Fusion Middleware Documentation
Advanced Search


Administering HTTP Session Management with Oracle Coherence*Web
Close Window

Table of Contents

Show All | Collapse

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

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

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()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" 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 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:

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.

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

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.

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

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

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. 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 the coherence-distributioncontroller-class parameter is specified or the coherence-preserve-attributes parameter is true.

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

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 you are using ActiveCache for GlassFish, this value will be set to true because the GlassFish Server requires local sessions to be available.

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 Chapter 7, "Cleaning Up Expired HTTP Sessions" for more information about the Session Reaper.

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 Chapter 7, "Cleaning Up Expired HTTP Sessions" for more information about 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, 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 Chapter 7, "Cleaning Up Expired HTTP Sessions" for more information about the Session Reaper.

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

coherence-reaperdaemon-priority

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

If unspecified, this parameter 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. See "Session Attribute Scoping" for more information.

Valid values include:

The default value for Coherence*Web SPI and ActiveCache for GlassFish 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.

This context parameter has no effect when used with the WebLogic SPI.

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. When used with the Coherence*Web SPI, this parameter can be used to define a cache name, but the cache will not be used.

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

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

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

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

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

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

coherence-session-cookie-name

This specifies the name of the session cookie.

If unspecified, this parameter defaults to JSESSIONID.

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

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

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

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.

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

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.

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

coherence-session-cookies-enabled

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

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

coherence-session-deathcert-cachename

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

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

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 Chapter 7, "Cleaning Up Expired HTTP Sessions" for more information.

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

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.

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

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—not when using the Coherence*Web SPI. 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.

For more information on session invalidation and the cause of the class not found exceptions that might occur during operation of the session reaper, 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" for more information.

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

See also the Javadoc for java.util.logging:

http://docs.oracle.com/javase/1.4.2/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. Appendix C, "Session Cache Configuration File" describes this parameter.

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

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.

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

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.

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

coherence-session-urlencode-enabled

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

If unspecified, this parameter defaults to true.

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

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.

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

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 using the Coherence*Web SPI in WebLogic Server. 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:

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.

coherence-web-sessions-enabled

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