org.jboss.netty.handler.queue

## Class BlockingReadHandler<E>

- java.lang.Object
- - org.jboss.netty.channel.SimpleChannelUpstreamHandler
  - - org.jboss.netty.handler.queue.BlockingReadHandler<E>

- Type Parameters:
    `E` - the type of the received messages
  All Implemented Interfaces:
    ChannelHandler, ChannelUpstreamHandler

      public class BlockingReadHandler<E>
      extends SimpleChannelUpstreamHandler

  Emulates blocking read operation. This handler stores all received messages into a `BlockingQueue` and returns the received messages when `read()`, `read(long, TimeUnit)`, `readEvent()`, or `readEvent(long, TimeUnit)` method is called.

  Please note that this handler is only useful for the cases where there are very small number of connections, such as testing and simple client-side application development.

  Also, any handler placed after this handler will never receive `messageReceived`, `exceptionCaught`, and `channelClosed` events, hence it should be placed in the last place in a pipeline.

  Here is an example that demonstrates the usage:

       BlockingReadHandler<ChannelBuffer> reader =
               new BlockingReadHandler<ChannelBuffer>();
       ChannelPipeline p = ...;
       p.addLast("reader", reader);

       ...

       // Read a message from a channel in a blocking manner.
       try {
           ChannelBuffer buf = reader.read(60, TimeUnit.SECONDS);
           if (buf == null) {
               // Connection closed.
           } else {
               // Handle the received message here.
           }
       } catch (BlockingReadTimeoutException e) {
           // Read timed out.
       } catch (IOException e) {
           // Other read errors
       }

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.jboss.netty.channel.ChannelHandler

      `ChannelHandler.Sharable`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `BlockingReadHandler()` Creates a new instance with `LinkedBlockingQueue`
    `BlockingReadHandler(BlockingQueue<ChannelEvent> queue)` Creates a new instance with the specified `BlockingQueue`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `channelClosed(ChannelHandlerContext ctx, ChannelStateEvent e)` Invoked when a `Channel` was closed and all its related resources were released.
    `void` | `exceptionCaught(ChannelHandlerContext ctx, ExceptionEvent e)` Invoked when an exception was raised by an I/O thread or a `ChannelHandler`.
    `protected BlockingQueue<ChannelEvent>` | `getQueue()` Returns the queue which stores the received messages.
    `boolean` | `isClosed()` Returns `true` if and only if the `Channel` associated with this handler has been closed.
    `void` | `messageReceived(ChannelHandlerContext ctx, MessageEvent e)` Invoked when a message object (e.g: `ChannelBuffer`) was received from a remote peer.
    `E` | `read()` Waits until a new message is received or the associated `Channel` is closed.
    `E` | `read(long timeout, TimeUnit unit)` Waits until a new message is received or the associated `Channel` is closed.
    `ChannelEvent` | `readEvent()` Waits until a new `ChannelEvent` is received or the associated `Channel` is closed.
    `ChannelEvent` | `readEvent(long timeout, TimeUnit unit)` Waits until a new `ChannelEvent` is received or the associated `Channel` is closed.

    - ### Methods inherited from class org.jboss.netty.channel.SimpleChannelUpstreamHandler

      `channelBound, channelConnected, channelDisconnected, channelInterestChanged, channelOpen, channelUnbound, childChannelClosed, childChannelOpen, handleUpstream, writeComplete`

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

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

- - ### Constructor Detail

    - #### BlockingReadHandler

          public BlockingReadHandler()

      Creates a new instance with `LinkedBlockingQueue`

    - #### BlockingReadHandler

          public BlockingReadHandler(BlockingQueue<ChannelEvent> queue)

      Creates a new instance with the specified `BlockingQueue`.

  - ### Method Detail

    - #### getQueue

          protected BlockingQueue<ChannelEvent> getQueue()

      Returns the queue which stores the received messages. The default implementation returns the queue which was specified in the constructor.

    - #### isClosed

          public boolean isClosed()

      Returns `true` if and only if the `Channel` associated with this handler has been closed.
      Throws:
        `IllegalStateException` - if this handler was not added to a `ChannelPipeline` yet

    - #### read

          public E read()
                 throws IOException,
                        InterruptedException

      Waits until a new message is received or the associated `Channel` is closed.
      Returns:
        the received message or `null` if the associated `Channel` has been closed
      Throws:
        `IOException` - if failed to receive a new message
        `InterruptedException` - if the operation has been interrupted

    - #### read

          public E read(long timeout,
               TimeUnit unit)
                 throws IOException,
                        InterruptedException

      Waits until a new message is received or the associated `Channel` is closed.
      Parameters:
        `timeout` - the amount time to wait until a new message is received. If no message is received within the timeout, `BlockingReadTimeoutException` is thrown.
        `unit` - the unit of `timeout`
      Returns:
        the received message or `null` if the associated `Channel` has been closed
      Throws:
        `BlockingReadTimeoutException` - if no message was received within the specified timeout
        `IOException` - if failed to receive a new message
        `InterruptedException` - if the operation has been interrupted

    - #### readEvent

          public ChannelEvent readEvent()
                                 throws InterruptedException

      Waits until a new `ChannelEvent` is received or the associated `Channel` is closed.
      Returns:
        a `MessageEvent` or an `ExceptionEvent`. `null` if the associated `Channel` has been closed
      Throws:
        `InterruptedException` - if the operation has been interrupted

    - #### readEvent

          public ChannelEvent readEvent(long timeout,
                               TimeUnit unit)
                                 throws InterruptedException,
                                        BlockingReadTimeoutException

      Waits until a new `ChannelEvent` is received or the associated `Channel` is closed.
      Parameters:
        `timeout` - the amount time to wait until a new `ChannelEvent` is received. If no message is received within the timeout, `BlockingReadTimeoutException` is thrown.
        `unit` - the unit of `timeout`
      Returns:
        a `MessageEvent` or an `ExceptionEvent`. `null` if the associated `Channel` has been closed
      Throws:
        `BlockingReadTimeoutException` - if no event was received within the specified timeout
        `InterruptedException` - if the operation has been interrupted

    - #### messageReceived

          public void messageReceived(ChannelHandlerContext ctx,
                             MessageEvent e)
                               throws Exception

      Description copied from class: `SimpleChannelUpstreamHandler`
      Invoked when a message object (e.g: `ChannelBuffer`) was received from a remote peer.
      Overrides:
        `messageReceived` in class `SimpleChannelUpstreamHandler`
      Throws:
        `Exception`

    - #### exceptionCaught

          public void exceptionCaught(ChannelHandlerContext ctx,
                             ExceptionEvent e)
                               throws Exception

      Description copied from class: `SimpleChannelUpstreamHandler`
      Invoked when an exception was raised by an I/O thread or a `ChannelHandler`.
      Overrides:
        `exceptionCaught` in class `SimpleChannelUpstreamHandler`
      Throws:
        `Exception`

    - #### channelClosed

          public void channelClosed(ChannelHandlerContext ctx,
                           ChannelStateEvent e)
                             throws Exception

      Description copied from class: `SimpleChannelUpstreamHandler`
      Invoked when a `Channel` was closed and all its related resources were released.
      Overrides:
        `channelClosed` in class `SimpleChannelUpstreamHandler`
      Throws:
        `Exception`

Copyright © 2008-2012 The Netty Project. All Rights Reserved.