001: //$HeadURL: https://svn.wald.intevation.org/svn/deegree/base/trunk/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() throws IOException;
091:
092: /**
093: * Retrieve the metadata value for a given metadata name.
094: *
095: * @param name
096: * Metadata keyword for which to retrieve metadata.
097: * @return The metadata value for the given metadata name. Should be one of the name returned by
098: * {@link #getMetadataNames}.
099: * @throws IOException
100: * if an error occurs during reading.
101: * @throws MetadataNameNotFoundException
102: * if there is no value for the specified metadata name.
103: *
104: * @revisit This javadoc may not apply thats well in the iterator scheme.
105: */
106: String getMetadataValue(String name) throws IOException,
107: MetadataNameNotFoundException;
108:
109: /**
110: * Sets the metadata value for a given metadata name.
111: *
112: * @param name
113: * Metadata keyword for which to set the metadata.
114: * @param value
115: * The metadata value for the given metadata name.
116: * @throws IOException
117: * if an error occurs during writing.
118: * @throws MetadataNameNotFoundException
119: * if the specified metadata name is not handled for this format.
120: *
121: * @revisit This javadoc may not apply thats well in the iterator scheme.
122: */
123: void setMetadataValue(String name, String value)
124: throws IOException, MetadataNameNotFoundException;
125:
126: /**
127: * @param name
128: * for the next grid coverage to {@linkplain #read read} within the
129: * {@linkplain #getSource() input }. The subname can been fetch later at reading
130: * time.
131: *
132: * @throws IOException
133: * if an error occurs during writing.
134: * @revisit Do we need a special method for that, or should it be a metadata?
135: */
136: void setCurrentSubname(String name) throws IOException;
137:
138: /**
139: * Retrieve the list of grid coverages contained within the {@linkplain #getSource input
140: * source}. Each grid can have a different coordinate system, number of dimensions and grid
141: * geometry. For example, a HDF-EOS file (GRID.HDF) contains 6 grid coverages each having a
142: * different projection. An empty array will be returned if no sub names exist.
143: *
144: * @return The list of grid coverages contained within the input source.
145: * @throws IOException
146: * if an error occurs during reading.
147: *
148: * @revisit The javadoc should also be more explicit about hierarchical format. Should the names
149: * be returned as paths? Explain what to return if the GridCoverage are accessible by
150: * index only. A proposal is to name them "grid1", "grid2", etc.
151: */
152: String[] listSubNames() throws IOException;
153:
154: /**
155: * @return the name for the next grid coverage to be {@linkplain #read read} from the
156: * {@linkplain #getSource input source}.
157: *
158: * @throws IOException
159: * if an error occurs during reading.
160: * @revisit Do we need a special method for that, or should it be a metadata?
161: */
162: String getCurrentSubname() throws IOException;
163:
164: /**
165: * Read the grid coverage from the current stream position, and move to the next grid coverage.
166: *
167: * @param parameters
168: * An optional set of parameters. Should be any or all of the parameters returned by
169: * {@link Format#getReadParameters}.
170: * @return A new {@linkplain GridCoverage grid coverage} from the input source.
171: * @throws InvalidParameterNameException
172: * if a parameter in <code>parameters</code> doesn't have a recognized name.
173: * @throws InvalidParameterValueException
174: * if a parameter in <code>parameters</code> doesn't have a valid value.
175: * @throws ParameterNotFoundException
176: * if a parameter was required for the operation but was not provided in the
177: * <code>parameters</code> list.
178: * @throws CannotCreateGridCoverageException
179: * if the coverage can't be created for a logical reason (for example an unsupported
180: * format, or an inconsistency found in the data).
181: * @throws IOException
182: * if a read operation failed for some other input/output reason, including
183: * {@link java.io.FileNotFoundException} if no file with the given <code>name</code>
184: * can be found, or {@link javax.imageio.IIOException} if an error was thrown by the
185: * underlying image library.
186: */
187: GridCoverage read(GeneralParameterValueIm[] parameters)
188: throws InvalidParameterNameException,
189: InvalidParameterValueException, ParameterNotFoundException,
190: IOException;
191:
192: /**
193: * Allows any resources held by this object to be released. The result of calling any other
194: * method subsequent to a call to this method is undefined. It is important for applications to
195: * call this method when they know they will no longer be using this
196: * <code>GridCoverageReader</code>. Otherwise, the reader may continue to hold on to
197: * resources indefinitely.
198: *
199: * @throws IOException
200: * if an error occured while disposing resources (for example while closing a file).
201: */
202: void dispose() throws IOException;
203: }
|