net.refractions.udig.catalog
Interface IResolve

All Known Implementing Classes:
ICatalog, IGeoResource, IService

public interface IResolve

Blocking IAdaptable, used to contact external services.

Since:
0.7.0
Author:
David Zwiers, Refractions Research
See Also:
IAdaptable

Nested Class Summary
static class IResolve.Status
           
 
Method Summary
<T> boolean
canResolve(java.lang.Class<T> adaptee)
          Required adaptions will be listed in Abstract Classes under the resolve() method.
 void dispose(IProgressMonitor monitor)
          Clean up after aquired resources - the handle will not function after being disposed.
 java.net.URL getIdentifier()
          A unique resource identifier ...
 java.lang.Throwable getMessage()
          Text description for this serice status.
 IResolve.Status getStatus()
          Status information for this service.
 java.util.List<? extends IResolve> members(IProgressMonitor monitor)
          Contents of this handle, Collections.EMPTY_LIST iff this is a leaf.
 IResolve parent(IProgressMonitor monitor)
          The parent of this handle, may be null if parent unknown.
<T> T
resolve(java.lang.Class<T> adaptee, IProgressMonitor monitor)
          Will attempt to morph into the adaptee, and return that object.
 

Method Detail

resolve

<T> T resolve(java.lang.Class<T> adaptee,
              IProgressMonitor monitor)
          throws java.io.IOException
Will attempt to morph into the adaptee, and return that object.

Required adaptions will be listed in Abstract Classes, along with the method they will call. IResolve implementations are encouraged to follow this practice - documenting what adapters are required.

The extensible interface pattern also demands that the set of adapters be open-ended; we have provided an extention point to let others teach the system new tricks at configuration time.

Here is a code example that every implementation needs to follow in order to make use of the IResolveManager:

 public  T resolve( Class adaptee, IProgressMonitor monitor ) throws IOException {
     if (monitor == null)
         monitor = new NullProgressMonitor();
     if (adaptee == null)
         throw new NullPointerException("No adaptor specified" );
     
     if (adaptee.isAssignableFrom(TYPE.class)) {
         return adaptee.cast(METHOD(monitor));
     }
     ...
     IResolveManager rm = CatalogPlugin.getDefault().getResolveManager();
     if (rm.canResolve(this, adaptee)) {
         return rm.resolve(this, adaptee, monitor);
     }
     return null; // could not find adapter
 }
May Block.

Parameters:
adaptee -
monitor - May Be Null
Returns:
Instance of type adaptee, or null if adaptee is unsuported.
Throws:
java.io.IOException - if result was unavailable due to a technical problem

canResolve

<T> boolean canResolve(java.lang.Class<T> adaptee)
Required adaptions will be listed in Abstract Classes under the resolve() method.

Restrictions on implementations:

When defining a new AbstractClass you are also asked to please list the required adaptations in your javadocs.

The following code example shows intended practice:


 public  boolean canResolve( Class adaptee ){
    return adaptee != null && (
               adaptee.isAssignableFrom(TYPE.class) ||
               CatalogPlugin.getDefault().getResolveManager().canResolve(this, adaptee)
           );
 }
 

Returns:
true if a resolution for adaptee is avaialble
See Also:
resolve(Class, IProgressMonitor);

parent

IResolve parent(IProgressMonitor monitor)
                throws java.io.IOException
The parent of this handle, may be null if parent unknown.

Parameters:
monitor - used to provide feedback during parent lookup
Returns:
Parent IResolve, null if unknown
Throws:
java.io.IOException - in the event of a technical problem

members

java.util.List<? extends IResolve> members(IProgressMonitor monitor)
                                           throws java.io.IOException
Contents of this handle, Collections.EMPTY_LIST iff this is a leaf.

Parameters:
monitor - Monitor used to provide feedback during member lookup
Returns:
List, possibly empty, of members. Will be EMPTY_LIST if this is a leaf.
Throws:
java.io.IOException - in the event of a technical problem

getStatus

IResolve.Status getStatus()
Status information for this service.

In the future this may be extended into a bit mask of connection status.

Returns:
Status of the resource

getMessage

java.lang.Throwable getMessage()
Text description for this serice status.

For a BROKEN status this will contain the error message, null will be returned if there is nothing interesting to report.

Not the Exception is ecpected to be in humar readable, terms.

Returns:
Text describing service status

getIdentifier

java.net.URL getIdentifier()
A unique resource identifier ... this should be unique for each service. Must Not Block.

Returns:
ID for this IResolve, should not be null.

dispose

void dispose(IProgressMonitor monitor)
Clean up after aquired resources - the handle will not function after being disposed.

Parameters:
monitor -