org.apache.catalina.cluster.session
Class JvmRouteBinderValve

java.lang.Object
  extended byorg.apache.catalina.valves.ValveBase
      extended byorg.apache.catalina.cluster.session.JvmRouteBinderValve
All Implemented Interfaces:
ClusterValve, Contained, Lifecycle, javax.management.MBeanRegistration, Valve

public class JvmRouteBinderValve
extends ValveBase
implements ClusterValve, Lifecycle

Valve to handle Tomcat jvmRoute takeover using mod_jk module after node failure. After a node crashes, subsequent requests go to other cluster nodes. That incurs a drop in performance. When this Valve is enabled on a backup node and sees a request, which was intended for another (thus failed) node, it will rewrite the cookie jsessionid information to use the route to this backup cluster node, that answered the request. After the response is delivered to the client, all subsequent client requests will go directly to the backup node. The change of sessionid is also sent to all other cluster nodes. After all that, the session stickyness will work directly to the backup node and the traffic will not go back to the failed node after it is restarted!

For this valve to function correctly, so that all nodes of the cluster receive the sessionid change notifications that it generates, the following ClusterListener MUST be configured at all nodes of the cluster: JvmRouteSessionIDBinderListener since Tomcat 5.5.10, and both JvmRouteSessionIDBinderListener and JvmRouteSessionIDBinderLifecycleListener for earlier versions of Tomcat.

Add this Valve to your host definition at conf/server.xml . Since 5.5.10 as direct cluster valve:

  <Cluster>
  <Valve className="org.apache.catalina.cluster.session.JvmRouteBinderValve" />  
  </Cluster>
 

Before 5.5.10 as Host element:
  <Host>
  <Valve className="org.apache.catalina.cluster.session.JvmRouteBinderValve" />  
  </Host>
 
A Trick:
You can enable this mod_jk turnover mode via JMX before you drop a node to all backup nodes! Set enable true on all JvmRouteBinderValve backups, disable worker at mod_jk and then drop node and restart it! Then enable mod_jk worker and disable JvmRouteBinderValves again. This use case means that only requested sessions are migrated.

Version:
$Id: JvmRouteBinderValve.java 1160227 2011-08-22 12:06:00Z kkolinko $
Author:
Peter Rossbach

Field Summary
protected  CatalinaCluster cluster
          the cluster
protected  boolean enabled
          enabled this component
protected static java.lang.String info
          The descriptive information about this implementation.
protected  LifecycleSupport lifecycle
          The lifecycle event support for this component.
static org.apache.commons.logging.Log log
           
protected  long numberOfSessions
          number of session that no at this tomcat instanz hosted
protected  java.lang.String sessionIdAttribute
           
protected  StringManager sm
          The string manager for this package.
protected  boolean started
          Has this component been started yet?
 
Fields inherited from class org.apache.catalina.valves.ValveBase
container, containerLog, controller, domain, mserver, next, oname
 
Fields inherited from interface org.apache.catalina.Lifecycle
AFTER_START_EVENT, AFTER_STOP_EVENT, BEFORE_START_EVENT, BEFORE_STOP_EVENT, DESTROY_EVENT, INIT_EVENT, PERIODIC_EVENT, START_EVENT, STOP_EVENT
 
Constructor Summary
JvmRouteBinderValve()
           
 
Method Summary
 void addLifecycleListener(LifecycleListener listener)
          Add a lifecycle event listener to this component.
protected  void changeRequestSessionID(Request request, Response response, java.lang.String sessionId, java.lang.String newSessionID)
          Change Request Session id
protected  void changeSessionID(Request request, Response response, java.lang.String sessionId, java.lang.String newSessionID, Session catalinaSession)
          change session id and send to all cluster nodes
 LifecycleListener[] findLifecycleListeners()
          Get the lifecycle listeners associated with this lifecycle.
 CatalinaCluster getCluster()
          Returns the cluster the cluster deployer is associated with
 boolean getEnabled()
           
 java.lang.String getInfo()
          Return descriptive information about this implementation.
