com.h3c.nbio

## Class IOLoop<M extends Message,B extends MessageBuffer<M>>

- java.lang.Object
- - com.h3c.nbio.SelectLoop
  - - com.h3c.nbio.IOLoop<M,B>

- Type Parameters:
    `M` - message type
    `B` - message buffer type
  All Implemented Interfaces:
    Runnable

      public abstract class IOLoop<M extends Message,B extends MessageBuffer<M>>
      extends SelectLoop

  Abstraction of an I/O loop for driving buffered message transfer across network socket connections.

  Loosely based on I/O loop algorithm authored by David Erickson.

- - ### Field Summary

    - ### Fields inherited from class com.h3c.nbio.SelectLoop

      `DEFAULT_TIMEOUT, log, selector, stopped, timeout`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `IOLoop()` Creates an IO loop with default timeout.
    `IOLoop(long timeout)` Creates an IO loop with the specified timeout.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `protected void` | `connect(SelectionKey key)` Processes a connection request represented by the supplied select key.
    `protected abstract B` | `createBuffer(ByteChannel ch, SSLContext sslContext)` Creates a new message buffer backed by the given socket channel and driven by the specified loop.
    `protected void` | `discardBuffer(MessageBuffer<M> b)` Discards the specified message buffer from the list of registered buffers.
    `protected void` | `handleMessageProcessingException(B b, RuntimeException e)` Invoked if a runtime exception is thrown from `processMessages(com.h3c.nbio.MessageBuffer<M>, java.util.List<M>)`.
    `protected void` | `loop()` I/O event loop.
    `protected void` | `processIO(SelectionKey key)` Processes a single IO request represented by the supplied select key.
    `protected abstract void` | `processMessages(MessageBuffer<M> b, List<M> messages)` Processes the list of messages received from the specified message buffer.
    `void` | `prune()` Prunes the registered buffers by discarding any stale ones.
    `void` | `registerAccept(SocketChannel ch, SSLContext sslContext)` Registers a new socket channel by creating a new message buffer backed by the socket channel and driven by this loop.
    `void` | `registerConnect(SocketChannel ch, SSLContext sslContext)` Registers a new client-side socket channel by creating a new message buffer backed by the socket channel and driven by this loop.

    - ### Methods inherited from class com.h3c.nbio.SelectLoop

      `cease, getError, openSelector, run, signalStart, waitForFinish, waitForStart`

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

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

- - ### Constructor Detail

    - #### IOLoop

          public IOLoop()
                 throws IOException

      Creates an IO loop with default timeout.
      Throws:
        `IOException` - if unable to open selector

    - #### IOLoop

          public IOLoop(long timeout)
                 throws IOException

      Creates an IO loop with the specified timeout.
      Parameters:
        `timeout` - select timeout in milliseconds
      Throws:
        `IOException` - if unable to open selector

  - ### Method Detail

    - #### createBuffer

          protected abstract B createBuffer(ByteChannel ch,
                       SSLContext sslContext)

      Creates a new message buffer backed by the given socket channel and driven by the specified loop. If an SSL context is specified, the IOLoop is expected to provide a secure `MessageBuffer`.
      Parameters:
        `ch` - backing byte channel
        `sslContext` - optional SSL context
      Returns:
        newly created message buffer

    - #### discardBuffer

          protected void discardBuffer(MessageBuffer<M> b)

      Discards the specified message buffer from the list of registered buffers.

      One should not invoke this method directly as this is merely a hook invoked by the default implementation of `MessageBuffer.discard()` method, which is what should be used directly instead.

      Parameters:
        `b` - message buffer

    - #### processMessages

          protected abstract void processMessages(MessageBuffer<M> b,
                             List<M> messages)

      Processes the list of messages received from the specified message buffer.
      Parameters:
        `b` - source message buffer
        `messages` - list of received messages; guaranteed not to be null and not empty

    - #### connect

          protected void connect(SelectionKey key)

      Processes a connection request represented by the supplied select key. Default implementation sets the key's `interestedOps` to `SelectionKey.OP_READ` and then attempts to finish the connection on the key socket channel.
      Parameters:
        `key` - selection key holding the pending connect operation.

    - #### processIO

          protected void processIO(SelectionKey key)

      Processes a single IO request represented by the supplied select key.
      Parameters:
        `key` - selection key holding the pending I/O operation.

    - #### handleMessageProcessingException

          protected void handleMessageProcessingException(B b,
                                              RuntimeException e)

      Invoked if a runtime exception is thrown from `processMessages(com.h3c.nbio.MessageBuffer<M>, java.util.List<M>)`.

      This default implementation simply rethrows the exception.

      Parameters:
        `b` - the buffer that was being processed
        `e` - the runtime exception that was thrown

    - #### prune

          public void prune()

      Prunes the registered buffers by discarding any stale ones.

    - #### registerAccept

          public void registerAccept(SocketChannel ch,
                            SSLContext sslContext)

      Registers a new socket channel by creating a new message buffer backed by the socket channel and driven by this loop. If an SSL context is specified, the IOLoop is expected to provide a secure `MessageBuffer`.
      Parameters:
        `ch` - socket channel
        `sslContext` - optional SSL context

    - #### registerConnect

          public void registerConnect(SocketChannel ch,
                             SSLContext sslContext)

      Registers a new client-side socket channel by creating a new message buffer backed by the socket channel and driven by this loop. If an SSL context is specified, the IOLoop is expected to provide a secure `MessageBuffer`.
      Parameters:
        `ch` - socket channel
        `sslContext` - optional SSL context

    - #### loop

          protected void loop()
                       throws IOException

      Description copied from class: `SelectLoop`
      I/O event loop. Implementations are expected to break when `SelectLoop.stopped` becomes `true` via `SelectLoop.cease()` invocation. Also, implementations are expected to `SelectLoop.signalStart()` when ready.
      Specified by:
        `loop` in class `SelectLoop`
      Throws:
        `IOException` - if unable to properly select channels or an I/O error is propagated by an event handler.

Copyright © 2014. All Rights Reserved.