Hibernate
/
hibernate-orm
mirror of https://github.com/hibernate/hibernate-orm
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Update for use with JBC 3 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@17672 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Brian Stansberry 2009-10-09 03:56:07 +00:00
parent c27da172ab
commit 7ca0f71ee1
6 changed files with 196 additions and 117 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

12
documentation/jbosscache2/pom.xml
View File

@ -39,12 +39,12 @@
</parent>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-jbc2-manual</artifactId>
<version>3.3.0-SNAPSHOT</version>
<artifactId>hibernate-jbc-manual</artifactId>
<version>3.5.0-SNAPSHOT</version>
<packaging>jdocbook</packaging>
<name>Hibernate/JBoss Cache 2 Reference Manual</name>
<description>The Hibernate / JBoss Cache 2 integration reference manual</description>
<name>Hibernate/JBoss Cache 3 Reference Manual</name>
<description>The Hibernate / JBoss Cache 3 integration reference manual</description>
<build>
<plugins>
@ -52,8 +52,8 @@
<groupId>org.jboss.maven.plugins</groupId>
<artifactId>maven-jdocbook-plugin</artifactId>
<configuration>
<sourceDocumentName>Hibernate_JBC2_Reference.xml</sourceDocumentName>
<sourceDirectory>${basedir}/src/main/docbook/en-US</sourceDirectory>
<sourceDocumentName>Hibernate_JBC_Reference.xml</sourceDocumentName>
<sourceDirectory>${basedir}/src/main/docbook/</sourceDirectory>
<masterTranslation>en-US</masterTranslation>
<imageResource>
<directory>${basedir}/src/main/docbook/en-US</directory>

10
documentation/jbosscache2/src/main/docbook/en-US/Hibernate_JBC2_Reference.xml → documentation/jbosscache2/src/main/docbook/en-US/Hibernate_JBC_Reference.xml
View File

@ -15,19 +15,19 @@
~ Red Hat Author(s): Brian Stansberry
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY versionNumber "3.3.0.alpha1">
<!ENTITY copyrightYear "2008">
<!ENTITY copyrightHolder "Red Hat Middleware, LLC.">
<!ENTITY versionNumber "3.5.0.alpha1">
<!ENTITY copyrightYear "2009">
<!ENTITY copyrightHolder "Red Hat, Inc.">
]>
<book>
<bookinfo>
<title>HIBERNATE - Relational Persistence for Idiomatic Java</title>
<subtitle>Using JBoss Cache 2 as a Hibernate Second Level Cache</subtitle>
<subtitle>Using JBoss Cache as a Hibernate Second Level Cache</subtitle>
<releaseinfo>&versionNumber;</releaseinfo>
<productnumber>&versionNumber;</productnumber>
<issuenum>1</issuenum>
<!--<issuenum>1</issuenum>-->
<mediaobject>
<imageobject role="fo">
<imagedata fileref="images/hibernate_logo_a.png" align="center" />

88
documentation/jbosscache2/src/main/docbook/en-US/content/concepts.xml
View File

