org.apache.mina.filter.executor
Class ExecutorFilter

java.lang.Object
  extended by org.apache.mina.common.IoFilterAdapter
      extended by org.apache.mina.filter.executor.ExecutorFilter
All Implemented Interfaces:
IoFilter

public class ExecutorFilter
extends IoFilterAdapter

A filter that forwards I/O events to Executor to enforce a certain thread model while allowing the events per session to be processed simultaneously. You can apply various thread model by inserting this filter to a IoFilterChain.

Life Cycle Management

Please note that this filter doesn't manage the life cycle of the Executor. If you created this filter using ExecutorFilter(Executor) or similar constructor that accepts an Executor that you've instantiated, you have full control and responsibility of managing its life cycle (e.g. calling ExecutorService.shutdown().

If you created this filter using convenience constructors like ExecutorFilter(int), then you can shut down the executor by calling destroy() explicitly.

Event Ordering

All convenience constructors of this filter creates a new OrderedThreadPoolExecutor instance. Therefore, the order of event is maintained like the following: However, if you specified other Executor instance in the constructor, the order of events are not maintained at all. This means more than one event handler methods can be invoked at the same time with mixed order. For example, let's assume that messageReceived, messageSent, and sessionClosed events are fired. If you need to maintain the order of events per session, please specify an OrderedThreadPoolExecutor instance or use the convenience constructors.

Selective Filtering

By default, all event types but sessionCreated, filterWrite, filterClose and filterSetTrafficMask are submitted to the underlying executor, which is most common setting.

If you want to submit only a certain set of event types, you can specify them in the constructor. For example, you could configure a thread pool for write operation for the maximum performance:


 IoService service = ...;
 DefaultIoFilterChainBuilder chain = service.getFilterChain();
 
 chain.addLast("codec", new ProtocolCodecFilter(...));
 // Use one thread pool for most events.
 chain.addLast("executor1", new ExecutorFilter());
 // and another dedicated thread pool for 'filterWrite' events.
 chain.addLast("executor2", new ExecutorFilter(IoEventType.WRITE));
 

Preventing OutOfMemoryError

Please refer to IoEventQueueThrottle, which is specified as a parameter of the convenience constructors.

Version:
$Rev: 593428 $, $Date: 2007-11-09 07:35:16 +0100 (Fri, 09 Nov 2007) $
Author:
The Apache MINA Project (dev@mina.apache.org)
See Also:
OrderedThreadPoolExecutor, UnorderedThreadPoolExecutor

Nested Class Summary
 
Nested classes/interfaces inherited from interface org.apache.mina.common.IoFilter
IoFilter.NextFilter
 
Constructor Summary
ExecutorFilter()
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(Executor executor)
          Creates a new instance with the specified Executor.
ExecutorFilter(Executor executor, IoEventType... eventTypes)
          Creates a new instance with the specified Executor.
ExecutorFilter(int maximumPoolSize)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(int corePoolSize, int maximumPoolSize)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(int corePoolSize, int maximumPoolSize, IoEventType... eventTypes)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, IoEventQueueHandler queueHandler)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, IoEventQueueHandler queueHandler, IoEventType... eventTypes)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, IoEventType... eventTypes)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, ThreadFactory threadFactory)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, ThreadFactory threadFactory, IoEventQueueHandler queueHandler)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, ThreadFactory threadFactory, IoEventQueueHandler queueHandler, IoEventType... eventTypes)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(int corePoolSize, int maximumPoolSize, long keepAliveTime, TimeUnit unit, ThreadFactory threadFactory, IoEventType... eventTypes)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(int maximumPoolSize, IoEventType... eventTypes)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
ExecutorFilter(IoEventType... eventTypes)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.
 
Method Summary
 void destroy()
          Shuts down the underlying executor if this filter is creates via a convenience constructor.
 void exceptionCaught(IoFilter.NextFilter nextFilter, IoSession session, Throwable cause)
          Filters IoHandler.exceptionCaught(IoSession,Throwable) event.
 void filterClose(IoFilter.NextFilter nextFilter, IoSession session)
          Filters IoSession.close() method invocation.
 void filterWrite(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)
          Filters IoSession.write(Object) method invocation.
protected  void fireEvent(IoFilterEvent event)
          Fires the specified event through the underlying executor.
 Executor getExecutor()
          Returns the underlying Executor instance this filter uses.
 void messageReceived(IoFilter.NextFilter nextFilter, IoSession session, Object message)
          Filters IoHandler.messageReceived(IoSession,Object) event.
 void messageSent(IoFilter.NextFilter nextFilter, IoSession session, WriteRequest writeRequest)
          Filters IoHandler.messageSent(IoSession,Object) event.
 void onPreAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)
          Invoked before this filter is added to the specified parent.
 void sessionClosed(IoFilter.NextFilter nextFilter, IoSession session)
          Filters IoHandler.sessionClosed(IoSession) event.
 void sessionCreated(IoFilter.NextFilter nextFilter, IoSession session)
          Filters IoHandler.sessionCreated(IoSession) event.
 void sessionIdle(IoFilter.NextFilter nextFilter, IoSession session, IdleStatus status)
          Filters IoHandler.sessionIdle(IoSession,IdleStatus) event.
 void sessionOpened(IoFilter.NextFilter nextFilter, IoSession session)
          Filters IoHandler.sessionOpened(IoSession) event.
 
