## org.opengis.coverage.grid
Interface GridCoverageReader

Deprecated. In favor of migrating to ISO 19123 definition for Coverage.

    public interface GridCoverageReader

Support for reading grid coverages out of a persisten store. Instance of `GridCoverageReader` are obtained through a call to `GridCoverageExchange.getReader(java.lang.Object)`. Grid coverages are usually read from the input stream in a sequential order.

WARNING: THIS CLASS WILL CHANGE. Current API is derived from OGC Grid Coverages Implementation specification 1.0. We plan to replace it by new interfaces derived from ISO 19123 (Schema for coverage geometry and functions). Current interfaces should be considered as legacy and are included in this distribution only because they were part of GeoAPI 1.0 release. We will try to preserve as much compatibility as possible, but no migration plan has been determined yet.

Since:
  GeoAPI 2.0
See Also:
  `GridCoverageExchange.getReader(java.lang.Object)`, `ImageReader`

Method Summary
`void` `dispose()` Deprecated. Allows any resources held by this object to be released.
`String` `getCurrentSubname()` Deprecated. Returns the name for the next grid coverage to be read from the input source.
`Format` `getFormat()` Deprecated. Returns the format handled by this `GridCoverageReader`.
`String[]` `getMetadataNames()` Deprecated. Returns the list of metadata keywords associated with the input source as a whole (not associated with any particular grid coverage).
`String` `getMetadataValue(String name)` Deprecated. Retrieve the metadata value for a given metadata name.
`Object` `getSource()` Deprecated. Returns the input source.
`boolean` `hasMoreGridCoverages()` Deprecated. Returns `true` if there is at least one more grid coverage available on the stream.
`String[]` `listSubNames()` Deprecated. Retrieve the list of grid coverages contained within the input source.
`GridCoverage` `read(GeneralParameterValue[] parameters)` Deprecated. Read the grid coverage from the current stream position, and move to the next grid coverage.
`void` `skip()` Deprecated. Skip the current grid coverage without reading it, and move the stream position to the next grid coverage.

Method Detail

### getFormat

    Format getFormat()

  Deprecated.
  Returns the format handled by this `GridCoverageReader`.

### getSource

    Object getSource()

  Deprecated.
  Returns the input source. This is the object passed to the `GridCoverageExchange.getReader(java.lang.Object)` method. It can be a `String`, an `InputStream`, a `FileChannel`, whatever.

### getMetadataNames

    String[] getMetadataNames()
                              throws IOException

  Deprecated.
  Returns the list of metadata keywords associated with the input source as a whole (not associated with any particular grid coverage). If no metadata is available, the array will be empty.

  Returns:
    The list of metadata keywords for the input source.
  Throws:
    `IOException` - if an error occurs during reading.
  TODO:
    This javadoc may not apply thats well in the iterator scheme.

### getMetadataValue

    String getMetadataValue(String name)
                            throws IOException,
                                   MetadataNameNotFoundException

  Deprecated.
  Retrieve the metadata value for a given metadata name.

  Parameters:
    `name` - Metadata keyword for which to retrieve metadata.
  Returns:
    The metadata value for the given metadata name. Should be one of the name returned by `getMetadataNames()`.
  Throws:
    `IOException` - if an error occurs during reading.
    `MetadataNameNotFoundException` - if there is no value for the specified metadata name.
  TODO:
    This javadoc may not apply thats well in the iterator scheme.

### listSubNames

    String[] listSubNames()
                          throws IOException

  Deprecated.
  Retrieve the list of grid coverages contained within the input source. Each grid can have a different coordinate system, number of dimensions and grid geometry. For example, a HDF-EOS file (GRID.HDF) contains 6 grid coverages each having a different projection. An empty array will be returned if no sub names exist.

  Returns:
    The list of grid coverages contained within the input source.
  Throws:
    `IOException` - if an error occurs during reading.
  TODO:
    The javadoc should also be more explicit about hierarchical format. Should the names be returned as paths? Explain what to return if the GridCoverage are accessible by index only. A proposal is to name them "grid1", "grid2", etc.

### getCurrentSubname

    String getCurrentSubname()
                             throws IOException

  Deprecated.
  Returns the name for the next grid coverage to be read from the input source.

  Throws:
    `IOException` - if an error occurs during reading.
  TODO:
    Do we need a special method for that, or should it be a metadata?

### hasMoreGridCoverages

    boolean hasMoreGridCoverages()
                                 throws IOException

  Deprecated.
  Returns `true` if there is at least one more grid coverage available on the stream.

  Throws:
    `IOException`

### read

    GridCoverage read(GeneralParameterValue[] parameters)
                      throws IllegalArgumentException,
                             IOException

  Deprecated.
  Read the grid coverage from the current stream position, and move to the next grid coverage. The method `hasMoreGridCoverages()` should be invoked first in order to verify that a coverage is available.

  Parameters:
    `parameters` - An optional set of parameters. Should be any or all of the parameters returned by `Format.getReadParameters()`.
  Returns:
    A new grid coverage from the input source.
  Throws:
    `InvalidParameterNameException` - if a parameter in `parameters` doesn't have a recognized name.
    `InvalidParameterValueException` - if a parameter in `parameters` doesn't have a valid value.
    `ParameterNotFoundException` - if a parameter was required for the operation but was not provided in the `parameters` list.
    `CannotCreateGridCoverageException` - if the coverage can't be created for a logical reason (for example an unsupported format, or an inconsistency found in the data).
    `IOException` - if a read operation failed for some other input/output reason, including `FileNotFoundException` if no file with the given `name` can be found, or `IIOException` if an error was thrown by the underlying image library.
    `IllegalArgumentException`

### skip

    void skip()
              throws IOException

  Deprecated.
  Skip the current grid coverage without reading it, and move the stream position to the next grid coverage.

  Throws:
    `IOException` - if the operation failed.

### dispose

    void dispose()
                 throws IOException

  Deprecated.
  Allows any resources held by this object to be released. The result of calling any other method subsequent to a call to this method is undefined. It is important for applications to call this method when they know they will no longer be using this `GridCoverageReader`. Otherwise, the reader may continue to hold on to resources indefinitely.

  Throws:
    `IOException` - if an error occured while disposing resources (for example while closing a file).

Copyright © 1994-2008 Open Geospatial Consortium. All Rights Reserved.