@ -2,7 +2,7 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!--
~ Copyright (c) 2008, Red Hat Middleware, LLC. All rights reserved.
~ Copyright (c) 2009, Red Hat, Inc. All rights reserved.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
@ -41,8 +41,8 @@
The Second Level Cache can cache four different types of data: entities,
collections, query results and timestamps. Proper handling of each
of the types requires slightly different caching semantics. A major
improvement in Hibernate 3.3 is the addition of the
<literal>org.hibernate.cache.RegionFactory</literal> API, which
improvement in Hibernate 3.3 was the addition of the
<literal>org.hibernate.cache.RegionFactory</literal> SPI, which
allows Hibernate to tell the caching integration layer what type
of data is being cached. Based on that knowledge, the cache integration
layer can apply the semantics appropriate to that type.
@ -128,10 +128,10 @@
by another transaction. Whether the presence of that read
lock prevents a concurrent write depends on whether the cache
is configured for READ_COMMITTED or REPEATABLE_READ semantics
and whether the cache is using optimistic locking. READ_COMMITTED
and whether the cache is using pessimistic locking. READ_COMMITTED
will allow a concurrent write to proceed; pessimistic locking
with REPEATABLE_READ will cause the write to block until the
transaction with the read lock commits. Optimistic locking
transaction with the read lock commits. MVCC or optimistic locking
allows a REPEATABLE_READ semantic without forcing the writing
transaction to block.
</para>
@ -185,6 +185,16 @@
information.
</para>
<para>
If the cache is configured to use invalidation, a write to
the cache of an entity newly created by the transaction (i.e.
an entity that is stored to the database using an SQL INSERT)
should not result in any cluster-wide message at all. No other
node in the cluster can possibly be storing an outdated version
of the new entity, so there is no point in sending a cache
invalidation message.
</para>
</listitem>
<listitem>
@ -285,7 +295,7 @@
performant unless the query is quite expensive, is very likely to
be repeated on other nodes, and is unlikely to be invalidated out
of the cache.<footnote><para>See the discussion of the
<literal>hibernate.cache.region.jbc2.query.localonly</literal>
<literal>hibernate.cache.jbc.query.localonly</literal>
property in <xref linkend="sessionfactory"/></para> for more on how
to only cache query results locally.</footnote>.
</para>
@ -505,7 +515,7 @@
configuration:
</para>
<programlisting><![CDATA[hibernate.cache.region.jbc2.query.localonly=true]]></programlisting>
<programlisting><![CDATA[hibernate.cache.jbc.query.localonly=true]]></programlisting>
<para>
If the JBoss Cache instance that the query cache is using
@ -552,35 +562,37 @@
<title>Locking Scheme</title>
<para>
JBoss Cache supports both optimistic and pessimistic locking schemes.
JBoss Cache supports both MVCC and pessimistic locking schemes.
See the <emphasis>JBoss Cache User Guide</emphasis> for an in depth
discussion of these options. In the Second Level Cache use case, the
main benefit of optimistic locking is that updates of cached entities
main benefit of MVCC locking is that updates of cached entities
by one transaction do not block reads of the cached entity by other
transactions, yet REPEATABLE_READ semantics are preserved.
transactions, yet REPEATABLE_READ semantics are preserved. MVCC is
also significantly faster than pessimistic locking. For these
reasons, using MVCC locking is recommended for Second Level Caches.
</para>
<para>
If you are using optimistic locking and data versioning in Hibernate
for your entities, you should use it in the entity cache as well.
If you are not using data versioning, pessimistic locking should be
a better choice. Optimistic locking has a higher level of runtime overhead
than pessimistic locking, and in most Second Level Cache use cases a
REPEATABLE_READ semantic from the cache is not required (see
<xref linkend="concepts-cache-attr-isolation"/> for details on why not).
</para>
<note>
<title>Optimistic Locking</title>
<para>
JBoss Cache supports a third locking scheme, known as Optimistic
locking. Like MVCC, optimistic locking does not block readers
for writes, yet preserves REPEATABLE_READ semantics. However,
the runtime overhead of optimistic locking is much, much higher
than that of MVCC. So, use of MVCC is recommended.
</para>
</note>
</sect2><sect2 id="concepts-cache-attr-isolation" revision="1">
<title>Isolation Level</title>
<para>
If the PESSIMISTIC node locking scheme is used, JBoss Cache supports a number of
If the MVCC or PESSIMISTIC node locking schemes are used, JBoss Cache supports
different isolation level configurations that specify how different
transactions coordinate the locking of nodes in the cache. These
are somewhat analogous to database isolation levels; see the
<emphasis>JBoss Cache User Guide</emphasis> for an in depth
discussion of these options. For the Second Level Cache use case,
only two are valid: READ_COMMITTED and REPEATABLE_READ. In both cases,
transactions coordinate the locking of nodes in the cache: READ_COMMITTED
and REPEATABLE_READ. These are somewhat analogous to database
isolation levels; see the <emphasis>JBoss Cache User Guide</emphasis>
for an in depth discussion of these options. In both cases,
cache reads do not block for other reads. In both cases a transaction
that writes to a node in the cache tree will hold an exclusive lock on
that node until the transaction commits, causing other transactions
@ -597,7 +609,7 @@
</para>
<para>
If the OPTIMISTIC node locking scheme is used, any isolation level
If the deprecated OPTIMISTIC node locking scheme is used, any isolation level
configuration is ignored by the cache. Optimistic locking provides a
repeatable read semantic but does not cause writes to block for reads.
</para>
@ -754,8 +766,8 @@
<para>
As mentioned previously, Hibernate 3.3 introduced the
<literal>RegionFactory</literal> API as its mechanism for managing
the Second Level Cache. This API makes it possible for implementations
<literal>RegionFactory</literal> SPI as its mechanism for managing
the Second Level Cache. This SPI makes it possible for implementations
to know at all times whether they are working with entities,
collections, queries or timestamps. That knowledge allows the
Hibernate/JBoss Cache integration layer to make the best use of the
@ -764,7 +776,7 @@
<para>
A Hibernate user doesn't need to understand the <literal>RegionFactory</literal>
API in any detail at all; the main point is internally it makes
SPI in any detail at all; the main point is internally it makes
possible independent management of the different cache types.
</para>
</sect2>
@ -794,9 +806,9 @@
<para>
Provide a set of named JBoss Cache configurations in an XML
file (or just use the default set included in the
<literal>jbc2-configs.xml</literal> file found in the
<literal>jbc-configs.xml</literal> file found in the
<literal>org.hibernate.cache.jbc.builder</literal> package
in <literal>hibernate-jbosscache2.jar</literal>).
in <literal>hibernate-jbosscache.jar</literal>).
</para>
</listitem>
<listitem>
@ -820,8 +832,8 @@
<title>Sharable JGroups Resources</title>
<para>
JGroups is the group communication library JBoss Cache uses to send
messages around a cluster. Each cache has a JGroups
JGroups is the group communication library JBoss Cache uses JGroups
to send messages around a cluster. Each cache has a JGroups
<literal>Channel</literal>; different channels
around the cluster that have the same name and compatible
configurations detect each other and form a group for message
@ -872,7 +884,7 @@
(or just use the default set included in the
<literal>jgroups-stacks.xml</literal> file found in the
<literal>org.hibernate.cache.jbc.builder</literal> package
in the <literal>hibernate-jbosscache2.jar</literal>).
in the <literal>hibernate-jbosscache.jar</literal>).
</para>
</listitem>
<listitem>
@ -880,7 +892,7 @@
Tell Hibernate where to find that set of configurations
on the classpath. See <xref linkend="sessionfactory"/> for
details on how to do this. This is not necessary if the
default set included in <literal>hibernate-jbosscache2.jar</literal>
default set included in <literal>hibernate-jbosscache.jar</literal>
is used.
</para>
</listitem>
@ -890,7 +902,7 @@
the name of the channel you want to use. This should be
one of the named configurations in the JGroups XML file.
The default set of JBoss Cache configurations found in the
<literal>hibernate-jbosscache2.jar</literal> already have
<literal>hibernate-jbosscache.jar</literal> already have
appropriate default choices. See <xref linkend="jbc-config-jgroups"/>
for details on how to set this if you don't wish to use the
defaults.
@ -910,7 +922,7 @@
<para>
So, we've seen that Hibernate caches up to four different types of
data (entities, collections, queries and timestamps) and that
Hibernate 3.3 + JBoss Cache 2 gives you the flexibility to use a
Hibernate + JBoss Cache gives you the flexibility to use a
separate underlying JBoss Cache, with different behavior, for each
type. You can actually deploy four separate caches, one for each type.
</para>
@ -922,7 +934,7 @@
The queries can usually use the same cache as well. Similarly,
queries and timestamps can share a JBoss Cache instance configured
for replication, with the
<literal>hibernate.cache.region.jbc2.query.localonly=true</literal>
<literal>hibernate.cache.jbc.query.localonly=true</literal>
configuration letting you turn off replication for the queries if
you want to.
</para>

