/*$************************************************************************************************
**
** $Id: Layer.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/layer/Layer.java $
**
** Copyright (C) 2005 Open GIS Consortium, Inc.
** All Rights Reserved. http://www.opengis.org/legal/
**
*************************************************************************************************/
package org.opengis.layer;
// J2SE direct dependencies
import java.util.Collection;
import java.util.Map; // For javadoc
import java.util.Set;
import java.util.List;
// OpenGIS direct dependencies
import org.opengis.feature.display.canvas.FeatureCanvas;
import org.opengis.feature.display.canvas.FeatureLayer;
import org.opengis.go.display.canvas.Canvas;
import org.opengis.go.display.primitive.Graphic;
import org.opengis.metadata.Identifier;
import org.opengis.metadata.extent.GeographicBoundingBox;
import org.opengis.referencing.crs.CoordinateReferenceSystem;
import org.opengis.spatialschema.geometry.Envelope;
import org.opengis.util.InternationalString;
// Annotations
import org.opengis.annotation.XmlElement;
/**
* Organizes the basic GO-1 constructs that may be added to {@link FeatureCanvas} or {@link Canvas}.
* A GO-1 application may be directed to "add" a {@code Layer}; it should then add the {@code Layer}'s
* {@link FeatureLayer} and {@link Graphic}s to the respective canvases.
*
*
Mutability
* In current version, layers are unmodifiable, i.e. they can't be modified through
* the API provided in this interface, but they are not immutable because they may (or may not, at
* implementor choice) reflect a change in the underlying database. This means that all methods
* returning a {@linkplain java.util.Collection collection} must returns either an
* {@linkplain java.util.Collections#unmodifiableList unmodifiable} one, or a copy.
* Modifying returned collections should have no affect on this {@code Layer}.
*
* Note that the mutability aspect of {@code Layer} may be revisited in future versions,
* so users are encouraged to not rely strongly on current behavior.
*
* @version Implementation specification 1.3
* @author Jesse Crossley (SYS Technologies)
* @since GeoAPI 2.0
*/
@XmlElement("Layer") // 7.2.4.5 Layers and styles
public interface Layer {
/**
* Provides a unique name for identifying this {@code Layer}. If, and only if, a layer has a
* name, then it is a map layer that can be requested by using that name in the {@code LAYERS}
* parameter of a {@code GetMap} request. A layer that contains a {@code Name} element is
* referred to as a named layer. If the layer has a {@linkplain #getTitle title}
* but no name, then that layer is only a category title for all the layers nested within. A
* Map Server that advertises a layer containing a name element shall be able to accept that
* name as the value of {@code LAYERS} argument in a {@code GetMap} request and return the
* corresponding map. A client shall not attempt to request a layer that has a title but no
* name.
*
* The name is not inherited by {@linkplain #getLayers child layers}.
*
* @return the unique string identifier for this {@code Layer}.
*/
@XmlElement("Name") // 7.2.4.6.3
String getName();
/**
* Provides the human-readable string for presenting this {@code Layer}.
* Equivalent to {@link org.opengis.metadata.citation.Citation#getTitle}
* in {@linkplain org.opengis.annotation.Specification#ISO_19115 ISO 19115}.
*
* @return the human-readable title for this {@code Layer}.
*/
@XmlElement("Title") // 7.2.4.6.2
InternationalString getTitle();
/**
* Provides the narrative description of this {@code Layer}.
* Equivalent to {@link org.opengis.metadata.identification.DataIdentification#getAbstract}
* in {@linkplain org.opengis.annotation.Specification#ISO_19115 ISO 19115}.
* The abstract is not inherited by {@linkplain #getLayers child layers}.
*
* @return the narrative description of this {@code Layer}.
*/
@XmlElement("Abstract") // 7.2.4.6.4
InternationalString getAbstract();
/**
* Provides keywords to aid in catalogue searches.
* Equivalent to {@link org.opengis.metadata.identification.TopicCategory}
* in {@linkplain org.opengis.annotation.Specification#ISO_19115 ISO 19115} if the {@code vocabulary}
* attribute of {@code Keyword} element is "ISO19115:2003". Other vocabularies are permitted.
* The keywords are not inherited by {@linkplain #getLayers child layers}.
*
* The returned {@code List} (if modifiable) should not be live, and
* modifying it should not affect this {@code Layer}'s set of keywords.
*
* @return this {@code Layer}'s keyword list.
*/
@XmlElement("KeywordList") // 7.2.4.6.4
List getKeywordList();
/**
* Provides the coordinate reference systems available to this {@code Layer},
* which includes CRSs inherited from parent {@code Layer}s. In order to indicate
* what layer CRSs are available, every named layer shall have at least one CRS.
* The root layer shall include a sequence of zero or more CRS elements listing all
* CRSs that are common to all subsidiary layers. A child layer may optionally add
* to the list inherited from a parent layer.
*
* If CRS and {@linkplain #getBoundingBoxes bounding boxes} are backed by a
* {@linkplain Map}<{@linkplain CoordinateReferenceSystem},{@linkplain Envelope}>
* (from the J2SE collection framework), then the CRSs are the {@linkplain Map#keySet ket set}
* of the above-cited map.
*
* This {@code Set} (if modifiable) should not be live, and
* modifying it should not affect this {@code Layer}'s set of CRSs.
*
* @return this {@code Layer}'s coordinate reference systems.
*/
@XmlElement("CRS") // 7.2.4.6.7
Set getCRSs();
/**
* Provides the bounding boxes that specify the coordinate ranges for
* this {@code Layer}, as {@code Envelope}s, including bounding boxes
* inherited from parent {@code Layer}s.
* Equivalent to {@link org.opengis.metadata.extent.BoundingPolygon}
* in {@linkplain org.opengis.annotation.Specification#ISO_19115 ISO 19115},
* except that it is strictly a box here.
*
* A layer may have multiple bounding box elements, but each one shall state a different CRS.
* A bounding box inherited from the parent layer for a particular CRS is replaced by any
* declaration for the same CRS in the child layer. A bounding box in the child for a new
* CRS not already declared by the parent is added to the list of bounding boxes for the child
* layer. A single layer element shall not contain more than one bounding box for the same CRS.
*
* NOTE: There is no provision for describing disjoint bounding boxes.
* For example, consider a dataset which covers two areas separated by some distance.
* The server cannot provide two separate bounding boxes in the same layer using the same
* CRS to separately describe those areas. To handle this type of situation, the server may
* either define a single larger bounding box which encloses both areas, or may define two
* separate layers that each have distinct name and bounding box values.
*
* A layer shall not provide a bounding box for a CRS it does not support. Conversely, a
* layer may support CRSs for which it does not provide a bounding box: a server that has
* the ability to transform data to different CRSs may choose not to provide an explicit
* bounding box for every possible CRS available for each layer. The server should provide
* bounding box information for at least the native CRS of the layer (that is, the CRS
* in which the layer is stored in the server's database).
*
* If {@linkplain #getCRSs CRS} and bounding boxes are backed by a
* {@linkplain Map}<{@linkplain CoordinateReferenceSystem},{@linkplain Envelope}>
* (from the J2SE collection framework), then the bounding boxes are the
* {@linkplain Map#values values} of the above-cited map.
*
* This {@code Collection} (if modifiable) should not be live, and modifying
* it should have no affect on this {@code Layer}'s set of bounding boxes.
*
* @return this {@code Layer}'s bounding box envelopes.
*/
@XmlElement("BoundingBox") // 7.2.4.6.8
Collection getBoundingBoxes();
/**
* Provides the geographic bounding box that specify the longitude and
* latitude ranges for this {@code Layer}.
* Every named layer shall have exactly one geographic bounding box that is either stated
* explicitly or inherited from a parent layer. Geographic bounding box states, via the
* {@linkplain GeographicBoundingBox#getWestBoundLongitude west bound longitude},
* {@linkplain GeographicBoundingBox#getEastBoundLongitude east bound longitude},
* {@linkplain GeographicBoundingBox#getSouthBoundLatitude south bound latitude}, and
* {@linkplain GeographicBoundingBox#getNorthBoundLatitude north bound latitude},
* the minimum bounding rectangle in decimal degrees of the area covered by the layer.
* Geographic bounding box shall be supplied regardless of what CRS the map server may support,
* but it may be approximate if the data are not natively in geographic coordinates. The purpose
* of beographic bounding box is to facilitate geographic searches without requiring coordinate
* transformations by the search engine.
*
* This method is conceptually similar to a {@linkplain #getBoundingBoxes bounding box} in
* which the CRS is implicitly CRS:84. However, Geographic bounding box shall not be used
* as a substitute for {@code }. If the server wishes to provide
* bounding box information in the CRS:84 CRS, then a separate bounding box element explicitly
* naming CRS:84 shall be included in the service metadata.
*/
@XmlElement("GeographicBoundingBox") // 7.2.4.6.6
GeographicBoundingBox getGeographicBoundingBox();
/**
* Provides the attribution for this {@code Layer}, which identifies the source of
* the geographic information used in this layer. This is partially equivalent to
* {@link org.opengis.metadata.citation.ResponsibleParty} in
* {@linkplain org.opengis.annotation.Specification#ISO_19115 ISO 19115}.
* The attribution is inherited by child layers. Any redefinition by
* a child replaces the inherited value.
*
* @return this {@code Layer}'s attribution.
*/
@XmlElement("Attribution") // 7.2.4.6.12
Attribution getAttribution();
/**
* Provides the authority URLs named in this {@code Layer}'s {@linkplain Identifier identifiers}.
* Equivalent to {@link org.opengis.metadata.citation.Contact#getOnLineResource}
* in {@linkplain org.opengis.annotation.Specification#ISO_19115 ISO 19115}.
*
* The returned {@code List} (if modifiable) should not be live, and
* modifying it should have no affect on this {@code Layer}'s set of authority URLs.
*
* @return this {@code Layer}'s authority URLs.
*/
@XmlElement("AuthorityURL") // 7.2.4.6.13
List getAuthorityURLs();
/**
* Provides the identifiers containing ID numbers or labels defined by a particular authority.
* Equivalent to {@link org.opengis.metadata.Identifier#getCode}
* in {@linkplain org.opengis.annotation.Specification#ISO_19115 ISO 19115}.
*
* The returned {@code List} (if modifiable) should not be live, and
* modifying it should have no affect on this {@code Layer}'s set of identifiers.
*
* @return this {@code Layer}'s identifiers.
*/
@XmlElement("Identifier") // 7.2.4.6.13
List getIdentifiers();
/**
* Provides the Metadata URLs that offer detailed, standardized metadata about
* the data for this {@code Layer}.
*
* The returned {@code List} (if modifiable) should not be live, and modifying
* it should have no affect on this {@code Layer}'s set of metadata URLs.
*
* @return this {@code Layer}'s metadata URLs.
*/
@XmlElement("MetadataURL") // 7.2.4.6.11
List getMetadataURLs();
/**
* Provides the data URLs that offer links to the underlying data represented by this {@code Layer}.
* Data URLs are not inherited by child layers.
*
* The returned {@code List} (if modifiable) should not be live, and modifying
* it should have no affect on this {@code Layer}'s set of data URLs.
*
* @return this {@code Layer}'s data URLs.
*/
@XmlElement("DataURL") // 7.2.4.6.15
List getDataURLs();
/**
* Provides the feature URLs that point to a list of features represented in this {@code Layer}.
* Feature URLs are not inherited by child layers.
*
* The returned {@code List} (if modifiable) should not be live, and modifying
* it should have no affect on this {@code Layer}'s feature list URLs.
*
* @return this {@code Layer}'s feature list URLs.
*/
@XmlElement("FeatureListURL") // 7.2.4.6.14
List getFeatureListURLs();
/**
* Provides the styles that may be requested for this {@code Layer}.
* Zero or more styles may be advertised for a layer or collection of layers, each of
* which shall have {@linkplain Style#getName name} and {@linkplain Style#getTitle title}.
* The style's name is used in the Map request {@code STYLES} parameter. The title is a
* human-readable string. If only a single style is available, that style is known as the
* "default" style and need not be advertised by the server.
*
* Style declarations are inherited by {@linkplain #getLayers child layers}.
* A child shall not redefine a style with the same {@linkplain Style#getName name}
* as one inherited from a parent. A child may define a new style with a new name
* that is not available for the parent layer.
*
* The returned {@code List} (if modifiable) should not be live, and
* modifying it should have no affect on this {@code Layer}'s styles.
*
* @return this {@code Layer}'s styles.
*/
@XmlElement("Style") // 7.2.4.6.5
List