Class FeatureQuery

java.lang.Object
org.apache.sis.storage.Query
org.apache.sis.storage.FeatureQuery
All Implemented Interfaces:
Serializable, Cloneable

public class FeatureQuery extends Query implements Cloneable, Serializable
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 Classes
    Modifier and Type
    Class
    Description
    static class 
    An expression to be retrieved by a Query, together with the name to assign to it.
  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    private long
    The maximum number of feature instances contained in the FeatureSet.
    private javax.measure.Quantity<javax.measure.quantity.Length>
    Hint used by resources to optimize returned features.
    The properties to retrieve, or null 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.
    The expressions to use for sorting the feature instances.
    private static final long
    Sentinel limit value for queries of unlimited length.
  • Constructor Summary

    Constructors
    Constructor
    Description
    Creates a new query applying no filter.
  • Method Summary

    Modifier and Type
    Method
    Description
    Returns a clone of this query.
    boolean
    Compares this query with the given object for equality.
    protected FeatureSet
    Applies this query on the given feature set.
    (package private) final DefaultFeatureType
    Returns the type of values evaluated by this query when executed on features of the given type.
    Returns the maximum number of feature instances contained in the FeatureSet.
    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, or null if all properties shall be included in the query.
    Returns the filter for trimming feature instances.
    (package private) final SortBy<AbstractFeature>
    Returns the expressions to use for sorting the feature instances.
    int
    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 the FeatureSet.
    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, or null if all properties shall be included in the query.
    void
    Sets the properties to retrieve, or null 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
    Sets the expressions to use for sorting the feature instances.
    (package private) final void
    Sets the expressions to use for sorting the feature instances.
    void
    Removes any limit defined by setLimit(long).
    Returns a textual representation of this query for debugging purposes.

    Methods inherited from class java.lang.Object

    finalize, getClass, notify, notifyAll, wait, wait, wait
  • Field Details

  • Constructor Details

    • FeatureQuery

      public FeatureQuery()
      Creates a new query applying no filter.
  • Method Details

    • setProjection

      public void setProjection(String... properties)
      Sets the properties to retrieve by their names. This convenience method wraps the given names in ValueReference expressions without alias and delegates to setProjection(NamedExpression...).
      Specified by:
      setProjection in class Query
      Parameters:
      properties - properties to retrieve, or null to retrieve all properties.
      Throws:
      IllegalArgumentException - if a property is duplicated.
    • setProjection

      @SafeVarargs public final void setProjection(Expression<? super AbstractFeature,?>... properties)
      Sets the properties to retrieve, or null if all properties shall be included in the query. This convenience method wraps the given expression in FeatureQuery.NamedExpressions without alias and delegates to setProjection(NamedExpression...).
      Parameters:
      properties - properties to retrieve, or null to retrieve all properties.
      Throws:
      IllegalArgumentException - if a property is duplicated.
    • setProjection

      public void setProjection(FeatureQuery.NamedExpression... properties)
      Sets the properties to retrieve, or null 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, or null to retrieve all properties.
      Throws:
      IllegalArgumentException - if a property or an alias is duplicated.
    • getProjection

      public FeatureQuery.NamedExpression[] getProjection()
      Returns the properties to retrieve, or null if all properties shall be included in the query. This is the expressions specified in the last call to setProjection(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 class Query
      Parameters:
      domain - the approximate area of interest, or null if none.
    • setSelection

      public void setSelection(Filter<? super AbstractFeature> selection)
      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, or null if none.
    • getSelection

      public Filter<? super AbstractFeature> getSelection()
      Returns the filter for trimming feature instances. This is the value specified in the last call to setSelection(Filter). The default value is null, 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 to setOffset(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 by setLimit(long).
    • setLimit

      public void setLimit(long limit)
      Set the maximum number of feature instances contained in the FeatureSet. 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.
    • getLimit

      public OptionalLong getLimit()
      Returns the maximum number of feature instances contained in the FeatureSet. This is the value specified in the last call to setLimit(long).
      Returns:
      maximum number of feature instances contained in the FeatureSet, or empty if none.
    • setSortBy

      @SafeVarargs final void setSortBy(SortProperty<AbstractFeature>... properties)
      Sets the expressions to use for sorting the feature instances. SortBy objects are used to order the Feature instances returned by the FeatureSet. SortBy clauses are applied in declaration order, like SQL.
      Parameters:
      properties - expressions to use for sorting the feature instances, or null or an empty array if none.
    • setSortBy

      final void setSortBy(SortBy<AbstractFeature> sortBy)
      Sets the expressions to use for sorting the feature instances. SortBy objects are used to order the Feature instances returned by the FeatureSet.
      Parameters:
      sortBy - expressions to use for sorting the feature instances, or null if none.
    • getSortBy

      final SortBy<AbstractFeature> getSortBy()
      Returns the expressions to use for sorting the feature instances. This is the value specified in the last call to setSortBy(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, or null for full resolution.
    • getLinearResolution

      public javax.measure.Quantity<javax.measure.quantity.Length> getLinearResolution()
      Returns the desired spatial resolution of geometries. A null value means that data are queried at their full resolution.
      Returns:
      desired spatial resolution, or null for full resolution.
    • label

      private static String label(Expression<?,?> expression)
      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

      protected FeatureSet execute(FeatureSet source) throws DataStoreException
      Applies this query on the given feature set. This method is invoked by the default implementation of FeatureSet.subset(Query). The default implementation executes the query using the default Stream 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 by FeatureSet.subset(Query).

      The returned FeatureSet does not cache the resulting Feature instances; the query is processed on every call to the FeatureSet.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

      final DefaultFeatureType expectedType(DefaultFeatureType valueType)
      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.
    • clone

      public FeatureQuery clone()
      Returns a clone of this query.
      Overrides:
      clone in class Object
      Returns:
      a clone of this query.
    • hashCode

      public int hashCode()
      Returns a hash code value for this query.
      Overrides:
      hashCode in class Object
      Returns:
      a hash value for this query.
    • equals

      public boolean equals(Object obj)
      Compares this query with the given object for equality.
      Overrides:
      equals in class Object
      Parameters:
      obj - the object to compare with this query.
      Returns:
      whether the two objects are equal.
    • toString

      public String toString()
      Returns a textual representation of this query for debugging purposes. The default implementation returns a string that looks like an SQL Select query.
      Overrides:
      toString in class Object
      Returns:
      textual representation of this query.