Oracle Coherence for C++ API
Release 3.6.1.0

E18813-01

DelegatingWriteBuffer Class Reference

#include <coherence/io/DelegatingWriteBuffer.hpp>

Inherits AbstractWriteBuffer.

List of all members.


Detailed Description

A DelegatingWriteBuffer is a WriteBuffer that writes through to an underlying (or "containing") WriteBuffer.

Basically, it allows a process that is writing to a WriteBuffer to ask for a "protected" sub-portion of that WriteBuffer to hand to a second process, such that the second process can not affect (or even read from) the WriteBuffer outside of the portion that the first process explicitly designated as viewable and modifiable.

This implementation is explicitly not thread-safe.

Author:
jh 2007.01.10

Public Types

typedef spec::Handle  Handle
  DelegatingWriteBuffer Handle definition.
typedef spec::View  View
  DelegatingWriteBuffer View definition.
typedef spec::Holder  Holder
  DelegatingWriteBuffer Holder definition.
typedef this_spec::Handle  Handle
  AbstractWriteBuffer Handle definition.
typedef this_spec::View  View
  AbstractWriteBuffer View definition.
typedef this_spec::Holder  Holder
  AbstractWriteBuffer Holder definition.

Public Member Functions

virtual size32_t  length () const
  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

virtual size32_t  getCapacity () const
  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

virtual size32_t  getMaximumCapacity () const
  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

virtual void  write (size32_t ofDest, octet_t b)
  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

virtual void  write (size32_t ofDest, Array< octet_t >::View vabSrc, size32_t ofSrc, size32_t cbSrc)
  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()

virtual void  write (size32_t ofDest, ReadBuffer::View vBufSrc, size32_t ofSrc, size32_t 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:


 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

virtual void  retain (size32_t of, size32_t cb)
  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()

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

virtual ReadBuffer::View  getUnsafeReadBuffer () const
  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

virtual Array
< octet_t >::View 
toOctetArray () const
  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


Protected Member Functions

  DelegatingWriteBuffer (WriteBuffer::Handle hBuf, size32_t of, size32_t cb)
  Construct a DelegatingWriteBuffer that will delegate to the containing WriteBuffer.
  DelegatingWriteBuffer (const DelegatingWriteBuffer &that)
  Copy constructor.
virtual
BufferOutput::Handle 
instantiateBufferOutput ()
  Factory method: Instantiate a BufferOutput object to write data to the WriteBuffer.
Returns:
a new BufferOutput writing to this ReadBuffer

virtual void  checkBounds (size32_t of, size32_t cb) const
  Test an offset and length of data to write to see if it can be written to this buffer.
virtual void  updateLength (size32_t cb)
  Update the length if the passed length is greater than the current buffer length.

Protected Attributes

MemberHandle
< WriteBuffer
m_hBuf
  The WriteBuffer to delegate to; the "containing" WriteBuffer.
size32_t  m_ofStart
  Offset into the containing WriteBuffer where this WriteBuffer starts.
size32_t  m_cb
  Length in octets of this WriteBuffer.
size32_t  m_cbMax
  Maximum number of octets in this WriteBuffer.

Classes

class   DelegatingBufferOutput
  A BufferOutput implementation that delegates to a BufferOutput implementation, except that its offset range is shifted and limited. More...

Constructor & Destructor Documentation

DelegatingWriteBuffer ( WriteBuffer::Handle  hBuf,
size32_t  of,
size32_t  cb  
) [protected]

Construct a DelegatingWriteBuffer that will delegate to the containing WriteBuffer.

Parameters:
hBuf  the containing WriteBuffer
of  the offset within the containing WriteBuffer that this WriteBuffer is starting at
cb  the maximum capacity for this WriteBuffer

Member Function Documentation

virtual void checkBounds ( size32_t  of,
size32_t  cb  
) const [protected, virtual]

Test an offset and length of data to write to see if it can be written to this buffer.

Parameters:
of  offset to write data at
cb  length in octets of data

virtual void updateLength ( size32_t  cb  )  [protected, virtual]

Update the length if the passed length is greater than the current buffer length.

Parameters:
cb  the possible new length

The documentation for this class was generated from the following file:
Copyright © 2000, 2010, Oracle and/or its affiliates. All rights reserved.