Package org.apache.sis.storage
Class 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
- See Also:
Defined in the sis-storage module
- 
Nested Class SummaryNested ClassesModifier and TypeClassDescriptionstatic classAn expression to be retrieved by aQuery, together with the name to assign to it.
- 
Constructor SummaryConstructors
- 
Method SummaryModifier and TypeMethodDescriptionclone()Returns a clone of this query.booleanCompares this query with the given object for equality.protected FeatureSetexecute(FeatureSet source) Applies this query on the given feature set.Returns the maximum number of feature instances contained in theFeatureSet.Returns the desired spatial resolution of geometries.longReturns the number of feature instances to skip from the beginning.Returns the properties to retrieve, ornullif all properties shall be included in the query.Filter<? super AbstractFeature>Returns the filter for trimming feature instances.intReturns a hash code value for this query.voidsetLimit(long limit) Set the maximum number of feature instances contained in theFeatureSet.voidsetLinearResolution(Quantity<Length> linearResolution) Sets the desired spatial resolution of geometries.voidsetOffset(long skip) Sets the number of feature instances to skip from the beginning.voidsetProjection(String... properties) Sets the properties to retrieve by their names.final voidsetProjection(Expression<? super AbstractFeature, ?>... properties) Sets the properties to retrieve, ornullif all properties shall be included in the query.voidsetProjection(FeatureQuery.NamedExpression... properties) Sets the properties to retrieve, ornullif all properties shall be included in the query.voidsetSelection(Filter<? super AbstractFeature> selection) Sets a filter for trimming feature instances.voidsetSelection(Envelope domain) Sets the approximate area of feature instances to include in the subset.voidRemoves any limit defined bysetLimit(long).Returns a textual representation of this query for debugging purposes.
- 
Constructor Details- 
FeatureQuerypublic FeatureQuery()Creates a new query applying no filter.
 
- 
- 
Method Details- 
setProjectionSets the properties to retrieve by their names. This convenience method wraps the given names inValueReferenceexpressions without alias and delegates tosetProjection(NamedExpression...).- Specified by:
- setProjectionin class- Query
- Parameters:
- properties- properties to retrieve, or- nullto retrieve all properties.
- Throws:
- IllegalArgumentException- if a property is duplicated.
 
- 
setProjectionSets the properties to retrieve, ornullif all properties shall be included in the query. This convenience method wraps the given expression inFeatureQuery.NamedExpressions without alias and delegates tosetProjection(NamedExpression...).- Parameters:
- properties- properties to retrieve, or- nullto retrieve all properties.
- Throws:
- IllegalArgumentException- if a property is duplicated.
 
- 
setProjectionSets the properties to retrieve, ornullif 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 SELECTclause of a SQL statement. Subset of columns is called projection in relational database terminology.- Parameters:
- properties- properties to retrieve, or- nullto retrieve all properties.
- Throws:
- IllegalArgumentException- if a property or an alias is duplicated.
 
- 
getProjectionReturns the properties to retrieve, ornullif 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 nullto retrieve all feature properties.
 
- 
setSelectionSets 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:
- setSelectionin class- Query
- Parameters:
- domain- the approximate area of interest, or- nullif none.
 
- 
setSelectionSets 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, or- nullif none.
 
- 
getSelectionReturns 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 nullif none.
 
- 
setOffsetpublic 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.
 
- 
getOffsetpublic 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.
 
- 
setUnlimitedpublic void setUnlimited()Removes any limit defined bysetLimit(long).
- 
setLimitpublic 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 the- FeatureSet.
 
- 
getLimitReturns 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.
 
- 
setLinearResolutionSets the desired spatial resolution of geometries. This property is an optional hint; resources may ignore it.- Parameters:
- linearResolution- desired spatial resolution, or- nullfor full resolution.
 
- 
getLinearResolutionReturns the desired spatial resolution of geometries. Anullvalue means that data are queried at their full resolution.- Returns:
- desired spatial resolution, or nullfor full resolution.
 
- 
executeApplies 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 defaultStreammethods. 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 FeatureSetdoes not cache the resultingFeatureinstances; 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:
 
- 
cloneReturns a clone of this query.
- 
hashCodepublic int hashCode()Returns a hash code value for this query.
- 
equalsCompares this query with the given object for equality.
- 
toStringReturns a textual representation of this query for debugging purposes. The default implementation returns a string that looks like an SQL Select query.
 
-