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 MultiBufferWriteBuffer

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

All Implemented Interfaces:
  WriteBuffer

    public class MultiBufferWriteBuffer

extends AbstractWriteBuffer

The MultiBufferWriteBuffer is used to present a single WriteBuffer that collects together a sequence of underlying WriteBuffer objects, and which grows by allocating additional WriteBuffer objects as necessary.

Author:
  cp 2006.04.10

Nested Class Summary
`class` | `MultiBufferWriteBuffer.MultiBufferOutput` The MultiBufferOutput implementation extends the AbstractBufferOutput to provide "pass through" operations to the underlying buffer if the operation is guaranteed to fit in the underlying buffer; otherwise, it vitualizes the operation onto the MultiBufferWriteBuffer itself so that the over-run of one underlying WriteBuffer will end up being written to the next underlying WriteBuffer.
`static interface` | `MultiBufferWriteBuffer.WriteBufferPool` A WriteBufferPool is used to dynamically allocate WriteBuffer objects as the MultiBufferWriteBuffer requires them.

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 inherited from class com.tangosol.io.AbstractWriteBuffer
`CHAR_BUF_MASK, CHAR_BUF_SIZE, m_achBuf, NO_BINARY, NO_BYTES`

Constructor Summary
`MultiBufferWriteBuffer(MultiBufferWriteBuffer.WriteBufferPool bufferpool)` Construct a MultiBufferWriteBuffer that will use the passed WriteBufferPool to allocate WriteBuffer objects from.

Method Summary
`protected WriteBuffer` | `advance()` Once the current buffer is full, allocate a new one and make it the current buffer.
`protected WriteBuffer` | `advanceTo(int of)` Increase the MultiBufferWriteBuffer length so that the next byte to write is at the specified offset.
`java.lang.Object` | `clone()` Create a clone of this WriteBuffer object.
`WriteBuffer` | `getBuffer(int iBuffer)` Obtain the specified buffer.
`int` | `getBufferCount()` Determine the number of WriteBuffer objects allocated by this MultiBufferWriteBuffer from the WriteBufferPool.
`protected int` | `getBufferIndexByOffset(int of)` Determine which underlying WriteBuffer contains the specified offset.
`int` | `getBufferOffset(int iBuffer)` Determine the offset of the specified buffer.
`WriteBuffer.BufferOutput` | `getBufferOutput(int of)` Get a BufferOutput object to write data to this buffer starting at a particular offset.
`MultiBufferWriteBuffer.WriteBufferPool` | `getBufferPool()` Obtain the factory used to create WriteBuffer objects.
`int` | `getCapacity()` Determine the number of bytes that the buffer can hold without resizing itself.
`protected WriteBuffer` | `getCurrentBuffer()` Obtain the current buffer.
`protected int` | `getCurrentBufferAbsoluteOffset()` Determine the offset of the first byte of the current buffer.
`protected int` | `getCurrentBufferRemaining()` Determine the maximum number of bytes that can still be written to the current underlying WriteBuffer.
`int` | `getMaximumCapacity()` Determine the maximum number of bytes that the buffer can hold.
`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`.
`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, 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, copyBufferInputPortion, copyBufferInputRemainder, copyStream, getAppendingBufferOutput, getBufferOutput, getReadBuffer, getWriteBuffer, getWriteBuffer, retain, tmpbuf, tmpbuf, toBinary, toByteArray, write, write, write, write`

Constructor Detail

### MultiBufferWriteBuffer

    public MultiBufferWriteBuffer(MultiBufferWriteBuffer.WriteBufferPool bufferpool)

  Construct a MultiBufferWriteBuffer that will use the passed WriteBufferPool to allocate WriteBuffer objects from.

  Parameters:
    `bufferpool` - a `MultiBufferWriteBuffer.WriteBufferPool` from which the MultiBufferWriteBuffer will allocate WriteBuffer objects

Method Detail

