ClassPath API comments, questions

Hi All,

I am looking at the ClassPath API and trying to understand it, but it 
seems to be harder than I was expecting. I know I am not very smart, so 
please be patient with me.

I've started with API. I understand that the PathContent is specialized 
version of ClassPath which allows manipulation of its contents (add, 
remove, reorder). Why this functionality wasn't added directly in the 
ClassPath? Also I don't understand the relation between PathResource and 
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 
creating the PathResource for FileObject (e.g. folder or jar), so in 
fact it's not easy to add something to the PathContent.

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?

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 
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 
PathResource.

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 ;-).

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; 
project-dependent stuff: ProjectPath, ProjectPathProvider)
* deprecate Classpath.BASE{COMPILE, DEBUG, EXECUTE} fields, they can be 
used only in deprecated ClassPath.getClassPath method
* 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)
* don't expose dependency on org.openide.loaders.*
* remove ClassPath.Entry.toLocalFile; it's redundant
* rename PathFactory to PathProvider and make it an interface
* change PathFactory.findPath(Object) to 
PathProvider.getClassPath(String pathId)
* 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")
* remove ProxyPathContent.Control; it's useless when public 
ProxyPathContent.setBases exists

Thanks for your answers,
-vita