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> </parent>
<groupId>org.hibernate</groupId> <groupId>org.hibernate</groupId>
<artifactId>hibernate-jbc2-manual</artifactId> <artifactId>hibernate-jbc-manual</artifactId>
<version>3.3.0-SNAPSHOT</version> <version>3.5.0-SNAPSHOT</version>
<packaging>jdocbook</packaging> <packaging>jdocbook</packaging>
<name>Hibernate/JBoss Cache 2 Reference Manual</name> <name>Hibernate/JBoss Cache 3 Reference Manual</name>
<description>The Hibernate / JBoss Cache 2 integration reference manual</description> <description>The Hibernate / JBoss Cache 3 integration reference manual</description>
<build> <build>
<plugins> <plugins>
@ -52,8 +52,8 @@
<groupId>org.jboss.maven.plugins</groupId> <groupId>org.jboss.maven.plugins</groupId>
<artifactId>maven-jdocbook-plugin</artifactId> <artifactId>maven-jdocbook-plugin</artifactId>
<configuration> <configuration>
<sourceDocumentName>Hibernate_JBC2_Reference.xml</sourceDocumentName> <sourceDocumentName>Hibernate_JBC_Reference.xml</sourceDocumentName>
<sourceDirectory>${basedir}/src/main/docbook/en-US</sourceDirectory> <sourceDirectory>${basedir}/src/main/docbook/</sourceDirectory>
<masterTranslation>en-US</masterTranslation> <masterTranslation>en-US</masterTranslation>
<imageResource> <imageResource>
<directory>${basedir}/src/main/docbook/en-US</directory> <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 ~ 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" [ <!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 versionNumber "3.5.0.alpha1">
<!ENTITY copyrightYear "2008"> <!ENTITY copyrightYear "2009">
<!ENTITY copyrightHolder "Red Hat Middleware, LLC."> <!ENTITY copyrightHolder "Red Hat, Inc.">
]> ]>
<book> <book>
<bookinfo> <bookinfo>
<title>HIBERNATE - Relational Persistence for Idiomatic Java</title> <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> <releaseinfo>&versionNumber;</releaseinfo>
<productnumber>&versionNumber;</productnumber> <productnumber>&versionNumber;</productnumber>
<issuenum>1</issuenum> <!--<issuenum>1</issuenum>-->
<mediaobject> <mediaobject>
<imageobject role="fo"> <imageobject role="fo">
<imagedata fileref="images/hibernate_logo_a.png" align="center" /> <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"> <!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, ~ 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 ~ 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, The Second Level Cache can cache four different types of data: entities,
collections, query results and timestamps. Proper handling of each collections, query results and timestamps. Proper handling of each
of the types requires slightly different caching semantics. A major of the types requires slightly different caching semantics. A major
improvement in Hibernate 3.3 is the addition of the improvement in Hibernate 3.3 was the addition of the
<literal>org.hibernate.cache.RegionFactory</literal> API, which <literal>org.hibernate.cache.RegionFactory</literal> SPI, which
allows Hibernate to tell the caching integration layer what type allows Hibernate to tell the caching integration layer what type
of data is being cached. Based on that knowledge, the cache integration of data is being cached. Based on that knowledge, the cache integration
layer can apply the semantics appropriate to that type. layer can apply the semantics appropriate to that type.
@ -128,10 +128,10 @@
by another transaction. Whether the presence of that read by another transaction. Whether the presence of that read
lock prevents a concurrent write depends on whether the cache lock prevents a concurrent write depends on whether the cache
is configured for READ_COMMITTED or REPEATABLE_READ semantics 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 will allow a concurrent write to proceed; pessimistic locking
with REPEATABLE_READ will cause the write to block until the 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 allows a REPEATABLE_READ semantic without forcing the writing
transaction to block. transaction to block.
</para> </para>
@ -185,6 +185,16 @@
information. information.
</para> </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>
<listitem> <listitem>
@ -285,7 +295,7 @@
performant unless the query is quite expensive, is very likely to performant unless the query is quite expensive, is very likely to
be repeated on other nodes, and is unlikely to be invalidated out be repeated on other nodes, and is unlikely to be invalidated out
of the cache.<footnote><para>See the discussion of the 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 property in <xref linkend="sessionfactory"/></para> for more on how
to only cache query results locally.</footnote>. to only cache query results locally.</footnote>.
</para> </para>
@ -505,7 +515,7 @@
configuration: configuration:
</para> </para>
<programlisting><![CDATA[hibernate.cache.region.jbc2.query.localonly=true]]></programlisting> <programlisting><![CDATA[hibernate.cache.jbc.query.localonly=true]]></programlisting>
<para> <para>
If the JBoss Cache instance that the query cache is using If the JBoss Cache instance that the query cache is using
@ -552,35 +562,37 @@
<title>Locking Scheme</title> <title>Locking Scheme</title>
<para> <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 See the <emphasis>JBoss Cache User Guide</emphasis> for an in depth
discussion of these options. In the Second Level Cache use case, the 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 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>
<para> <note>
If you are using optimistic locking and data versioning in Hibernate <title>Optimistic Locking</title>
for your entities, you should use it in the entity cache as well. <para>
If you are not using data versioning, pessimistic locking should be JBoss Cache supports a third locking scheme, known as Optimistic
a better choice. Optimistic locking has a higher level of runtime overhead locking. Like MVCC, optimistic locking does not block readers
than pessimistic locking, and in most Second Level Cache use cases a for writes, yet preserves REPEATABLE_READ semantics. However,
REPEATABLE_READ semantic from the cache is not required (see the runtime overhead of optimistic locking is much, much higher
<xref linkend="concepts-cache-attr-isolation"/> for details on why not). than that of MVCC. So, use of MVCC is recommended.
</para> </para>
</note>
</sect2><sect2 id="concepts-cache-attr-isolation" revision="1"> </sect2><sect2 id="concepts-cache-attr-isolation" revision="1">
<title>Isolation Level</title> <title>Isolation Level</title>
<para> <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 different isolation level configurations that specify how different
transactions coordinate the locking of nodes in the cache. These transactions coordinate the locking of nodes in the cache: READ_COMMITTED
are somewhat analogous to database isolation levels; see the and REPEATABLE_READ. These are somewhat analogous to database
<emphasis>JBoss Cache User Guide</emphasis> for an in depth isolation levels; see the <emphasis>JBoss Cache User Guide</emphasis>
discussion of these options. For the Second Level Cache use case, for an in depth discussion of these options. In both cases,
only two are valid: READ_COMMITTED and REPEATABLE_READ. In both cases,
cache reads do not block for other reads. In both cases a transaction 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 writes to a node in the cache tree will hold an exclusive lock on
that node until the transaction commits, causing other transactions that node until the transaction commits, causing other transactions
@ -597,7 +609,7 @@
</para> </para>
<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 configuration is ignored by the cache. Optimistic locking provides a
repeatable read semantic but does not cause writes to block for reads. repeatable read semantic but does not cause writes to block for reads.
</para> </para>
@ -754,8 +766,8 @@
<para> <para>
As mentioned previously, Hibernate 3.3 introduced the As mentioned previously, Hibernate 3.3 introduced the
<literal>RegionFactory</literal> API as its mechanism for managing <literal>RegionFactory</literal> SPI as its mechanism for managing
the Second Level Cache. This API makes it possible for implementations the Second Level Cache. This SPI makes it possible for implementations
to know at all times whether they are working with entities, to know at all times whether they are working with entities,
collections, queries or timestamps. That knowledge allows the collections, queries or timestamps. That knowledge allows the
Hibernate/JBoss Cache integration layer to make the best use of the Hibernate/JBoss Cache integration layer to make the best use of the
@ -764,7 +776,7 @@
<para> <para>
A Hibernate user doesn't need to understand the <literal>RegionFactory</literal> 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. possible independent management of the different cache types.
</para> </para>
</sect2> </sect2>
@ -794,9 +806,9 @@
<para> <para>
Provide a set of named JBoss Cache configurations in an XML Provide a set of named JBoss Cache configurations in an XML
file (or just use the default set included in the 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 <literal>org.hibernate.cache.jbc.builder</literal> package
in <literal>hibernate-jbosscache2.jar</literal>). in <literal>hibernate-jbosscache.jar</literal>).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -820,8 +832,8 @@
<title>Sharable JGroups Resources</title> <title>Sharable JGroups Resources</title>
<para> <para>
JGroups is the group communication library JBoss Cache uses to send JGroups is the group communication library JBoss Cache uses JGroups
messages around a cluster. Each cache has a JGroups to send messages around a cluster. Each cache has a JGroups
<literal>Channel</literal>; different channels <literal>Channel</literal>; different channels
around the cluster that have the same name and compatible around the cluster that have the same name and compatible
configurations detect each other and form a group for message configurations detect each other and form a group for message
@ -872,7 +884,7 @@
(or just use the default set included in the (or just use the default set included in the
<literal>jgroups-stacks.xml</literal> file found in the <literal>jgroups-stacks.xml</literal> file found in the
<literal>org.hibernate.cache.jbc.builder</literal> package <literal>org.hibernate.cache.jbc.builder</literal> package
in the <literal>hibernate-jbosscache2.jar</literal>). in the <literal>hibernate-jbosscache.jar</literal>).
</para> </para>
</listitem> </listitem>
<listitem> <listitem>
@ -880,7 +892,7 @@
Tell Hibernate where to find that set of configurations Tell Hibernate where to find that set of configurations
on the classpath. See <xref linkend="sessionfactory"/> for on the classpath. See <xref linkend="sessionfactory"/> for
details on how to do this. This is not necessary if the 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. is used.
</para> </para>
</listitem> </listitem>
@ -890,7 +902,7 @@
the name of the channel you want to use. This should be the name of the channel you want to use. This should be
one of the named configurations in the JGroups XML file. one of the named configurations in the JGroups XML file.
The default set of JBoss Cache configurations found in the 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"/> appropriate default choices. See <xref linkend="jbc-config-jgroups"/>
for details on how to set this if you don't wish to use the for details on how to set this if you don't wish to use the
defaults. defaults.
@ -910,7 +922,7 @@
<para> <para>
So, we've seen that Hibernate caches up to four different types of So, we've seen that Hibernate caches up to four different types of
data (entities, collections, queries and timestamps) and that 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 separate underlying JBoss Cache, with different behavior, for each
type. You can actually deploy four separate caches, one for each type. type. You can actually deploy four separate caches, one for each type.
</para> </para>
@ -922,7 +934,7 @@
The queries can usually use the same cache as well. Similarly, The queries can usually use the same cache as well. Similarly,
queries and timestamps can share a JBoss Cache instance configured queries and timestamps can share a JBoss Cache instance configured
for replication, with the 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 configuration letting you turn off replication for the queries if
you want to. you want to.
</para> </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"> <!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, ~ 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 ~ copy, or redistribute it subject to the terms and conditions of the GNU
@ -22,7 +22,7 @@
<para> <para>
There are three main areas of configuration involved in using JBoss Cache 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 <literal>SessionFactory</literal>, configuring the underlying JBoss Cache
instance(s), and configuring the JGroups <literal>ChannelFactory</literal>. instance(s), and configuring the JGroups <literal>ChannelFactory</literal>.
If you use the standard JBoss Cache and JGroups configurations that ship If you use the standard JBoss Cache and JGroups configurations that ship
@ -77,7 +77,7 @@
results replicated: results replicated:
</para> </para>
<programlisting><![CDATA[hibernate.cache.region.jbc2.query.localonly=true]]></programlisting> <programlisting><![CDATA[hibernate.cache.jbc.query.localonly=true]]></programlisting>
</listitem> </listitem>
<listitem> <listitem>
@ -88,8 +88,8 @@
configuration option. configuration option.
</para> </para>
<programlisting><![CDATA[<![CDATA[hibernate.cache.region.factory_class= <programlisting><![CDATA[hibernate.cache.region.factory_class=
org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]>]]></programlisting> org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]></programlisting>
<para> <para>
To determine the correct factory class, you must decide To determine the correct factory class, you must decide
@ -121,8 +121,8 @@
<title>Specifying the <literal>RegionFactory</literal> Implementation</title> <title>Specifying the <literal>RegionFactory</literal> Implementation</title>
<para> <para>
Hibernate 3.3 ships with the following <literal>RegionFactory</literal> Hibernate 3.5 ships with the following <literal>RegionFactory</literal>
implementations that work with JBoss Cache 2. Select the implementations that work with JBoss Cache 3. Select the
one that is appropriate to your needs and use it with one that is appropriate to your needs and use it with
the <literal>hibernate.cache.region.factory_class</literal> the <literal>hibernate.cache.region.factory_class</literal>
configuration option. configuration option.
@ -188,7 +188,7 @@
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.shared</literal></term> <term><literal>hibernate.cache.jbc.cfg.shared</literal></term>
<listitem> <listitem>
<para> <para>
Classpath or filesystem resource containing JBoss Cache Classpath or filesystem resource containing JBoss Cache
@ -198,14 +198,14 @@
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.multiplexer.stacks</literal></term> <term><literal>hibernate.cache.jbc.cfg.multiplexer.stacks</literal></term>
<listitem> <listitem>
<para> <para>
Classpath or filesystem resource containing JGroups protocol Classpath or filesystem resource containing JGroups protocol
stack configurations the <literal>ChannelFactory</literal> stack configurations the <literal>ChannelFactory</literal>
should use. Default is should use. Default is
<literal>org/hibernate/cache/jbc2/builder/jgroups-stacks.xml</literal>, <literal>org/hibernate/cache/jbc/builder/jgroups-stacks.xml</literal>,
a file found in the <literal>hibernate-jbosscache2.jar</literal>. a file found in the <literal>hibernate-jbosscache.jar</literal>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
@ -227,7 +227,7 @@
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.shared</literal></term> <term><literal>hibernate.cache.jbc.cfg.shared</literal></term>
<listitem> <listitem>
<para> <para>
Specifies the JNDI name under which the JBoss Cache instance Specifies the JNDI name under which the JBoss Cache instance
@ -261,7 +261,7 @@
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.configs</literal></term> <term><literal>hibernate.cache.jbc.configs</literal></term>
<listitem> <listitem>
<para> <para>
Classpath or filesystem resource containing JBoss Cache Classpath or filesystem resource containing JBoss Cache
@ -273,28 +273,28 @@
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.multiplexer.stacks</literal></term> <term><literal>hibernate.cache.jbc.cfg.multiplexer.stacks</literal></term>
<listitem> <listitem>
<para> <para>
Classpath or filesystem resource containing JGroups protocol Classpath or filesystem resource containing JGroups protocol
stack configurations the <literal>ChannelFactory</literal> stack configurations the <literal>ChannelFactory</literal>
should use. Default is should use. Default is
<literal>org/hibernate/cache/jbc2/builder/jgroups-stacks.xml</literal>, <literal>org/hibernate/cache/jbc/builder/jgroups-stacks.xml</literal>,
a file found in the <literal>hibernate-jbosscache2.jar</literal>. a file found in the <literal>hibernate-jbosscache.jar</literal>.
</para> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.entity</literal></term> <term><literal>hibernate.cache.jbc.cfg.entity</literal></term>
<listitem> <listitem>
<para> <para>
Name of the configuration that should be used for entity caches. 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.collection</literal></term> <term><literal>hibernate.cache.jbc.cfg.collection</literal></term>
<listitem> <listitem>
<para> <para>
Name of the configuration that should be used for collection caches. Name of the configuration that should be used for collection caches.
@ -304,7 +304,7 @@
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.ts</literal></term> <term><literal>hibernate.cache.jbc.cfg.timestamps</literal></term>
<listitem> <listitem>
<para> <para>
Name of the configuration that should be used for timestamp caches. Name of the configuration that should be used for timestamp caches.
@ -313,7 +313,7 @@
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.query</literal></term> <term><literal>hibernate.cache.jbc.cfg.query</literal></term>
<listitem> <listitem>
<para> <para>
Name of the configuration that should be used for query caches. Name of the configuration that should be used for query caches.
@ -327,11 +327,11 @@
<para> <para>
Many of the default values name JBoss Cache configurations in the Many of the default values name JBoss Cache configurations in the
standard <literal>jbc2-configs.xml</literal> file found in the standard <literal>jbc-configs.xml</literal> file found in the
<literal>hibernate-jbosscache2.jar</literal>. See <literal>hibernate-jbosscache.jar</literal>. See
<xref linkend="jbc-config-multiple-std"/> for details on those <xref linkend="jbc-config-multiple-std"/> for details on those
configurations. If you want to set 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 own JBoss Cache configuration file, you can still take advantage of
these default names; just name the configurations in your file these default names; just name the configurations in your file
to match. to match.
@ -342,10 +342,10 @@
just configure the defaults, with query caching enabled: just configure the defaults, with query caching enabled:
</para> </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.use_query_cache=true
hibernate.cache.region.factory_class= hibernate.cache.region.factory_class=
org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]>]]></programlisting> org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]></programlisting>
<para> <para>
You would end up using two JBoss Cache instances: You would end up using two JBoss Cache instances:
@ -390,7 +390,7 @@ hibernate.cache.region.factory_class=
<variablelist> <variablelist>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cachefactory</literal></term> <term><literal>hibernate.cache.jbc.cachefactory</literal></term>
<listitem> <listitem>
<para> <para>
Specifies the JNDI name under which the Specifies the JNDI name under which the
@ -400,16 +400,16 @@ hibernate.cache.region.factory_class=
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.entity</literal></term> <term><literal>hibernate.cache.jbc.cfg.entity</literal></term>
<listitem> <listitem>
<para> <para>
Name of the configuration that should be used for entity caches. 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> </para>
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.collection</literal></term> <term><literal>hibernate.cache.jbc.cfg.collection</literal></term>
<listitem> <listitem>
<para> <para>
Name of the configuration that should be used for collection caches. Name of the configuration that should be used for collection caches.
@ -419,7 +419,7 @@ hibernate.cache.region.factory_class=
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.ts</literal></term> <term><literal>hibernate.cache.jbc.cfg.timestamps</literal></term>
<listitem> <listitem>
<para> <para>
Name of the configuration that should be used for timestamp caches. Name of the configuration that should be used for timestamp caches.
@ -428,7 +428,7 @@ hibernate.cache.region.factory_class=
</listitem> </listitem>
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term><literal>hibernate.cache.region.jbc2.cfg.query</literal></term> <term><literal>hibernate.cache.jbc.cfg.query</literal></term>
<listitem> <listitem>
<para> <para>
Name of the configuration that should be used for query caches. Name of the configuration that should be used for query caches.
@ -442,7 +442,7 @@ hibernate.cache.region.factory_class=
<para> <para>
See <xref linkend="sessionfactory-multiplexed"/> for a discussion of 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. options combine to determine what JBoss Cache instances are used.
</para> </para>
@ -456,6 +456,31 @@ hibernate.cache.region.factory_class=
</para> </para>
</sect2> </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> </sect1>
@ -497,8 +522,8 @@ hibernate.cache.region.factory_class=
If you are using <literal>MultiplexedJBossCacheRegionFactory</literal> If you are using <literal>MultiplexedJBossCacheRegionFactory</literal>
you will need to provide a set of JBoss Cache configurations for you will need to provide a set of JBoss Cache configurations for
its <literal>CacheManager</literal> to use. (Or, use the set in the its <literal>CacheManager</literal> to use. (Or, use the set in the
<literal>jbc2-configs.xml</literal> file that ships with <literal>jbc-configs.xml</literal> file that ships with
<literal>hibernate-jbosscache2.jar</literal>.) The XML file used <literal>hibernate-jbosscache.jar</literal>.) The XML file used
by a <literal>CacheManager</literal> is very similar to the by a <literal>CacheManager</literal> is very similar to the
usual config file used by a standalone cache; the biggest usual config file used by a standalone cache; the biggest
difference is it can include multiple, named, configurations. difference is it can include multiple, named, configurations.
@ -510,10 +535,10 @@ hibernate.cache.region.factory_class=
<cache-configs> <cache-configs>
<!-- A config appropriate for entity/collection caching. --> <!-- A config appropriate for entity/collection caching. -->
<cache-config name="optimistic-entity"> <cache-config name="mvcc-entity">
<!-- Node locking scheme --> <!-- Node locking scheme -->
<attribute name="NodeLockingScheme">OPTIMISTIC</attribute> <attribute name="NodeLockingScheme">MVCC</attribute>
..... other configuration attributes ..... other configuration attributes
@ -595,10 +620,10 @@ hibernate.cache.region.factory_class=
</para> </para>
<programlisting><![CDATA[<!-- Node locking scheme: <programlisting><![CDATA[<!-- Node locking scheme:
OPTIMISTIC MVCC
PESSIMISTIC (default) PESSIMISTIC (default)
--> -->
<attribute name="NodeLockingScheme">OPTIMISTIC</attribute>]]></programlisting> <attribute name="NodeLockingScheme">MVCC</attribute>]]></programlisting>
</sect3> </sect3>
@ -723,7 +748,7 @@ hibernate.cache.region.factory_class=
<para> <para>
Region based marshalling is enabled in the standard cache Region based marshalling is enabled in the standard cache
configurations that ship with configurations that ship with
<literal>hibernate-jbosscache2.jar</literal> <literal>hibernate-jbosscache.jar</literal>
</para> </para>
</sect3> </sect3>
@ -743,8 +768,8 @@ hibernate.cache.region.factory_class=
<para> <para>
Hibernate ships with a number of standard JBoss Cache configurations Hibernate ships with a number of standard JBoss Cache configurations
in the <literal>hibernate-jbosscache2.jar</literal>'s in the <literal>hibernate-jbosscache.jar</literal>'s
<literal>jbc2-configs.xml</literal> file. The following table <literal>jbc-configs.xml</literal> file. The following table
highlights the key features of each configuration. highlights the key features of each configuration.
</para> </para>
@ -768,6 +793,26 @@ hibernate.cache.region.factory_class=
</row> </row>
</thead> </thead>
<tbody> <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> <row>
<entry> <entry>
<property>optimistic-entity</property> <property>optimistic-entity</property>
@ -776,7 +821,7 @@ hibernate.cache.region.factory_class=
<property>E/C/Q</property> <property>E/C/Q</property>
</entry> </entry>
<entry> <entry>
<property>E/C/Q</property> <property>--</property>
</entry> </entry>
<entry> <entry>
<property>INVALIDATION_SYNC</property> <property>INVALIDATION_SYNC</property>
@ -796,7 +841,7 @@ hibernate.cache.region.factory_class=
<property>E/C/Q</property> <property>E/C/Q</property>
</entry> </entry>
<entry> <entry>
<property>E/C/Q</property> <property>--</property>
</entry> </entry>
<entry> <entry>
<property>INVALIDATION_SYNC</property> <property>INVALIDATION_SYNC</property>
@ -822,7 +867,7 @@ hibernate.cache.region.factory_class=
<property>LOCAL</property> <property>LOCAL</property>
</entry> </entry>
<entry> <entry>
<property>PESSIMISTIC</property> <property>MVCC</property>
</entry> </entry>
<entry> <entry>
<para>no</para> <para>no</para>
@ -842,7 +887,7 @@ hibernate.cache.region.factory_class=
<property>LOCAL</property> <property>LOCAL</property>
</entry> </entry>
<entry> <entry>
<property>OPTIMISTIC</property> <property>MVCC</property>
</entry> </entry>
<entry> <entry>
<para>no</para> <para>no</para>
@ -862,7 +907,27 @@ hibernate.cache.region.factory_class=
<property>REPL_ASYNC</property> <property>REPL_ASYNC</property>
</entry> </entry>
<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>
<entry> <entry>
<para>yes</para> <para>yes</para>
@ -942,9 +1007,11 @@ hibernate.cache.region.factory_class=
</listitem> </listitem>
<listitem> <listitem>
<para> <para>
The configurations that use PESSIMISTIC locking use isolation level The configurations that use MVCC or PESSIMISTIC locking use isolation level
READ_COMMITTED. There are also two other standard configurations READ_COMMITTED. There are also four other standard configurations
not shown in the table that use REPEATABLE_READ: 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-entity-repeatable</literal> and
<literal>pessimistic-shared-repeatable</literal>. In all other <literal>pessimistic-shared-repeatable</literal>. In all other
respects those configurations are the same as the similarly named respects those configurations are the same as the similarly named
@ -977,7 +1044,7 @@ hibernate.cache.region.factory_class=
<para> <para>
The <literal>jgroups-stacks.xml</literal> file found in the The <literal>jgroups-stacks.xml</literal> file found in the
<literal>org.hibernate.cache.jbc.builder</literal> package <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 set of standard JGroups configurations; these should be suitable for
most needs. If you need to create your own configuration set, we most needs. If you need to create your own configuration set, we
recommend that you start with this file as a base. 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 since maintaining cache consistency means many messages need to
be sent to all members. UDP-based channel configurations are be sent to all members. UDP-based channel configurations are
used in the JBoss Cache configurations in the standard 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. Hibernate.
</para> </para>
</listitem> </listitem>
@ -1050,7 +1117,7 @@ hibernate.cache.region.factory_class=
<para> <para>
The TCP-based configurations in the The TCP-based configurations in the
<literal>jgroups-stacks.xml</literal> file found in <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 TCP + MPING. This is because there is no way for the
Hibernate authors to provide a meaningful static Hibernate authors to provide a meaningful static
configuration for TCPPING. If you want to use TCP + TCPPING 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"> <!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, ~ 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 ~ copy, or redistribute it subject to the terms and conditions of the GNU
@ -68,9 +68,9 @@
<sect2 id="introduction-requirements-dependencies" revision="1"> <sect2 id="introduction-requirements-dependencies" revision="1">
<title>Dependencies</title> <title>Dependencies</title>
<para> <para>
Second level caching with JBoss Cache 2 requires the use of JBoss Second level caching with JBoss Cache 3 requires the use of JBoss
Cache 2.1.0 or later. The core JBoss Cache project is used; the Cache 3.1.0 or later. The core JBoss Cache project is used; the
related PojoCache project/library is not needed. The following jars, related POJO Cache project/library is not needed. The following jars,
included with the JBoss Cache distribution, need to be on the classpath: included with the JBoss Cache distribution, need to be on the classpath:
</para> </para>
@ -88,7 +88,7 @@
</para> </para>
<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. the Hibernate distribution also needs to be on the classpath.
</para> </para>
@ -97,9 +97,9 @@
file<footnote><para><ulink url="http://labs.jboss.org/jgroups">JGroups</ulink> file<footnote><para><ulink url="http://labs.jboss.org/jgroups">JGroups</ulink>
is the group communication library used by JBoss Cache for intra-cluster is the group communication library used by JBoss Cache for intra-cluster
communication.</para></footnote>, need to be on the classpath. The 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> 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. Cache and the <literal>jgroups-stacks.xml</literal> file is for JGroups.
See <xref linkend="jbc-config"/> and <xref linkend="jgroups-config"/> See <xref linkend="jbc-config"/> and <xref linkend="jgroups-config"/>
for more details on these files. Users can create their own versions for more details on these files. Users can create their own versions
@ -157,12 +157,12 @@
<listitem> <listitem>
<para> <para>
Tell Hibernate in your <literal>SessionFactory</literal> 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: Second Level Cache implementation:
</para> </para>
<programlisting><![CDATA[<![CDATA[hibernate.cache.region.factory_class= <programlisting><![CDATA[hibernate.cache.region.factory_class=
org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]>]]></programlisting> org.hibernate.cache.jbc.MultiplexedJBossCacheRegionFactory]]></programlisting>
<para> <para>
There are a number of values that can be provided for the There are a number of values that can be provided for the
@ -179,9 +179,9 @@
<para> <para>
Do not set the legacy <literal>hibernate.cache.provider_class</literal> 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 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> </para>
</listitem> </listitem>
@ -209,7 +209,7 @@
results replicated: results replicated:
</para> </para>
<programlisting><![CDATA[hibernate.cache.region.jbc2.query.localonly=true]]></programlisting> <programlisting><![CDATA[hibernate.cache.jbc.query.localonly=true]]></programlisting>
</listitem> </listitem>
</itemizedlist> </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"> <!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, ~ 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 ~ 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 caching libraries. This document is focused on the use of the
<ulink url="http://labs.jboss.org/jbosscache">JBoss Cache</ulink> <ulink url="http://labs.jboss.org/jbosscache">JBoss Cache</ulink>
clustered transactional caching library as an implementation of 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>
<para> <para>
@ -142,7 +142,7 @@
<listitem> <listitem>
<para> <para>
Use this guide as your primary source of information on the 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> </para>
</listitem> </listitem>
</orderedlist> </orderedlist>