/*$************************************************************************************************
**
** $Id: Query.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/Query.java $
**
** Copyright (C) 2005 Open GIS Consortium, Inc.
** All Rights Reserved. http://www.opengis.org/legal/
**
*************************************************************************************************/
package org.opengis.feature;
// J2SE direct dependencies
import java.util.List;
// OpenGIS direct dependencies
import org.opengis.filter.Filter;
import org.opengis.referencing.crs.CoordinateReferenceSystem;
import org.opengis.util.GenericName;
// Annotations
import org.opengis.annotation.Extension;
import org.opengis.annotation.XmlElement;
/**
* Used by the {@link FeatureStore#getFeatures(Query) getFeatures} method
* of the {@linkplain FeatureStore data store} interface, to encapsulate a request.
* A query defines which {@linkplain FeatureType feature type} to query, what properties
* to retrieve and what constraints (spatial and non-spatial) to apply to those properties.
* It is designed to closesly match a WFS Query element of a {@code getFeatures} request.
* A difference is the addition of the {@link #getMaxFeatures maxFeatures} element, which
* allows more control over the {@linkplain Feature features} selected. It allows a full
* {@code getFeatures} request to properly control how many features it gets from each query,
* instead of requesting and discarding when the max is reached.
*
* @version Implementation specification 1.1
* @since GeoAPI 2.0
*
* @todo The following XML elements are not yet defined in this interface:
* {@code Function}, {@code SortBy}.
*/
@XmlElement("Query")
public interface Query {
/**
* Returns the name of the type that is to be queried.
*
* @todo OGC specification said that a list should be returned.
* We may add a {@code getTypeNames()} (plural form) in a
* future version.
*/
@XmlElement("typeName")
GenericName getTypeName();
/**
* Returns the name of the type that is to be queried.
* The type name is a list of one or more feature type names that indicate
* which types of feature instances should be included in the reponse set.
* Specifying more than one type name indicates that a join operation is
* being performed. All the names in the type name list must be valid types
* that belong to this query's feature content.
*/
// @XmlElement("typeName")
// Collection getTypeNames();
/**
* Returns the filter that will limit which {@linkplain Feature features} are returned.
* The filter element is used to define spatial and/or non-spatial constraints on query.
* It may be {@code null} if there is none.
*/
@XmlElement("Filter")
Filter getFilter();
/**
* Returns the list of property names of the {@linkplain Feature features}
* to be retrieved. This may be null if all properties are to be retrieved.
*
* This is used to specify one or more properties of a {@linkplain Feature feature}
* whose values are to be retrieved by a Web Feature Service. While a Web Feature
* Service should endeavour to satisfy the exact request specified, in some instance
* this may not be possible. Specifically, a Web Feature Service must generate a
* valid GML response to a Query operation. The schema used to generate the output
* may include properties that are mandatory. In order that the output validates,
* these mandatory properties must be specified in the request. If they are not, a
* Web Feature Service may add them automatically to the Query before processing it.
* Thus a client application should, in general, be prepared to receive more properties
* than it requested. Of course, using {@link FeatureAttributeDescriptor}, a client
* application can determine which properties are mandatory and request them in the
* first place.
*/
@XmlElement("Property")
List getPropertyNames();
/**
* Gives a mnemonic name for use by the client to identify this query.
* The handle allows a client application to assign a client-generated
* identifier for the query. The handle is included to facilitate error
* reporting. If one query in a {@code GetFeature} request causes an exception,
* a WFS may report the handle to indicate which query element failed. If the
* handle is not present, the WFS may use other means to localize the error
* (e.g. line numbers).
*/
@XmlElement("handle")
String getHandle();
/**
* Returns the maximum number of features to be retrieved by the query.
* Can return zero. Can also return {@link Integer#MAX_VALUE} to indicate
* that the maximum number of features is unlimited.
*
* @todo {@code maxFeatures} is an attribute of {@code getFeature} request.
* We may wish to avoid duplication once WMS interfaces are provided in
* GeoAPI.
*/
@Extension
int getMaxFeatures();
/**
* Returns the feature version to query. The version attribute is included in order to
* accommodate systems that support feature versioning. A value of {@code "ALL"} indicates
* that all versions of a feature should be fetched. Otherwise an integer, n,
* can be specified to return the nth version of a {@linkplain Feature
* feature}. The version numbers start at '1' which is the oldest version. If a version value
* larger than the largest version is specified then the latest version is return. The default
* action shall be for the query to return the latest version. Systems that do not support
* versioning can ignore the parameter and return the only version that they have.
*
* @return the version of the feature to return, or null for latest.
*/
@XmlElement("featureVersion")
String getVersion();
/**
* Temporarily override the coordinate reference system.
* This denotes a request to temporarily override the coordinate reference
* system contained in the {@link FeatureStore} being queried. The same
* coordinate values will be used, but the features created will appear in this CRS.
*
* This change is not persistant at all, indeed it is only for the {@link Feature}s
* returned by this {@code Query}. It may be used in conjunction with the reprojection
* CRS, but this one will always be used first. The reprojection CRS will perform its
* operation on this crs.
*
* @return The coordinate reference system to be returned for {@link Feature}s from this
* {@code Query}.
*
* @todo JG: Please if you possibly can treat the idea of "forcing" the CRS as a
* {@link FeatureCollection} configuration issue (or a {@link FeatureStore}
* configuration issue). Recent experience with Geotools shows the added burden
* on client code to be a pain.
*
* @todo MD: This method is misnamed. {@link org.opengis.referencing.cs.CoordinateSystem}
* and {@link org.opengis.referencing.crs.CoordinateReferenceSystem} are not the
* same thing.
*/
@Extension
CoordinateReferenceSystem getCoordinateSystem();
/**
* Request data reprojection. Gets the coordinate reference system to reproject the
* data contained in the backend {@linkplain FeatureStore feature store} to.
* If the feature store can optimize the reprojection it should. If not then
* a decorator on the reader should perform the reprojection on the fly.
*
* @return The coordinate reference system that {@linkplain Feature features} from the
* {@linkplain FeatureStore feature store} should be reprojected to.
*
* @todo MD: This method is misnamed. {@link org.opengis.referencing.cs.CoordinateSystem}
* and {@link org.opengis.referencing.crs.CoordinateReferenceSystem} are not the
* same thing.
*/
@Extension
CoordinateReferenceSystem getCoordinateSystemReproject();
/**
* Specifies a specific WFS-supported CRS that should be used for returned feature
* geometries. The value may be the WFS {@code "StorageSRS"} value,
* {@code "DefaultRetrievalSRS"} value, or one of {@code "AdditionalSRS"} values.
* If no CRS name value is supplied, then the features will be returned using either
* the {@code "DefaultRetrievalSRS"}, if specified, and {@code "StorageSRS"} otherwise.
* For feature types with no spatial properties, this attribute must not be specified
* or ignored if it is specified.
*/
// @XmlElement("srsName")
// String getCrsName();
}
Ads help maintain this website.