### Eclipse Workspace Patch 1.0 #P docs-cluster_guide Index: en-US/Clustering_Guide_HTTP.xml =================================================================== --- en-US/Clustering_Guide_HTTP.xml (revision 93485) +++ en-US/Clustering_Guide_HTTP.xml (working copy) @@ -18,7 +18,8 @@ State replication is directly handled by JBoss. When you run JBoss in the all configuration, session state replication is enabled by default. Just configure your web application as - <distributable> in its web.xml (see below), + <distributable> in its web.xml + (see ), deploy it, and its session state is automtically replicated across all JBoss instances in the cluster. However, load-balancing is a different story; it is not handled by @@ -44,15 +45,15 @@ example) will be lost and the clients will most probably need to login on another node and restart with a new session. In many situations, it is acceptable not to replicate HTTP sessions because all critical state - is stored in a database. In other situations, losing a client session - is not acceptable and, in this case, session state replication is the - price one has to pay. + is stored in a database or on the client. In other situations, losing a + client session is not acceptable and, in this case, session state + replication is the price one has to pay.
Configuring load balancing using Apache and mod_jk - Apache is a well-known web server which can be extended by plugging in modules. One of these modules, mod_jk has been specifically designed to allow the forwarding of requests from Apache to a Servlet container. Furthermore, it is also able to load-balance HTTP calls to a set of Servlet containers while maintaining sticky sessions, which is what is most interesting for us in this section. + Apache is a well-known web server which can be extended by plugging in modules. One of these modules, mod_jk, has been specifically designed to allow the forwarding of requests from Apache to a Servlet container. Furthermore, it is also able to load-balance HTTP calls to a set of Servlet containers while maintaining sticky sessions, which is what is most interesting for us in this section.
@@ -60,11 +61,11 @@ First of all, make sure that you have Apache installed. You can download Apache directly from Apache web site at http://httpd.apache.org/. Its installation is pretty straightforward and requires no specific configuration. As several versions of Apache exist, we - advise you to use version 2.0.x. We will consider, for the next sections, that you have installed + advise you to use the latest stable 2.2.x version. We will consider, for the next sections, that you have installed Apache in the APACHE_HOME directory. Next, download mod_jk binaries. Several versions of mod_jk exist as well. We strongly advise you to use mod_jk 1.2.x, as both mod_jk and mod_jk2 are deprecated, unsupported and no further - developments are going on in the community. The mod_jk 1.2.x binary can be downloaded from + development is going on in the community. The mod_jk 1.2.x binary can be downloaded from http://www.apache.org/dist/jakarta/tomcat-connectors/jk/binaries/. Rename the downloaded file to mod_jk.so and copy it under APACHE_HOME/modules/. @@ -134,7 +135,7 @@ The JkMount directive tells Apache which URLs it should forward to the mod_jk module (and, in turn, to the Servlet containers). In the above file, all requests with URL path /application/* are sent to the mod_jk load-balancer. This - way, you can configure Apache to server static contents (or PHP contents) directly and only + way, you can configure Apache to serve static contents (or PHP contents) directly and only use the loadbalancer for Java applications. If you only use mod_jk as a loadbalancer, you can also forward all URLs (i.e., /*) to mod_jk. @@ -197,9 +198,9 @@ worker.status.type=status Basically, the above file configures mod_jk to perform weighted round-robin load balancing with - sticky sessions between two servlet containers (JBoss Tomcat) node1 and node2 listening on port + sticky sessions between two servlet containers (i.e. JBoss AS instances) node1 and node2 listening on port 8009. - In the works.properties file, each node is defined using the + In the workers.properties file, each node is defined using the worker.XXX naming convention where XXX represents an arbitrary name you choose for each of the target Servlet containers. For each worker, you must specify the host name (or IP address) and the port number of the AJP13 connector running in the Servlet container. @@ -227,11 +228,11 @@
Configuring JBoss to work with mod_jk - Finally, we must configure the JBoss Tomcat instances on all clustered nodes so that they can + Finally, we must configure the JBoss AS instances on all clustered nodes so that they can expect requests forwarded from the mod_jk loadbalancer. On each clustered JBoss node, we have to name the node according to the name specified in workers.properties. For instance, on JBoss instance node1, edit the - JBOSS_HOME/server/all/deploy/jboss-web.deployer/server.xml file (replace + JBOSS_HOME/server/all/deploy/jbossweb.sar/server.xml file (replace /all with your own server name if necessary). Locate the <Engine> element and add an attribute jvmRoute: @@ -241,27 +242,19 @@ You also need to be sure the AJP connector in server.xml is enabled (i.e., uncommented). It is enabled by default. - - ]]> + +]]> - -Then, for each JBoss Tomcat instance in the cluster, we need to tell it that mod_jk is in use, so it can properly manage the jvmRoute appended to its session cookies so that mod_jk can properly route incoming requests. Edit the - JBOSS_HOME/server/all/deploy/jbossweb-tomcat50.sar/META-INF/jboss-service.xml - file (replace /all with your own server name). Locate the - <attribute> element with a name of UseJK, and set - its value to true: - -<attribute name="UseJK">true</attribute> - + At this point, you have a fully working Apache+mod_jk load-balancer setup that will balance call to the Servlet containers of your cluster while taking care of session stickiness (clients will always use the same Servlet container). - For more updated information on using mod_jk 1.2 with JBoss Tomcat, please refer to the JBoss + For more updated information on using mod_jk 1.2 with JBoss AS, please refer to the JBoss wiki page at - http://wiki.jboss.org/wiki/Wiki.jsp?page=UsingMod_jk1.2WithJBoss. + http://www.jboss.org/community/wiki/UsingModjk12WithJBoss.
@@ -271,155 +264,383 @@ The preceding discussion has been focused on using mod_jk as a load balancer. The content of the remainder our discussion of clustering HTTP services in JBoss AS applies no matter what load balancer is used. - In , we covered how to use sticky sessions to make sure that a client in a session always hits the same server node in order to maintain the session state. However, sticky sessions by themselves are not an ideal solution. If a node goes down, all its session data is lost. A better and more reliable solution is to replicate session data across the nodes in the cluster. This way, the client can hit any server node and obtain the same session state. + In , we covered how to use sticky sessions to make sure that a client in a session always hits the same server node in order to maintain the session state. However, sticky sessions by themselves are not an ideal solution. If a node goes down, all its session data is lost. A better and more reliable solution is to replicate session data across the nodes in the cluster. This way, if a server node fails or is shut down, the load balancer can fail over the next client request to any server node and obtain the same session state. - The jboss.cache:service=TomcatClusteringCache MBean makes use of JBoss Cache to - provide HTTP session replication services to the JBoss Tomcat cluster. This MBean is defined in the deploy/jboss-web-cluster.sar/META-INF/jboss-service.xml file. - - Before AS 4.2.0, the location of the HTTP session cache configuration file was deploy/tc5-cluster.sar/META-INF/jboss-service.xml. Prior to AS 4.0.4 CR2, the file was named deploy/tc5-cluster-service.xml. - - Below is a typical deploy/jbossweb-cluster.sar/META-INF/jboss-service.xml file. The - configuration attributes in the TomcatClusteringCache MBean are very similar to - those in the JBoss AS cache configuration. - -<mbean code="org.jboss.cache.aop.TreeCacheAop" - name="jboss.cache:service=TomcatClusteringCache"> - - <depends>jboss:service=Naming</depends> - <depends>jboss:service=TransactionManager</depends> - <depends>jboss.aop:service=AspectDeployer</depends> - - <attribute name="TransactionManagerLookupClass"> - org.jboss.cache.BatchModeTransactionManagerLookup - </attribute> - - <attribute name="IsolationLevel">REPEATABLE_READ</attribute> - - <attribute name="CacheMode">REPL_ASYNC</attribute> - - <attribute name="ClusterName"> - Tomcat-${jboss.partition.name:Cluster} - </attribute> - - <attribute name="UseMarshalling">false</attribute> - - <attribute name="InactiveOnStartup">false</attribute> - - <attribute name="ClusterConfig"> - ... ... - </attribute> - - - <attribute name="LockAcquisitionTimeout">15000</attribute> - <attribute name="SyncReplTimeout">20000</attribute> -</mbean> - - - Note that the value of the mbean element's code attribute is org.jboss.cache.aop.TreeCacheAop, which is different from the other JBoss Cache Mbeans used in JBoss AS. This is because FIELD granularity HTTP session replication (covered below) needs the added features of the TreeCacheAop (a.k.a. PojoCache) class. - - - The details of all the configuration options for a TreeCache MBean are covered in the JBoss Cache documentation. Below, we will just discuss several attributes that are most relevant to the HTTP cluster session replication. - - - TransactionManagerLookupClass sets the transaction - manager factory. The default value is - org.jboss.cache.BatchModeTransactionManagerLookup. It tells the cache - NOT to participate in JTA-specific transactions. Instead, the cache manages its own transactions. Please do not change this. - - - - CacheMode controls how the cache is replicated. The valid - values are REPL_SYNC and REPL_ASYNC. With either setting the client request thread updates the local cache with the current sesssion contents and then sends a message to the caches on the other members of the cluster, telling them to make the same change. With REPL_ASYNC (the default) the request thread returns as soon as the update message has been put on the network. With REPL_SYNC, the request thread blocks until it gets a reply message from all cluster members, informing it that the update was successfully applied. Using synchronous replication makes sure changes are applied aroundthe cluster before the web request completes. However, synchronous replication is much slower. - - - ClusterName specifies the name of the cluster that the - cache works within. The default cluster name is the the word "Tomcat-" appended by the - current JBoss partition name. All the nodes must use the same cluster name. - - - The UseMarshalling and InactiveOnStartup attributes must have the same value. They must be - true if FIELD level session replication is needed - (see later). Otherwise, they are default to false. - - - ClusterConfig configures the underlying JGroups stack. Please refer to for more information. - - - LockAcquisitionTimeout sets the maximum number of - milliseconds to wait for a lock acquisition when trying to lock a cache node. The default value is 15000. - - - SyncReplTimeout sets the maximum number of milliseconds to wait for a response from all nodes in the cluster when a synchronous replication message is sent out. The default value is 20000; should be a few seconds longer than LockAcquisitionTimeout. - - - - +
Enabling session replication in your application - To enable clustering of your web application you must tag it as distributable in the + To enable replication of your web application sessions, you must tag + the application as distributable in the web.xml descriptor. Here's an example: <?xml version="1.0"?> <web-app xmlns="http://java.sun.com/xml/ns/j2ee" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://java.sun.com/xml/ns/j2ee - http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" + http://java.sun.com/xml/ns/j2ee/web-app_2_4.xsd" version="2.4"> + <distributable/> - <!-- ... --> + </web-app> You can futher configure session replication using the replication-config - element in the jboss-web.xml file. Here is an example: - <jboss-web> - <replication-config> - <replication-trigger>SET_AND_NON_PRIMITIVE_GET</replication-trigger> - <replication-granularity>SESSION</replication-granularity> - <replication-field-batch-mode>true</replication-field-batch-mode> - </replication-config> -</jboss-web> - The replication-trigger element determines what triggers a session replication - (i.e. when is a session is considered dirty and in need of replication). It has 4 options: + element in the jboss-web.xml file. However, + the replication-config element only needs to be set + if one or more of the default values described below is unacceptable. + Here is an example: + + + + + + custom-session-cache + SET + ATTRIBUTE + true + false + 30 + instant + 1000 + com.example.CustomSessionNotificationPolicy + + +]]> + + All of the above configuration elements are optional and can be ommitted + if the default value is acceptable. A couple are commonly used; the rest + are very infrequently changed from the defaults. We'll cover the commonly used ones first. + + The replication-trigger element determines when + the container should consider that session data must be replicated across + the cluster. The rationale for this setting is that after a mutable object + stored as a session attribute is accessed from the session, in the absence + of a setAttribute call the container has no clear way + to know if the object (and hence the session state) has been modified + and needs to be replicated. This element has 3 valid values: - SET: With this policy, the session is considered dirty only when an attribute is set in the session (i.e., HttpSession.setAttribute() is invoked.) If your application always writes changed values back into the session, this option will be most optimal in terms of performance. The downside of SET is that if an object is retrieved from the session and modified without being written back into the session, the session manager will not know the attribute is dirty and the change to that object may not be replicated. + SET_AND_GET is conservative but not optimal (performance-wise): it will always replicate session data even if its content has not been modified but simply accessed. This setting made (a little) sense in AS 4 since using it was a way to ensure that every request triggered replication of the session's timestamp. Since setting max_unreplicated_interval to 0 accomplishes the same thing at much lower cost, using SET_AND_GET makes no sense with AS 5. - SET_AND_GET: With this policy, any attribute that is get or set will be marked as dirty. If an object is retrieved from the session and modified without being written back into the session, the change to that object will be replicated. The downside of SET_AND_GET is that it can have significant performance implications, since even reading immutable objects from the session (e.g., strings, numbers) will mark the read attributes as needing to be replicated. + SET_AND_NON_PRIMITIVE_GET is conservative but will only replicate if an object of a non-primitive type has been accessed (i.e. the object is not of a well-known immutable JDK type such as Integer, Long, String, etc.) This is the default value. - SET_AND_NON_PRIMITIVE_GET: This policy is similar to the SET_AND_GET policy except that get operationsthat return attribute values with primitive types do not mark the attribute as dirty. Primitive system types (i.e., String, Integer, Long, etc.) are immutable, so there is no reason to mark an attribute with such a type as dirty just because it has been read. If a get operation returns a value of a non-primitive type, the session manager has no simple way to know whether the object is mutable, so it assumes it is an marks the attribute as dirty. This setting avoids the downside of SET while reducing the performance impact of SET_AND_GET. It is the default setting. - - - ACCESS: This option causes the session to be marked as dirty whenever it is accessed. Since a the session is accessed during each HTTP request, it will be replicated with each request. The purpose of ACCESS is to ensure session last-access timestamps are kept in sync around the cluster.. Since with the other replication-trigger options the time stamp may not be updated in other clustering nodes because of no replication, the session in other nodes may expire before the active node if the HTTP request does not retrieve or modify any session attributes. When this option is set, the session timestamps will be synchronized throughout the cluster nodes. Note that use of this option can have a significant performance impact, so use it with caution. With the other replication-trigger options, if a session has gone 80% of its expiration interval without being replicated, as a safeguard its timestamp will be replicated no matter what. So, ACCESS is only useful in special circumstances where the above safeguard is considered inadequate. + SET assumes that the developer will explicitly call setAttribute on the session if the data needs to be replicated. This setting prevents unnecessary replication and can have a major beneficial impact on performance, but requires very good coding practices to ensure setAttribute is always called whenever a mutable object stored in the session is modified. - The replication-granularity element controls the size of the replication units. + + In all cases, calling setAttribute marks the session as needing replication. + + The replication-granularity element determines the granularity of what gets replicated if the container determines session replication is needed. The supported values are: - + + + SESSION indicates that the entire session attribute map should be replicated when any attribute is considered modified. Replication occurs at request end. This option replicates the most data and thus incurs the highest replication cost, but since all attributes values are always replicated together it ensures that any references between attribute values will not be broken when the session is deserialized. For this reason it is the default setting. + - ATTRIBUTE: Replication is only for the dirty attributes in the session plus some session data, like the last-accessed timestamp. For sessions that carry large amounts of data, this option can increase replication performance. However, attributes will be separately serialized, so if there are any shared references between objects stored in the attributes, those shared references may be broken on remote nodes. For example, say a Person object stored under key “husband” has a reference to an Address, while another Person object stored under key “wife” has a reference to that same Address object. When the “husband” and “wife” attributes are separately deserialized on the remote nodes, each Person object will now have a reference to its own Address object; the Address object will no longer be shared. - - - SESSION: The entire session object is replicated if any attribute is dirty. The entire session is serialized in one unit, so shared object references are maintained on remote nodes. This is the default setting. - - - + ATTRIBUTE indicates that only attributes that the session considers to be potentially modified are replicated. Replication occurs at request end. For sessions carrying large amounts of data, parts of which are infrequently updated, this option can significantly increase replication performance. However, it is not suitable for applications that store objects in different attributes that share references with each other (e.g. a Person object in the "husband" attribute sharing with another Person in the "wife" attribute a reference to an Address object). This is because if the attributes are separately replicated, when the session is deserialized on remote nodes the shared references will be broken. + - FIELD: Replication is only for individual changed data fields inside session attribute objects. Shared object references will be preserved across the cluster. Potentially most performant, but requires changes to your application (this will be discussed later). + FIELD is useful if the classes stored in the session have been bytecode enhanced for use by POJO Cache. If they have been, the session management layer will detect field level changes within objects stored to the session, and will replicate only those changes. This is the most performant setting. Replication is only for individual changed data fields inside session attribute objects. Shared object references will be preserved across the cluster. Potentially most performant, but requires changes to your application (this will be discussed later). - The replication-field-batch-mode element indicates whether you want all replication messages associated with a request to be batched into one message. Only applicable if replication-granularity is FIELD. Default is true. - If your sessions are generally small, SESSION is the better policy. If your session is larger and - some parts are infrequently accessed, ATTRIBUTE replication will be more effective. If your - application has very big data objects in session attributes and only fields in those objects are - frequently modified, the FIELD policy would be the best. In the next section, we will discuss exactly - how the FIELD level replication works. + + The other elements under the replication-config element are much less frequently used. + + The cacheName element indicates the name of the + JBoss Cache configuration that should be used for storing distributable + sessions and replicating them around the cluster. This element allows webapps that need + different caching characteristics to specify the use of separate, differently + configured, JBoss Cache instances. In AS 4 the cache to use was a server-wide + configuration that could not be changed per webapp. The default value is standard-session-cache + if the replication-granularity is not FIELD, + field-granularity-session-cache if it is. See + for more details on JBoss Cache configuration for web tier clustering. + + The replication-field-batch-mode element indicates + whether you want all replication messages associated with a request to be + batched into one message. Only applicable if replication-granularity + is FIELD. If this is set to true, + fine-grained changes made to objects stored in the session + attribute map will replicate only when the http request is finished; otherwise + they replicate as they occur. Setting this to false is not + advised. Default is true. + + The useJK element indicates whether the container + should assume a JK-based software load balancer (e.g. mod_jk, mod_proxy, + mod_cluster) is used for load balancing for this webapp. If set to true, + the container will examine the session id associated with every request and + replace the jvmRoute portion of the session id if it detects a failover. + + The default value is null (i.e. unspecified), in + which case the session manager will use the presence or absence of a jvmRoute + configuration on its enclosing JBoss Web Engine + (see ) as indicating whether JK is used. + + The only real reason to set this element is to set it to false + for a particular webapp whose URL's the JK load balancer doesn't handle. Even doing + that isn't really necessary. + + The max-unreplicated-interval element configures the + maximum interval between requests, in seconds, after which a request will + trigger replication of the session's timestamp regardless of whether the + request has otherwise made the session dirty. Such replication ensures that + other nodes in the cluster are aware of the most recent value for the session's + timestamp and won't incorrectly expire an unreplicated session upon failover. + It also results in correct values for HttpSession.getLastAccessedTime() calls + following failover. + + A value of 0 means the timestamp will be replicated + whenever the session is accessed. A value of -1 means the + timestamp will be replicated only if some other activity during the request + (e.g. modifying an attribute) has resulted in other replication work involving + the session. A positive value greater than the + HttpSession.getMaxInactiveInterval() value will be treated + as a likely misconfiguration and converted to 0; i.e. replicate + the metadata on every request. Default value is 60. + + The snapshot-mode element configures when sessions + are replicated to the other nodes. Possible values are instant + (the default) and interval. + + The typical value, instant, replicates changes to the + other nodes at the end of requests, using the request processing thread to + perform the replication. In this case, the snapshot-interval + property is ignored. + + With interval mode, a background task is created that + runs every snapshot-interval milliseconds, checking for + modified sessions and replicating them. + + Note that this property has no effect if replication-granularity + is set to FIELD. If it is FIELD, + instant mode will be used. + + The snapshot-interval element defines how often + (in milliseconds) the background task that replicates modified sessions + should be started for this web app. Only meaningful if snapshot-mode + is set to interval. + + The session-notification-policy element specifies the + fully qualified class name of the implementation of the + ClusteredSessionNotificationPolicy interface that should be + used to govern whether servlet specification notifications should be emitted + to any registered HttpSessionListener, HttpSessionAttributeListener + and/or HttpSessionBindingListener. + + Event notifications that may make sense in a non-clustered environment + may or may not make sense in a clustered environment; see + https://jira.jboss.org/jira/browse/JBAS-5778 + for an example of why a notification may not be desired. Configuring an appropriate + ClusteredSessionNotificationPolicy gives the application + author fine-grained control over what notifications are issued. + + In AS 5.0.0.GA the default value if not explicitly set is the + LegacyClusteredSessionNotificationPolicy, which implements + the behavior in previous JBoss versions. In the AS 5.1.0 release this was + changed to IgnoreUndeployLegacyClusteredSessionNotificationPolicy, + which implements the same behavior except for in undeployment situations, + during which no HttpSessionListener and + HttpSessionAttributeListener notifications are sent. + +
+ +
+ HttpSession Passivation and Activation + Passivation is the process of controlling memory usage by removing + relatively unused sessions from memory while storing them in persistent + storage. If a passivated session is requested by a client, it can be + "activated" back into memory and removed from the persistent store. + JBoss AS 5 supports passivation of HttpSessions from webapps whose + web.xml includes the distributable + tag (i.e. clustered webapps). + + Passivation occurs at 3 points during the lifecycle of a web application: + + + + When the container requests the creation of a new session. + If the number of currently active sessions exceeds a configurable limit, + an attempt is made to passivate sessions to make room in memory. + + + Periodically (by default every ten seconds) as the JBoss Web + background task thread runs. + + + When the web application is deployed and a backup copy of sessions + active on other servers is acquired by the newly deploying web app's + session manager. + + + + A session will be passivated if one of the following holds true: + + + + The session hasn't been used in greater than a configurable maximum idle time. + + + The number of active sessions exceeds a configurable maximum and the + session hasn't been used in greater than a configurable minimum idle time. + + + + In both cases, sessions are passivated on a Least Recently Used (LRU) basis. + +
+ Configuring HttpSession Passivation + + Session passivation behavior is configured via the + jboss-web.xml deployment descriptor in your webapp's + WEB-INF directory. + + + + + + 20 + + true + 60 + 600 + + + +]]> + + + + max-active-session + Determines the maximum number of active sessions allowed. If the + number of sessions managed by the the session manager exceeds this value + and passivation is enabled, the excess will be passivated based on the + configured passivation-min-idle-time. If after + passivation is completed (or if passivation is disabled), the number of + active sessions still exceeds this limit, attempts to create new sessions + will be rejected. If set to -1 (the default), there is no limit + + + use-session-passivation + Determines whether session passivation will be enabled for the web + application. Default is false. + + + passivation-min-idle-time + Determines the minimum time (in seconds) that a session must have been + inactive before the container will consider passivating it in order to + reduce the active session count below max-active-sessions. + A value of -1 (the default) disables passivating sessions + before passivation-max-idle-time. Neither a value of -1 + nor a high value are recommended if max-active-sessions + is set. + + + passivation-max-idle-time + Determines the maximum time (in seconds) that a session can be inactive + before the container should attempt to passivate it to save memory. + Passivation of such sessions will take place regardless of whether the + active session count exceeds max-active-sessions. Should + be less than the web.xml session-timeout setting. A value + of -1 (the default) disables passivation based on maximum + inactivity. + + + + Note that the number of sessions in memory includes sessions + replicated from other cluster nodes that are not being accessed on this + node. Be sure to account for that when setting + max-active-sessions. Note also that the number of + sessions replicated from other nodes may differ greatly depending on + whether buddy replication is enabled. In an 8 node cluster where each + node is handling requests from 100 users, with total replication each + node will have 800 sessions in memory. With buddy replication with the + default numBuddies setting of 1, + each node will have 200 sessions in memory.
+
+
+ + Configuring the JBoss Cache instance used for session state replication + The container for a distributable web application makes use of JBoss Cache to + provide HTTP session replication services around the cluster. The container + integrates with the CacheManager service to obtain a reference to a JBoss Cache instance + (see ). + The name of the JBoss Cache configuration to use is controlled by the + cacheName element in the application's + jboss-web.xml (see ). + In most cases, though, this does not need to be set as the default values of + standard-session-cache and + field-granularity-session-cache (for applications + configured for FIELD granularity) are appropriate. + The JBoss Cache configurations in the CacheManager service expose + are large number of options. See and + the JBoss Cache documentation for a more complete discussion. However, + the standard-session-cache and + field-granularity-session-cache configurations are + already optimized for the web session replication use case, and most of the + settings should not be altered. However, there are a few items + that an JBoss AS administrator may wish to change: + + + + cacheMode + By default, REPL_ASYNC, meaning a web request thread + sending a session replication message to the cluster does not wait for + responses from other cluster nodes confirming they have received and + processed the message. Alternative REPL_SYNC offers + greater guarantees that the session state was received, but at a significant + performance cost. See . + + + + enabled property in the buddyReplicationConfig section + Set to true to enable buddy replication. See . + Default is false. + + + + numBuddies property in the buddyReplicationConfig section + Set to a value greater than the default 1 to increase the number of backup nodes onto + which sessions are replicated. Only relevant if buddy replication is enabled. See . + + + + buddyPoolName property in the buddyReplicationConfig section + A way to specify a preferred replication group when buddy replication is enabled. + JBoss Cache tries to pick a buddy who shares the same pool name (falling back to other + buddies if not available). Only relevant if buddy replication is enabled. See . + + + + multiplexerStack + Name of the JGroups protocol stack the cache should use. See . + + + + clusterName + Identifying name JGroups will use for this cache's channel. Only + change this if you create a new cache configuration, in which case this + property should have a different value from all other cache configurations. + + + + + If you wish to use a completely new JBoss Cache configuration rather + than editing one of the existing ones, please see . +
+ +
Using FIELD level replication @@ -429,8 +650,7 @@ The first step in doing this is to identify the classes that need to be prepared. This is done via annotations. For example: - -If you annotate a class with InstanceAopMarker instead, then all of its subclasses will be automatically annotated as well. Similarly, you can annotate an interface with InstanceofAopMarker and all of its implementing classes will be annotated. For example: +If you annotate a class with @Replicable, then all of its subclasses will be automatically annotated as well. Similarly, you can annotate an interface with @Replicable and all of its implementing classes will be annotated. For example: - -There will be no need to annotate Student. It will be annotated automatically because it is a sub-class of Person. -Jboss AS 4.2 requires JDK 5 at runtime, but some users may still need to build their projects using JDK 1.4. In this case, annotating classes can be done via JDK 1.4 style annotations embedded in JavaDocs. For example: +There is no need to annotate Student. POJO Cache will recognize it as @Replicable because it is a sub-class of Person. +JBoss AS 5 requires JDK 5 at runtime, but some users may still need to build their projects using JDK 1.4. In this case, annotating classes can be done via JDK 1.4 style annotations embedded in JavaDocs. For example: - -/* - * My usual comments here first. - * @@org.jboss.web.tomcat.tc5.session.AopMarker - */ -public class Address -{ -... -} - - - -The anologue for @InstanceAopMarker is: - - -/* +/** + * Represents a street address. * - * @@org.jboss.web.tomcat.tc5.session.InstanceOfAopMarker + * @@org.jboss.cache.pojo.annotation.Replicable */ -public class Person +public class Address { ... } - - - Once you have annotated your classes, you will need to perform a pre-processing step to bytecode enhance your classes for use by TreeCacheAop. You need to use the JBoss AOP pre-compiler annotationc and post-compiler aopc to process the above source code before and after they are compiled by the Java compiler. The annotationc step is only need if the JDK 1.4 style annotations are used; if JDK 5 annotations are used it is not necessary. Here is an example on how to invoke those commands from command line. + Once you have annotated your classes, you will need to perform a pre-processing step to bytecode enhance your classes for use by POJO Cache. You need to use the JBoss AOP pre-compiler annotationc and post-compiler aopc to process the above source code before and after they are compiled by the Java compiler. The annotationc step is only need if the JDK 1.4 style annotations are used; if JDK 5 annotations are used it is not necessary. Here is an example of how to invoke those commands from command line. @@ -498,74 +701,39 @@ Please see the JBoss AOP documentation for the usage of the pre- and post-compiler. The JBoss AOP project also provides easy to use ANT tasks to help integrate those steps into your application build process. + + Finally, let's see an example on how to use FIELD-level replication on those data classes. First, we see some servlet code that reads some data from the request parameters, creates a couple of objects and stores them in the session: -// Do this only once. So this can be in init(), e.g. -if(firstTime) -{ - Person joe = new Person("Joe", 40); - Person mary = new Person("Mary", 30); - Address addr = new Address(); - addr.setZip(94086); - - joe.setAddress(addr); - mary.setAddress(addr); // joe and mary share the same address! +Person husband = new Person(getHusbandName(request), getHusbandAge(request)); +Person wife = new Person(getWifeName(request), getWifeAge(request)); +Address addr = new Address(); +addr.setPostalCode(getPostalCode(request)); - session.setAttribute("joe", joe); // that's it. - session.setAttribute("mary", mary); // that's it. -} +husband.setAddress(addr); +wife.setAddress(addr); // husband and wife share the same address! -Person mary = (Person)session.getAttribute("mary"); -mary.getAddress().setZip(95123); // this will update and replicate the zip code. - +session.setAttribute("husband", husband); // that's it. +session.setAttribute("wife", wife); // that's it. + + + Later, a different servlet could update the family's postal code: + +Person wife = (Person)session.getAttribute("wife"); +wife.getAddress().setPostalCode(getPostalCode(request)); // this will update and replicate the postal code. + + + Notice that in there is no need to call session.setAttribute() after you make changes to + the data object, and all changes to the fields are automatically replicated across the cluster. Besides plain objects, you can also use regular Java collections of those objects as session - attributes. JBoss cache automatically figures out how to handle those collections and replicate + attributes. POJO Cache automatically figures out how to handle those collections and replicate field changes in their member objects. -
- -
- Monitoring session replication - If you have deployed and accessed your application, go to the - jboss.cache:service=TomcatClusteringCache MBean and invoke the - printDetails operation. You should see output resembling the following. - /JSESSION - -/localhost - -/quote - -/FB04767C454BAB3B2E462A27CB571330 -VERSION: 6 -FB04767C454BAB3B2E462A27CB571330: org.jboss.invocation.MarshalledValue@1f13a81c - -/AxCI8Ovt5VQTfNyYy9Bomw** -VERSION: 4 -AxCI8Ovt5VQTfNyYy9Bomw**: org.jboss.invocation.MarshalledValue@e076e4c8 - - - This output shows two separate web sessions, in one application named quote, that are being shared via JBossCache. This example uses a replication-granularity of session. Had ATTRIBUTE level replication been used, there would be additional entries showing each replicated session attribute. In either case, the replicated values are stored in an opaque MarshelledValue container. There aren't currently any tools that allow you to inspect the contents of the replicated session values. If you do not see any output, either the application was not correctly marked as distributable or you haven't accessed a part of application that places values in the HTTP session. The org.jboss.cache and org.jboss.web logging categories provide additional insight into session replication useful for debugging purposes. - +
@@ -608,15 +776,14 @@ cacheConfig is the name of the - cache configuration (see ) to use + cache configuration (see ) to use for the clustered SSO cache. Default is clustered-sso. treeCacheName is deprecated; use cacheConfig. Specifies a JMX ObjectName of the JBoss Cache MBean to use for the clustered SSO cache. If no cache can be located from the - CacheManager service using the value of cacheConfig - (see ), + CacheManager service using the value of cacheConfig, an attempt to locate an mbean registered in JMX under this ObjectName will be made. Default value is jboss.cache:service=TomcatClusteringCache.