001: /*
002: * uDig - User Friendly Desktop Internet GIS client
003: * http://udig.refractions.net
004: * (C) 2004, Refractions Research Inc.
005: *
006: * This library is free software; you can redistribute it and/or
007: * modify it under the terms of the GNU Lesser General Public
008: * License as published by the Free Software Foundation;
009: * version 2.1 of the License.
010: *
011: * This library is distributed in the hope that it will be useful,
012: * but WITHOUT ANY WARRANTY; without even the implied warranty of
013: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
014: * Lesser General Public License for more details.
015: *
016: */
017: package net.refractions.udig.catalog;
018:
019: import java.io.IOException;
020: import java.net.URL;
021: import java.util.List;
022:
023: import org.eclipse.core.runtime.IProgressMonitor;
024: import org.eclipse.core.runtime.NullProgressMonitor;
025:
026: /**
027: * Blocking IAdaptable, used to contact external services.
028: *
029: * @author David Zwiers, Refractions Research
030: * @since 0.7.0
031: * @see IAdaptable
032: */
033: public interface IResolve {
034:
035: /**
036: * Will attempt to morph into the adaptee, and return that object.
037: * <p>
038: * Required adaptions will be listed in Abstract Classes,
039: * along with the method they will call. IResolve implementations
040: * are encouraged to follow this practice - documenting what
041: * adapters are required.
042: * </p>
043: * The extensible interface pattern also demands that the set of
044: * adapters be open-ended; we have provided an extention point
045: * to let others teach the system new tricks at configuration time.
046: * </p>
047: * Here is a code example that every implementation needs to follow
048: * in order to make use of the IResolveManager:
049: * <ul>
050: * <li>TYPE - an example required class (like URL.class)
051: * <li>METHOD - an example method that will produce the adapter
052: * </ul>
053: * <pre><code>
054: * public <T> T resolve( Class<T> adaptee, IProgressMonitor monitor ) throws IOException {
055: * if (monitor == null)
056: * monitor = new NullProgressMonitor();
057: * if (adaptee == null)
058: * throw new NullPointerException("No adaptor specified" );
059: *
060: * if (adaptee.isAssignableFrom(TYPE.class)) {
061: * return adaptee.cast(METHOD(monitor));
062: * }
063: * ...
064: * IResolveManager rm = CatalogPlugin.getDefault().getResolveManager();
065: * if (rm.canResolve(this, adaptee)) {
066: * return rm.resolve(this, adaptee, monitor);
067: * }
068: * return null; // could not find adapter
069: * }</code></pre>
070: * May Block.
071: *
072: * @param adaptee
073: * @param monitor May Be Null
074: * @return Instance of type adaptee, or null if adaptee is unsuported.
075: * @throws IOException if result was unavailable due to a technical problem
076: */
077: public <T> T resolve(Class<T> adaptee, IProgressMonitor monitor)
078: throws IOException;
079:
080: /**
081: * Required adaptions will be listed in Abstract Classes under the resolve() method.
082: * <p>
083: * Restrictions on implementations:
084: * <ul>
085: * <li>May not Block
086: * <li>*MUST NOT* throw any exceptions (be sure to check for null!)
087: * <li>Must delegate to ResolveManger - to recognize adapters contributed by others
088: * </ul>
089: * When defining a new AbstractClass you are also asked to please list the
090: * required adaptations in your javadocs.
091: * <p>
092: * The following code example shows intended practice:<pre><code>
093: * public <T> boolean canResolve( Class<T> adaptee ){
094: * return adaptee != null && (
095: * adaptee.isAssignableFrom(TYPE.class) ||
096: * CatalogPlugin.getDefault().getResolveManager().canResolve(this, adaptee)
097: * );
098: * }
099: * </code></pre>
100: *
101: * @see IResolve#resolve(Class, IProgressMonitor);
102: * @return true if a resolution for adaptee is avaialble
103: */
104: public <T> boolean canResolve(Class<T> adaptee);
105:
106: /**
107: * The parent of this handle, may be null if parent unknown.
108: *
109: * @param monitor used to provide feedback during parent lookup
110: * @return Parent IResolve, null if unknown
111: * @throws IOException in the event of a technical problem
112: */
113: public IResolve parent(IProgressMonitor monitor) throws IOException;
114:
115: /**
116: * Contents of this handle, Collections.EMPTY_LIST iff this is a leaf.
117: *
118: * @param monitor Monitor used to provide feedback during member lookup
119: * @return List, possibly empty, of members. Will be EMPTY_LIST if this is a leaf.
120: * @throws IOException in the event of a technical problem
121: */
122: public List<? extends IResolve> members(IProgressMonitor monitor)
123: throws IOException;
124:
125: public enum Status {
126: /** Status constant indicates a live connection in use */
127: CONNECTED,
128:
129: /** Status constant indicates a connection that is not in use */
130: NOTCONNECTED,
131:
132: /** Status constant indicates a connection that is broken */
133: BROKEN,
134:
135: /** Indicates that user does not have access to resource */
136: RESTRICTED_ACCESS
137: };
138:
139: /**
140: * Status information for this service.
141: * <p>
142: * In the future this may be extended into a bit mask of connection status.
143: * </p>
144: *
145: * @return Status of the resource
146: */
147: public Status getStatus();
148:
149: /**
150: * Text description for this serice status.
151: * <p>
152: * For a BROKEN status this will contain the error message, null will be returned if there is
153: * nothing interesting to report.
154: * <p>
155: * <p>
156: * Not the Exception is ecpected to be in humar readable, terms.
157: * </p>
158: *
159: * @return Text describing service status
160: */
161: public Throwable getMessage();
162:
163: /**
164: * A unique resource identifier ... this should be unique for each service.
165: * Must Not Block.
166: *
167: * @return ID for this IResolve, should not be null.
168: */
169: public abstract URL getIdentifier();
170:
171: /**
172: * Clean up after aquired resources - the handle will not function
173: * after being disposed.
174: *
175: * @param monitor
176: */
177: public void dispose(IProgressMonitor monitor);
178:
179: }
|