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 IdleStatuss that this filter is interested in automatically (e.g. IdleStatus.READER_IDLE and IdleStatus.WRITER_IDLE.) Changing the idleTime of the IdleStatuss 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:
Message
NameDescriptionImplementation
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.

  • Field Details

    • WAITING_FOR_RESPONSE

      private final AttributeKey WAITING_FOR_RESPONSE

    • IGNORE_READER_IDLE_ONCE

      private final AttributeKey IGNORE_READER_IDLE_ONCE

    • messageFactory

      private final KeepAliveMessageFactory messageFactory

    • interestedIdleStatus

      private final IdleStatus interestedIdleStatus

    • requestTimeoutHandler

      private volatile KeepAliveRequestTimeoutHandler requestTimeoutHandler

    • requestInterval

      private volatile int requestInterval

    • requestTimeout

      private volatile int requestTimeout

    • forwardEvent

      private volatile boolean forwardEvent

  • Constructor Details

    • KeepAliveFilter

      public KeepAliveFilter(KeepAliveMessageFactory messageFactory)
      Creates a new instance with the default properties. The default property values are:
      Parameters:
      messageFactory - The message factory to use

    • KeepAliveFilter

      public KeepAliveFilter(KeepAliveMessageFactory messageFactory, IdleStatus interestedIdleStatus)
      Creates a new instance with the default properties. The default property values are:
      Parameters:
      messageFactory - The message factory to use
      interestedIdleStatus - The IdleStatus the filter is interested in

    • 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)
      Parameters:
      messageFactory - The message factory to use
      policy - The TimeOut handler policy

    • 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)
      Parameters:
      messageFactory - The message factory to use
      interestedIdleStatus - The IdleStatus the filter is interested in
      policy - The TimeOut handler policy

    • KeepAliveFilter

      public KeepAliveFilter(KeepAliveMessageFactory messageFactory, IdleStatus interestedIdleStatus, KeepAliveRequestTimeoutHandler policy, int keepAliveRequestInterval, int keepAliveRequestTimeout)
      Creates a new instance.
      Parameters:
      messageFactory - The message factory to use
      interestedIdleStatus - The IdleStatus the filter is interested in
      policy - The TimeOut handler policy
      keepAliveRequestInterval - the interval to use
      keepAliveRequestTimeout - The timeout to use

  • Method Details