Oracle Coherence for C++ API
Release 3.6.0.0
E15728-01

- Main Page
- Namespaces
- Classes
- Files

- Alphabetical List
- Class List
- Class Hierarchy
- Class Members

# WriteBuffer Class Reference

`#include <coherence/io/WriteBuffer.hpp>`

Inherits Object.

Inherited by AbstractWriteBuffer `[virtual]`.

List of all members.

## Detailed Description

The WriteBuffer interface represents an in-memory block of binary data that is being accumulated (written to).

Author:
  jh 2007.12.20

## Public Types
typedef spec::Handle | Handle
| WriteBuffer Handle definition.
typedef spec::View | View
| WriteBuffer View definition.
typedef spec::Holder | Holder
| WriteBuffer Holder definition.
typedef this_spec::Handle | Handle
| Object Handle definition.
typedef this_spec::View | View
| Object View definition.
typedef this_spec::Holder | Holder
| Object Holder definition.
## Public Member Functions
virtual size32_t | length () const =0
| Determine the length of the data that is in the buffer.
virtual size32_t | getCapacity () const =0
| Determine the number of octets that the buffer can hold without resizing itself.
virtual size32_t | getMaximumCapacity () const =0
| Determine the maximum number of octets that the buffer can hold.
virtual void | write (size32_t ofDest, octet_t b)=0
| Store the specified octet at the specified offset within the buffer.
virtual void | write (size32_t ofDest, Array< octet_t >::View vabSrc)=0
| Store the specified octets at the specified offset within the buffer.
virtual void | write (size32_t ofDest, Array< octet_t >::View vabSrc, size32_t ofSrc, size32_t cbSrc)=0
| Store the specified number of octets from the specified location within the passed octet array at the specified offset within this buffer.
virtual void | write (size32_t ofDest, ReadBuffer::View vBufSrc)=0
| Store the contents of the specified ReadBuffer at the specified offset within this buffer.
virtual void | write (size32_t ofDest, ReadBuffer::View vBufSrc, size32_t ofSrc, size32_t cbSrc)=0
| Store the specified portion of the contents of the specified ReadBuffer at the specified offset within this buffer.
virtual void | retain (size32_t of)=0
| Starting with the octet at offset `of`, retain the remainder of this WriteBuffer, such that the octet at offset `of` is shifted to offset 0, the octet at offset `of + 1` is shifted to offset 1, and so on up to the octet at offset `length() - 1`, which is shifted to offset `length() - of - 1`.
virtual void | retain (size32_t of, size32_t cb)=0
| Starting with the octet at offset `of`, retain `cb` octets in this WriteBuffer, such that the octet at offset `of` is shifted to offset 0, the octet at offset `of + 1` is shifted to offset 1, and so on up to the octet at offset `of + cb - 1`, which is shifted to offset `cb - 1`.
virtual void | clear ()=0
| Set the length of the buffer as indicated by the length() method to zero.
virtual WriteBuffer::Handle | getWriteBuffer (size32_t of)=0
| Obtain a WriteBuffer starting at a particular offset within this WriteBuffer.
virtual WriteBuffer::Handle | getWriteBuffer (size32_t of, size32_t cb)=0
| Obtain a WriteBuffer for a portion of this WriteBuffer.
virtual ReadBuffer::View | getReadBuffer () const =0
| Get a ReadBuffer object that is a snapshot of this WriteBuffer's data.
virtual ReadBuffer::View | getUnsafeReadBuffer () const =0
| Get a ReadBuffer object to read data from this buffer.
virtual Array < octet_t >::View | toOctetArray () const =0
| Returns an octet array that holds the complete contents of this WriteBuffer.
virtual BufferOutput::Handle | getBufferOutput (size32_t of=0)=0
| Get a BufferOutput object to write data to this buffer starting at a particular offset.
virtual BufferOutput::Handle | getAppendingBufferOutput ()=0
| Get a BufferOutput object to write data to this buffer.
## Classes
class | BufferOutput
| The BufferOutput interface represents a data output stream on top of a WriteBuffer. More...

