Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

Code Block
public interface GridCoverageReader {
    /**
     * Returns the format handled by this {@code GridCoverageReader}.
     */
    Format getFormat();
    /**
     * Returns the input source. It can be a
     * {@link java.lang.String}, an {@link java.io.InputStream}, a
     * {@link java.nio.channels.FileChannel}, whatever.
     */
    Object getSource();
  void dispose() throws IOException;
  GridCoverage read(GeneralParameterValue[] parameters) throws IllegalArgumentException, IOException;
    /**
     * Returns the list of metadata keywords associated with the {@linkplain #getSource
     * input source} as a whole (not associated with any particular grid coverage).
     * If no metadata is available, the array will be empty.
     *
     * @return 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.
     */
    String[] getMetadataNames() throws IOException;
    
    /**
     * Returns the list of metadata keywords associated with a specific gridCoverage 
     * referred by name.
     * If no metadata is available, the array will be empty.
     *
     * @return 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.
     */
    String[] getMetadataNames(String coverageName) throws IOException;
    /**
     * Retrieve the metadata value for a given metadata name.
     *
     * @param  name Metadata keyword for which to retrieve metadata.
     * @return The metadata value for the given metadata name. Should be one of
     *         the name returned by {@link #getMetadataNames}.
     * @throws IOException if an error occurs during reading.
     *
     * @todo This javadoc may not apply thats well in the iterator scheme.
     */
    String getMetadataValue(String name) throws IOException;
    
