Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

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

Version:
  $Rev: 2295 $, $Date: 2010-06-03 18:01:46 +0900 (Thu, 03 Jun 2010) $
Author:
  The Netty Project, Trustin Lee

Nested Class Summary

Nested classes/interfaces inherited from interface org.jboss.netty.channel.ChannelHandler
`ChannelHandler.Sharable`

Constructor Summary
`ExecutionHandler(Executor executor)` Creates a new instance with the specified `Executor`.

Method Summary
`Executor` | `getExecutor()` Returns the `Executor` which was specified with the constructor.
`void` | `handleDownstream(ChannelHandlerContext ctx, ChannelEvent e)` Handles the specified downstream event.
`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.

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`

Overview | Package | Class | Use | Tree | Deprecated | Index | Help
PREV CLASS NEXT CLASS | FRAMES NO FRAMES
SUMMARY: NESTED | FIELD | CONSTR | METHOD | DETAIL: FIELD | CONSTR | METHOD

Copyright © 2008-2010 JBoss, a division of Red Hat, Inc.. All Rights Reserved.