PIRL.Image_Tools
Class Multibuf_ImageInputStream

java.lang.Object
  javax.imageio.stream.ImageInputStreamImpl
      PIRL.Image_Tools.Multibuf_ImageInputStream

All Implemented Interfaces:

DataInput, ImageInputStream

public class Multibuf_ImageInputStream
extends ImageInputStreamImpl

An Multibuf_ImageInputStream provides an ImageInputStream interface to a List of ByteBuffers.

The buffer list is thread-safe.

Version:

1.8

Author:

Bradford Castalia UA/PIRL

See Also:

ImageInputStream

Field Summary

protected long	Buffer_Location Virtual stream location of the Data_Buffer
protected ByteBuffer	Data_Buffer Current image data buffer.
static String	ID

Fields inherited from class javax.imageio.stream.ImageInputStreamImpl

bitOffset, byteOrder, flushedPos, streamPos

Constructor Summary

Multibuf_ImageInputStream()
Construct an empty Multibuf_ImageInputStream.

Multibuf_ImageInputStream(ByteBuffer buffer)
Construct a Multibuf_ImageInputStream that initial contains a single ByteBuffer.

Multibuf_ImageInputStream(List buffers)
Construct a Multibuf_ImageInputStream on a List of ByteBuffers.

Method Summary

Multibuf_ImageInputStream	Add(ByteBuffer buffer) Add a ByteBuffer to the list of buffers providing stream data.
Multibuf_ImageInputStream	Add(Multibuf_ImageInputStream stream) Add the contents of another Multibuf_ImageInputStream to this Multibuf_ImageInputStream.
void	close() Pretends to close the stream.
boolean	Contains(ByteBuffer buffer) Test if the specified buffer is contained in the buffers list.
List	Data_Buffers() Get the List of data buffers backing this object.
void	flushBefore(long location) Suggests that data before a source location may be discared.
boolean	isCached() Determine if the source data is cached.
boolean	isCachedMemory() Determine if the source data is cached in memory.
long	length() Get the total size of all the buffer contents.
protected boolean	Next_Buffer() Set the next buffer as the current buffer.
protected boolean	Previous_Buffer() Set the previous data buffer as the current buffer.
int	read() Read a source byte.
int	read(byte[] data, int offset, int length) Read a sequence of source bytes and store them in an array.
Multibuf_ImageInputStream	Remove(ByteBuffer buffer) Remove the specified buffer from the buffers list.
Multibuf_ImageInputStream	Remove(int index) Remove a buffer from the buffers list.
void	seek(long location) Set the current source stream location where the next byte will be read.

Methods inherited from class javax.imageio.stream.ImageInputStreamImpl

checkClosed, finalize, flush, getBitOffset, getByteOrder, getFlushedPosition, getStreamPosition, isCachedFile, mark, read, readBit, readBits, readBoolean, readByte, readBytes, readChar, readDouble, readFloat, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readFully, readInt, readLine, readLong, readShort, readUnsignedByte, readUnsignedInt, readUnsignedShort, readUTF, reset, setBitOffset, setByteOrder, skipBytes, skipBytes

Methods inherited from class java.lang.Object

clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

ID

public static final String ID

See Also:

Constant Field Values

Data_Buffer

protected ByteBuffer Data_Buffer

Current image data buffer.

The Data_Buffer contains the current data accessed by the ImageInputStream interface. It's position is where the next ImageInputStream read byte will be obtained; this is equivalent to the virtual stream location. It's limit is the end of valid source data in the buffer (the buffer may not be full to capacity).

Buffer_Location

protected long Buffer_Location

Virtual stream location of the Data_Buffer

The first byte of the buffer is located at Buffer_Location offset in the stream.

Constructor Detail

Multibuf_ImageInputStream

public Multibuf_ImageInputStream(List buffers)
                          throws IllegalArgumentException

Construct a Multibuf_ImageInputStream on a List of ByteBuffers.

Parameters:

buffers - The List of ByteBuffers to use to use as the data source in the order they occur in the List.

Throws:

IllegalArgumentException - If the List contains a non-null Object that is not a.ByteBuffer instance.

See Also:

Add(ByteBuffer)

Multibuf_ImageInputStream

public Multibuf_ImageInputStream(ByteBuffer buffer)

Construct a Multibuf_ImageInputStream that initial contains a single ByteBuffer.

Parameters:

buffer - The ByteBuffer to provide stream data.

See Also:

Add(ByteBuffer)

Multibuf_ImageInputStream

public Multibuf_ImageInputStream()

Construct an empty Multibuf_ImageInputStream.

Method Detail

Add

public Multibuf_ImageInputStream Add(ByteBuffer buffer)

Add a ByteBuffer to the list of buffers providing stream data.

If the buffer is null or empty (zero limit) it is ignored.

A duplicate of the buffer (pointers are copied, data is not) is added to the end of the buffers list and rewound (position set to zero). The length of the stream is incremented by the amount of data (limit) in the buffer. If a current buffer has not be set the new buffer is set as the current buffer.

Parameters:

buffer - The ByteBuffer to be added to the buffers list.

Returns:

This Multibuf_ImageInputStream.

Add

public Multibuf_ImageInputStream Add(Multibuf_ImageInputStream stream)

Add the contents of another Multibuf_ImageInputStream to this Multibuf_ImageInputStream.

Each data buffer in the source stream is Added to the end of the list of data buffers in this stream in the order in which they are listed.

Returns:

This Multibuf_ImageInputStream.

Contains

public boolean Contains(ByteBuffer buffer)

Test if the specified buffer is contained in the buffers list.

Warning: The ByteBuffer.equals(Object) method is used to compare the specified buffer against the contents of the buffers list. This compares the structure and contents of the buffers, not their object reference values. This can be expensive for large and/or many buffers. It will also test true if a buffer in the list happens to have the same content as the specified buffer even if the buffer objects are different.

