KickJava   Java API By Example, From Geeks To Geeks.

Java > Open Source Codes > javax > imageio > 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 JavaDoc;
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 JavaDoc convertStreamMetadata(IIOMetadata JavaDoc inData,
99                                       ImageWriteParam JavaDoc 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 JavaDoc convertImageMetadata(IIOMetadata JavaDoc inData,
133                                      ImageTypeSpecifier JavaDoc imageType,
134                                      ImageWriteParam JavaDoc param);
135 }
136
Popular Tags