[jboss-cvs] JBossAS SVN: r98072 - projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Mon Dec 21 02:24:38 EST 2009
Author: laubai
Date: 2009-12-21 02:24:38 -0500 (Mon, 21 Dec 2009)
New Revision: 98072
Modified:
projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Cache.xml
Log:
Minor edits to Cache chapter of Admin and Config Guide for 5.0.
Modified: projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Cache.xml
===================================================================
--- projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Cache.xml 2009-12-21 07:01:45 UTC (rev 98071)
+++ projects/docs/enterprise/EWP_5.0/Administration_And_Configuration_Guide/en-US/Cache.xml 2009-12-21 07:24:38 UTC (rev 98072)
@@ -7,9 +7,9 @@
<section><title>What is JBoss Cache?</title>
<para>
<indexterm><primary>JBoss Cache</primary><secondary>about</secondary></indexterm>
- JBoss Cache is a tree-structured, clustered, transactional cache. It is the backbone for many fundamental JBoss Enterprise Application Platform clustering services, including - in certain versions - clustering JNDI, HTTP and EJB sessions. </para>
+ JBoss Cache is a tree-structured, clustered, transactional cache. It is the backbone for many fundamental JBoss Enterprise Web Platform clustering services, including — in certain versions — clustering JNDI, HTTP and EJB sessions. </para>
- <para>JBoss Cache can also be used as a standalone transactional and clustered caching library or even an object oriented data store. It can even be embedded in other enterprise Java frameworks and application servers such as BEA WebLogic or IBM WebSphere, Tomcat, Spring, Hibernate, and many others. It is also very commonly used directly by standalone Java applications that do not run from within an application server, to maintain clustered state. </para>
+ <para>JBoss Cache can also be used as a standalone transactional and clustered caching library or even an object oriented data store. <!--It can even be embedded in other enterprise Java frameworks and application servers such as BEA WebLogic or IBM WebSphere, Tomcat, Spring, Hibernate, and many others.--> It is also very commonly used directly by standalone Java applications that do not run from within an application server, to maintain clustered state. </para>
</section>
<section>
<title>And what is Pojo Cache?</title>
@@ -24,14 +24,14 @@
<para>fine grained replication, where only modified object fields are replicated. </para>
</listitem>
<listitem>
- <para>"API-less" clustering model where pojos are simply annotated as being clustered. </para>
+ <para>"API-less" clustering model where POJOs are simply annotated as being clustered. </para>
</listitem>
</orderedlist>
<para>Pojo Cache has a complete and separate set of documentation, including a user guide, FAQ and tutorial and as such, Pojo Cache is not discussed further in this book. </para>
- <para>Pojo Cache deployment in the JBoss Enterprise Application Platform5 is discussed more in <xref linkend="pojocachedeployment"/></para>
+ <para>Pojo Cache deployment in the JBoss Enterprise Web Platform 5 is discussed further in <xref linkend="pojocachedeployment"/></para>
</section>
<section><title>Summary of Features</title>
- <para>JBoss Cache offers a simple and straightforward API, where data (simple Java objects) can be placed in the cache and, based on configuration options selected, this data may be one or all of: </para>
+ <para>JBoss Cache offers a simple and straightforward API, where data (simple Java objects) placed in the cache can be acted on in one or all of the following ways, depending on selected configuration options: </para>
<orderedlist>
<listitem>
<para>replicated to some or all cache instances in a cluster. </para>
@@ -46,19 +46,19 @@
<para>In addition, JBoss Cache offers a rich set of enterprise-class features: </para>
<orderedlist>
<listitem>
- <para>being able to participate in JTA transactions (works with Java EE compliant TransactionManagers). </para>
+ <para>being able to participate in JTA transactions (works with Java EE compliant <classname>TransactionManager</classname>s). </para>
</listitem>
<listitem>
- <para>attach to JMX servers and provide runtime statistics on the state of the cache. </para>
+ <para>attach to JMX servers and provide runtime statistics on the state of the cache.</para>
</listitem>
<listitem>
<para>allow client code to attach listeners and receive notifications on cache events. </para>
</listitem>
</orderedlist>
- <para>A cache is organised as a tree, with a single root. Each node in the tree essentially contains a Map, which acts as a store for key/value pairs. The only requirement placed on objects that are cached is that they implement java.io.Serializable . Note that this requirement does not exist for Pojo Cache. </para>
+ <para>A cache is organised as a tree with a single root. Each node in the tree contains a <classname>Map</classname>, which acts as a store for key/value pairs. The only requirement placed on objects that are cached is that they implement <classname>java.io.Serializable</classname>. Note that this requirement does not exist for Pojo Cache. </para>
<para>JBoss Cache can be either local or replicated. Local trees exist only inside the JVM in which they are created, whereas replicated trees propagate any changes to some or all other trees in the same cluster. A cluster may span different hosts on a network or just different JVMs on a single host. </para>
- <para>When a change is made to an object in the cache and that change is done in the context of a transaction, the replication of changes is deferred until the transaction commits successfully. All modifications are kept in a list associated with the transaction for the caller. When the transaction commits, we replicate the changes. Otherwise, (on a rollback) we simply undo the changes locally resulting in zero network traffic and overhead. For example, if a caller makes 100 modifications and then rolls back the transaction, we will not replicate anything, resulting in no network traffic. </para>
- <para>If a caller has no transaction associated with it (and isolation level is not NONE - more about this later), we will replicate right after each modification, e.g. in the above case we would send 100 messages, plus an additional message for the rollback. In this sense, running without a transaction can be thought of as analogous as running with auto-commit switched on in JDBC terminology, where each operation is committed automatically. </para>
+ <para>When a change is made to an object in the cache and that change is performed in the context of a transaction, the replication of changes is deferred until the transaction commits successfully. All modifications are kept in a list associated with the transaction for the caller. When the transaction commits, we replicate the changes. Otherwise, on a rollback, we simply undo the changes locally, resulting in zero network traffic and overhead. For example, if a caller makes 100 modifications and then rolls back the transaction, we will not replicate anything, resulting in no network traffic. </para>
+ <para>If a caller has no transaction associated with it (and its isolation level is not <literal>NONE</literal> — more about this later), we will replicate immediately after each modification. In the above case we would send 100 messages, plus an additional message for the rollback. In this sense, running without a transaction can be thought of as analogous to running with auto-commit switched on in JDBC terminology, where each operation is committed automatically. </para>
<para>JBoss Cache works out of the box with most popular transaction managers, and even provides an API where custom transaction manager lookups can be written. </para>
<para>The cache is also completely thread-safe. It uses a pessimistic locking scheme for nodes in the tree by default, with an optimistic locking scheme as a configurable option. With pessimistic locking, the degree of concurrency can be tuned using a number of isolation levels, corresponding to database-style transaction isolation levels, i.e., SERIALIZABLE, REPEATABLE_READ, READ_COMMITTED, READ_UNCOMMITTED and NONE. Concurrency, locking and isolation levels will be discussed later. </para>
</section>
@@ -67,17 +67,17 @@
<section>
<title>Running JBoss Cache in the JBoss Application server</title>
<para>
- <indexterm><primary>JBoss Enterprise Application Platform</primary><secondary>running JBoss Cache with JBoss Enterprise Application Platform</secondary></indexterm>
+ <indexterm><primary>JBoss Enterprise Web Platform</primary><secondary>running JBoss Cache with JBoss Enterprise Web Platform</secondary></indexterm>
JBoss Cache uses JGroups as a transport layer. More information on JGroups can be found on <xref linkend="jgroups"/>
</para>
- <!--<para>The following is the JBoss Cache JGroups and JBoss Enterprise Application Platform compatibility matrix.</para>
+ <!--<para>The following is the JBoss Cache JGroups and JBoss Enterprise Web Platform compatibility matrix.</para>
<para>
- <table frame="all"><title>JBoss Enterprise Application Platform + JBoss Cache</title>
+ <table frame="all"><title>JBoss Enterprise Web Platform + JBoss Cache</title>
<tgroup cols="3"><tbody>
<row>
<entry>
- <para>JBoss Enterprise Application Platform </para>
+ <para>JBoss Enterprise Web Platform </para>
</entry>
<entry>
<para>Ships with JBoss Cache </para>
@@ -199,18 +199,18 @@
</entry>
</row></tbody></tgroup>
</table>
-<note><title></title><para>For JBoss Enterprise Application Platform 4.0.3SP1 (and earlier) to run with JBoss Cache 1.4.0.x you need to add jboss-serialization.jar to JBOSS_HOME/server/all/lib </para></note>
+<note><title></title><para>For JBoss Enterprise Web Platform 4.0.3SP1 (and earlier) to run with JBoss Cache 1.4.0.x you need to add jboss-serialization.jar to JBOSS_HOME/server/all/lib </para></note>
-<note><title></title><para>Upgrading to these JBoss Cache versions within JBoss Enterprise Application Platform 4.0.x requires JGroups to be upgraded to 2.2.9 or higher</para></note>-->
+<note><title></title><para>Upgrading to these JBoss Cache versions within JBoss Enterprise Web Platform 4.0.x requires JGroups to be upgraded to 2.2.9 or higher</para></note>-->
<para>
<!--
- <table frame="all"><title>JBoss Enterprise Application Platform + Jgroups compatibility matrix</title>
+ <table frame="all"><title>JBoss Enterprise Web Platform + Jgroups compatibility matrix</title>
<tgroup cols="3"><tbody>
<row>
<entry>
- <para>JBoss Enterprise Application Platform </para>
+ <para>JBoss Enterprise Web Platform </para>
</entry>
<entry>
<para>Ships with JGroups </para>
@@ -584,11 +584,11 @@
</table>-->
</para>
-<para>In the JBoss Enterprise Application Platform 5, JBoss cache runs in the <emphasis>all</emphasis> configuration of the Enterprise Application Platform (for instance, <JBOSS_HOME>/server/all). All you need to do is start the server with this configuration.
+<para>In the JBoss Enterprise Web Platform 5, JBoss cache runs in the <emphasis>all</emphasis> configuration of the Enterprise Web Platform (for instance, <JBOSS_HOME>/server/all). All you need to do is start the server with this configuration.
<screen><command><JBOSS_HOME>/bin/./run.sh -c all</command></screen>
All required jars will be on the classpath. Otherwise, you will need to ensure jbosscache.jar and jgroups-all.jar are on the classpath. You may need to add other jars if you're using things like <filename>JdbmCacheLoader</filename>. The simplest way to do this is to copy the jars from the JBoss Cache distribution's <filename>lib</filename> directory to the server configurations <emphasis>all</emphasis> <filename>lib</filename> directory. You could also package the jars with the configuration file in Service Archive (.sar) file or an EAR. </para>
- <!--<para>It is possible to deploy a JBoss Cache 2.0 instance in JBoss Enterprise Application Platform 4.x (at least in 4.2.0.GA; other AS releases are completely untested). However, the significant API changes between the JBoss Cache 2.x and 1.x releases mean none of the standard AS 4.x clustering services (e.g. http session replication) that rely on JBoss Cache will work with JBoss Cache 2.x. Also, be aware that usage of JBoss Cache 2.x in AS 4.x is not something the JBoss Cache developers are making any significant effort to test, so be sure to test your application well (which of course you're doing anyway.) </para>-->
+ <!--<para>It is possible to deploy a JBoss Cache 2.0 instance in JBoss Enterprise Web Platform 4.x (at least in 4.2.0.GA; other AS releases are completely untested). However, the significant API changes between the JBoss Cache 2.x and 1.x releases mean none of the standard AS 4.x clustering services (e.g. http session replication) that rely on JBoss Cache will work with JBoss Cache 2.x. Also, be aware that usage of JBoss Cache 2.x in AS 4.x is not something the JBoss Cache developers are making any significant effort to test, so be sure to test your application well (which of course you're doing anyway.) </para>-->
<para>Note in the <ulink url="http://labs.jboss.com/file-access/default/members/jbosscache/freezone/docs/2.1.0.GA/userguide_en/html_single/index.html#sample_xml_file">http://labs.jboss.com/file-access/default/members/jbosscache/freezone/docs/2.1.0.GA/userguide_en/html_single/index.html#sample_xml_file</ulink> the value of the mbean element's code attribute: org.jboss.cache.jmx.CacheJmxWrapper . This is the class JBoss Cache uses to handle JMX integration; the Cache itself does not expose an MBean interface. See the <ulink url="http://labs.jboss.com/file-access/default/members/jbosscache/freezone/docs/2.1.0.GA/userguide_en/html_single/index.html#jmx.mbeans">JBoss Cache MBeans section</ulink> for more on the CacheJmxWrapper . </para>
<para>Once your cache is deployed, in order to use it with an in-VM client such as a servlet, a JMX proxy can be used to get a reference to the cache: </para>
<para>
@@ -619,15 +619,15 @@
Simply instantiate a PojoCacheFactory and invoke one of the overloaded createCache methods shown in the API Overview.
</para>
</section>
- <section><title>JMX-Based Deployment in JBoss Enterprise Application Platform (JBoss Enterprise Application Platform 5.x and 4.x)</title>
+ <section><title>JMX-Based Deployment in JBoss Enterprise Web Platform (JBoss Enterprise Web Platform 5.x and 4.x)</title>
<para>
- If PojoCache is run in JBoss Enterprise Application Platform then your cache can be deployed as an MBean simply by copying a standard cache configuration file to the server's deploy directory. The standard format of PojoCache's standard XML configuration file (as shown in the Appendix) is the same as a JBoss Enterprise Application Platform MBean deployment descriptor, so the Enterprise Application Platform's SAR Deployer has no trouble handling it. Also, you don't have to place the configuration file directly in deploy; you can package it along with other services or JEE components in a SAR or EAR.
+ If PojoCache is run in JBoss Enterprise Web Platform then your cache can be deployed as an MBean simply by copying a standard cache configuration file to the server's deploy directory. The standard format of PojoCache's standard XML configuration file (as shown in the Appendix) is the same as a JBoss Enterprise Web Platform MBean deployment descriptor, so the Enterprise Web Platform's SAR Deployer has no trouble handling it. Also, you don't have to place the configuration file directly in deploy; you can package it along with other services or JEE components in a SAR or EAR.
</para>
<para>
- In Enterprise Application Platform 5, if you're using a server config based on the standard all config, then that's all you need to do; all required jars will be on the classpath. Otherwise, you will need to ensure pojocache.jar, jbosscache.jar and jgroups-all.jar are on the classpath. You may need to add other jars if you're using things like JdbmCacheLoader. The simplest way to do this is to copy the jars from the PojoCache distribution's lib directory to the server config's lib directory. You could also package the jars with the configuration file in Service Archive (.sar) file or an EAR.
+ In Enterprise Web Platform 5, if you're using a server config based on the standard all config, then that's all you need to do; all required jars will be on the classpath. Otherwise, you will need to ensure pojocache.jar, jbosscache.jar and jgroups-all.jar are on the classpath. You may need to add other jars if you're using things like JdbmCacheLoader. The simplest way to do this is to copy the jars from the PojoCache distribution's lib directory to the server config's lib directory. You could also package the jars with the configuration file in Service Archive (.sar) file or an EAR.
</para>
<!-- <para>
- It is possible, to deploy a POJO Cache 2.0 instance in JBoss Enterprise Application Platform 4.x However, the significant API changes between the 2.x and 1.x releases mean none of the standard Enterprise Application Platform 4.x clustering services (for example, http session replication) that rely on the 1.x API will work with PojoCache 2.x. Also, be aware that usage of PojoCache 2.x in Enterprise Application Platform 4.x is not something the cache developers are making any significant effort to test, so be sure to test your application well (which of course you're doing anyway.)
+ It is possible, to deploy a POJO Cache 2.0 instance in JBoss Enterprise Web Platform 4.x However, the significant API changes between the 2.x and 1.x releases mean none of the standard Enterprise Web Platform 4.x clustering services (for example, http session replication) that rely on the 1.x API will work with PojoCache 2.x. Also, be aware that usage of PojoCache 2.x in Enterprise Web Platform 4.x is not something the cache developers are making any significant effort to test, so be sure to test your application well (which of course you're doing anyway.)
</para> -->
<para>
Note in the example the value of the mbean element's code attribute: org.jboss.cache.pojo.jmx.PojoCacheJmxWrapper. This is the class JBoss Cache uses to handle JMX integration; the PojoCache itself does not expose an MBean interface. See the JBoss Cache MBeans section for more on the PojoCacheJmxWrapper.
@@ -654,18 +654,18 @@
Once the proxy to the PojoCacheJmxWrapper is obtained, the getPojoCache() will return a reference to the PojoCache itself.
</para>
</section>
-<section><title>Via JBoss Microcontainer (JBoss Enterprise Application Platform 5.x)</title>
+<section><title>Via JBoss Microcontainer (JBoss Enterprise Web Platform 5.x)</title>
<para>
- Beginning with Enterprise Application Platform 5, JBoss Enterprise Application Platform also supports deployment of POJO services via deployment of a file whose name ends with -beans.xml. A POJO service is one whose implementation is via a "Plain Old Java Object", meaning a simple java bean that isn't required to implement any special interfaces or extend any particular superclass. A PojoCache is a POJO service, and all the components in a Configuration are also POJOS, so deploying a cache in this way is a natural step.
+ Beginning with Enterprise Web Platform 5, JBoss Enterprise Web Platform also supports deployment of POJO services via deployment of a file whose name ends with -beans.xml. A POJO service is one whose implementation is via a "Plain Old Java Object", meaning a simple java bean that isn't required to implement any special interfaces or extend any particular superclass. A PojoCache is a POJO service, and all the components in a Configuration are also POJOS, so deploying a cache in this way is a natural step.
</para>
<para>
- Deployment of the cache is done using the JBoss Microcontainer that forms the core of JBoss Enterprise Application Platform. JBoss Microcontainer is a sophisticated IOC framework (similar to Spring). A -beans.xml file is basically a descriptor that tells the IOC framework how to assemble the various beans that make up a POJO service.
+ Deployment of the cache is done using the JBoss Microcontainer that forms the core of JBoss Enterprise Web Platform. JBoss Microcontainer is a sophisticated IOC framework (similar to Spring). A -beans.xml file is basically a descriptor that tells the IOC framework how to assemble the various beans that make up a POJO service.
</para>
<para>
The rules for how to deploy the file, how to package it, how to ensure the required jars are on the classpath, etc. are the same as for a JMX-based deployment.
</para>
<para>
- Following is an abbreviated example -beans.xml file. The details of building up the Configuration are omitted; see the "Deploying JBoss Cache" chapter in the JBoss Cache User Guide for a more complete example. If you look in the <filename>server/all/deploy</filename> directory of an Enterprise Application Platform 5 installation, you can find several more examples.
+ Following is an abbreviated example -beans.xml file. The details of building up the Configuration are omitted; see the "Deploying JBoss Cache" chapter in the JBoss Cache User Guide for a more complete example. If you look in the <filename>server/all/deploy</filename> directory of an Enterprise Web Platform 5 installation, you can find several more examples.
</para>
<programlisting role="XML"><?xml version="1.0" encoding="UTF-8"?>
More information about the jboss-cvs-commits
mailing list