A Coherence*Web Context Parameters

Coherence*Web includes many context parameters that can be configured in the web.xml file or they can also be entered on the command line as system properties.The system properties have the same name as the context parameters, but the dash (-) is replaced with a period (.).

For example, the context parameter coherence-enable-sessioncontext can be declared on the command line by:

-Dcoherence.enable.sessioncontext=true

If both a system property and the equivalent context parameter are configured, the value from the system property is honored.

Table A-1 describes the context parameters for Coherence*Web.

Table A-1 Context Parameters for Coherence*Web

Parameter Name Description

coherence-application-name

Coherence*Web uses the value of this parameter to determine the name of the application that uses the ApplicationScopeController interface to scope attributes. The value for this parameter should be provided in the following format:

application name + ! + Web module name

The application name is the name of the application that uses the ApplicationScopeController interface and Web module name is the name of the Web module in which it appears.

For example, if you have an EAR file named test.ear and a Web-module named app1 defined in the EAR file, then the default value for the coherence-application-name parameter would be test!app1.

If this parameter is not configured, then Coherence*Web uses the name of the class loader instead. Also, if the parameter is not configured and the ApplicationScopeController interface is configured, then a warning is logged saying that the application name was not configured. See Session Attribute Scoping.

coherence-attribute-overflow-threshold

For the Split Model, described in Session Models, this value specifies the minimum length (in bytes) that the serialized form of an attribute value must be for it to be stored in the separate overflow cache that is reserved for large attributes.

If unspecified, this parameter defaults to 1024.

coherence-cache-configuration-path

Specifies the name of the file that Coherence*Web should use to obtain session cache information, instead of using the default default-session-cache-config.xml file. See Customizing the Name of the Session Cache Configuration File.

coherence-cache-delegator-class

Specifies a cache delegator class that is responsible for manipulating (getting, putting, or deleting) data in the distributed cache. Valid value is:

  • com.tangosol.coherence.servlet.LocalSessionCacheDelegator—This class indicates that the local cache should be used for storing and retrieving the session instance before attempting to use the distributed cache. See Getting Concurrent Access to the Same Session Instance.

coherence-cluster-owned

If true, Coherence*Web automatically shuts down the Coherence node when the Web application shuts down. You must use the WAR-scoped cluster node deployment model in this case. See WAR-Scoped Cluster Nodes.

If false, the Web application is responsible for shutting down the Coherence node (see com.tangosol.net.CacheFactory.shutdown() in the Javadoc). You must carefully consider a cluster node-scoping deployment model in this case and the circumstances under which the application shuts down the Coherence node and the side effects of doing so. See Cluster Node Isolation.

Note: When using the WebInstaller, a value of true instructs the WebInstaller to place the Coherence library in the WEB-INF/lib directory of each Web application found in your Java EE application.

If unspecified, this parameter defaults to false.

coherence-configuration-consistency

If true, Coherence*Web runs a configuration check at startup to determine whether all nodes in the Web tier have the same Coherence*Web configuration. If the configuration of a particular node is not consistent, then it will fail to start (which, in turn, prevents the application from starting).

If false, (there is no checking) and the configurations are not consistent, then the cluster members might exhibit inconsistent behavior in managing the session data.

If unspecified, this parameter defaults to false.

coherence-contextless-session-retain-millis

Specifies the number of milliseconds that a server holds a lock on a session while accessing it without the session being implied by the current request context. A session is implied by the current request context if and only if the current thread is processing a servlet request, and the request is associated with that session. All other access to a session object is out of context. For example, if a reference to an arbitrary session is obtained from a SessionContext object (if that option is enabled), or if the application has code that holds on to session object references to manage sessions directly. Because session access requires session ownership, out of context access to the session object automatically obtains ownership on behalf of the caller; that ownership will be retained for the number of milliseconds specified by this option so that repeated calls to the session do not individually obtain and release ownership, which is potentially an expensive operation. The valid range is 10 to 10000 (from 1/100th of a second up to 10 seconds).

If unspecified, this parameter defaults to 200.

coherence-distributioncontroller-class

This value specifies a class name of the com.tangosol.coherence.servlet.HttpSessionCollection$SessionDistributionController interface implementation.

