org.apache.mina.core.filterchain

## Interface IoFilter

- All Known Implementing Classes:
    AbstractStreamWriteFilter, BlacklistFilter, BufferedWriteFilter, CommonEventFilter, CompressionFilter, ConnectionThrottleFilter, ErrorGeneratingFilter, ExecutorFilter, FileRegionWriteFilter, HttpClientCodec, HttpServerCodec, IoFilterAdapter, KeepAliveFilter, LoggingFilter, MdcInjectionFilter, NoopFilter, ProfilerTimerFilter, ProtocolCodecFilter, ProxyFilter, ReferenceCountingFilter, RequestResponseFilter, SessionAttributeInitializingFilter, SslFilter, StreamWriteFilter, ToHaikuIoFilter, WriteRequestFilter, WriteRequestFilter

      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 `ReferenceCountingFilter` 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.core.filterchain.IoFilter.NextFilter)` threw an exception. `destroy()` is also invoked by `ReferenceCountingFilter` 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 `ReferenceCountingFilter` if the removed filter was the last one.
  Author:
    Apache MINA Project
  See Also:
    `IoFilterAdapter`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static interface` | `IoFilter.NextFilter` Represents the next `IoFilter` in `IoFilterChain`.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `destroy()` Invoked by `ReferenceCountingFilter` 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, WriteRequest writeRequest)` Filters `IoSession.write(Object)` method invocation.
    `void` | `init()` Invoked by `ReferenceCountingFilter` 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, WriteRequest writeRequest)` 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 `ReferenceCountingFilter` 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 `ReferenceCountingFilter`.
      Throws:
        `Exception`

    - #### destroy

          void destroy()
                       throws Exception

      Invoked by `ReferenceCountingFilter` 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 `ReferenceCountingFilter`.
      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,
                         WriteRequest writeRequest)
                           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,
                         WriteRequest writeRequest)
                           throws Exception

      Filters `IoSession.write(Object)` method invocation.
      Throws:
        `Exception`

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