Package org.apache.sis.storage
Class FeatureQuery
java.lang.Object
org.apache.sis.storage.Query
org.apache.sis.storage.FeatureQuery
- All Implemented Interfaces:
Serializable
,Cloneable
Definition of filtering to apply for fetching a subset of
FeatureSet
.
This query mimics SQL SELECT
statements using OGC Filter and Expressions.
Information stored in this query can be used directly with Stream
API.
Terminology
This class uses relational database terminology:- A selection is a filter choosing the features instances to include in the subset. In relational databases, a feature instances are mapped to table rows.
- A projection (not to be confused with map projection) is the set of feature property to keep. In relational databases, feature properties are mapped to table columns.
Optional values
All aspects of this query are optional and initialized to "none". Unless otherwise specified, all methods accept a null argument or can return a null value, which means "none".- Since:
- 1.1
- Version:
- 1.2
- See Also:
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionstatic class
An expression to be retrieved by aQuery
, together with the name to assign to it. -
Field Summary
FieldsModifier and TypeFieldDescriptionprivate long
The maximum number of feature instances contained in theFeatureSet
.private javax.measure.Quantity<javax.measure.quantity.Length>
Hint used by resources to optimize returned features.private FeatureQuery.NamedExpression[]
The properties to retrieve, ornull
if all properties shall be included in the query.private Filter<? super AbstractFeature>
The filter for trimming feature instances.private static final long
For cross-version compatibility.private long
The number of feature instances to skip from the beginning.private SortBy<AbstractFeature>
The expressions to use for sorting the feature instances.private static final long
Sentinel limit value for queries of unlimited length. -
Constructor Summary
Constructors -
Method Summary
Modifier and TypeMethodDescriptionclone()
Returns a clone of this query.boolean
Compares this query with the given object for equality.protected FeatureSet
execute
(FeatureSet source) Applies this query on the given feature set.(package private) final DefaultFeatureType
expectedType
(DefaultFeatureType valueType) Returns the type of values evaluated by this query when executed on features of the given type.getLimit()
Returns the maximum number of feature instances contained in theFeatureSet
.javax.measure.Quantity<javax.measure.quantity.Length>
Returns the desired spatial resolution of geometries.long
Returns the number of feature instances to skip from the beginning.Returns the properties to retrieve, ornull
if all properties shall be included in the query.Filter<? super AbstractFeature>
Returns the filter for trimming feature instances.(package private) final SortBy<AbstractFeature>
Returns the expressions to use for sorting the feature instances.int
hashCode()
Returns a hash code value for this query.private static String
label
(Expression<?, ?> expression) Returns a label for the given expression for reporting to human (e.g.void
setLimit
(long limit) Set the maximum number of feature instances contained in theFeatureSet
.void
setLinearResolution
(javax.measure.Quantity<javax.measure.quantity.Length> linearResolution) Sets the desired spatial resolution of geometries.void
setOffset
(long skip) Sets the number of feature instances to skip from the beginning.void
setProjection
(String... properties) Sets the properties to retrieve by their names.final void
setProjection
(Expression<? super AbstractFeature, ?>... properties) Sets the properties to retrieve, ornull
if all properties shall be included in the query.void
setProjection
(FeatureQuery.NamedExpression... properties) Sets the properties to retrieve, ornull
if all properties shall be included in the query.void
setSelection
(Filter<? super AbstractFeature> selection) Sets a filter for trimming feature instances.void
setSelection
(org.opengis.geometry.Envelope domain) Sets the approximate area of feature instances to include in the subset.(package private) final void
setSortBy
(SortBy<AbstractFeature> sortBy) Sets the expressions to use for sorting the feature instances.(package private) final void
setSortBy
(SortProperty<AbstractFeature>... properties) Sets the expressions to use for sorting the feature instances.void
Removes any limit defined bysetLimit(long)
.toString()
Returns a textual representation of this query for debugging purposes.
-
Field Details
-
serialVersionUID
private static final long serialVersionUIDFor cross-version compatibility.- See Also:
-
UNLIMITED
private static final long UNLIMITEDSentinel limit value for queries of unlimited length. This value applies to thelimit
field.- See Also:
-
projection
The properties to retrieve, ornull
if all properties shall be included in the query. In a database, "properties" are table columns. Subset of columns is called projection in relational database terminology. -
selection
The filter for trimming feature instances. In a database, "feature instances" are table rows. Subset of rows is called selection in relational database terminology.- See Also:
-
skip
private long skipThe number of feature instances to skip from the beginning. This is zero if there are no instances to skip.- See Also:
-
limit
private long limitThe maximum number of feature instances contained in theFeatureSet
. This isUNLIMITED
if there is no limit.- See Also:
-
sortBy
The expressions to use for sorting the feature instances.- See Also:
-
linearResolution
private javax.measure.Quantity<javax.measure.quantity.Length> linearResolutionHint used by resources to optimize returned features. Different stores make use of vector tiles of different scales. Anull
value means to query data at their full resolution.
-
-
Constructor Details
-
FeatureQuery
public FeatureQuery()Creates a new query applying no filter.
-
-
Method Details
-
setProjection
Sets the properties to retrieve by their names. This convenience method wraps the given names inValueReference
expressions without alias and delegates tosetProjection(NamedExpression...)
.- Specified by:
setProjection
in classQuery
- Parameters:
properties
- properties to retrieve, ornull
to retrieve all properties.- Throws:
IllegalArgumentException
- if a property is duplicated.
-
setProjection
Sets the properties to retrieve, ornull
if all properties shall be included in the query. This convenience method wraps the given expression inFeatureQuery.NamedExpression
s without alias and delegates tosetProjection(NamedExpression...)
.- Parameters:
properties
- properties to retrieve, ornull
to retrieve all properties.- Throws:
IllegalArgumentException
- if a property is duplicated.
-
setProjection
Sets the properties to retrieve, ornull
if all properties shall be included in the query. A query column may use a simple or complex expression and an alias to create a new type of property in the returned features.This is equivalent to the column names in the
SELECT
clause of a SQL statement. Subset of columns is called projection in relational database terminology.- Parameters:
properties
- properties to retrieve, ornull
to retrieve all properties.- Throws:
IllegalArgumentException
- if a property or an alias is duplicated.
-
getProjection
Returns the properties to retrieve, ornull
if all properties shall be included in the query. This is the expressions specified in the last call tosetProjection(NamedExpression[])
. The default value is null.- Returns:
- properties to retrieve, or
null
to retrieve all feature properties.
-
setSelection
public void setSelection(org.opengis.geometry.Envelope domain) Sets the approximate area of feature instances to include in the subset. This convenience method creates a filter that checks if the bounding box of the feature's"sis:geometry"
property interacts with the given envelope.- Specified by:
setSelection
in classQuery
- Parameters:
domain
- the approximate area of interest, ornull
if none.
-
setSelection
Sets a filter for trimming feature instances. Features that do not pass the filter are discarded. Discarded features are not counted for the query limit.- Parameters:
selection
- the filter, ornull
if none.
-
getSelection
Returns the filter for trimming feature instances. This is the value specified in the last call tosetSelection(Filter)
. The default value isnull
, which means that no filtering is applied.- Returns:
- the filter, or
null
if none.
-
setOffset
public void setOffset(long skip) Sets the number of feature instances to skip from the beginning. Offset and limit are often combined to obtain paging. The offset cannot be negative.Note that setting this property can be costly on parallelized streams. See
Stream.skip(long)
for more information.- Parameters:
skip
- the number of feature instances to skip from the beginning.
-
getOffset
public long getOffset()Returns the number of feature instances to skip from the beginning. This is the value specified in the last call tosetOffset(long)
. The default value is zero, which means that no features are skipped.- Returns:
- the number of feature instances to skip from the beginning.
-
setUnlimited
public void setUnlimited()Removes any limit defined bysetLimit(long)
. -
setLimit
public void setLimit(long limit) Set the maximum number of feature instances contained in theFeatureSet
. Offset and limit are often combined to obtain paging.Note that setting this property can be costly on parallelized streams. See
Stream.limit(long)
for more information.- Parameters:
limit
- maximum number of feature instances contained in theFeatureSet
.
-
getLimit
Returns the maximum number of feature instances contained in theFeatureSet
. This is the value specified in the last call tosetLimit(long)
.- Returns:
- maximum number of feature instances contained in the
FeatureSet
, or empty if none.
-
setSortBy
Sets the expressions to use for sorting the feature instances.SortBy
objects are used to order theFeature
instances returned by theFeatureSet
.SortBy
clauses are applied in declaration order, like SQL.- Parameters:
properties
- expressions to use for sorting the feature instances, ornull
or an empty array if none.
-
setSortBy
Sets the expressions to use for sorting the feature instances.SortBy
objects are used to order theFeature
instances returned by theFeatureSet
.- Parameters:
sortBy
- expressions to use for sorting the feature instances, ornull
if none.
-
getSortBy
Returns the expressions to use for sorting the feature instances. This is the value specified in the last call tosetSortBy(SortBy)
.- Returns:
- expressions to use for sorting the feature instances, or
null
if none.
-
setLinearResolution
public void setLinearResolution(javax.measure.Quantity<javax.measure.quantity.Length> linearResolution) Sets the desired spatial resolution of geometries. This property is an optional hint; resources may ignore it.- Parameters:
linearResolution
- desired spatial resolution, ornull
for full resolution.
-
getLinearResolution
public javax.measure.Quantity<javax.measure.quantity.Length> getLinearResolution()Returns the desired spatial resolution of geometries. Anull
value means that data are queried at their full resolution.- Returns:
- desired spatial resolution, or
null
for full resolution.
-
label
Returns a label for the given expression for reporting to human (e.g. in exception messages). This method uses the value reference (XPath) or literal value if applicable, truncated to an arbitrary length. -
execute
Applies this query on the given feature set. This method is invoked by the default implementation ofFeatureSet.subset(Query)
. The default implementation executes the query using the defaultStream
methods. Queries executed by this method may not benefit from accelerations provided for example by databases. This method should be used only as a fallback when the query cannot be executed natively byFeatureSet.subset(Query)
.The returned
FeatureSet
does not cache the resultingFeature
instances; the query is processed on every call to theFeatureSet.features(boolean)
method.- Parameters:
source
- the set of features to filter, sort or process.- Returns:
- a view over the given feature set containing only the filtered feature instances.
- Throws:
DataStoreException
- if an error occurred during creation of the subset.- Since:
- 1.2
- See Also:
-
expectedType
Returns the type of values evaluated by this query when executed on features of the given type. If some expressions have no name, default names are computed as below:- If the expression is an instance of
ValueReference
, the name of the property referenced by the x-path. - Otherwise the localized string "Unnamed #1" with increasing numbers.
- Parameters:
valueType
- the type of features to be evaluated by the expressions in this query.- Returns:
- type resulting from expressions evaluation (never null).
- Throws:
IllegalArgumentException
- if this method can operate only on some feature types and the given type is not one of them.IllegalArgumentException
- if this method cannot determine the result type of an expression in this query. It may be because that expression is backed by an unsupported implementation.
- If the expression is an instance of
-
clone
Returns a clone of this query. -
hashCode
public int hashCode()Returns a hash code value for this query. -
equals
Compares this query with the given object for equality. -
toString
Returns a textual representation of this query for debugging purposes. The default implementation returns a string that looks like an SQL Select query.
-