001 //$HeadURL: svn+ssh://rbezema@svn.wald.intevation.org/deegree/base/branches/2.2_testing/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 14:30:32 +0100 (Do, 27 Dez 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 )
110 throws IOException, 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()
144 throws IOException;
145
146 /**
147 * Returns the name for the next grid coverage to be
148 * {@linkplain #write(GridCoverage, GeneralParameterValueIm[]) write} to the
149 * {@linkplain #getDestination() output destination}.
150 *
151 * @return the name for the next grid coverage to be
152 *
153 * @throws IOException
154 * if an error occurs during reading.
155 * @revisit Do we need a special method for that, or should it be a metadata?
156 */
157 String getCurrentSubname()
158 throws IOException;
159
160 /**
161 * Set the name for the next grid coverage to
162 * {@linkplain #write(GridCoverage, GeneralParameterValueIm[]) write} within the
163 * {@linkplain #getDestination output destination}. The subname can been fetch later at reading
164 * time.
165 *
166 * @param name
167 *
168 * @throws IOException
169 * if an error occurs during writing.
170 * @revisit Do we need a special method for that, or should it be a metadata?
171 */
172 void setCurrentSubname( String name )
173 throws IOException;
174
175 /**
176 * Writes the specified grid coverage.
177 *
178 * @param coverage
179 * The {@linkplain GridCoverage grid coverage} to write.
180 * @param parameters
181 * An optional set of parameters. Should be any or all of the parameters returned by
182 * {@link Format#getWriteParameters}.
183 * @throws InvalidParameterNameException
184 * if a parameter in <code>parameters</code> doesn't have a recognized name.
185 * @throws InvalidParameterValueException
186 * if a parameter in <code>parameters</code> doesn't have a valid value.
187 * @throws ParameterNotFoundException
188 * if a parameter was required for the operation but was not provided in the
189 * <code>parameters</code> list.
190 * @throws FileFormatNotCompatibleWithGridCoverageException
191 * if the grid coverage can't be exported in the
192 * {@linkplain #getFormat writer format}.
193 * @throws IOException
194 * if the export failed for some other input/output reason, including
195 * {@link javax.imageio.IIOException} if an error was thrown by the underlying image
196 * library.
197 */
198 void write( GridCoverage coverage, GeneralParameterValueIm[] parameters )
199 throws InvalidParameterNameException, InvalidParameterValueException,
200 ParameterNotFoundException, IOException;
201
202 /**
203 * Allows any resources held by this object to be released. The result of calling any other
204 * method subsequent to a call to this method is undefined. It is important for applications to
205 * call this method when they know they will no longer be using this
206 * <code>GridCoverageWriter</code>. Otherwise, the writer may continue to hold on to
207 * resources indefinitely.
208 *
209 * @throws IOException
210 * if an error occured while disposing resources (for example while flushing data
211 * and closing a file).
212 */
213 void dispose()
214 throws IOException;
215 }