org.geotools.catalog
Interface Resolve

All Known Subinterfaces:

Catalog, GeoResource, Service

All Known Implementing Classes:

AbstractCatalog, AbstractGeoResource, AbstractService

public interface Resolve

Interface for objects which serve has handles to actual data objects.

The resolve pattern is based on the IAdaptable pattern used extensivly by the Eclipse framework. Also known as the Extensible Interface pattern, objects implementing the IAdaptable interface morph or adapt themselves into objects implementing a different interface.

The resolve pattern is slightly different in that morphing or adapting (ie. resolving) into a different object involves a blocking call in which I/O is being performed, possibly with the local disk, or with a remote service.

The following code illustrates the use of the resolve pattern:

 	
 	Resolve resolve = ....
 	ProgressListener listener = ....
 
 	FeatureSource featureSource = resolve.resolve(FeatureSource.class,listener);
 	if (featureSource != null) {
 		//do something
 	}
 	
 

As a convenience, the canResolve(Class) method is used to determine if a particular type of object is supported, but not to perform the resolve. This method can be useful in situations where it is not desirable to block.

An implementation of resolve supports the notion of resolving into a parent, or into a list of children, called members. Like any other resolve, these are blocking operations. Parents and members must also implement the Resolve interface.

Since:

0.7.0

Author:

David Zwiers, Refractions Research, Justin Deoliveira, The Open Planning Project

Nested Class Summary

static class

Resolve.Status Enumeration class for representing the status or state of a Resolve.

Method Summary

void	addListener(ResolveChangeListener listener) Adds a listener to the Resolve.
boolean	canResolve(java.lang.Class adaptee) Non blocking method which is used to determine if a resolve into an instance of a particular class is supported.
void	fire(ResolveChangeEvent event) Fires a change event against the Resolve.
java.net.URI	getIdentifier() Returns a URI which uniqley identifies the Resolve.
java.lang.Throwable	getMessage() In the event that an error occurs during a resolve, that error can be reported back with this method.
Resolve.Status	getStatus() Status of the resolve.
java.util.List	members(ProgressListener monitor) Blocking method which resolves this instance into its members (children).
Resolve	parent(ProgressListener monitor) Blocking method which resolves this instance into its parent.
void	removeListener(ResolveChangeListener listener) Removes a listener from the Resolve.
java.lang.Object	resolve(java.lang.Class adaptee, ProgressListener monitor) Blocking method which is used to resolve into an instance of a particular class.

Method Detail

resolve

public java.lang.Object resolve(java.lang.Class adaptee,
                                ProgressListener monitor)
                         throws java.io.IOException

Blocking method which is used to resolve into an instance of a particular class.

Required adaptions will be listed in Abstract Classes that implement this interface.

Parameters:

adaptee - Class of object to resolve into.

monitor - Progress monitor used to report status while blocking. May be null.

Returns:

Instance of type adaptee, or null if the resolve is unsuported.

Throws:

java.io.IOException - in the result of an I/O error.

canResolve

public boolean canResolve(java.lang.Class adaptee)

Non blocking method which is used to determine if a resolve into an instance of a particular class is supported.

Parameters:

adaptee - Class of object to resolve into.

Returns:

true if a resolution for adaptee is avaialble

See Also:

IResolve#resolve(Class,ProgressListener)

parent

public Resolve parent(ProgressListener monitor)
               throws java.io.IOException

Blocking method which resolves this instance into its parent. This method may return null if the parent can not be determined.

Parameters:

monitor - Progress monitor used to report status while blocking. May be null.

Returns:

The parent Resolve, or null if the parent can be obtained.

Throws:

java.io.IOException - in the result of an I/O error.

members

public java.util.List members(ProgressListener monitor)
                       throws java.io.IOException

Blocking method which resolves this instance into its members (children). This method returns null if the instance does not have any children, or the children could be determined.

Parameters:

monitor - Progress monitor used to report status while blocking. May be null.

Returns:

A list (possibly empty) of members, null if the members could not be obtained or the instance has not members. Objects in the returned list implement the Resolve interface.

Throws:

java.io.IOException - in the result of an I/O error.

getStatus

public Resolve.Status getStatus()

Status of the resolve. Resolving into other types of objects often involves connecting to a remote service or resource. This method is provided to indicate the state of any connections.

Returns:

One of Resolve.Status.BROKEN,Resolve.Status.CONNECTED, or Resolve.Status.NOTCONNECTED.

getMessage

public java.lang.Throwable getMessage()

In the event that an error occurs during a resolve, that error can be reported back with this method. This method returns a value when getStatus() returns Resolve.Status.BROKEN, otherwise it return null.

Returns:

An exception that occured during a resolve, otherwise null.

See Also:

Resolve.Status

getIdentifier

public java.net.URI getIdentifier()

Returns a URI which uniqley identifies the Resolve.

Returns:

Id of the Resolve, should never be null.

addListener

public void addListener(ResolveChangeListener listener)
                 throws java.lang.UnsupportedOperationException

Adds a listener to the Resolve. Support for event notification is up to the specific implementation.

Parameters:

listener - The observer.

Throws:

java.lang.UnsupportedOperationException - When event notification is not supported.

removeListener

public void removeListener(ResolveChangeListener listener)

Removes a listener from the Resolve. Support for event notification is up to the specific implementation.

Parameters:

listener - The observer.

fire

public void fire(ResolveChangeEvent event)

Fires a change event against the Resolve. Support for event notification is up to the specific implementation.

Parameters:

event - The event describing the change.