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
Interface WriteBuffer

All Known Implementing Classes:
  AbstractWriteBuffer, BinaryWriteBuffer, ByteArrayWriteBuffer, ByteBufferWriteBuffer, DelegatingWriteBuffer, MultiBufferWriteBuffer

    public interface WriteBuffer

The WriteBuffer interface represents an in-memory block of binary data that is being accumulated (written to). It is analogous to the byte[] inside a Java ByteArrayOutputStream.

Author:
  cp 2005.01.18 created, cp 2005.03.21 defining

Nested Class Summary
`static interface` | `WriteBuffer.BufferOutput` The BufferOutput interface represents a DataOutputStream on top of a WriteBuffer.

Method Summary
`void` | `clear()` Set the length of the buffer as indicated by the `length()` method to zero.
`java.lang.Object` | `clone()` Create a clone of this WriteBuffer object.
`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.
`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.
`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.
`int` | `length()` Determine the length of the data that is in the buffer.
`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 ``length()` - 1`, which is shifted to offset ``length()` - of - 1`.
`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.
`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.
`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.

Method Detail

### write

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

  Parameters:
    `ofDest` - the offset within this buffer to store the passed data
    `b` - the byte to store in this buffer

### write

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

  Parameters:
    `ofDest` - the offset within this buffer to store the passed data
    `abSrc` - the array of bytes to store in this buffer

### write

    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.

  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

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

  Parameters:
    `ofDest` - the offset within this buffer to store the passed data
    `bufSrc` - the array of bytes to store in this buffer

### write

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

  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

    void write(int ofDest,
               InputStreaming stream)
               throws java.io.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);

  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:
    `java.io.IOException` - if an IOException occurs reading from the passed stream

### write

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

  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

    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.

  Returns:
    the number of bytes of data represented by this WriteBuffer

### retain

    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 ``length()` - 1`, which is shifted to offset ``length()` - of - 1`. After this method, the length of of the buffer as indicated by the `length()` method will be equal to ``length()` - of`.

  This method is functionally equivalent to the following code:

       retain(of, length() - of);

  Parameters:
    `of` - the offset of the first byte within the WriteBuffer that will be retained
  Throws:
    `java.lang.IndexOutOfBoundsException` - if `of` is negative or if `of` is greater than ``length()``

### retain

    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.

  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()``

### clear

    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.

### getCapacity

    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.

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

### getMaximumCapacity

    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.

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

### getWriteBuffer

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

  Parameters:
    `of` - the beginning index, inclusive
  Returns:
    a WriteBuffer that represents a portion of this WriteBuffer
  Throws:
    `java.lang.IndexOutOfBoundsException` - if `of` is negative, or `of` is larger than the ``getMaximumCapacity()`` of this `WriteBuffer` object

### getWriteBuffer

    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 ``getMaximumCapacity()`` must return the same value as was passed in `cb`.

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

### getBufferOutput

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

  Returns:
    a BufferOutput that is writing to this buffer starting at offset zero

### getBufferOutput

    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;

  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

    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 `length()` of this buffer.

  This is functionally equivalent to:

       return getBufferOutput(length());

  Returns:
    a BufferOutput configured to append to this buffer

### getReadBuffer

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

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

### getUnsafeReadBuffer

    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.

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

### toByteArray

    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();

  Returns:
    the contents of this WriteBuffer as a byte[]

### toBinary

    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();

  Returns:
    the contents of this WriteBuffer as a Binary object

### clone

    java.lang.Object clone()

  Create a clone of this WriteBuffer object. Changes to the clone will not affect the original, and vice-versa.

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