Package org.apache.sis.storage

# Class CoverageQuery

Object
Query
CoverageQuery

All Implemented Interfaces:
  `Serializable`, `Cloneable`

public class CoverageQuery extends Query implements Cloneable, Serializable
Definition of filtering to apply for fetching a subset of `GridCoverageResource`. This query allows requesting a subset of the coverage domain and the range.

## Terminology

This class uses relational database terminology for consistency with generic queries:

- A selection is a filter choosing the cells or pixels to include in the subset. In this context, the selection is the coverage domain.
- A projection (not to be confused with map projection) is the set of sample values to keep. In this context, the projection is the coverage range (i.e. set of sample dimensions).

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

Defined in the `sis-storage` module

- ## Constructor Summary

  Constructors
  Constructor
  Description
  `CoverageQuery()`
  Creates a new query performing no filtering.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `CoverageQuery`
  `clone()`
  Returns a clone of this query.
  `boolean`
  `equals(Object obj)`
  Compares this query with the given object for equality.
  `int[]`
  `getProjection()`
  Returns the indices of samples dimensions to read, or `null` if there is no filtering on range.
  `GridGeometry`
  `getSelection()`
  Returns the desired grid extent and resolution.
  `int`
  `getSourceDomainExpansion()`
  Returns the number of additional cells to read on each border of the source grid coverage.
  `int`
  `hashCode()`
  Returns a hash code value for this query.
  `void`
  `setProjection(int... range)`
  Sets the indices of samples dimensions to read (the coverage range).
  `void`
  `setProjection(String... range)`
  Sets the sample dimensions to read by their names.
  `void`
  `setSelection(GridGeometry domain)`
  Sets the desired grid extent and resolution.
  `void`
  `setSelection(Envelope domain)`
  Sets the approximate area of cells or pixels to include in the subset.
  `void`
  `setSourceDomainExpansion(int margin)`
  Sets a number of additional cells to read on each border of the source grid coverage.
  `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

  - ### CoverageQuery

    public CoverageQuery()
    Creates a new query performing no filtering.

- ## Method Details

  - ### setSelection

    public void setSelection(Envelope domain)
    Sets the approximate area of cells or pixels to include in the subset. This convenience method creates a grid geometry containing only the given envelope. Note that the given envelope is approximate: Coverages may expand the envelope to an integer amount of tiles.
    Specified by:
      `setSelection` in class `Query`
    Parameters:
      `domain` - the approximate area of interest, or `null` if none.

  - ### setSelection

    public void setSelection(GridGeometry domain)
    Sets the desired grid extent and resolution. The given domain is approximate: Coverages may use a different resolution and expand the envelope to an integer amount of tiles.
    Parameters:
      `domain` - desired grid extent and resolution, or `null` for reading the whole domain.

  - ### getSelection

    public GridGeometry getSelection()
    Returns the desired grid extent and resolution. This is the value set by the last call to `setSelection(GridGeometry)`.
    Note on terminology: "selection" is the generic term used in queries for designating a subset of feature instances. In a grid coverage, feature instances are cells or pixels. So this concept maps to the coverage domain.
    Returns:
      desired grid extent and resolution, or `null` for reading the whole domain.

  - ### setProjection

    public void setProjection(String... range)
    Sets the sample dimensions to read by their names.
    Specified by:
      `setProjection` in class `Query`
    Parameters:
      `range` - sample dimensions to retrieve, or `null` to retrieve all properties.
    Throws:
      `IllegalArgumentException` - if a sample dimension is duplicated.

  - ### setProjection

    public void setProjection(int... range)
    Sets the indices of samples dimensions to read (the coverage range). A `null` value means to read all sample dimensions (no filtering on range). If non-null, then the `range` array shall contain at least one element, all elements must be positive and no value can be duplicated.
    Parameters:
      `range` - 0-based indices of sample dimensions to read, or `null` for reading them all.
    Throws:
      `IllegalArgumentException` - if the given array is empty or contains negative or duplicated values.

  - ### getProjection

    public int[] getProjection()
    Returns the indices of samples dimensions to read, or `null` if there is no filtering on range. If non-null, the returned array shall never be empty.
    Note on terminology: "projection" (not to be confused with map projection) is the generic term used in queries for designating a subset of feature properties retained in each feature instances. In a coverage, this concept maps to the coverage range.
    Returns:
      0-based indices of sample dimensions to read, or `null` for reading them all.

  - ### setSourceDomainExpansion

    public void setSourceDomainExpansion(int margin)
    Sets a number of additional cells to read on each border of the source grid coverage. If non-zero, this property expands the `domain` to be read by the specified margin.

    #### Unit of measurement

    The parameter value is a number of cells in the `domain` argument specified in a read operation. If no `domain` is specified at read time, then this is a number of cells in the full image to be read from the resource. Cells are counted after subsampling, e.g. cells are twice bigger if a subsampling of 2 is applied. Those cells do not necessarily have the same size than the cells of the `domain of this query`.

    #### Use case

    At reading time it may be necessary to add a margin to the coverage extent. This margin is used when the user knows that an image processing operation will need to iterate over a little bit more data than the area of interest. For example the bilinear interpolation uses a 2×2 pixels window.
    Parameters:
      `margin` - read margin, which must be zero or positive.

  - ### getSourceDomainExpansion

    public int getSourceDomainExpansion()
    Returns the number of additional cells to read on each border of the source grid coverage. This is the value sets by the last call to `setSourceDomainExpansion(int)`.
    Returns:
      read margin, zero or positive.

  - ### clone

    public CoverageQuery 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.