| Element | Description | Class |
|---|
| blacklistFilter | A {@link IoFilter} which blocks connections from blacklisted remote
address. | org.apache.mina.filter.firewall.BlacklistFilter |
| bufferedWriteFilter | An {@link IoFilter} implementation used to buffer outgoing {@link WriteRequest} almost
like what {@link BufferedOutputStream} does. Using this filter allows to be less dependent
from network latency. It is also useful when a session is generating very small messages
too frequently and consequently generating unnecessary traffic overhead.
Please note that it should always be placed before the {@link ProtocolCodecFilter}
as it only handles {@link WriteRequest}'s carrying {@link IoBuffer} objects. | org.apache.mina.filter.buffer.BufferedWriteFilter |
| defaultIoFilterChainBuilder | The default implementation of {@link IoFilterChainBuilder} which is useful
in most cases. {@link DefaultIoFilterChainBuilder} has an identical interface
with {@link IoFilter}; it contains a list of {@link IoFilter}s that you can
modify. The {@link IoFilter}s which are added to this builder will be appended
to the {@link IoFilterChain} when {@link #buildFilterChain(IoFilterChain)} is
invoked.
However, the identical interface doesn't mean that it behaves in an exactly
same way with {@link IoFilterChain}. {@link DefaultIoFilterChainBuilder}
doesn't manage the life cycle of the {@link IoFilter}s at all, and the
existing {@link IoSession}s won't get affected by the changes in this builder.
{@link IoFilterChainBuilder}s affect only newly created {@link IoSession}s.
IoAcceptor acceptor = ...;
DefaultIoFilterChainBuilder builder = acceptor.getFilterChain();
builder.addLast( "myFilter", new MyFilter() );
...
| org.apache.mina.core.filterchain.DefaultIoFilterChainBuilder |
| errorGeneratingFilter | An {@link IoFilter} implementation generating random bytes and PDU modification in
your communication streams.
It's quite simple to use :
ErrorGeneratingFilter egf = new ErrorGeneratingFilter();
For activate the change of some bytes in your {@link IoBuffer}, for a probability of 200 out
of 1000 {@link IoBuffer} processed :
egf.setChangeByteProbability(200);
For activate the insertion of some bytes in your {@link IoBuffer}, for a
probability of 200 out of 1000 :
egf.setInsertByteProbability(200);
And for the removing of some bytes :
egf.setRemoveByteProbability(200);
You can activate the error generation for write or read with the
following methods :
egf.setManipulateReads(true);
egf.setManipulateWrites(true); | org.apache.mina.filter.errorgenerating.ErrorGeneratingFilter |
| executorFilter | A filter that forwards I/O events to {@link 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 {@link IoFilterChain}.
Life Cycle Management
Please note that this filter doesn't manage the life cycle of the {@link Executor}.
If you created this filter using {@link #ExecutorFilter(Executor)} or similar
constructor that accepts an {@link Executor} that you've instantiated, you have
full control and responsibility of managing its life cycle (e.g. calling
{@link ExecutorService#shutdown()}.
If you created this filter using convenience constructors like
{@link #ExecutorFilter(int)}, then you can shut down the executor by calling
{@link #destroy()} explicitly.
Event Ordering
All convenience constructors of this filter creates a new
{@link 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 {@link 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
{@link 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 {@link OutOfMemoryError}
Please refer to {@link IoEventQueueThrottle}, which is specified as
a parameter of the convenience constructors. | org.apache.mina.filter.executor.ExecutorFilter |
| expiringSessionRecycler | An {@link IoSessionRecycler} with sessions that time out on inactivity.
TODO Document me. | org.apache.mina.core.session.ExpiringSessionRecycler |
| fileRegionWriteFilter | Filter implementation that converts a {@link FileRegion} to {@link IoBuffer}
objects and writes those buffers to the next filter. When end of the
{@code FileRegion} has been reached this filter will call
{@link IoFilter.NextFilter#messageSent(IoSession,WriteRequest)} using the
original {@link FileRegion} written to the session and notifies
{@link org.apache.mina.core.future.WriteFuture} on the original
{@link org.apache.mina.core.write.WriteRequest}.
Normall {@code FileRegion} objects should be handled by the
{@link org.apache.mina.core.service.IoProcessor} but this is not always possible
if a filter is being used that needs to modify the contents of the file
before sending over the network (i.e. the
{@link org.apache.mina.filter.ssl.SslFilter} or a data compression filter.)
This filter will ignore written messages which aren't {@link FileRegion}
instances. Such messages will be passed to the next filter directly.
NOTE: this filter does not close the file channel in
{@link FileRegion#getFileChannel()} after the data from the file has been
written. The {@code FileChannel} should be closed in either
{@link org.apache.mina.core.service.IoHandler#messageSent(IoSession,Object)}
or in an {@link org.apache.mina.core.future.IoFutureListener} associated with the
{@code WriteFuture}.
| org.apache.mina.filter.stream.FileRegionWriteFilter |
| keepAliveFilter | An {@link IoFilter} that sends a keep-alive request on
{@link IoEventType#SESSION_IDLE} and sends back the response for the
sent keep-alive request.
Interference with {@link IoSessionConfig#setIdleTime(IdleStatus, int)}
This filter adjusts idleTime of the {@link IdleStatus}s that
this filter is interested in automatically (e.g. {@link IdleStatus#READER_IDLE}
and {@link IdleStatus#WRITER_IDLE}.) Changing the idleTime
of the {@link IdleStatus}s can lead this filter to a unexpected behavior.
Please also note that any {@link IoFilter} and {@link IoHandler} behind
{@link KeepAliveFilter} will not get any {@link IoEventType#SESSION_IDLE}
event. To receive the internal {@link IoEventType#SESSION_IDLE} event,
you can call {@link #setForwardEvent(boolean)} with true.
Implementing {@link KeepAliveMessageFactory}
To use this filter, you have to provide an implementation of
{@link KeepAliveMessageFactory}, which determines a received or sent
message is a keep-alive message or not and creates a new keep-alive
message:
| Name | Description | Implementation |
| Active |
You want a keep-alive request is sent when the reader is idle.
Once the request is sent, the response for the request should be
received within keepAliveRequestTimeout seconds. Otherwise,
the specified {@link KeepAliveRequestTimeoutHandler} will be invoked.
If a keep-alive request is received, its response also should be sent back.
|
Both {@link KeepAliveMessageFactory#getRequest(IoSession)} and
{@link KeepAliveMessageFactory#getResponse(IoSession, Object)} must
return a non-null. |
| Semi-active |
You want a keep-alive request to be sent when the reader is idle.
However, you don't really care if the response is received or not.
If a keep-alive request is received, its response should
also be sent back.
|
Both {@link KeepAliveMessageFactory#getRequest(IoSession)} and
{@link KeepAliveMessageFactory#getResponse(IoSession, Object)} must
return a non-null, and the timeoutHandler property
should be set to {@link KeepAliveRequestTimeoutHandler#NOOP},
{@link KeepAliveRequestTimeoutHandler#LOG} or the custom {@link KeepAliveRequestTimeoutHandler}
implementation that doesn't affect the session state nor throw an exception.
|
| Passive |
You don't want to send a keep-alive request by yourself, but the
response should be sent back if a keep-alive request is received. |
{@link KeepAliveMessageFactory#getRequest(IoSession)} must return
null and {@link KeepAliveMessageFactory#getResponse(IoSession, Object)}
must return a non-null. |
| Deaf Speaker |
You want a keep-alive request to be sent when the reader is idle, but
you don't want to send any response back. |
{@link KeepAliveMessageFactory#getRequest(IoSession)} must return
a non-null,
{@link KeepAliveMessageFactory#getResponse(IoSession, Object)} must
return null and the timeoutHandler must be set to
{@link KeepAliveRequestTimeoutHandler#DEAF_SPEAKER}. |
| Silent Listener |
You don't want to send a keep-alive request by yourself nor send any
response back. |
Both {@link KeepAliveMessageFactory#getRequest(IoSession)} and
{@link KeepAliveMessageFactory#getResponse(IoSession, Object)} must
return null. |
Please note that you must implement
{@link KeepAliveMessageFactory#isRequest(IoSession, Object)} and
{@link KeepAliveMessageFactory#isResponse(IoSession, Object)} properly
whatever case you chose.
Handling timeout
{@link KeepAliveFilter} will notify its {@link KeepAliveRequestTimeoutHandler}
when {@link KeepAliveFilter} didn't receive the response message for a sent
keep-alive message. The default handler is {@link KeepAliveRequestTimeoutHandler#CLOSE},
but you can use other presets such as {@link KeepAliveRequestTimeoutHandler#NOOP},
{@link KeepAliveRequestTimeoutHandler#LOG} or {@link KeepAliveRequestTimeoutHandler#EXCEPTION}.
You can even implement your own handler.
Special handler: {@link KeepAliveRequestTimeoutHandler#DEAF_SPEAKER}
{@link KeepAliveRequestTimeoutHandler#DEAF_SPEAKER} is a special handler which is
dedicated for the 'deaf speaker' mode mentioned above. Setting the
timeoutHandler property to {@link KeepAliveRequestTimeoutHandler#DEAF_SPEAKER}
stops this filter from waiting for response messages and therefore disables
response timeout detection. | org.apache.mina.filter.keepalive.KeepAliveFilter |
| loggingFilter | Logs all MINA protocol events. Each event can be
tuned to use a different level based on the user's specific requirements. Methods
are in place that allow the user to use either the get or set method for each event
and pass in the {@link IoEventType} and the {@link LogLevel}.
By default, all events are logged to the {@link LogLevel#INFO} level except
{@link IoFilterAdapter#exceptionCaught(IoFilter.NextFilter, IoSession, Throwable)},
which is logged to {@link LogLevel#WARN}. | org.apache.mina.filter.logging.LoggingFilter |
| nioDatagramAcceptor | {@link IoAcceptor} for datagram transport (UDP/IP). | org.apache.mina.transport.socket.nio.NioDatagramAcceptor |
| orderedThreadPoolExecutor | A {@link ThreadPoolExecutor} that maintains the order of {@link IoEvent}s.
If you don't need to maintain the order of events per session, please use
{@link UnorderedThreadPoolExecutor}. | org.apache.mina.filter.executor.OrderedThreadPoolExecutor |
| profilerTimerFilter | This class will measure the time it takes for a
method in the {@link IoFilterAdapter} class to execute. The basic
premise of the logic in this class is to get the current time
at the beginning of the method, call method on nextFilter, and
then get the current time again. An example of how to use
the filter is:
ProfilerTimerFilter profiler = new ProfilerTimerFilter(
TimeUnit.MILLISECOND, IoEventType.MESSAGE_RECEIVED);
chain.addFirst("Profiler", profiler);
The profiled {@link IoEventType} are :
- IoEventType.MESSAGE_RECEIVED
- IoEventType.MESSAGE_SENT
- IoEventType.SESSION_CREATED
- IoEventType.SESSION_OPENED
- IoEventType.SESSION_IDLE
- IoEventType.SESSION_CLOSED
| org.apache.mina.filter.statistic.ProfilerTimerFilter |
| protocolCodecFilter | An {@link IoFilter} which translates binary or protocol specific data into
message objects and vice versa using {@link ProtocolCodecFactory},
{@link ProtocolEncoder}, or {@link ProtocolDecoder}. | org.apache.mina.filter.codec.ProtocolCodecFilter |
| referenceCountingFilter | An {@link IoFilter}s wrapper that keeps track of the number of usages of this filter and will call init/destroy
when the filter is not in use. | org.apache.mina.filter.util.ReferenceCountingFilter |
| requestResponseFilter | TODO Add documentation | org.apache.mina.filter.reqres.RequestResponseFilter |
| sessionAttributeInitializingFilter | An {@link IoFilter} that sets initial attributes when a new
{@link IoSession} is created. By default, the attribute map is empty when
an {@link IoSession} is newly created. Inserting this filter will make
the pre-configured attributes available after this filter executes the
sessionCreated event. | org.apache.mina.filter.util.SessionAttributeInitializingFilter |
| socketAddress | Workaround for dealing with inability to annotate java docs of JDK
socket address classes. | org.apache.mina.integration.xbean.SocketAddressFactory |
| sslFilter | An SSL filter that encrypts and decrypts the data exchanged in the session.
Adding this filter triggers SSL handshake procedure immediately by sending
a SSL 'hello' message, so you don't need to call
{@link #startSsl(IoSession)} manually unless you are implementing StartTLS
(see below). If you don't want the handshake procedure to start
immediately, please specify {@code false} as {@code autoStart} parameter in
the constructor.
This filter uses an {@link SSLEngine} which was introduced in Java 5, so
Java version 5 or above is mandatory to use this filter. And please note that
this filter only works for TCP/IP connections.
Implementing StartTLS
You can use {@link #DISABLE_ENCRYPTION_ONCE} attribute to implement StartTLS:
public void messageReceived(IoSession session, Object message) {
if (message instanceof MyStartTLSRequest) {
// Insert SSLFilter to get ready for handshaking
session.getFilterChain().addFirst(sslFilter);
// Disable encryption temporarilly.
// This attribute will be removed by SSLFilter
// inside the Session.write() call below.
session.setAttribute(SSLFilter.DISABLE_ENCRYPTION_ONCE, Boolean.TRUE);
// Write StartTLSResponse which won't be encrypted.
session.write(new MyStartTLSResponse(OK));
// Now DISABLE_ENCRYPTION_ONCE attribute is cleared.
assert session.getAttribute(SSLFilter.DISABLE_ENCRYPTION_ONCE) == null;
}
}
| org.apache.mina.filter.ssl.SslFilter |
| standardThreadPool | | org.apache.mina.integration.xbean.StandardThreadPool |
| streamWriteFilter | Filter implementation which makes it possible to write {@link InputStream}
objects directly using {@link IoSession#write(Object)}. When an
{@link InputStream} is written to a session this filter will read the bytes
from the stream into {@link IoBuffer} objects and write those buffers
to the next filter. When end of stream has been reached this filter will
call {@link IoFilter.NextFilter#messageSent(IoSession,WriteRequest)} using the original
{@link InputStream} written to the session and notifies
{@link org.apache.mina.core.future.WriteFuture} on the
original {@link org.apache.mina.core.write.WriteRequest}.
This filter will ignore written messages which aren't {@link InputStream}
instances. Such messages will be passed to the next filter directly.
NOTE: this filter does not close the stream after all data from stream
has been written. The {@link org.apache.mina.core.service.IoHandler} should take
care of that in its
{@link org.apache.mina.core.service.IoHandler#messageSent(IoSession,Object)}
callback.
| org.apache.mina.filter.stream.StreamWriteFilter |
| unorderedThreadPoolExecutor | A {@link ThreadPoolExecutor} that does not maintain the order of {@link IoEvent}s.
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 use
{@link OrderedThreadPoolExecutor}. | org.apache.mina.filter.executor.UnorderedThreadPoolExecutor |