# OpenORB 1.3.1: Class MarshalBuffer

## org.openorb.io
Class MarshalBuffer

    java.lang.Object
      |
      +--org.openorb.io.MarshalBuffer

public class MarshalBuffer
extends java.lang.Object

MarshalBuffers serve as a sink for data to be marshaled into. Fragmentation of the data as it is marshaled can be controlled by the Listener registered with the buffer at creation time.

Author:
  Unknown

Inner Class Summary
`static interface` `MarshalBuffer.BlockGenerator` Interface BlockGenerator.
`static interface` `MarshalBuffer.HeaderGenerator` Interface HeaderGenerator.
`static interface` `MarshalBuffer.Listener`

Constructor Summary
`MarshalBuffer()` Construct marshal buffer without listener.
`MarshalBuffer(MarshalBuffer.Listener listener, java.lang.Object listenerCookie)` Construct marshall buffer with listener.

Method Summary
`void` `addHeader(MarshalBuffer.HeaderGenerator gen, int len, boolean frag, java.lang.Object cookie)` Add a header generator.
`void` `alloc(OctetSeqHolder buf, IntHolder off, int len)` Alocate space at end of buffer.
`void` `append(byte[] buf, int off, int len)` Attach a readonly scrap to the end of the buffer.
`int` `available()` count of all bytes available for extracting into a fragment.
`void` `beginBlock(MarshalBuffer.BlockGenerator gen, int len, boolean frag, java.lang.Object cookie)` Begin a block.
`void` `cancel(SystemException ex)` Cancel marshal.
`void` `close()` Close.
`void` `endBlock()` Call the endBlock operation on the last block written with the beginBlock operation and remove the hold on the data.
`StorageBuffer` `fragment(int len)` Prepare fragment.
`boolean` `getAllowFragment()` Test if fragmentation is currently enabled.
`boolean` `isStandalone()` Returns true if not connected to a listener.
`StorageBuffer` `lastFragment()` Return the last fragment.
`static void` `main(java.lang.String[] args)`
`void` `pad(int len)` Insert padding.
`void` `setAllowFragment(boolean allowFragment)` Allow or dissallow fragmentation.
`int` `size()` count of all bytes inserted into the buffer, including previous fragments

Methods inherited from class java.lang.Object
`equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

Constructor Detail

### MarshalBuffer

    public MarshalBuffer()

  Construct marshal buffer without listener. Use the fragment and lastFragment methods to extract data from the buffer.

### MarshalBuffer

    public MarshalBuffer(MarshalBuffer.Listener listener,
                         java.lang.Object listenerCookie)

  Construct marshall buffer with listener. The listener is informed when the buffer grows or is closed, and calls the fragment or lastFragment methods respectivly.

Method Detail

### isStandalone

    public boolean isStandalone()

  Returns true if not connected to a listener. To get the data from the buffer use lastFragment()

### size

    public int size()

  count of all bytes inserted into the buffer, including previous fragments

### available

    public int available()

  count of all bytes available for extracting into a fragment.

### setAllowFragment

    public void setAllowFragment(boolean allowFragment)

  Allow or dissallow fragmentation. An opertunity to send a fragment will occour when this is true only after the next append to the buffer.

### getAllowFragment

    public boolean getAllowFragment()

  Test if fragmentation is currently enabled. This may be false even after a call to setAllowFragment(true) if fragmentation is disabled for some other reason. While this returns false availIncreaced will not be called on the listener

### alloc

    public void alloc(OctetSeqHolder buf,
                      IntHolder off,
                      int len)

  Alocate space at end of buffer. The dest scrap is modified so it's contents contain the allocated space. The allocated space is considered to be scratch space, it's buffer is only avalable until the next call.
  Parameters:
    `buf` - Out parameter, holds pointer to scratch space on return. This space should not be stored. The pointer will be invalidated by setting it's value to null on next call.
    `off` - Out parameter, holds buffer offset on return.
    `len` - Length of requested buffer.

### append

    public void append(byte[] buf,
                       int off,
                       int len)

  Attach a readonly scrap to the end of the buffer. This will be stored by reference and will not be copied unless the StorageBuffer it spawns uses readWriteMode when iterating over itself.

### pad

    public void pad(int len)

  Insert padding.

### addHeader

    public void addHeader(MarshalBuffer.HeaderGenerator gen,
                          int len,
                          boolean frag,
                          java.lang.Object cookie)

  Add a header generator. Header generators generate data at a later time, typically writing the length of the entire fragment or message when it is about to be sent. Header generators also get an opportunity to write to the beginning of a new fragment when a fragment is taken from the buffer.
  Parameters:
    `gen` - the header generator
    `len` - the length of the data which will be written by the generator.
    `frag` - true if the header allows fragmentation to occour within it's range of authority.
    `cookie` - passed to the begin message and end message operations.

### beginBlock

    public void beginBlock(MarshalBuffer.BlockGenerator gen,
                           int len,
                           boolean frag,
                           java.lang.Object cookie)

  Begin a block. Blocks unlike headers can overlap fragmentation boundaries but can themselves be fragmented when the position in the buffer that they hold is about to be sent. Every beginBlock operation is always paired with an endBlock operation some time later in the stream.

  Nonfragmentable blocks can be nested, however fragmentable blocks cannot.

  Parameters:
    `gen` - the block generator.
    `len` - the length of the data which will be written.
    `frag` - true if the block can be fragmented.
    `cookie` - passed to the fragment block and end block operation.

### endBlock

    public void endBlock()

  Call the endBlock operation on the last block written with the beginBlock operation and remove the hold on the data.

### close

    public void close()

  Close. Calls close operation on listeners and frees all data contained within the buffer. It is illegal to call close while within a block.

### cancel

    public void cancel(SystemException ex)

  Cancel marshal. Calls cancel operation on listeners and frees all data contained within the buffer. All following allocations will either be silently discarded (if the listener does not throw an exception) or will be responded to with the exception passed.

### fragment

    public StorageBuffer fragment(int len)

  Prepare fragment. The returned storage buffer will be exactly the length specified.

### lastFragment

    public StorageBuffer lastFragment()

  Return the last fragment. This also closes the buffer.

### main

    public static void main(java.lang.String[] args)