Valid values include:

  • com.tangosol.coherence.servlet.AbstractHttpSessionCollection$DistributedController an implementation of the SessionDistributionController interface that forces all sessions (and thus their attributes) to be managed in a distributed manner. This is the default behavior, but by having an implementation that forces this, the raw overhead of using a HttpSessionController can be measured.

  • com.tangosol.coherence.servlet.AbstractHttpSessionCollection$HybridController an implementation of the SessionDistributionController interface that forces all sessions and serializable attributes to be managed in a distributed manner. All session attributes that do not implement the Serializable interface will be kept local.

  • com.tangosol.coherence.servlet.AbstractHttpSessionCollection$LocalController an implementation of the SessionDistributionController interface that forces all sessions (and thus their attributes) to be managed locally. This might not be useful for production purposes, but it can be useful for testing the difference in scalable performance between local-only and fully-distributed implementations.

coherence-enable-sessioncontext

When set to true, this parameter allows the application to iterate sessions from the session context, thus disobeying the deprecation in the servlet specification.

If unspecified, this parameter defaults to false.

coherence-eventlisteners

This is the comma-delimited list of names of application classes that want to receive events from the Web container. This list comes from the application listeners declared in the listener elements of the web.xml file.

coherence-enable-suspect-attributes

If set to true, Coherence*Web attempts to detect whether the value of any session-related attributes have changed. Attributes that can be changed (determined with a simple check) and that can be accessed by a get method are deemed to be suspect. Changeable objects might have been changed by application code and must be re-serialized back into the cache. See Detecting Changed Attribute Values.

If unspecified, this parameter defaults to true.

coherence-factory-class

This is the fully qualified name of the class that implements the SessionHelper.Factory factory class.

This parameter defaults to com.tangosol.coherence.servlet.apinn.DefaultFactory where nn is 22, 23, 24, or 25 for Servlet 2.2, 2.3, 2.4, or 2.5 containers respectively.

coherence-local-session-cachename

This name overrides the name of the local cache that stores nondistributed sessions when the coherence-distributioncontroller-class parameter is specified.

If unspecified, this parameter defaults to local-session-storage. See Session Cache Configuration File.

coherence-local-attribute-cachename

This name overrides the name of the local cache that stores non-distributed sessions when either the coherence-sessiondistributioncontroller-class parameter is specified or the coherence-preserve-attributes parameter is true.

If unspecified, this parameter defaults to local-attribute-storage. SeeSession Cache Configuration File.

coherence-preserve-attributes

This value, if set to true, specifies that non-serializable attributes should be preserved as local ones. This parameter requires a load balancer to be present to retrieve non-serializable attributes for a session.

These attributes will be lost if the client (application server) fails. The application would need to be able to recover from this.

If unspecified, this parameter defaults to false.

coherence-reaperdaemon-assume-locality

This setting allows the Session Reaper to assume that the sessions that are stored on this node (for example, by a distributed cache service) are the only sessions that this node must check for expiration. This value must be set to false if the session storage cache is being managed by nodes that are not running a reaper, for example if cache servers are being used to manage the session storage cache.

If cache servers are being used, select the Split Model and run the session overflow storage in a separate distributed cache service that is managed entirely by the cache servers. Leave the session storage cache itself in a distributed cache service that is managed entirely by the application server JVMs so they can take advantage of this assume locality feature. See Cleaning Up Expired HTTP Sessions.

If unspecified, this parameter defaults to true.

coherence-reaperdaemon-cluster-coordinated

If true, the Session Reaper coordinates reaping in the cluster such that only one server will perform reaping within a given reaping cycle, and it will be responsible for checking all of the sessions that are being managed in the cluster. See Cleaning Up Expired HTTP Sessions.

This option should not be used if sticky optimization (coherence-sticky-sessions) is also enabled. See Understanding the Session Reaper.

If unspecified, this parameter defaults to false.

coherence-reaperdaemon-cycle-seconds

This is the number of seconds that the daemon rests between reaping. For production clusters with long session timeout intervals, this can safely be set higher. For testing, particularly with short session timeout intervals, it can be set much lower. Setting it too low can cause more network traffic and use more processing cycles, and has benefit only if the application requires the sessions to be invalidated quickly when they have expired. See Cleaning Up Expired HTTP Sessions.

