Java(TM) Image I/O API Early Access 2
README

Contents

   * System Requirements
   * What's New
   * Installation Instructions
   * Release Notes
   * Prior Release Notes
   * Questions, Feedback, and Reporting Bugs

                             System Requirements

The Java(TM) Image I/O API early access implementation is designed to run on
the Java(TM) 2 Platform, Standard Edition (J2SE). There are no particular
processor speed or memory requirements beyond those necessary to run the
Java(TM) platform.

The early access implementation has been tested mainly on Sun's production
Java(TM) 2 SDK implementations:

   * Java 2 SDK, Standard Edition, v 1.2.2, Windows 95/98/NT Production
     Release
   * Java 2 SDK, Standard Edition, v 1.2.2, Solaris Production Release
   * Java 2 SDK, Standard Edition, v 1.3, Windows 95/98/NT Production
     Release

Other Java 2 SDK implementations may work as well; we would appreciate
feedback on working and non-working configurations.

                                 What's New

The EA2 release provides many improvements over the prior release:

   * An entirely new metadata model based on XML
   * PNG writing capability
   * Ability to abort reads or writes in progress
   * More sophisticated writing options including editing capabilities
   * Better control over writing
   * Ability to attach a "controller" object to an ImageReadParam,
     ImageWriteParam, or IIOMetadata object.
   * Additional classes for future JPEG support
   * More consistent event handling
   * Imporved and simplified registry including preferences
   * More consistent handling of stream cacheing.
   * Performance enhancements for GIF and PNG reading

See the release notes for more detailed information on the differences
between the EA1 and EA2 releases.

                          Installation Instructions

A Java SDK, or Java Software Development Kit, contains all the files needed
to both develop and run Java programs. A JRE, or Java(TM) Runtime Environment,
contains the files needed to run but not to develop Java applications.

The Java API for XML Parsing (JAXP), version 1.0.1, is required by the EA2
implementation. This requirement is only for the early access version, in
order to allow it to run on current versions of the Java 2 platform.

The JAXP reference implementation may be downloaded from
http://java.sun.com/xml/download.html, and should be installed into the same
Java Runtime Environment (JRE) as the Image I/O API. Installation
instructions may be found at http://java.sun.com/xml/install.html.

The Java SDK or JRE in which the Image I/O API early access implementation
is to be installed must be version 1.2.2 or later, or the implementation
will not operate correctly.

Unpacking the Files

The downloaded file must first be unpacked.

Windows:

     Download the .zip file and use a program such as WinZip, InfoZip,
     or pcunzip to extract its component files.

Solaris:

     To unpack the .Z compressed .tar file, enter the following command
     at your command prompt:

             uncompress -c imageio-1_0-ea2.tar.Z | tar xf -


     To unpack the .gz compressed file, enter the following command at
     your command prompt:

             gunzip -c imageio-1_0-ea2.tar.gz | tar xf -


Installation into an SDK

Windows:

     Assuming the SDK is located in the C:\jdk1.3 directory, use an
     MS-DOS command such as:

             copy imageio.jar C:\jdk1.3\jre\lib\ext


     or use the Windows Explorer program to move the icon representing
     imageio.jar into the desired directory.

Solaris:

     Assuming the SDK is located in the /usr/jdk1.3 directory, use a
     shell command such as:

             cp imageio.jar /usr/jdk1.3/jre/lib/ext


     to install the JAR file.

Installation into a JRE

Windows:

     Assuming the JRE is located in the C:\Program
     Files\JavaSoft\JRE\1.3 directory, use an MS-DOS command (on one
     line) such as:

             copy imageio.jar
                "C:\Program Files\JavaSoft\JRE\1.3\lib\ext"


     or use the Windows Explorer program to move the icon representing
     imageio.jar into the desired directory.

Solaris:

     Assuming the JRE is located in the /usr/jre/1.3 directory, use a
     shell command such as:

             cp imageio.jar /usr/jre/1.3/lib/ext


     to install the JAR file.

Unpacking the source code

The source code JAR file (imageio-src.jar) may be unpacked using the jar
program found in the bin directory of the Java 2 SDK or any zip-compatible
utility:

             jar xf imageio-src.jar


You do not need to unpack the implementation JAR file (imageio.jar); leave
it in JAR form.

                                Release Notes

                               General Notes

All package names have been changed from javax.media.imageio.* to
javax.imageio.* in order to fit better into the J2SDK naming scheme. The
package names will not change again.

