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
`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`