If unspecified, this parameter defaults to 300.

coherence-reaperdaemon-parallel

If set to true, the Session Reaper will invalidate expired sessions in parallel. When set to false, expired sessions will be invalidated serially. See Understanding the Session Reaper.

The default is false.

coherence-reaperdaemon-priority

This is the priority for the Session Reaper daemon. See Cleaning Up Expired HTTP Sessions and the source for the java.lang.Thread class.

If unspecified, this parameter defaults to 5.

coherence-session-reaping-mechanism

This property indicates the mechanism that is used by the session reaper to delete timed-out sessions. Valid values are Default and RemoteDelete. See Cleaning Up Expired HTTP Sessions.

The default is Default

coherence-scopecontroller-class

This value specifies a class name of the optional com.tangosol.coherence.servlet.HttpSessionCollection$AttributeScopeController interface implementation. See Session Attribute Scoping.

Valid values include:

  • com.tangosol.coherence.servlet.AbstractHttpSessionCollection$ApplicationScopeController

  • com.tangosol.coherence.servlet.AbstractHttpSessionCollection$GlobalScopeController

The default value for Coherence*Web is com.tangosol.coherence.servlet.AbstractHttpSessionCollection$ApplicationScopeController

For Coherence*Web WebInstaller, there is no declared default value.

coherence-servletcontext-clustered

This value is either true or false to indicate whether the attributes of the ServletContext will be clustered. If true, then all serializable ServletContext attribute values will be shared among all cluster nodes.

If unspecified, this parameter defaults to false, primarily because the servlet specification indicates that the ServletContext attributes are local to a JVM and should not be clustered.

coherence-servletcontext-cachename

This specifies the name of the Coherence cache to be used to hold the servlet context data if the servlet context is clustered.

If unspecified, this parameter defaults to servletcontext-storage. SeeSession Cache Configuration File.

coherence-session-affinity-token

Configures the session affinity suffix token with a given value. For example, to set the session affinity suffix to abcd, add the following code to the Web application's web.xml file:

<context-param>
  <param-name>coherence-session-affinity-token</param-name>
  <param-value>abcd</param-value>
</context-param>

To strip the session affinity suffix from the token, enter an exclamation point (!) as the parameter value. See Sharing Coherence*Web Sessions with Other Application Servers.

coherence-session-app-locking

This value, if set to true, will prevent two threads in different applications from processing a request for the same session at the same time. If set to true the value of the coherence-session-member-locking parameter will be ignored, because application locking implies member locking. A value of false is incompatible with thread locking.

If unspecified, this parameter defaults to false.

See also coherence-session-member-locking, coherence-session-locking, and coherence-session-app-locking parameter descriptions in this table and Session Locking Modes.

coherence-session-cachename

This name overrides the name of the clustered cache that stores the sessions.

If unspecified, this parameter defaults to session-storage. SeeSession Cache Configuration File.

coherence-session-cache-federated

This specifies whether the session cache is federated among cluster participants. Valid values are true and false. If set to true, the default-federated-session-cache-config.xml session cache configuration file is used and results in the session cache being federated. See Federated Session Caches.

The default is false

coherence-session-cookie-domain

This specifies the domain of the session cookie as defined by Request for Comments 2109: HTTP State Management Mechanism (RFC 2109). By default, no domain is set explicitly by the session management implementation. See Session and Session Attribute Scoping.

coherence-session-cookie-httponly

Appends the HttpOnly attribute to the session cookie. Note that not all browsers support this functionality. This context parameter can be used only with instrumented applications. See Preventing Cross-Site Scripting Attacks.

coherence-session-cookie-name

This specifies the name of the session cookie.

If unspecified, this parameter defaults to JSESSIONID.

coherence-session-cookie-path

This specifies the path of the session cookie as defined by RFC 2109. By default, no path is set explicitly by the session management implementation. See Session and Session Attribute Scoping.

coherence-session-cookie-max-age

This specifies the maximum age in seconds of the session cookie as defined by RFC 2109. A value of -1 indicates that the cookie will not persist on the client; a positive value gives the maximum age that the cookie will be persistent for the client. Zero is not permitted.

If unspecified, this parameter defaults to -1.

