org.opengis.feature.display.canvas

Interface FeatureCanvas

All Known Subinterfaces:

WebFeatureCanvas

public interface FeatureCanvas

Represents a canvas that consumes features and automatically turns them into graphics. A FeatureCanvas should be able to consume Feature objects from any FeatureStore that the user may provide.

Implementations of 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 FeatureCanvas turns every Feature it draws into one or more Graphic objects and adds them to a GO-1 Graphic Canvas. However, an implementation is free to optimize this by not creating actual Graphic objects until they are requested.

Data is added to a canvas by creating layers. A layer consists of a 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 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 FeatureCanvas is similar to the Map Context information as defined in the corresponding OGC spec. After further reflection, the FeatureCanvas abstraction may need to be refactored in light of these other two specs.

Since:

GeoAPI 2.0

Method Summary

Modifier and Type	Method and Description
void	addFeatureLayer(FeatureLayer layer) Adds the given layer to the map.
void	deleteFeatureLayer(FeatureLayer layer) Removes the given layer from being displayed on this map.
Canvas	getCanvas() Returns the Canvas onto which the Graphics will be rendered.
Feature	getFeatureAtPoint(int x, int y) Returns the feature whose graphic is located at the given location in the Canvas window.
Feature	getFeatureFromGraphic(Graphic graphic) 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 addFeatureLayer(...) call.
java.util.Iterator<Feature>	getFeaturesAtPoint(int x, int y) Returns the features whose graphics are located at the given location in the Canvas window.
java.util.List<FeatureLayer>	getLayers() Returns a list containing all of the FeatureLayers currently known to this canvas.

Method Detail

getFeatureFromGraphic

Feature getFeatureFromGraphic(Graphic graphic)

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 addFeatureLayer(...) call.

Parameters:

graphic - Find the feature instances associated with the given graphic. FeatureCanvases 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.

getFeatureAtPoint

Feature getFeatureAtPoint(int x,
                          int y)

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 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.

getFeaturesAtPoint

java.util.Iterator<Feature> getFeaturesAtPoint(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 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.

addFeatureLayer

void addFeatureLayer(FeatureLayer layer)

Adds the given layer to the map.

deleteFeatureLayer

void deleteFeatureLayer(FeatureLayer layer)

Removes the given layer from being displayed on this map.

getLayers

java.util.List<FeatureLayer> getLayers()

Returns a list containing all of the FeatureLayers currently known to this canvas. Callers should not attempt to modify this list. Instead, they should call addFeatureLayer(...) or deleteFeatureLayer(...).

getCanvas

Canvas getCanvas()

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.