Parameters:

buffer - The ByteBuffer to test for.

Returns:

true if the specified buffer equals some other

Remove

public Multibuf_ImageInputStream Remove(int index)
                                 throws ArrayIndexOutOfBoundsException

Remove a buffer from the buffers list.

The indexed buffer is removed from the buffers list and the length of the stream decremented by the amount of data (limit) in the buffer.

If the index of the removed buffer is less than the index of the current buffer the current stream position and current buffer location are decremented by the amount of data in the removed buffer.

If the index of the removed buffer is equal to the index of the current buffer the current stream position is set to the current buffer location. If there is another buffer in the buffers list following the removed buffer, the next buffer is set as the current buffer; thus the fist byte of the next available buffer will be the next byte read (unless the stream position is moved). However, if there is no next buffer - the removed buffer is at the end of the buffers list - but there is a buffer in the buffers list immediately preceeding the removed buffer, then the previous buffer becomes the current buffer and its position is set to its end (limit); thus the stream position is now st the end of the stream. Finally, if the removed buffer is the last one in the buffers list the current buffer is set to null and all pointers are at zero which is the end of the (now empty) stream.

Parameters:

index - The index of the buffer to be removed.

Returns:

This Multibuf_ImageInputStream.

Throws:

ArrayIndexOutOfBoundsException - If the specified index is less than zero or greater than or equal to the size of the buffers list.

Remove

public Multibuf_ImageInputStream Remove(ByteBuffer buffer)

Remove the specified buffer from the buffers list.

Warning: The specified buffer is sought using the List.indexOf(Object) method on the list of data buffers which employs the ByteBuffer.equals(Object) method. See the Contains method for details.

Parameters:

buffer - The ByteBuffer to be removed.

Returns:

This Multibuf_ImageInputStream.

See Also:

Remove(int)

Data_Buffers

public List Data_Buffers()

Get the List of data buffers backing this object.

Caution: Modifying the contents of the list by reordering or adding to the List, or changing the amount of valid data in a buffer (its limit) could invalidate the current stream position and/or stream length information with indeterminate (i.e. bad) consequences. Use the Add and Remove methods to safely manipulate the data buffer List.

Returns:

The List of ByteBuffer objects backing this Multibuf_ImageInputStream.

Next_Buffer

protected boolean Next_Buffer()

Set the next buffer as the current buffer.

A next buffer is present if the current buffer index plus one is less than the size of the buffers list. In this case the Buffer_Location is incremented by the amount of data (limit) in the current buffer, the buffer index is incremented and the correspoding buffer from the buffer list is set as the current Data_Buffer. It's position is rewound to zero.

Returns:

true if a next buffer has been set; false if there is no next buffer.

Previous_Buffer

protected boolean Previous_Buffer()

Set the previous data buffer as the current buffer.

If the current buffer index in the buffers list is not zero, the buffer index is decremented and the corresponding buffer from the buffer list is set as the current Data_Buffer. It's position remains unchanged. The Buffer_Location is decremented by the amount of data (limit) in the new buffer.

Returns:

true if a previous buffer has been set; false if there is no previous buffer.

read

public int read()

Read a source byte.

The bit offset is set to zero.

Specified by:

read in interface ImageInputStream

Specified by:

read in class ImageInputStreamImpl

Returns:

The next byte value from the source. This will be -1 if the current source location is the end of the stream.

read

public int read(byte[] data,
                int offset,
                int length)

Read a sequence of source bytes and store them in an array.

The number of bytes actually read may be less than the specified length. The length will be reduced to the smaller of the amount of space in the data array following the offset or the amount of buffered data remaining after an attempt to provide length bytes.

The bit offset is set to zero.

The current source input location is advanced by the amount of data read.

Specified by:

read in interface ImageInputStream

Specified by:

read in class ImageInputStreamImpl

Parameters:

data - The byte array into which the data is to be stored.

offset - The offset of the array where the first byte read is to be stored.

length - The number of bytes to read.

Returns:

The number of bytes read and stored. This will be -1 if the current source location is the end of the stream.

Throws:

NullPointerException - If the data array is null.

IndexOutOfBoundsException - If the offset or length are negative, or the offset is greater than the length of the data array.

seek

public void seek(long location)

Set the current source stream location where the next byte will be read.

The bit offset is set to zero.

Specified by:

seek in interface ImageInputStream

Overrides:

seek in class ImageInputStreamImpl

Parameters:

location - The source stream offset for the next read position. A location less than zero will be set to zero; a location greater than the source stream size will be set to the end of the source stream.

isCached

public boolean isCached()

Determine if the source data is cached.

Specified by:

isCached in interface ImageInputStream

Overrides:

isCached in class ImageInputStreamImpl

Returns:

true

isCachedMemory

public boolean isCachedMemory()

Determine if the source data is cached in memory.

Specified by:

isCachedMemory in interface ImageInputStream

Overrides:

isCachedMemory in class ImageInputStreamImpl

Returns:

true

length

public long length()

Get the total size of all the buffer contents.

Specified by:

length in interface ImageInputStream

Overrides:

length in class ImageInputStreamImpl

Returns:

The size of the source stream.

flushBefore

public void flushBefore(long location)

Suggests that data before a source location may be discared.

N.B.: No buffered data is ever discared; the suggestion is ignored.

Specified by:

flushBefore in interface ImageInputStream

Overrides:

flushBefore in class ImageInputStreamImpl

Parameters:

location - The source stream offset before which buffered data may be discarded.

close

public void close()

Pretends to close the stream.

Nothing is done since the source data is externally owned.

Specified by:

close in interface ImageInputStream

Overrides:

close in class ImageInputStreamImpl