[udig-devel] [jira] Created: (UDIG-1105) Move IService contract from jav

["Jody Garnett (JIRA)" <jira@xxxxxxxxxxxx>]

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