# Interface Tile

public interface Tile
A small hyper-rectangular representation of data which is part of a tiling scheme. A tile is uniquely defined in a tile matrix by an integer index in each dimension. Tiles can be a coverage subsets, or a feature based representation (e.g. vector tiles).

All methods in this interface return non-null values.

Since:
  1.2
See Also:
  - `TileMatrix​.getTiles(GridExtent, boolean)`

- ## Method Summary

  Modifier and Type
  Method
  Description
  `default Optional<Path>`
  `getContentPath()`
  Returns a path to the tile content as a file or a BLOB.
  `long[]`
  `getIndices()`
  Returns the indices of this tile in the `TileMatrix`.
  `default Optional<Metadata>`
  `getMetadata()`
  Returns information about this tile.
  `Resource`
  `getResource()`
  Returns the tile content as a resource.
  `TileStatus`
  `getStatus()`
  Returns information about whether the tile failed to load.

- ## Method Details

  - ### getIndices

    long[] getIndices()
    Returns the indices of this tile in the `TileMatrix`. If this tile was obtained by a call to `TileMatrix​.getTile(long...)`, then the returned array contains the indices that were given in that call.

    The returned array contains coordinates in the space defined by the extent of the tiling scheme. As such, it complies with the following constraints:

    - The array length is equal to `GridExtent​.getDimension()`.
    - The axis order — usually (column, row/) — is the extent axis order.
    - Values are between the extent low and high values, inclusive.
    Returns:
      indices of this tile in the `TileMatrix`, as coordinates inside the matrix `GridExtent`.
    See Also:
      - `TileMatrix​.getTile(long...)`

  - ### getMetadata

    default Optional<Metadata> getMetadata()
    Returns information about this tile. The returned metadata may differ from the tile resource metadata. For example, it may be a subset containing only the information available without reading the resource. The tile metadata may be absent if it does not contain any information that are not already provided by the `TileMatrix` or `TileMatrixSet` metadata.
    Returns:
      information about this tile.
    Since:
      1.5
    See Also:
      - `Resource​.getMetadata()`

  - ### getStatus

    TileStatus getStatus()
    Returns information about whether the tile failed to load. The return value can be `TileStatus​.EXISTS` or `TileStatus​.IN_ERROR`; other enumeration values should not happen after a user successfully obtained this `Tile` instance.

    #### State transition

    `TileStatus​.EXISTS` is not a guarantee that a call to `getResource()` will succeed. The error may be detected only during the first attempt to read the resource. Consequently, this method may initially return `EXISTS`, then return `IN_ERROR` later after the first read attempt.
    Returns:
      information about the availability of this tile.
    See Also:
      - `TileMatrix​.getTileStatus(long...)`

  - ### getResource

    Resource getResource() throws DataStoreException
    Returns the tile content as a resource. The resource type is typically `GridCoverageResource`, but it may also be other types (e.g. vector tiles).
    Returns:
      the tile content.
    Throws:
      `DataStoreException` - if an error occurred while reading the content.

  - ### getContentPath

    default Optional<Path> getContentPath() throws DataStoreException
    Returns a path to the tile content as a file or a BLOB. Tiles are usually small chunks of raw data which are forwarded to a displaying device or processing unit. Unlike the `getResource()` method, this method should return the unprocessed data quickly.

    The default implementation fallbacks on the `getResource()` method and returns the first path from the resource fileset.

    Returns:
      path to the tile content, or empty if none.
    Throws:
      `DataStoreException` - if an error occurred while returning the content.
    Since:
      1.5