Apache Tomcat 6.0.53

## org.apache.catalina.ha.session
Class JvmRouteBinderValve

    java.lang.Object
      org.apache.catalina.valves.ValveBase
          org.apache.catalina.ha.session.JvmRouteBinderValve

All Implemented Interfaces:
  javax.management.MBeanRegistration, Contained, ClusterValve, Lifecycle, 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.ha.session.JvmRouteBinderValve" />
      </Cluster>

Before 5.5.10 as Host element:

      <Host>
      <Valve className="org.apache.catalina.ha.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.

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 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, event, 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`

Methods inherited from interface org.apache.catalina.Valve
`backgroundProcess, event, getNext, setNext`

Field Detail

### log

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

Apache Tomcat 6.0.53

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