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® 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 }