001: /*
002: * uDig - User Friendly Desktop Internet GIS client http://udig.refractions.net (C) 2004,
003: * Refractions Research Inc. This library is free software; you can redistribute it and/or modify it
004: * under the terms of the GNU Lesser General Public License as published by the Free Software
005: * Foundation; version 2.1 of the License. This library is distributed in the hope that it will be
006: * useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
007: * FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.
008: */
009: package net.refractions.udig.project;
010:
011: import java.io.IOException;
012: import java.net.URL;
013: import java.util.List;
014:
015: import net.refractions.udig.catalog.IGeoResource;
016:
017: import org.eclipse.core.runtime.IProgressMonitor;
018: import org.eclipse.jface.resource.ImageDescriptor;
019: import org.geotools.data.Query;
020: import org.geotools.feature.FeatureType;
021: import org.geotools.filter.Filter;
022: import org.geotools.geometry.jts.ReferencedEnvelope;
023: import org.geotools.referencing.crs.DefaultEngineeringCRS;
024: import org.opengis.referencing.crs.CoordinateReferenceSystem;
025: import org.opengis.referencing.operation.MathTransform;
026:
027: import com.vividsolutions.jts.geom.Envelope;
028:
029: /**
030: * TODO Purpose of net.refractions.udig.project
031: * <p>
032: * </p>
033: *
034: * @author Jesse
035: * @since 1.0.0
036: */
037: public interface ILayer extends Comparable<ILayer> {
038:
039: /**
040: * Indicates the crs that will be used if the layer does not declare a crs. This crs is wgs84
041: * crs with the name: Messages.LayerImpl_unknown (unkown in english)
042: */
043: public static final CoordinateReferenceSystem UNKNOWN_CRS = DefaultEngineeringCRS.GENERIC_2D;
044:
045: /** <code>UNCONFIGURED</code> associated GeoResource is unconfigured, or is unavailable */
046: public static final int UNCONFIGURED = -2;
047:
048: /** <code>MISSING</code> cannot locate a GeoResource for this layer */
049: public static final int MISSING = -1;
050:
051: /** <code>DONE</code> rendering process completed normally */
052: public static final int DONE = 0;
053:
054: /**
055: * <code>WAIT</code> layer is waiting for information.
056: */
057: public static final int WAIT = 1;
058:
059: /** <code>ERROR</code> render process was unable to complete normally */
060: public static final int ERROR = 2;
061:
062: /** <code>WARNING</code> render process has produced warning(s) in the log. */
063: public static final int WARNING = 4;
064:
065: /**
066: * <code>WORKING</code> rendering process is underway.
067: * <p>
068: * Note the default Label decorator makes use of a WORKING_HINT layer property. The rendering
069: * process will clear this HINT when starting work, subsequence calls to setState( WORKING )
070: * will cycle the to update the clock.
071: * </p>
072: */
073: public static final int WORKING = 5;
074:
075: /** Listen to changes on this layer. Each listener can only be added once*/
076: public void addListener(ILayerListener listener);
077:
078: /** remove LayerListener */
079: public void removeListener(ILayerListener listener);
080:
081: /**
082: * Resource the user associates with this layer. This is not the same as getGeoResource(Class
083: * clazz).
084: *
085: * @return Resource the user associates with this layer.
086: */
087: public IGeoResource getGeoResource();
088:
089: /**
090: * Returns the first found geoResource that can resolve to clazz.
091: *
092: * @param clazz the clazz that the returned georesource can resolve to.
093: * @return the first found geoResource that can resolve to clazz.
094: * @deprecated
095: */
096: public <T> IGeoResource getGeoResource(Class<T> clazz);
097:
098: /**
099: * Locate the first IGeoResource that canResolve the provided resource type.
100: * <p>
101: * Example implementation:
102: *
103: * <pre><code>
104: * for( IGeoResource resource : getGeoResources() ) {
105: * if (resource.canResolve(FeatureSource.class)) {
106: * return resource;
107: * }
108: * }
109: * return null;
110: * </code></pre>
111: *
112: * </p>
113: *
114: * @param clazz class of the resource that the IGeoResource claims it can adapt to.
115: * @return true if a IGeoResource exists that canResolve to resourceType.
116: * @model
117: */
118: <T> IGeoResource findGeoResource(Class<T> clazz);
119:
120: /**
121: * StyleBlackboard used for collaboration with the rendering process.
122: * <p>
123: * This Blackboard is persisted, any modications made to the blackboard will result refresh of
124: * the effected layers.
125: * <p>
126: *
127: * @return Blackboard used for renderer collaboration.
128: */
129: public IStyleBlackboard getStyleBlackboard();
130:
131: /**
132: * Check if a IGeoResource exists that canResolve to the provided resource type.
133: * <p>
134: * Example:
135: *
136: * <pre><code>
137: * if (layer.hasResource(FeatureSource.class)) {
138: * return handle.getResource(FeatureSource.class, monitor);
139: * }
140: * </code></pre>
141: *
142: * </p>
143: * The blocking {@linkplain #getResource(Class, IProgressMonitor)} method allow the object to be
144: * obtained.
145: *
146: * @param resourceType the type of resource calleer is interested in.
147: * @return true if a IGeoResource exists that canResolve to resourceType.
148: */
149: public <T> boolean hasResource(Class<T> resourceType);
150:
151: /**
152: * @see #hasResource(Class)
153: *
154: * @deprecated use {@link #hasResource(Class)}
155: */
156: public <T> boolean isType(Class<T> resourceType);
157:
158: /**
159: * Returns a <i>real</i> resource that one of the GeoResources can resolved to.
160: * <p>
161: * Note: examples of resources are: FeatureSource, WebMapServer, etc... GeoResources are handles
162: * for real resources.
163: * </p>
164: * <p>
165: * Example implementation:
166: *
167: * <pre><code>
168: * for( IGeoResource resource : getGeoResources() ) {
169: * if (resource.canResolve(FeatureSource.class)) {
170: * return resource;
171: * }
172: * }
173: * return null;
174: * </code></pre>
175: *
176: * </p>
177: *
178: * <p>
179: * <b>IMPORTANT:</b> unlike using {@link IGeoResource#resolve(Class, IProgressMonitor)} {@link #getResource(Class, IProgressMonitor)}
180: * returns the same <em>instance</em> of the resource. The {@link IGeoResource#resolve(Class, IProgressMonitor)} method returns a new instance
181: * each time and therefore should <b>NOT</b> be used as a replacement for {@link #getResource(Class, IProgressMonitor)}.
182: * </p>
183: *
184: * @param resourceType
185: * @return true if a IGeoResource exists that canResolve to resourceType.
186: */
187: public <E> E getResource(Class<E> resourceType,
188: IProgressMonitor monitor) throws IOException;
189:
190: /**
191: * Filter indicating the selected features.
192: * <p>
193: * In order for this value to be useful the layer should be selectable, often a single fid
194: * filter during user edit opperations.
195: * </p>
196: * <p>
197: * Note: Filter.ALL indicates no selected Features. (All features are filtered out)
198: * </p>
199: * <p>
200: * A tool may wish to record the previous Filter, before replacing (or adding to) this value.
201: * </p>
202: * Will never return null.
203: *
204: * @return Filter indicating the selected features. Filter.ALL indicates no selected Features.
205: */
206: Filter getFilter();
207:
208: /**
209: * Returns the ZOrder of the Layer. The Z-Order dictates the order in which the Layer is rendered
210: * Low z-orders are rendered first and higher z-orders are rendered on top.
211: *
212: * @return the ZOrder of the Layer.
213: */
214: public int getZorder();
215:
216: /**
217: * Indication of Layer status.
218: * <p>
219: * This is used to provide feedback for a Layers rendering status.
220: * </p>
221: * Future versions will return an enum.
222: *
223: * @return
224: * @uml.property name="status"
225: */
226: public int getStatus();
227:
228: /**
229: * A message to provide the user with additional feed back about the current rendering status.
230: * <p>
231: * This is used to provide feedback for a Layers rendering status.
232: * </p>
233: *
234: * @return message to provide the user with additional feed back about the current rendering
235: * status.
236: */
237: public String getStatusMessage();
238:
239: /**
240: * Check toolset applicability.
241: * <p>
242: * Note: some layers may not ever be applicable for certaint toolsets. Sometimes this is can be
243: * determined quickly from a layer property like "selectable" for the selection toolset. Other
244: * toolsets may need to perform a more detailed examination.
245: * </p>
246: *
247: * @see isSelectable
248: * @param toolCategoryId
249: * @return
250: */
251: public boolean isApplicable(String toolCategoryId);
252:
253: /**
254: * Gets the name from the associated metadata.
255: *
256: * @return the name from the associated metadata
257: */
258: public String getName();
259:
260: /**
261: * Gets the unique id, unique within a context model
262: *
263: * @return the id of the layerRef
264: */
265: public URL getID();
266:
267: /**
268: * Returns whether this layer is currently visible
269: *
270: * @return whether this layer is currently visible
271: */
272: public boolean isVisible();
273:
274: /**
275: * Access to resources that hold data for this layer.
276: *
277: * @return IGeoResources that can used to obtain layer data
278: */
279: public List<IGeoResource> getGeoResources();
280:
281: /**
282: * ImageDescriptor for this Layer.
283: * <p>
284: * Note we need to do the decorator exention on Layer to reflect status.
285: *
286: * @return Custom glyph - or null if none available.
287: */
288: public ImageDescriptor getGlyph();
289:
290: /**
291: * Query that selects all the features for the layer.
292: * <p>
293: * The selected flag is used with respect to {@link getFilter()}:
294: * <ul>
295: * <li><b>false </b>: Query for layers contents
296: * <li><b>true </b>: Query for the layer's selected features
297: * </ul>
298: * </p>
299: * <p>
300: * Convenience method
301: * </p>
302: *
303: * @param layer The layer the Query is associated with.
304: * @param selection true will return a query for the selected features.
305: * @return If selection if false then the features that are not selected are returned, otherwise
306: * a query that selects all the selected features is returned.
307: */
308: public Query getQuery(boolean selection);
309:
310: /**
311: * Retrieve a schema description of this Layer.
312: * <p>
313: * This schema can be used to determine the available attributes for use in Style Rule
314: * construction. That is we will need to construct an "answer" for this query even if we just
315: * have a WMS layer.
316: * </p>
317: * <p>
318: * This is similar to the following check:
319: *
320: * <pre><code>
321: *
322: * data = getResource();
323: * <b>return</b> data != null ? data.getSchema() : null;
324: *
325: * </code></pre>
326: *
327: * </p>
328: *
329: * @return Schema information if available, otherwise null.
330: */
331: public FeatureType getSchema();
332:
333: /**
334: * Gets the CRS for the layer. NOTE: THIS METHOD MAY BLOCK!!!
335: *
336: * @param monitor may be null.
337: * @return the CoordinateReferenceSystem of the layer or if the CRS cannot be determined. the
338: * current map's CRS will be returned, or if this fails the CRS will be WGS84.
339: *
340: * @deprecated
341: */
342: CoordinateReferenceSystem getCRS(IProgressMonitor monitor);
343:
344: /**
345: * Gets the CRS for the layer. NOTE: THIS METHOD MAY BLOCK!!!
346: *
347: * @return the CoordinateReferenceSystem of the layer or if the CRS cannot be determined. the
348: * current map's CRS will be returned, or if this fails the CRS will be WGS84.
349: */
350: CoordinateReferenceSystem getCRS();
351:
352: /**
353: * Triggers the layer to rerender if it is currently displayed.
354: *
355: * @param bounds The area to render or the entire viewport if null.
356: */
357: void refresh(Envelope bounds);
358:
359: /**
360: * Returns the Mathtransform from this layers CRS to the map's CRS (modelled as part of the
361: * viewport model).
362: * <p>
363: * getMap().getViewportModel() will return the ViewportModel.
364: * </p>
365: *
366: * @see net.refractions.udig.project.render.IViewportModel
367: */
368: MathTransform layerToMapTransform() throws IOException;
369:
370: /**
371: * Returns the Mathtransform from the map's CRS (modeled as part of the viewport model) to this
372: * layers CRS .
373: * <p>
374: * getMap().getViewportModel() will return the ViewportModel.
375: * </p>
376: *
377: * @see net.refractions.udig.project.render.IViewportModel
378: */
379: MathTransform mapToLayerTransform() throws IOException;
380:
381: /**
382: * Temporary layer properties, used for lightweight collaboration.
383: * <p>
384: * Note these values are not persisted, this can act as a blackboard for plugin collabaration.
385: * These properties are not saved and are reset when a map is opened.
386: * </p>
387: * If you need long term collaboration we can set up a persistent blackboard in the same manner
388: * as StyleBlackbord.
389: * </p>
390: * <p>
391: * Note: Please don't use this to work around limitations of our object model, instead send
392: * email and we can set up a long term solution.
393: * </p>
394: *
395: * @return Blackboard used for lightweight collaboration.
396: * @deprecated
397: */
398: IBlackboard getProperties();
399:
400: /**
401: * Temporary layer properties, used for lightweight collaboration.
402: * <p>
403: * Note these values are not persisted, this can act as a blackboard for plugin collabaration.
404: * These properties are not saved and are reset when a map is opened.
405: * </p>
406: * If you need long term collaboration we can set up a persistent blackboard in the same manner
407: * as {@link IMap#getBlackboard()}.
408: * </p>
409: * <p>
410: * Note: Please don't use this to work around limitations of our object model, instead send
411: * email and we can set up a long term solution.
412: * </p>
413: *
414: * @return Blackboard used for lightweight collaboration.
415: *
416: */
417: IBlackboard getBlackboard();
418:
419: /**
420: * Returns the bounds of the layer as best estimated. The bounds will be reprojected into the
421: * crs provided. If the crs parameter is null then the native envelope will be returned. If the
422: * native projection is not known or if a transformation is not possible then the native
423: * envelope will be returned.. This method may be blocking.
424: *
425: * @param monitor
426: * @param crs the desired CRS for the returned envelope.
427: * @return the envelope of the layer. If the native crs is not known or if a transformation is
428: * not possible then the untransformed envelope will be returned.
429: */
430: ReferencedEnvelope getBounds(IProgressMonitor monitor,
431: CoordinateReferenceSystem crs) throws IOException;
432:
433: /**
434: * Creates A geometry filter for the layer.
435: * <p>
436: * getMap().getViewportModel() will return the ViewportModel.
437: * </p>
438: *
439: * @see net.refractions.udig.project.render.IViewportModel
440: * @param boundingBox in the same crs as the viewport model.
441: * @return a Geometry filter in the correct CRS or null if an exception occurs.
442: */
443: public Filter createBBoxFilter(Envelope boundingBox,
444: IProgressMonitor monitor);
445:
446: /**
447: * The Map that "owns" or "contains" the current layer.
448: *
449: * @return the containing map.
450: */
451: public IMap getMap();
452:
453: /**
454: * Sets the current status of the Layer.
455: *
456: * @param status the status. Will be an enum in the future but current EMF implementation
457: * prevents this.
458: * @uml.property name="status"
459: */
460: public void setStatus(int status);
461:
462: /**
463: * Sets the current status message
464: *
465: * @param message the status message
466: */
467: public void setStatusMessage(String string);
468:
469: }
|