### getBufferPool

    public MultiBufferWriteBuffer.WriteBufferPool getBufferPool()

  Obtain the factory used to create WriteBuffer objects.

  Returns:
    the WriteBufferPool used by this MultiBufferWriteBuffer

### getBufferCount

    public int getBufferCount()

  Determine the number of WriteBuffer objects allocated by this MultiBufferWriteBuffer from the WriteBufferPool.

  Returns:
    the count of WriteBuffer objects allocated

### getBufferOffset

    public int getBufferOffset(int iBuffer)

  Determine the offset of the specified buffer. The offset of a buffer is the absolute offset of the first byte stored in the buffer.

  Parameters:
    `iBuffer` - an index `0 <= iBuffer < getBufferCount()`
  Returns:
    the absolute offset of the first byte of the specified WriteBuffer

### getBuffer

    public WriteBuffer getBuffer(int iBuffer)

  Obtain the specified buffer.

  Parameters:
    `iBuffer` - an index `0 <= iBuffer < getBufferCount()`
  Returns:
    the specified WriteBuffer

### 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 ``AbstractWriteBuffer.length()`` method will become `Math.max(`AbstractWriteBuffer.length()`, ofDest + cbSrc)`.

  As a result of this method, the buffer capacity as reported by the ``AbstractWriteBuffer.getCapacity()`` method will not change if the new value returned by ``AbstractWriteBuffer.length()`` would not exceed the old value returned by ``AbstractWriteBuffer.getCapacity()``; otherwise, the capacity will be increased such that ``AbstractWriteBuffer.getCapacity()` >= `AbstractWriteBuffer.length()``. Regardless, it is always true that ``AbstractWriteBuffer.getCapacity()` >= `AbstractWriteBuffer.length()`` and ``AbstractWriteBuffer.getMaximumCapacity()` >= `AbstractWriteBuffer.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 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

### 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 `AbstractWriteBuffer.length()` method will be equal to `cb`.

  Legal values for the offset of the first byte to retain `of` are `(of >= 0 && of <= `AbstractWriteBuffer.length()`)`. Legal values for the number of bytes to retain `cb` are `(cb >= 0 && cb <= `AbstractWriteBuffer.length()`)`, such that `(of + cb <= `AbstractWriteBuffer.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 int getCapacity()

  Determine the number of bytes that the buffer can hold without resizing itself. In other words, a WriteBuffer has `getCapacity() - `AbstractWriteBuffer.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 `AbstractWriteBuffer.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

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

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

### clone

    public java.lang.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 `AbstractWriteBuffer`
  Returns:
    a WriteBuffer object with the same contents as this WriteBuffer object

### getBufferIndexByOffset

    protected int getBufferIndexByOffset(int of)

  Determine which underlying WriteBuffer contains the specified offset.

  Parameters:
    `of` - an offset into the MultiBufferWriteBuffer, `0 <= of <= length()`
  Returns:
    the index of the WriteBuffer containing the specified offset

### advance

    protected WriteBuffer advance()

  Once the current buffer is full, allocate a new one and make it the current buffer.

  Returns:
    the new WriteBuffer object

### advanceTo

    protected WriteBuffer advanceTo(int of)

  Increase the MultiBufferWriteBuffer length so that the next byte to write is at the specified offset.

  Parameters:
    `of` - the offset to advance to
  Returns:
    the underlying WriteBuffer containing space for the next byte to write

### getCurrentBuffer

    protected WriteBuffer getCurrentBuffer()

  Obtain the current buffer.

  Returns:
    the current underlying WriteBuffer

### getCurrentBufferAbsoluteOffset

    protected int getCurrentBufferAbsoluteOffset()

  Determine the offset of the first byte of the current buffer.

  Returns:
    the offset of the first byte written to the current underlying WriteBuffer

### getCurrentBufferRemaining

    protected int getCurrentBufferRemaining()

  Determine the maximum number of bytes that can still be written to the current underlying WriteBuffer.

  Returns:
    the number of bytes of capacity that remain on the current underlying WriteBuffer object

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.