org.apache.mina.filter.keepalive

## Class KeepAliveFilter

- java.lang.Object
- - org.apache.mina.core.filterchain.IoFilterAdapter
  - - org.apache.mina.filter.keepalive.KeepAliveFilter

- All Implemented Interfaces:
    IoFilter

      public class KeepAliveFilter
      extends IoFilterAdapter

  An `IoFilter` that sends a keep-alive request on `IoEventType.SESSION_IDLE` and sends back the response for the sent keep-alive request.

  ## Interference with `IoSessionConfig.setIdleTime(IdleStatus, int)`

  This filter adjusts `idleTime` of the `IdleStatus`s that this filter is interested in automatically (e.g. `IdleStatus.READER_IDLE` and `IdleStatus.WRITER_IDLE`.) Changing the `idleTime` of the `IdleStatus`s can lead this filter to a unexpected behavior. Please also note that any `IoFilter` and `IoHandler` behind `KeepAliveFilter` will not get any `IoEventType.SESSION_IDLE` event. To receive the internal `IoEventType.SESSION_IDLE` event, you can call `setForwardEvent(boolean)` with `true`.

  ## Implementing `KeepAliveMessageFactory`

  To use this filter, you have to provide an implementation of `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 `KeepAliveRequestTimeoutHandler` will be invoked. If a keep-alive request is received, its response also should be sent back. | Both `KeepAliveMessageFactory.getRequest(IoSession)` and `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 `KeepAliveMessageFactory.getRequest(IoSession)` and `KeepAliveMessageFactory.getResponse(IoSession, Object)` must return a non-`null`, and the `timeoutHandler` property should be set to `KeepAliveRequestTimeoutHandler.NOOP`, `KeepAliveRequestTimeoutHandler.LOG` or the custom `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. | `KeepAliveMessageFactory.getRequest(IoSession)` must return `null` and `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. | `KeepAliveMessageFactory.getRequest(IoSession)` must return a non-`null`, `KeepAliveMessageFactory.getResponse(IoSession, Object)` must return `null` and the `timeoutHandler` must be set to `KeepAliveRequestTimeoutHandler.DEAF_SPEAKER`.
  Silent Listener | You don't want to send a keep-alive request by yourself nor send any response back. | Both `KeepAliveMessageFactory.getRequest(IoSession)` and `KeepAliveMessageFactory.getResponse(IoSession, Object)` must return `null`.

  Please note that you must implement `KeepAliveMessageFactory.isRequest(IoSession, Object)` and `KeepAliveMessageFactory.isResponse(IoSession, Object)` properly whatever case you chose.

  ## Handling timeout

  `KeepAliveFilter` will notify its `KeepAliveRequestTimeoutHandler` when `KeepAliveFilter` didn't receive the response message for a sent keep-alive message. The default handler is `KeepAliveRequestTimeoutHandler.CLOSE`, but you can use other presets such as `KeepAliveRequestTimeoutHandler.NOOP`, `KeepAliveRequestTimeoutHandler.LOG` or `KeepAliveRequestTimeoutHandler.EXCEPTION`. You can even implement your own handler.

  ### Special handler: `KeepAliveRequestTimeoutHandler.DEAF_SPEAKER`

  `KeepAliveRequestTimeoutHandler.DEAF_SPEAKER` is a special handler which is dedicated for the 'deaf speaker' mode mentioned above. Setting the `timeoutHandler` property to `KeepAliveRequestTimeoutHandler.DEAF_SPEAKER` stops this filter from waiting for response messages and therefore disables response timeout detection.
  Author:
    Apache MINA Project

