/*$************************************************************************************************
 **
 ** $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