## Member Function Documentation

virtual size32_t length | ( |  | ) | const `[pure virtual]`

Determine the length of the data that is in the buffer.

This is the actual number of octets of data that have been written to the buffer, not the capacity of the buffer.

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

Implemented in DelegatingWriteBuffer, and OctetArrayWriteBuffer.

virtual size32_t getCapacity | ( |  | ) | const `[pure virtual]`

Determine the number of octets that the buffer can hold without resizing itself.

In other words, a WriteBuffer has `getCapacity() - length()` octets 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.

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 octets of data that this WriteBuffer can hold without resizing its underlying buffer

Implemented in DelegatingWriteBuffer, and OctetArrayWriteBuffer.

virtual size32_t getMaximumCapacity | ( |  | ) | const `[pure virtual]`

Determine the maximum number of octets 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 octets of data that the WriteBuffer can hold

Implemented in AbstractWriteBuffer, DelegatingWriteBuffer, and OctetArrayWriteBuffer.

virtual void write | ( | size32_t | ofDest,
|  | octet_t | b |
| ) |  |  | `[pure virtual]`

Store the specified octet at the specified offset within the buffer.

For purposes of side-effects and potential exceptions, this method is functionally equivalent to the following code:

     Array<octet_t>::Handle habSrc = Array<octet_t>::create(1);
     habSrc[0] = b;
     write(ofDest, habSrc, 0, 1);

Parameters:

  | ofDest | the offset within this buffer to store the passed data
  | b | the octet to store in this buffer

Implemented in DelegatingWriteBuffer, and OctetArrayWriteBuffer.

virtual void write | ( | size32_t | ofDest,
|  | Array< octet_t >::View | vabSrc |
| ) |  |  | `[pure virtual]`

Store the specified octets 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, vabSrc, 0, vabSrc.length);

Parameters:

  | ofDest | the offset within this buffer to store the passed data
  | vabSrc | the array of octets to store in this buffer

Implemented in AbstractWriteBuffer.

virtual void write | ( | size32_t | ofDest,
|  | Array< octet_t >::View | vabSrc,
|  | size32_t | ofSrc,
|  | size32_t | cbSrc |
| ) |  |  | `[pure virtual]`

