Streams

The new seekable classes are used to cache the image data being read so that methods can be used to seek backwards and forwards through the data without having to re-read the data. This is especially important for image data types that are segmented or that cannot be easily re-read to locate important information.

Class: SeekableStream
Extends: InputStream
Implements: DataInput
An abstract class that combines the functionality of InputStream and RandomAccessFile, along with the ability to read primitive data types in little-endian format.

Class: FileSeekableStream
Extends: SeekableStream
Implements SeekableStream functionality on data stored in a File.

Class: ByteArraySeekableStream
Extends: SeekableStream
Implements SeekableStream functionality on data stored in an array of bytes.

Class: SegmentedSeekableStream
Extends: SeekableStream
Provides a view of a subset of another SeekableStream consisting of a series of segments with given starting positions in the source stream and lengths. The resulting stream behaves like an ordinary SeekableStream.

Class: ForwardSeekableStream
Extends: SeekableStream
Provides SeekableStream functionality on data from an InputStream with minimal overhead, but does not allow seeking backwards. ForwardSeekableStream may be used with input formats that support streaming, avoiding the need to cache the input data.

Class: FileCacheSeekableStream
Extends: SeekableStream
Provides SeekableStream functionality on data from an InputStream with minimal overhead, but does not allow seeking backwards. ForwardSeekableStream may be used with input formats that support streaming, avoiding the need to cache the input data. In circumstances that do not allow the creation of a temporary file (for example, due to security consideration or the absence of local disk), the MemoryCacheSeekableStream class may be used.

Class: MemoryCacheSeekableStream
Extends: SeekableStream
Provides SeekableStream functionality on data from an InputStream, using an in-memory cache to allow seeking backwards. MemoryCacheSeekableStream should be used when security or lack of access to local disk precludes the use of FileCacheSeekableStream.

A complete list of the methods to read data:
readInt: Reads a signed 32-bit integer
readIntLE: Reads a signed 32-bit integer in little-endian order
readShort: Reads a signed 16-bit number
readShortLE: Reads a 16-bit number in little-endian order
readLong: Reads a signed 64-bit integer
readLongLE: Reads a signed 64-bit integer in little-endian order
readFloat: Reads a 32-bit float
readFloatLE: Reads a 32-bit float in little-endian order
readDouble: Reads a 64-bit double
readDoubleLE: Reads a 64-bit double in little-endian order
readChar: Reads a 16-bit Unicode character
readCharLE: Reads a 16-bit Unicode character in little-endian order
readByte: Reads an signed 8-bit byte
readBoolean: Reads a Boolean value
readUTF: Reads a string of characters in UTF (Unicode Text Format)
readUnsignedShort: Reads an unsigned 16-bit short integer
readUnsignedShortLE: Reads an unsigned 16-bit short integer in little-endian order
readUnsignedInt: Reads an unsigned 32-bit integer
readUnsignedIntLE: Reads an unsigned 32-bit integer in little-endian order
readUnsignedByte: Reads an unsigned 8-bit byte
readLine: Reads in a line that has been terminated by a line-termination character.
readFully: Reads a specified number of bytes, starting at the current stream pointer
read(): Reads the next byte of data from the input stream.

In addition to the familiar methods from InputStream, the methods getFilePointer() and seek(), are defined as in the RandomAccessFile class. The canSeekBackwards() method returns true if it is permissible to seek to a position earlier in the stream than the current value of getFilePointer(). Some subclasses of SeekableStream guarantee the ability to seek backwards while others may not offer this feature in the interest of efficiency for those users who do not require backward seeking.

Several concrete subclasses of SeekableStream are supplied in the com.sun.media.jai.codec package. Three classes are provided for the purpose of adapting a standard InputStream to the SeekableStream interface. The ForwardSeekableStream class does not allow seeking backwards, but is inexpensive to use. The FileCacheSeekableStream class maintains a copy of all of the data read from the input in a temporary file; this file will be discarded automatically when the FileSeekableStream is finalized, or when the JVM exits normally.

The FileCacheSeekableStream class is intended to be reasonably efficient apart from the unavoidable use of disk space. In circumstances where the creation of a temporary file is not possible, the MemoryCacheSeekableStream class may be used. The MemoryCacheSeekableStream class creates a potentially large in-memory buffer to store the stream data and so should be avoided when possible. The FileSeekableStream class wraps a File or RandomAccessFile. It forwards requests to the real underlying file. FileSeekableStream performs a limited amount of caching to avoid excessive I/O costs.

A convenience method, wrapInputStream is provided to construct a suitable SeekableStream instance whose data is supplied by a given InputStream. The caller, by means of the canSeekBackwards parameter, determines whether support for seeking backwards is required.