    /**
@deprecated. No replacement for this method. */
  String getCurrentSubname(     * Retrieve the metadata value for a given metadata name for a specified coverage.
     *
     * @param  name Metadata keyword for which to retrieve metadata.
     * @return The metadata value for the given metadata name. Should be one of
     *         the name returned by {@link #getMetadataNames}.
     * @throws IOException if an error occurs during reading.
     *
     * @todo This javadoc may not apply thats well in the iterator scheme.
     */
    String getMetadataValue(String coverageName, String name) throws IOException;
    /**
     * Retrieve the list of grid coverages contained within the {@linkplain #getSource
     * 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.
     *
     * @return 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.
     * @deprecated use {@link #getGridCoverageNames()}
     */** @deprecated. No replacement for this method.  */
  boolean hasMoreGridCoverages
    String[] listSubNames() throws IOException;
    /**
     * Retrieve the list of coverages contained within the {@linkplain #getSource
     * 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.
     *
     * @return The list of grid coverages contained within the input source.
     * @throws IOException if an error occurs during reading.
     *
     */
    String[] getGridCoverageNames() throws IOException;
    /**
@deprecated. No replacement for this method.  */
  void skip     * Retrieve the number of coverages contained within the {@linkplain #getSource
     * input source}.
     *
     * @return The number of coverages contained within the input source.
     * @throws IOException if an error occurs during reading.
     *
     */
    int getGridCoverageCount() throws IOException;
    /**
     * Returns the name for the next grid coverage to be {@linkplain #read read} from the
     * {@linkplain #getSource 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?
     * 
     * @deprecated no replacement for that.
use getGridCoverageNames    */
    String[] listSubNamesgetCurrentSubname() throws IOException;
   int getGridCoverageCount();
  String[] getGridCoverageNames();

  String[] getMetadataNames(String coverageName) throws IOException;
  String getMetadataValue(String coverageName, String name) throws IOException;
    /**
     * Returns {@code true} if there is at least one more grid coverage
     * available on the stream.
     * 
     * @deprecated no replacement for that.
     */
    boolean hasMoreGridCoverages() throws IOException;
    /**
     * Read the only available grid coverage. Use {@link #read(String, GeneralParameterValue[])}
     * in case of multiple grid coverages available.
     *
     * @param  parameters An optional set of parameters. Should be any or all of the
     *         parameters returned by {@link Format#getReadParameters}.
     * @return A new {@linkplain GridCoverage grid coverage} from the input source.
     * @throws InvalidParameterNameException if a parameter in {@code parameters}
     *         doesn't have a recognized name.
     * @throws InvalidParameterValueException if a parameter in {@code parameters}
     *         doesn't have a valid value.
     * @throws ParameterNotFoundException if a parameter was required for the operation but was
     *         not provided in the {@code parameters} list.
     * @throws CannotCreateGridCoverageException if the coverage can't be created for a logical
     *         reason (for example an unsupported format, or an inconsistency found in the data).
     * @throws IOException if a read operation failed for some other input/output reason, including
     *         {@link FileNotFoundException} if no file with the given {@code name} can be
     *         found, or {@link javax.imageio.IIOException} if an error was thrown by the
     *         underlying image library.
     */
    GridCoverage read(GeneralParameterValue[] parameters)
            throws IllegalArgumentException, IOException;
    
    
    /**
     * Read the grid coverage specified by coverageName parameter.
     *
     * @param  parameters An optional set of parameters. Should be any or all of the
     *         parameters returned by {@link Format#getReadParameters}.
     * @return A new {@linkplain GridCoverage grid coverage} from the input source.
     * @throws InvalidParameterNameException if a parameter in {@code parameters}
     *         doesn't have a recognized name.
     * @throws InvalidParameterValueException if a parameter in {@code parameters}
     *         doesn't have a valid value.
     * @throws ParameterNotFoundException if a parameter was required for the operation but was
     *         not provided in the {@code parameters} list.
     * @throws CannotCreateGridCoverageException if the coverage can't be created for a logical
     *         reason (for example an unsupported format, or an inconsistency found in the data).
     * @throws IOException if a read operation failed for some other input/output reason, including
     *         {@link FileNotFoundException} if no file with the given {@code name} can be
     *         found, or {@link javax.imageio.IIOException} if an error was thrown by the
     *         underlying image library.
     */
    GridCoverage read(String coverageName, GeneralParameterValue[] parameters)
            throws IllegalArgumentException, IOException;
  }
   /**
     * Skip the current grid coverage without reading it, and move the stream position to
     * the next grid coverage.
     *
     * @throws IOException if the operation failed.
     * @deprecated no replacement for that.
     */
    void skip() throws 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 {@code 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).
     */
    void dispose() throws IOException;
}

GridCoverage2DReader (new interface extending GridCoverageReader)

Code Block
public interface GridCoverage2DReader extends GridCoverageReader {
    /**
     * The time domain (comma separated list of values)
     */
    public static final String TIME_DOMAIN = "TIME_DOMAIN";
    /**
     * Time domain resolution (when using min/max/resolution)
     */
    public static final String TIME_DOMAIN_RESOLUTION = "TIME_DOMAIN_RESOLUTION";
    /**
     * If the time domain is available (or if a min/max/resolution approach has been chosen)
     */
    public static final String HAS_TIME_DOMAIN = "HAS_TIME_DOMAIN";
    /**
     * The time domain max value
     */
    public static final String TIME_DOMAIN_MAXIMUM = "TIME_DOMAIN_MAXIMUM";
    /**
     * The time domain min value
     */
    public static final String TIME_DOMAIN_MINIMUM = "TIME_DOMAIN_MINIMUM";
    /**
     * Whether the elevation is expressed as a full domain or min/max/resolution (true if domain
     * list available)
     */
    public static final String HAS_ELEVATION_DOMAIN = "HAS_ELEVATION_DOMAIN";
    /**
     * Elevation domain (comma separated list of values)
     */
    public static final String ELEVATION_DOMAIN = "ELEVATION_DOMAIN";
    /**
     * Elevation domain maximum value
     */
    public static final String ELEVATION_DOMAIN_MAXIMUM = "ELEVATION_DOMAIN_MAXIMUM";
    /**
     * Elevation domain minimum value
     */
    public static final String ELEVATION_DOMAIN_MINIMUM = "ELEVATION_DOMAIN_MINIMUM";
    /**
     * Elevation domain resolution
     */
    public static final String ELEVATION_DOMAIN_RESOLUTION = "ELEVATION_DOMAIN_RESOLUTION";
    /**
     * If a coverage has this property is means it been read straight out of a file without 
     * any sub-setting, it means the coverage represents the full contents of the file.
     * This can be used for different types of optimizations, such as avoiding reading
     * and re-encoding the original file when the original file would do.
     */
    public static final String FILE_SOURCE_PROPERTY = "OriginalFileSource";
    
