/*$************************************************************************************************
 **
 ** $Id: FeatureCanvas.java 831 2006-05-01 00:27:23Z Desruisseaux $
 **
 ** $URL: http://svn.code.sf.net/p/geoapi/code/branches/2.0.x/geoapi/src/main/java/org/opengis/feature/display/canvas/FeatureCanvas.java $
 **
 ** Copyright (C) 2005 Open GIS Consortium, Inc.
 ** All Rights Reserved. http://www.opengis.org/legal/
 **
 *************************************************************************************************/
package org.opengis.feature.display.canvas;

// J2SE direct dependencies
import java.util.Iterator;
import java.util.List;

// OpenGIS direct dependencies
import org.opengis.layer.Layer;                // For javadoc
import org.opengis.feature.Feature;
import org.opengis.feature.FeatureStore;       // For javadoc
import org.opengis.feature.FeatureCollection;  // For javadoc
import org.opengis.go.display.canvas.Canvas;
import org.opengis.go.display.primitive.Graphic;


/**
 * Represents a canvas that consumes {@linkplain Feature features} and automatically
 * turns them into {@linkplain Graphic graphics}. A {@code FeatureCanvas} should be
 * able to consume {@code Feature} objects from any {@link FeatureStore} that the user
 * may provide.
 * 

* Implementations of {@code FeatureCanvas} are free to optimize their temporary storage * of features in any way that they see fit. This could simply mean holding * feature instances in memory, or it could mean serializing them into secondary * storage in order minimize their impact on main memory, or some more * sophisticated caching scheme. *

* Conceptually, a {@code FeatureCanvas} turns every {@link Feature} it draws into one * or more {@link Graphic} objects and adds them to a GO-1 Graphic Canvas. However, an * implementation is free to optimize this by not creating actual {@link Graphic} * objects until they are requested. *

* Data is added to a canvas by creating {@linkplain Layer layers}. A layer consists of a * {@link FeatureCollection}, a style to use for drawing those features, and perhaps * some child Layers. In order to keep its rendering up-to-date, an * implementation of {@code FeatureCanvas} may add feature listeners to the feature * collection in the layer. *

* In many ways, this class looks like an in-process WMS that draws Features. * Similar to a WMS, it has concepts of layers with styles. Moreover, the state * information maintained by a {@code FeatureCanvas} is similar to the Map Context * information as defined in the corresponding OGC spec. After further * reflection, the {@code FeatureCanvas} abstraction may need to be refactored in light * of these other two specs. * * @author Chris Dillard (SYS Technologies) * @since GeoAPI 2.0 */ public interface FeatureCanvas { /** * Given a Graphic that is on this canvas, returns the Feature from which * it was built, or null if the graphic is not on this canvas or was not * created as a result of an {@link #addFeatureLayer addFeatureLayer(...)} * call. * * @param graphic Find the feature instances associated with the given * graphic. {@code FeatureCanvas}es are required to maintain this * mapping of graphics to feature. However, you must use the contained * GO-1 canvas to obtain instances of Graphic based on their position * on a canvas. */ Feature getFeatureFromGraphic(Graphic graphic); /** * Returns the feature whose graphic is located at the given location in the * Canvas window. *

* A naive implementation could implement this method by getting the * Graphics at that location (from the Canvas) and then call * {@link #getFeatureFromGraphic getFeatureFromGraphic(...)}. * However, a more sophisticated implementation may not even create * Graphic instances when a Feature is added to this Canvas. * Instead it may defer that until absolutely necessary. */ Feature getFeatureAtPoint(int x, int y); /** * Returns the features whose graphics are located at the given location in * the Canvas window. *

* A naive implementation could implement this method by getting the * Graphics at that location (from the Canvas) and then repeatedly call * {@link #getFeatureFromGraphic getFeatureFromGraphic(...)}. However, * a more sophisticated implementation may not even create Graphic instances * when a Feature is added to this Canvas. Instead it may defer that until * absolutely necessary. */ Iterator getFeaturesAtPoint(int x, int y); /** * Adds the given layer to the map. */ void addFeatureLayer(FeatureLayer layer); /** * Removes the given layer from being displayed on this map. */ void deleteFeatureLayer(FeatureLayer layer); /** * Returns a list containing all of the {@code FeatureLayer}s currently * known to this canvas. Callers should not attempt to modify this list. * Instead, they should call {@link #addFeatureLayer addFeatureLayer(...)} * or {@link #deleteFeatureLayer deleteFeatureLayer(...)}. */ List getLayers(); /** * Returns the Canvas onto which the Graphics will be rendered. References to * this canvas must not be held by the callers of the feature * canvas API. The feature canvas instance that provides the GO-1 canvas is * expected to have the freedom to control the life-cycle of the GO-1 canvas * so that it may apply a variety of potential optimizations to the management * of canvas objects. */ Canvas getCanvas(); }

Ads help maintain this website.