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 
  26 package javax.imageio;
  27 
  28 import 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  */
  86 public 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 }
--- EOF ---