ExecutorFilter (Apache MINA 2.0.0-RC1 API Documentation)

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.apache.mina.filter.executor
Class ExecutorFilter

java.lang.Object
  org.apache.mina.core.filterchain.IoFilterAdapter
      org.apache.mina.filter.executor.ExecutorFilter

All Implemented Interfaces:: IoFilter

public class ExecutorFilter
extends IoFilterAdapter
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:

All event handler methods are called exclusively. (e.g. messageReceived and messageSent can't be invoked at the same time.)
The event order is never mixed up. (e.g. messageReceived is always invoked before sessionClosed or messageSent.)

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.

All event handler methods can be called simultaneously. (e.g. messageReceived and messageSent can be invoked at the same time.)
The event order can be mixed up. (e.g. sessionClosed or messageSent can be invoked before messageReceived is invoked.)

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.

Author:: Apache MINA Project
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)` Invoked before this filter is added to the specified `parent`.
`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 pool size

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 initial pool size; maximumPoolSize - The maximum pool size