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

# Enum Class RasterLoadingStrategy

Object
Enum<RasterLoadingStrategy>
RasterLoadingStrategy

All Implemented Interfaces:
  `Serializable`, `Comparable<RasterLoadingStrategy>`, `Constable`

public enum RasterLoadingStrategy extends Enum<RasterLoadingStrategy>
Time when the "physical" loading of raster data should happen. Some resource implementations may not load data immediately when the read method is invoked, but instead defer the actual loading until the image is rendered. This enumeration gives some control over the time when data loading happens. The different strategies are compromises between memory consumption, redundant loading of same data and early error detection.

Enumeration values are ordered from the most eager strategy to the laziest strategy. The eager strategy is fastest when all pixels are used, at the cost of largest memory consumption. The lazy strategy is more efficient when only a few tiles will be used and those tiles are not known in advance. The lazy strategy is also the only applicable one if the image is too large for holding in memory.

Since:
  1.1

- ## Nested Class Summary

  ## Nested classes/interfaces inherited from class Enum

  `Enum​.EnumDesc<E extends Enum<E>>`

- ## Enum Constant Summary

  Enum Constants
  Enum Constant
  Description
  `AT_GET_TILE_TIME`
  Raster data are loaded at `RenderedImage​.getTile(int, int)` invocation time.
  `AT_READ_TIME`
  Raster data are loaded at `GridCoverageResource​.read(GridGeometry, int...)` invocation time.
  `AT_RENDER_TIME`
  Raster data are loaded at `GridCoverage​.render(GridExtent)` invocation time.

- ## Method Summary

  Modifier and Type
  Method
  Description
  `static RasterLoadingStrategy`
  `valueOf(String name)`
  Returns the enum constant of this class with the specified name.
  `static RasterLoadingStrategy[]`
  `values()`
  Returns an array containing the constants of this enum class, in the order they are declared.

  ### Methods inherited from class Enum

  `clone, compareTo, describeConstable, equals, finalize, getDeclaringClass, hashCode, name, ordinal, toString, valueOf`

  ### Methods inherited from class Object

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

- ## Enum Constant Details

  - ### AT_READ_TIME

    public static final RasterLoadingStrategy AT_READ_TIME
    Raster data are loaded at `GridCoverageResource​.read(GridGeometry, int...)` invocation time. This is the most eager loading strategy.

    Advantages:

    - Fastest loading strategy if all pixels in the returned `GridCoverage` will be used.
    - No redundant data loading: all data stay in memory until the resource is garbage-collected.
    - Immediate error notification with a checked `DataStoreException`.

    Disadvantages:

    - Slower than other strategies if only a subset of the returned `GridCoverage` will be used.
    - Consume memory for the full `GridCoverage` as long as the resource is referenced.

  - ### AT_RENDER_TIME

    public static final RasterLoadingStrategy AT_RENDER_TIME
    Raster data are loaded at `GridCoverage​.render(GridExtent)` invocation time. Speed and memory usage are at an intermediate level between `AT_READ_TIME` and `AT_GET_TILE_TIME`.

    Advantages:

    - Faster than `AT_GET_TILE_TIME` if all pixels in the returned `RenderedImage` will be used.
    - Load less data than `AT_READ_TIME` if the `GridExtent` is a sub-region of the coverage.
    - Memory is released sooner (when the `RenderedImage` is garbage-collected) than above mode.

    Disadvantages:

    - Slower than `AT_GET_TILE_TIME` if only a few tiles will be used.
    - Consume memory for the full `RenderedImage` as long as the image is referenced.
    - May reload the same data many times if images are discarded and recreated.
    - Unchecked `CannotEvaluateException` can happen relatively late (at `render(…)` invocation time) in a chain of coverage operations.

  - ### AT_GET_TILE_TIME

    public static final RasterLoadingStrategy AT_GET_TILE_TIME
    Raster data are loaded at `RenderedImage​.getTile(int, int)` invocation time. This is the laziest loading strategy. This is also the only strategy that can handle very large `RenderedImage`s.

    Advantages:

    - Only the tiles that are actually used are loaded.
    - Memory can be released at any time (tiles are kept by soft references).

    Disadvantages:

    - Slower read operations (numerous seeks when tiles are read in random order).
    - May reload the same data many times if tiles are discarded and recreated.
    - Unchecked `ImagingOpException` can happen late (at `getTile(…)` invocation time) in a chain of image operations.

- ## Method Details

  - ### values

    public static RasterLoadingStrategy[] values()
    Returns an array containing the constants of this enum class, in the order they are declared.
    Returns:
      an array containing the constants of this enum class, in the order they are declared

  - ### valueOf

    public static RasterLoadingStrategy valueOf(String name)
    Returns the enum constant of this class with the specified name. The string must match exactly an identifier used to declare an enum constant in this class. (Extraneous whitespace characters are not permitted.)
    Parameters:
      `name` - the name of the enum constant to be returned.
    Returns:
      the enum constant with the specified name
    Throws:
      `IllegalArgumentException` - if this enum class has no constant with the specified name
      `NullPointerException` - if the argument is null