[jboss-cvs] JBossCache/docs/JBossCache-UserGuide/en/modules ...
Manik Surtani
manik at jboss.org
Thu Apr 26 10:31:43 EDT 2007
User: msurtani
Date: 07/04/26 10:31:43
Modified: docs/JBossCache-UserGuide/en/modules replication.xml
Log:
JBCACHE-1036
Revision Changes Path
1.9 +694 -560 JBossCache/docs/JBossCache-UserGuide/en/modules/replication.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: replication.xml
===================================================================
RCS file: /cvsroot/jboss/JBossCache/docs/JBossCache-UserGuide/en/modules/replication.xml,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -b -r1.8 -r1.9
--- replication.xml 30 Jan 2007 02:06:03 -0000 1.8
+++ replication.xml 26 Apr 2007 14:31:43 -0000 1.9
@@ -10,7 +10,8 @@
<para>JBoss Cache can be configured to be either local (standalone) or
clustered. If in a cluster, the cache can be configured to replicate
changes, or to invalidate changes. A detailed discussion on this
- follows.</para>
+ follows.
+ </para>
<section>
<title>Local Mode</title>
@@ -20,7 +21,8 @@
serializable - however, we recommend making them serializable, enabling
a user to change the cache mode at any time. The dependency on the
JGroups library is still there, although a JGroups channel is not
- started.</para>
+ started.
+ </para>
</section>
<section>
@@ -29,17 +31,22 @@
<para>Replicated caches replicate all changes to some or all of the other cache
instances in the cluster. Replication can either happen after each
modification (no transactions), or at the end of a transaction (commit
- time).</para>
+ time).
+ </para>
<para>Replication can be synchronous or asynchronous . Use of either one
of the options is application dependent. Synchronous replication blocks
- the caller (e.g. on a <literal>put()</literal>) until the modifications
+ the caller (e.g. on a
+ <literal>put()</literal>
+ ) until the modifications
have been replicated successfully to all nodes in a cluster.
Asynchronous replication performs replication in the background (the
- <literal>put()</literal> returns immediately). JBoss Cache also offers a
+ <literal>put()</literal>
+ returns immediately). JBoss Cache also offers a
replication queue, where modifications are replicated periodically (i.e.
interval-based), or when the queue size exceeds a number of elements, or
- a combination thereof.</para>
+ a combination thereof.
+ </para>
<para>Asynchronous replication is faster (no caller blocking), because
synchronous replication requires acknowledgments from all nodes in a
@@ -49,7 +56,8 @@
applied to all cache instances, whereas this is not be the case with asynchronous
replication. With asynchronous replication, errors are simply written to
a log. Even when using transactions, a transaction may succeed but
- replication may not succeed on all cache instances.</para>
+ replication may not succeed on all cache instances.
+ </para>
<section id="replication.tx">
<title>Replicated Caches and Transactions</title>
@@ -60,13 +68,18 @@
broadcast rather than a series of individual modifications, and can be
a lot more efficient than not using transactions. Another effect of
this is that if a transaction were to roll back, nothing is broadcast
- across a cluster.</para>
+ across a cluster.
+ </para>
<para>Depending on whether you are running your cluster in
asynchronous or synchronous mode, JBoss Cache will use either a single
- phase or <ulink
+ phase or
+ <ulink
url="http://en.wikipedia.org/wiki/Two-phase_commit_protocol">two phase
- commit</ulink> protocol, respectively.</para>
+ commit
+ </ulink>
+ protocol, respectively.
+ </para>
<section>
<title>One Phase Commits</title>
@@ -75,7 +88,8 @@
replicated in a single call, which instructs remote caches to apply
the changes to their local in-memory state and commit locally.
Remote errors/rollbacks are never fed back to the originator of the
- transaction since the communication is asynchronous.</para>
+ transaction since the communication is asynchronous.
+ </para>
</section>
<section>
@@ -89,20 +103,27 @@
the originator of the transaction broadcasts a commit. This
instructs all remote caches to commit their data. If any of the
caches fail to respond to the prepare phase, the originator
- broadcasts a rollback.</para>
+ broadcasts a rollback.
+ </para>
<para>Note that although the prepare phase is synchronous, the
- commit and rollback phases are asynchronous. This is because <ulink
+ commit and rollback phases are asynchronous. This is because
+ <ulink
url="http://java.sun.com/products/jta/">Sun's JTA
- specification</ulink> does not specify how transactional resources
+ specification
+ </ulink>
+ does not specify how transactional resources
should deal with failures at this stage of a transaction; and other
resources participating in the transaction may have indeterminate
state anyway. As such, we do away with the overhead of synchronous
communication for this phase of the transaction. That said, they can
be forced to be synchronous using the
- <literal>SyncCommitPhase</literal> and
- <literal>SyncRollbackPhase</literal> configuration
- attributes.</para>
+ <literal>SyncCommitPhase</literal>
+ and
+ <literal>SyncRollbackPhase</literal>
+ configuration
+ attributes.
+ </para>
</section>
</section>
@@ -114,22 +135,31 @@
more 'buddies' in the cluster, and only replicates to these specific
buddies. This greatly helps scalability as there is no longer a memory
and network traffic impact every time another instance is added to a
- cluster.</para>
+ cluster.
+ </para>
<para>One of the most common use cases of Buddy Replication is when a
replicated cache is used by a servlet container to store HTTP session
data. One of the pre-requisites to buddy replication working well and
- being a real benefit is the use of <emphasis>session
- affinity</emphasis>, more casually known as <emphasis>sticky
- sessions</emphasis> in HTTP session replication speak. What this means
+ being a real benefit is the use of
+ <emphasis>session
+ affinity
+ </emphasis>
+ , more casually known as
+ <emphasis>sticky
+ sessions
+ </emphasis>
+ in HTTP session replication speak. What this means
is that if certain data is frequently accessed, it is desirable that
this is always accessed on one instance rather than in a round-robin
fashion as this helps the cache cluster optimise how it chooses
buddies, where it stores data, and minimises replication
- traffic.</para>
+ traffic.
+ </para>
<para>If this is not possible, Buddy Replication may prove to be more
- of an overhead than a benefit.</para>
+ of an overhead than a benefit.
+ </para>
<section>
<title>Selecting Buddies</title>
@@ -139,28 +169,37 @@
<mediaobject>
<imageobject>
- <imagedata fileref="images/BuddyReplication.png" />
+ <imagedata fileref="images/BuddyReplication.png"/>
</imageobject>
</mediaobject>
</figure>
<para>Buddy Replication uses an instance of a
- <literal>BuddyLocator</literal> which contains the logic used to
+ <literal>BuddyLocator</literal>
+ which contains the logic used to
select buddies in a network. JBoss Cache currently ships with a
- single implementation, <literal>NextMemberBuddyLocator</literal>,
+ single implementation,
+ <literal>NextMemberBuddyLocator</literal>
+ ,
which is used as a default if no implementation is provided. The
- <literal>NextMemberBuddyLocator</literal> selects the next member in
+ <literal>NextMemberBuddyLocator</literal>
+ selects the next member in
the cluster, as the name suggests, and guarantees an even spread of
- buddies for each instance.</para>
+ buddies for each instance.
+ </para>
- <para>The <literal>NextMemberBuddyLocator</literal> takes in 2
- parameters, both optional. <itemizedlist>
+ <para>The
+ <literal>NextMemberBuddyLocator</literal>
+ takes in 2
+ parameters, both optional.
+ <itemizedlist>
<listitem>
<literal>numBuddies</literal>
- - specifies how many buddies each instance should pick to back its data onto. This defaults to 1.
+ - specifies how many buddies each instance should pick to back its data onto. This defaults to
+ 1.
</listitem>
<listitem>
@@ -172,32 +211,39 @@
<emphasis>try</emphasis>
- to select a buddy on a different physical host. If not able to do so though, it will fall back to colocated instances. This defaults to
+ to select a buddy on a different physical host. If not able to do so though, it will fall back
+ to colocated instances. This defaults to
<literal>true</literal>
.
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</section>
<section>
<title>BuddyPools</title>
- <para>Also known as <emphasis>replication groups</emphasis>, a buddy
+ <para>Also known as
+ <emphasis>replication groups</emphasis>
+ , a buddy
pool is an optional construct where each instance in a cluster may
be configured with a buddy pool name. Think of this as an 'exclusive
club membership' where when selecting buddies,
- <literal>BuddyLocator</literal>s that support buddy pools would try
+ <literal>BuddyLocator</literal>
+ s that support buddy pools would try
and select buddies sharing the same buddy pool name. This allows
system administrators a degree of flexibility and control over how
buddies are selected. For example, a sysadmin may put two instances
on two separate physical servers that may be on two separate
physical racks in the same buddy pool. So rather than picking an
instance on a different host on the same rack,
- <literal>BuddyLocator</literal>s would rather pick the instance in
+ <literal>BuddyLocator</literal>
+ s would rather pick the instance in
the same buddy pool, on a separate rack which may add a degree of
- redundancy.</para>
+ redundancy.
+ </para>
</section>
<section>
@@ -208,7 +254,8 @@
indirectly, via some other service such as HTTP session replication)
is able to redirect the request to any other random cache instance
in the cluster. This is where a concept of Data Gravitation comes
- in.</para>
+ in.
+ </para>
<para>Data Gravitation is a concept where if a request is made on a
cache in the cluster and the cache does not contain this
@@ -217,28 +264,36 @@
to check in the backup data they store for other caches. This means
that even if a cache containing your session dies, other instances
will still be able to access this data by asking the cluster to
- search through their backups for this data.</para>
+ search through their backups for this data.
+ </para>
<para>Once located, this data is then transferred to the instance
which requested it and is added to this instance's data tree. It is
then (optionally) removed from all other instances (and backups) so
that if session affinity is used, the affinity should now be to this
- new cache instance which has just <emphasis>taken
- ownership</emphasis> of this data.</para>
+ new cache instance which has just
+ <emphasis>taken
+ ownership
+ </emphasis>
+ of this data.
+ </para>
<para>Data Gravitation is implemented as an interceptor. The
following (all optional) configuration properties pertain to data
- gravitation. <itemizedlist>
+ gravitation.
+ <itemizedlist>
<listitem>
<literal>dataGravitationRemoveOnFind</literal>
- - forces all remote caches that own the data or hold backups for the data to remove that data, thereby making the requesting cache the new data owner. If set to
+ - forces all remote caches that own the data or hold backups for the data to remove that data,
+ thereby making the requesting cache the new data owner. If set to
<literal>false</literal>
- an evict is broadcast instead of a remove, so any state persisted in cache loaders will remain. This is useful if you have a shared cache loader configured. Defaults to
+ an evict is broadcast instead of a remove, so any state persisted in cache loaders will remain.
+ This is useful if you have a shared cache loader configured. Defaults to
<literal>true</literal>
@@ -270,7 +325,8 @@
<literal>false</literal>
- to prevent unnecessary network calls. Most use cases will know when it may need to gravitate data and will pass in an
+ to prevent unnecessary network calls. Most use cases will know when it may need to gravitate
+ data and will pass in an
<literal>Option</literal>
@@ -288,13 +344,15 @@
is unnecessary.
</listitem>
- </itemizedlist></para>
+ </itemizedlist>
+ </para>
</section>
<section>
<title>Configuration</title>
- <para><programlisting>
+ <para>
+ <programlisting>
<!-- Buddy Replication config -->
<attribute name="BuddyReplicationConfig">
@@ -306,7 +364,8 @@
<!-- These are the default values anyway -->
<buddyLocatorClass>org.jboss.cache.buddyreplication.NextMemberBuddyLocator</buddyLocatorClass>
- <!-- numBuddies is the number of backup nodes each node maintains. ignoreColocatedBuddies means that
+ <!-- numBuddies is the number of backup nodes each node maintains. ignoreColocatedBuddies means
+ that
each node will *try* to select a buddy on a different physical host. If not able to do so though,
it will fall back to colocated nodes. -->
<buddyLocatorProperties>
@@ -314,31 +373,39 @@
ignoreColocatedBuddies = true
</buddyLocatorProperties>
- <!-- A way to specify a preferred replication group. If specified, we try and pick a buddy why shares
- the same pool name (falling back to other buddies if not available). This allows the sysdmin to hint at
- backup buddies are picked, so for example, nodes may be hinted topick buddies on a different physical rack
+ <!-- A way to specify a preferred replication group. If specified, we try and pick a buddy why
+ shares
+ the same pool name (falling back to other buddies if not available). This allows the sysdmin to
+ hint at
+ backup buddies are picked, so for example, nodes may be hinted topick buddies on a different
+ physical rack
or power supply for added fault tolerance. -->
<buddyPoolName>myBuddyPoolReplicationGroup</buddyPoolName>
- <!-- Communication timeout for inter-buddy group organisation messages (such as assigning to and removing
+ <!-- Communication timeout for inter-buddy group organisation messages (such as assigning to and
+ removing
from groups, defaults to 1000. -->
<buddyCommunicationTimeout>2000</buddyCommunicationTimeout>
- <!-- Whether data is removed from old owners when gravitated to a new owner. Defaults to true. -->
+ <!-- Whether data is removed from old owners when gravitated to a new owner. Defaults to true.
+ -->
<dataGravitationRemoveOnFind>true</dataGravitationRemoveOnFind>
- <!-- Whether backup nodes can respond to data gravitation requests, or only the data owner is supposed to respond.
+ <!-- Whether backup nodes can respond to data gravitation requests, or only the data owner is
+ supposed to respond.
defaults to true. -->
<dataGravitationSearchBackupTrees>true</dataGravitationSearchBackupTrees>
- <!-- Whether all cache misses result in a data gravitation request. Defaults to false, requiring callers to
+ <!-- Whether all cache misses result in a data gravitation request. Defaults to false, requiring
+ callers to
enable data gravitation on a per-invocation basis using the Options API. -->
<autoDataGravitation>false</autoDataGravitation>
</config>
</attribute>
- </programlisting></para>
+ </programlisting>
+ </para>
</section>
</section>
</section>
@@ -356,29 +423,35 @@
twofold: network traffic is minimised as invalidation messages are very
small compared to replicating updated data, and also that other caches in
the cluster look up modified data in a lazy manner, only when
- needed.</para>
+ needed.
+ </para>
<para>Invalidation messages are sent after each modification (no
transactions), or at the end of a transaction, upon successful commit.
This is usually more efficient as invalidation messages can be optimised
for the transaction as a whole rather than on a per-modification
- basis.</para>
+ basis.
+ </para>
<para>Invalidation too can be synchronous or asynchronous, and just as in
the case of replication, synchronous invalidation blocks until all caches
in the cluster receive invalidation messages and have evicted stale data
while asynchronous invalidation works in a 'fire-and-forget' mode, where
invalidation messages are broadcast but doesn't block and wait for
- responses.</para>
+ responses.
+ </para>
</section>
<section>
<title>State Transfer</title>
- <para><emphasis>State Transfer</emphasis> refers to the process by which a
+ <para>
+ <emphasis>State Transfer</emphasis>
+ refers to the process by which a
JBoss Cache instance prepares itself to begin providing a service by
acquiring the current state from another cache instance and integrating
- that state into its own state.</para>
+ that state into its own state.
+ </para>
<section>
<title>State Transfer Types</title>
@@ -392,7 +465,8 @@
tree transfer represents full transfer while transfer of a particular
subtree represents partial state transfer. And finally state transfer
can be "in-memory" and "persistent" transfer depending on a particular
- use of cache. </para>
+ use of cache.
+ </para>
</section>
<section>
@@ -410,12 +484,14 @@
application state is represented as a tree whose aggregate size is 1GB,
rather than having to provide a 1GB byte array streaming state transfer
transfers the state in chunks of N bytes where N is user
- configurable.</para>
+ configurable.
+ </para>
<para>Byte array and streaming based state transfer are completely API
transparent, interchangeable, and statically configured through a
standard cache configuration XML file. Refer to JGroups documentation on
- how to change from one type of transfer to another. </para>
+ how to change from one type of transfer to another.
+ </para>
</section>
<section>
@@ -427,32 +503,42 @@
of the state related to the entire tree -- i.e. the root node and all
nodes below it. A "partial" state transfer is one where just a portion
of the tree is transferred -- i.e. a node at a given Fqn and all nodes
- below it.</para>
+ below it.
+ </para>
<para>If either in-memory or persistent state transfer is enabled, state
- transfer will occur at the following times:</para>
+ transfer will occur at the following times:
+ </para>
<orderedlist>
<listitem>
<para>Initial state transfer. This occurs when the cache is first
- started (as part of the processing of the <literal>start()</literal>
+ started (as part of the processing of the
+ <literal>start()</literal>
method). This is a full state transfer. The state is retrieved from
the cache instance that has been operational the longest. If there
is any problem receiving or integrating the state, the cache will
- not start.</para>
+ not start.
+ </para>
<para>Initial state transfer will occur unless:</para>
<orderedlist>
<listitem>
- <para>The cache's <literal>InactiveOnStartup</literal> property
- is <literal>true</literal> . This property is used in
- conjunction with region-based marshaling.</para>
+ <para>The cache's
+ <literal>InactiveOnStartup</literal>
+ property
+ is
+ <literal>true</literal>
+ . This property is used in
+ conjunction with region-based marshaling.
+ </para>
</listitem>
<listitem>
<para>Buddy replication is used. See below for more on state
- transfer with buddy replication.</para>
+ transfer with buddy replication.
+ </para>
</listitem>
</orderedlist>
</listitem>
@@ -463,19 +549,26 @@
classloader is needed to unmarshal the state for a portion of the
tree. State transfer cannot succeed until the application registers
this classloader with the cache. Once the application registers its
- classloader, it calls <literal>cache.getRegion(fqn,
- true).activate()</literal> . As part of the region activation
+ classloader, it calls
+ <literal>cache.getRegion(fqn,
+ true).activate()
+ </literal>
+ . As part of the region activation
process, a partial state transfer of the relevant subtree's state is
performed. The state is requested from the oldest cache instance in
the cluster; if that instance responds with no state, state is
requested from each instance one by one until one provides state or
- all instances have been queried.</para>
+ all instances have been queried.
+ </para>
<para>Typically when region-based marshalling is used, the cache's
- <literal>InactiveOnStartup</literal> property is set to
- <literal>true</literal> . This suppresses initial state transfer,
+ <literal>InactiveOnStartup</literal>
+ property is set to
+ <literal>true</literal>
+ . This suppresses initial state transfer,
which would fail due to the inability to deserialize the transferred
- state.</para>
+ state.
+ </para>
</listitem>
<listitem>
@@ -488,20 +581,28 @@
new buddy is slightly different from other forms of state transfer,
which are based on a "pull" approach (i.e. recipient asks for and
receives state). However, the process of preparing and integrating
- the state is the same.</para>
+ the state is the same.
+ </para>
<para>This "push" of state upon buddy group formation only occurs if
- the <literal>InactiveOnStartup</literal> property is set to
- <literal>false</literal> . If it is <literal>true</literal> , state
+ the
+ <literal>InactiveOnStartup</literal>
+ property is set to
+ <literal>false</literal>
+ . If it is
+ <literal>true</literal>
+ , state
transfer amongst the buddies only occurs when the application
- activates the region on the various members of the group.</para>
+ activates the region on the various members of the group.
+ </para>
<para>Partial state transfer following a region activation call is
slightly different in the buddy replication case as well. Instead of
requesting the partial state from one cache instance, and trying all
instances until one responds, with buddy replication the instance
that is activating a region will request partial state from each
- instance for which it is serving as a backup.</para>
+ instance for which it is serving as a backup.
+ </para>
</listitem>
</orderedlist>
</section>
@@ -510,7 +611,8 @@
<title>Transient ("in-memory") and persistent state transfer</title>
<para>The state that is acquired and integrated can consist of two basic
- types:</para>
+ types:
+ </para>
<orderedlist>
<listitem>
@@ -519,11 +621,15 @@
various in-memory nodes in the cache that is providing state are
serialized and transferred; the recipient deserializes the data,
creates corresponding nodes in its own in-memory tree, and populates
- them with the transferred data.</para>
+ them with the transferred data.
+ </para>
<para>"In-memory" state transfer is enabled by setting the cache's
- <literal>FetchInMemoryState</literal> configuration attribute to
- <literal>true</literal> .</para>
+ <literal>FetchInMemoryState</literal>
+ configuration attribute to
+ <literal>true</literal>
+ .
+ </para>
</listitem>
<listitem>
@@ -531,25 +637,35 @@
loader is used. The state stored in the state-provider cache's
persistent store is deserialized and transferred; the recipient
passes the data to its own cache loader, which persists it to the
- recipient's persistent store.</para>
+ recipient's persistent store.
+ </para>
<para>"Persistent" state transfer is enabled by setting a cache
- loader's <literal>fetchPersistentState</literal> attribute to
- <literal>true</literal> . If multiple cache loaders are configured
+ loader's
+ <literal>fetchPersistentState</literal>
+ attribute to
+ <literal>true</literal>
+ . If multiple cache loaders are configured
in a chain, only one can have this property set to true; otherwise
- you will get an exception at startup.</para>
+ you will get an exception at startup.
+ </para>
<para>Persistent state transfer with a shared cache loader does not
make sense, as the same persistent store that provides the data will
just end up receiving it. Therefore, if a shared cache loader is
used, the cache will not allow a persistent state transfer even if a
- cache loader has <literal>fetchPersistentState</literal> set to
- <literal>true</literal> .</para>
+ cache loader has
+ <literal>fetchPersistentState</literal>
+ set to
+ <literal>true</literal>
+ .
+ </para>
</listitem>
</orderedlist>
<para>Which of these types of state transfer is appropriate depends on
- the usage of the cache.</para>
+ the usage of the cache.
+ </para>
<orderedlist>
<listitem>
@@ -561,11 +677,15 @@
correct state. In-memory state can be transferred as well if the
desire is to have a "hot" cache -- one that has all relevant data in
memory when the cache begins providing service. (Note that the
- <literal><![CDATA[<cacheloader><preload>]]></literal> element in the <literal>CacheLoaderConfig</literal>configuration parameter can be used as well to
+ <literal><![CDATA[<cacheloader><preload>]]></literal>
+ element in the
+ <literal>CacheLoaderConfig</literal>
+ configuration parameter can be used as well to
provide a "warm" or "hot" cache without requiring an in-memory state
transfer. This approach somewhat reduces the burden on the cache
instance providing state, but increases the load on the persistent
- store on the recipient side.)</para>
+ store on the recipient side.)
+ </para>
</listitem>
<listitem>
@@ -574,7 +694,8 @@
in-memory (i.e. non-passivated) and persistent (i.e. passivated)
states. Therefore an in-memory state transfer is necessary. A
persistent state transfer is necessary if the cache loader is not
- shared.</para>
+ shared.
+ </para>
</listitem>
<listitem>
@@ -582,9 +703,22 @@
write-aside cache (i.e. one that is used to cache data that can also
be found in a persistent store, e.g. a database), whether or not
in-memory state should be transferred depends on whether or not a
- "hot" cache is desired.</para>
+ "hot" cache is desired.
+ </para>
</listitem>
</orderedlist>
</section>
+ <section>
+ <title>Configuring State Transfer</title>
+ <para>
+ To ensure state transfer behaves as expected, it is important that all nodes in the cluster are configured
+ with
+ the same settings for persistent and transient state. This is because byte array based transfers, when
+ requested,
+ rely only on the requester's configuration while stream based transfers rely on both the requester and
+ sender's
+ configuration, and this is expected to be identical.
+ </para>
+ </section>
</section>
</chapter>
\ No newline at end of file
More information about the jboss-cvs-commits
mailing list