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&reg; 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    }