ImageTranscoder


1   /*
2    * @(#)ImageTranscoder.java 1.19 03/12/19
3    *
4    * Copyright 2004 Sun Microsystems, Inc. All rights reserved.
5    * SUN PROPRIETARY/CONFIDENTIAL. Use is subject to license terms.
6    */
7   
8   package javax.imageio;
9   
10  import javax.imageio.metadata.IIOMetadata  ;
11  
12  /**
13   * An interface providing metadata transcoding capability.
14   *
15   * <p> Any image may be transcoded (written to a different format
16   * than the one it was originally stored in) simply by performing
17   * a read operation followed by a write operation.  However, loss
18   * of data may occur in this process due to format differences.
19   *
20   * <p> In general, the best results will be achieved when
21   * format-specific metadata objects can be created to encapsulate as
22   * much information about the image and its associated metadata as
23   * possible, in terms that are understood by the specific
24   * <code>ImageWriter</code> used to perform the encoding.
25   *
26   * <p> An <code>ImageTranscoder</code> may be used to convert the
27   * <code>IIOMetadata</code> objects supplied by the
28   * <code>ImageReader</code> (representing per-stream and per-image
29   * metadata) into corresponding objects suitable for encoding by a
30   * particular <code>ImageWriter</code>.  In the case where the methods
31   * of this interface are being called directly on an
32   * <code>ImageWriter</code>, the output will be suitable for that
33   * writer.
34   *
35   * <p> The internal details of converting an <code>IIOMetadata</code>
36   * object into a writer-specific format will vary according to the
37   * context of the operation.  Typically, an <code>ImageWriter</code>
38   * will inspect the incoming object to see if it implements additional
39   * interfaces with which the writer is familiar.  This might be the
40   * case, for example, if the object was obtained by means of a read
41   * operation on a reader plug-in written by the same vendor as the
42   * writer.  In this case, the writer may access the incoming object by
43   * means of its plug-in specific interfaces.  In this case, the
44   * re-encoding may be close to lossless if the image file format is
45   * kept constant.  If the format is changing, the writer may still
46   * attempt to preserve as much information as possible.
47   *
48   * <p> If the incoming object does not implement any additional
49   * interfaces known to the writer, the writer has no choice but to
50   * access it via the standard <code>IIOMetadata</code> interfaces such
51   * as the tree view provided by <code>IIOMetadata.getAsTree</code>.
52   * In this case, there is likely to be significant loss of
53   * information.
54   *
55   * <p> An independent <code>ImageTranscoder</code> essentially takes
56   * on the same role as the writer plug-in in the above examples.  It
57   * must be familiar with the private interfaces used by both the
58   * reader and writer plug-ins, and manually instantiate an object that
59   * will be usable by the writer.  The resulting metadata objects may
60   * be used by the writer directly.
61   *
62   * <p> No independent implementations of <code>ImageTranscoder</code>
63   * are provided as part of the standard API.  Instead, the intention
64   * of this interface is to provide a way for implementations to be
65   * created and discovered by applications as the need arises.
66   * 
67   * @version 0.5
68   */
69  public interface ImageTranscoder {
70  
71      /**
72       * Returns an <code>IIOMetadata</code> object that may be used for
73       * encoding and optionally modified using its document interfaces
74       * or other interfaces specific to the writer plug-in that will be
75       * used for encoding.
76       *
77       * <p> An optional <code>ImageWriteParam</code> may be supplied
78       * for cases where it may affect the structure of the stream
79       * metadata.
80       *
81       * <p> If the supplied <code>ImageWriteParam</code> contains
82       * optional setting values not understood by this writer or
83       * transcoder, they will be ignored.
84       *
85       * @param inData an <code>IIOMetadata</code> object representing
86       * stream metadata, used to initialize the state of the returned
87       * object.
88       * @param param an <code>ImageWriteParam</code> that will be used to
89       * encode the image, or <code>null</code>.
90       *
91       * @return an <code>IIOMetadata</code> object, or
92       * <code>null</code> if the plug-in does not provide metadata
93       * encoding capabilities.
94       *
95       * @exception IllegalArgumentException if <code>inData</code> is
96       * <code>null</code>.
97       */
98      IIOMetadata   convertStreamMetadata(IIOMetadata   inData,
99                                        ImageWriteParam   param);
100 
101     /**
102      * Returns an <code>IIOMetadata</code> object that may be used for
103      * encoding and optionally modified using its document interfaces
104      * or other interfaces specific to the writer plug-in that will be
105      * used for encoding.
106      *
107      * <p> An optional <code>ImageWriteParam</code> may be supplied
108      * for cases where it may affect the structure of the image
109      * metadata.
110      *
111      * <p> If the supplied <code>ImageWriteParam</code> contains
112      * optional setting values not understood by this writer or
113      * transcoder, they will be ignored.
114      *
115      * @param inData an <code>IIOMetadata</code> object representing
116      * image metadata, used to initialize the state of the returned
117      * object.
118      * @param imageType an <code>ImageTypeSpecifier</code> indicating
119      * the layout and color information of the image with which the
120      * metadata will be associated.
121      * @param param an <code>ImageWriteParam</code> that will be used to
122      * encode the image, or <code>null</code>.
123      *
124      * @return an <code>IIOMetadata</code> object,
125      * or <code>null</code> if the plug-in does not provide
126      * metadata encoding capabilities.
127      *
128      * @exception IllegalArgumentException if either of
129      * <code>inData</code> or <code>imageType</code> is
130      * <code>null</code>.
131      */
132     IIOMetadata   convertImageMetadata(IIOMetadata   inData,
133                                      ImageTypeSpecifier   imageType,
134                                      ImageWriteParam   param);
135 }
136
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags