org.geotools.data
Interface Query

All Known Implementing Classes:

DefaultQuery

public interface Query

Encapsulates a data request.

The query object is used by the FeatureSource.getFeatures(Query) to encapsulate a request. For this use it the FeatureSource.getSchema().getTypeName() should match the one provided by the Query, or the Query should not provide one.

Suggested Extensions (Jody):

• Transient CoordianteSystem override done getCoordianteSystem()
• Transient Geometry reproject to an alternate CoordinateSystem - done getCoordinateSystemReproject()
• Consider Namespace, FeatueType name override - not done considered evil
• DataStore.getFeatureReader( Query, Transaction )
• DataStore.getView( Query ) - prototype in AbstractDataStore (not really ready for primetime, see Expr)

Version:

$Id: Query.java 17702 2006-01-23 00:08:55Z desruisseaux $

Author:

Chris Holmes

Field Summary

static Query	ALL Implements a query that will fetch all features from a datasource.
static java.lang.String[]	ALL_NAMES Ask for all properties when used with setPropertyNames.
static int	DEFAULT_MAX So getMaxFeatures does not return null we use a very large number.
static Query	FIDS Implements a query that will fetch all the FeatureIDs from a datasource.
static java.lang.String[]	NO_NAMES Ask for no properties when used with setPropertyNames.
static java.net.URI	NO_NAMESPACE TODO: should this be ANY_URI

Method Summary

org.opengis.referencing.crs.CoordinateReferenceSystem	getCoordinateSystem() Temporarily override the coordinate system.
org.opengis.referencing.crs.CoordinateReferenceSystem	getCoordinateSystemReproject() Request data reprojection.
Filter	getFilter() The Filter can be used to define constraints on a query.
java.lang.String	getHandle() The handle attribute is included to allow a client to associate a mnemonic name to the Query request.
int	getMaxFeatures() The optional maxFeatures can be used to limit the number of features that a query request retrieves.
java.net.URI	getNamespace() The namespace attribute is used to indicate the namespace of the schema being represented.
java.lang.String[]	getPropertyNames() The properties array is used to specify the attributes that should be selected for the return feature collection.
SortBy[]	getSortBy() SortBy results according to indicated property and order.
java.lang.String	getTypeName() The typeName attribute is used to indicate the name of the feature type to be queried.
java.lang.String	getVersion() From WFS Spec: The version attribute is included in order to accommodate systems that support feature versioning.
boolean	retrieveAllProperties() Convenience method to determine if the query should use the full schema (all properties) of the data source for the features returned.

Field Detail

NO_NAMESPACE

public static final java.net.URI NO_NAMESPACE

TODO: should this be ANY_URI

DEFAULT_MAX

public static final int DEFAULT_MAX

So getMaxFeatures does not return null we use a very large number.

See Also:

Constant Field Values

ALL

public static final Query ALL

Implements a query that will fetch all features from a datasource. This query should retrieve all properties, with no maxFeatures, no filtering, and the default featureType.

FIDS

public static final Query FIDS

Implements a query that will fetch all the FeatureIDs from a datasource. This query should retrive no properties, with no maxFeatures, no filtering, and the a featureType with no attribtues.

NO_NAMES

public static final java.lang.String[] NO_NAMES

Ask for no properties when used with setPropertyNames.

Note the query will still return a result - limited to FeatureIDs.

ALL_NAMES

public static final java.lang.String[] ALL_NAMES

Ask for all properties when used with setPropertyNames.

Method Detail

getPropertyNames

public java.lang.String[] getPropertyNames()

The properties array is used to specify the attributes that should be selected for the return feature collection.

• ALL_NAMES: null
  If no properties are specified (getProperties returns ALL_NAMES or null) then the full schema should be used (all attributes).
• NO_NAMES: new String[0]
  If getProperties returns an array of size 0, then the datasource should return features with no attributes, only their ids.

The available properties can be determined with a getSchema call from the DataSource interface. A datasource can use retrieveAllProperties() as a shortcut to determine if all its available properties should be returned (same as checking to see if getProperties is ALL_NAMES, but clearer)

If properties that are not part of the datasource's schema are requested then the datasource shall throw an exception.

This replaces our funky setSchema method of retrieving select properties. It makes it easier to understand how to get certain properties out of the datasource, instead of having users get the schema and then compose a new schema using the attributes that they want. The old way had problems because one couldn't have multiple object reuse the same datasource object, since some other object could come along and change its schema, and would then return the wrong properties.

