com.tangosol.io

Interface ReadBuffer

All Superinterfaces:

ByteSequence, Cloneable

All Known Implementing Classes:

AbstractByteArrayReadBuffer, AbstractReadBuffer, Binary, ByteArrayReadBuffer, ByteBufferReadBuffer, ExternalizableHelper.DecoratedMultiBufferReadBuffer, MultiBufferReadBuffer

public interface ReadBuffer
extends ByteSequence, Cloneable

The ReadBuffer interface represents an in-memory block of binary data, such as that represented by a byte[], a Binary object, or an NIO buffer.

Author:

cp 2005.01.18

Nested Class Summary

Nested Classes

Modifier and Type	Interface and Description
static interface	ReadBuffer.BufferInput The BufferInput interface represents a DataInputStream on top of a ReadBuffer.

Method Summary

Modifier and Type	Method and Description
byte	byteAt(int of) Returns the byte at the specified offset.
Object	clone() Create a clone of this ReadBuffer object.
void	copyBytes(int ofBegin, int ofEnd, byte[] abDest, int ofDest) Copies bytes from this ReadBuffer into the destination byte array.
boolean	equals(Object o) Compare two ReadBuffer objects for equality.
ReadBuffer.BufferInput	getBufferInput() Get a BufferInput object to read data from this buffer.
ReadBuffer	getReadBuffer(int of, int cb) Obtain a ReadBuffer for a portion of this ReadBuffer.
int	length() Determine the length of the buffer.
ByteSequence	subSequence(int ofStart, int ofEnd) Returns a new ByteSequence that is a subsequence of this sequence.
Binary	toBinary() Return a new Binary object that holds the complete contents of this ReadBuffer.
Binary	toBinary(int of, int cb) Return a Binary object that holds the specified portion of this ReadBuffer.
byte[]	toByteArray() Get the contents of the ReadBuffer as a byte array.
byte[]	toByteArray(int of, int cb) Get a portion of the contents of the ReadBuffer as a byte array.
ByteBuffer	toByteBuffer() Return a read-only ByteBuffer view of this ReadBuffer.
ByteBuffer	toByteBuffer(int of, int cb) Return a read-only ByteBuffer view of the specified portion of this ReadBuffer.
void	writeTo(ByteBuffer buf) Write the contents of the Binary object to a ByteBuffer.
void	writeTo(ByteBuffer buf, int of, int cb) Write the contents of the Binary object to a ByteBuffer.
void	writeTo(DataOutput out) Write the contents of this ReadBuffer to a DataOutput.
void	writeTo(DataOutput out, int of, int cb) Write the contents of this ReadBuffer to a DataOutput.
void	writeTo(OutputStream out) Write the contents of this ReadBuffer to an OutputStream.
void	writeTo(OutputStream out, int of, int cb) Write the contents of the ReadBuffer to an OutputStream.

Method Detail

length

int length()

Determine the length of the buffer.

Specified by:

length in interface ByteSequence

Returns:

the number of bytes of data represented by this ReadBuffer

byteAt

byte byteAt(int of)

Returns the byte at the specified offset. An offset ranges from 0 to length() - 1. The first byte of the sequence is at offset 0, the next at offset 1, and so on, as for array indexing.

Specified by:

byteAt in interface ByteSequence

Parameters:

of - the offset (index) of the byte

Returns:

the byte at the specified offset in this ReadBuffer

Throws:

IndexOutOfBoundsException - if the of argument is negative or not less than the length of this ReadBuffer

copyBytes

void copyBytes(int ofBegin,
               int ofEnd,
               byte[] abDest,
               int ofDest)

Copies bytes from this ReadBuffer into the destination byte array.

The first byte to be copied is at offset ofBegin; the last byte to be copied is at offset ofEnd-1 (thus the total number of bytes to be copied is ofEnd - ofBegin). The bytes are copied into the sub-array of abDest starting at offset ofDest and ending at index:

     ofDest + (ofEnd - ofBegin) - 1
 

This method is the ReadBuffer equivalent of String.getChars(int, int, char[], int). It allows the caller to extract a chunk of bytes into the caller's own array.

Parameters:

ofBegin - offset of the first byte in the ReadBuffer to copy

ofEnd - offset after the last byte in the ReadBuffer to copy

abDest - the destination byte array

ofDest - the offset in the destination byte array to copy the first byte to

Throws:

IndexOutOfBoundsException - Thrown if any of the following is true:

• ofBegin is negative;
• ofBegin is greater than ofEnd
• ofEnd is greater than the length of this ReadBuffer;
• ofDest is negative
• ofDest + (ofEnd - ofBegin) is larger than abDest.length

NullPointerException - if abDest is null

getBufferInput

ReadBuffer.BufferInput getBufferInput()

Get a BufferInput object to read data from this buffer. Note that each call to this method will return a new BufferInput object, with the possible exception being that a zero-length ReadBuffer could always return the same instance (since there is nothing to read).

Returns:

a BufferInput that is reading from this buffer starting at offset zero

getReadBuffer

ReadBuffer getReadBuffer(int of,
                         int cb)

Obtain a ReadBuffer for a portion of this ReadBuffer.

Parameters:

of - the beginning index, inclusive

cb - the number of bytes to include in the resulting ReadBuffer

Returns:

a ReadBuffer that represents a portion of this ReadBuffer

Throws:

IndexOutOfBoundsException - if of or cb is negative, or of + cb is larger than the length of this ReadBuffer object

writeTo

void writeTo(OutputStream out)
      throws IOException

Write the contents of this ReadBuffer to an OutputStream.

Parameters:

out - an OutputStream to write to

Throws:

IOException - if an I/O exception occurs

writeTo

void writeTo(OutputStream out,
             int of,
             int cb)
      throws IOException

Write the contents of the ReadBuffer to an OutputStream.

Parameters:

out - an OutputStream to write to

of - the beginning index, inclusive

cb - the number of bytes to write to an OutputStream

Throws:

IOException - if an I/O exception occurs

writeTo

void writeTo(DataOutput out)
      throws IOException

Write the contents of this ReadBuffer to a DataOutput.

Parameters:

out - a DataOutput to write to

Throws:

IOException - if an I/O exception occurs

writeTo

void writeTo(DataOutput out,
             int of,
             int cb)
      throws IOException

Write the contents of this ReadBuffer to a DataOutput.

Parameters:

out - a DataOutput to write to

of - the beginning index, inclusive

cb - the number of bytes to write to a DataOutput

Throws:

IOException - if an I/O exception occurs

writeTo

void writeTo(ByteBuffer buf)

Write the contents of the Binary object to a ByteBuffer.

Parameters:

buf - a ByteBuffer to write to

writeTo

void writeTo(ByteBuffer buf,
             int of,
             int cb)
      throws IOException

Write the contents of the Binary object to a ByteBuffer.

Parameters:

buf - an ByteBuffer to write to

of - the beginning index, inclusive

cb - the number of bytes to write to a ByteBuffer

Throws:

IOException - if an I/O exception occurs

toByteArray

byte[] toByteArray()

Get the contents of the ReadBuffer as a byte array.

This is the equivalent of toByteArray(0, length()).

Returns:

a byte[] with the contents of this ReadBuffer object

toByteArray

byte[] toByteArray(int of,
                   int cb)

Get a portion of the contents of the ReadBuffer as a byte array.

This method is an equivalent of getReadBuffer(of, cb).toByteArray().

Parameters:

of - the beginning index, inclusive

cb - the number of bytes to include in the resulting byte[]

Returns:

a byte[] containing the specified portion of this ReadBuffer

Throws:

IndexOutOfBoundsException - if of or cb is negative, or of + cb is larger than the length of this ReadBuffer object

toBinary

Binary toBinary()

Return a new Binary object that holds the complete contents of this ReadBuffer.

This is the equivalent of toBinary(0, length()).

Specified by:

toBinary in interface ByteSequence

Returns:

the contents of this ReadBuffer as a Binary object

toBinary

Binary toBinary(int of,
                int cb)

Return a Binary object that holds the specified portion of this ReadBuffer.

This method is an equivalent of getReadBuffer(of, cb).toBinary().

Parameters:

of - the beginning index, inclusive

cb - the number of bytes to include in the Binary object

Returns:

a Binary object containing the specified portion of this ReadBuffer

Throws:

IndexOutOfBoundsException - if of or cb is negative, or of + cb is larger than the length of this ReadBuffer object

toByteBuffer

ByteBuffer toByteBuffer()

Return a read-only ByteBuffer view of this ReadBuffer. This view may or may not reflect any subsequent changes made to the underlying content.

Returns:

a read-only ByteBuffer view of this ReadBuffer

Since:

Coherence 12.1.2

toByteBuffer

ByteBuffer toByteBuffer(int of,
                        int cb)

Return a read-only ByteBuffer view of the specified portion of this ReadBuffer. This view may or may not reflect any subsequent changes made to the underlying content.

This method is an equivalent of getReadBuffer(of, cb).toByteBuffer().

Parameters:

of - the beginning index, inclusive

cb - the number of bytes to include in the ByteBuffer object

Returns:

a read-only ByteBuffer view of the specified portion of this ReadBuffer

Throws:

IndexOutOfBoundsException - if of or cb is negative, or of + cb is larger than the length of this ReadBuffer object

Since:

Coherence 12.1.2

subSequence

ByteSequence subSequence(int ofStart,
                         int ofEnd)

Returns a new ByteSequence that is a subsequence of this sequence. The subsequence starts with the byte value at the specified index and ends with the byte value at index ofEnd - 1. The length (in bytes) of the returned sequence is ofEnd - ofStart, so if ofStart == ofEnd then an empty sequence is returned.

Specified by:

subSequence in interface ByteSequence

Parameters:

ofStart - the start index, inclusive

ofEnd - the end index, exclusive

Returns:

the specified subsequence

Since:

Coherence 3.7

equals

boolean equals(Object o)

Compare two ReadBuffer objects for equality.

Overrides:

equals in class Object

Parameters:

o - a ReadBuffer object

Returns:

true iff the other ReadBuffer is identical to this

clone

Object clone()

Create a clone of this ReadBuffer object.

Returns:

a ReadBuffer object with the same contents as this ReadBuffer object