A new package, javax.imageio.plugins.jpeg, has been added. It contains
classes for use with the standard JPEG plug-in. The plug-in itself is not
included in the EA2 release, but will appear in the final release.

                           javax.imageio package

   * ImageReader

        o An abort method was added to ImageReader and ImageWriter, which
          allows a read or write in progress to be stopped by another
          thread.
        o The ImageReader.getNumImages method takes an additional
          allowSearch argument to prevent the entire stream from being read
          for formats that do not store the number of images in the header.
        o ImageReader now supports a query to determine whether random
          access to pixel data using an ImageReadParam within an image is
          efficient.
        o ImageReader now has a getAspectRatio method for use with resizable
          image formats.
        o A new method ImageReader.canReadRaster was added; if it returns
          false, readRasterwill throw an UnsupportedOperationException.

   * ImageWriter

        o ImageWriter now provides support for a number of different styles
          of writing:
             + Appending a complete image file to an output stream;
             + Appending image data only (no header data) to an output
               stream;
             + Replacing the stream metadata of an existing image file;
             + Replacing image metadata within an existing image file;
             + Inserting an image into an existing image file;
             + Inserting a blank image into an existing image file;
             + Replacing pixels of an image within an existing image file.
        o ImageWriter now supports preferred thumbnail size queries.
        o A new method ImageWriter.canWriteRasters was added; if it returns
          false, the use of Raster sources will throw an
          UnsupportedOperationException.

   * ImageIO

        o The ImageIO class was cleaned up. Methods that return an Iterator
          previously returned null to indicate the absence of results, and
          now return an empty Iterator.
        o Support in the ImageIO class for old-style image loading using the
          AWT Image class, and the ImageProducer interface, has been
          removed.

   * ImageReadParam and ImageWriteParam

        o ImageReadParam and ImageWriteParam now share a common IIOParam
          superinterface.
        o ImageReadParam now allows full control over the range of
          progressive passes to be decoded.
        o The names of some methods in ImageReadParam dealing with resizable
          imagery have been changed in order to clarify their function.
        o ImageWriteParam has been redesigned to allow control over whether
          a particular feature (tiling, progressive encoding, or
          compression) is disabled, set to a default value, set explictly,
          or copied from metadata.
        o ImageWriteParam may be queried for tiling support, including
          preferred tile sizes.
        o ImageWriteParam now supports control over compression methods and
          quality.
        o Some method arguments of IIOParam have been changed to use
          geometric classes (Point, Dimension, and Rectangle) instead of
          passing individual coordinates and dimensions.
        o The semantics of the source and destination band settings in
          IIOParam have been simplified.
        o IIOParam now supports a pair of subsampling offsets which control
          the relationship between the start of the region being read or
          written and the start of the subsampled region.
        o IIOParam supports the concept of an IIOParamController, which
          provides a graphical or other interface for an ImageReadParam or
          ImageWriteParam.

   * Miscellaneous

        o An IIOImage may now contain a Raster source.
        o IIOException is now a subclass of IOException.
        o UnsupportedImageParamException has been removed.
        o ImageTranscoder now takes the place of its former superinterface,
          IIOMetadataConverter.
        o Localization has been simplified for ImageReaders and
          ImageWriters.

                        javax.imageio.event package

   * An additional BufferedImage source argument was added to a number of
     event listener methods to provide then with access to the image being
     decoded.
   * IIOReadUpdateListener now receives information about the range of
     progressive passes being decoded, and about thumbnail updates.
   * IIOReadWarningListener and IIOWriteWarningListener no longer deal with
     Locales. Instead, a Locale may be set on the ImageReader or ImageWriter
     prior to attaching the listener.

                       javax.imageio.metadata package

   * The handling of metadata has changed substantially. The IIOReadInfo and
     IIOWriteSpecifier interfaces and the various classes that implemented
     them are no longer present. Instead, access to metadata is via XML DOM
     (Document Object Model) structures obtained from an IIOMetadata object.
   * A new interface, IIOMetadataFormat, describes the syntax of the DOM
     trees created and used by plug-ins. An implementation class,
     IIOMetadataFormatImpl, is provided.
   * The various enumerations in the metadata package have been removed from
     the API, and are replaced by string constants in the XML Document Type
     Definitions (DTDs) of the standard metadata format.
   * A new interface, IIOMetadataController, allows graphical or other user
     interfaces to be attached to IIOMetadata objects.

                         javax.imageio.spi package

   * The registry was simplified to use a Filter interface to perform
     general queries instead of hard-wiring a particular set of queries.
   * The concept of a preferred writer has been dropped. Instead, a more
     general notion of preferences between serive providers is available.
   * The ImageReaderSpi.canDecodeInput method is now responsible for
     restoring the seek offset of the stream.
   * Reader and writer SPIs can be queried for the metadata formats they
     support.
   * The ImageReaderSpi.createReaderInstance and
     ImageWriterSpi.createWriterInstance methods have been made abstract,
     whereas previously they contained a reflection-based implementation.
   * The ImageWriterSpi.getBestImageTypeSpecifiers method has been removed.
   * ImageTranscoderSpi now provides the class names of its associated
     ImageReaderSpi and ImageWriterSpi instead of live references.
   * All Spi classes now have a protected no-args constructor.

                        javax.imageio.stream package

   * The AbstractImageInputStream and AbstractImageOutputStream classes were
     renamed to ImageInputStreamImpl and ImageOutputStreamImpl.
   * Implementations are now present for all input and output stream
     classes.
   * A FileCacheImageOutputStream class was added.
   * The URLImageInputStream class was removed.
   * Non-bit reads and writes now reset the bit offset to 0.
   * Non-bit writes cause unwritten bits to be padded with 0 bits up to a
     byte boundary, and flushed.
   * All streams now support cache status queries.

                                  Plug-ins

   * A PNG writer plug-in is now present.
   * The PNG and GIF readers have been sped up.
   * The PNM reader plug-in has been withdrawn as it will not be part of the
     standard set of plug-ins.

                             Prior Release Notes

