AbstractWriteBuffer (Oracle® Coherence Java API Reference)

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

All Implemented Interfaces:

WriteBuffer

Direct Known Subclasses:

ByteArrayWriteBuffer, ByteBufferWriteBuffer, DelegatingWriteBuffer, MultiBufferWriteBuffer
```
public abstract class AbstractWriteBuffer
extends Object
implements WriteBuffer
```
The AbstractWriteBuffer is a partial implementation of the WriteBuffer interface intended to be used as a base class for easily creating concrete WriteBuffer implementations.
This implementation is explicitly not thread-safe.

Author:

cp 2005.03.23 created

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`class`	`AbstractWriteBuffer.AbstractBufferOutput` AbstractBufferOutput is a concrete implementation of BufferOutput for the non-concrete AbstractWriteBuffer implementation.

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

Field Summary

Fields
Modifier and Type	Field and Description
`protected static int`	`CHAR_BUF_MASK` Bitmask used against a raw offset to determine the offset within the temporary character buffer.
`protected static int`	`CHAR_BUF_SIZE` Size of the temporary character buffer.
`protected char[]`	`m_achBuf` A lazily instantiated temp buffer used to avoid allocations from `String.toCharArray()` and repeated calls to `String.charAt(int)`.
`static Binary`	`NO_BINARY` An empty Binary object.
`static byte[]`	`NO_BYTES` An empty byte array (by definition immutable).

Constructor Summary

Constructors
Constructor and Description

AbstractWriteBuffer()

Constructors
Constructor and Description
`AbstractWriteBuffer()`

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`void`	`clear()` Set the length of the buffer as indicated by the `WriteBuffer.length()` method to zero.
`Object`	`clone()` Create a clone of this WriteBuffer object.
`protected void`	`copyBufferInputPortion(int ofDest, ReadBuffer.BufferInput inSrc, int cbSrc)` Read a portion of the specified BufferInput and write it to the specified offset within this buffer.
`protected int`	`copyBufferInputRemainder(int ofDest, ReadBuffer.BufferInput inSrc, int cbMax)` Read the remaining contents of the specified BufferInput and write it to the specified offset within this buffer.
`protected int`	`copyStream(int ofDest, InputStreaming stream, int cbMax)` Store the remaining contents of the specified InputStreaming object at the specified offset within this buffer.
`WriteBuffer.BufferOutput`	`getAppendingBufferOutput()` Get a BufferOutput object to write data to this buffer.
`WriteBuffer.BufferOutput`	`getBufferOutput()` Get a BufferOutput object to write data to this buffer, starting at the beginning of the WriteBuffer.
`WriteBuffer.BufferOutput`	`getBufferOutput(int of)` Get a BufferOutput object to write data to this buffer starting at a particular offset.
`abstract 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.
`abstract ReadBuffer`	`getUnsafeReadBuffer()` Get a ReadBuffer object to read data from this buffer.
`WriteBuffer`	`getWriteBuffer(int of)` Obtain a WriteBuffer starting at a particular offset within this WriteBuffer.
`WriteBuffer`	`getWriteBuffer(int of, int cb)` Obtain a WriteBuffer for a portion of this WriteBuffer.
`abstract int`	`length()` Determine the length of the data that is in the buffer.
`protected void`	`releaseBuffers()` Release the internal buffers held by the WriteBuffer.
`void`	`retain(int of)` Starting with the byte at offset `of`, retain the remainder of 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 `WriteBuffer.length() - 1`, which is shifted to offset `WriteBuffer.length() - of - 1`.
`abstract 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`.
`protected byte[]`	`tmpbuf()` Get a small buffer for formating data to bytes.
`protected byte[]`	`tmpbuf(int cb)` Get a buffer for formating data to bytes.
`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.
`abstract void`	`write(int ofDest, byte b)` Store the specified byte at the specified offset within the buffer.
`void`	`write(int ofDest, byte[] abSrc)` Store the specified bytes at the specified offset within the buffer.
`abstract 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)` Store the contents of the specified ReadBuffer 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 java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - NO_BYTES
```
public static final byte[] NO_BYTES
```
    An empty byte array (by definition immutable).
  - NO_BINARY
```
public static final Binary NO_BINARY
```
    An empty Binary object.
  - CHAR_BUF_SIZE
```
protected static final int CHAR_BUF_SIZE
```
    Size of the temporary character buffer. Must be a power of 2.
    Size is: 256 characters (.25 KB).
    
    See Also:
    
    Constant Field Values
  - CHAR_BUF_MASK
```
protected static final int CHAR_BUF_MASK
```
    Bitmask used against a raw offset to determine the offset within the temporary character buffer.
    
    See Also:
    
    Constant Field Values
  - m_achBuf
```
protected transient char[] m_achBuf
```
    A lazily instantiated temp buffer used to avoid allocations from String.toCharArray() and repeated calls to String.charAt(int).