coherence-session-cookie-secure

If true, this value ensures that the session cookie will be sent only from a Web client over a Secure Socket Layer (SSL) connection. If unspecified, the default is false.

coherence-session-cookies-enabled

If unspecified, this parameter defaults to true to enable session cookies.

coherence-session-expire-seconds

This value overrides the session expiration time, and is expressed in seconds. Setting it to -1 causes sessions to never expire. See Cleaning Up Expired HTTP Sessions.

If unspecified, this parameter defaults to 1800.

coherence-session-get-lock-timeout

This value configures a timeout for lock acquisition for Coherence*Web. See Troubleshooting Locking in HTTP Sessions.

coherence-session-id-length

This is the length, in characters, of generated session IDs. The suggested absolute minimum length is 8.

If unspecified, this parameter defaults to 12.

coherence-session-lazy-access

This value enables lazy acquisition of sessions. A session will be acquired only when the servlet or filter attempts to access it. This is relevant only for instrumented Web applications. See Accessing Sessions with Lazy Acquisition.

If unspecified, this parameter defaults to false.

coherence-session-locking

If false, concurrent modification to sessions, with the last update being saved, will be allowed. If coherence-session-app-locking, coherence-session-member-locking, or coherence-session-thread-locking are set to true, then this value is ignored (being logically true). See Optimistic Locking and Last-Write-Wins Locking.

If unspecified, this parameter defaults to false.

See also coherence-session-app-locking , coherence-session-member-locking, and coherence-session-thread-locking in this table.

coherence-session-locking-mode

The value of this context parameter determines the locking mode that will govern concurrent access to HTTP sessions.

  • none—This value allows concurrent access to a session by multiple threads in a single member or multiple members. In this case, the last write is saved. This is the default locking mode. See Last-Write-Wins Locking.

  • optimistic—This value allows multiple web container threads in one or more members to access the same session concurrently. See Optimistic Locking.

  • app—This value prevent two threads in different applications from processing a request for the same session at the same time. If this parameter is set to app, then the value of the coherence-session-member-locking parameter will be ignored, because application locking implies member locking. A value of false is incompatible with thread locking. See Application Locking.

  • member—This value allows multiple web container threads in the same cluster node to access and modify the same session concurrently, but prohibits concurrent access by threads in different members. See Member Locking.

  • thread—This value prevents two threads in the same JVM from processing a request for the same session at the same time. If set to true, the value of the coherence-session-member-locking parameter is ignored, because thread locking implies member locking. See Thread Locking.

For example, to set the coherence-session-locking-mode context parameter to application locking in web.xml:

<context-param>
   <param-name>coherence-session-locking-mode</param-name>
   <param-value>app</param-value>
</context-param>

coherence-session-log-invalidation-exceptions

During session invalidation, many class not found exceptions might be thrown and logged in the session reaper. If this context parameter is set to false, then the exceptions will be suppressed. If set to true, then the exceptions will be logged.

If unspecified, this parameter defaults to true. See Understanding Session Invalidation Exceptions for the Session Reaper.

coherence-session-log-threads-holding-lock

If true, this value specifies if a diagnostic invocation service is executed when a member cannot acquire the cluster lock for a session. The invocation service will cause the member that has ownership of the session to log the stack trace of the threads that are currently holding the lock. The coherence-session-log-threads-holding-lock context parameter is available only when the coherence-sticky-sessions context parameter is set to true.

If unspecified, this parameter defaults to true.

See Troubleshooting Locking in HTTP Sessions.

coherence-session-logger-level

An alternative way to set the logging level for Coherence*Web (as opposed to JDK logging). The valid values for this parameter are the same as for JDK logging: SEVERE, WARNING, INFO, CONFIG, FINE, FINER (default), and FINEST. See Configuring Logging for Coherence*Web.

See also the Javadoc for java.util.logging:

http://docs.oracle.com/javase/8/docs/api/java/util/logging/Level.html

coherence-session-management-cachename

This name overrides the name of the clustered cache that stores the management and configuration information for the session management implementation. Generally, it should be configured as a replicated cache.

If unspecified, this parameter defaults to session-management. See Session Cache Configuration File.

coherence-session-member-locking

