A Coherence*Web Context Parameters

This appendix describes the Coherence*Web context parameters. The parameters 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 Context Parameters for Coherence*Web

Parameter Name Description

coherence-attribute-overflow-threshold

For the split model, 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, defaults to 1024.

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" for more information.

If false, the Web application is responsible for shutting down the Coherence node (see com.tangosol.net.CacheFactory.shutdown()) according to its own considerations. 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" for more information on cluster node scoping.

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 J2EE application.

If unspecified, this parameter defaults to false.

coherence-configuration-consistency

If true, 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 members may exhibit inconsistent behavior in managing the session data.

If unspecified, this parameter defaults to false.

coherence-contextless-session-retain-millis

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. Since 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 legal range is 10 to 10000 (from 1/100th of a second up to 10 seconds).

If unspecified, defaults to 200.

coherence-distributioncontroller-class

This value specifies a class name of the com.tangosol.coherence.servlet.HttpSessionCollection$SessionDistributionController interface implementation to use. This feature requires coherence-sticky-sessions optimization to be enabled.

Legal values include:

coherence-enable-sessioncontext (See Note 1)

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

If unspecified, defaults to false.

coherence-eventlisteners (See Note 1)

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 web.xml.

coherence-enable-suspect-attributes

When set to true, an attempt is made to detect whether the value of any session-related attributes may have changed. Attributes that are mutable (determined with a simple check) and that can be accessed by a get are deemed to be suspect. Mutable objects may have been changed by application code and must be re-serialized back into the cache.

If unspecified, defaults to false.

coherence-factory-class

The fully qualified class name of the SessionHelper.Factory to use.

Defaults to com.tangosol.coherence.servlet.apiXX.DefaultFactory where XX 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 non-distributed sessions when coherence-distributioncontroller-class parameter is specified.

If unspecified, defaults to local-session-storage. Appendix C, "Session Cache Configuration File" describes this parameter.

coherence-local-attribute-cachename

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

If unspecified, defaults to local-attribute-storage. Appendix C, "Session Cache Configuration File" describes this parameter.

coherence-preserve-attributes

This value, if set to true, specifies whether 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.

If unspecified, 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 expiry. 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" for more information on the Session Reaper.

If unspecified, defaults to true.

coherence-reaperdaemon-cluster-coordinated

When set to true, 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" for more information on the Session Reaper.

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

If unspecified, defaults to false.

coherence-reaperdaemon-cycle-seconds

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

If unspecified, defaults to 300.

coherence-reaperdaemon-parallel

When 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 true.

coherence-reaperdaemon-priority

The priority for the Session Reaper daemon. For more information, see "Cleaning Up Expired HTTP Sessions" and the source for the java.lang.Thread class.

If unspecified, defaults to 5.

coherence-reaperdaemon-sweep-modulo

This parameter is deprecated as of Coherence Release 3.5.

coherence-scopecontroller-class

This value specifies a class name of the optional com.tangosol.coherence.servlet.HttpSessionCollection$AttributeScopeController interface implementation to use.

See "Session Attribute Scoping" for more information.

Legal values include:

coherence-servletcontext-clustered (See Note 1)

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, 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 (See Note 1)

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

If unspecified, defaults to servletcontext-storage. Appendix C, "Session Cache Configuration File" describes this parameter.

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, as application locking implies member locking. A value of false is incompatible with thread locking.

If unspecified, defaults to false.

See also: coherence-session-member-locking, coherence-session-locking, and coherence-session-thread-locking parameter descriptions and "Session Locking Modes".

coherence-session-cachename

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

If unspecified, defaults to session-storage. Appendix C, "Session Cache Configuration File" describes this parameter.

coherence-session-cookie-domain (See Note 1)

The domain of the session cookie as defined by RFC 2109. By default, no domain is set explicitly by the session management implementation. See "Session and Session Attribute Scoping" for more information.

coherence-session-cookie-name (See Note 1)

The name of the session cookie.

If unspecified, defaults to JSESSIONID.

coherence-session-cookie-path (See Note 1)

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" for more information.

coherence-session-cookie-max-age (See Note 1)

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

If unspecified, defaults to -1.

coherence-session-cookie-secure

Set to true to ensure that the session cookie will be sent only from a Web client over an SSL connection. If unspecified, the default is false.

coherence-session-cookies-enabled (See Note 1)

If unspecified, defaults to true to enable session cookies.

coherence-session-deathcert-cachename

This name overrides the name of the clustered cache that stores the IDs of "recently departed" sessions.

If unspecified, defaults to session-death-certificates. Appendix C, "Session Cache Configuration File" describes this parameter.

coherence-session-expire-seconds

This value overrides the session expiry time, and is expressed in seconds. Setting it to -1 causes sessions to never expire.

If unspecified, defaults to 1800.

See "Cleaning Up Expired HTTP Sessions" for more information.

coherence-session-id-length (See Note 1)

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

If unspecified, defaults to 12.

coherence-session-lazy-access

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

If unspecified, defaults to false.

coherence-session-locking

If false, concurrent modification to sessions, with the last update winning, 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 "Last Write Wins Locking".

If unspecified, defaults to false.

See also: coherence-session-app-locking, coherence-session-member-locking, and coherence-session-thread-locking

coherence-session-log-threads-holding-lock

If true, specifies whether 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.

If unspecified, defaults to true.

See "Troubleshooting Locking in HTTP Sessions" for more information.

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, defaults to session-management. Appendix C, "Session Cache Configuration File" describes this parameter.

coherence-session-member-locking

This value, if set to true, prevents two threads in different JVMs from processing a request for the same session at the same time. See "Optimistic Locking".

If unspecified, defaults to false.

See also: coherence-session-thread-locking, coherence-session-locking, and coherence-session-app-locking

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, defaults to session-overflow. Appendix C, "Session Cache Configuration File" describes this parameter.

coherence-session-strict-spec

If the value is set to 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 the value is set to 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, defaults to true.

coherence-session-thread-locking

This value, if set to true, 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, as thread locking implies member locking.

If unspecified, defaults to true.

See also: coherence-session-app-locking, coherence-session-locking, and coherence-session-member-locking parameter descriptions and "Session Locking Modes".

coherence-session-urldecode-bycontainer (See Note 1)

When set to true, 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, defaults to true.

coherence-session-urlencode-bycontainer (See Note 1)

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

If unspecified, defaults to false.

coherence-session-urlencode-enabled (See Note 1)

When set to true, enables URL encoding of session ids.

If unspecified, defaults to true.

coherence-session-urlencode-name (See Note 1)

The parameter name to encode the session id into the URL with. On some containers, this value cannot be overridden.

If unspecified, defaults to jsessionid.

coherence-session-weblogic-compatibility-mode

When set to 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 it is false, then the standard behavior will apply: that is, a single session ID will map to a single session instance using the Coherence*Web SPI in WebLogic. All other session persistence mechanisms in WebLogic use a single session ID in each web-app to refer to different session instances.

If unspecified, 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

The fully qualified class name of the HttpSessionCollection implementation to use. Possible values include:

A value must be specified for this parameter.

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 shut-down; any positive value indicates asynchronous shut-down.

If unspecified, defaults to 0, because some servers are not capable of asynchronous shut-down.

coherence-sticky-sessions

This value, if set to true, specifies whether sticky sessions optimizations will be used. This should only be enabled 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.

If unspecified, defaults to false.

coherence-web-sessions-enabled

Enables Coherence*Web sessions in WebLogic Portal applications. For more information, see "Enable Coherence*Web Sessions".


Notes:

  1. This parameter does not control Coherence*Web behavior when used with the WebLogic SPI implementation.