org.jboss.netty.handler.timeout
Class IdleStateHandler

java.lang.Object
  org.jboss.netty.channel.SimpleChannelUpstreamHandler
      org.jboss.netty.handler.timeout.IdleStateHandler

All Implemented Interfaces:

ChannelHandler, ChannelUpstreamHandler, LifeCycleAwareChannelHandler, ExternalResourceReleasable

@ChannelHandler.Sharable
public class IdleStateHandler
extends SimpleChannelUpstreamHandler
implements LifeCycleAwareChannelHandler, ExternalResourceReleasable

Triggers an IdleStateEvent when a Channel has not performed read, write, or both operation for a while.

Supported idle states

Property	Meaning
readerIdleTime	an IdleStateEvent whose state is IdleState.READER_IDLE will be triggered when no read was performed for the specified period of time. Specify 0 to disable.
writerIdleTime	an IdleStateEvent whose state is IdleState.WRITER_IDLE will be triggered when no write was performed for the specified period of time. Specify 0 to disable.
allIdleTime	an IdleStateEvent whose state is IdleState.ALL_IDLE will be triggered when neither read nor write was performed for the specified period of time. Specify 0 to disable.

 // An example that sends a ping message when there is no outbound traffic
 // for 30 seconds.  The connection is closed when there is no inbound traffic
 // for 60 seconds.

 public class MyPipelineFactory implements ChannelPipelineFactory {

     private final Timer timer;
     private final ChannelHandler idleStateHandler;

     public MyPipelineFactory(Timer timer) {
         this.timer = timer;
         this.idleStateHandler = new IdleStateHandler(timer, 60, 30, 0), // timer must be shared.
     }

     public ChannelPipeline getPipeline() {
         return Channels.pipeline(
             idleStateHandler,
             new MyHandler());
     }
 }

 // Handler should handle the IdleStateEvent triggered by IdleStateHandler.
 public class MyHandler extends IdleStateAwareChannelHandler {

     @Override
     public void channelIdle(ChannelHandlerContext ctx, IdleStateEvent e) {
         if (e.getState() == IdleState.READER_IDLE) {
             e.getChannel().close();
         } else if (e.getState() == IdleState.WRITER_IDLE) {
             e.getChannel().write(new PingMessage());
         }
     }
 }

 ServerBootstrap bootstrap = ...;
 Timer timer = new HashedWheelTimer();
 ...
 bootstrap.setPipelineFactory(new MyPipelineFactory(timer));
 ...
 

The Timer which was specified when the IdleStateHandler is created should be stopped manually by calling releaseExternalResources() or Timer.stop() when your application shuts down.

Version:

$Rev: 2224 $, $Date: 2010-03-30 17:02:32 +0900 (Tue, 30 Mar 2010) $

Author:

The Netty Project, Trustin Lee

See Also:

ReadTimeoutHandler, WriteTimeoutHandler

Nested Class Summary

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

ChannelHandler.Sharable

Constructor Summary

IdleStateHandler(Timer timer, int readerIdleTimeSeconds, int writerIdleTimeSeconds, int allIdleTimeSeconds)
Creates a new instance.

IdleStateHandler(Timer timer, long readerIdleTime, long writerIdleTime, long allIdleTime, TimeUnit unit)
Creates a new instance.

Method Summary

void	afterAdd(ChannelHandlerContext ctx)
void	afterRemove(ChannelHandlerContext ctx)
void	beforeAdd(ChannelHandlerContext ctx)
void	beforeRemove(ChannelHandlerContext ctx)
void	channelClosed(ChannelHandlerContext ctx, ChannelStateEvent e) Invoked when a Channel was closed and all its related resources were released.
protected void	channelIdle(ChannelHandlerContext ctx, IdleState state, long lastActivityTimeMillis)
void	channelOpen(ChannelHandlerContext ctx, ChannelStateEvent e) Invoked when a Channel is open, but not bound nor connected.
void	messageReceived(ChannelHandlerContext ctx, MessageEvent e) Invoked when a message object (e.g: ChannelBuffer) was received from a remote peer.
void	releaseExternalResources() Stops the Timer which was specified in the constructor of this handler.
void	writeComplete(ChannelHandlerContext ctx, WriteCompletionEvent e) Invoked when something was written into a Channel.

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

