Author: laubai Date: 2009-12-10 00:35:51 -0500 (Thu, 10 Dec 2009) New Revision: 8318 Modified: enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/architecture.xml enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/cache_loaders.xml enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/eviction_policies.xml enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/replication.xml enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/transactions.xml Log: Added second part of changes for JBPAPP-2964. Modified: enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/architecture.xml =================================================================== --- enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/architecture.xml 2009-12-10 04:47:53 UTC (rev 8317) +++ enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/architecture.xml 2009-12-10 05:35:51 UTC (rev 8318) @@ -169,7 +169,7 @@ </para> <para> In addition to being visitable, commands are also replicable. The JBoss Cache marshallers know how to - efficiently marshall commands and invoke them on remote cache instances using an internal RPC mechanism + efficiently marshal commands and invoke them on remote cache instances using an internal RPC mechanism based on JGroups. </para> </section> @@ -184,13 +184,11 @@ which sits at the start of the interceptor chain. </para> <para> - <literal>InvocationContext</literal> - , as its name implies, holds contextual information associated with a single cache + <literal>InvocationContext</literal>, as its name implies, holds contextual information associated with a single cache method invocation. Contextual information includes associated <literal>javax.transaction.Transaction</literal> or - <literal>org.jboss.cache.transaction.GlobalTransaction</literal> - , + <literal>org.jboss.cache.transaction.GlobalTransaction</literal>, method invocation origin ( <literal>InvocationContext.isOriginLocal()</literal> ) as well as @@ -240,13 +238,11 @@ in delegating classes, such as <literal>SingletonStoreCacheLoader</literal> or - <literal>AsyncCacheLoader</literal> - , + <literal>AsyncCacheLoader</literal>, or may add the <literal>CacheLoader</literal> to a chain using the - <literal>ChainingCacheLoader</literal> - . + <literal>ChainingCacheLoader</literal>. </para> </section> Modified: enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/cache_loaders.xml =================================================================== --- enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/cache_loaders.xml 2009-12-10 04:47:53 UTC (rev 8317) +++ enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/cache_loaders.xml 2009-12-10 05:35:51 UTC (rev 8318) @@ -141,7 +141,7 @@ a chain. The impact is that the cache will look at all of the cache loaders in the order they've been configured, until it finds a valid, non-null element of data. When performing writes, all cache loaders are - written to (except if the + written to, except if the <literal>ignoreModifications</literal> element has been set to <literal>true</literal> @@ -190,8 +190,7 @@ whereas a database implementation might define the database URL, name and password to establish a database connection. This configuration is passed to the cache loader implementation via - <literal>CacheLoader.setConfig(Properties)</literal> - . Note that + <literal>CacheLoader.setConfig(Properties)</literal>. Note that backspaces may have to be escaped. </para> @@ -243,22 +242,20 @@ <literal>async</literal> element defaults to - <literal>false</literal> - . + <literal>false</literal>. </para> - <para> - <emphasis role="bold">Note on using the - <literal>async</literal> - element: - </emphasis> - there is always the possibility of dirty reads since + <note> + <title>Using the <literal>async</literal> element</title> + </para> + There is always the possibility of dirty reads since all writes are performed asynchronously, and it is thus impossible to guarantee when (and even if) a write succeeds. This needs to be kept in mind when setting the <literal>async</literal> element to true. - </para> + </para> + </note> <para> <literal>ignoreModifications</literal> @@ -271,10 +268,8 @@ used by all servers in the network. This feature allows you to write to the 'local' file cache loader but not the shared - <literal>JDBCCacheLoader</literal> - . This property defaults to - <literal>false</literal> - , so writes are propagated to all cache loaders + <literal>JDBCCacheLoader</literal>. This property defaults to + <literal>false</literal>, so writes are propagated to all cache loaders configured. </para> @@ -284,8 +279,7 @@ (if <literal>ignoreModifications</literal> is - <literal>false</literal> - ) + <literal>false</literal>) when the cache loader starts up. </para> @@ -346,8 +340,7 @@ Default value for <literal>enabled</literal> is - <literal>false</literal> - . + <literal>false</literal>. </para> <para> @@ -357,10 +350,8 @@ <literal>class</literal> element that specifies the implementation class that provides the singleton store functionality. This class must extend - <literal>org.jboss.cache.loader.AbstractDelegatingCacheLoader</literal> - , and if absent, it defaults to - <literal>org.jboss.cache.loader.SingletonStoreCacheLoader</literal> - . + <literal>org.jboss.cache.loader.AbstractDelegatingCacheLoader</literal>, and if absent, it defaults to + <literal>org.jboss.cache.loader.SingletonStoreCacheLoader</literal>. </para> <para> @@ -395,8 +386,7 @@ <literal>true</literal> if each node's cache loader is configured with a different location. Default value is - <literal>true</literal> - . + <literal>true</literal>. </para> <para> @@ -412,13 +402,10 @@ if exceeded. Default value is 20000. </para> - <para> - <emphasis role="bold">Note on using the - <literal>singletonStore</literal> - element: - </emphasis> - setting - up a cache loader as a singleton and using cache passivation (via + <note> + <title>Using the <literal>singletonStore</literal> element</title> + <para> + Setting up a cache loader as a singleton and using cache passivation (via evictions) can lead to undesired effects. If a node is to be passivated as a result of an eviction, while the cluster is in the process of electing a new coordinator, the data will be lost. This is because no @@ -426,7 +413,8 @@ the cluster will store the passivated node. A new coordinator is elected in the cluster when either, the coordinator leaves the cluster, the coordinator crashes or stops responding. - </para> + </para> + </note> </section> </section> @@ -447,7 +435,7 @@ configuration element contains a <literal>location</literal> - property, which maps to a directory to be used as a persistent store. + property, which maps to a directory to be used as a persistent store (e.g., <literal>location=/tmp/myDataStore</literal> ). Used mainly for testing and not recommended for production use. @@ -455,8 +443,7 @@ <itemizedlist> <listitem> <para> - <literal>FileCacheLoader</literal> - , which is a simple filesystem-based implementation. By default, this cache + <literal>FileCacheLoader</literal>, which is a simple filesystem-based implementation. By default, this cache loader checks for any potential character portability issues in the location or tree node names, for example invalid characters, producing warning messages. These checks can be disabled adding @@ -503,19 +490,15 @@ <para> <literal>BdbjeCacheLoader</literal> , which is a cache loader implementation based on the Oracle/Sleepycat's - <ulink url="http://www.oracle.com/database/berkeley-db/index.html">... Java Edition - </ulink> - . + <ulink url="http://www.oracle.com/database/berkeley-db/index.html">... Java Edition</ulink>. </para> </listitem> <listitem> <para> - <literal>JdbmCacheLoader</literal> - , which is a cache loader + <literal>JdbmCacheLoader</literal>, which is a cache loader implementation based on the - <ulink url="http://jdbm.sourceforge.net/">JDBM engine</ulink> - , a fast and free alternative to + <ulink url="http://jdbm.sourceforge.net/">JDBM engine</ulink>, a fast and free alternative to BerkeleyDB. </para> </listitem> @@ -524,7 +507,7 @@ <para>Note that the BerkeleyDB implementation is much more efficient than the filesystem-based implementation, and provides transactional guarantees, but requires a commercial license if distributed with an - application (see http://www.oracle.com/database/berkeley-db/index.html for + application (see <ulink url="http://www.oracle.com/database/berkeley-db/index.html">... for details). </para> @@ -542,16 +525,14 @@ </listitem> <listitem> <para> - <literal>ClusteredCacheLoader</literal> - , which allows querying + <literal>ClusteredCacheLoader</literal>, which allows querying of other caches in the same cluster for in-memory data via the same clustering protocols used to replicate data. Writes are <emphasis>not</emphasis> 'stored' though, as replication would take care of any updates needed. You need to specify a property called - <literal>timeout</literal> - , a long value telling the cache + <literal>timeout</literal>, a long value telling the cache loader how many milliseconds to wait for responses from the cluster before assuming a null value. For example, <literal>timeout = 3000</literal> @@ -568,8 +549,7 @@ <para>JBossCache is distributed with a JDBC-based cache loader implementation that stores/loads nodes' state into a relational database. The implementing class is - <literal>org.jboss.cache.loader.JDBCCacheLoader</literal> - . + <literal>org.jboss.cache.loader.JDBCCacheLoader</literal>. </para> <para>The current implementation uses just one table. Each row in the table @@ -594,7 +574,10 @@ <para> <literal>Fqn</literal>s are stored as strings. Node content is stored as a BLOB. - <emphasis>WARNING:</emphasis> + </para> + + <warning> + <para> JBoss Cache does not impose any limitations on the types of objects used in <literal>Fqn</literal> @@ -602,8 +585,7 @@ cache loader requires <literal>Fqn</literal> to contain only objects of type - <literal>java.lang.String</literal> - . Another limitation for + <literal>java.lang.String</literal>. Another limitation for <literal>Fqn</literal> is its length. Since @@ -612,7 +594,8 @@ <literal>VARCHAR</literal> which can store text values up to some maximum length determined by the database in use. - </para> + </para> + </warning> <para>See <ulink url="http://www.jboss.org/community/docs/DOC-10864">this wiki page</ulink> @@ -832,7 +815,7 @@ </loaders> ]]></programlisting> - <para>Cconfiguration example for a cache loader using c3p0 JDBC connection pooling:</para> + <para>Configuration example for a cache loader using c3p0 JDBC connection pooling:</para> <programlisting role="XML"><![CDATA[ <loaders passivation="false" shared="false"> @@ -982,7 +965,7 @@ <listitem><para> <literal>cache.s3.secure</literal> - - The default is<literal>false</literal>: + The default is <literal>false</literal>: Traffic is sent unencrypted over the public Internet. Set to <literal>true</literal> @@ -996,22 +979,22 @@ Name of the bucket to store data. For different caches using the same access key, use a different bucket name. Read the S3 documentation on the definition of a bucket. - The default value is<literal>jboss-cache</literal>.</para> + The default value is <literal>jboss-cache</literal>.</para> </listitem> <listitem><para> <literal>cache.s3.callingFormat</literal> - - One of<literal>PATH</literal>,<literal>SUBDOMAIN</literal>, or + One of<literal>PATH</literal>, <literal>SUBDOMAIN</literal>, or <literal>VANITY</literal>. Read the S3 documentation on the use of calling domains. - The default value is<literal>SUBDOMAIN</literal>.</para> + The default value is <literal>SUBDOMAIN</literal>.</para> </listitem> <listitem><para> <literal>cache.s3.optimize</literal> - - The default is<literal>false</literal>. + The default is <literal>false</literal>. If true, <literal>put(Map)</literal> operations @@ -1023,7 +1006,7 @@ <listitem><para> <literal>cache.s3.parentCache</literal> - - The default is<literal>true</literal>. + The default is <literal>true</literal>. Set this value to <literal>false</literal> if you are using multiple caches @@ -1342,11 +1325,11 @@ the FileCacheLoader), or a shared database. Because both nodes access the same store, they don't necessarily need state transfer on startup. - <footnote> + <note> <para>Of course they can enable state transfer, if they want to have a warm or hot cache after startup. </para> - </footnote> + </note> Rather, the <literal>FetchInMemoryState</literal> attribute could be set to false, resulting in a 'cold' cache, that @@ -1427,7 +1410,7 @@ cache are (a) replicated across the cluster and (b) persisted using the cache loader. This means that all datastores have exactly the same state. When replicating changes synchronously and in a transaction, - the two phase commit protocol takes care that all modifications are + the two-phase commit protocol takes care that all modifications are replicated and persisted in each datastore, or none is replicated and persisted (atomic updates). </para> Modified: enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/eviction_policies.xml =================================================================== --- enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/eviction_policies.xml 2009-12-10 04:47:53 UTC (rev 8317) +++ enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/eviction_policies.xml 2009-12-10 05:35:51 UTC (rev 8318) @@ -161,12 +161,14 @@ <literal>/a</literal> and<literal>/a/b</literal>. </para> - <para> - N.B. when adding attributes to a resident node, e.g. - <literal>cache.put("/a", "k", "v")</literal> - in the above example, it would make sense to mark the nodes - as non-resident again and let them be considered for eviction.. - </para> + <note> + <para> + When adding attributes to a resident node, e.g. + <literal>cache.put("/a", "k", "v")</literal> + in the above example, it would make sense to mark the nodes + as non-resident again and let them be considered for eviction. + </para> + </note> </section> </section> Modified: enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/replication.xml =================================================================== --- enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/replication.xml 2009-12-10 04:47:53 UTC (rev 8317) +++ enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/replication.xml 2009-12-10 05:35:51 UTC (rev 8318) @@ -75,9 +75,8 @@ asynchronous or synchronous mode, JBoss Cache will use either a single phase or <ulink - url="http://en.wikipedia.org/wiki/Two-phase_commit_protocol">... phase - commit - </ulink> + url="http://en.wikipedia.org/wiki/Two-phase_commit_protocol">... + commit</ulink> protocol, respectively. </para> @@ -179,8 +178,7 @@ which contains the logic used to select buddies in a network. JBoss Cache currently ships with a single implementation, - <literal>NextMemberBuddyLocator</literal> - , + <literal>NextMemberBuddyLocator</literal>, which is used as a default if no implementation is provided. The <literal>NextMemberBuddyLocator</literal> selects the next member in @@ -226,8 +224,7 @@ <title>BuddyPools</title> <para>Also known as - <emphasis>replication groups</emphasis> - , a buddy + <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, @@ -489,8 +486,7 @@ <literal>InactiveOnStartup</literal> property is - <literal>true</literal> - . This property is used in + <literal>true</literal>. This property is used in conjunction with region-based marshalling. </para> </listitem> @@ -511,8 +507,7 @@ </para> <para>After registration, the application calls - <literal>cache.getRegion(fqn, true).activate()</literal> - , + <literal>cache.getRegion(fqn, true).activate()</literal>, which initiates a partial state transfer of the relevant subtree's state. The request is first made to the oldest cache instance in the cluster. However, if that instance responds with no state, it is then @@ -523,8 +518,7 @@ <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>true</literal>. This suppresses initial state transfer, which would fail due to the inability to deserialize the transferred state. </para> @@ -547,10 +541,8 @@ the <literal>InactiveOnStartup</literal> property is set to - <literal>false</literal> - . If it is - <literal>true</literal> - , state + <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> @@ -586,8 +578,7 @@ <para>"In-memory" state transfer is enabled by setting the cache's <literal>FetchInMemoryState</literal> configuration attribute to - <literal>true</literal> - . + <literal>true</literal>. </para> </listitem> @@ -603,8 +594,7 @@ loader's <literal>fetchPersistentState</literal> attribute to - <literal>true</literal> - . If multiple cache loaders are configured + <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> @@ -616,8 +606,7 @@ cache loader has <literal>fetchPersistentState</literal> set to - <literal>true</literal> - . + <literal>true</literal>. </para> </listitem> </orderedlist> Modified: enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/transactions.xml =================================================================== --- enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/transactions.xml 2009-12-10 04:47:53 UTC (rev 8317) +++ enterprise-docs/tags/JBoss_EWP_5_0_0/Cache_User_Guide/en-US/transactions.xml 2009-12-10 05:35:51 UTC (rev 8318) @@ -230,7 +230,7 @@ <literal>TransactionManager</literal>. </para> - <para>When the transaction commits, we initiate either a one- two-phase commit + <para>When the transaction commits, we initiate either a one-phase or two-phase commit protocol. See <xref linkend="replication.tx" /> for details. </para>