001: //$HeadURL: https://svn.wald.intevation.org/svn/deegree/base/trunk/src/org/deegree/model/coverage/grid/GridCoverageWriter.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 writing grid coverages into a persistent store. Instance of
055: * <code>GridCoverageWriter</code> are obtained through a call to
056: * {@link GridCoverageExchange#getWriter}. Grid coverages are usually added to the output stream in
057: * a sequential order.
058: *
059: * @author <A HREF="http://www.opengis.org">OpenGIS® consortium</A>
060: * @author last edited by: $Author: apoth $
061: *
062: * @version $Revision: 9343 $, $Date: 2007-12-27 05:30:32 -0800 (Thu, 27 Dec 2007) $
063: *
064: * @see GridCoverageExchange#getWriter
065: * @see javax.imageio.ImageWriter
066: */
067: public interface GridCoverageWriter {
068: /**
069: * Returns the format handled by this <code>GridCoverageWriter</code>.
070: *
071: * @return the format handled by this <code>GridCoverageWriter</code>.
072: */
073: Format getFormat();
074:
075: /**
076: * Returns the output destination. This is the object passed to the
077: * {@link GridCoverageExchange#getWriter} method. It can be a {@link java.lang.String}, an
078: * {@link java.io.OutputStream}, a {@link java.nio.channels.FileChannel}, etc.
079: *
080: * @return
081: */
082: Object getDestination();
083:
084: /**
085: * Returns the list of metadata keywords associated with the {@linkplain #getDestination output
086: * destination} as a whole (not associated with any particular grid coverage). If no metadata is
087: * allowed, the array will be empty.
088: *
089: * @return The list of metadata keywords for the output destination.
090: *
091: * @revisit This javadoc may not apply thats well in the iterator scheme.
092: */
093: String[] getMetadataNames();
094:
095: /**
096: * Retrieve the metadata value for a given metadata name.
097: *
098: * @param name
099: * Metadata keyword for which to retrieve metadata.
100: * @return The metadata value for the given metadata name. Should be one of the name returned by
101: * {@link #getMetadataNames}.
102: * @throws IOException
103: * if an error occurs during reading.
104: * @throws MetadataNameNotFoundException
105: * if there is no value for the specified metadata name.
106: *
107: * @revisit This javadoc may not apply thats well in the iterator scheme.
108: */
109: Object getMetadataValue(String name) throws IOException,
110: MetadataNameNotFoundException;
111:
112: /**
113: * Sets the metadata value for a given metadata name.
114: *
115: * @param name
116: * Metadata keyword for which to set the metadata.
117: * @param value
118: * The metadata value for the given metadata name.
119: * @throws IOException
120: * if an error occurs during writing.
121: * @throws MetadataNameNotFoundException
122: * if the specified metadata name is not handled for this format.
123: *
124: * @revisit This javadoc may not apply thats well in the iterator scheme.
125: */
126: void setMetadataValue(String name, String value)
127: throws IOException, MetadataNameNotFoundException;
128:
129: /**
130: * Retrieve the list of grid coverages contained within the {@linkplain #getDestination() input
131: * source}. Each grid can have a different coordinate system, number of dimensions and grid
132: * geometry. For example, a HDF-EOS file (GRID.HDF) contains 6 grid coverages each having a
133: * different projection. An empty array will be returned if no sub names exist.
134: *
135: * @return The list of grid coverages contained within the input source.
136: * @throws IOException
137: * if an error occurs during reading.
138: *
139: * @revisit The javadoc should also be more explicit about hierarchical format. Should the names
140: * be returned as paths? Explain what to return if the GridCoverage are accessible by
141: * index only. A proposal is to name them "grid1", "grid2", etc.
142: */
143: String[] listSubNames() throws IOException;
144:
145: /**
146: * Returns the name for the next grid coverage to be
147: * {@linkplain #write(GridCoverage, GeneralParameterValueIm[]) write} to the
148: * {@linkplain #getDestination() output destination}.
149: *
150: * @return the name for the next grid coverage to be
151: *
152: * @throws IOException
153: * if an error occurs during reading.
154: * @revisit Do we need a special method for that, or should it be a metadata?
155: */
156: String getCurrentSubname() throws IOException;
157:
158: /**
159: * Set the name for the next grid coverage to
160: * {@linkplain #write(GridCoverage, GeneralParameterValueIm[]) write} within the
161: * {@linkplain #getDestination output destination}. The subname can been fetch later at reading
162: * time.
163: *
164: * @param name
165: *
166: * @throws IOException
167: * if an error occurs during writing.
168: * @revisit Do we need a special method for that, or should it be a metadata?
169: */
170: void setCurrentSubname(String name) throws IOException;
171:
172: /**
173: * Writes the specified grid coverage.
174: *
175: * @param coverage
176: * The {@linkplain GridCoverage grid coverage} to write.
177: * @param parameters
178: * An optional set of parameters. Should be any or all of the parameters returned by
179: * {@link Format#getWriteParameters}.
180: * @throws InvalidParameterNameException
181: * if a parameter in <code>parameters</code> doesn't have a recognized name.
182: * @throws InvalidParameterValueException
183: * if a parameter in <code>parameters</code> doesn't have a valid value.
184: * @throws ParameterNotFoundException
185: * if a parameter was required for the operation but was not provided in the
186: * <code>parameters</code> list.
187: * @throws FileFormatNotCompatibleWithGridCoverageException
188: * if the grid coverage can't be exported in the
189: * {@linkplain #getFormat writer format}.
190: * @throws IOException
191: * if the export failed for some other input/output reason, including
192: * {@link javax.imageio.IIOException} if an error was thrown by the underlying image
193: * library.
194: */
195: void write(GridCoverage coverage,
196: GeneralParameterValueIm[] parameters)
197: throws InvalidParameterNameException,
198: InvalidParameterValueException, ParameterNotFoundException,
199: IOException;
200:
201: /**
202: * Allows any resources held by this object to be released. The result of calling any other
203: * method subsequent to a call to this method is undefined. It is important for applications to
204: * call this method when they know they will no longer be using this
205: * <code>GridCoverageWriter</code>. Otherwise, the writer may continue to hold on to
206: * resources indefinitely.
207: *
208: * @throws IOException
209: * if an error occured while disposing resources (for example while flushing data
210: * and closing a file).
211: */
212: void dispose() throws IOException;
213: }
|