- - ### Nested Class Summary

    - ### Nested classes/interfaces inherited from interface org.apache.mina.core.filterchain.IoFilter

      `IoFilter.NextFilter`

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `KeepAliveFilter(KeepAliveMessageFactory messageFactory)` Creates a new instance with the default properties.
    `KeepAliveFilter(KeepAliveMessageFactory messageFactory, IdleStatus interestedIdleStatus)` Creates a new instance with the default properties.
    `KeepAliveFilter(KeepAliveMessageFactory messageFactory, IdleStatus interestedIdleStatus, KeepAliveRequestTimeoutHandler policy)` Creates a new instance with the default properties.
    `KeepAliveFilter(KeepAliveMessageFactory messageFactory, IdleStatus interestedIdleStatus, KeepAliveRequestTimeoutHandler policy, int keepAliveRequestInterval, int keepAliveRequestTimeout)` Creates a new instance.
    `KeepAliveFilter(KeepAliveMessageFactory messageFactory, KeepAliveRequestTimeoutHandler policy)` Creates a new instance with the default properties.

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `IdleStatus` | `getInterestedIdleStatus()`
    `KeepAliveMessageFactory` | `getMessageFactory()`
    `int` | `getRequestInterval()`
    `int` | `getRequestTimeout()`
    `KeepAliveRequestTimeoutHandler` | `getRequestTimeoutHandler()`
    `boolean` | `isForwardEvent()` Returns `true` if and only if this filter forwards a `IoEventType.SESSION_IDLE` event to the next filter.
    `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` | `sessionIdle(IoFilter.NextFilter nextFilter, IoSession session, IdleStatus status)` Filters `IoHandler.sessionIdle(IoSession,IdleStatus)` event.
    `void` | `setForwardEvent(boolean forwardEvent)` Sets if this filter needs to forward a `IoEventType.SESSION_IDLE` event to the next filter.
    `void` | `setRequestInterval(int keepAliveRequestInterval)`
    `void` | `setRequestTimeout(int keepAliveRequestTimeout)`
    `void` | `setRequestTimeoutHandler(KeepAliveRequestTimeoutHandler timeoutHandler)`

    - ### Methods inherited from class org.apache.mina.core.filterchain.IoFilterAdapter

      `destroy, exceptionCaught, filterClose, filterWrite, init, onPreRemove, sessionClosed, sessionCreated, sessionOpened, toString`

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait`

- - ### Constructor Detail

    - #### KeepAliveFilter

          public KeepAliveFilter(KeepAliveMessageFactory messageFactory)

      Creates a new instance with the default properties. The default property values are:
      - `interestedIdleStatus` - `IdleStatus.READER_IDLE`
      - `policy` = `KeepAliveRequestTimeoutHandler.CLOSE`
      - `keepAliveRequestInterval` - 60 (seconds)
      - `keepAliveRequestTimeout` - 30 (seconds)

    - #### KeepAliveFilter

          public KeepAliveFilter(KeepAliveMessageFactory messageFactory,
                         IdleStatus interestedIdleStatus)

      Creates a new instance with the default properties. The default property values are:
      - `policy` = `KeepAliveRequestTimeoutHandler.CLOSE`
      - `keepAliveRequestInterval` - 60 (seconds)
      - `keepAliveRequestTimeout` - 30 (seconds)

    - #### KeepAliveFilter

          public KeepAliveFilter(KeepAliveMessageFactory messageFactory,
                         KeepAliveRequestTimeoutHandler policy)

      Creates a new instance with the default properties. The default property values are:
      - `interestedIdleStatus` - `IdleStatus.READER_IDLE`
      - `keepAliveRequestInterval` - 60 (seconds)
      - `keepAliveRequestTimeout` - 30 (seconds)

    - #### KeepAliveFilter

          public KeepAliveFilter(KeepAliveMessageFactory messageFactory,
                         IdleStatus interestedIdleStatus,
                         KeepAliveRequestTimeoutHandler policy)

      Creates a new instance with the default properties. The default property values are:
      - `keepAliveRequestInterval` - 60 (seconds)
      - `keepAliveRequestTimeout` - 30 (seconds)

    - #### KeepAliveFilter

          public KeepAliveFilter(KeepAliveMessageFactory messageFactory,
                         IdleStatus interestedIdleStatus,
                         KeepAliveRequestTimeoutHandler policy,
                         int keepAliveRequestInterval,
                         int keepAliveRequestTimeout)

      Creates a new instance.

  - ### Method Detail

    - #### getInterestedIdleStatus

          public IdleStatus getInterestedIdleStatus()

    - #### getRequestTimeoutHandler

          public KeepAliveRequestTimeoutHandler getRequestTimeoutHandler()

    - #### setRequestTimeoutHandler

          public void setRequestTimeoutHandler(KeepAliveRequestTimeoutHandler timeoutHandler)

    - #### getRequestInterval

          public int getRequestInterval()

    - #### setRequestInterval

          public void setRequestInterval(int keepAliveRequestInterval)

    - #### getRequestTimeout

          public int getRequestTimeout()

    - #### setRequestTimeout

          public void setRequestTimeout(int keepAliveRequestTimeout)

    - #### getMessageFactory

          public KeepAliveMessageFactory getMessageFactory()

    - #### isForwardEvent

          public boolean isForwardEvent()

      Returns `true` if and only if this filter forwards a `IoEventType.SESSION_IDLE` event to the next filter. By default, the value of this property is `false`.

    - #### setForwardEvent

          public void setForwardEvent(boolean forwardEvent)

      Sets if this filter needs to forward a `IoEventType.SESSION_IDLE` event to the next filter. By default, the value of this property is `false`.

    - #### onPreAdd

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

      Description copied from class: `IoFilterAdapter`
      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 `IoFilter.init()` is invoked.
      Specified by:
        `onPreAdd` in interface `IoFilter`
      Overrides:
        `onPreAdd` in class `IoFilterAdapter`
      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

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

      Description copied from class: `IoFilterAdapter`
      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 `IoFilter.init()` is invoked.
      Specified by:
        `onPostAdd` in interface `IoFilter`
      Overrides:
        `onPostAdd` in class `IoFilterAdapter`
      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

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

      Description copied from class: `IoFilterAdapter`
      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 `IoFilter.destroy()` is invoked.
      Specified by:
        `onPostRemove` in interface `IoFilter`
      Overrides:
        `onPostRemove` in class `IoFilterAdapter`
      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`

    - #### messageReceived

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

      Description copied from class: `IoFilterAdapter`
      Filters `IoHandler.messageReceived(IoSession,Object)` event.
      Specified by:
        `messageReceived` in interface `IoFilter`
      Overrides:
        `messageReceived` in class `IoFilterAdapter`
      Throws:
        `Exception`

    - #### messageSent

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

      Description copied from class: `IoFilterAdapter`
      Filters `IoHandler.messageSent(IoSession,Object)` event.
      Specified by:
        `messageSent` in interface `IoFilter`
      Overrides:
        `messageSent` in class `IoFilterAdapter`
      Throws:
        `Exception`

    - #### sessionIdle

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

      Description copied from class: `IoFilterAdapter`
      Filters `IoHandler.sessionIdle(IoSession,IdleStatus)` event.
      Specified by:
        `sessionIdle` in interface `IoFilter`
      Overrides:
        `sessionIdle` in class `IoFilterAdapter`
      Throws:
        `Exception`

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