171
documentation/jbosscache2/src/main/docbook/en-US/content/configuration.xml
View File

@ -2,7 +2,7 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!--
~ Copyright (c) 2008, Red Hat Middleware, LLC. All rights reserved.
~ Copyright (c) 2009, Red Hat, Inc. All rights reserved.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
@ -22,7 +22,7 @@
<para>
There are three main areas of configuration involved in using JBoss Cache
2 for your Hibernate Second Level Cache: configuring the Hibernate
3 for your Hibernate Second Level Cache: configuring the Hibernate
<literal>SessionFactory</literal>, configuring the underlying JBoss Cache
instance(s), and configuring the JGroups <literal>ChannelFactory</literal>.
If you use the standard JBoss Cache and JGroups configurations that ship
@ -77,7 +77,7 @@
results replicated:
</para>
<programlisting><![CDATA[hibernate.cache.region.jbc2.query.localonly=true]]></programlisting>
<programlisting><![CDATA[hibernate.cache.jbc.query.localonly=true]]></programlisting>
</listitem>
<listitem>
@ -88,8 +88,8 @@
configuration option.
</para>
<programlisting><![CDATA[<![CDATA[hibernate.cache.region.factory_class=
org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]>]]></programlisting>
<programlisting><![CDATA[hibernate.cache.region.factory_class=
org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]></programlisting>
<para>
To determine the correct factory class, you must decide
@ -121,8 +121,8 @@
<title>Specifying the <literal>RegionFactory</literal> Implementation</title>
<para>
Hibernate 3.3 ships with the following <literal>RegionFactory</literal>
implementations that work with JBoss Cache 2. Select the
Hibernate 3.5 ships with the following <literal>RegionFactory</literal>
implementations that work with JBoss Cache 3. Select the
one that is appropriate to your needs and use it with
the <literal>hibernate.cache.region.factory_class</literal>
configuration option.
@ -188,7 +188,7 @@
<variablelist>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.shared</literal></term>
<term><literal>hibernate.cache.jbc.cfg.shared</literal></term>
<listitem>
<para>
Classpath or filesystem resource containing JBoss Cache
@ -198,14 +198,14 @@
</listitem>
</varlistentry>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.multiplexer.stacks</literal></term>
<term><literal>hibernate.cache.jbc.cfg.multiplexer.stacks</literal></term>
<listitem>
<para>
Classpath or filesystem resource containing JGroups protocol
stack configurations the <literal>ChannelFactory</literal>
should use. Default is
<literal>org/hibernate/cache/jbc2/builder/jgroups-stacks.xml</literal>,
a file found in the <literal>hibernate-jbosscache2.jar</literal>.
<literal>org/hibernate/cache/jbc/builder/jgroups-stacks.xml</literal>,
a file found in the <literal>hibernate-jbosscache.jar</literal>.
</para>
</listitem>
</varlistentry>
@ -227,7 +227,7 @@
<variablelist>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.shared</literal></term>
<term><literal>hibernate.cache.jbc.cfg.shared</literal></term>
<listitem>
<para>
Specifies the JNDI name under which the JBoss Cache instance
@ -261,7 +261,7 @@
<variablelist>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.configs</literal></term>
<term><literal>hibernate.cache.jbc.configs</literal></term>
<listitem>
<para>
Classpath or filesystem resource containing JBoss Cache
@ -273,28 +273,28 @@
</listitem>
</varlistentry>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.multiplexer.stacks</literal></term>
<term><literal>hibernate.cache.jbc.cfg.multiplexer.stacks</literal></term>
<listitem>
<para>
Classpath or filesystem resource containing JGroups protocol
stack configurations the <literal>ChannelFactory</literal>
should use. Default is
<literal>org/hibernate/cache/jbc2/builder/jgroups-stacks.xml</literal>,
a file found in the <literal>hibernate-jbosscache2.jar</literal>.
<literal>org/hibernate/cache/jbc/builder/jgroups-stacks.xml</literal>,
a file found in the <literal>hibernate-jbosscache.jar</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.entity</literal></term>
<term><literal>hibernate.cache.jbc.cfg.entity</literal></term>
<listitem>
<para>
Name of the configuration that should be used for entity caches.
Default value is <literal>optimistic-entity</literal>.
Default value is <literal>mvcc-entity</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.collection</literal></term>
<term><literal>hibernate.cache.jbc.cfg.collection</literal></term>
<listitem>
<para>
Name of the configuration that should be used for collection caches.
@ -304,7 +304,7 @@
</listitem>
</varlistentry>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.ts</literal></term>
<term><literal>hibernate.cache.jbc.cfg.timestamps</literal></term>
<listitem>
<para>
Name of the configuration that should be used for timestamp caches.
@ -313,7 +313,7 @@
</listitem>
</varlistentry>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.query</literal></term>
<term><literal>hibernate.cache.jbc.cfg.query</literal></term>
<listitem>
<para>
Name of the configuration that should be used for query caches.
@ -327,11 +327,11 @@
<para>
Many of the default values name JBoss Cache configurations in the
standard <literal>jbc2-configs.xml</literal> file found in the
<literal>hibernate-jbosscache2.jar</literal>. See
standard <literal>jbc-configs.xml</literal> file found in the
<literal>hibernate-jbosscache.jar</literal>. See
<xref linkend="jbc-config-multiple-std"/> for details on those
configurations. If you want to set
<literal>hibernate.cache.region.jbc2.configs</literal> and use your
<literal>hibernate.cache.jbc.configs</literal> and use your
own JBoss Cache configuration file, you can still take advantage of
these default names; just name the configurations in your file
to match.
@ -342,10 +342,10 @@
just configure the defaults, with query caching enabled:
</para>
<programlisting><![CDATA[<![CDATA[hibernate.cache.use_second_level_cache=true
<programlisting><![CDATA[hibernate.cache.use_second_level_cache=true
hibernate.cache.use_query_cache=true
hibernate.cache.region.factory_class=
org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]>]]></programlisting>
org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]></programlisting>
<para>
You would end up using two JBoss Cache instances:
@ -390,7 +390,7 @@ hibernate.cache.region.factory_class=
<variablelist>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cachefactory</literal></term>
<term><literal>hibernate.cache.jbc.cachefactory</literal></term>
<listitem>
<para>
Specifies the JNDI name under which the
@ -400,16 +400,16 @@ hibernate.cache.region.factory_class=
</listitem>
</varlistentry>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.entity</literal></term>
<term><literal>hibernate.cache.jbc.cfg.entity</literal></term>
<listitem>
<para>
Name of the configuration that should be used for entity caches.
Default value is <literal>optimistic-entity</literal>.
Default value is <literal>mvcc-entity</literal>.
</para>
</listitem>
</varlistentry>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.collection</literal></term>
<term><literal>hibernate.cache.jbc.cfg.collection</literal></term>
<listitem>
<para>
Name of the configuration that should be used for collection caches.
@ -419,7 +419,7 @@ hibernate.cache.region.factory_class=
</listitem>
</varlistentry>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.ts</literal></term>
<term><literal>hibernate.cache.jbc.cfg.timestamps</literal></term>
<listitem>
<para>
Name of the configuration that should be used for timestamp caches.
@ -428,7 +428,7 @@ hibernate.cache.region.factory_class=
</listitem>
</varlistentry>
<varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.query</literal></term>
<term><literal>hibernate.cache.jbc.cfg.query</literal></term>
<listitem>
<para>
Name of the configuration that should be used for query caches.
@ -442,7 +442,7 @@ hibernate.cache.region.factory_class=
<para>
See <xref linkend="sessionfactory-multiplexed"/> for a discussion of
how the various <literal>hibernate.cache.region.jbc2.cfg</literal>
how the various <literal>hibernate.cache.jbc.cfg</literal>
options combine to determine what JBoss Cache instances are used.
</para>
@ -456,6 +456,31 @@ hibernate.cache.region.factory_class=
</para>
</sect2>
<sect2 id="sessionfactory-legacy">
<title>Legacy Configuration Properties</title>
<para>A number of the configuration properties discussed above have
changed their name from Hibernate 3.3 to Hibernate 3.5. However,
to aid users moving applications from 3.3 to 3.5, the legacy property
names are still supported. The legacy property names are:</para>
<itemizedlist>
<listitem><para><literal>hibernate.cache.region.jbc2.query.localonly</literal></para></listitem>
<listitem><para><literal>hibernate.cache.region.jbc2.cfg.shared</literal></para></listitem>
<listitem><para><literal>hibernate.cache.region.jbc2.cfg.multiplexer.stacks</literal></para></listitem>
<listitem><para><literal>hibernate.cache.region.jbc2.configs</literal></para></listitem>
<listitem><para><literal>hibernate.cache.region.jbc2.cfg.entity</literal></para></listitem>
<listitem><para><literal>hibernate.cache.region.jbc2.cfg.collection</literal></para></listitem>
<listitem><para><literal>hibernate.cache.region.jbc2.cfg.query</literal></para></listitem>
<listitem><para><literal>hibernate.cache.region.jbc2.cfg.ts</literal></para></listitem>
</itemizedlist>
<para>To understand the meaning of these legacy properties, just change
<literal>.region.jbc2</literal> to <literal>.jbc</literal> and see
the documentation above. The only exception to that is
<literal>hibernate.cache.region.jbc2.cfg.ts</literal> has
been changed to <literal>hibernate.cache.jbc.cfg.timestamps</literal>.</para>
</sect2>
</sect1>
@ -497,8 +522,8 @@ hibernate.cache.region.factory_class=
If you are using <literal>MultiplexedJBossCacheRegionFactory</literal>
you will need to provide a set of JBoss Cache configurations for
its <literal>CacheManager</literal> to use. (Or, use the set in the
<literal>jbc2-configs.xml</literal> file that ships with
<literal>hibernate-jbosscache2.jar</literal>.) The XML file used
<literal>jbc-configs.xml</literal> file that ships with
<literal>hibernate-jbosscache.jar</literal>.) The XML file used
by a <literal>CacheManager</literal> is very similar to the
usual config file used by a standalone cache; the biggest
difference is it can include multiple, named, configurations.
@ -510,10 +535,10 @@ hibernate.cache.region.factory_class=
<cache-configs>
<!-- A config appropriate for entity/collection caching. -->
<cache-config name="optimistic-entity">
<cache-config name="mvcc-entity">
<!-- Node locking scheme -->
<attribute name="NodeLockingScheme">OPTIMISTIC</attribute>
<attribute name="NodeLockingScheme">MVCC</attribute>
..... other configuration attributes
@ -595,10 +620,10 @@ hibernate.cache.region.factory_class=
</para>
<programlisting><![CDATA[<!-- Node locking scheme:
OPTIMISTIC
MVCC
PESSIMISTIC (default)
-->
<attribute name="NodeLockingScheme">OPTIMISTIC</attribute>]]></programlisting>
<attribute name="NodeLockingScheme">MVCC</attribute>]]></programlisting>
</sect3>
@ -723,7 +748,7 @@ hibernate.cache.region.factory_class=
<para>
Region based marshalling is enabled in the standard cache
configurations that ship with
<literal>hibernate-jbosscache2.jar</literal>
<literal>hibernate-jbosscache.jar</literal>
</para>
</sect3>
@ -743,8 +768,8 @@ hibernate.cache.region.factory_class=
<para>
Hibernate ships with a number of standard JBoss Cache configurations
in the <literal>hibernate-jbosscache2.jar</literal>'s
<literal>jbc2-configs.xml</literal> file. The following table
in the <literal>hibernate-jbosscache.jar</literal>'s
<literal>jbc-configs.xml</literal> file. The following table
highlights the key features of each configuration.
</para>
@ -768,6 +793,26 @@ hibernate.cache.region.factory_class=
</row>
</thead>
<tbody>
<row>
<entry>
<property>mvcc-entity</property>
</entry>
<entry>
<property>E/C/Q</property>
</entry>
<entry>
<property>E/C/Q</property>
</entry>
<entry>
<property>INVALIDATION_SYNC</property>
</entry>
<entry>
<property>MVCC</property>
</entry>
<entry>
<para>no</para>
</entry>
</row>
<row>
<entry>
<property>optimistic-entity</property>
@ -776,7 +821,7 @@ hibernate.cache.region.factory_class=
<property>E/C/Q</property>
</entry>
<entry>
<property>E/C/Q</property>
<property>--</property>
</entry>
<entry>
<property>INVALIDATION_SYNC</property>
@ -796,7 +841,7 @@ hibernate.cache.region.factory_class=
<property>E/C/Q</property>
</entry>
<entry>
<property>E/C/Q</property>
<property>--</property>
</entry>
<entry>
<property>INVALIDATION_SYNC</property>
@ -822,7 +867,7 @@ hibernate.cache.region.factory_class=
<property>LOCAL</property>
</entry>
<entry>
<property>PESSIMISTIC</property>
<property>MVCC</property>
</entry>
<entry>
<para>no</para>
@ -842,7 +887,7 @@ hibernate.cache.region.factory_class=
<property>LOCAL</property>
</entry>
<entry>
<property>OPTIMISTIC</property>
<property>MVCC</property>
</entry>
<entry>
<para>no</para>
@ -862,7 +907,27 @@ hibernate.cache.region.factory_class=
<property>REPL_ASYNC</property>
</entry>
<entry>
<property>PESSIMISTIC</property>
<property>MVCC</property>
</entry>
<entry>
<para>yes</para>
</entry>
</row>
<row>
<entry>
<property>mvcc-shared</property>
</entry>
<entry>
<property>E/C/Q/T</property>
</entry>
<entry>
<property>--</property>
</entry>
<entry>
<property>REPL_SYNC</property>
</entry>
<entry>
<property>MVCC</property>
</entry>
<entry>
<para>yes</para>
@ -942,9 +1007,11 @@ hibernate.cache.region.factory_class=
</listitem>
<listitem>
<para>
The configurations that use PESSIMISTIC locking use isolation level
READ_COMMITTED. There are also two other standard configurations
The configurations that use MVCC or PESSIMISTIC locking use isolation level
READ_COMMITTED. There are also four other standard configurations
not shown in the table that use REPEATABLE_READ:
<literal>mvcc-entity-repeatable</literal>,
<literal>mvcc-shared-repeatable</literal>,
<literal>pessimistic-entity-repeatable</literal> and
<literal>pessimistic-shared-repeatable</literal>. In all other
respects those configurations are the same as the similarly named
@ -977,7 +1044,7 @@ hibernate.cache.region.factory_class=
<para>
The <literal>jgroups-stacks.xml</literal> file found in the
<literal>org.hibernate.cache.jbc.builder</literal> package
in the <literal>hibernate-jbosscache2.jar</literal> provides a good
in the <literal>hibernate-jbosscache.jar</literal> provides a good
set of standard JGroups configurations; these should be suitable for
most needs. If you need to create your own configuration set, we
recommend that you start with this file as a base.
@ -1002,7 +1069,7 @@ hibernate.cache.region.factory_class=
since maintaining cache consistency means many messages need to
be sent to all members. UDP-based channel configurations are
used in the JBoss Cache configurations in the standard
<literal>jbc2-configs.xml</literal> file that ships with
<literal>jbc-configs.xml</literal> file that ships with
Hibernate.
</para>
</listitem>
@ -1050,7 +1117,7 @@ hibernate.cache.region.factory_class=
<para>
The TCP-based configurations in the
<literal>jgroups-stacks.xml</literal> file found in
<literal>hibernate-jbosscache2.jar</literal> all use
<literal>hibernate-jbosscache.jar</literal> all use
TCP + MPING. This is because there is no way for the
Hibernate authors to provide a meaningful static
configuration for TCPPING. If you want to use TCP + TCPPING

26
documentation/jbosscache2/src/main/docbook/en-US/content/introduction.xml
View File

@ -2,7 +2,7 @@
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!--
~ Copyright (c) 2008, Red Hat Middleware, LLC. All rights reserved.
~ Copyright (c) 2009, Red Hat, Inc. All rights reserved.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
@ -68,9 +68,9 @@
<sect2 id="introduction-requirements-dependencies" revision="1">
<title>Dependencies</title>
<para>
Second level caching with JBoss Cache 2 requires the use of JBoss
Cache 2.1.0 or later. The core JBoss Cache project is used; the
related PojoCache project/library is not needed. The following jars,
Second level caching with JBoss Cache 3 requires the use of JBoss
Cache 3.1.0 or later. The core JBoss Cache project is used; the
related POJO Cache project/library is not needed. The following jars,
included with the JBoss Cache distribution, need to be on the classpath:
</para>
@ -88,7 +88,7 @@
</para>
<para>
The <literal>hibernate-jbosscache2.jar</literal> that is included with
The <literal>hibernate-jbosscache.jar</literal> that is included with
the Hibernate distribution also needs to be on the classpath.
</para>
@ -97,9 +97,9 @@
file<footnote><para><ulink url="http://labs.jboss.org/jgroups">JGroups</ulink>
is the group communication library used by JBoss Cache for intra-cluster
communication.</para></footnote>, need to be on the classpath. The
<literal>hibernate-jbosscache2.jar</literal> includes standard
<literal>hibernate-jbosscache.jar</literal> includes standard
configuration files in the <literal>org.hibernate.cache.jbc.builder</literal>
package. The <literal>jbc2-configs.xml</literal> file is for JBoss
package. The <literal>jbc-configs.xml</literal> file is for JBoss
Cache and the <literal>jgroups-stacks.xml</literal> file is for JGroups.
See <xref linkend="jbc-config"/> and <xref linkend="jgroups-config"/>
for more details on these files. Users can create their own versions
@ -157,12 +157,12 @@
<listitem>
<para>
Tell Hibernate in your <literal>SessionFactory</literal>
configuration that you want to use JBoss Cache 2 as your
configuration that you want to use JBoss Cache as your
Second Level Cache implementation:
</para>
<programlisting><![CDATA[<![CDATA[hibernate.cache.region.factory_class=
org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]>]]></programlisting>
<programlisting><![CDATA[hibernate.cache.region.factory_class=
org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]></programlisting>
<para>
There are a number of values that can be provided for the
@ -179,9 +179,9 @@
<para>
Do not set the legacy <literal>hibernate.cache.provider_class</literal>
property when using JBoss Cache 2. That is a legacy property
property when using JBoss Cache 3. That is a legacy property
from before Hibernate 3.3's redesign of second level caching
internals. It will not work with JBoss Cache 2.
internals. It will not work with JBoss Cache 3.
</para>
</listitem>
@ -209,7 +209,7 @@
results replicated:
</para>
<programlisting><![CDATA[hibernate.cache.region.jbc2.query.localonly=true]]></programlisting>
<programlisting><![CDATA[hibernate.cache.jbc.query.localonly=true]]></programlisting>
</listitem>
</itemizedlist>

6
documentation/jbosscache2/src/main/docbook/en-US/content/preface.xml
View File

@ -2,7 +2,7 @@
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<!--
~ Copyright (c) 2008, Red Hat Middleware, LLC. All rights reserved.
~ Copyright (c) 2009, Red Hat, Inc. All rights reserved.
~
~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU
@ -62,7 +62,7 @@
caching libraries. This document is focused on the use of the
<ulink url="http://labs.jboss.org/jbosscache">JBoss Cache</ulink>
clustered transactional caching library as an implementation of
the Second Level Cache. It specifically focuses on JBoss Cache 2.
the Second Level Cache. It specifically focuses on JBoss Cache 3.
</para>
<para>
@ -142,7 +142,7 @@
<listitem>
<para>
Use this guide as your primary source of information on the
usage of JBoss Cache 2 as a Hibernate Second Level Cache.
usage of JBoss Cache 3 as a Hibernate Second Level Cache.
</para>
</listitem>
</orderedlist>