Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

## 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
`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.
`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
`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
`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.

Method Summary
`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 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` | `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.
`byte[]` | `getRawByteArray()` Obtain the byte array that this WriteBuffer uses.
`ReadBuffer` | `getUnsafeReadBuffer()` Get a ReadBuffer object to read data from this buffer.
`protected 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.
`int` | `length()` Determine the length of the data that is in the buffer.
`void` | `makeByteArrayPrivate()` Make sure that the underlying byte[] will be treated as private data.
`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 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, 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
`clear, clone, copyBufferInputPortion, copyBufferInputRemainder, getAppendingBufferOutput, getBufferOutput, getReadBuffer, getWriteBuffer, getWriteBuffer, retain, tmpbuf, tmpbuf, toBinary, toByteArray, write, write, write`

Field Detail

### 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 Detail

### 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:
    `java.lang.NullPointerException` - if `ab` is `null`

### ByteArrayWriteBuffer

    public ByteArrayWriteBuffer(int cbCap)

  Construct an ByteArrayWriteBuffer with a certain initial capacity.

  Parameters:
    `cbCap` - initial capacity
  Throws:
    `java.lang.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:
    `java.lang.IllegalArgumentException` - if `cbCap` or `cbMax` is negative, or if `cbCap` is greater than `cbMax`

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:
    `java.lang.NullPointerException` - if `abSrc` is `null`
    `java.lang.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,
                      int cbSrc)
               throws java.io.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:
    `java.io.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:
    `java.lang.IndexOutOfBoundsException` - if `of` or `cb` is negative of if `of + cb` is greater than ``length()``

### 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:
    `java.lang.IndexOutOfBoundsException` - if `of` is negative, or `of` is larger than the ``getMaximumCapacity()`` of this `WriteBuffer` object

### 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 `AbstractWriteBuffer.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

### 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 void makeByteArrayPrivate()

  Make sure that the underlying byte[] will be treated as private data.

### getRawByteArray

    public 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 `AbstractWriteBuffer.toByteArray()`.

  Returns:
    the byte array that this WriteBuffer uses

### copyStream

    protected int copyStream(int ofDest,
                             InputStreaming stream,
                             int cbMax)
                      throws java.io.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:
    `java.io.IOException` - if an IOException occurs reading from the passed stream or if the limit is reached without emptying the source stream

### 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 void grow(int cbCap)

  Grow the underlying byte array to at least the specified size.

  Parameters:
    `cbCap` - the required or requested capacity

### updateLength

    protected 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)

Overview | Package | Class | Tree | Index | Help

Oracle® Coherence Java API Reference
v3.5.3
E15583-01
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2000, 2010, Oracle. All rights reserved.