Module org.apache.sis.storage
Package org.apache.sis.storage

# Class FeatureQuery

Object
Query
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 properties 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:
  - Serialized Form

- ## Nested Class Summary

  Nested Classes
  Modifier and Type
  Class
  Description
  `static class`
  `FeatureQuery​.NamedExpression`
  An expression to be retrieved by a `Query`, together with the name to assign to it.
  `static enum`
  `FeatureQuery​.ProjectionType`
  Whether a property evaluated by a query is computed on the fly or stored.

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `FeatureQuery()`
  Creates a new query applying no filter.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `FeatureQuery`
  `clone()`
  Returns a clone of this query.
  `boolean`
  `equals(Object obj)`
  Compares this query with the given object for equality.
  `protected FeatureSet`
  `execute(FeatureSet source)`
  Applies this query on the given feature set.
  `OptionalLong`
  `getLimit()`
  Returns the maximum number of feature instances contained in the `FeatureSet`.
  `Quantity<Length>`
  `getLinearResolution()`
  Returns the desired spatial resolution of geometries.
  `long`
  `getOffset()`
  Returns the number of feature instances to skip from the beginning.
  `FeatureQuery​.NamedExpression[]`
  `getProjection()`
  Returns the properties to retrieve, or `null` if all properties shall be included in the query.
  `Filter<? super AbstractFeature>`
  `getSelection()`
  Returns the filter for trimming feature instances.
  `int`
  `hashCode()`
  Returns a hash code value for this query.
  `void`
  `setLimit(long limit)`
  Set the maximum number of feature instances contained in the `FeatureSet`.
  `void`
  `setLinearResolution(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`
  `setProjection(FeatureQuery​.NamedExpression... properties)`
  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(Envelope domain)`
  Sets the approximate area of feature instances to include in the subset.
  `void`
  `setUnlimited()`
  Removes any limit defined by `setLimit(long)`.
  `String`
  `toString()`
  Returns a textual representation of this query for debugging purposes.

  ### Methods inherited from class Object

  `finalize, getClass, notify, notifyAll, wait, wait, wait`

- ## 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​.NamedExpression`s 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(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.

  - ### setLinearResolution

    public void setLinearResolution(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 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.

  - ### 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:
      - `FeatureSet​.subset(Query)`
      - `CoverageQuery​.execute(GridCoverageResource)`

  - ### 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.