The release notes for the prior release (EA1) are made available for
reference. They do not reflect the current state of the specification or
implementation.
                                 EA1 Release

As this is an early access release, not all of the specification has been
implemented. The main purpose of the implementation is to act as a testbed
for the evolution of the specification. We are sharing this prototype
implementation with the developer community in order to allow the community
to gain a greater understanding of the intent of the specification and to
evaluate the usefulness of the API.

There are a number of known bugs and limitations in the EA1 implementation:

   * Core framework

        o The getImageProducer and readAWTImage methods in ImageIO are not
          implemented.
        o The Banded case of ImageTypeSpecifier is non-functional.
        o MemoryCacheImageInputStream and URLImageInputStream are not
          implemented.
        o FileCacheImageInputStream has been implemented but not tested.
        o There are no concrete implementations of ImageOutputStream.

   * GIF reader plug-in

        o The end of some animated GIFs is not detected correctly, resulting
          in an incorrect frame count.
        o The GIFMetadata class does not provide any IIOReadInfo objects.
        o The source and destination bands in the ImageReadParam are
          ignored.

   * PNG reader plug-in

        o A very slow algorithm is used to perform subsampling requested via
          an ImageReadParam.
        o The source and destination bands in the ImageReadParam are
          ignored.
        o The PNGImageMetadata and PNGStreamMetadata classed do not provide
          any IIOReadInfo objects.

   * PNM plug-in

        o Only bitmap and grayscale images are currently implemented.
        o The ImageReadParam is ignored.
        o Although a source file called 'PNMImageWriter' exists, it is
          non-functional.

                   Questions, Feedback, and Reporting Bugs

We encourage all developers of the Java programming language to examine the
Java Image I/O specification and early access implementation and to send
questions and comments to the development team. However, please consult the
list of answers to frequently asked questions (FAQ) before sending in your
question.

Please send messages to either the comments or interest alias; do not send
messages to individual team members. This will help us respond in a more
timely manner. Please note that we may not be able to respond to every
message individually.

To submit comments on the Java Image I/O specification, send email to
java-imageio-comments@eng.sun.com. Only members of the Image I/O team at Sun
can read messages sent to this alias.

To submit questions about the Java Image I/O Specification, use the public
interest group list. The interest group list is available for communication
with both the team and the other members of the mailing list. You must
subscribe before posting messages to the mailing list.

Subscribing

To subscribe to the interest group, send email with:

     subscribe java-imageio-interest YOUR NAME

For example:

     subscribe java-imageio-interest Albert Einstein

in the message body to listserv@java.sun.com.

Receiving the Digest Version

If you would rather receive messages sent to java-imageio-interest in digest
form, send email with:

     SET JAVA-IMAGEIO-INTEREST DIG

in the message body to listserv@java.sun.com.

Sending Messages

To send messages to the interest group, send email to
java-imageio-interest@java.sun.com.

Unsubscribing

To unsubscribe from the interest group, send email with:

     signoff java-imageio-interest

in the message body to listserv@java.sun.com.

Reporting Bugs

To report a bug or request a feature, file a bug report at
http://java.sun.com/cgi-bin/EAbugreport.cgi.
