1/* 2 * Copyright (c) 2000, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26package javax.imageio; 27 28import javax.imageio.metadata.IIOMetadata; 29 30/** 31 * An interface providing metadata transcoding capability. 32 * 33 * <p> Any image may be transcoded (written to a different format 34 * than the one it was originally stored in) simply by performing 35 * a read operation followed by a write operation. However, loss 36 * of data may occur in this process due to format differences. 37 * 38 * <p> In general, the best results will be achieved when 39 * format-specific metadata objects can be created to encapsulate as 40 * much information about the image and its associated metadata as 41 * possible, in terms that are understood by the specific 42 * {@code ImageWriter} used to perform the encoding. 43 * 44 * <p> An {@code ImageTranscoder} may be used to convert the 45 * {@code IIOMetadata} objects supplied by the 46 * {@code ImageReader} (representing per-stream and per-image 47 * metadata) into corresponding objects suitable for encoding by a 48 * particular {@code ImageWriter}. In the case where the methods 49 * of this interface are being called directly on an 50 * {@code ImageWriter}, the output will be suitable for that 51 * writer. 52 * 53 * <p> The internal details of converting an {@code IIOMetadata} 54 * object into a writer-specific format will vary according to the 55 * context of the operation. Typically, an {@code ImageWriter} 56 * will inspect the incoming object to see if it implements additional 57 * interfaces with which the writer is familiar. This might be the 58 * case, for example, if the object was obtained by means of a read 59 * operation on a reader plug-in written by the same vendor as the 60 * writer. In this case, the writer may access the incoming object by 61 * means of its plug-in specific interfaces. In this case, the 62 * re-encoding may be close to lossless if the image file format is 63 * kept constant. If the format is changing, the writer may still 64 * attempt to preserve as much information as possible. 65 * 66 * <p> If the incoming object does not implement any additional 67 * interfaces known to the writer, the writer has no choice but to 68 * access it via the standard {@code IIOMetadata} interfaces such 69 * as the tree view provided by {@code IIOMetadata.getAsTree}. 70 * In this case, there is likely to be significant loss of 71 * information. 72 * 73 * <p> An independent {@code ImageTranscoder} essentially takes 74 * on the same role as the writer plug-in in the above examples. It 75 * must be familiar with the private interfaces used by both the 76 * reader and writer plug-ins, and manually instantiate an object that 77 * will be usable by the writer. The resulting metadata objects may 78 * be used by the writer directly. 79 * 80 * <p> No independent implementations of {@code ImageTranscoder} 81 * are provided as part of the standard API. Instead, the intention 82 * of this interface is to provide a way for implementations to be 83 * created and discovered by applications as the need arises. 84 * 85 */ 86public interface ImageTranscoder { 87 88 /** 89 * Returns an {@code IIOMetadata} object that may be used for 90 * encoding and optionally modified using its document interfaces 91 * or other interfaces specific to the writer plug-in that will be 92 * used for encoding. 93 * 94 * <p> An optional {@code ImageWriteParam} may be supplied 95 * for cases where it may affect the structure of the stream 96 * metadata. 97 * 98 * <p> If the supplied {@code ImageWriteParam} contains 99 * optional setting values not understood by this writer or 100 * transcoder, they will be ignored. 101 * 102 * @param inData an {@code IIOMetadata} object representing 103 * stream metadata, used to initialize the state of the returned 104 * object. 105 * @param param an {@code ImageWriteParam} that will be used to 106 * encode the image, or {@code null}. 107 * 108 * @return an {@code IIOMetadata} object, or 109 * {@code null} if the plug-in does not provide metadata 110 * encoding capabilities. 111 * 112 * @exception IllegalArgumentException if {@code inData} is 113 * {@code null}. 114 */ 115 IIOMetadata convertStreamMetadata(IIOMetadata inData, 116 ImageWriteParam param); 117 118 /** 119 * Returns an {@code IIOMetadata} object that may be used for 120 * encoding and optionally modified using its document interfaces 121 * or other interfaces specific to the writer plug-in that will be 122 * used for encoding. 123 * 124 * <p> An optional {@code ImageWriteParam} may be supplied 125 * for cases where it may affect the structure of the image 126 * metadata. 127 * 128 * <p> If the supplied {@code ImageWriteParam} contains 129 * optional setting values not understood by this writer or 130 * transcoder, they will be ignored. 131 * 132 * @param inData an {@code IIOMetadata} object representing 133 * image metadata, used to initialize the state of the returned 134 * object. 135 * @param imageType an {@code ImageTypeSpecifier} indicating 136 * the layout and color information of the image with which the 137 * metadata will be associated. 138 * @param param an {@code ImageWriteParam} that will be used to 139 * encode the image, or {@code null}. 140 * 141 * @return an {@code IIOMetadata} object, 142 * or {@code null} if the plug-in does not provide 143 * metadata encoding capabilities. 144 * 145 * @exception IllegalArgumentException if either of 146 * {@code inData} or {@code imageType} is 147 * {@code null}. 148 */ 149 IIOMetadata convertImageMetadata(IIOMetadata inData, 150 ImageTypeSpecifier imageType, 151 ImageWriteParam param); 152} 153