001 //$HeadURL: svn+ssh://rbezema@svn.wald.intevation.org/deegree/base/tags/2.1/src/org/deegree/model/coverage/grid/GridCoverageReader.java $
002 /*---------------- FILE HEADER ------------------------------------------
003
004 This file is part of deegree.
005 Copyright (C) 2001-2007 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 /**
055 * Support for reading grid coverages out of a persisten store. Instance of
056 * <code>GridCoverageReader</code> are obtained through a call to
057 * {@link GridCoverageExchange#getReader(Object)}. Grid coverages are usually
058 * read from the input stream in a sequential order.
059 *
060 * @author <A HREF="http://www.opengis.org">OpenGIS® consortium</A>
061 * @version 2.0
062 *
063 * @see GridCoverageExchange#getReader(Object)
064 * @see javax.imageio.ImageReader
065 */
066 public interface GridCoverageReader {
067 /**
068 * @return the format handled by this <code>GridCoverageReader</code>.
069 */
070 Format getFormat();
071
072 /**
073 * @return the input source. This is the object passed to the
074 * {@link GridCoverageExchange#getReader(Object)} method. It can be a
075 * {@link java.lang.String}, an {@link java.io.InputStream}, a
076 * {@link java.nio.channels.FileChannel}, whatever.
077 */
078 Object getSource();
079
080 /**
081 * Returns the list of metadata keywords associated with the {@linkplain #getSource
082 * input source} as a whole (not associated with any particular grid coverage).
083 * If no metadata is available, the array will be empty.
084 *
085 * @return The list of metadata keywords for the input source.
086 * @throws IOException if an error occurs during reading.
087 *
088 * @revisit This javadoc may not apply thats well in the iterator scheme.
089 */
090 String[] getMetadataNames() throws IOException;
091
092 /**
093 * Retrieve the metadata value for a given metadata name.
094 *
095 * @param name Metadata keyword for which to retrieve metadata.
096 * @return The metadata value for the given metadata name. Should be one of
097 * the name returned by {@link #getMetadataNames}.
098 * @throws IOException if an error occurs during reading.
099 * @throws MetadataNameNotFoundException if there is no value for the specified metadata name.
100 *
101 * @revisit This javadoc may not apply thats well in the iterator scheme.
102 */
103 String getMetadataValue(String name) throws IOException, MetadataNameNotFoundException;
104
105 /**
106 * Sets the metadata value for a given metadata name.
107 *
108 * @param name Metadata keyword for which to set the metadata.
109 * @param value The metadata value for the given metadata name.
110 * @throws IOException if an error occurs during writing.
111 * @throws MetadataNameNotFoundException if the specified metadata name is not handled
112 * for this format.
113 *
114 * @revisit This javadoc may not apply thats well in the iterator scheme.
115 */
116 void setMetadataValue(String name, String value) throws IOException, MetadataNameNotFoundException;
117
118 /**
119 * @param name for the next grid coverage to {@linkplain #read read} within the
120 * {@linkplain #getSource() input }. The subname can been fetch later
121 * at reading time.
122 *
123 * @throws IOException if an error occurs during writing.
124 * @revisit Do we need a special method for that, or should it be a metadata?
125 */
126 void setCurrentSubname(String name) throws IOException;
127
128 /**
129 * Retrieve the list of grid coverages contained within the {@linkplain #getSource
130 * input source}. Each grid can have a different coordinate system, number of dimensions
131 * and grid geometry. For example, a HDF-EOS file (GRID.HDF) contains 6 grid coverages
132 * each having a different projection. An empty array will be returned if no sub names
133 * exist.
134 *
135 * @return The list of grid coverages contained within the input source.
136 * @throws IOException if an error occurs during reading.
137 *
138 * @revisit The javadoc should also be more explicit about hierarchical format.
139 * Should the names be returned as paths?
140 * Explain what to return if the GridCoverage are accessible by index
141 * only. A proposal is to name them "grid1", "grid2", etc.
142 */
143 String[] listSubNames() throws IOException;
144
145 /**
146 * @return the name for the next grid coverage to be {@linkplain #read read} from the
147 * {@linkplain #getSource input source}.
148 *
149 * @throws IOException if an error occurs during reading.
150 * @revisit Do we need a special method for that, or should it be a metadata?
151 */
152 String getCurrentSubname() throws IOException;
153
154 /**
155 * Read the grid coverage from the current stream position, and move to the next grid
156 * coverage.
157 *
158 * @param parameters An optional set of parameters. Should be any or all of the
159 * parameters returned by {@link Format#getReadParameters}.
160 * @return A new {@linkplain GridCoverage grid coverage} from the input source.
161 * @throws InvalidParameterNameException if a parameter in <code>parameters</code>
162 * doesn't have a recognized name.
163 * @throws InvalidParameterValueException if a parameter in <code>parameters</code>
164 * doesn't have a valid value.
165 * @throws ParameterNotFoundException if a parameter was required for the operation but was
166 * not provided in the <code>parameters</code> list.
167 * @throws CannotCreateGridCoverageException if the coverage can't be created for a logical
168 * reason (for example an unsupported format, or an inconsistency found in the data).
169 * @throws IOException if a read operation failed for some other input/output reason, including
170 * {@link java.io.FileNotFoundException} if no file with the given <code>name</code> can be
171 * found, or {@link javax.imageio.IIOException} if an error was thrown by the
172 * underlying image library.
173 */
174 GridCoverage read(GeneralParameterValueIm[] parameters)
175 throws InvalidParameterNameException, InvalidParameterValueException, ParameterNotFoundException, IOException;
176
177 /**
178 * Allows any resources held by this object to be released. The result of calling any other
179 * method subsequent to a call to this method is undefined. It is important for applications
180 * to call this method when they know they will no longer be using this <code>GridCoverageReader</code>.
181 * Otherwise, the reader may continue to hold on to resources indefinitely.
182 *
183 * @throws IOException if an error occured while disposing resources (for example while closing
184 * a file).
185 */
186 void dispose() throws IOException;
187 }