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.common
Interface IoFilter

All Known Implementing Classes:
  BlacklistFilter, CompressionFilter, ExecutorFilter, IoFilterAdapter, LoggingFilter, ProtocolCodecFilter, ReferenceCountingIoFilter, SSLFilter, StreamWriteFilter

    public interface IoFilter

A filter which intercepts `IoHandler` events like Servlet filters. Filters can be used for these purposes:

- Event logging,
- Performance measurement,
- Authorization,
- Overload control,
- Message transformation (e.g. encryption and decryption, ...),
- and many more.

Please NEVER implement your filters to wrap `IoSession`s. Users can cache the reference to the session, which might malfunction if any filters are added or removed later.

### The Life Cycle

`IoFilter`s are activated only when they are inside `IoFilterChain`.

When you add an `IoFilter` to an `IoFilterChain`:

1. `init()` is invoked by `ReferenceCountingIoFilter` if the filter is added at the first time.
2. `onPreAdd(IoFilterChain, String, NextFilter)` is invoked to notify that the filter will be added to the chain.
3. The filter is added to the chain, and all events and I/O requests pass through the filter from now.
4. `onPostAdd(IoFilterChain, String, NextFilter)` is invoked to notify that the filter is added to the chain.
5. The filter is removed from the chain if `onPostAdd(IoFilterChain, String, org.apache.mina.common.IoFilter.NextFilter)` threw an exception. `destroy()` is also invoked by `ReferenceCountingIoFilter` if the filter is the last filter which was added to `IoFilterChain`s.

When you remove an `IoFilter` from an `IoFilterChain`:

1. `onPreRemove(IoFilterChain, String, NextFilter)` is invoked to notify that the filter will be removed from the chain.
2. The filter is removed from the chain, and any events and I/O requests don't pass through the filter from now.
3. `onPostRemove(IoFilterChain, String, NextFilter)` is invoked to notify that the filter is removed from the chain.
4. `destroy()` is invoked by `ReferenceCountingIoFilter` if the removed filter was the last one.

Version:
  $Rev: 599822 $, $Date: 2007-11-30 14:54:07 +0100 (Fri, 30 Nov 2007) $
Author:
  The Apache Directory Project (mina-dev@directory.apache.org)
See Also:
  `IoFilterAdapter`

Nested Class Summary
`static interface` | `IoFilter.NextFilter` Represents the next `IoFilter` in `IoFilterChain`.
`static class` | `IoFilter.WriteRequest` Represents write request fired by `IoSession.write(Object)`.

Method Summary
`void` | `destroy()` Invoked by `ReferenceCountingIoFilter` when this filter is not used by any `IoFilterChain` anymore, so you can destroy shared resources.
`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, IoFilter.WriteRequest writeRequest)` Filters `IoSession.write(Object)` method invocation.
`void` | `init()` Invoked by `ReferenceCountingIoFilter` when this filter is added to a `IoFilterChain` at the first time, so you can initialize shared resources.
`void` | `messageReceived(IoFilter.NextFilter nextFilter, IoSession session, Object message)` Filters `IoHandler.messageReceived(IoSession,Object)` event.
`void` | `messageSent(IoFilter.NextFilter nextFilter, IoSession session, Object message)` Filters `IoHandler.messageSent(IoSession,Object)` event.
`void` | `onPostAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)` Invoked after this filter is added to the specified `parent`.
`void` | `onPostRemove(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)` Invoked after this filter is removed from the specified `parent`.
`void` | `onPreAdd(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)` Invoked before this filter is added to the specified `parent`.
`void` | `onPreRemove(IoFilterChain parent, String name, IoFilter.NextFilter nextFilter)` Invoked before this filter is removed from 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.

Method Detail

### init

    void init()
              throws Exception

  Invoked by `ReferenceCountingIoFilter` when this filter is added to a `IoFilterChain` at the first time, so you can initialize shared resources. Please note that this method is never called if you don't wrap a filter with `ReferenceCountingIoFilter`.

  Throws:
    `Exception`

### destroy

    void destroy()
                 throws Exception

  Invoked by `ReferenceCountingIoFilter` when this filter is not used by any `IoFilterChain` anymore, so you can destroy shared resources. Please note that this method is never called if you don't wrap a filter with `ReferenceCountingIoFilter`.

  Throws:
    `Exception`

### onPreAdd

    void onPreAdd(IoFilterChain parent,
                  String name,
                  IoFilter.NextFilter nextFilter)
                  throws Exception

  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 `init()` is invoked.

  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`

### onPostAdd

    void onPostAdd(IoFilterChain parent,
                   String name,
                   IoFilter.NextFilter nextFilter)
                   throws Exception

  Invoked after 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 `init()` is invoked.

  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`

### onPreRemove

    void onPreRemove(IoFilterChain parent,
                     String name,
                     IoFilter.NextFilter nextFilter)
                     throws Exception

  Invoked before this filter is removed from the specified `parent`. Please note that this method can be invoked more than once if this filter is removed from more than one parents. This method is always invoked before `destroy()` is invoked.

  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`

### onPostRemove

    void onPostRemove(IoFilterChain parent,
                      String name,
                      IoFilter.NextFilter nextFilter)
                      throws Exception

  Invoked after this filter is removed from the specified `parent`. Please note that this method can be invoked more than once if this filter is removed from more than one parents. This method is always invoked before `destroy()` is invoked.

  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

    void sessionCreated(IoFilter.NextFilter nextFilter,
                        IoSession session)
                        throws Exception

  Filters `IoHandler.sessionCreated(IoSession)` event.

  Throws:
    `Exception`

### sessionOpened

    void sessionOpened(IoFilter.NextFilter nextFilter,
                       IoSession session)
                       throws Exception

  Filters `IoHandler.sessionOpened(IoSession)` event.

  Throws:
    `Exception`

### sessionClosed

    void sessionClosed(IoFilter.NextFilter nextFilter,
                       IoSession session)
                       throws Exception

  Filters `IoHandler.sessionClosed(IoSession)` event.

  Throws:
    `Exception`

### sessionIdle

    void sessionIdle(IoFilter.NextFilter nextFilter,
                     IoSession session,
                     IdleStatus status)
                     throws Exception

  Filters `IoHandler.sessionIdle(IoSession,IdleStatus)` event.

  Throws:
    `Exception`

### exceptionCaught

    void exceptionCaught(IoFilter.NextFilter nextFilter,
                         IoSession session,
                         Throwable cause)
                         throws Exception

  Filters `IoHandler.exceptionCaught(IoSession,Throwable)` event.

  Throws:
    `Exception`

### messageReceived

    void messageReceived(IoFilter.NextFilter nextFilter,
                         IoSession session,
                         Object message)
                         throws Exception

  Filters `IoHandler.messageReceived(IoSession,Object)` event.

  Throws:
    `Exception`

### messageSent

    void messageSent(IoFilter.NextFilter nextFilter,
                     IoSession session,
                     Object message)
                     throws Exception

  Filters `IoHandler.messageSent(IoSession,Object)` event.

  Throws:
    `Exception`

### filterClose

    void filterClose(IoFilter.NextFilter nextFilter,
                     IoSession session)
                     throws Exception

  Filters `IoSession.close()` method invocation.

  Throws:
    `Exception`

### filterWrite

    void filterWrite(IoFilter.NextFilter nextFilter,
                     IoSession session,
                     IoFilter.WriteRequest writeRequest)
                     throws Exception

  Filters `IoSession.write(Object)` method invocation.

  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 © 2004-2008 Apache MINA Project. All Rights Reserved.