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