Re: Review of Java ClassPath API

It would be really nice if you could update the usecases. Let me know 
when you do (btw. I suggest you to put high level usecases into the 
generated javadoc). Otherwise I have really hard time to believe that 
everything has to be as complicated.

Sorry.
yarda

PS: Just looking at the UML gives one feeling that something is there twice.


Svata Dedic wrote:
> Jaroslav Tulach wrote:
> 
>>
>> The recommendation is to merge ClassPath and PathContent functionality 
>> and keep only ClassPath.
>>
> 
> As I wrote elsewhere - there are two (supposed) types of clients: the
> ones who are satisfied with flat model of ClassPath - a list of
> individible items (roots of classpath) and need only query/search
> interface to that model. This is what "ClassPath" was originally
> intended for.
> 
> The other client type is more concerned by management, so it should get
> the structured model and a basic manipulation APIs to alter the model.
> PathContent is meant for this type of clients. This type of clients do
> not primarily access/locate/search for resources on the ClassPath
> (althoguh they may need it in order to determine the configuration steps).
> I count configuration UI into this client type.
> 
> If the distinction above is not sufficient to keep the types separate,
> alternatives can be:
> - merge them together
> - ClassPath created by from a PathContent using some factory method
> 
>>
>> Mixing API and SPI I.
>> ---------------------
>>
>> In order to support structured paths a new interface PathResource has 
>> been introduced that duplicates and enhances functionality already 
>> available in ClassPath.Entry. Moreover this class mixes API with SPI 
>> which makes it look even more strange.
>>
>> The only valid usecases it was possible to find (because the classpath 
>> requirements do not contain anything about structured classpaths) are 
> 
> 
> Mea culpa, I will add that section. The requirement here is to allow
> adding entities that contribute multiple roots. Such entities should be
> treated equally to single-rooted items by the API, both are logical
> building blocks for the path/
> 
> An example could be "source files" or "compiler output" entities, which
> contribute one to many roots to the resulting classpath. Another typical
> scenario is to insert another project's output, which may contribute one
> to many roots and even imply some additional libraries to be isnserted.
> 
> 
>> part of the javadoc documentation and are build around usage of 
>> methods PathContent.getAllResources(), PathContent.getResources () and 
> 
> 
> Probably I should revisit the documentation -- while "getResources"
> gives the content of the path itself, getAllResources() produces a flat
> depth-first list of all leaf resources on the path - essentially the
> input for ClassPath interface.
> 
>> PathResource.getEnvironment(). But the class PathResource contains 
>> other methods like isLeaf(), getContents(), etc. It is belived that 
>> these methods are SPI (at least there is no usecase for them from API 
>> point of 
> 
> 
> No, isLeaf() and getContents() is part of the structured model, as
> isData() and getFileObjects() is part of FS API model.
> 
> Possibly the names are not descriptive enough, or poorly documented. If
> so, file me a bug please.
> 
>> view), they are only used internally to correctly implement 
>> PathContent.getAllResources (). As mixing API and SPI can only cause 
> 
> 
> getAllResources() is essentially part of bridge between 2nd client and
> 1st client style described above. It takes structured path as input and
> produces flat model as output.
> 
> getAllResources() could, in theory, filter or transform resources
> contributed by complex libraries inserted into the path -- but that
> would indeed mix SPI/API.
> 
>> First of all, the API part of the PathResource shall be moved to 
>> ClassPath.Entry (methods isValid(), getEnvironment, getFile, maybe the 
>> change listener belong there). The structured functionality shall be 
> 
> 
> Change listener is definitely a part of API -- if the client is
> interested in validity of entries, it should be able to listen on the
> changes.
> 
>> handled internally and by a separate API, so users of the 
>> ClassPath.getResources() and ClassPath.getAllResources () are not 
>> scared by it. Possible solution is to have factory method ClassPath.Entry 
> 
> 
> This matches the original intention for having ClassPath and PathContent
> as separate types. If ClassPath and PathContent are merged into one 
> interface, simple clients would be scared by a number of management 
> (add/remove/structure) methods they do not need.
> 
> Possibly PathContent should NOT extend ClassPath and rather serve as a
> factory for ClassPath instances to keep the separation visible (as noted
> above).
> 
>> The suggested change is to follow the Registry API design and keep 
>> ClassPath and ClassPath.Entry final and under control of the module 
>> and provide interfaces and factory methods to create new instances. 
>> All the SPI functionality of the ClassPath shall be extracted to an 
>> interface, say ClassPathImpl. Plus there shall be a factory method 
>> ClassPath Factory.createClassPath (ClassPathImpl impl) that could be 
>> used by modules trying to provide their own factory. Also 
>> ProxyPathContent shall be replaced by an interface ProxyImpl extends 
>> ClassPathImpl and factory method to create ClassPath from it. Other 
>> SPI classes shall be changed in such a way as well.
> 
> 
> Sorry, I do not exactly follow this paragraph. Supposing that
> PathContent (as a management interface) will produce ClassPath
> instances, ClassPath / ClassPath.Entry could be well final - they will
> only delegate to the relevant PathResource methods or build list from
> get[All]Resources.
> 
> I must say I do not see an advantage of ClassPathImpl interface, except
> that it would allow to separate SPI functions:
> - getResources() - provides possibly dynamic content from some storage
> - add()
> - remove()
> - setOrder
> from client called methods of the same name -- supposing the storage
> handling is ultimately the responsibility of the SPI implementor.
> Do you think it is worth to introduce such bridge layer ?
> 
> Thanks for the review,
> -Svata
> 
> 
> 
> ---------------------------------------------------------------------
> To unsubscribe, e-mail: [email protected]
> For additional commands, e-mail: [email protected]
> 

-- 
/**
* @author Jaroslav Tulach
* @see http://www.netbeans.org
*/