- Constructor Detail
  - AbstractWriteBuffer
```
public AbstractWriteBuffer()
```
- Method Detail
  - write
```
public abstract 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
    
    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)
```
    Store the specified bytes at the specified offset within the buffer.
    For purposes of side-effects and potential exceptions, this method is functionally equivalent to the following code:
```
 write(ofDest, abSrc, 0, abSrc.length);
 
```
    Specified by:
    
    write in interface WriteBuffer
    
    Parameters:
    
    ofDest - the offset within this buffer to store the passed data
    
    abSrc - the array of bytes to store in this buffer
  - write
```
public abstract 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 WriteBuffer.length() method will become Math.max(WriteBuffer.length(), ofDest + cbSrc).
    
    As a result of this method, the buffer capacity as reported by the WriteBuffer.getCapacity() method will not change if the new value returned by WriteBuffer.length() would not exceed the old value returned by WriteBuffer.getCapacity(); otherwise, the capacity will be increased such that WriteBuffer.getCapacity() >= WriteBuffer.length(). Regardless, it is always true that WriteBuffer.getCapacity() >= WriteBuffer.length() and WriteBuffer.getMaximumCapacity() >= WriteBuffer.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
    
    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
  - write
```
public void write(int ofDest,
                  ReadBuffer bufSrc)
```
    Store 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();
 write(ofDest, abSrc, 0, abSrc.length);
 
```
    Specified by:
    
    write in interface WriteBuffer
    
    Parameters:
    
    ofDest - the offset within this buffer to store the passed data
    
    bufSrc - the array of bytes to store in this buffer
  - 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
    
    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
    
    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
    
    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 abstract 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
    
    Returns:
    
    the number of bytes of data represented by this WriteBuffer
  - retain
```
public void retain(int of)
```
    Starting with the byte at offset of, retain the remainder of 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 WriteBuffer.length() - 1, which is shifted to offset WriteBuffer.length() - of - 1. After this method, the length of of the buffer as indicated by the WriteBuffer.length() method will be equal to WriteBuffer.length() - of.
    This method is functionally equivalent to the following code:
```
 retain(of, length() - of);
 
```
    Specified by:
    
    retain in interface WriteBuffer
    
    Parameters:
    
    of - the offset of the first byte within the WriteBuffer that will be retained
  - retain
```
public abstract 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 WriteBuffer.length() method will be equal to cb.
    Legal values for the offset of the first byte to retain of are (of >= 0 && of <= WriteBuffer.length()). Legal values for the number of bytes to retain cb are (cb >= 0 && cb <= WriteBuffer.length()), such that (of + cb <= WriteBuffer.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
    
    Parameters:
    
    of - the offset of the first byte within the WriteBuffer that will be retained
    
    cb - the number of bytes to retain
  - clear
```
public void clear()
```
    Set the length of the buffer as indicated by the WriteBuffer.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
  - getCapacity
```
public abstract int getCapacity()
```
    Determine the number of bytes that the buffer can hold without resizing itself. In other words, a WriteBuffer has getCapacity() - WriteBuffer.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 WriteBuffer.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
    
    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
    
    Returns:
    
    the maximum number of bytes of data that the WriteBuffer can hold
  - getWriteBuffer
```
public WriteBuffer getWriteBuffer(int of)
```
    Obtain a WriteBuffer starting at a particular offset within this WriteBuffer.
    This is functionally equivalent to:
```
 return getWriteBuffer(of, getMaximumCapacity() - of);
 
```
    Specified by:
    
    getWriteBuffer in interface WriteBuffer
    
    Parameters:
    
    of - the beginning index, inclusive
    
    Returns:
    
    a WriteBuffer that represents a portion of this WriteBuffer
  - getWriteBuffer
```
public WriteBuffer getWriteBuffer(int of,
                                  int cb)
```
    Obtain a WriteBuffer for a portion of this WriteBuffer.
    Use of the resulting buffer will correspond to using this buffer directly but with the offset being passed to the buffer methods automatically having of added. As a result, the length of this buffer can be modified by writing to the new buffer; however, changes made directly to this buffer will not affect the length of the new buffer.
    
    Note that the resulting WriteBuffer is limited in the number of bytes that can be written to it; in other words, its WriteBuffer.getMaximumCapacity() must return the same value as was passed in cb.
    
    Specified by:
    
    getWriteBuffer in interface WriteBuffer
    
    Parameters:
    
    of - the offset of the first byte within this WriteBuffer to map to offset 0 of the new WriteBuffer
    
    cb - the number of bytes to cover in the resulting WriteBuffer
    
    Returns:
    
    a WriteBuffer that represents a portion of this WriteBuffer
  - getBufferOutput
```
public WriteBuffer.BufferOutput getBufferOutput()
```
    Get a BufferOutput object to write data to this buffer, starting at the beginning of the WriteBuffer.
    This is functionally equivalent to:
```
 return getBufferOutput(0);
 
