    001    //$HeadURL: https://svn.wald.intevation.org/svn/deegree/base/branches/2.4_testing/src/org/deegree/model/coverage/grid/GridCoverageReader.java $
    002    /*----------------------------------------------------------------------------
    003     This file originated as a part of GeoAPI.
    004
    005     GeoAPI is free software. GeoAPI may be used, modified and
    006     redistributed by anyone for any purpose requring only maintaining the
    007     copyright and license terms on the source code and derivative files.
    008     See the OGC legal page for details.
    009
    010     The copyright to the GeoAPI interfaces is held by the Open Geospatial
    011     Consortium, see http://www.opengeospatial.org/ogc/legal
    012    ----------------------------------------------------------------------------*/
    013    package org.deegree.model.coverage.grid;
    014
    015    import java.io.IOException;
    016
    017    import org.deegree.datatypes.parameter.GeneralParameterValueIm;
    018    import org.deegree.datatypes.parameter.InvalidParameterNameException;
    019    import org.deegree.datatypes.parameter.InvalidParameterValueException;
    020    import org.deegree.datatypes.parameter.ParameterNotFoundException;
    021
    022    /**
    023     * Support for reading grid coverages out of a persisten store. Instance of
    024     * <code>GridCoverageReader</code> are obtained through a call to
    025     * {@link GridCoverageExchange#getReader(Object)}. Grid coverages are usually read from the input
    026     * stream in a sequential order.
    027     *
    028     * @author <A HREF="http://www.opengis.org">OpenGIS&reg; consortium</A>
    029     * @version 2.0
    030     *
    031     * @see GridCoverageExchange#getReader(Object)
    032     * @see javax.imageio.ImageReader
    033     */
    034    public interface GridCoverageReader {
    035        /**
    036         * @return the format handled by this <code>GridCoverageReader</code>.
    037         */
    038        Format getFormat();
    039
    040        /**
    041         * @return the input source. This is the object passed to the
    042         *         {@link GridCoverageExchange#getReader(Object)} method. It can be a
    043         *         {@link java.lang.String}, an {@link java.io.InputStream}, a
    044         *         {@link java.nio.channels.FileChannel}, whatever.
    045         */
    046        Object getSource();
    047
    048        /**
    049         * Returns the list of metadata keywords associated with the {@linkplain #getSource input
    050         * source} as a whole (not associated with any particular grid coverage). If no metadata is
    051         * available, the array will be empty.
    052         *
    053         * @return The list of metadata keywords for the input source.
    054         * @throws IOException
    055         *             if an error occurs during reading.
    056         *
    057         * @revisit This javadoc may not apply thats well in the iterator scheme.
    058         */
    059        String[] getMetadataNames()
    060                                throws IOException;
    061
    062        /**
    063         * Retrieve the metadata value for a given metadata name.
    064         *
    065         * @param name
    066         *            Metadata keyword for which to retrieve metadata.
    067         * @return The metadata value for the given metadata name. Should be one of the name returned by
    068         *         {@link #getMetadataNames}.
    069         * @throws IOException
    070         *             if an error occurs during reading.
    071         * @throws MetadataNameNotFoundException
    072         *             if there is no value for the specified metadata name.
    073         *
    074         * @revisit This javadoc may not apply thats well in the iterator scheme.
    075         */
    076        String getMetadataValue( String name )
    077                                throws IOException, MetadataNameNotFoundException;
    078
    079        /**
    080         * Sets the metadata value for a given metadata name.
    081         *
    082         * @param name
    083         *            Metadata keyword for which to set the metadata.
    084         * @param value
    085         *            The metadata value for the given metadata name.
    086         * @throws IOException
    087         *             if an error occurs during writing.
    088         * @throws MetadataNameNotFoundException
    089         *             if the specified metadata name is not handled for this format.
    090         *
    091         * @revisit This javadoc may not apply thats well in the iterator scheme.
    092         */
    093        void setMetadataValue( String name, String value )
    094                                throws IOException, MetadataNameNotFoundException;
    095
    096        /**
    097         * @param name
    098         *            for the next grid coverage to {@linkplain #read read} within the
    099         *            {@linkplain #getSource() input }. The subname can been fetch later at reading
    100         *            time.
    101         *
    102         * @throws IOException
    103         *             if an error occurs during writing.
    104         * @revisit Do we need a special method for that, or should it be a metadata?
    105         */
    106        void setCurrentSubname( String name )
    107                                throws IOException;
    108
    109        /**
    110         * Retrieve the list of grid coverages contained within the {@linkplain #getSource input
    111         * source}. Each grid can have a different coordinate system, number of dimensions and grid
    112         * geometry. For example, a HDF-EOS file (GRID.HDF) contains 6 grid coverages each having a
    113         * different projection. An empty array will be returned if no sub names exist.
    114         *
    115         * @return The list of grid coverages contained within the input source.
    116         * @throws IOException
    117         *             if an error occurs during reading.
    118         *
    119         * @revisit The javadoc should also be more explicit about hierarchical format. Should the names
    120         *          be returned as paths? Explain what to return if the GridCoverage are accessible by
    121         *          index only. A proposal is to name them "grid1", "grid2", etc.
    122         */
    123        String[] listSubNames()
    124                                throws IOException;
    125
    126        /**
    127         * @return the name for the next grid coverage to be {@linkplain #read read} from the
    128         *         {@linkplain #getSource input source}.
    129         *
    130         * @throws IOException
    131         *             if an error occurs during reading.
    132         * @revisit Do we need a special method for that, or should it be a metadata?
    133         */
    134        String getCurrentSubname()
    135                                throws IOException;
    136
    137        /**
    138         * Read the grid coverage from the current stream position, and move to the next grid coverage.
    139         *
    140         * @param parameters
    141         *            An optional set of parameters. Should be any or all of the parameters returned by
    142         *            {@link Format#getReadParameters}.
    143         * @return A new {@linkplain GridCoverage grid coverage} from the input source.
    144         * @throws InvalidParameterNameException
    145         *             if a parameter in <code>parameters</code> doesn't have a recognized name.
    146         * @throws InvalidParameterValueException
    147         *             if a parameter in <code>parameters</code> doesn't have a valid value.
    148         * @throws ParameterNotFoundException
    149         *             if a parameter was required for the operation but was not provided in the
    150         *             <code>parameters</code> list.
    151         * @throws CannotCreateGridCoverageException
    152         *             if the coverage can't be created for a logical reason (for example an unsupported
    153         *             format, or an inconsistency found in the data).
    154         * @throws IOException
    155         *             if a read operation failed for some other input/output reason, including
    156         *             {@link java.io.FileNotFoundException} if no file with the given <code>name</code>
    157         *             can be found, or {@link javax.imageio.IIOException} if an error was thrown by the
    158         *             underlying image library.
    159         */
    160        GridCoverage read( GeneralParameterValueIm[] parameters )
    161                                throws InvalidParameterNameException, InvalidParameterValueException,
    162                                ParameterNotFoundException, IOException;
    163
    164        /**
    165         * Allows any resources held by this object to be released. The result of calling any other
    166         * method subsequent to a call to this method is undefined. It is important for applications to
    167         * call this method when they know they will no longer be using this
    168         * <code>GridCoverageReader</code>. Otherwise, the reader may continue to hold on to
    169         * resources indefinitely.
    170         *
    171         * @throws IOException
    172         *             if an error occured while disposing resources (for example while closing a file).
    173         */
    174        void dispose()
    175                                throws IOException;
    176    }