001    //$HeadURL: svn+ssh://jwilden@svn.wald.intevation.org/deegree/base/branches/2.5_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    }