8:20 a.m.
Author: epbernard
Date: 2010-02-18 09:20:36 -0500 (Thu, 18 Feb 2010)
New Revision: 18833
Modified:
core/trunk/annotations/src/main/docbook/en/master.xml
core/trunk/annotations/src/main/docbook/en/modules/additionalmodules.xml
core/trunk/annotations/src/main/docbook/en/modules/entity.xml
core/trunk/annotations/src/main/docbook/en/modules/setup.xml
Log:
HHH-4933 update non core annotatios doc
Modified: core/trunk/annotations/src/main/docbook/en/master.xml
===================================================================
--- core/trunk/annotations/src/main/docbook/en/master.xml 2010-02-18 12:47:31 UTC (rev
18832)
+++ core/trunk/annotations/src/main/docbook/en/master.xml 2010-02-18 14:20:36 UTC (rev
18833)
@@ -23,9 +23,9 @@
~ Boston, MA 02110-1301 USA
-->
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
- <!ENTITY versionNumber "3.4.0.GA">
+ <!ENTITY versionNumber "3.5.0.GA">
<!ENTITY copyrightYear "2004">
- <!ENTITY copyrightHolder "Red Hat Middleware, LLC.">
+ <!ENTITY copyrightHolder "Red Hat Inc. and the various authors">
]>
<book lang="en">
<bookinfo>
@@ -40,6 +40,17 @@
<imagedata fileref="images/hibernate_logo_a.png"
format="png" />
</imageobject>
</mediaobject>
+ <copyright>
+ <year>©rightYear;</year>
+ <holder>©rightHolder;</holder>
+ </copyright>
+ <authorgroup>
+ <author>
+ <firstname>Emmanuel</firstname>
+ <surname>Bernard</surname>
+ </author>
+ <!--TODO add translators like core did -->
+ </authorgroup>
</bookinfo>
<toc/>
Modified: core/trunk/annotations/src/main/docbook/en/modules/additionalmodules.xml
===================================================================
--- core/trunk/annotations/src/main/docbook/en/modules/additionalmodules.xml 2010-02-18
12:47:31 UTC (rev 18832)
+++ core/trunk/annotations/src/main/docbook/en/modules/additionalmodules.xml 2010-02-18
14:20:36 UTC (rev 18833)
@@ -27,7 +27,7 @@
<chapter id="additionalmodules">
<title>Additional modules</title>
- <para>Hibernate Annotations mainly focus on persistence metadata. The
+ <para>Hibernate Annotations mainly focuses on persistence metadata. The
project also have a nice integration with some external modules.</para>
<section>
@@ -71,7 +71,7 @@
<para>To enable the Hibernate - Bean Validation integration, simply add
a Bean Validation provider (preferably Hibernate Validation 4) in your
- classpath. </para>
+ classpath.</para>
</section>
<section>
@@ -86,8 +86,9 @@
<para>You can customize the Bean Validation integration by setting the
validation mode. Use the
<literal>javax.persistence.validation.mode</literal> property and set
it
- up for example in your <filename>persistence.xml</filename> file.
- Several options are possible:</para>
+ up for example in your <filename>persistence.xml</filename> file or
your
+ <filename>hibernate.cfg.xml</filename> file. Several options are
+ possible:</para>
<itemizedlist>
<listitem>
@@ -200,12 +201,14 @@
<classname>ConstraintViolationException</classname> which exposes the
set of <classname>ConstraintViolation</classname>s.</para>
- <para>This exception is wrapped into an
- <classname>HibernateException</classname> or a
- <classname>PersistenceException</classname>. Note that generally,
- catchable violation are validated at a higher level (for example in Seam
- / JSF 2 via the JSF - Bean Validation integration or in your business
- layer by explicitly calling Bean Validation).</para>
+ <para>This exception is wrapped in a
+ <classname>RollbackException</classname> when the violation happens at
+ commit time. Otherwise the
+ <classname>ConstraintViolationException</classname> is returned (for
+ example when calling <methodname>flush()</methodname>. Note that
+ generally, catchable violations are validated at a higher level (for
+ example in Seam / JSF 2 via the JSF - Bean Validation integration or in
+ your business layer by explicitly calling Bean Validation).</para>
<para>An application code will rarely be looking for a
<classname>ConstraintViolationException</classname> raised by
Hibernate.
@@ -233,7 +236,7 @@
<listitem>
<para><classname>@Min</classname>,
<classname>@Max</classname> lead
- to column checks (like <code>value <= max</code>)
</para>
+ to column checks (like <code>value <=
max</code>)</para>
</listitem>
<listitem>
Modified: core/trunk/annotations/src/main/docbook/en/modules/entity.xml
===================================================================
--- core/trunk/annotations/src/main/docbook/en/modules/entity.xml 2010-02-18 12:47:31 UTC
(rev 18832)
+++ core/trunk/annotations/src/main/docbook/en/modules/entity.xml 2010-02-18 14:20:36 UTC
(rev 18833)
@@ -30,8 +30,8 @@
<sect1 id="entity-overview" revision="2">
<title>Intro</title>
- <para>This section covers EJB 3.0 (aka Java Persistence) entity
- annotations and Hibernate-specific extensions.</para>
+ <para>This section covers Java Persistence 2.0 mapping annotations as well
+ as Hibernate-specific extensions.</para>
</sect1>
<sect1 id="entity-mapping" revision="2">
@@ -2530,7 +2530,7 @@
<para>The default access type is determined from the position of the
<literal>@Id</literal> or <literal>@EmbeddedId</literal>
annotation in
- the entity hierarchy. </para>
+ the entity hierarchy.</para>
<note>
<para>The placement of annotations within a class hierarchy has to
@@ -2572,7 +2572,7 @@
<listitem>
<para>The access type is overriden for the annotated element, if
overriden on a class, all the properties of the given class
- inherit the access type. </para>
+ inherit the access type.</para>
</listitem>
<listitem>
@@ -2582,7 +2582,7 @@
getters are scanned for annotations, if the enitiy is marked as
<literal>(a)Access(AccessType.FIELD)</literal> or
<literal>@AccessType("field")</literal> respectively,
the fields
- are scanned for annotations. </para>
+ are scanned for annotations.</para>
</listitem>
</itemizedlist>
@@ -2731,11 +2731,11 @@
<literal>@Type</literal> annotation.</para>
<note>
- Package level annotations are placed in a file named
+ Package level annotations are placed in a file named
<filename>package-info.java</filename>
- in the appropriate package. Place your annotations before the package
declaration.
+ in the appropriate package. Place your annotations before the package
declaration.
</note>
<programlisting>
@@ -3938,4 +3938,4 @@
}</programlisting>
</sect2>
</sect1>
-</chapter>
+</chapter>
\ No newline at end of file
Modified: core/trunk/annotations/src/main/docbook/en/modules/setup.xml
===================================================================
--- core/trunk/annotations/src/main/docbook/en/modules/setup.xml 2010-02-18 12:47:31 UTC
(rev 18832)
+++ core/trunk/annotations/src/main/docbook/en/modules/setup.xml 2010-02-18 14:20:36 UTC
(rev 18833)
@@ -1,4 +1,4 @@
-<?xml version='1.0' encoding="UTF-8"?>
+<?xml version="1.0" encoding="UTF-8"?>
<!--
~ Hibernate, Relational Persistence for Idiomatic Java
~
@@ -22,8 +22,8 @@
~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA
-->
-
-<!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">
<chapter>
<title id="setup" revision="1">Setting up an annotations
project</title>
@@ -32,26 +32,30 @@
<itemizedlist>
<listitem>
- <para><ulink
url="http://www.hibernate.org/6.html">Download</ulink>
- and unpack the Hibernate Annotations distribution from the Hibernate
- website.</para>
+ <para>Make sure you have JDK 5.0 installed or above.</para>
</listitem>
<listitem>
- <para><emphasis>This release requires Hibernate Core 3.3 and
- above.</emphasis></para>
+ <para><ulink
url="http://www.hibernate.org/6.html">Download</ulink>
+ and unpack the Hibernate Core distribution from the Hibernate website.
+ Hibernate 3.5 and onward contains the Hibernate Annotation
+ jars.</para>
</listitem>
<listitem>
- <para>This release is known to work on Hibernate Core
3.3.0.SP1</para>
- </listitem>
+ <para>Alternatively add the following dependency in your dependency
+ manager (like Maven or Ivy). Here is an example</para>
- <listitem>
- <para>Make sure you have JDK 5.0 installed or above. You can of course
- continue using XDoclet and get some of the benefits of
- annotation-based metadata with older JDK versions. Note that this
- document only describes JDK 5.0 annotations and you have to refer to
- the XDoclet documentation for more information.</para>
+ <programlisting><project ...>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-core</artifactId>
+ <version>${hibernate-core-version}</version>
+ </dependency>
+ </dependencies>
+</project></programlisting>
</listitem>
</itemizedlist>
</section>
@@ -62,35 +66,74 @@
<para>First, set up your classpath (after you have created a new project
in your favorite IDE): <itemizedlist>
<listitem>
- <para>Copy all Hibernate3 core and required 3rd party library files
- (see lib/README.txt in Hibernate).</para>
+ <para>Copy all Hibernate3 core and required 3rd party library
+ files.</para>
</listitem>
<listitem>
<para>Copy <filename>hibernate-annotations.jar</filename>,
<filename>lib/hibernate-comons-annotations.jar</filename> and
- <filename>lib/ejb3-persistence.jar</filename> from the Hibernate
- Annotations distribution to your classpath as well.</para>
+ <filename>lib/hibernate-jpa-2.0-api.jar</filename> from the
+ distribution to your classpath as well.</para>
</listitem>
</itemizedlist></para>
- <para>If you wish to use <ulink
- url="http://validator.hibernate.org">Hibernate Validator</ulink>,
download
- it from the Hibernate website and add
- <filename>hibernate-validator.jar</filename> in your
classpath.</para>
+ <para>Alternatively, import your pom.xml in your favorite IDE and let the
+ dependencies be resolved automatically,</para>
+ <note>
+ <title>What is hibernate-jpa-2.0-api-x.y.z.jar</title>
+
+ <para>This is the JAR containing the JPA 2.0 API, it is fully compliant
+ with the spec and passed the TCK signature test. You typically don't
+ need it when you deploy your application in a Java EE 6 application
+ server (like JBoss AS 6 for example).</para>
+ </note>
+
+ <para>We recommend you use <ulink
+ url="http://validator.hibernate.org">Hibernate Validator</ulink>
and the
+ Bean VAlidation specification capabilities. Download Hibernate Validator 4
+ or above from the Hibernate website and add
+ <filename>hibernate-validator.jar</filename> and
+ <filename>validation-api.jar</filename> in your classpath. Alternatively
+ add the following dependency in your
+ <filename>pom.xml</filename>.<programlisting><project
...>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-validator</artifactId>
+ <version>${hibernate-validator-version}</version>
+ </dependency>
+ </dependencies>
+</project></programlisting></para>
+
<para>If you wish to use <ulink
url="http://search.hibernate.org">Hibernate Search</ulink>,
download it
from the Hibernate website and add
<filename>hibernate-search.jar</filename> and
- <filename>lucene-core-x.y.z.jar</filename> in your
classpath.</para>
+ <filename>lucene-core-x.y.z.jar</filename> in your classpath.
+ Alternatively add the following dependency in your
+ <filename>pom.xml</filename>.<programlisting><project
...>
+ ...
+ <dependencies>
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-search</artifactId>
+ <version>${hibernate-search-version}</version>
+ </dependency>
+ </dependencies>
+</project></programlisting></para>
- <para>We also recommend a small wrapper class to startup Hibernate in a
- static initializer block, known as <classname>HibernateUtil</classname>.
- You might have seen this class in various forms in other areas of the
- Hibernate documentation. For Annotation support you have to enhance this
- helper class as follows: <programlisting>package hello;
+ <para>We recommend you use the JPA 2 APIs to bootstrap Hibernate (see the
+ Hibernate EntityManager documentation for more information). If you use
+ Hibernate Core and its native APIs read on.</para>
+ <para>If you boot Hibernate yourself, make sure to use the
+ <classname>AnnotationConfiguration</classname> class instead of the
+ <classname>Configuration</classname> class. Here is an example using the
+ (legacy) <classname>HibernateUtil</classname> approach:
<programlisting>package hello;
+
import org.hibernate.*;
import org.hibernate.cfg.*;
import test.*;
@@ -128,51 +171,50 @@
"-//Hibernate/Hibernate Configuration DTD 3.0//EN"
"http://hibernate.sourceforge.net/hibernate-configuration-3.0.dtd">
- <hibernate-configuration>
- <session-factory>
- <emphasis role="bold"><mapping
package="test.animals"/>
- <mapping class="test.Flight"/>
- <mapping class="test.Sky"/>
- <mapping class="test.Person"/>
- <mapping class="test.animals.Dog"/></emphasis>
-<emphasis role="bold"> <mapping
resource="test/animals/orm.xml"/></emphasis>
- </session-factory>
- </hibernate-configuration>
- </programlisting>
+<hibernate-configuration>
+ <session-factory>
+ <emphasis role="bold"><mapping
package="test.animals"/>
+ <mapping class="test.Flight"/>
+ <mapping class="test.Sky"/>
+ <mapping class="test.Person"/>
+ <mapping class="test.animals.Dog"/></emphasis>
+<emphasis role="bold"> <mapping
resource="test/animals/orm.xml"/></emphasis>
+ </session-factory>
+</hibernate-configuration> </programlisting>
- <para>Note that you can mix the hbm.xml use and the new annotation one.
- The resource element can be either an hbm file or an EJB3 XML deployment
- descriptor. The distinction is transparent for your configuration
- process.</para>
+ <para>Note that you can mix the legacy hbm.xml use and the annotation
+ approach. The resource element can be either an hbm file or an EJB3 XML
+ deployment descriptor. The distinction is transparent for your
+ configuration process.</para>
<para>Alternatively, you can define the annotated classes and packages
using the programmatic API</para>
- <programlisting> sessionFactory = new <emphasis
role="bold">AnnotationConfiguration()
+ <programlisting>sessionFactory = new <emphasis
role="bold">AnnotationConfiguration()
.addPackage("test.animals") //the fully qualified package
name
.addAnnotatedClass(Flight.class)
.addAnnotatedClass(Sky.class)
.addAnnotatedClass(Person.class)
.addAnnotatedClass(Dog.class)</emphasis>
<emphasis role="bold">
.addResource("test/animals/orm.xml")</emphasis>
- configure()..buildSessionFactory();</programlisting>
+ .configure()
+ .buildSessionFactory();</programlisting>
- <para>You can also use the Hibernate EntityManager which has its own
- configuration mechanism. Please refer to this project documentation for
- more details.</para>
-
<para>There is no other difference in the way you use Hibernate APIs with
annotations, except for this startup routine change or in the
configuration file. You can use your favorite configuration method for
other properties ( <filename>hibernate.properties</filename>,
- <filename>hibernate.cfg.xml</filename>, programmatic APIs, etc). You can
- even mix annotated persistent classes and classic
- <filename>hbm.cfg.xml</filename> declarations with the same
- <classname>SessionFactory</classname>. You can however not declare a
class
- several times (whether annotated or through hbm.xml). You cannot mix
- configuration strategies (hbm vs annotations) in a mapped entity hierarchy
- either.</para>
+ <filename>hibernate.cfg.xml</filename>, programmatic APIs, etc).
</para>
+ <note>
+ <para>You can mix annotated persistent classes and classic
+ <filename>hbm.cfg.xml</filename> declarations with the same
+ <classname>SessionFactory</classname>. You can however not declare a
+ class several times (whether annotated or through hbm.xml). You cannot
+ mix configuration strategies (hbm vs annotations) in an entity hierarchy
+ either.</para>
+ </note>
+
<para>To ease the migration process from hbm files to annotations, the
configuration mechanism detects the mapping duplication between
annotations and hbm files. HBM files are then prioritized over annotated
@@ -186,8 +228,48 @@
<section>
<title id="setup-properties">Properties</title>
- <para>Asides from the Hibernate core properties, Hibernate Annotations
- reacts to the following one</para>
+ <para>On top of the Hibernate Core properties, Hibernate Annotations
+ reacts to the following one.<table>
+ <title>Hibernate Annotations specific properties</title>
+
+ <tgroup cols="2">
+ <thead>
+ <row>
+ <entry align="center">Property</entry>
+
+ <entry align="center">Function</entry>
+ </row>
+ </thead>
+
+ <tbody>
+ <row>
+
<entry><literal>hibernate.cache.default_cache_concurrency_strategy</literal></entry>
+
+ <entry><para>Setting used to give the name of the default
+
<classname>org.hibernate.annotations.CacheConcurrencyStrategy</classname>
+ to use when either <classname>@Cacheable</classname>
+ <classname>@Cache</classname>} is used.
+ <classname>@Cache(strategy="..")</classname> is used
to override
+ this default.</para></entry>
+ </row>
+
+ <row>
+
<entry><literal>hibernate.id.new_generator_mappings</literal></entry>
+
+ <entry><para>true or false. Setting which indicates whether or
+ not the new <classname>IdentifierGenerator</classname>
+ implementations are used for AUTO, TABLE and SEQUENCE. Default
+ to false to keep backward compatibility.</para></entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table><note>
+ <para>We recommend all new projects to use
+ <code>hibernate.id.new_generator_mappings=true</code> as the new
+ generators are more efficient and closer to the JPA 2 specification
+ semantic. However they are not backward compatible with existing
+ databases (if a sequence or a table is used for id generation).</para>
+ </note></para>
</section>
<section>
@@ -235,4 +317,4 @@
url="http://www.hibernate.org/hib_docs/v3/reference/en/html_single/#...
in the Hibernate Core documentation.</para>
</section>
-</chapter>
+</chapter>
\ No newline at end of file