com.tangosol.io
Class DelegatingWriteBuffer

java.lang.Object
  com.tangosol.io.AbstractWriteBuffer
      com.tangosol.io.DelegatingWriteBuffer

All Implemented Interfaces:

WriteBuffer

public class DelegatingWriteBuffer
extends AbstractWriteBuffer

A DelegatingWriteBuffer is a WriteBuffer that writes through to an underlying (or "containing") WriteBuffer. Basically, it allows a process that is writing to a WriteBuffer to ask for a "protected" sub-portion of that WriteBuffer to hand to a second process, such that the second process can not affect (or even read from) the WriteBuffer outside of the portion that the first process explicitly designated as viewable and modifiable.

This implementation is explicitly not thread-safe.

Author:

cp 2005.03.24 created

Nested Class Summary

class

DelegatingWriteBuffer.DelegatingBufferOutput A BufferOutput implementation that delegates to a BufferOutput implementation, except that its offset range is shifted and limited.

Nested classes/interfaces inherited from class com.tangosol.io.AbstractWriteBuffer

AbstractWriteBuffer.AbstractBufferOutput

Nested classes/interfaces inherited from interface com.tangosol.io.WriteBuffer

WriteBuffer.BufferOutput

Field Summary

protected WriteBuffer	m_buf The WriteBuffer to delegate to; the "containing" WriteBuffer.
protected int	m_cb Length in bytes of this WriteBuffer.
protected int	m_cbMax Maximum number of bytes in this WriteBuffer.
protected int	m_ofStart Offset into the containing WriteBuffer where this WriteBuffer starts.

Fields inherited from class com.tangosol.io.AbstractWriteBuffer

CHAR_BUF_MASK, CHAR_BUF_SIZE, m_achBuf, NO_BINARY, NO_BYTES

Constructor Summary

DelegatingWriteBuffer(WriteBuffer buf, int of, int cb)
Construct a DelegatingWriteBuffer that will delegate to the containing WriteBuffer.

Method Summary

protected void	checkBounds(int of, int cb) Test an offset and length of data to write to see if it can be written to this buffer.
void	clear() Set the length of the buffer as indicated by the length() method to zero.
protected int	copyStream(int ofDest, InputStreaming stream, int cbLimit) Store the remaining contents of the specified InputStreaming object at the specified offset within this buffer.
WriteBuffer.BufferOutput	getBufferOutput(int of) Get a BufferOutput object to write data to this buffer starting at a particular offset.
int	getCapacity() Determine the number of bytes that the buffer can hold without resizing itself.
int	getMaximumCapacity() Determine the maximum number of bytes that the buffer can hold.
ReadBuffer	getReadBuffer() Get a ReadBuffer object that is a snapshot of this WriteBuffer's data.
ReadBuffer	getUnsafeReadBuffer() Get a ReadBuffer object to read data from this buffer.
int	length() Determine the length of the data that is in the buffer.
void	retain(int of, int cb) Starting with the byte at offset of, retain cb bytes in this WriteBuffer, such that the byte at offset of is shifted to offset 0, the byte at offset of + 1 is shifted to offset 1, and so on up to the byte at offset of + cb - 1, which is shifted to offset cb - 1.
Binary	toBinary() Returns a new Binary object that holds the complete contents of this WriteBuffer.
byte[]	toByteArray() Returns a new byte array that holds the complete contents of this WriteBuffer.
protected void	updateLength(int cb) Update the length if the passed length is greater than the current buffer length.
void	write(int ofDest, byte b) Store the specified byte at the specified offset within the buffer.
void	write(int ofDest, byte[] abSrc, int ofSrc, int cbSrc) Store the specified number of bytes from the specified location within the passed byte array at the specified offset within this buffer.
void	write(int ofDest, InputStreaming stream) Store the remaining contents of the specified InputStreaming object at the specified offset within this buffer.
void	write(int ofDest, InputStreaming stream, int cbSrc) Store the specified number of bytes from the specified InputStreaming object at the specified offset within this buffer.
void	write(int ofDest, ReadBuffer bufSrc, int ofSrc, int cbSrc) Store the specified portion of the contents of the specified ReadBuffer at the specified offset within this buffer.

