org.apache.mina.filter.executor
Class ExecutorFilter

java.lang.Object
  extended by org.apache.mina.core.filterchain.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: 706043 $, $Date: 2008-10-19 18:14:11 +0200 (So, 19 Okt 2008) $
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.core.filterchain.IoFilter
IoFilter.NextFilter
 
Constructor Summary
ExecutorFilter()
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor, no thread in the pool, and a maximum of 16 threads in the pool.
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, no thread in the pool, but a maximum of threads in the pool is given.
ExecutorFilter(int corePoolSize, int maximumPoolSize)
          (Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor, a number of thread to start with, a maximum of threads the pool can contain.
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 hase been created 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)
          A trigger fired when adding this filter in a chain.
 void sessionClosed(IoFilter.NextFilter nextFilter, IoSession session)
          Filters IoHandler.sessionClosed(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.core.filterchain.IoFilterAdapter
init, onPostAdd, onPostRemove, onPreRemove, sessionCreated, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

ExecutorFilter

public ExecutorFilter()
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor, no thread in the pool, and a maximum of 16 threads in the pool. All the event will be handled by this default executor.


ExecutorFilter

public ExecutorFilter(int maximumPoolSize)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor, no thread in the pool, but a maximum of threads in the pool is given. All the event will be handled by this default executor.

Parameters:
maximumPoolSize - The maximum number of thread the default executor can use

ExecutorFilter

public ExecutorFilter(int corePoolSize,
                      int maximumPoolSize)
(Convenience constructor) Creates a new instance with a new OrderedThreadPoolExecutor, a number of thread to start with, a maximum of threads the pool can contain. All the event will be handled by this default executor.

Parameters:
corePoolSize - the base number of threads the pool will contain at startup
maximumPoolSize - The maximum number of thread the default executor can use

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.

Parameters:
corePoolSize - The base number of thread in the pool
maximumPoolSize - The macimum thread contained in the executor
keepAliveTime - The KeepAlive timeout, expressed using the time unit
unit - The time unit
threadFactory -
queueHandler -
eventTypes - The list of events handled by the created executor

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 hase been created 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.

Returns:
The underlying Executor

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
A trigger fired when adding this filter in a chain. As this filter can be added only once in a chain, if the chain already contains the same filter, and exception will be thrown.

Specified by:
onPreAdd in interface IoFilter
Overrides:
onPreAdd in class IoFilterAdapter
Parameters:
parent - The chain in which we want to inject this filter
name - The Fitler's name
nextFilter - The next filter in the chain
Throws:
IllegalArgumentException - If the filter is already present in the chain
Exception

sessionOpened

public final void sessionOpened(IoFilter.NextFilter nextFilter,
                                IoSession session)
Description copied from class: IoFilterAdapter
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 class: IoFilterAdapter
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 class: IoFilterAdapter
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 class: IoFilterAdapter
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 class: IoFilterAdapter
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 class: IoFilterAdapter
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 class: IoFilterAdapter
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 class: IoFilterAdapter
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.