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.

See Also:
  `ReadTimeoutHandler`, `WriteTimeoutHandler`

### Nested Class Summary

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

`ChannelHandler.Sharable`

### Constructor Summary

Constructors
Constructor and Description
`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

Methods
`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.
`long` `getAllIdleTimeInMillis()` Return the allIdleTime that was given when instance this class in milliseconds.
`long` `getReaderIdleTimeInMillis()` Return the readerIdleTime that was given when instance this class in milliseconds.
`long` `getWriterIdleTimeInMillis()` Return the writerIdleTime that was given when instance this class in milliseconds.
`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

#### getReaderIdleTimeInMillis

    public long getReaderIdleTimeInMillis()

Return the readerIdleTime that was given when instance this class in milliseconds.

#### getWriterIdleTimeInMillis

    public long getWriterIdleTimeInMillis()

Return the writerIdleTime that was given when instance this class in milliseconds.

#### getAllIdleTimeInMillis

    public long getAllIdleTimeInMillis()

Return the allIdleTime that was given when instance this class in milliseconds.

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