    /**
     * Return the original {@link GeneralEnvelope} for the default coverage served by the underlying store.
     * 
     * @return the original {@link GeneralEnvelope} for the default coverage served by the underlying store.
     */
    GeneralEnvelope getOriginalEnvelope();
    /**
     * Return the original {@link GeneralEnvelope} for the specified coverageName.
     * 
     * @param coverageName the name of the coverage to work on.
     * @return the original {@link GeneralEnvelope} for the specified coverageName.
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     * @throws IllegalArgumentException if the specified coverageName does not exist
     */
    GeneralEnvelope getOriginalEnvelope(String coverageName);
    /**
     * Retrieves the {@link CoordinateReferenceSystem} associated to the default coverage for this {@link GridCoverage2DReader}.
     * 
     * <p>
     * @return the {@link CoordinateReferenceSystem} mapped to the specified coverageName, or {@code null} if the provided coverageName does not map
     *         to a real coverage.
     * 
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     */
    CoordinateReferenceSystem getCoordinateReferenceSystem();
    /**
     * Retrieves the {@link CoordinateReferenceSystem} associated to this {@link GridCoverage2DReader} for the specified coverageName.
     * 
     * <p>
     * @return the {@link CoordinateReferenceSystem} mapped to the specified coverageName
     * 
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     * @throws IllegalArgumentException if the specified coverageName does not exist
     */
    CoordinateReferenceSystem getCoordinateReferenceSystem(String coverageName);
    /**
     * Retrieves the {@link GridEnvelope} associated to the default coverage for this {@link GridCoverage2DReader}.
     * <p>
     * The {@link GridEnvelope} describes the raster area (in pixels) covered by the coverage.
     * 
     * <p>
     * @return the {@link CoordinateReferenceSystem} mapped to the default coverageName
     */
    GridEnvelope getOriginalGridRange();
    /**
     * Retrieves the {@link GridEnvelope} associated to the specified coverageName for this {@link GridCoverage2DReader}.
     * <p>
     * The {@link GridEnvelope} describes the raster area (in pixels) covered by the coverage.
     * 
     * @param coverageName the name of the coverage to work with
     * @return the {@link GridEnvelope} mapped to the specified coverageName
     * 
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     * @throws IllegalArgumentException if the specified coverageName does not exist
     */
    GridEnvelope getOriginalGridRange(String coverageName);
    MathTransform  /**
     * Retrieves the {@link MathTransform} associated to the default coverage for this {@link GridCoverage2DReader}.
     * 
     * <p>
     * @return the {@link CoordinateReferenceSystem} mapped to the default coverageName
     */
    MathTransform getOriginalGridToWorld(PixelInCell pixInCell);
    /**
     * Retrieves the {@link MathTransform} associated to the requested coverageName for this {@link GridCoverage2DReader}.
     * 
     * @param coverageName the name of the coverage to work with
     * @return the {@link MathTransform} mapped to the specified coverageName
     * 
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     * @throws IllegalArgumentException if the specified coverageName does not exist
     */
    MathTransform getOriginalGridToWorld(String coverageName, PixelInCell pixInCell);
    /**
     * Created a {@link GridCoverage2D} out of this {@link GridCoverage2DReader} for the default coverage.
     * 
     * @param parameters an array of {@link GeneralParameterValue} that uses a subset of the available read params for this
     *        {@link GridCoverage2DReader} as specified by the {@link Format}
     * @return a {@link GridCoverage2D} for the underlying default coverage for this {@link GridCoverage2DReader} or <code>null</code> in case no
     *         {@link GridCoverage2D} can be read for the provided parameters.
     * @throws IOException in case an error happen during read time.
     */
    GridCoverage2D read(GeneralParameterValue[] parameters) throws IllegalArgumentException, IOException;
    /**
     * Retrieves the {@link GridEnvelope} associated to the specified coverageName for this {@link GridCoverage2DReader}.
     * 
     * @param coverageName the name of the coverage to work with
     * @param parameters an array of {@link GeneralParameterValue} that uses a subset of the available read params for this
     *        {@link GridCoverage2DReader} as specified by the {@link Format}
     * @return a {@link GridCoverage2D} for the underlying default coverage for this {@link GridCoverage2DReader} or <code>null</code> in case no
     *         {@link GridCoverage2D} can be read for the provided parameters.
     * 
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     * @throws IllegalArgumentException if the specified coverageName does not exist
     */
    GridCoverage2D read(String coverageName, GeneralParameterValue[] parameters) throws IllegalArgumentException, IOException;
    /**
     * Return the {@link Set} of dynamic read parameters supported by this {@link GridCoverage2DReader} for the default coverage.
     * 
     * @return the {@link Set} of dynamic read parameters supported by this {@link GridCoverage2DReader}.
     * @throws IOException in case an error occurs while creating the {@link Set} of dynamic parameters.
     */
    Set<ParameterDescriptor<List>> getDynamicParameters() throws IOException;
    /**
     * Return the {@link Set} of dynamic read parameters supported by this {@link GridCoverage2DReader} for the specified coverage.
     * 
     * @param coverageName the name of the coverage to work with
     * @return the {@link Set} of dynamic read parameters supported by this {@link GridCoverage2DReader}.
     * @throws IOException in case an error occurs while creating the {@link Set} of dynamic parameters.
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     * @throws IllegalArgumentException if the specified coverageName does not exist
     */
    Set<ParameterDescriptor<List>> getDynamicParameters(String coverageName) throws IOException;
    /**
     * Return the resolution of the overview which would be picked out for the provided requested resolution
     * using the provided {@link OverviewPolicy}. This method works on the default coverage for this {@link GridCoverage2DReader}.
     *  
     * @param policy the {@link OverviewPolicy} to use during evaluation.
     * @param requestedResolution the requested resolution 
     * @return an array of 2 double with the resolution of the selected overview.
     * @throws IOException in case an error occurs.
     */
    double[] getReadingResolutions(OverviewPolicy policy, double[] requestedResolution) throws IOException;
    /**
     * Return the resolution of the overview which would be picked out for the provided requested resolution
     * using the provided {@link OverviewPolicy}. This method works on the specified coverage for this {@link GridCoverage2DReader}.
     *  
     * @param coverageName the name of the coverage to work on.
     * @param policy the {@link OverviewPolicy} to use during evaluation.
     * @param requestedResolution the requested resolution 
     * @return an array of 2 double with the resolution of the selected overview.
     * @throws IOException in case an error occurs.
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     * @throws IllegalArgumentException if the specified coverageName does not exist
     */
    double[] getReadingResolutions(String coverageName, OverviewPolicy policy, double[] requestedResolution) throws IOException;
    /**
     * Number of predetermined overviews for the default coverage.
     * 
     * @return The number of predetermined overviews for the default coverage. Zero if none are available, -1 if infinite are available, otherwise a
     *         positive number.
     */
    int getNumOverviews();
    /**
     * Number of predetermined overviews for the specified coverage.
     * 
     * @param coverageName the name of the coverage for which we do want to get the number of overviews.
     * 
     * @return The number of predetermined overviews for the specified coverage. 0 if none are available, -1 if infinite are available, otherwise a
     *         positive number.
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     * @throws IllegalArgumentException if the specified coverageName does not exist
     */
    int getNumOverviews(String coverageName);
    /**
     * Retrieve the {@link ImageLayout} for the default coverage.
     * <p>
     * Throw an {@link IllegalArgumentException} in case the name is wrong and/or no such a coverage exists.
     * 
     * @return an {@link ImageLayout} that is useful for actually knowing the {@link ColorModel}, the {@link SampleModel} as well as the tile grid for
     *         the default coverage.
     */
    ImageLayout getImageLayout()throws IOException;
    /**
     * Retrieve the {@link ImageLayout} for the specified coverage.
     * <p>
     * Throw an {@link IllegalArgumentException} in case the name is wrong and/or no such a coverage exists.
     * 
     * @param coverageName the name of the coverage for which we want to know the {@link GridEnvelope}.
     * @return an {@link ImageLayout} that is useful for actually knowing the {@link ColorModel}, the {@link SampleModel} as well as the tile grid for
     *         a certain coverage.
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     * @throws IllegalArgumentException if the specified coverageName does not exist
     */
    ImageLayout getImageLayout(String coverageName)throws IOException;
    /**
     * Retrieve the resolution levels for the default coverage.
     * <p>
     * Throw an {@link IllegalArgumentException} in case the name is wrong and/or no such a coverage exists.
     * 
     * @return the resolution levels for the default coverage.
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     * @throws IllegalArgumentException if the specified coverageName does not exist
     */
    double[][] getResolutionLevels() throws IOException;
    /**
     * Retrieve the resolution levels for the specified coverage.
     * <p>
     * Throw an {@link IllegalArgumentException} in case the name is wrong and/or no such a coverage exists.
     * 
     * @param coverageName the name of the coverage for which we want to know the resolution levels.
     * @return the resolution levels for the specified coverage.
     * @throws NullPointerException if the specified coverageName is <code>null</code>
     * @throws IllegalArgumentException if the specified coverageName does not exist
     */
    double[][] getResolutionLevels(String coverageName) throws IOException;

}

Default implementation changes

...