Featured , Phase-Deploy
Introduction
For the most simple integration you just need to have a tomcat (6 or 7) and a memcached installed (or s.th. supporting the memcached protocol). In your production environment you probably will have several tomcats and you should also have several memcached nodes available, on different pieces of hardware. You can use sticky sessions or non-sticky sessions, memcached-session-manager (msm) supports both operation modes.
The following description shows an example for a setup with sticky sessions, with two instances of tomcat and two instances of memcached installed.
Tomcat-1 (t1) will primarily store it's sessions in memcached-2 (m2) which is running on another machine (m2 is a regular node for t1). Only if m2 is not available, t1 will store it's sessions in memcached-1 (m1, m1 is the failoverNode for t1). With this configuration, sessions won't be lost when machine 1 (serving t1 and m1) crashes. The following really nice ASCII art shows this setup.
<t1> <t2>
. \ / .
. X .
. / \ .
<m1> <m2>
So what needs to be done for this?
Decide which serialization strategy to use
Starting with release 1.1 there are several session serialization strategies available, as they are described onSerializationStrategies. The default strategy uses java serialization and is already provided by the memcached-session-manager jar. Other strategies are provided by separate jars, in the section below you'll see which jars are required for which strategy.
Configure tomcat
The configuration of tomcat requires two things: you need to drop some jars in your$CATALINA_HOME/lib/ and WEB-INF/lib/ directories and you have to configure the memcached session manager in the related<Context> element (e.g. in $CATALINA_HOME/conf/context.xml).
Add memcached-session-manager jars to tomcat
Independent of the chosen serialization strategy you always need thememcached-session-manager-${version}.jar and either memcached-session-manager-tc6-${version}.jar for tomcat6 or memcached-session-manager-tc7-${version}.jar for tomcat7.
If you're using memcached or couchbase, you also need thespymemcached-2.8.12.jar and couchbase-client-1.1.4.jar.
If you're using couchbase, you need additionally these jars:jettison-1.1.jar, commons-codec-1.5.jar, httpcore-4.1.1.jar, httpcore-nio-4.1.1.jar, netty-3.5.5.Final.jar.
Please download the appropriate jars and put them in$CATALINA_HOME/lib/.
Add custom serializers to your webapp (optional)
If you want to use java's built in serialization nothing more has to be done. If you want to use a custom serialization strategy (e.g. because ofbetter performance) this has to be deployed with your webapp so that they're available inWEB-INF/lib/.
As msm is available in maven central (under groupIdde.javakaffee.msm) you can just pull it in using the dependency management of your build system. With maven you can use this dependency definition for the kryo-serializer:
<dependency>
<groupId>de.javakaffee.msm</groupId>
<artifactId>msm-kryo-serializer</artifactId>
<version>1.6.5</version>
<scope>runtime</scope>
</dependency>
For javolution the artifactId is msm-javolution-serializer, for xstreammsm-xstream-serializer and for flexjson it's msm-flexjson-serializer.
If you're not using a dependency management based on maven repositories these are the jars you need for the different serializers:
- kryo-serializer: msm-kryo-serializer, kryo-serializers-0.10 (0.10 is needed, as 0.20+ is for kryo2), kryo, minlog, reflectasm, asm-3.2
- javolution-serializer: msm-javolution-serializer, javolution-5.4.3.1
- xstream-serializer: msm-xstream-serializer, xstream, xmlpull, xpp3_min
- flexjson-serializer: msm-flexjson-serializer, flexjson
Configure memcached-session-manager as<Context> Manager
Update the <Context> element (in $CATALINA_HOME/conf/context.xml or what else you choose for context definition, please check the relatedtomcat documentation for this) so that it contains the Manager configuration for the memcached-session-manager, like in the examples below.
The following examples show configurations for sticky sessions and non-sticky sessions with memcached servers and for non-sticky sessions with membase. The examples with memcached servers assume that there are two memcacheds running, one on host1 and another one on host2. All sample configurations assume that you want to use kryo based serialization.
The following example shows the configuration of the first tomcat, assuming that it runs on host1, together with memcached "n1". The attributefailoverNodes="n1" tells msm to store sessions preferably in memcached "n2" and only store sessions in "n1" (running on the same host/machine) if no other memcached node (here only n2) is available (even if host1 goes down completely, the session is still available in memcached "n2" and could be served by the tomcat on host2). For the second tomcat (on host2) you just need to change the failover node to "n2", so that it prefers the memcached "n1". Everything else should be left unchanged.
<Context>
...
<Manager className="de.javakaffee.web.msm.MemcachedBackupSessionManager"
memcachedNodes="n1:host1.yourdomain.com:11211,n2:host2.yourdomain.com:11211"
failoverNodes="n1"
requestUriIgnorePattern=".*\.(ico|png|gif|jpg|css|js)$"
transcoderFactoryClass="de.javakaffee.web.msm.serializer.kryo.KryoTranscoderFactory"
/>
</Context>
The following example shows a configuration for non-sticky sessions. In this case there's no need forfailoverNodes, as sessions are served by all tomcats round-robin and they're not bound to a single tomcat. For non-sticky sessions the configuration (for both/all tomcats) would look like this:
<Context>
...
<Manager className="de.javakaffee.web.msm.MemcachedBackupSessionManager"
memcachedNodes="n1:host1.yourdomain.com:11211,n2:host2.yourdomain.com:11211"
sticky="false"
sessionBackupAsync="false"
lockingMode="uriPattern:/path1|/path2"
requestUriIgnorePattern=".*\.(ico|png|gif|jpg|css|js)$"
transcoderFactoryClass="de.javakaffee.web.msm.serializer.kryo.KryoTranscoderFactory"
/>
</Context>
To connect to a membase bucket "bucket1" the configuration would look like this:
<Context>
...
<Manager className="de.javakaffee.web.msm.MemcachedBackupSessionManager"
memcachedNodes="http://host1.yourdomain.com:8091/pools"
username="bucket1"
password="topsecret"
memcachedProtocol="binary"
sticky="false"
sessionBackupAsync="false"
requestUriIgnorePattern=".*\.(ico|png|gif|jpg|css|js)$"
transcoderFactoryClass="de.javakaffee.web.msm.serializer.kryo.KryoTranscoderFactory"
/>
</Context>
More details for all configuration attributes are provided in the section below.
After you have configured msm in the Context/Manager element, you can just start your application and sessions will be stored in the memcached nodes or in membase as configured. Now you should do some tests with a simulated tomcat failure, a restart of a memcached node etc. - have fun! :-)
Overview over memcached-session-manager configuration attributes
className (required)
This should be set to de.javakaffee.web.msm.MemcachedBackupSessionManager to get sessions stored in memcached. However, since version 1.3.6 there's also ade.javakaffee.web.msm.DummyMemcachedBackupSessionManager that can be used for development purposes: it simply serializes sessions to a special in memory map and deserializes the serialized data at the next request when a session is requested (without really using this session) - just to see if deserialization is working for each request. Your application is still using sessions as if the memcached-session-manager (or DummyMemcachedBackupSessionManager) would not be existing. Session serialization/deserialization is done asynchronously. The configuration attributes memcachedNodes andfailoverNode are not used to create a memcached client, so serialized session data willnot be sent to memcached - and therefore no running memcacheds are required.
memcachedNodes (required)
This attribute must contain all memcached nodes you have running, or the membase bucket uri(s). It should be the same for all tomcats.
memcached nodes: Each memcached node is defined as <id>:<host>:<port>. Several definitions are separated by space or comma (e.g.memcachedNodes="n1:app01:11211,n2:app02:11211"). For a single node the <id> is optional so that it's allowed to set only <host>:<port> (e.g.memcachedNodes="localhost:11211"). Then the sessionId will be left unchanged (no node id appended). This option is useful for the usage with e.g. membase+moxi, where each tomcat knows only a single "memcached" node (moxi actually).
membase bucket uris (since 1.6.0): For usage with membase it's possible to specify one or more membase bucket uris, e.g.http://host1:8091/pools,http://host2:8091/pools. Bucket name and password are specified via the attributesusername and password (see below). Connecting to membase buckets requires the binary memcached protocol. Also remember to have thejettison.jar and netty.jar available in CATALINA_HOME/lib/.
failoverNodes (optional, must not be used for non-sticky sessions)
This attribute must contain the ids of the memcached nodes, that shall not be used by this tomcat for session backup, but only if no other memcached nodes are available. Therefore, you should list those memcached nodes, that are running on the same machine as this tomcat. Several memcached node ids are separated by space or comma. For non-sticky sessions failoverNodes must not be specified as a session is not tied to a single tomcat. For membase buckets this attribute should also be left out.
username (since 1.6.0, optional)
Specifies the username used for a membase bucket or SASL. If thememcachedNodes contains a membase bucket uri (or multiple) this is the bucket name. If thememcachedNodes contains memcached node definitions this is the username used for SASL authentication. Both require the binary memcached protocol.
password (since 1.6.0, optional)
Specifies the password used for membase bucket or SASL authentication (can be left empty / omitted if the "default" membase bucket without a password shall be used).
memcachedProtocol (since 1.3, optional, defaulttext)
This attribute specifies the memcached protocol to use, one oftext or binary.
sticky (since 1.4.0, optional, default true)
Specifies if sticky or non-sticky sessions are used.
lockingMode (since 1.4.0, optional, for non-sticky sessions only, defaultnone)
Specifies the locking strategy for non-sticky sessions. Session locking is useful to prevent concurrent modifications and lost updates of the session in the case of parallel requests (tabbed browsing with long requests, ajax etc.). Session locking is done using memcached. Possible values for lockingMode are:
- none: sessions are never locked
- all: the session is locked when requested by the app until the end of the request
- auto: readonly requests are detected, for them the session is not locked. For requests that are not classified as "readonly" the session is locked
- uriPattern:<regexp>: the provided regular expression pattern is compared with the requestURI + "?" + queryString and the session is locked if they match.
requestUriIgnorePattern (optional)
This attribute contains a regular expression for request URIs, that shall not trigger a session backup. If static resources like css, javascript, images etc. are delivered by the same tomcat and the same web application context these requests will also pass the memcached-session-manager. However, as these requests should not change anything in a http session, they should also not trigger a session backup. So you should check if any static resources are delivered by tomcat and in this case you should exclude them by using this attribute. The requestUriIgnorePattern must follow the java regexPattern.
sessionBackupAsync (optional, default true)
Specifies if the session shall be stored asynchronously in memcached. If this istrue, the backupThreadCount setting is evaluated. If this is false, the timeout set via sessionBackupTimeout is evaluated.
backupThreadCount (since 1.3, optional, defaultnumber-of-cpu-cores)
The number of threads that are used for asynchronous session backup (ifsessionBackupAsync="true"). For the default value the number of available processors (cores) is used.
sessionBackupTimeout (optional, default 100)
The timeout in milliseconds after that a session backup is considered as beeing failed. This property is only evaluated if sessions are stored synchronously (set viasessionBackupAsync). The default value is 100 milliseconds.
operationTimeout (since 1.6.0, optional, default1000)
The memcached operation timeout used at various places, e.g. used for the spymemcached ConnectionFactory.
sessionAttributeFilter (since 1.5.0, optional)
A regular expression to control which session attributes are serialized to memcached. The regular expression is evaluated with session attribute names. E.g.sessionAttributeFilter="^(userName|sessionHistory)$" specifies that only "userName" and "sessionHistory" attributes are stored in memcached. Works independently from the chosen serialization strategy.
transcoderFactoryClass (since 1.1, optional, defaultde.javakaffee.web.msm.JavaSerializationTranscoderFactory)
The class name of the factory that creates the transcoder to use for serializing/deserializing sessions to/from memcached. The specified class must implementde.javakaffee.web.msm.TranscoderFactory and provide a no-args constructor. OtherTranscoderFactory implementations are available through other packages/jars likemsm-kryo-serializer, msm-xstream-serializer and msm-javolution-serializer (as describe above), those are listed and compared onSerializationStrategies.
Available TranscoderFactory implementations:
- Java serialization: de.javakaffee.web.msm.JavaSerializationTranscoderFactory
- Kryo based serialization:de.javakaffee.web.msm.serializer.kryo.KryoTranscoderFactory
- Javolution based serialization: de.javakaffee.web.msm.serializer.javolution.JavolutionTranscoderFactory
- XStream based serialization: de.javakaffee.web.msm.serializer.xstream.XStreamTranscoderFactory
copyCollectionsForSerialization (since 1.1, optional, defaultfalse)
A boolean value that specifies, if iterating over collection elements shall be done on a copy of the collection or on the collection itself. This configuration property must be supported by the serialization strategy specified with transcoderFactoryClass. Which strategy supports this feature can be seen in the columnCopy Collections before serialization in the list of available serialization strategies. This feature and its motivation is described more deeply atSerializationStrategies#Concurrent_modifications_of_collections.
customConverter (since 1.2, optional)
Custom converter allow you to provide custom serialization of application specific types. Multiple custom converter class names are specified separated by comma (with optional space following the comma). Converter classes must be available in the classpath of the web application (place jars in WEB-INF/lib).
This option is useful if you need some special serialization for a certain type or if reflection based serialization is just very verbose and you want to provide a more efficient serialization for a specific type.
Custom converter must be supported by the serialization strategy specified with transcoderFactoryClass. Requirements regarding the specific custom converter classes depend on the actual serialization strategy, but a common requirement would be that they must provide a default/no-args constructor. For more details have a look atavailable serialization strategies.
Available converter implementations:
- Kryo (converters provided by msm-kryo-serializer jar)
- de.javakaffee.web.msm.serializer.kryo.JodaDateTimeRegistration: A more efficient serialization of Joda'sDateTime with kryo.
- de.javakaffee.web.msm.serializer.kryo.CGLibProxySerializerFactory: serializes/deserializes CGLIB proxies.
- de.javakaffee.web.msm.serializer.kryo.HibernateCollectionsSerializerFactory: serializes/deserializes hibernate persistent collections (required if you store collections loaded by hibernate in your session).
- de.javakaffee.web.msm.serializer.kryo.WicketSerializerFactory: required if you're running a wicket web application.
- de.javakaffee.web.msm.serializer.kryo.FacesLRUMapRegistration: Needed if kryo serialization shall be used in combination with JSF2/Mojarra (see alsoissue #97).
- de.javakaffee.web.msm.serializer.kryo.GrailsFlashScopeRegistration: Support for grails flash scope (see alsoissue #107).
- Javolution (converters provided by msm-javolution-serializer jar)
- de.javakaffee.web.msm.serializer.javolution.JodaDateTimeFormat: A more efficient serialization of Joda'sDateTime, see also issue #32.
- de.javakaffee.web.msm.serializer.javolution.CGLibProxyFormat : serializes/deserializes CGLIB proxies, see alsoissue #59.
- de.javakaffee.web.msm.serializer.javolution.HibernateCollectionsXMLFormat: serializes/deserializes hibernate persistent collections (required if you store collections loaded by hibernate in your session).
enableStatistics (since 1.2, optional, defaulttrue)
A boolean value that specifies, if statistics shall be gathered. For more info see theJMXStatistics page.
enabled (since 1.4.0, optional, default true)
Specifies if session storage in memcached is enabled or not, can also be changed at runtime via JMX. Only allowed in sticky mode.
Configure logging
If you want to enable fine grained / debug logging you can add
de.javakaffee.web.msm.level=FINE
to $CATALINA_HOME/conf/logging.properties.
As the memcached-session-manager uses spymemcached also the logging hints of spymemcached might be interesting to you. A short summary how you can make spymemcached more silent:
- Add the following to $CATALINA_HOME/bin/catalina.sh:
CATALINA_OPTS="-Dnet.spy.log.LoggerImpl=net.spy.memcached.compat.log.SunLogger" - Add this to $CATALINA_HOME/conf/logging.properties:
# A handler's log level threshold can be set using SEVERE, WARNING, INFO, CONFIG, FINE, FINER, FINEST or ALL net.spy.memcached.level = WARNING # To make only the MemcachedConnection less verbose: #net.spy.memcached.MemcachedConnection.level = WARNING
More info about logging in tomcat can be found in thetomcat logging documentation.
396
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