Methods inherited from class org.apache.mina.common.IoFilterAdapter
filterSetTrafficMask, init, onPostAdd, onPostRemove, onPreRemove
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ExecutorFilter

public ExecutorFilter()
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int maximumPoolSize)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int corePoolSize,
                      int maximumPoolSize)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      IoEventQueueHandler queueHandler)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      ThreadFactory threadFactory)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      ThreadFactory threadFactory,
                      IoEventQueueHandler queueHandler)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(IoEventType... eventTypes)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int maximumPoolSize,
                      IoEventType... eventTypes)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int corePoolSize,
                      int maximumPoolSize,
                      IoEventType... eventTypes)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      IoEventType... eventTypes)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      IoEventQueueHandler queueHandler,
                      IoEventType... eventTypes)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      ThreadFactory threadFactory,
                      IoEventType... eventTypes)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(int corePoolSize,
                      int maximumPoolSize,
                      long keepAliveTime,
                      TimeUnit unit,
                      ThreadFactory threadFactory,
                      IoEventQueueHandler queueHandler,
                      IoEventType... eventTypes)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor.


ExecutorFilter

public ExecutorFilter(Executor executor)
Creates a new instance with the specified Executor.


ExecutorFilter

public ExecutorFilter(Executor executor,
                      IoEventType... eventTypes)
Creates a new instance with the specified Executor.

Method Detail

destroy

public void destroy()
Shuts down the underlying executor if this filter is creates via a convenience constructor.

Specified by:
destroy in interface IoFilter
Overrides:
destroy in class IoFilterAdapter

getExecutor

public final Executor getExecutor()
Returns the underlying Executor instance this filter uses.


fireEvent

protected void fireEvent(IoFilterEvent event)
Fires the specified event through the underlying executor.


onPreAdd

public void onPreAdd(IoFilterChain parent,
                     String name,
                     IoFilter.NextFilter nextFilter)
              throws Exception
Description copied from interface: IoFilter
Invoked before this filter is added to the specified parent. Please note that this method can be invoked more than once if this filter is added to more than one parents. This method is not invoked before IoFilter.init() is invoked.

Specified by:
onPreAdd in interface IoFilter
Overrides:
onPreAdd in class IoFilterAdapter
Parameters:
parent - the parent who called this method
name - the name assigned to this filter
nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.
Throws:
Exception

sessionCreated

public final void sessionCreated(IoFilter.NextFilter nextFilter,
                                 IoSession session)
Description copied from interface: IoFilter
Filters IoHandler.sessionCreated(IoSession) event.

Specified by:
sessionCreated in interface IoFilter
Overrides:
sessionCreated in class IoFilterAdapter

sessionOpened

public final void sessionOpened(IoFilter.NextFilter nextFilter,
                                IoSession session)
Description copied from interface: IoFilter
Filters IoHandler.sessionOpened(IoSession) event.

Specified by:
sessionOpened in interface IoFilter
Overrides:
sessionOpened in class IoFilterAdapter

sessionClosed

public final void sessionClosed(IoFilter.NextFilter nextFilter,
                                IoSession session)
Description copied from interface: IoFilter
Filters IoHandler.sessionClosed(IoSession) event.

Specified by:
sessionClosed in interface IoFilter
Overrides:
sessionClosed in class IoFilterAdapter

sessionIdle

public final void sessionIdle(IoFilter.NextFilter nextFilter,
                              IoSession session,
                              IdleStatus status)
Description copied from interface: IoFilter
Filters IoHandler.sessionIdle(IoSession,IdleStatus) event.

Specified by:
sessionIdle in interface IoFilter
Overrides:
sessionIdle in class IoFilterAdapter

exceptionCaught

public final void exceptionCaught(IoFilter.NextFilter nextFilter,
                                  IoSession session,
                                  Throwable cause)
Description copied from interface: IoFilter
Filters IoHandler.exceptionCaught(IoSession,Throwable) event.

Specified by:
exceptionCaught in interface IoFilter
Overrides:
exceptionCaught in class IoFilterAdapter

messageReceived

public final void messageReceived(IoFilter.NextFilter nextFilter,
                                  IoSession session,
                                  Object message)
Description copied from interface: IoFilter
Filters IoHandler.messageReceived(IoSession,Object) event.

Specified by:
messageReceived in interface IoFilter
Overrides:
messageReceived in class IoFilterAdapter

messageSent

public final void messageSent(IoFilter.NextFilter nextFilter,
                              IoSession session,
                              WriteRequest writeRequest)
Description copied from interface: IoFilter
Filters IoHandler.messageSent(IoSession,Object) event.

Specified by:
messageSent in interface IoFilter
Overrides:
messageSent in class IoFilterAdapter

filterWrite

public final void filterWrite(IoFilter.NextFilter nextFilter,
                              IoSession session,
                              WriteRequest writeRequest)
Description copied from interface: IoFilter
Filters IoSession.write(Object) method invocation.

Specified by:
filterWrite in interface IoFilter
Overrides:
filterWrite in class IoFilterAdapter

filterClose

public final void filterClose(IoFilter.NextFilter nextFilter,
                              IoSession session)
                       throws Exception
Description copied from interface: IoFilter
Filters IoSession.close() method invocation.

Specified by:
filterClose in interface IoFilter
Overrides:
filterClose in class IoFilterAdapter
Throws:
Exception


Copyright © 2004-2009 Apache MINA Project. All Rights Reserved.