Package org.jboss.netty.handler.execution

Class ExecutionHandler

java.lang.Object
org.jboss.netty.handler.execution.ExecutionHandler
All Implemented Interfaces:
ChannelDownstreamHandler, ChannelHandler, ChannelUpstreamHandler, ExternalResourceReleasable
@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.