Methods inherited from class com.tangosol.io.AbstractWriteBuffer

clone, getAppendingBufferOutput, getBufferOutput, getWriteBuffer, getWriteBuffer, retain, tmpbuf, tmpbuf, write, write

Field Detail

m_buf

protected WriteBuffer m_buf

The WriteBuffer to delegate to; the "containing" WriteBuffer.

m_ofStart

protected int m_ofStart

Offset into the containing WriteBuffer where this WriteBuffer starts.

m_cb

protected int m_cb

Length in bytes of this WriteBuffer.

m_cbMax

protected int m_cbMax

Maximum number of bytes in this WriteBuffer.

Constructor Detail

DelegatingWriteBuffer

public DelegatingWriteBuffer(WriteBuffer buf,
                             int of,
                             int cb)

Construct a DelegatingWriteBuffer that will delegate to the containing WriteBuffer.

Parameters:

of - the offset within the containing WriteBuffer that this WriteBuffer is starting at

cb - the maximum capacity for this WriteBuffer

Method Detail

write

public void write(int ofDest,
                  byte b)

Store the specified byte at the specified offset within the buffer.

For purposes of side-effects and potential exceptions, this method is functionally equivalent to the following code:

 byte[] abSrc = new byte[1];
 abSrc[0] = b;
 write(ofDest, abSrc, 0, abSrc.length);
 

Specified by:

write in interface WriteBuffer

Specified by:

write in class AbstractWriteBuffer

Parameters:

ofDest - the offset within this buffer to store the passed data

b - the byte to store in this buffer

write

public void write(int ofDest,
                  byte[] abSrc,
                  int ofSrc,
                  int cbSrc)

Store the specified number of bytes from the specified location within the passed byte array at the specified offset within this buffer.

As a result of this method, the buffer length as reported by the length() method will become Math.max(length(), ofDest + cbSrc).

As a result of this method, the buffer capacity as reported by the getCapacity() method will not change if the new value returned by length() would not exceed the old value returned by getCapacity(); otherwise, the capacity will be increased such that getCapacity() >= length(). Regardless, it is always true that getCapacity() >= length() and getMaximumCapacity() >= getCapacity(). If the buffer capacity cannot be increased due to resource constraints, an undesignated Error or RuntimeException will be thrown, such as OutOfMemoryError.

Specified by:

write in interface WriteBuffer

Specified by:

write in class AbstractWriteBuffer

Parameters:

ofDest - the offset within this buffer to store the passed data

abSrc - the array containing the bytes to store in this buffer

ofSrc - the offset within the passed byte array to copy from

cbSrc - the number of bytes to copy from the passed byte array

Throws:

NullPointerException - if abSrc is null

IndexOutOfBoundsException - if ofDest, ofSrc or cbSrc is negative, if ofSrc + cbSrc is greater than abSrc.length, or if ofDest + cbSrc is greater than getMaximumCapacity()

write

public void write(int ofDest,
                  ReadBuffer bufSrc,
                  int ofSrc,
                  int cbSrc)

Store the specified portion of the contents of the specified ReadBuffer at the specified offset within this buffer.

For purposes of side-effects and potential exceptions, this method is functionally equivalent to the following code:

 byte[] abSrc = bufSrc.toByteArray(ofSrc, cbSrc);
 write(ofDest, abSrc, 0, abSrc.length);
 

Specified by:

write in interface WriteBuffer

Overrides:

write in class AbstractWriteBuffer

Parameters:

ofDest - the offset within this buffer to store the passed data

bufSrc - the array of bytes to store in this buffer

ofSrc - the offset within the passed ReadBuffer to copy from

cbSrc - the number of bytes to copy from the passed ReadBuffer

write

public void write(int ofDest,
                  InputStreaming stream)
           throws IOException

Store the remaining contents of the specified InputStreaming object at the specified offset within this buffer.

