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
    Modifier and Type | Method and Description
    --- | ---
    `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`

Copyright © 2008-2012 The Netty Project. All Rights Reserved.