If true, this value prevents two threads in different members from processing a request for the same session at the same time.

If unspecified, this parameter defaults to false.

See also coherence-session-thread-locking, coherence-session-locking, and coherence-session-app-locking in this table.

coherence.session.optimizeModifiedSessions

This JVM system property, if set to true, enables near cache optimizations which can improve performance with applications that use Last-Write-Wins locking.

If unspecified, this value defaults to false.

This parameter can be set only on the command line as a system property.

coherence-session-overflow-cachename

For the Split Model, this value overrides the name of the clustered cache that stores the large attributes that exceed a certain size and thus are determined to be more efficiently managed as separate cache entries and not as part of the serialized session object itself.

If unspecified, this parameter defaults to session-overflow. SeeSession Cache Configuration File.

coherence-session-strict-spec

If false, then the implementation will not be required to adhere to the servlet specification. The implementation will ignore certain types of exceptions and the application will not terminate. Setting, getting, and removing attributes, or invalidating sessions will not generate any callbacks to session listeners. Any ClassNotFound exceptions will not be propagated back to the caller if an attribute cannot be deserialized because the class does not exist in the invoking application.

If true, then the implementation strictly adheres to the servlet specification. ClassNotFound exceptions must be handled by the application, and session listener events will be sent, even if retrieving the attribute value fails.

If unspecified, this parameter defaults to true.

coherence-session-thread-locking

If true, this value prevents two threads in the same JVM from processing a request for the same session at the same time. If set to true, the value of the coherence-session-member-locking parameter is ignored, because thread locking implies member locking.

If unspecified, this parameter defaults to false.

See also coherence-session-app-locking, coherence-session-locking, and coherence-session-member-locking parameter descriptions in this table and Session Locking Modes.

coherence-session-urldecode-bycontainer

If true, this value uses the container's decoding of the URL session ID. If coherence-session-urlencode-name has been overridden, this must be set to false. Setting this to false will not work in some containers.

If unspecified, this parameter defaults to true.

coherence-session-urlencode-bycontainer

If true, this value uses the container's encoding of the URL session ID. Setting this to true could conflict with the setting for coherence-session-urlencode-name if it has been specified.

If unspecified, this parameter defaults to false.

coherence-session-urlencode-enabled

If true, this value enables URL encoding of session IDs.

If unspecified, this parameter defaults to true.

coherence-session-urlencode-name

This is the parameter name to encode the session ID into the URL. On some containers, this value cannot be overridden.

If unspecified, this parameter defaults to jsessionid.

coherence-session-weblogic-compatibility-mode

If true, a single session ID (with the cookie path set to "/") will map to a unique Coherence*Web session instance in each Web application. If false, then the standard behavior will apply: that is, a single session ID will map to a single session instance. All other session persistence mechanisms in WebLogic Server use a single session ID in each Web application to refer to different session instances.

If unspecified, this parameter defaults to true. An exception is when the application is configured to use the global scope controller. In this case, the default is false.

See Scoping the Session Cookie Path.

coherence-sessioncollection-class

This is the fully-qualified class name of the HttpSessionCollection implementation to use. Possible values include:

  • com.tangosol.coherence.servlet.MonolithicHttpSessionCollection

  • com.tangosol.coherence.servlet.SplitHttpSessionCollection (default)

  • com.tangosol.coherence.servlet.TraditionalHttpSessionCollection

A value must be specified for this parameter. See Configuring a Session Model.

coherence-shutdown-delay-seconds

This value determines how long the session management implementation waits before shutting down after receiving the last indication that the application has been stopped, either from ServletContextListener events (Servlet 2.3 or later) or by the destruction of Servlet and Filter objects. This value is expressed in seconds. A value of zero indicates synchronous shutdown; any positive value indicates asynchronous shutdown.

If unspecified, this parameter defaults to 0, because some servers are not capable of asynchronous shutdown.

coherence-sticky-sessions

If true, this value specifies whether sticky session optimizations will be used. This should be enabled only if a sticky load balancer is being used. This feature requires member, application or thread locking to be enabled. See Enabling Sticky Session Optimizations.

See also coherence-session-thread-locking, coherence-session-member-locking, and coherence-session-app-locking in this table.

If unspecified, this parameter defaults to false.