## 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
     }

Version:
  $Rev: 2122 $, $Date: 2010-02-02 11:00:04 +0900 (Tue, 02 Feb 2010) $
Author:
  The Netty Project, Trustin Lee

Nested Class Summary

Nested classes/interfaces inherited from interface org.jboss.netty.channel.ChannelHandler
`ChannelHandler.Sharable`

Constructor Summary
`BlockingReadHandler()` Creates a new instance with the default unbounded `BlockingQueue` implementation.
`BlockingReadHandler(BlockingQueue<ChannelEvent> queue)` Creates a new instance with the specified `BlockingQueue`.

Method Summary
`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 the default unbounded `BlockingQueue` implementation.

### 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-2010 JBoss, a division of Red Hat, Inc.. All Rights Reserved.