channelBound, channelConnected, channelDisconnected, channelInterestChanged, channelUnbound, childChannelClosed, childChannelOpen, exceptionCaught, handleUpstream

Methods inherited from class java.lang.Object

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

Constructor Detail

IdleStateHandler

public IdleStateHandler(Timer timer,
                        int readerIdleTimeSeconds,
                        int writerIdleTimeSeconds,
                        int allIdleTimeSeconds)

Creates a new instance.

Parameters:

timer - the Timer that is used to trigger the scheduled event. The recommended Timer implementation is HashedWheelTimer.

readerIdleTimeSeconds - an IdleStateEvent whose state is IdleState.READER_IDLE will be triggered when no read was performed for the specified period of time. Specify 0 to disable.

writerIdleTimeSeconds - an IdleStateEvent whose state is IdleState.WRITER_IDLE will be triggered when no write was performed for the specified period of time. Specify 0 to disable.

allIdleTimeSeconds - an IdleStateEvent whose state is IdleState.ALL_IDLE will be triggered when neither read nor write was performed for the specified period of time. Specify 0 to disable.

IdleStateHandler

public IdleStateHandler(Timer timer,
                        long readerIdleTime,
                        long writerIdleTime,
                        long allIdleTime,
                        TimeUnit unit)

Creates a new instance.

Parameters:

timer - the Timer that is used to trigger the scheduled event. The recommended Timer implementation is HashedWheelTimer.

readerIdleTime - an IdleStateEvent whose state is IdleState.READER_IDLE will be triggered when no read was performed for the specified period of time. Specify 0 to disable.

writerIdleTime - an IdleStateEvent whose state is IdleState.WRITER_IDLE will be triggered when no write was performed for the specified period of time. Specify 0 to disable.

allIdleTime - an IdleStateEvent whose state is IdleState.ALL_IDLE will be triggered when neither read nor write was performed for the specified period of time. Specify 0 to disable.

unit - the TimeUnit of readerIdleTime, writeIdleTime, and allIdleTime

Method Detail

releaseExternalResources

public void releaseExternalResources()

Stops the Timer which was specified in the constructor of this handler. You should not call this method if the Timer is in use by other objects.

Specified by:

releaseExternalResources in interface ExternalResourceReleasable

beforeAdd

public void beforeAdd(ChannelHandlerContext ctx)
               throws Exception

Specified by:

beforeAdd in interface LifeCycleAwareChannelHandler

Throws:

Exception

afterAdd

public void afterAdd(ChannelHandlerContext ctx)
              throws Exception

Specified by:

afterAdd in interface LifeCycleAwareChannelHandler

Throws:

Exception

beforeRemove

public void beforeRemove(ChannelHandlerContext ctx)
                  throws Exception

Specified by:

beforeRemove in interface LifeCycleAwareChannelHandler

Throws:

Exception

afterRemove

public void afterRemove(ChannelHandlerContext ctx)
                 throws Exception

Specified by:

afterRemove in interface LifeCycleAwareChannelHandler

Throws:

Exception

channelOpen

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

Description copied from class: SimpleChannelUpstreamHandler

Invoked when a Channel is open, but not bound nor connected.
Be aware that this event is fired from within the Boss-Thread so you should not execute any heavy operation in there as it will block the dispatching to other workers!

Overrides:

channelOpen 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

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

writeComplete

public void writeComplete(ChannelHandlerContext ctx,
                          WriteCompletionEvent e)
                   throws Exception

Description copied from class: SimpleChannelUpstreamHandler

Invoked when something was written into a Channel.

Overrides:

writeComplete in class SimpleChannelUpstreamHandler

Throws:

Exception

channelIdle

protected void channelIdle(ChannelHandlerContext ctx,
                           IdleState state,
                           long lastActivityTimeMillis)
                    throws Exception

Throws:

Exception