protected  java.lang.String getLocalJvmRoute(Request request)
          get jvmroute from engine
protected  Manager getManager(Request request)
          get Cluster DeltaManager
 long getNumberOfSessions()
           
 java.lang.String getSessionIdAttribute()
          set session id attribute to failed node for request.
protected  void handleJvmRoute(Request request, Response response, java.lang.String sessionId, java.lang.String localJvmRoute)
          Handle jvmRoute stickyness after tomcat instance failed.
protected  void handlePossibleTurnover(Request request, Response response)
          handle possible session turn over.
 void invoke(Request request, Response response)
          Detect possible the JVMRoute change at cluster backup node..
 void removeLifecycleListener(LifecycleListener listener)
          Remove a lifecycle event listener from this component.
protected  void sendSessionIDClusterBackup(ClusterManager manager, Request request, java.lang.String sessionId, java.lang.String newSessionID)
          Send the changed Sessionid to all clusternodes.
 void setCluster(CatalinaCluster cluster)
          Associates the cluster deployer with a cluster
 void setEnabled(boolean enabled)
           
protected  void setNewSessionCookie(Request request, Response response, java.lang.String sessionId)
          Deprecated. Use Request.changeSessionId(String)
 void setSessionIdAttribute(java.lang.String sessionIdAttribute)
          get name of failed reqeust session attribute
 void start()
          Prepare for the beginning of active use of the public methods of this component.
 void stop()
          Gracefully terminate the active use of the public methods of this component.
 
Methods inherited from class org.apache.catalina.valves.ValveBase
backgroundProcess, createObjectName, getContainer, getContainerName, getController, getDomain, getNext, getObjectName, getParentName, postDeregister, postRegister, preDeregister, preRegister, setContainer, setController, setNext, setObjectName, toString
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

log

public static org.apache.commons.logging.Log log

info

protected static final java.lang.String info
The descriptive information about this implementation.

See Also:
Constant Field Values

cluster

protected CatalinaCluster cluster
the cluster


sm

protected StringManager sm
The string manager for this package.


started

protected boolean started
Has this component been started yet?


enabled

protected boolean enabled
enabled this component


numberOfSessions

protected long numberOfSessions
number of session that no at this tomcat instanz hosted


sessionIdAttribute

protected java.lang.String sessionIdAttribute

lifecycle

protected LifecycleSupport lifecycle
The lifecycle event support for this component.

Constructor Detail

JvmRouteBinderValve

public JvmRouteBinderValve()
Method Detail

getInfo

public java.lang.String getInfo()
Return descriptive information about this implementation.

Specified by:
getInfo in interface Valve
Overrides:
getInfo in class ValveBase

getSessionIdAttribute

public java.lang.String getSessionIdAttribute()
set session id attribute to failed node for request.

Returns:
Returns the sessionIdAttribute.

setSessionIdAttribute

public void setSessionIdAttribute(java.lang.String sessionIdAttribute)
get name of failed reqeust session attribute

Parameters:
sessionIdAttribute - The sessionIdAttribute to set.

getNumberOfSessions

public long getNumberOfSessions()
Returns:
Returns the number of migrated sessions.

getEnabled

public boolean getEnabled()
Returns:
Returns the enabled.

setEnabled

public void setEnabled(boolean enabled)
Parameters:
enabled - The enabled to set.

invoke

public void invoke(Request request,
                   Response response)
            throws java.io.IOException,
                   javax.servlet.ServletException
Detect possible the JVMRoute change at cluster backup node..

Specified by:
invoke in interface Valve
Specified by:
invoke in class ValveBase
Parameters:
request - tomcat request being processed
response - tomcat response being processed
Throws:
java.io.IOException - if an input/output error has occurred
javax.servlet.ServletException - if a servlet error has occurred

handlePossibleTurnover

protected void handlePossibleTurnover(Request request,
                                      Response response)
handle possible session turn over.

Parameters:
request - current request
response - current response
See Also:
handleJvmRoute(Request, Response, String, String)

getLocalJvmRoute

