deegree 2.5 (2011/06/29 09:44 build-8-official)

org.deegree.model.coverage.grid
Interface GridCoverageReader

All Known Implementing Classes:
AbstractGridCoverageReader, CompoundGridCoverageReader, GeoTIFFGridCoverageReader, ImageGridCoverageReader, OracleGeoRasterGridCoverageReader, RawDataReader

public interface GridCoverageReader

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

Version:
2.0
Author:
OpenGIS® consortium
See Also:
GridCoverageExchange.getReader(Object), ImageReader

Method Summary
 void dispose()
          Allows any resources held by this object to be released.
 java.lang.String getCurrentSubname()
           
 Format getFormat()
           
 java.lang.String[] getMetadataNames()
          Returns the list of metadata keywords associated with the input source as a whole (not associated with any particular grid coverage).
 java.lang.String getMetadataValue(java.lang.String name)
          Retrieve the metadata value for a given metadata name.
 java.lang.Object getSource()
           
 java.lang.String[] listSubNames()
          Retrieve the list of grid coverages contained within the input source.
 GridCoverage read(GeneralParameterValueIm[] parameters)
          Read the grid coverage from the current stream position, and move to the next grid coverage.
 void setCurrentSubname(java.lang.String name)
           
 void setMetadataValue(java.lang.String name, java.lang.String value)
          Sets the metadata value for a given metadata name.
 

Method Detail

getFormat

Format getFormat()
Returns:
the format handled by this GridCoverageReader.

getSource

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

getMetadataNames

java.lang.String[] getMetadataNames()
                                    throws java.io.IOException
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:
java.io.IOException - if an error occurs during reading.
revisit
This javadoc may not apply thats well in the iterator scheme.

getMetadataValue

java.lang.String getMetadataValue(java.lang.String name)
                                  throws java.io.IOException,
                                         MetadataNameNotFoundException
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:
java.io.IOException - if an error occurs during reading.
MetadataNameNotFoundException - if there is no value for the specified metadata name.
revisit
This javadoc may not apply thats well in the iterator scheme.

setMetadataValue

void setMetadataValue(java.lang.String name,
                      java.lang.String value)
                      throws java.io.IOException,
                             MetadataNameNotFoundException
Sets the metadata value for a given metadata name.

Parameters:
name - Metadata keyword for which to set the metadata.
value - The metadata value for the given metadata name.
Throws:
java.io.IOException - if an error occurs during writing.
MetadataNameNotFoundException - if the specified metadata name is not handled for this format.
revisit
This javadoc may not apply thats well in the iterator scheme.

setCurrentSubname

void setCurrentSubname(java.lang.String name)
                       throws java.io.IOException
Parameters:
name - for the next grid coverage to read within the input . The subname can been fetch later at reading time.
Throws:
java.io.IOException - if an error occurs during writing.
revisit
Do we need a special method for that, or should it be a metadata?

listSubNames

java.lang.String[] listSubNames()
                                throws java.io.IOException
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:
java.io.IOException - if an error occurs during reading.
revisit
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

java.lang.String getCurrentSubname()
                                   throws java.io.IOException
Returns:
the name for the next grid coverage to be read from the input source.
Throws:
java.io.IOException - if an error occurs during reading.
revisit
Do we need a special method for that, or should it be a metadata?

read

GridCoverage read(GeneralParameterValueIm[] parameters)
                  throws InvalidParameterNameException,
                         InvalidParameterValueException,
                         ParameterNotFoundException,
                         java.io.IOException
Read the grid coverage from the current stream position, and move to the next grid coverage.

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).
java.io.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.

dispose

void dispose()
             throws java.io.IOException
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:
java.io.IOException - if an error occured while disposing resources (for example while closing a file).

deegree 2.5 (2011/06/29 09:44 build-8-official)

an open source project founded by lat/lon, Bonn, Germany.
For more information visit: http://www.deegree.org