PIRL.Image_Tools

## Class Multibuf_ImageInputStream

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

All Implemented Interfaces:
  Closeable, DataInput, AutoCloseable, 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.

See Also:
  `ImageInputStream`

### Field Summary

Fields
`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

Constructors
Constructor and Description
`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

Methods
`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 `Add`ed 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 `Closeable`
Specified by:
  `close` in interface `AutoCloseable`
Specified by:
  `close` in interface `ImageInputStream`
Overrides:
  `close` in class `ImageInputStreamImpl`