```
    Specified by:
    
    getBufferOutput in interface WriteBuffer
    
    Returns:
    
    a BufferOutput that is writing to this buffer starting at offset zero
  - 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
    
    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
  - getAppendingBufferOutput
```
public WriteBuffer.BufferOutput getAppendingBufferOutput()
```
    Get a BufferOutput object to write data to this buffer. The BufferOutput object returned by this method is set to append to the WriteBuffer, meaning that its offset is pre-set to the WriteBuffer.length() of this buffer.
    This is functionally equivalent to:
```
 return getBufferOutput(length());
 
```
    Specified by:
    
    getAppendingBufferOutput in interface WriteBuffer
    
    Returns:
    
    a BufferOutput configured to append to this buffer
  - 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
    
    Returns:
    
    a ReadBuffer that reflects the point-in-time contents of this WriteBuffer
  - getUnsafeReadBuffer
```
public abstract 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 WriteBuffer.getReadBuffer() method.
    
    Specified by:
    
    getUnsafeReadBuffer in interface WriteBuffer
    
    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
    
    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
    
    Returns:
    
    the contents of this WriteBuffer as a Binary object
  - clone
```
public Object clone()
```
    Create a clone of this WriteBuffer object. Changes to the clone will not affect the original, and vice-versa.
    
    Specified by:
    
    clone in interface WriteBuffer
    
    Overrides:
    
    clone in class Object
    
    Returns:
    
    a WriteBuffer object with the same contents as this WriteBuffer object
  - copyBufferInputPortion
```
protected void copyBufferInputPortion(int ofDest,
                                      ReadBuffer.BufferInput inSrc,
                                      int cbSrc)
                               throws IOException
```
    Read a portion of the specified BufferInput and write it to the specified offset within this buffer.
    
    Parameters:
    
    ofDest - the offset within this buffer to store the passed data
    
    inSrc - the BufferInput to read data from to copy to this buffer
    
    cbSrc - the exact number of bytes to read from the passed BufferInput
    
    Throws:
    
    IOException - if an IOException occurs reading from the passed stream
  - copyBufferInputRemainder
```
protected int copyBufferInputRemainder(int ofDest,
                                       ReadBuffer.BufferInput inSrc,
                                       int cbMax)
                                throws IOException
```
    Read the remaining contents of the specified BufferInput and write it to the specified offset within this buffer.
    
    Parameters:
    
    ofDest - the offset within this buffer to store the passed data
    
    inSrc - the BufferInput to read and store in this buffer
    
    cbMax - the maximum number of bytes to copy
    
    Returns:
    
    the actual number of bytes read from the BufferInput and written to this buffer
    
    Throws:
    
    IOException - if an IOException occurs reading from the passed stream or if the limit is reached without emptying the source stream
  - copyStream
```
protected int copyStream(int ofDest,
                         InputStreaming stream,
                         int cbMax)
                  throws IOException
```
    Store the remaining contents of the specified InputStreaming object at the specified offset within this buffer.
    
    Parameters:
    
    ofDest - the offset within this buffer to store the passed data
    
    stream - the stream of bytes to read and store in this buffer
    
    cbMax - the maximum number of bytes to copy
    
    Returns:
    
    the actual number of bytes read from the InputStreaming object and written to this buffer
    
    Throws:
    
    IOException - if an IOException occurs reading from the passed stream or if the limit is reached without emptying the source stream
  - tmpbuf
```
protected byte[] tmpbuf()
```
    Get a small buffer for formating data to bytes.
    
    Returns:
    
    a byte array that is at least MIN_BUF bytes long
  - tmpbuf
```
protected byte[] tmpbuf(int cb)
```
    Get a buffer for formating data to bytes. Note that the resulting buffer may be shorter than the requested size.
    
    Parameters:
    
    cb - the requested size for the buffer
    
    Returns:
    
    a byte array that is at least cb bytes long, but not shorter than MIN_BUF and (regardless of the value of cb) not longer than MAX_BUF
  - releaseBuffers
```
protected final void releaseBuffers()
```
    Release the internal buffers held by the WriteBuffer.

Class AbstractWriteBuffer

Nested Class Summary

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

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

NO_BYTES

NO_BINARY

CHAR_BUF_SIZE

CHAR_BUF_MASK

m_achBuf

Constructor Detail

AbstractWriteBuffer

Method Detail

write

write

write

write

write

write

write

length

retain

retain

clear

getCapacity

getMaximumCapacity

getWriteBuffer

getWriteBuffer

getBufferOutput

getBufferOutput

getAppendingBufferOutput

getReadBuffer

getUnsafeReadBuffer

toByteArray

toBinary

clone

copyBufferInputPortion

copyBufferInputRemainder

copyStream

tmpbuf

tmpbuf

releaseBuffers