com.h3c.nbio

## Class MessageBuffer<M extends Message>

- java.lang.Object
- - com.h3c.nbio.MessageBuffer<M>

- Type Parameters:
    `M` - message type

      public abstract class MessageBuffer<M extends Message>
      extends Object

  Abstraction of a bidirectional message transfer buffer backed by a `byte channel` and driven by an `I/O loop`.

  Implementations are expected to provide means to get and put a message into the provided byte buffers.

  Writers feed the data in form of messages via one of the `queue(java.util.List<M>)` methods and the data will get flushed

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `protected static int` | `BUFFER_SIZE` Initial buffer size for in-bound & out-bound byte buffers.
    `protected static double` | `GROWTH_FACTOR` Default growth factor for the out-bound byte buffer.
    `protected org.slf4j.Logger` | `log` Shared logger.
    `protected static int` | `MAX_AGE` Default maximum age in milliseconds before the buffer becomes stale.

  - ### Constructor Summary

    Constructors
    Modifier | Constructor and Description
    --- | ---
    `protected` | `MessageBuffer(ByteChannel ch, IOLoop<M,?> loop)` Creates a message buffer backed by the specified byte channel and driven by the given I/O loop.
    `protected` | `MessageBuffer(ByteChannel ch, IOLoop<M,?> loop, SSLContext sslContext)` Creates a message buffer backed by the specified byte channel and driven by the given I/O loop.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `boolean` | `alreadyDiscarded()` Returns true if this buffer has already been discarded.
    `List<M>` | `dequeue()` Gets a list of messages from the buffer in non-blocking fashion.
    `void` | `discard()` Discards the message buffer.
    `void` | `flush()` Flushes any pending writes accumulated in the out-bound buffer to the backing socket channel.
    `boolean` | `flushFailed()` Returns true if a prior flush encountered an error.
    `protected abstract M` | `get(ByteBuffer rb)` Gets a single message from the supplied byte buffer.
    `Exception` | `getFlushError()` Gets the prior flush error, if one occurred.
    `protected ByteBuffer` | `growBuffer(ByteBuffer buffer)` Grows the given buffer by `growthFactor()` and returns a new buffer instance with any remaining data copied into it.
    `protected double` | `growthFactor()` Returns the out-bound buffer growth-factor.
    `ThroughputTracker` | `inBytes()` Returns the in-bound bytes throughput tracker.
    `ThroughputTracker` | `inMessages()` Returns the in-bound messages throughput tracker.
    `SelectionKey` | `key()` Returns the selection key used for registration of the backing socket channel.
    `IOLoop<M,?>` | `loop()` Returns the IO loop to which this stream is bound.
    `protected int` | `maxAge()` Returns the maximum age before buffer is considered stale without any dequeue/queue operations.
    `ThroughputTracker` | `outBytes()` Returns the out-bound bytes throughput tracker.
    `ThroughputTracker` | `outMessages()` Returns the out-bound messages throughput tracker.
    `protected abstract void` | `put(M message, ByteBuffer wb)` Puts the specified message into the internal buffer.
    `void` | `queue(List<M> messages)` Queues the list of messages to the buffer and flushes to the backing channel if necessary.
    `void` | `queue(M message)` Queues the message to the buffer and flushes to the backing channel if necessary.
    `void` | `setKey(SelectionKey key)` Sets the select key obtained when the backing channel of this stream was registered with the IO loop selector.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Field Detail

    - #### log

          protected org.slf4j.Logger log

      Shared logger.

    - #### BUFFER_SIZE

          protected static final int BUFFER_SIZE

      Initial buffer size for in-bound & out-bound byte buffers.
      See Also:
        Constant Field Values

    - #### GROWTH_FACTOR

          protected static final double GROWTH_FACTOR

      Default growth factor for the out-bound byte buffer.
      See Also:
        Constant Field Values

    - #### MAX_AGE

          protected static final int MAX_AGE

      Default maximum age in milliseconds before the buffer becomes stale.
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### MessageBuffer

          protected MessageBuffer(ByteChannel ch,
                       IOLoop<M,?> loop)

      Creates a message buffer backed by the specified byte channel and driven by the given I/O loop.
      Parameters:
        `ch` - backing socket channel
        `loop` - driver IO loop

    - #### MessageBuffer

          protected MessageBuffer(ByteChannel ch,
                       IOLoop<M,?> loop,
                       SSLContext sslContext)

      Creates a message buffer backed by the specified byte channel and driven by the given I/O loop.
      Parameters:
        `ch` - backing socket channel
        `loop` - driver IO loop
        `sslContext` - TLS secure context

  - ### Method Detail

    - #### alreadyDiscarded

          public boolean alreadyDiscarded()

      Returns true if this buffer has already been discarded. That is, `discard()` has been called.
      Returns:
        true if this buffer has been discarded

    - #### discard

          public void discard()

      Discards the message buffer. This involves freezing all throughput trackers, closing the backing channel and unregistering it from the driver loop.

    - #### setKey

          public void setKey(SelectionKey key)

      Sets the select key obtained when the backing channel of this stream was registered with the IO loop selector.
      Parameters:
        `key` - select key from registration of the backing channel

    - #### get

          protected abstract M get(ByteBuffer rb)

      Gets a single message from the supplied byte buffer.

      Implementations are expected not to flip, reset or clear the buffer.

      Parameters:
        `rb` - read byte buffer
      Returns:
        read message or null if message could not be extracted due to insufficient available bytes

    - #### put

          protected abstract void put(M message,
                 ByteBuffer wb)

      Puts the specified message into the internal buffer.

      Implementations are expected not to flip, reset or clear the buffer.

      Parameters:
        `message` - message to be placed to the buffer
        `wb` - write byte buffer

    - #### dequeue

          public List<M> dequeue()
                                          throws IOException

      Gets a list of messages from the buffer in non-blocking fashion. If there are no messages to be read, the list will be empty. If the backing socket channel has been closed, null will be returned.
      Returns:
        list of read messages; null if backing channel is closed
      Throws:
        `IOException` - if data could not be read

    - #### queue

          public void queue(List<M> messages)
                     throws IOException

      Queues the list of messages to the buffer and flushes to the backing channel if necessary.
      Parameters:
        `messages` - list of messages to be transfered
      Throws:
        `IOException` - if data could not be transfered or flushed

    - #### queue

          public void queue(M message)
                     throws IOException

      Queues the message to the buffer and flushes to the backing channel if necessary.
      Parameters:
        `message` - message to be transfered
      Throws:
        `IOException` - if data could not be transfered or flushed

    - #### flush

          public void flush()
                     throws IOException

      Flushes any pending writes accumulated in the out-bound buffer to the backing socket channel.
      Throws:
        `IOException` - if flush failed

    - #### flushFailed

          public boolean flushFailed()

      Returns true if a prior flush encountered an error. The error can be retrieved via `getFlushError()` method.
      Returns:
        true if a write failed

    - #### getFlushError

          public Exception getFlushError()

      Gets the prior flush error, if one occurred.
      Returns:
        flush error; null if none occurred

    - #### loop

          public IOLoop<M,?> loop()

      Returns the IO loop to which this stream is bound.
      Returns:
        I/O loop used to drive this stream

    - #### key

          public SelectionKey key()

      Returns the selection key used for registration of the backing socket channel.
      Returns:
        socket channel registration selection key

    - #### growBuffer

          protected ByteBuffer growBuffer(ByteBuffer buffer)

      Grows the given buffer by `growthFactor()` and returns a new buffer instance with any remaining data copied into it.
      Parameters:
        `buffer` - the buffer to grow
      Returns:
        a new (bigger) buffer instance

    - #### growthFactor

          protected double growthFactor()

      Returns the out-bound buffer growth-factor.
      Returns:
        growth factor; must be larger than 1.0

    - #### maxAge

          protected int maxAge()

      Returns the maximum age before buffer is considered stale without any dequeue/queue operations.
      Returns:
        max age in milliseconds; must be greater than 1

    - #### inMessages

          public ThroughputTracker inMessages()

      Returns the in-bound messages throughput tracker.
      Returns:
        throughput tracker

    - #### inBytes

          public ThroughputTracker inBytes()

      Returns the in-bound bytes throughput tracker.
      Returns:
        throughput tracker

    - #### outMessages

          public ThroughputTracker outMessages()

      Returns the out-bound messages throughput tracker.
      Returns:
        throughput tracker

    - #### outBytes

          public ThroughputTracker outBytes()

      Returns the out-bound bytes throughput tracker.
      Returns:
        throughput tracker

Copyright © 2014. All Rights Reserved.