Package 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 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:

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	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

Modifier and Type	Method	Description
IdleStatus	getInterestedIdleStatus()
KeepAliveMessageFactory	getMessageFactory()
int	getRequestInterval()
int	getRequestTimeout()
KeepAliveRequestTimeoutHandler	getRequestTimeoutHandler()
boolean	isForwardEvent()
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)	Sets the interval for keepAlive messages
void	setRequestTimeout(int keepAliveRequestTimeout)	Sets the timeout
void	setRequestTimeoutHandler(KeepAliveRequestTimeoutHandler timeoutHandler)	Set the timeout handler

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

destroy, event, exceptionCaught, filterClose, filterWrite, init, inputClosed, 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)

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:

• policy = KeepAliveRequestTimeoutHandler.CLOSE
• keepAliveRequestInterval - 60 (seconds)
• keepAliveRequestTimeout - 30 (seconds)

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 Detail

getInterestedIdleStatus

public IdleStatus getInterestedIdleStatus()

Returns:

The IdleStatus

getRequestTimeoutHandler

public KeepAliveRequestTimeoutHandler getRequestTimeoutHandler()

Returns:

The timeout request handler

setRequestTimeoutHandler

public void setRequestTimeoutHandler(KeepAliveRequestTimeoutHandler timeoutHandler)

Set the timeout handler

Parameters:

timeoutHandler - The instance of KeepAliveRequestTimeoutHandler to use

getRequestInterval

public int getRequestInterval()

Returns:

the interval for keep alive messages

setRequestInterval

public void setRequestInterval(int keepAliveRequestInterval)

Sets the interval for keepAlive messages

Parameters:

keepAliveRequestInterval - the interval to set

getRequestTimeout

public int getRequestTimeout()

Returns:

The timeout

setRequestTimeout

public void setRequestTimeout(int keepAliveRequestTimeout)

Sets the timeout

Parameters:

keepAliveRequestTimeout - The timeout to set

getMessageFactory

public KeepAliveMessageFactory getMessageFactory()

Returns:

The message factory

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.

Parameters:

forwardEvent - a flag set to tell if the filter has to forward a IoEventType.SESSION_IDLE event

onPreAdd

public 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 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 - If an error occurred while processing the event

onPostAdd

public 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 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 - If an error occurred while processing the event

onPostRemove

public 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 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 - If an error occurred while processing the event

messageReceived

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

Filters IoHandler.messageReceived(IoSession,Object) event.

Specified by:

messageReceived in interface IoFilter

Overrides:

messageReceived in class IoFilterAdapter

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has received this event

message - The received message

Throws:

Exception - If an error occurred while processing the event

messageSent

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

Filters IoHandler.messageSent(IoSession,Object) event.

Specified by:

messageSent in interface IoFilter

Overrides:

messageSent in class IoFilterAdapter

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has received this event

writeRequest - The WriteRequest that contains the sent message

Throws:

Exception - If an error occurred while processing the event

sessionIdle

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

Filters IoHandler.sessionIdle(IoSession,IdleStatus) event.

Specified by:

sessionIdle in interface IoFilter

Overrides:

sessionIdle in class IoFilterAdapter

Parameters:

nextFilter - the IoFilter.NextFilter for this filter. You can reuse this object until this filter is removed from the chain.

session - The IoSession which has received this event

status - The IdleStatus type

Throws:

Exception - If an error occurred while processing the event