Java example source code file (IIOImage.java)

This example Java source code file (IIOImage.java) is included in the alvinalexander.com "Java Source Code Warehouse" project. The intent of this project is to help you "Learn Java by Example" ^TM.

Learn more about this Java project at its project page.

Java - Java tags/keywords

awt, bufferedimage, iioimage, iiometadata, illegalargumentexception, image, indexoutofboundsexception, list, raster, renderedimage, util

The IIOImage.java Java example source code

/*
 * Copyright (c) 2000, 2004, Oracle and/or its affiliates. All rights reserved.
 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
 *
 * This code is free software; you can redistribute it and/or modify it
 * under the terms of the GNU General Public License version 2 only, as
 * published by the Free Software Foundation.  Oracle designates this
 * particular file as subject to the "Classpath" exception as provided
 * by Oracle in the LICENSE file that accompanied this code.
 *
 * This code is distributed in the hope that it will be useful, but WITHOUT
 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
 * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
 * version 2 for more details (a copy is included in the LICENSE file that
 * accompanied this code).
 *
 * You should have received a copy of the GNU General Public License version
 * 2 along with this work; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
 *
 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
 * or visit www.oracle.com if you need additional information or have any
 * questions.
 */

package javax.imageio;

import java.awt.image.BufferedImage;
import java.awt.image.Raster;
import java.awt.image.RenderedImage;
import java.util.List;
import javax.imageio.metadata.IIOMetadata;

/**
 * A simple container class to aggregate an image, a set of
 * thumbnail (preview) images, and an object representing metadata
 * associated with the image.
 *
 * <p> The image data may take the form of either a
 * <code>RenderedImage, or a Raster.  Reader
 * methods that return an <code>IIOImage will always return a
 * <code>BufferedImage using the RenderedImage
 * reference.  Writer methods that accept an <code>IIOImage
 * will always accept a <code>RenderedImage, and may optionally
 * accept a <code>Raster.
 *
 * <p> Exactly one of getRenderedImage and
 * <code>getRaster will return a non-null value.
 * Subclasses are responsible for ensuring this behavior.
 *
 * @see ImageReader#readAll(int, ImageReadParam)
 * @see ImageReader#readAll(java.util.Iterator)
 * @see ImageWriter#write(javax.imageio.metadata.IIOMetadata,
 *                        IIOImage, ImageWriteParam)
 * @see ImageWriter#write(IIOImage)
 * @see ImageWriter#writeToSequence(IIOImage, ImageWriteParam)
 * @see ImageWriter#writeInsert(int, IIOImage, ImageWriteParam)
 *
 */
public class IIOImage {

    /**
     * The <code>RenderedImage being referenced.
     */
    protected RenderedImage image;

    /**
     * The <code>Raster being referenced.
     */
    protected Raster raster;

    /**
     * A <code>List of BufferedImage thumbnails,
     * or <code>null.  Non-BufferedImage objects
     * must not be stored in this <code>List.
     */
    protected List<? extends BufferedImage> thumbnails = null;

    /**
     * An <code>IIOMetadata object containing metadata
     * associated with the image.
     */
    protected IIOMetadata metadata;

    /**
     * Constructs an <code>IIOImage containing a
     * <code>RenderedImage, and thumbnails and metadata
     * associated with it.
     *
     * <p> All parameters are stored by reference.
     *
     * <p> The thumbnails argument must either be
     * <code>null or contain only BufferedImage
     * objects.
     *
     * @param image a <code>RenderedImage.
     * @param thumbnails a <code>List of BufferedImages,
     * or <code>null.
     * @param metadata an <code>IIOMetadata object, or
     * <code>null.
     *
     * @exception IllegalArgumentException if <code>image is
     * <code>null.
     */
    public IIOImage(RenderedImage image,
                    List<? extends BufferedImage> thumbnails,
                    IIOMetadata metadata) {
        if (image == null) {
            throw new IllegalArgumentException("image == null!");
        }
        this.image = image;
        this.raster = null;
        this.thumbnails = thumbnails;
        this.metadata = metadata;
    }

    /**
     * Constructs an <code>IIOImage containing a
     * <code>Raster, and thumbnails and metadata
     * associated with it.
     *
     * <p> All parameters are stored by reference.
     *
     * @param raster a <code>Raster.
     * @param thumbnails a <code>List of BufferedImages,
     * or <code>null.
     * @param metadata an <code>IIOMetadata object, or
     * <code>null.
     *
     * @exception IllegalArgumentException if <code>raster is
     * <code>null.
     */
    public IIOImage(Raster raster,
                    List<? extends BufferedImage> thumbnails,
                    IIOMetadata metadata) {
        if (raster == null) {
            throw new IllegalArgumentException("raster == null!");
        }
        this.raster = raster;
        this.image = null;
        this.thumbnails = thumbnails;
        this.metadata = metadata;
    }

