001 //$HeadURL: svn+ssh://rbezema@svn.wald.intevation.org/deegree/base/branches/2.2_testing/src/org/deegree/model/coverage/grid/GridCoverageReader.java $
002 /*---------------- FILE HEADER ------------------------------------------
003
004 This file is part of deegree.
005 Copyright (C) 2001-2008 by:
006 EXSE, Department of Geography, University of Bonn
007 http://www.giub.uni-bonn.de/deegree/
008 lat/lon GmbH
009 http://www.lat-lon.de
010
011 This library is free software; you can redistribute it and/or
012 modify it under the terms of the GNU Lesser General Public
013 License as published by the Free Software Foundation; either
014 version 2.1 of the License, or (at your option) any later version.
015
016 This library is distributed in the hope that it will be useful,
017 but WITHOUT ANY WARRANTY; without even the implied warranty of
018 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
019 Lesser General Public License for more details.
020
021 You should have received a copy of the GNU Lesser General Public
022 License along with this library; if not, write to the Free Software
023 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
024
025 Contact:
026
027 Andreas Poth
028 lat/lon GmbH
029 Aennchenstr. 19
030 53115 Bonn
031 Germany
032 E-Mail: poth@lat-lon.de
033
034 Prof. Dr. Klaus Greve
035 Department of Geography
036 University of Bonn
037 Meckenheimer Allee 166
038 53115 Bonn
039 Germany
040 E-Mail: greve@giub.uni-bonn.de
041
042
043 ---------------------------------------------------------------------------*/
044 package org.deegree.model.coverage.grid;
045
046 import java.io.IOException;
047
048 import org.deegree.datatypes.parameter.GeneralParameterValueIm;
049 import org.deegree.datatypes.parameter.InvalidParameterNameException;
050 import org.deegree.datatypes.parameter.InvalidParameterValueException;
051 import org.deegree.datatypes.parameter.ParameterNotFoundException;
052
053 /**
054 * Support for reading grid coverages out of a persisten store. Instance of
055 * <code>GridCoverageReader</code> are obtained through a call to
056 * {@link GridCoverageExchange#getReader(Object)}. Grid coverages are usually read from the input
057 * stream in a sequential order.
058 *
059 * @author <A HREF="http://www.opengis.org">OpenGIS® consortium</A>
060 * @version 2.0
061 *
062 * @see GridCoverageExchange#getReader(Object)
063 * @see javax.imageio.ImageReader
064 */
065 public interface GridCoverageReader {
066 /**
067 * @return the format handled by this <code>GridCoverageReader</code>.
068 */
069 Format getFormat();
070
071 /**
072 * @return the input source. This is the object passed to the
073 * {@link GridCoverageExchange#getReader(Object)} method. It can be a
074 * {@link java.lang.String}, an {@link java.io.InputStream}, a
075 * {@link java.nio.channels.FileChannel}, whatever.
076 */
077 Object getSource();
078
079 /**
080 * Returns the list of metadata keywords associated with the {@linkplain #getSource input
081 * source} as a whole (not associated with any particular grid coverage). If no metadata is
082 * available, the array will be empty.
083 *
084 * @return The list of metadata keywords for the input source.
085 * @throws IOException
086 * if an error occurs during reading.
087 *
088 * @revisit This javadoc may not apply thats well in the iterator scheme.
089 */
090 String[] getMetadataNames()
091 throws IOException;
092
093 /**
094 * Retrieve the metadata value for a given metadata name.
095 *
096 * @param name
097 * Metadata keyword for which to retrieve metadata.
098 * @return The metadata value for the given metadata name. Should be one of the name returned by
099 * {@link #getMetadataNames}.
100 * @throws IOException
101 * if an error occurs during reading.
102 * @throws MetadataNameNotFoundException
103 * if there is no value for the specified metadata name.
104 *
105 * @revisit This javadoc may not apply thats well in the iterator scheme.
106 */
107 String getMetadataValue( String name )
108 throws IOException, MetadataNameNotFoundException;
109
110 /**
111 * Sets the metadata value for a given metadata name.
112 *
113 * @param name
114 * Metadata keyword for which to set the metadata.
115 * @param value
116 * The metadata value for the given metadata name.
117 * @throws IOException
118 * if an error occurs during writing.
119 * @throws MetadataNameNotFoundException
120 * if the specified metadata name is not handled for this format.
121 *
122 * @revisit This javadoc may not apply thats well in the iterator scheme.
123 */
124 void setMetadataValue( String name, String value )
125 throws IOException, MetadataNameNotFoundException;
126
127 /**
128 * @param name
129 * for the next grid coverage to {@linkplain #read read} within the
130 * {@linkplain #getSource() input }. The subname can been fetch later at reading
131 * time.
132 *
133 * @throws IOException
134 * if an error occurs during writing.
135 * @revisit Do we need a special method for that, or should it be a metadata?
136 */
137 void setCurrentSubname( String name )
138 throws IOException;
139
140 /**
141 * Retrieve the list of grid coverages contained within the {@linkplain #getSource input
142 * source}. Each grid can have a different coordinate system, number of dimensions and grid
143 * geometry. For example, a HDF-EOS file (GRID.HDF) contains 6 grid coverages each having a
144 * different projection. An empty array will be returned if no sub names exist.
145 *
146 * @return The list of grid coverages contained within the input source.
147 * @throws IOException
148 * if an error occurs during reading.
149 *
150 * @revisit The javadoc should also be more explicit about hierarchical format. Should the names
151 * be returned as paths? Explain what to return if the GridCoverage are accessible by
152 * index only. A proposal is to name them "grid1", "grid2", etc.
153 */
154 String[] listSubNames()
155 throws IOException;
156
157 /**
158 * @return the name for the next grid coverage to be {@linkplain #read read} from the
159 * {@linkplain #getSource input source}.
160 *
161 * @throws IOException
162 * if an error occurs during reading.
163 * @revisit Do we need a special method for that, or should it be a metadata?
164 */
165 String getCurrentSubname()
166 throws IOException;
167
168 /**
169 * Read the grid coverage from the current stream position, and move to the next grid coverage.
170 *
171 * @param parameters
172 * An optional set of parameters. Should be any or all of the parameters returned by
173 * {@link Format#getReadParameters}.
174 * @return A new {@linkplain GridCoverage grid coverage} from the input source.
175 * @throws InvalidParameterNameException
176 * if a parameter in <code>parameters</code> doesn't have a recognized name.
177 * @throws InvalidParameterValueException
178 * if a parameter in <code>parameters</code> doesn't have a valid value.
179 * @throws ParameterNotFoundException
180 * if a parameter was required for the operation but was not provided in the
181 * <code>parameters</code> list.
182 * @throws CannotCreateGridCoverageException
183 * if the coverage can't be created for a logical reason (for example an unsupported
184 * format, or an inconsistency found in the data).
185 * @throws IOException
186 * if a read operation failed for some other input/output reason, including
187 * {@link java.io.FileNotFoundException} if no file with the given <code>name</code>
188 * can be found, or {@link javax.imageio.IIOException} if an error was thrown by the
189 * underlying image library.
190 */
191 GridCoverage read( GeneralParameterValueIm[] parameters )
192 throws InvalidParameterNameException, InvalidParameterValueException,
193 ParameterNotFoundException, IOException;
194
195 /**
196 * Allows any resources held by this object to be released. The result of calling any other
197 * method subsequent to a call to this method is undefined. It is important for applications to
198 * call this method when they know they will no longer be using this
199 * <code>GridCoverageReader</code>. Otherwise, the reader may continue to hold on to
200 * resources indefinitely.
201 *
202 * @throws IOException
203 * if an error occured while disposing resources (for example while closing a file).
204 */
205 void dispose()
206 throws IOException;
207 }