org.jboss.netty.handler.execution

## Class ExecutionHandler

- java.lang.Object
- - org.jboss.netty.handler.execution.ExecutionHandler

- All Implemented Interfaces:
    ChannelDownstreamHandler, ChannelHandler, ChannelUpstreamHandler, ExternalResourceReleasable

      @ChannelHandler.Sharable
      public class ExecutionHandler
      extends Object
      implements ChannelUpstreamHandler, ChannelDownstreamHandler, ExternalResourceReleasable

  Forwards an upstream `ChannelEvent` to an `Executor`.

  `ExecutionHandler` is often used when your `ChannelHandler` performs a blocking operation that takes long time or accesses a resource which is not CPU-bound business logic such as DB access. Running such operations in a pipeline without an `ExecutionHandler` will result in unwanted hiccup during I/O because an I/O thread cannot perform I/O until your handler returns the control to the I/O thread.

  In most cases, an `ExecutionHandler` is coupled with an `OrderedMemoryAwareThreadPoolExecutor` because it guarantees the correct event execution order and prevents an `OutOfMemoryError` under load:

       public class DatabaseGatewayPipelineFactory implements ChannelPipelineFactory {

           private final ExecutionHandler executionHandler;

           public DatabaseGatewayPipelineFactory(ExecutionHandler executionHandler) {
               this.executionHandler = executionHandler;
           }

           public ChannelPipeline getPipeline() {
               return Channels.pipeline(
                       new DatabaseGatewayProtocolEncoder(),
                       new DatabaseGatewayProtocolDecoder(),
                       executionHandler, // Must be shared
                       new DatabaseQueryingHandler());
           }
       }
       ...

       public static void main(String[] args) {
           ServerBootstrap bootstrap = ...;
           ...
           ExecutionHandler executionHandler = new ExecutionHandler(
                   new OrderedMemoryAwareThreadPoolExecutor(16, 1048576, 1048576))
           bootstrap.setPipelineFactory(
                   new DatabaseGatewayPipelineFactory(executionHandler));
           ...
           bootstrap.bind(...);
           ...

           while (!isServerReadyToShutDown()) {
               // ... wait ...
           }

           bootstrap.releaseExternalResources();
           executionHandler.releaseExternalResources();
       }

  Please refer to `OrderedMemoryAwareThreadPoolExecutor` for the detailed information about how the event order is guaranteed.

  ### SEDA (Staged Event-Driven Architecture)

  You can implement an alternative thread model such as SEDA by adding more than one `ExecutionHandler` to the pipeline.

  ### Using other `Executor` implementation

  Although it's recommended to use `OrderedMemoryAwareThreadPoolExecutor`, you can use other `Executor` implementations. However, you must note that other `Executor` implementation might break your application because they often do not maintain event execution order nor interact with I/O threads to control the incoming traffic and avoid `OutOfMemoryError`.

- - ### Nested Class Summary

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

      `ChannelHandler.Sharable`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `ExecutionHandler(Executor executor)` Creates a new instance with the specified `Executor`.
    `ExecutionHandler(Executor executor, boolean handleDownstream)` Deprecated.
    `ExecutionHandler(Executor executor, boolean handleDownstream, boolean handleUpstream)` Creates a new instance with the specified `Executor`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `Executor` | `getExecutor()` Returns the `Executor` which was specified with the constructor.
    `void` | `handleDownstream(ChannelHandlerContext ctx, ChannelEvent e)` Handles the specified downstream event.
    `protected boolean` | `handleReadSuspend(ChannelHandlerContext ctx, ChannelEvent e)` Handle suspended reads
    `void` | `handleUpstream(ChannelHandlerContext context, ChannelEvent e)` Handles the specified upstream event.
    `void` | `releaseExternalResources()` Shuts down the `Executor` which was specified with the constructor and wait for its termination.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ExecutionHandler

          public ExecutionHandler(Executor executor)

      Creates a new instance with the specified `Executor`. Specify an `OrderedMemoryAwareThreadPoolExecutor` if unsure.

    - #### ExecutionHandler

          @Deprecated
          public ExecutionHandler(Executor executor,
                                     boolean handleDownstream)

      Deprecated.
      Use `ExecutionHandler(Executor, boolean, boolean)` `Deprecated`

    - #### ExecutionHandler

          public ExecutionHandler(Executor executor,
                          boolean handleDownstream,
                          boolean handleUpstream)

      Creates a new instance with the specified `Executor`. Specify an `OrderedMemoryAwareThreadPoolExecutor` if unsure.

  - ### Method Detail

    - #### getExecutor

          public Executor getExecutor()

      Returns the `Executor` which was specified with the constructor.

    - #### releaseExternalResources

          public void releaseExternalResources()

      Shuts down the `Executor` which was specified with the constructor and wait for its termination.
      Specified by:
        `releaseExternalResources` in interface `ExternalResourceReleasable`

    - #### handleUpstream

          public void handleUpstream(ChannelHandlerContext context,
                            ChannelEvent e)
                              throws Exception

      Description copied from interface: `ChannelUpstreamHandler`
      Handles the specified upstream event.
      Specified by:
        `handleUpstream` in interface `ChannelUpstreamHandler`
      Parameters:
        `context` - the context object for this handler
        `e` - the upstream event to process or intercept
      Throws:
        `Exception`

    - #### handleDownstream

          public void handleDownstream(ChannelHandlerContext ctx,
                              ChannelEvent e)
                                throws Exception

      Description copied from interface: `ChannelDownstreamHandler`
      Handles the specified downstream event.
      Specified by:
        `handleDownstream` in interface `ChannelDownstreamHandler`
      Parameters:
        `ctx` - the context object for this handler
        `e` - the downstream event to process or intercept
      Throws:
        `Exception`

    - #### handleReadSuspend

          protected boolean handleReadSuspend(ChannelHandlerContext ctx,
                                  ChannelEvent e)

      Handle suspended reads

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