For purposes of side-effects and potential exceptions, this method is functionally similar to the following code:

 ByteArrayOutputStream streamOut = new ByteArrayOutputStream();
 int b;
 while ((b = stream.read()) >= 0)
     {
     streamOut.write(b);
     }
 byte[] abSrc = streamOut.toByteArray();
 write(ofDest, abSrc, 0, abSrc.length);
 

Specified by:

write in interface WriteBuffer

Overrides:

write in class AbstractWriteBuffer

Parameters:

ofDest - the offset within this buffer to store the passed data

stream - the stream of bytes to read and store in this buffer

Throws:

IOException - if an IOException occurs reading from the passed stream

write

public void write(int ofDest,
                  InputStreaming stream,
                  int cbSrc)
           throws IOException

Store the specified number of bytes from the specified InputStreaming object at the specified offset within this buffer.

For purposes of side-effects and potential exceptions, this method is functionally similar to the following code:

 DataInputStream streamData = new DataInputStream(
         new WrapperInputStream(stream));
 byte[] abSrc = new byte[cbSrc];
 streamData.readFully(abSrc);
 write(ofDest, abSrc, 0, abSrc.length);
 

Specified by:

write in interface WriteBuffer

Overrides:

write in class AbstractWriteBuffer

Parameters:

ofDest - the offset within this buffer to store the passed data

stream - the stream of bytes to read and store in this buffer

cbSrc - the exact number of bytes to read from the stream and put in this buffer

Throws:

IOException - if an IOException occurs reading from the passed stream

length

public int length()

Determine the length of the data that is in the buffer. This is the actual number of bytes of data that have been written to the buffer, not the capacity of the buffer.

Specified by:

length in interface WriteBuffer

Specified by:

length in class AbstractWriteBuffer

Returns:

the number of bytes of data represented by this WriteBuffer

retain

public void retain(int of,
                   int cb)

Starting with the byte at offset of, retain cb bytes in this WriteBuffer, such that the byte at offset of is shifted to offset 0, the byte at offset of + 1 is shifted to offset 1, and so on up to the byte at offset of + cb - 1, which is shifted to offset cb - 1. After this method, the length of the buffer as indicated by the length() method will be equal to cb.

Legal values for the offset of the first byte to retain of are (of >= 0 && of <= length()). Legal values for the number of bytes to retain cb are (cb >= 0 && cb <= length()), such that (of + cb <= length()).

If cb is zero, then this method will have the same effect as clear. If of is zero, then this method will have the effect of truncating the data in the buffer, but no bytes will be shifted within the buffer.

The effect on the capacity of the buffer is implementation-specific; some implementations are expected to retain the same capacity while others are expected to shrink accordingly.

Specified by:

retain in interface WriteBuffer

Specified by:

retain in class AbstractWriteBuffer

Parameters:

of - the offset of the first byte within the WriteBuffer that will be retained

cb - the number of bytes to retain

Throws:

IndexOutOfBoundsException - if of or cb is negative of if of + cb is greater than length()

clear

public void clear()

Set the length of the buffer as indicated by the length() method to zero.

The effect on the capacity of the buffer is implementation-specific; some implementations are expected to retain the same capacity while others are expected to shrink accordingly.

Specified by:

clear in interface WriteBuffer

Overrides:

clear in class AbstractWriteBuffer

getCapacity

public int getCapacity()

Determine the number of bytes that the buffer can hold without resizing itself. In other words, a WriteBuffer has getCapacity() - length() bytes that can be written to it without overflowing the current underlying buffer allocation. Since the buffer is an abstract concept, the actual mechanism for the underlying buffer is not known, but it could be a Java NIO buffer, or a byte array, etc.

Note that if the maximum size returned by getMaximumCapacity() is greater than the current size returned by this method, then the WriteBuffer will automatically resize itself to allocate more space when the amount of data written to it passes the current size.

Specified by:

getCapacity in interface WriteBuffer

Specified by:

getCapacity in class AbstractWriteBuffer

Returns:

the number of bytes of data that this WriteBuffer can hold without resizing its underlying buffer

getMaximumCapacity

public int getMaximumCapacity()

