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