001: /*
002: * GeoTools - OpenSource mapping toolkit
003: * http://geotools.org
004: * (C) 2005-2006, GeoTools Project Managment Committee (PMC)
005: * (C) 2005, Refractions Research Inc.
006: *
007: * This library is free software; you can redistribute it and/or
008: * modify it under the terms of the GNU Lesser General Public
009: * License as published by the Free Software Foundation;
010: * version 2.1 of the License.
011: *
012: * This library is distributed in the hope that it will be useful,
013: * but WITHOUT ANY WARRANTY; without even the implied warranty of
014: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
015: * Lesser General Public License for more details.
016: */
017: package org.geotools.catalog;
018:
019: import java.io.IOException;
020: import java.net.URI;
021: import java.util.List;
022: import org.geotools.util.ProgressListener;
023:
024: /**
025: * Interface for objects which serve has handles to actual data objects.
026: *
027: * <p>
028: * The resolve pattern is based on the IAdaptable pattern used extensivly by
029: * the Eclipse framework. Also known as the Extensible Interface pattern,
030: * objects implementing the IAdaptable interface morph or adapt themselves
031: * into objects implementing a different interface.
032: * </p>
033: *
034: * <p>
035: * The resolve pattern is slightly different in that morphing or adapting (ie.
036: * resolving) into a different object involves a blocking call in which I/O
037: * is being performed, possibly with the local disk, or with a remote service.
038: * </p>
039: *
040: * <p>
041: * The following code illustrates the use of the resolve pattern:
042: * <pre>
043: * <code>
044: * Resolve resolve = ....
045: * ProgressListener listener = ....
046: *
047: * FeatureSource featureSource = resolve.resolve(FeatureSource.class,listener);
048: * if (featureSource != null) {
049: * //do something
050: * }
051: * </code>
052: * </pre>
053: * As a convenience, the {@link Resolve#canResolve(Class)} method is used to
054: * determine if a particular type of object is supported, but not to perform
055: * the resolve. This method can be useful in situations where it is not
056: * desirable to block.
057: * </p>
058: *
059: * <p>
060: * An implementation of resolve supports the notion of resolving into a parent,
061: * or into a list of children, called members. Like any other resolve, these
062: * are blocking operations. Parents and members must also implement the
063: * Resolve interface.
064: * </p>
065: *
066: * @author David Zwiers, Refractions Research
067: * @author Justin Deoliveira, The Open Planning Project
068: *
069: * @since 0.7.0
070: * @source $URL: http://svn.geotools.org/geotools/tags/2.4.1/modules/library/api/src/main/java/org/geotools/catalog/Resolve.java $
071: */
072: public interface Resolve {
073: /**
074: * Blocking method which is used to resolve into an instance of a
075: * particular class.
076: *
077: * <p>
078: * Required adaptions will be listed in Abstract Classes that implement
079: * this interface.
080: * </p>
081: *
082: * @param adaptee Class of object to resolve into.
083: * @param monitor Progress monitor used to report status while blocking.
084: * May be null.
085: *
086: * @return Instance of type adaptee, or null if the resolve is unsuported.
087: *
088: * @throws IOException in the result of an I/O error.
089: */
090: Object resolve(Class adaptee, ProgressListener monitor)
091: throws IOException;
092:
093: /**
094: * Non blocking method which is used to determine if a resolve into an
095: * instance of a particular class is supported.
096: *
097: * @param adaptee Class of object to resolve into.
098: *
099: * @return true if a resolution for adaptee is avaialble
100: *
101: * @see IResolve#resolve(Class,ProgressListener)
102: */
103: boolean canResolve(Class adaptee);
104:
105: /**
106: * Blocking method which resolves this instance into its parent. This
107: * method may return null if the parent can not be determined.
108: *
109: * @param monitor Progress monitor used to report status while blocking.
110: * May be null.
111: *
112: * @return The parent Resolve, or null if the parent can be obtained.
113: *
114: * @throws IOException in the result of an I/O error.
115: */
116: Resolve parent(ProgressListener monitor) throws IOException;
117:
118: /**
119: * Blocking method which resolves this instance into its members
120: * (children). This method returns null if the instance does not have any
121: * children, or the children could be determined.
122: *
123: * @param monitor Progress monitor used to report status while blocking.
124: * May be null.
125: *
126: * @return A list (possibly empty) of members, null if the members could
127: * not be obtained or the instance has not members. Objects in the
128: * returned list implement the Resolve interface.
129: *
130: * @throws IOException in the result of an I/O error.
131: */
132: List members(ProgressListener monitor) throws IOException;
133:
134: /**
135: * Status of the resolve. Resolving into other types of objects often
136: * involves connecting to a remote service or resource. This method is
137: * provided to indicate the state of any connections.
138: *
139: * @return One of {@link Status#BROKEN},{@link Status#CONNECTED}, or
140: * {@link Status#NOTCONNECTED}.
141: */
142: Status getStatus();
143:
144: /**
145: * In the event that an error occurs during a resolve, that error can be
146: * reported back with this method. This method returns a value when
147: * {@link Resolve#getStatus()} returns {@link Status#BROKEN}, otherwise it
148: * return null.
149: *
150: * @return An exception that occured during a resolve, otherwise null.
151: *
152: * @see Status
153: */
154: Throwable getMessage();
155:
156: /**
157: * Returns a URI which uniqley identifies the Resolve.
158: *
159: * @return Id of the Resolve, should never be null.
160: */
161: URI getIdentifier();
162:
163: /**
164: * Adds a listener to the Resolve. Support for event notification is up to
165: * the specific implementation.
166: *
167: * @param listener The observer.
168: *
169: * @throws UnsupportedOperationException When event notification is not
170: * supported.
171: */
172: void addListener(ResolveChangeListener listener)
173: throws UnsupportedOperationException;
174:
175: /**
176: * Removes a listener from the Resolve. Support for event notification is
177: * up to the specific implementation.
178: *
179: * @param listener The observer.
180: */
181: void removeListener(ResolveChangeListener listener);
182:
183: /**
184: * Fires a change event against the Resolve. Support for event notification
185: * is up to the specific implementation.
186: *
187: * @param event The event describing the change.
188: */
189: void fire(ResolveChangeEvent event);
190:
191: /**
192: * Enumeration class for representing the status or state of a Resolve.
193: */
194: class Status {
195: /** Status constant indicates a live connection in use */
196: public static final Status CONNECTED = new Status();
197:
198: /** Status constant indicates a connection that is not in use */
199: public static final Status NOTCONNECTED = new Status();
200:
201: /** Status constant indicates a connection that is broken */
202: public static final Status BROKEN = new Status();
203:
204: private Status() {
205: }
206: }
207: }
|