Determine the maximum number of bytes that the buffer can hold. If the maximum size is greater than the current size, then the buffer is expected to resize itself as necessary up to the maximum size in order to contain the data given to it.

Specified by:

getMaximumCapacity in interface WriteBuffer

Overrides:

getMaximumCapacity in class AbstractWriteBuffer

Returns:

the maximum number of bytes of data that the WriteBuffer can hold

getBufferOutput

public WriteBuffer.BufferOutput getBufferOutput(int of)

Get a BufferOutput object to write data to this buffer starting at a particular offset.

Note that each call to this method will return a new BufferOutput object, with the possible exception being that a zero-length non-resizing WriteBuffer could always return the same instance (since it is not writable).

This is functionally equivalent to:

 BufferOutput bufout = getBufferOutput();
 bufout.setOffset(of);
 return bufout;
 

Specified by:

getBufferOutput in interface WriteBuffer

Overrides:

getBufferOutput in class AbstractWriteBuffer

Parameters:

of - the offset of the first byte of this buffer that the BufferOutput will write to

Returns:

a BufferOutput that will write to this buffer

Throws:

IndexOutOfBoundsException - if of is negative, or of is larger than the getMaximumCapacity() of this WriteBuffer object

getReadBuffer

public ReadBuffer getReadBuffer()

Get a ReadBuffer object that is a snapshot of this WriteBuffer's data.

This method is functionally equivalent to the following code:

 ReadBuffer buf = getUnsafeReadBuffer();
 byte[] ab = buf.toByteArray();
 return new ByteArrayReadBuffer(ab);
 

Specified by:

getReadBuffer in interface WriteBuffer

Overrides:

getReadBuffer in class AbstractWriteBuffer

Returns:

a ReadBuffer that reflects the point-in-time contents of this WriteBuffer

getUnsafeReadBuffer

public ReadBuffer getUnsafeReadBuffer()

Get a ReadBuffer object to read data from this buffer. This method is not guaranteed to return a snapshot of this buffer's data, nor is it guaranteed to return a live view of this buffer, which means that subsequent changes to this WriteBuffer may or may not affect the contents and / or the length of the returned ReadBuffer.

To get a snapshot, use the getReadBuffer() method.

Specified by:

getUnsafeReadBuffer in interface WriteBuffer

Specified by:

getUnsafeReadBuffer in class AbstractWriteBuffer

Returns:

a ReadBuffer that reflects the contents of this WriteBuffer but whose behavior is undefined if the WriteBuffer is modified

toByteArray

public byte[] toByteArray()

Returns a new byte array that holds the complete contents of this WriteBuffer.

This method is functionally equivalent to the following code:

 return getUnsafeReadBuffer().toByteArray();
 

Specified by:

toByteArray in interface WriteBuffer

Overrides:

toByteArray in class AbstractWriteBuffer

Returns:

the contents of this WriteBuffer as a byte[]

toBinary

public Binary toBinary()

Returns a new Binary object that holds the complete contents of this WriteBuffer.

This method is functionally equivalent to the following code:

 return getUnsafeReadBuffer().toBinary();
 

Specified by:

toBinary in interface WriteBuffer

Overrides:

toBinary in class AbstractWriteBuffer

Returns:

the contents of this WriteBuffer as a Binary object

checkBounds

protected void checkBounds(int of,
                           int cb)

Test an offset and length of data to write to see if it can be written to this buffer.

Parameters:

of - offset to write data at

cb - length in bytes of data

updateLength

protected void updateLength(int cb)

Update the length if the passed length is greater than the current buffer length.

Parameters:

cb - the possible new length

copyStream

protected int copyStream(int ofDest,
                         InputStreaming stream,
                         int cbLimit)
                  throws IOException

Store the remaining contents of the specified InputStreaming object at the specified offset within this buffer.

Overrides:

copyStream in class AbstractWriteBuffer

Parameters:

ofDest - the offset within this buffer to store the passed data

stream - the stream of bytes to read and store in this buffer

cbLimit - the maximum number of bytes to copy

Throws:

IOException - if an IOException occurs reading from the passed stream or if the limit is reached without emptying the source stream