protected java.lang.String getLocalJvmRoute(Request request)
get jvmroute from engine

Parameters:
request - current request
Returns:
return jvmRoute from ManagerBase or null

getManager

protected Manager getManager(Request request)
get Cluster DeltaManager

Parameters:
request - current request
Returns:
manager or null

getCluster

public CatalinaCluster getCluster()
Description copied from interface: ClusterValve
Returns the cluster the cluster deployer is associated with

Specified by:
getCluster in interface ClusterValve
Returns:
Returns the cluster.

setCluster

public void setCluster(CatalinaCluster cluster)
Description copied from interface: ClusterValve
Associates the cluster deployer with a cluster

Specified by:
setCluster in interface ClusterValve
Parameters:
cluster - The cluster to set.

handleJvmRoute

protected void handleJvmRoute(Request request,
                              Response response,
                              java.lang.String sessionId,
                              java.lang.String localJvmRoute)
Handle jvmRoute stickyness after tomcat instance failed. After this correction a new Cookie send to client with new jvmRoute and the SessionID change propage to the other cluster nodes.

Parameters:
request - current request
response - Tomcat Response
sessionId - request SessionID from Cookie
localJvmRoute - local jvmRoute

changeSessionID

protected void changeSessionID(Request request,
                               Response response,
                               java.lang.String sessionId,
                               java.lang.String newSessionID,
                               Session catalinaSession)
change session id and send to all cluster nodes

Parameters:
request - current request
response - current response
sessionId - original session id
newSessionID - new session id for node migration
catalinaSession - current session with original session id

changeRequestSessionID

protected void changeRequestSessionID(Request request,
                                      Response response,
                                      java.lang.String sessionId,
                                      java.lang.String newSessionID)
Change Request Session id

Parameters:
request - current request
response - current response
sessionId - original session id
newSessionID - new session id for node migration

sendSessionIDClusterBackup

protected void sendSessionIDClusterBackup(ClusterManager manager,
                                          Request request,
                                          java.lang.String sessionId,
                                          java.lang.String newSessionID)
Send the changed Sessionid to all clusternodes.

Parameters:
manager - ClusterManager
sessionId - current failed sessionid
newSessionID - new session id, bind to the new cluster node
See Also:
JvmRouteSessionIDBinderListener.messageReceived(ClusterMessage)

setNewSessionCookie

protected void setNewSessionCookie(Request request,
                                   Response response,
                                   java.lang.String sessionId)
Deprecated. Use Request.changeSessionId(String)

Sets a new cookie for the given session id and response and see Request.configureSessionCookie(javax.servlet.http.Cookie)

Parameters:
request - current request
response - Tomcat Response
sessionId - The session id

addLifecycleListener

public void addLifecycleListener(LifecycleListener listener)
Add a lifecycle event listener to this component.

Specified by:
addLifecycleListener in interface Lifecycle
Parameters:
listener - The listener to add

findLifecycleListeners

public LifecycleListener[] findLifecycleListeners()
Get the lifecycle listeners associated with this lifecycle. If this Lifecycle has no listeners registered, a zero-length array is returned.

Specified by:
findLifecycleListeners in interface Lifecycle

removeLifecycleListener

public void removeLifecycleListener(LifecycleListener listener)
Remove a lifecycle event listener from this component.

Specified by:
removeLifecycleListener in interface Lifecycle
Parameters:
listener - The listener to add

start

public void start()
           throws LifecycleException
Prepare for the beginning of active use of the public methods of this component. This method should be called after configure(), and before any of the public methods of the component are utilized.

Specified by:
start in interface Lifecycle
Throws:
LifecycleException - if this component detects a fatal error that prevents this component from being used

stop

public void stop()
          throws LifecycleException
Gracefully terminate the active use of the public methods of this component. This method should be the last one called on a given instance of this component.

Specified by:
stop in interface Lifecycle
Throws:
LifecycleException - if this component detects a fatal error that needs to be reported


Copyright © 2000-2012 Apache Software Foundation. All Rights Reserved.