    /**
     * Returns the currently set <code>RenderedImage, or
     * <code>null if only a Raster is available.
     *
     * @return a <code>RenderedImage, or null.
     *
     * @see #setRenderedImage
     */
    public RenderedImage getRenderedImage() {
        synchronized(this) {
            return image;
        }
    }

    /**
     * Sets the current <code>RenderedImage.  The value is
     * stored by reference.  Any existing <code>Raster is
     * discarded.
     *
     * @param image a <code>RenderedImage.
     *
     * @exception IllegalArgumentException if <code>image is
     * <code>null.
     *
     * @see #getRenderedImage
     */
    public void setRenderedImage(RenderedImage image) {
        synchronized(this) {
            if (image == null) {
                throw new IllegalArgumentException("image == null!");
            }
            this.image = image;
            this.raster = null;
        }
    }

    /**
     * Returns <code>true if this IIOImage stores
     * a <code>Raster rather than a RenderedImage.
     *
     * @return <code>true if a Raster is
     * available.
     */
    public boolean hasRaster() {
        synchronized(this) {
            return (raster != null);
        }
    }

    /**
     * Returns the currently set <code>Raster, or
     * <code>null if only a RenderedImage is
     * available.
     *
     * @return a <code>Raster, or null.
     *
     * @see #setRaster
     */
    public Raster getRaster() {
        synchronized(this) {
            return raster;
        }
    }

    /**
     * Sets the current <code>Raster.  The value is
     * stored by reference.  Any existing <code>RenderedImage is
     * discarded.
     *
     * @param raster a <code>Raster.
     *
     * @exception IllegalArgumentException if <code>raster is
     * <code>null.
     *
     * @see #getRaster
     */
    public void setRaster(Raster raster) {
        synchronized(this) {
            if (raster == null) {
                throw new IllegalArgumentException("raster == null!");
            }
            this.raster = raster;
            this.image = null;
        }
    }

    /**
     * Returns the number of thumbnails stored in this
     * <code>IIOImage.
     *
     * @return the number of thumbnails, as an <code>int.
     */
    public int getNumThumbnails() {
        return thumbnails == null ? 0 : thumbnails.size();
    }

    /**
     * Returns a thumbnail associated with the main image.
     *
     * @param index the index of the desired thumbnail image.
     *
     * @return a thumbnail image, as a <code>BufferedImage.
     *
     * @exception IndexOutOfBoundsException if the supplied index is
     * negative or larger than the largest valid index.
     * @exception ClassCastException if a
     * non-<code>BufferedImage object is encountered in the
     * list of thumbnails at the given index.
     *
     * @see #getThumbnails
     * @see #setThumbnails
     */
    public BufferedImage getThumbnail(int index) {
        if (thumbnails == null) {
            throw new IndexOutOfBoundsException("No thumbnails available!");
        }
        return (BufferedImage)thumbnails.get(index);
    }

    /**
     * Returns the current <code>List of thumbnail
     * <code>BufferedImages, or null if none is
     * set.  A live reference is returned.
     *
     * @return the current <code>List of
     * <code>BufferedImage thumbnails, or null.
     *
     * @see #getThumbnail(int)
     * @see #setThumbnails
     */
    public List<? extends BufferedImage> getThumbnails() {
        return thumbnails;
    }

    /**
     * Sets the list of thumbnails to a new <code>List of
     * <code>BufferedImages, or to null.  The
     * reference to the previous <code>List is discarded.
     *
     * <p> The thumbnails argument must either be
     * <code>null or contain only BufferedImage
     * objects.
     *
     * @param thumbnails a <code>List of
     * <code>BufferedImage thumbnails, or null.
     *
     * @see #getThumbnail(int)
     * @see #getThumbnails
     */
    public void setThumbnails(List<? extends BufferedImage> thumbnails) {
        this.thumbnails = thumbnails;
    }

    /**
     * Returns a reference to the current <code>IIOMetadata
     * object, or <code>null is none is set.
     *
     * @return an <code>IIOMetadata object, or null.
     *
     * @see #setMetadata
     */
    public IIOMetadata getMetadata() {
        return metadata;
    }

    /**
     * Sets the <code>IIOMetadata to a new object, or
     * <code>null.
     *
     * @param metadata an <code>IIOMetadata object, or
     * <code>null.
     *
     * @see #getMetadata
     */
    public void setMetadata(IIOMetadata metadata) {
        this.metadata = metadata;
    }
}