[hibernate-commits] Hibernate SVN: r17672 - in core/trunk/documentation/jbosscache2: src/main/docbook/en-US and 1 other directories.

Author: bstansberry(a)jboss.com Date: 2009-10-08 23:56:07 -0400 (Thu, 08 Oct 2009) New Revision: 17672 Added: core/trunk/documentation/jbosscache2/.settings/ core/trunk/documentation/jbosscache2/src/main/docbook/en-US/Hibernate_JBC_Reference.xml Removed: core/trunk/documentation/jbosscache2/src/main/docbook/en-US/Hibernate_JBC2_Reference.xml Modified: core/trunk/documentation/jbosscache2/pom.xml core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/concepts.xml core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/configuration.xml core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/introduction.xml core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/preface.xml Log: Update for use with JBC 3 Modified: core/trunk/documentation/jbosscache2/pom.xml =================================================================== --- core/trunk/documentation/jbosscache2/pom.xml 2009-10-09 02:59:30 UTC (rev 17671) +++ core/trunk/documentation/jbosscache2/pom.xml 2009-10-09 03:56:07 UTC (rev 17672) @@ -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> Deleted: core/trunk/documentation/jbosscache2/src/main/docbook/en-US/Hibernate_JBC2_Reference.xml =================================================================== --- core/trunk/documentation/jbosscache2/src/main/docbook/en-US/Hibernate_JBC2_Reference.xml 2009-10-09 02:59:30 UTC (rev 17671) +++ core/trunk/documentation/jbosscache2/src/main/docbook/en-US/Hibernate_JBC2_Reference.xml 2009-10-09 03:56:07 UTC (rev 17672) @@ -1,61 +0,0 @@ -<?xml version='1.0' encoding="UTF-8"?> -<!-- - ~ Copyright (c) 2008, Red Hat Middleware, LLC. 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 - ~ Lesser General Public License, v. 2.1. This program is distributed in the - ~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied - ~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU - ~ Lesser General Public License for more details. You should have received a - ~ copy of the GNU Lesser General Public License, v.2.1 along with this - ~ distribution; if not, write to the Free Software Foundation, Inc., - ~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. - ~ - ~ 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."> -]> - -<book> - - <bookinfo> - <title>HIBERNATE - Relational Persistence for Idiomatic Java</title> - <subtitle>Using JBoss Cache 2 as a Hibernate Second Level Cache</subtitle> - <releaseinfo>&versionNumber;</releaseinfo> - <productnumber>&versionNumber;</productnumber> - <issuenum>1</issuenum> - <mediaobject> - <imageobject role="fo"> - <imagedata fileref="images/hibernate_logo_a.png" align="center" /> - </imageobject> - <imageobject role="html"> - <imagedata fileref="images/hibernate_logo_a.png" depth="3cm" /> - </imageobject> - </mediaobject> - <copyright> - <year>&copyrightYear;</year> - <holder>&copyrightHolder;</holder> - </copyright> - <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - <!-- include translators... --> - </bookinfo> - - <toc/> - - <xi:include href="content/preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="content/introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="content/concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="content/configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="content/eviction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> - - <xi:include href="content/architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -</book> - Copied: core/trunk/documentation/jbosscache2/src/main/docbook/en-US/Hibernate_JBC_Reference.xml (from rev 17643, core/trunk/documentation/jbosscache2/src/main/docbook/en-US/Hibernate_JBC2_Reference.xml) =================================================================== --- core/trunk/documentation/jbosscache2/src/main/docbook/en-US/Hibernate_JBC_Reference.xml (rev 0) +++ core/trunk/documentation/jbosscache2/src/main/docbook/en-US/Hibernate_JBC_Reference.xml 2009-10-09 03:56:07 UTC (rev 17672) @@ -0,0 +1,61 @@ +<?xml version='1.0' encoding="UTF-8"?> +<!-- + ~ Copyright (c) 2008, Red Hat Middleware, LLC. 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 + ~ Lesser General Public License, v. 2.1. This program is distributed in the + ~ hope that it will be useful, but WITHOUT A WARRANTY; without even the implied + ~ warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU + ~ Lesser General Public License for more details. You should have received a + ~ copy of the GNU Lesser General Public License, v.2.1 along with this + ~ distribution; if not, write to the Free Software Foundation, Inc., + ~ 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301, USA. + ~ + ~ 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.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 as a Hibernate Second Level Cache</subtitle> + <releaseinfo>&versionNumber;</releaseinfo> + <productnumber>&versionNumber;</productnumber> + <!--<issuenum>1</issuenum>--> + <mediaobject> + <imageobject role="fo"> + <imagedata fileref="images/hibernate_logo_a.png" align="center" /> + </imageobject> + <imageobject role="html"> + <imagedata fileref="images/hibernate_logo_a.png" depth="3cm" /> + </imageobject> + </mediaobject> + <copyright> + <year>&copyrightYear;</year> + <holder>&copyrightHolder;</holder> + </copyright> + <xi:include href="legal_notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + <!-- include translators... --> + </bookinfo> + + <toc/> + + <xi:include href="content/preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/introduction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/eviction.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="content/architecture.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> +</book> + Modified: core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/concepts.xml =================================================================== --- core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/concepts.xml 2009-10-09 02:59:30 UTC (rev 17671) +++ core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/concepts.xml 2009-10-09 03:56:07 UTC (rev 17672) @@ -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> Modified: core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/configuration.xml =================================================================== --- core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/configuration.xml 2009-10-09 02:59:30 UTC (rev 17671) +++ core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/configuration.xml 2009-10-09 03:56:07 UTC (rev 17672) @@ -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 @@ <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 @@ </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 @@ </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 @@ </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 @@ <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 @@ </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 @@ 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 @@ <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 @@ </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 @@ <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 @@ <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> @@ -770,7 +795,7 @@ <tbody> <row> <entry> - <property>optimistic-entity</property> + <property>mvcc-entity</property> </entry> <entry> <property>E/C/Q</property> @@ -782,6 +807,26 @@ <property>INVALIDATION_SYNC</property> </entry> <entry> + <property>MVCC</property> + </entry> + <entry> + <para>no</para> + </entry> + </row> + <row> + <entry> + <property>optimistic-entity</property> + </entry> + <entry> + <property>E/C/Q</property> + </entry> + <entry> + <property>--</property> + </entry> + <entry> + <property>INVALIDATION_SYNC</property> + </entry> + <entry> <property>OPTIMISTIC</property> </entry> <entry> @@ -796,7 +841,7 @@ <property>E/C/Q</property> </entry> <entry> - <property>E/C/Q</property> + <property>--</property> </entry> <entry> <property>INVALIDATION_SYNC</property> @@ -822,7 +867,7 @@ <property>LOCAL</property> </entry> <entry> - <property>PESSIMISTIC</property> + <property>MVCC</property> </entry> <entry> <para>no</para> @@ -842,7 +887,7 @@ <property>LOCAL</property> </entry> <entry> - <property>OPTIMISTIC</property> + <property>MVCC</property> </entry> <entry> <para>no</para> @@ -862,7 +907,7 @@ <property>REPL_ASYNC</property> </entry> <entry> - <property>PESSIMISTIC</property> + <property>MVCC</property> </entry> <entry> <para>yes</para> @@ -870,6 +915,26 @@ </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> + </entry> + </row> + <row> + <entry> <property>optimistic-shared</property> </entry> <entry> @@ -942,9 +1007,11 @@ </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 @@ <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 @@ 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 @@ <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 Modified: core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/introduction.xml =================================================================== --- core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/introduction.xml 2009-10-09 02:59:30 UTC (rev 17671) +++ core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/introduction.xml 2009-10-09 03:56:07 UTC (rev 17672) @@ -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> Modified: core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/preface.xml =================================================================== --- core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/preface.xml 2009-10-09 02:59:30 UTC (rev 17671) +++ core/trunk/documentation/jbosscache2/src/main/docbook/en-US/content/preface.xml 2009-10-09 03:56:07 UTC (rev 17672) @@ -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>