Returns:

the attributes to be used in the returned FeatureCollection.

Task:

REVISIT: make a FidProperties object, instead of an array size 0. I think Query.FIDS fills this role to some degree. Query.FIDS.equals( filter ) would meet this need?

retrieveAllProperties

public boolean retrieveAllProperties()

Convenience method to determine if the query should use the full schema (all properties) of the data source for the features returned. This method is equivalent to if (query.getProperties() == null), but allows for more clarity on the part of datasource implementors, so they do not need to examine and use null values. All Query implementations should return true for this function if getProperties returns null.

Returns:

if all datasource attributes should be included in the schema of the returned FeatureCollection.

getMaxFeatures

public int getMaxFeatures()

The optional maxFeatures can be used to limit the number of features that a query request retrieves. If no maxFeatures is specified then all features should be returned.

This is the only method that is not directly out of the Query element in the WFS spec. It is instead a part of a GetFeature request, which can hold one or more queries. But each of those in turn will need a maxFeatures, so it is needed here.

Returns:

the max features the getFeature call should return.

getFilter

public Filter getFilter()

The Filter can be used to define constraints on a query. If no Filter is present then the query is unconstrained and all feature instances should be retrieved.

Returns:

The filter that defines constraints on the query.

getTypeName

public java.lang.String getTypeName()

The typeName attribute is used to indicate the name of the feature type to be queried. If no typename is specified, then the default typeName should be returned from the dataStore. If the datasstore only supports one feature type then this part of the query may be ignored.

Returns:

the name of the feature type to be returned with this query.

getNamespace

public java.net.URI getNamespace()

The namespace attribute is used to indicate the namespace of the schema being represented.

Returns:

the gml namespace of the feature type to be returned with this query

getHandle

public java.lang.String getHandle()

The handle attribute is included to allow a client to associate a mnemonic name to the Query request. The purpose of the handle attribute is to provide an error handling mechanism for locating a statement that might fail.

Returns:

the mnemonic name of the query request.

getVersion

public java.lang.String getVersion()

From WFS Spec: The version attribute is included in order to accommodate systems that support feature versioning. A value of ALL indicates that all versions of a feature should be fetched. Otherwise an integer, n, can be specified to return the n th version of a 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.

Returns:

the version of the feature to return, or null for latest.

getCoordinateSystem

public org.opengis.referencing.crs.CoordinateReferenceSystem getCoordinateSystem()

Temporarily override the coordinate system.

This denotes a request to Temporarily to override the coordinate system contained in the FeatureSource being queried. The same coordinate values will be used, but the features created will appear in this Coordinate System.

This change is not persistant at all, indeed it is only for the Features returned by this Query. It may be used in conjunction with the reprojection Coordinate System, but this one will always be used first, the reprojection CS will perform its operation on this cs.

Returns:

The coordinate system to be returned for Features from this Query (override the set coordinate system).

getCoordinateSystemReproject

public org.opengis.referencing.crs.CoordinateReferenceSystem getCoordinateSystemReproject()

Request data reprojection.

Gets the coordinate System to reproject the data contained in the backend datastore to.

If the DataStore can optimize the reprojection it should, if not then a decorator on the reader should perform the reprojection on the fly.

If the datastore has the wrong CS then getOverrideCS() should be set to the CS to be used, this will perform the reprojection on that.

Returns:

The coordinate system that Features from the datasource should be reprojected to.

getSortBy

public SortBy[] getSortBy()

SortBy results according to indicated property and order.

SortBy is part of the Filter 1.1 specification, it is referenced by WFS1.1 and Catalog 2.0.x specifications and is used to organize results.

The SortBy's are ment to be applied in order:

• SortBy( year, ascending )
• SortBy( month, decsending )

Would produce something like:

 [year=2002 month=4],[year=2002 month=3],[year=2002 month=2],
 [year=2002 month=1],[year=2003 month=12],[year=2002 month=4],
 

SortBy should be considered at the same level of abstraction as Filter, and like Filter you may sort using properties not listed in getPropertyNames.

At a technical level the interface SortBy2 is used to indicate the additional requirements of a GeoTools implementation. The pure WFS 1.1 specification itself is limited to SortBy.

Returns:

SortBy array or order of application