Store the specified number of octets from the specified location within the passed octet 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 `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 Exception will be thrown.

Parameters:

  | ofDest | the offset within this buffer to store the passed data
  | vabSrc | the array containing the octets to store in this buffer
  | ofSrc | the offset within the passed octet array to copy from
  | cbSrc | the number of octets to copy from the passed octet array

Exceptions:

  | NullPointerException | if `vabSrc` is NULL
  | IndexOutOfBoundsException | if `ofSrc + cbSrc` is greater than `vabSrc->length`, or if `ofDest + cbSrc` is greater than `getMaximumCapacity()`

Implemented in DelegatingWriteBuffer, and OctetArrayWriteBuffer.

virtual void write | ( | size32_t | ofDest,
|  | ReadBuffer::View | vBufSrc |
| ) |  |  | `[pure virtual]`

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:

     Array<octet_t>::View vabSrc = vBufSrc->toOctetArray();
     write(ofDest, vabSrc, 0, vabSrc->length);

Parameters:

  | ofDest | the offset within this buffer to store the passed data
  | vBufSrc | the array of octets to store in this buffer

Implemented in AbstractWriteBuffer.

virtual void write | ( | size32_t | ofDest,
|  | ReadBuffer::View | vBufSrc,
|  | size32_t | ofSrc,
|  | size32_t | cbSrc |
| ) |  |  | `[pure virtual]`

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:

     Array<octet_t>::View vabSrc = vbufSrc.toOctetArray(ofSrc, cbSrc);
     write(ofDest, vabSrc, 0, vabSrc->length);

Parameters:

  | ofDest | the offset within this buffer to store the passed data
  | vBufSrc | the source ReadBuffer
  | ofSrc | the offset within the passed ReadBuffer to copy from
  | cbSrc | the number of octets to copy from the passed ReadBuffer

Implemented in AbstractWriteBuffer, DelegatingWriteBuffer, and OctetArrayWriteBuffer.

virtual void retain | ( | size32_t | of | ) | `[pure virtual]`

Starting with the octet at offset `of`, retain the remainder of this WriteBuffer, such that the octet at offset `of` is shifted to offset 0, the octet at offset `of + 1` is shifted to offset 1, and so on up to the octet 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 octet within the WriteBuffer that will be retained

Exceptions:

  | IndexOutOfBoundsException | if `of` is greater than `length()`

Implemented in AbstractWriteBuffer.

virtual void retain | ( | size32_t | of,
|  | size32_t | cb |
| ) |  |  | `[pure virtual]`

Starting with the octet at offset `of`, retain `cb` octets in this WriteBuffer, such that the octet at offset `of` is shifted to offset 0, the octet at offset `of + 1` is shifted to offset 1, and so on up to the octet 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 octet to retain `of` are `(of >= 0 && of <= length())`. Legal values for the number of octets 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 octets 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 octet within the WriteBuffer that will be retained
  | cb | the number of octets to retain

Exceptions:

  | IndexOutOfBoundsException | if `of + cb` is greater than `length()`

Implemented in DelegatingWriteBuffer, and OctetArrayWriteBuffer.

virtual void clear | ( |  | ) | `[pure virtual]`

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.

Implemented in AbstractWriteBuffer, and DelegatingWriteBuffer.

virtual WriteBuffer::Handle getWriteBuffer | ( | size32_t | of | ) | `[pure virtual]`

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

Exceptions:

  | IndexOutOfBoundsException | if `of` is larger than the `getMaximumCapacity()` of this WriteBuffer

Implemented in AbstractWriteBuffer.

virtual WriteBuffer::Handle getWriteBuffer | ( | size32_t | of,
|  | size32_t | cb |
| ) |  |  | `[pure virtual]`

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 octets 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 octet within this WriteBuffer to map to offset 0 of the new WriteBuffer
  | cb | the number of octets to cover in the resulting WriteBuffer

Returns:
  a WriteBuffer that represents a portion of this WriteBuffer

Exceptions:

  | IndexOutOfBoundsException | if `of + cb` is larger than the `getMaximumCapacity()` of this WriteBuffer

Implemented in AbstractWriteBuffer.

virtual ReadBuffer::View getReadBuffer | ( |  | ) | const `[pure virtual]`

Get a ReadBuffer object that is a snapshot of this WriteBuffer's data.

This method is functionally equivalent to the following code:

     Array<octet_t>::View vab = toOctetArray();
     return OctetArrayReadBuffer::create(vab, 0, vab->length(), true);

Returns:
  a ReadBuffer that reflects the point-in-time contents of this WriteBuffer; the returned ReadBuffer is inherently immutable

Implemented in AbstractWriteBuffer.

virtual ReadBuffer::View getUnsafeReadBuffer | ( |  | ) | const `[pure virtual]`

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

Implemented in DelegatingWriteBuffer, and OctetArrayWriteBuffer.

virtual Array<octet_t>::View toOctetArray | ( |  | ) | const `[pure virtual]`

Returns an octet array that holds the complete contents of this WriteBuffer.

This method is functionally equivalent to the following code:

     return getUnsafeReadBuffer()->toOctetArray();

Returns:
  the contents of this WriteBuffer as an octet array

Implemented in AbstractWriteBuffer, and DelegatingWriteBuffer.

virtual BufferOutput::Handle getBufferOutput | ( | size32_t | of = `0` | ) | `[pure virtual]`

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

Parameters:

  | of | the offset of the first octet of this buffer that the BufferOutput will write to

Returns:
  a BufferOutput that will write to this buffer

Implemented in AbstractWriteBuffer.

virtual BufferOutput::Handle getAppendingBufferOutput | ( |  | ) | `[pure virtual]`

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

Implemented in AbstractWriteBuffer.

The documentation for this class was generated from the following file:

- coherence/io/WriteBuffer.hpp

Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.