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