Move IService contract from javadocs to code
--------------------------------------------
Key: UDIG-1105
URL: http://jira.codehaus.org/browse/UDIG-1105
Project: uDIG
Issue Type: Task
Components: API catalog
Affects Versions: UDIG 1.1.RC5
Reporter: Jody Garnett
Fix For: UDIG 1.1.RC6
The IService contract has been exactly specified in the javadocs ... we should
make use of IService being an abstract class and encode the requirements using
Java.
Here is the contract:
- IServer.resoleve( List.class, null ) ---> defined to be List<GeoResource) ie
the children
- IService.resolve( IService.class, null ) --> this
- IService.resolve( IServiceInfo.class , null ) --> getInfo()
- IService.resolve( ICatalog.class , null ) --> parent()
- IService.canResolve( Class ) must make use of ResolveManager
- IService.resolve( Class, null ) must make use of ResolveManager
- provided monitor should be used when connecting to external resources...
- IService.canResolve( null ) --> false
- IService.resolve( null, null ) --> IOException
The gap between code and the javadocs has resulted in several complications:
- IService.members( null ) was implemented as a class to resolve( List.class,
null ) ---> but all implementations but one provided an override (and then did
not respect the resolve contract)
- IService.info() <-> getInfo() contract was not respected by all
implementations
- IService.resolve( IService.class, null ) <-> was only respected by one
implementation
- etc....
Recomendation One: make resolve delegate to IService methods
- make members into an abstract method (allowing subclasses to account for
their children in a single block of code)
- provide an implementation of IService.resolve that captures the contract:
1. makes the correct call to parent, getInfo, members, this)
2. correct calls the ResolveManager
3. Correctly protects against a null adapter
Pros:
- it works, and may subclasses no longer need to provide an implementation of
resolve or canResolve - the default will function correctly
Cons:
- Javadocs are still the weak link - subclasses *must* call return
super.resolve( adaptee, monitor ) if they were unable to provide something
directly
- Any subclass can break the chain by not handling resolve( null, monitor )
correctly
- Applications cannot override the implementation of members(), info() by
simply providing a ResolveAdapter
Recomendation Two: make resolve final
- make IService.resolve( class, monitor ) a final method with the contract as
above using either of the following alternatives:
1. force implementations to provide an ResolveAdapter using the extention point
- for everything. This would allow applications to splice in their own
implementation for members() by providing a resolve adapter for List.class.
2. create an protected method resolveDirect( class, monitor ) that subclasses
can implement; with no magic calls to super needed
Alternative: IService Decorator
Please note that the uDig port of IService makes use of a Decorator to perform
the ResolveManager check (so implementations can be done in the most direct
manner possible; and ResolveManager is spliced in with no additional or special
coding on their part).
There is no question that this is a great way to go; however we would loose the
instanceof Checks (not that they are very helpful on a handle).
--
This message is automatically generated by JIRA.
-
If you think it was sent incorrectly contact one of the administrators:
http://jira.codehaus.org/secure/Administrators.jspa
-
For more information on JIRA, see: http://www.atlassian.com/software/jira
_______________________________________________
User-friendly Desktop Internet GIS (uDig)
http://udig.refractions.net
http://lists.refractions.net/mailman/listinfo/udig-devel
