001 //$HeadURL: svn+ssh://jwilden@svn.wald.intevation.org/deegree/base/branches/2.5_testing/src/org/deegree/model/coverage/grid/GridCoverageWriter.java $
002 /*----------------------------------------------------------------------------
003 This file originated as a part of GeoAPI.
004
005 GeoAPI is free software. GeoAPI may be used, modified and
006 redistributed by anyone for any purpose requring only maintaining the
007 copyright and license terms on the source code and derivative files.
008 See the OGC legal page for details.
009
010 The copyright to the GeoAPI interfaces is held by the Open Geospatial
011 Consortium, see http://www.opengeospatial.org/ogc/legal
012 ----------------------------------------------------------------------------*/
013 package org.deegree.model.coverage.grid;
014
015 import java.io.IOException;
016
017 import org.deegree.datatypes.parameter.GeneralParameterValueIm;
018 import org.deegree.datatypes.parameter.InvalidParameterNameException;
019 import org.deegree.datatypes.parameter.InvalidParameterValueException;
020 import org.deegree.datatypes.parameter.ParameterNotFoundException;
021
022 /**
023 * Support for writing grid coverages into a persistent store. Instance of
024 * <code>GridCoverageWriter</code> are obtained through a call to
025 * {@link GridCoverageExchange#getWriter}. Grid coverages are usually added to the output stream in
026 * a sequential order.
027 *
028 * @author <A HREF="http://www.opengis.org">OpenGIS® consortium</A>
029 * @author last edited by: $Author: mschneider $
030 *
031 * @version $Revision: 20326 $, $Date: 2009-10-22 18:41:56 +0200 (Do, 22 Okt 2009) $
032 *
033 * @see GridCoverageExchange#getWriter
034 * @see javax.imageio.ImageWriter
035 */
036 public interface GridCoverageWriter {
037 /**
038 * Returns the format handled by this <code>GridCoverageWriter</code>.
039 *
040 * @return the format handled by this <code>GridCoverageWriter</code>.
041 */
042 Format getFormat();
043
044 /**
045 * Returns the output destination. This is the object passed to the
046 * {@link GridCoverageExchange#getWriter} method. It can be a {@link java.lang.String}, an
047 * {@link java.io.OutputStream}, a {@link java.nio.channels.FileChannel}, etc.
048 *
049 * @return the output destination
050 */
051 Object getDestination();
052
053 /**
054 * Returns the list of metadata keywords associated with the {@linkplain #getDestination output
055 * destination} as a whole (not associated with any particular grid coverage). If no metadata is
056 * allowed, the array will be empty.
057 *
058 * @return The list of metadata keywords for the output destination.
059 *
060 * @revisit This javadoc may not apply thats well in the iterator scheme.
061 */
062 String[] getMetadataNames();
063
064 /**
065 * Retrieve the metadata value for a given metadata name.
066 *
067 * @param name
068 * Metadata keyword for which to retrieve metadata.
069 * @return The metadata value for the given metadata name. Should be one of the name returned by
070 * {@link #getMetadataNames}.
071 * @throws IOException
072 * if an error occurs during reading.
073 * @throws MetadataNameNotFoundException
074 * if there is no value for the specified metadata name.
075 *
076 * @revisit This javadoc may not apply thats well in the iterator scheme.
077 */
078 Object getMetadataValue( String name )
079 throws IOException, MetadataNameNotFoundException;
080
081 /**
082 * Sets the metadata value for a given metadata name.
083 *
084 * @param name
085 * Metadata keyword for which to set the metadata.
086 * @param value
087 * The metadata value for the given metadata name.
088 * @throws IOException
089 * if an error occurs during writing.
090 * @throws MetadataNameNotFoundException
091 * if the specified metadata name is not handled for this format.
092 *
093 * @revisit This javadoc may not apply thats well in the iterator scheme.
094 */
095 void setMetadataValue( String name, String value )
096 throws IOException, MetadataNameNotFoundException;
097
098 /**
099 * Retrieve the list of grid coverages contained within the {@linkplain #getDestination() input
100 * source}. Each grid can have a different coordinate system, number of dimensions and grid
101 * geometry. For example, a HDF-EOS file (GRID.HDF) contains 6 grid coverages each having a
102 * different projection. An empty array will be returned if no sub names exist.
103 *
104 * @return The list of grid coverages contained within the input source.
105 * @throws IOException
106 * if an error occurs during reading.
107 *
108 * @revisit The javadoc should also be more explicit about hierarchical format. Should the names
109 * be returned as paths? Explain what to return if the GridCoverage are accessible by
110 * index only. A proposal is to name them "grid1", "grid2", etc.
111 */
112 String[] listSubNames()
113 throws IOException;
114
115 /**
116 * Returns the name for the next grid coverage to be
117 * {@linkplain #write(GridCoverage, GeneralParameterValueIm[]) write} to the
118 * {@linkplain #getDestination() output destination}.
119 *
120 * @return the name for the next grid coverage to be
121 *
122 * @throws IOException
123 * if an error occurs during reading.
124 * @revisit Do we need a special method for that, or should it be a metadata?
125 */
126 String getCurrentSubname()
127 throws IOException;
128
129 /**
130 * Set the name for the next grid coverage to
131 * {@linkplain #write(GridCoverage, GeneralParameterValueIm[]) write} within the
132 * {@linkplain #getDestination output destination}. The subname can been fetch later at reading
133 * time.
134 *
135 * @param name
136 *
137 * @throws IOException
138 * if an error occurs during writing.
139 * @revisit Do we need a special method for that, or should it be a metadata?
140 */
141 void setCurrentSubname( String name )
142 throws IOException;
143
144 /**
145 * Writes the specified grid coverage.
146 *
147 * @param coverage
148 * The {@linkplain GridCoverage grid coverage} to write.
149 * @param parameters
150 * An optional set of parameters. Should be any or all of the parameters returned by
151 * {@link Format#getWriteParameters}.
152 * @throws InvalidParameterNameException
153 * if a parameter in <code>parameters</code> doesn't have a recognized name.
154 * @throws InvalidParameterValueException
155 * if a parameter in <code>parameters</code> doesn't have a valid value.
156 * @throws ParameterNotFoundException
157 * if a parameter was required for the operation but was not provided in the
158 * <code>parameters</code> list.
159 * @throws IOException
160 * if the export failed for some other input/output reason, including
161 * {@link javax.imageio.IIOException} if an error was thrown by the underlying image
162 * library.
163 */
164 void write( GridCoverage coverage, GeneralParameterValueIm[] parameters )
165 throws InvalidParameterNameException, InvalidParameterValueException,
166 ParameterNotFoundException, IOException;
167
168 /**
169 * Allows any resources held by this object to be released. The result of calling any other
170 * method subsequent to a call to this method is undefined. It is important for applications to
171 * call this method when they know they will no longer be using this
172 * <code>GridCoverageWriter</code>. Otherwise, the writer may continue to hold on to
173 * resources indefinitely.
174 *
175 * @throws IOException
176 * if an error occured while disposing resources (for example while flushing data
177 * and closing a file).
178 */
179 void dispose()
180 throws IOException;
181 }