Package com.tangosol.io

Class ByteArrayWriteBuffer

java.lang.Object
com.tangosol.io.AbstractWriteBuffer
com.tangosol.io.ByteArrayWriteBuffer
All Implemented Interfaces:
WriteBuffer
Direct Known Subclasses:
BinaryWriteBuffer
public class ByteArrayWriteBuffer extends AbstractWriteBuffer
ByteArrayWriteBuffer is an implementation of WriteBuffer on a byte array. It is designed to support both fixed length buffers and resizable buffers.

This implementation is not intended to be thread safe.

Author:
cp 2005.03.24

  • Nested Class Summary

    Nested Classes
    Modifier and Type
    Class
    Description
    static class 
    ByteArrayWriteBuffer.Allocator
    Allocator is a WriteBufferPool implementation which allocates a new ByteArrayWriteBuffer on each request to the pool, and does not retain the returned buffer.
    final class 
    ByteArrayWriteBuffer.ByteArrayBufferOutput
    ByteArrayBufferOutput is an implementation of BufferOutput optimized for writing to the buffer's underlying byte array.

    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

    Fields
    Modifier and Type
    Field
    Description
    protected byte[]
    m_ab
    The byte array that holds the binary data.
    protected ByteArrayReadBuffer
    m_bufUnsafe
    Cached ReadBuffer to quickly provide an answer to getUnsafeReadBuffer().
    protected int
    m_cb
    Number of bytes in the byte array that have been written by this WriteBuffer.
    protected int
    m_cbMax
    Number of bytes that the byte array can be grown to.

    Fields inherited from class com.tangosol.io.AbstractWriteBuffer

    CHAR_BUF_MASK, CHAR_BUF_SIZE, m_achBuf, NO_BINARY, NO_BYTES

  • Constructor Summary

    Constructors
    Modifier
    Constructor
    Description
    protected
    ByteArrayWriteBuffer()
    Default constructor; intended only for use by subclasses.
     
    ByteArrayWriteBuffer(byte[] ab)
    Construct a ByteArrayWriteBuffer on a byte array.
     
    ByteArrayWriteBuffer(int cbCap)
    Construct an ByteArrayWriteBuffer with a certain initial capacity.
     
    ByteArrayWriteBuffer(int cbCap, int cbMax)
    Construct an ByteArrayWriteBuffer with a certain initial capacity and a certain maximum capacity.
     
    ByteArrayWriteBuffer(WriteBuffer buffer, int i, int cb)
    Create a new ByteArrayWriteBuffer based on a region of an already existing WriteBuffer.

  • Method Summary

    Modifier and Type
    Method
    Description
    protected void
    checkBounds(int of, int cb)
    Validate the ranges for the passed bounds and make sure that the underlying array is big enough to handle them.
    protected final int
    copyStream(int ofDest, InputStreaming stream, int cbMax)
    Store the remaining contents of the specified InputStreaming object at the specified offset within this buffer.
    protected static byte[]
    createBytes(int cb)
    Create a byte array of the specified size.
    final WriteBuffer.BufferOutput
    getBufferOutput(int of)
    Get a BufferOutput object to write data to this buffer starting at a particular offset.
    final int
    getCapacity()
    Determine the number of bytes that the buffer can hold without resizing itself.
    final int
    getMaximumCapacity()
    Determine the maximum number of bytes that the buffer can hold.
    final byte[]
    getRawByteArray()
    Obtain the byte array that this WriteBuffer uses.
    final ReadBuffer
    getUnsafeReadBuffer()
    Get a ReadBuffer object to read data from this buffer.
    protected final void
    grow(int cbCap)
    Grow the underlying byte array to at least the specified size.
    boolean
    isByteArrayPrivate()
    Determine if the underlying byte[] should be treated as private data.
    final int
    length()
    Determine the length of the data that is in the buffer.
    final void
    makeByteArrayPrivate()
    Make sure that the underlying byte[] will be treated as private data.
    final 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.
    final void
    setLength(int cb)
    Reconfigure the length of the buffer.
    Binary
    toBinary()
    Returns a new Binary object that holds the complete contents of this WriteBuffer.
    final byte[]
    toByteArray()
    Returns a new byte array that holds the complete contents of this WriteBuffer.
    protected final void
    updateLength(int cb)
    Update the length if the passed length is greater than the current buffer length.
    final void
    write(int ofDest, byte b)
    Store the specified byte at the specified offset within the buffer.
    final 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.
    final 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.
    final 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

    clear, clone, copyBufferInputPortion, copyBufferInputRemainder, getAppendingBufferOutput, getBufferOutput, getReadBuffer, getWriteBuffer, getWriteBuffer, releaseBuffers, retain, tmpbuf, tmpbuf, write, write, write

    Methods inherited from class java.lang.Object

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

  • Field Details

    • m_ab

      protected byte[] m_ab
      The byte array that holds the binary data.

    • m_cb

      protected int m_cb
      Number of bytes in the byte array that have been written by this WriteBuffer. This is the length.

    • m_cbMax

      protected int m_cbMax
      Number of bytes that the byte array can be grown to. This is the maximum capacity.

    • m_bufUnsafe

      protected transient ByteArrayReadBuffer m_bufUnsafe
      Cached ReadBuffer to quickly provide an answer to getUnsafeReadBuffer().

  • Constructor Details

    • ByteArrayWriteBuffer

      protected ByteArrayWriteBuffer()
      Default constructor; intended only for use by subclasses.

      Note that this default constructor leaves the buffer in an invalid state.

    • ByteArrayWriteBuffer

      public ByteArrayWriteBuffer(byte[] ab)
      Construct a ByteArrayWriteBuffer on a byte array.
      Parameters:
      ab - a byte array
      Throws:
      NullPointerException - if ab is null

    • ByteArrayWriteBuffer

      public ByteArrayWriteBuffer(int cbCap)
      Construct an ByteArrayWriteBuffer with a certain initial capacity.
      Parameters:
      cbCap - initial capacity
      Throws:
      IllegalArgumentException - if cbCap is negative

    • ByteArrayWriteBuffer

      public ByteArrayWriteBuffer(int cbCap, int cbMax)
      Construct an ByteArrayWriteBuffer with a certain initial capacity and a certain maximum capacity.
      Parameters:
      cbCap - initial capacity
      cbMax - maximum capacity
      Throws:
      IllegalArgumentException - if cbCap or cbMax is negative, or if cbCap is greater than cbMax

    • ByteArrayWriteBuffer

      public ByteArrayWriteBuffer(WriteBuffer buffer, int i, int cb)
      Create a new ByteArrayWriteBuffer based on a region of an already existing WriteBuffer.
      Parameters:
      buffer - the source buffer
      i - the offset within the source buffer
      cb - the number of bytes to copy

  • Method Details

    • write

      public final 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 final 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
      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

    • write

      public final 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 final 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 final 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

    • setLength

      public final void setLength(int cb)
      Reconfigure the length of the buffer. The length must not be longer than the available capacity.
      Parameters:
      cb - the new length of the buffer

    • retain

      public final 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
      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

    • getCapacity

      public final 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
      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 final 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 final 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

    • getUnsafeReadBuffer

      public final 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
      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 final 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();
      For efficiency purposes, it is possible to obtain the internal byte array that the ByteArrayWriteBuffer is using by calling getRawByteArray(); if the internal byte array is private (i.e. if it cannot be exposed to the caller), then the result will be the same as would be returned by 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

    • isByteArrayPrivate

      public boolean isByteArrayPrivate()
      Determine if the underlying byte[] should be treated as private data.
      Returns:
      true iff the underlying data should not ever be exposed by this object

    • makeByteArrayPrivate

      public final void makeByteArrayPrivate()
      Make sure that the underlying byte[] will be treated as private data.

    • getRawByteArray

      public final byte[] getRawByteArray()
      Obtain the byte array that this WriteBuffer uses. If the underlying byte array is private, then this method will always return a copy of the portion of the byte array that this WriteBuffer represents as if the called had called toByteArray().
      Returns:
      the byte array that this WriteBuffer uses

    • copyStream

      protected final 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.
      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
      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

    • createBytes

      protected static byte[] createBytes(int cb)
      Create a byte array of the specified size. The main reason to make this into a separate method is a fact the native OOME comes without any stack trace.
      Parameters:
      cb - the specified size
      Returns:
      a byte array

    • checkBounds

      protected void checkBounds(int of, int cb)
      Validate the ranges for the passed bounds and make sure that the underlying array is big enough to handle them.
      Parameters:
      of - the offset that data is about to be written to
      cb - the length of the data that is about to be written

    • grow

      protected final void grow(int cbCap)
      Grow the underlying byte array to at least the specified size.
      Parameters:
      cbCap - the required or requested capacity

    • updateLength

      protected final void updateLength(int cb)
      Update the length if the passed length is greater than the current buffer length.
      Parameters:
      cb - the count of the last byte written (or the index of the next byte to write)