[jboss-cvs] JBossAS SVN: r94135 - projects/docs/community/5/Clustering_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Tue Sep 29 23:06:06 EDT 2009
Author: bstansberry at jboss.com
Date: 2009-09-29 23:06:03 -0400 (Tue, 29 Sep 2009)
New Revision: 94135
Modified:
projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Entity_EJBs.xml
Log:
Make stuff fit on PDF
Modified: projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Entity_EJBs.xml
===================================================================
--- projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Entity_EJBs.xml 2009-09-30 01:31:23 UTC (rev 94134)
+++ projects/docs/community/5/Clustering_Guide/en-US/Clustering_Guide_Entity_EJBs.xml 2009-09-30 03:06:03 UTC (rev 94135)
@@ -55,27 +55,26 @@
<para>
e.g.
</para>
- <programlisting><![CDATA[
-<?xml version="1.0" encoding="UTF-8"?>
-<persistence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns="http://java.sun.com/xml/ns/persistence"
- xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd">
+ <programlisting><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+<persistence xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns="http://java.sun.com/xml/ns/persistence"
<persistence-unit name="tempdb" transaction-type="JTA">
<jta-data-source>java:/DefaultDS</jta-data-source>
<properties>
<property name="hibernate.cache.use_second_level_cache" value="true"/>
<property name="hibernate.cache.use_query_cache" value="true"/>
- <property name="hibernate.cache.region.factory_class" value="org.hibernate.cache.jbc2.JndiMultiplexedJBossCacheRegionFactory"/>
+ <property name="hibernate.cache.region.factory_class"
+ value="org.hibernate.cache.jbc2.JndiMultiplexedJBossCacheRegionFactory"/>
<!-- region factory specific properties -->
<property name="hibernate.cache.region.jbc2.cachefactory" value="java:CacheManager"/>
<property name="hibernate.cache.region.jbc2.cfg.entity" value="mvcc-entity"/>
<property name="hibernate.cache.region.jbc2.cfg.collection" value="mvcc-entity"/>
</properties>
</persistence-unit>
-</persistence>
-]]></programlisting>
+</persistence>]]></programlisting>
<variablelist>
<varlistentry>
- <term>hibernate.cache.use_second_level_cache</term>
+ <term><emphasis role="bold">hibernate.cache.use_second_level_cache</emphasis></term>
<listitem>
<para>
Enables second-level caching of entities and collections.
@@ -83,7 +82,7 @@
</listitem>
</varlistentry>
<varlistentry>
- <term>hibernate.cache.use_query_cache</term>
+ <term><emphasis role="bold">hibernate.cache.use_query_cache</emphasis></term>
<listitem>
<para>
Enables second-level caching of queries.
@@ -91,7 +90,15 @@
</listitem>
</varlistentry>
<varlistentry>
- <term>hibernate.cache.region.factory_class</term>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.query.localonly</emphasis></term>
+ <listitem><para>If you have enabled caching of query results, set to
+ <literal>true</literal> to tell Hibernate you want to suppress costly
+ replication of those results around the cluster. No need to set this
+ property if you want query results replicated.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.factory_class</emphasis></term>
<listitem>
<para>
Defines the <literal>RegionFactory</literal> implementation that dictates region-specific caching behavior.
@@ -103,202 +110,198 @@
<para>Hibernate ships with 2 shared region factory implementations:</para>
<variablelist>
<varlistentry>
- <term>org.hibernate.cache.jbc2.SharedJBossCacheRegionFactory</term>
+ <term><emphasis role="bold">org.hibernate.cache.jbc2.SharedJBossCacheRegionFactory</emphasis></term>
<listitem>
<para>
Uses a single JBoss Cache configuration, from a newly instantiated CacheManager, for all cache regions.
</para>
- <table frame="all">
- <title>Additional properties for SharedJBossCacheRegionFactory</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Default</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>hibernate.cache.region.jbc2.cfg.shared</entry>
- <entry>treecache.xml</entry>
- <entry>The classpath or filesystem resource containing the JBoss Cache configuration settings.</entry>
- </row>
- <row>
- <entry>hibernate.cache.region.jbc2.cfg.jgroups.stacks</entry>
- <entry>org/hibernate/cache/jbc2/builder/jgroups-stacks.xml</entry>
- <entry>The classpath or filesystem resource containing the JGroups protocol stack configurations.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
</listitem>
</varlistentry>
<varlistentry>
- <term>org.hibernate.cache.jbc2.JndiSharedJBossCacheRegionFactory</term>
+ <term><emphasis role="bold">org.hibernate.cache.jbc2.JndiSharedJBossCacheRegionFactory</emphasis></term>
<listitem>
<para>
Uses a single JBoss Cache configuration, from an existing CacheManager bound to JNDI, for all cache regions.
</para>
- <table frame="all">
- <title>Additional properties for JndiSharedJBossCacheRegionFactory</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Default</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>hibernate.cache.region.jbc2.cfg.shared</entry>
- <entry><emphasis>Required</emphasis></entry>
- <entry>JNDI name to which the shared <literal>Cache</literal> instance is bound.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
</listitem>
</varlistentry>
</variablelist>
<para>
A multiplexed region factory uses separate Cache instances, using optimized configurations for each cache region.
</para>
- <table frame="all">
- <title>Common properties for multiplexed region factory implementations</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Default</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>hibernate.cache.region.jbc2.cfg.entity</entry>
- <entry>optimistic-entity</entry>
- <entry>
- The JBoss Cache configuration used for the entity cache region.
- Alternative configurations: mvcc-entity, pessimistic-entity, mvcc-entity-repeatable, optimistic-entity-repeatable, pessimistic-entity-repeatable
- </entry>
- </row>
- <row>
- <entry>hibernate.cache.region.jbc2.cfg.collection</entry>
- <entry>optimistic-entity</entry>
- <entry>
- The JBoss Cache configuration used for the collection cache region.
- The collection cache region typically uses the same configuration as the entity cache region.
- </entry>
- </row>
- <row>
- <entry>hibernate.cache.region.jbc2.cfg.query</entry>
- <entry>local-query</entry>
- <entry>
- The JBoss Cache configuration used for the query cache region.
- By default, cached query results are not replicated.
- Alternative configurations: replicated-query
- </entry>
- </row>
- <row>
- <entry>hibernate.cache.region.jbc2.cfg.ts</entry>
- <entry>timestamps-cache</entry>
- <entry>
- The JBoss Cache configuration used for the timestamp cache region.
- If query caching is used, the corresponding timestamp cache must be replicating, even if the query cache is non-replicating.
- The timestamp cache region must never share the same cache as the query cache.
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- <para>Hibernate ships with 2 shared region factory implementations:</para>
+ <para>Hibernate ships with 2 multiplexed region factory implementations:</para>
<variablelist>
<varlistentry>
- <term>org.hibernate.cache.jbc2.MultiplexedJBossCacheRegionFactory</term>
+ <term><emphasis role="bold">org.hibernate.cache.jbc2.MultiplexedJBossCacheRegionFactory</emphasis></term>
<listitem>
<para>
Uses separate JBoss Cache configurations, from a newly instantiated CacheManager, per cache region.
</para>
- <table frame="all">
- <title>Additional properties for MultiplexedJBossCacheRegionFactory</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Default</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>hibernate.cache.region.jbc2.configs</entry>
- <entry>org/hibernate/cache/jbc2/builder/jbc2-configs.xml</entry>
- <entry>The classpath or filesystem resource containing the JBoss Cache configuration settings.</entry>
- </row>
- <row>
- <entry>hibernate.cache.region.jbc2.cfg.jgroups.stacks</entry>
- <entry>org/hibernate/cache/jbc2/builder/jgroups-stacks.xml</entry>
- <entry>The classpath or filesystem resource containing the JGroups protocol stack configurations.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
</listitem>
</varlistentry>
<varlistentry>
- <term>org.hibernate.cache.jbc2.JndiMultiplexedJBossCacheRegionFactory</term>
+ <term><emphasis role="bold">org.hibernate.cache.jbc2.JndiMultiplexedJBossCacheRegionFactory</emphasis></term>
<listitem>
<para>
Uses separate JBoss Cache configurations, from a JNDI-bound CacheManager, see <xref linkend="clustering-blocks-jbc-cachemanager"/>, per cache region.
</para>
- <table frame="all">
- <title>Additional properties for JndiMultiplexedJBossCacheRegionFactory</title>
- <tgroup cols="3">
- <thead>
- <row>
- <entry>Property</entry>
- <entry>Default</entry>
- <entry>Description</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>hibernate.cache.region.jbc2.cachefactory</entry>
- <entry><emphasis>Required</emphasis></entry>
- <entry>JNDI name to which the <literal>CacheManager</literal> instance is bound.</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
</listitem>
</varlistentry>
</variablelist>
</listitem>
</varlistentry>
</variablelist>
+
+ <note>
+ <title>What <literal>RegionFactory</literal> is best to use inside JBoss AS?</title>
+ <para>Use <literal>org.hibernate.cache.jbc2.JndiMultiplexedJBossCacheRegionFactory</literal>.
+ It integrates cleanly with the <literal>CacheManager</literal> service
+ (see <xref linkend="clustering-blocks-jbc-cachemanager"/> that is the source
+ of JBoss Cache instances for all of the standard JBoss AS clustered services.</para>
+ </note>
+
+ <para>Depending on what class you specify as your
+ <literal>hibernate.cache.region.factory_class</literal>, there are
+ other configuration properties available that are specific to that
+ <literal>RegionFactory</literal>:</para>
+
+ <section id="clustering-entity-30-cache-shared">
+ <title>Additional properties for SharedJBossCacheRegionFactory</title>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.shared</emphasis></term>
+ <listitem><para>The classpath or filesystem resource containing the JBoss Cache configuration settings. Default is <literal>treecache.xml</literal></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.jgroups.stacks</emphasis></term>
+ <listitem><para>The classpath or filesystem resource containing
+ the JGroups protocol stack configurations. Default is
+ <literal>org/hibernate/cache/jbc2/builder/jgroups-stacks.xml</literal>
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="clustering-entity-30-cache-jndishared">
+ <title>Additional properties for JndiSharedJBossCacheRegionFactory</title>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.shared</emphasis></term>
+ <listitem><para>JNDI name to which the shared <literal>Cache</literal> instance is bound. Configuring this property is required, as there is no default.</para></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="clustering-entity-30-cache-multiplexed">
+ <title>Additional properties for MultiplexedJBossCacheRegionFactory</title>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.configs</emphasis></term>
+ <listitem><para>The classpath or filesystem resource containing the JBoss Cache configuration settings.
+ Default is <literal>org/hibernate/cache/jbc2/builder/jbc2-configs.xml</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.jgroups.stacks</emphasis></term>
+ <listitem><para>The classpath or filesystem resource containing the JGroups protocol stack configurations.
+ Default is <literal>org/hibernate/cache/jbc2/builder/jgroups-stacks.xml</literal></para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.entity</emphasis></term>
+ <listitem><para>
+ The JBoss Cache configuration used for the entity cache region. Default is <literal>optimistic-entity</literal>.
+ Alternative configurations: mvcc-entity, pessimistic-entity, mvcc-entity-repeatable, optimistic-entity-repeatable, pessimistic-entity-repeatable.
+ See <xref linkend="clustering-blocks-jbc-cachemanager"/>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.collection</emphasis></term>
+ <listitem><para>
+ The JBoss Cache configuration used for the collection cache region.
+ The default behavior is for the collection cache to use the same configuration as the entity cache.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.query</emphasis></term>
+ <listitem><para>
+ The JBoss Cache configuration used for the query cache region.
+ The default value is <literal>local-query</literal>, which results in cached query results not being replicated.
+ Alternative configurations: replicated-query
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.ts</emphasis></term>
+ <listitem><para>
+ The JBoss Cache configuration used for the timestamp cache region.
+ If query caching is used, the corresponding timestamp cache must be replicating, even if the query cache is non-replicating.
+ The timestamp cache region must never share the same cache as the query cache.
+ Default value is <literal>timestamps-cache</literal>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="clustering-entity-30-cache-jndimultiplexed">
+ <title>Additional properties for JndiMultiplexedJBossCacheRegionFactory</title>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cachefactory</emphasis></term>
+ <listitem><para>JNDI name to which the <literal>CacheManager</literal> instance is bound.
+ Must be specified, as there is no default. Inside JBoss AS use <literal>java:CacheManager</literal>.</para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.entity</emphasis></term>
+ <listitem><para>
+ The JBoss Cache configuration used for the entity cache region. Default is <literal>optimistic-entity</literal>.
+ Alternative configurations: mvcc-entity, pessimistic-entity, mvcc-entity-repeatable, optimistic-entity-repeatable, pessimistic-entity-repeatable.
+ See <xref linkend="clustering-blocks-jbc-cachemanager"/>.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.collection</emphasis></term>
+ <listitem><para>
+ The JBoss Cache configuration used for the collection cache region.
+ The default behavior is for the collection cache to use the same configuration as the entity cache.
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.query</emphasis></term>
+ <listitem><para>
+ The JBoss Cache configuration used for the query cache region.
+ The default value is <literal>local-query</literal>, which results in cached query results not being replicated.
+ Alternative configurations: replicated-query
+ </para></listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis role="bold">hibernate.cache.region.jbc2.cfg.ts</emphasis></term>
+ <listitem><para>
+ The JBoss Cache configuration used for the timestamp cache region.
+ If query caching is used, the corresponding timestamp cache must be replicating, even if the query cache is non-replicating.
+ The timestamp cache region must never share the same cache as the query cache.
+ Default value is <literal>timestamps-cache</literal>.
+ </para></listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
<para>
Now, we have JBoss Cache configured to support distributed caching of EJB 3.0 entity beans.
We still have to configure individual entity beans to use the cache service.
</para>
</section>
<section id="clustering-entity-30-bean">
- <title>Configure the entity beans for cache</title>
+ <title>Configure the entity beans for caching</title>
<para>
Next we need to configure which entities to cache.
The default is to not cache anything, even with the settings shown above.
We use the <literal>@org.hibernate.annotations.Cache</literal> annotation to tag entity beans that needs to be cached.
</para>
- <programlisting><![CDATA[
- at Entity
+ <programlisting><![CDATA[@Entity
@Cache(usage = CacheConcurrencyStrategy.TRANSACTIONAL)
public class Account implements Serializable
{
// ... ...
-}
-]]></programlisting>
+}]]></programlisting>
<para>
A very simplified rule of thumb is that you will typically want to do caching for objects that rarely change, and which are frequently read.
You can fine tune the cache for each entity bean in the appropriate JBoss Cache configuration file, e.g. jboss-cache-manager-jboss-beans.xml.
@@ -306,8 +309,7 @@
If there are too many objects in the cache, the cache can evict the oldest or least used objects, depending on configuration, to make room for new objects.
Assuming the region_prefix specified in <literal>persistence.xml</literal> was <literal>myprefix</literal>, the default name of the cache region for the <literal>com.mycompany.entities.Account</literal> entity bean would be <literal>/myprefix/com/mycompany/entities/Account</literal>.
</para>
- <programlisting><![CDATA[
-<bean name="..." class="org.jboss.cache.config.Configuration">
+ <programlisting><![CDATA[<bean name="..." class="org.jboss.cache.config.Configuration">
... ...
<property name="evictionConfig">
<bean class="org.jboss.cache.config.EvictionConfig">
@@ -346,25 +348,21 @@
</property>
</bean>
</property>
-</bean>
-]]></programlisting>
+</bean>]]></programlisting>
<para>
If you do not specify a cache region for an entity bean class, all instances of this class will be cached using the <literal>defaultEvictionRegionConfig</literal> as defined above.
The @Cache annotation exposes an optional attribute “region” that lets you specify the cache region where an entity is to be stored, rather than having it be automatically be created from the fully-qualified class name of the entity class.
</para>
- <programlisting><![CDATA[
- at Entity
+ <programlisting><![CDATA[@Entity
@Cache(usage = CacheConcurrencyStrategy.TRANSACTIONAL, region = ”Account”)
public class Account implements Serializable
{
// ... ...
-}
-]]></programlisting>
+}]]></programlisting>
<para>
The eviction configuration would then become:
</para>
- <programlisting><![CDATA[
-<bean name="..." class="org.jboss.cache.config.Configuration">
+ <programlisting><![CDATA[<bean name="..." class="org.jboss.cache.config.Configuration">
... ...
<property name="evictionConfig">
<bean class="org.jboss.cache.config.EvictionConfig">
@@ -399,8 +397,7 @@
</property>
</bean>
</property>
-</bean>
-]]></programlisting>
+</bean>]]></programlisting>
</section>
<section>
@@ -416,8 +413,7 @@
<para>
Next, you create a named query associated with an entity, and tell Hibernate you want to cache the results of that query:
</para>
- <programlisting><![CDATA[
- at Entity
+ <programlisting><![CDATA[@Entity
@Cache(usage = CacheConcurrencyStrategy.TRANSACTIONAL, region = ”Account”)
@NamedQueries(
{
@@ -430,8 +426,7 @@
public class Account implements Serializable
{
// ... ...
-}
-]]></programlisting>
+}]]></programlisting>
<para>
The @NamedQueries, @NamedQuery and @QueryHint annotations are all in the javax.persistence package.
See the Hibernate and EJB3 documentation for more on how to use EJB3 queries and on how to instruct EJB3 to cache queries.
@@ -441,8 +436,7 @@
Based on this, you can set up separate eviction handling for your query results.
So, if the region prefix were set to myprefix in persistence.xml, you could, for example, create this sort of eviction handling:
</para>
- <programlisting><![CDATA[
-<bean name="..." class="org.jboss.cache.config.Configuration">
+ <programlisting><![CDATA[<bean name="..." class="org.jboss.cache.config.Configuration">
... ...
<property name="evictionConfig">
<bean class="org.jboss.cache.config.EvictionConfig">
@@ -486,13 +480,11 @@
</property>
</bean>
</property>
-</bean>
-]]></programlisting>
+</bean>]]></programlisting>
<para>
The @NamedQuery.hints attribute shown above takes an array of vendor-specific @QueryHints as a value. Hibernate accepts the “org.hibernate.cacheRegion” query hint, where the value is the name of a cache region to use instead ofthe default /org/hibernate/cache/StandardQueryCache. For example:
</para>
- <programlisting><![CDATA[
- at Entity
+ <programlisting><![CDATA[@Entity
@Cache(usage = CacheConcurrencyStrategy.TRANSACTIONAL, region = ”Account”)
@NamedQueries(
{
@@ -509,13 +501,11 @@
public class Account implements Serializable
{
// ... ...
-}
-]]></programlisting>
+}]]></programlisting>
<para>
The related eviction configuration:
</para>
- <programlisting><![CDATA[
-<bean name="..." class="org.jboss.cache.config.Configuration">
+ <programlisting><![CDATA[<bean name="..." class="org.jboss.cache.config.Configuration">
... ...
<property name="evictionConfig">
<bean class="org.jboss.cache.config.EvictionConfig">
@@ -560,8 +550,7 @@
</property>
</bean>
</property>
-</bean>
-]]></programlisting>
+</bean>]]></programlisting>
</section>
</section>
@@ -580,8 +569,7 @@
To cluster EJB 2.x entity beans, you need to add the <literal><clustered></literal> element to the application's <literal>jboss.xml</literal> descriptor file.
Below is a typical <literal>jboss.xml</literal> file.
</para>
- <programlisting><![CDATA[
-<jboss>
+ <programlisting><![CDATA[<jboss>
<enterprise-beans>
<entity>
<ejb-name>nextgen.EnterpriseEntity</ejb-name>
@@ -589,13 +577,16 @@
<clustered>True</clustered>
<cluster-config>
<partition-name>DefaultPartition</partition-name>
- <home-load-balance-policy>org.jboss.ha.framework.interfaces.RoundRobin</home-load-balance-policy>
- <bean-load-balance-policy>org.jboss.ha.framework.interfaces.FirstAvailable</bean-load-balance-policy>
+ <home-load-balance-policy>
+ org.jboss.ha.framework.interfaces.RoundRobin
+ </home-load-balance-policy>
+ <bean-load-balance-policy>
+ org.jboss.ha.framework.interfaces.FirstAvailable
+ </bean-load-balance-policy>
</cluster-config>
</entity>
</enterprise-beans>
-</jboss>
-]]></programlisting>
+</jboss>]]></programlisting>
<para>
The EJB 2.x entity beans are clustered for load balanced remote invocations.
All the bean instances are synchronized to have the same contents on all nodes.
More information about the jboss-cvs-commits
mailing list