Re: ClassPath API comments, questions

[resending Svata's response, it was hang somewhere]



> I've started with API. I understand that the PathContent is specialized 
> version of ClassPath which allows manipulation of its contents (add, 


Originally I thought that it would be useful to have a restricted 
interface for query clients, who need ClassPath to access/find resources 
and that PathContent/PathResource should be mainly used by clients 
interesting in configuration and project management.

I still think such division could be useful, please suggest how to to 
that.


>> ClassPath.Entry, these classes seem to be independent, but PathResource 
>> contains the same methods (not all, but many) as CP.Entry and in fact 
>> serves the same purpose IMO. It seems that there is no support for 
>  
>

Correct. 


>> creating the PathResource for FileObject (e.g. folder or jar), so in 
>> fact it's not easy to add something to the PathContent.
>> 
>  
>

The PathResource does serve one additional purpose: it establishes an 
identity for the folder (other than the folder identity) so that other IDE
modules could (possibly) plug into that identity's Lookup.

It's not as easy to hook into "folders which are in some PathContent", but 
it could be moderately simple to hook on "all folder-based path 
resources".
This is used in e.g. projects, when a PathResource can be itself 
compilable.

For cases when this feature is not needed, a factory method was planned to 
create a PathResource whose getDefinition() returns null.


>> The docs describe that the PathResource can be either the leaf one or 
>> compound from several other PathResources, but I don't understand how 
>> this could be achieved when nothing in the ClassPath API/SPI extends the 
>> PathResource. Shouldn't the PathContent also be PathResource allowing 
>> nesting? Or shound't there be support for creating PathResource from 
>> PathContent?
>  
>

See above about identities. PathResource (a particular implementation) may 
contain only link to the definition, such as in the case of "output from 
other project". Such link may be broken (PR.isValid() == false). If PC 
extends PR, then we would need to proxy data and propagate events for such 
detachable contents. I tried to avoid that.

As for PC -> PR conversion, if the identity above is not needed, it could 
be done. I remember your suggestion to have PC also identity-based (e.g. 
where did it come from -- a FileObject, for example). If needed, this part 
could be factored out as a common interface.


>> 
>> The SPI seems even more cryptic to me. Why is there EditableContent 
>> interface when nothing implements it? Is it just a garbage? Why is there 
>  
>

Garbage. Old relict from the times when I did not know whether dialogs 
will have Ok/Cancel or Close. Please delete it.


>> public ReadOnlyProxy class extending LightWeightProxy which is package 
>> private? The ProxyPathContent.Control is for what (it does the same as 
>> public method ProxyPathContent.setBases)? Again, no way how to create 
>  
>

I tried to avoid ugly uses of ProxyFileSet, when in order to control 
contents of the FileSet, you have to create a subclass. I tried to follow 
a patten used in o.o.u.Mutex -- the one who creates has special access 
rights through a "control" interface.


>> 
>> The javadoc of ClassPath API is poor on some places (read completely 
>> missing for some classes) and even if the overview docs are good 
>> (explanations, pictures, references) the overall impression is bad. 
>> Sorry. I am volunteering to improve the javadoc in exchange for 
>> explanation how the API works and was intended to be used ;-).
>  
>

_I_ am sorry - I can contribute to, but not in the next few hours. Say to 
the end of this calendar week. Please do the work assignment.


>> Here are some changes I am proposing to clean up the API/SPI (the list 
>> isn't final):
>> 
>> * separate the project-independent part of classpath API to its own 
>> module java/classpath (or perhaps separate project-dependent API to its 
>> own module if the above would cause compatibility problems; 
>  
>

OK, please rather create a pure java (w/o projects) API, we may end with 
more stuff in there.


>> * deprecate Classpath.BASE{COMPILE, DEBUG, EXECUTE} fields, they can be 
>> used only in deprecated ClassPath.getClassPath method
>  
>

I thought I have already deprecated them. Mea culpa. Please do so.


>> * classes from classpath API shouldn't implement Node.Cookie (they are 
>> accessed through lookup anyway provided by PEPs, etc.; in worst case use 
>> superclass patching)
>  
>

Relict from the time when node Lookups and LookupNodes did not function so 
well. Should not be there.


>> * rename PathFactory to PathProvider and make it an interface
>> * change PathFactory.findPath(Object) to 
>> PathProvider.getClassPath(String pathId)
>  
>

I would rather keep "find" in the name -- the path type may not be 
supported at the object.


>> * change return type of PathProvider.getClassPath from PathContent to 
>> ClassPath
>> * create ClassPath.EMPTY constant; I've seen several times 
>> PathContent.createPath(Collection.EMPTY, null, "blabla")
>  
>

Yes, please.


>> * remove ProxyPathContent.Control; it's useless when public 
>> ProxyPathContent.setBases exists
>> 
>  
>
See above for explanation of use cases.

-Svata