[hibernate-commits] Hibernate SVN: r18923 - in core/trunk: entitymanager/src/main/docbook/en and 1 other directories.

Author: epbernard Date: 2010-03-04 13:15:19 -0500 (Thu, 04 Mar 2010) New Revision: 18923 Modified: core/trunk/annotations/src/main/docbook/en/modules/setup.xml core/trunk/entitymanager/src/main/docbook/en/master.xml core/trunk/entitymanager/src/main/docbook/en/modules/architecture.xml core/trunk/entitymanager/src/main/docbook/en/modules/batch.xml core/trunk/entitymanager/src/main/docbook/en/modules/configuration.xml core/trunk/entitymanager/src/main/docbook/en/modules/entitymanagerapi.xml core/trunk/entitymanager/src/main/docbook/en/modules/listeners.xml core/trunk/entitymanager/src/main/docbook/en/modules/query_ejbql.xml core/trunk/entitymanager/src/main/docbook/en/modules/query_native.xml core/trunk/entitymanager/src/main/docbook/en/modules/transactions.xml Log: HHH-4933 Work on HEM doc, refreshing it for JPA 2. architecture and configuration refreshed Modified: core/trunk/annotations/src/main/docbook/en/modules/setup.xml =================================================================== --- core/trunk/annotations/src/main/docbook/en/modules/setup.xml 2010-03-03 22:37:31 UTC (rev 18922) +++ core/trunk/annotations/src/main/docbook/en/modules/setup.xml 2010-03-04 18:15:19 UTC (rev 18923) @@ -51,7 +51,7 @@ &lt;dependencies&gt; &lt;dependency&gt; &lt;groupId&gt;org.hibernate&lt;/groupId&gt; - &lt;artifactId&gt;hibernate-core&lt;/artifactId&gt; + &lt;artifactId&gt;hibernate-annotations&lt;/artifactId&gt; &lt;version&gt;${hibernate-core-version}&lt;/version&gt; &lt;/dependency&gt; &lt;/dependencies&gt; @@ -66,8 +66,8 @@ <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.</para> + <para>Copy <filename>hibernate-core.jar</filename> and required 3rd + party library files.</para> </listitem> <listitem> Modified: core/trunk/entitymanager/src/main/docbook/en/master.xml =================================================================== --- core/trunk/entitymanager/src/main/docbook/en/master.xml 2010-03-03 22:37:31 UTC (rev 18922) +++ core/trunk/entitymanager/src/main/docbook/en/master.xml 2010-03-04 18:15:19 UTC (rev 18923) @@ -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,80 +22,129 @@ ~ 51 Franklin Street, Fifth Floor ~ 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" [ +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" +"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [ <!ENTITY version "WORKING"> <!ENTITY today "TODAY"> ]> - <book> - <bookinfo> <title>Hibernate EntityManager</title> + <subtitle>User guide</subtitle> - <releaseinfo>&version;</releaseinfo> - <edition>1.0</edition> - <pubsnumber>1</pubsnumber> - <pubdate>&today;</pubdate> - <productnumber>&version;</productnumber> - <issuenum>1</issuenum> - <mediaobject> - <imageobject> - <imagedata fileref="images/hibernate_logo_a.png" format="PNG"/> - </imageobject> - </mediaobject> - <copyright> - <year>2005</year> - <holder>Red Hat Inc.</holder> - </copyright> + + <releaseinfo>&version;</releaseinfo> + + <edition>1.0</edition> + + <pubsnumber>1</pubsnumber> + + <pubdate>&today;</pubdate> + + <productnumber>&version;</productnumber> + + <issuenum>1</issuenum> + + <mediaobject> + <imageobject> + <imagedata fileref="images/hibernate_logo_a.png" format="PNG" /> + </imageobject> + </mediaobject> + + <copyright> + <year>2005</year> + + <holder>Red Hat Inc. and the various authors</holder> + </copyright> + + <authorgroup> + <author> + <firstname>Emmanuel</firstname> + + <surname>Bernard</surname> + </author> + + <author> + <firstname>Steve</firstname> + + <surname>Ebersole</surname> + </author> + + <!--TODO add translators like core did --> + </authorgroup> </bookinfo> - <toc/> + <toc></toc> + <preface> - <title>Introducing EJB3 Persistence</title> - <para>The EJB3 specification recognizes the interest and the success of - the transparent object/relational mapping paradigm. The EJB3 specification - standardizes the basic APIs and the metadata needed for any - object/relational persistence mechanism. - <emphasis>Hibernate EntityManager</emphasis> - implements the programming interfaces and - lifecycle rules as defined by the EJB3 persistence specification. Together - with<emphasis>Hibernate Annotations</emphasis>, this wrapper implements a - complete (and standalone) EJB3 persistence solution on top of the mature - Hibernate core. You may use a combination of all three together, - annotations without EJB3 programming interfaces and lifecycle, or even - pure native Hibernate, depending on the business and technical needs of - your project. You can at all times fall back to Hibernate native APIs, or - if required, even to native JDBC and SQL. - </para> + <title>Introducing JPA Persistence</title> + + <para>The JPA specification recognizes the interest and the success of the + transparent object/relational mapping paradigm. It standardizes the basic + APIs and the metadata needed for any object/relational persistence + mechanism. <emphasis>Hibernate EntityManager</emphasis> implements the + programming interfaces and lifecycle rules as defined by the JPA 2.0 + specification. Together with <emphasis>Hibernate Annotations</emphasis>, + this wrapper implements a complete (and standalone) JPA persistence + solution on top of the mature Hibernate Core. You may use a combination of + all three together, annotations without JPA programming interfaces and + lifecycle, or even pure native Hibernate Core, depending on the business + and technical needs of your project. You can at all times fall back to + Hibernate native APIs, or if required, even to native JDBC and SQL.</para> </preface> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/architecture.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/configuration.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/entitymanagerapi.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/metamodel.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/transactions.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/listeners.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/batch.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/query_ejbql.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/query_criteria.xml"/> - <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/query_native.xml"/> + <xi:include href="modules/architecture.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="modules/configuration.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="modules/entitymanagerapi.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="modules/metamodel.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="modules/transactions.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="modules/listeners.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="modules/batch.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="modules/query_ejbql.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="modules/query_criteria.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + + <xi:include href="modules/query_native.xml" + xmlns:xi="http://www.w3.org/2001/XInclude" /> + <bibliography> <title>References</title> + <biblioentry id="JPA2"> <abbrev id="JPA2_ABBREV">JPA 2 Specification</abbrev> - <title>JSR 317: <trademark>Java</trademark> Persistence API, Version 2.0 </title> + + <title>JSR 317: <trademark>Java</trademark> Persistence API, Version + 2.0</title> + <collab> <collabname>Java Persistence 2.0 Expert Group</collabname> </collab> + <copyright> <year>2009</year> + <holder>SUN MICROSYSTEMS, INC.</holder> </copyright> - <bibliomisc> - <email&gt;jsr-317-feedback(a)sun.com&lt;/email&gt; - <ulink url="http://jcp.org/en/jsr/detail?id=317">JSR 317 JCP Page</ulink> - </bibliomisc> + + <bibliomisc&gt;&lt;email&gt;jsr-317-feedback(a)sun.com&lt;/email&gt; <ulink + url="http://jcp.org/en/jsr/detail?id=317">JSR 317 JCP + Page</ulink></bibliomisc> </biblioentry> </bibliography> - </book> Modified: core/trunk/entitymanager/src/main/docbook/en/modules/architecture.xml =================================================================== --- core/trunk/entitymanager/src/main/docbook/en/modules/architecture.xml 2010-03-03 22:37:31 UTC (rev 18922) +++ core/trunk/entitymanager/src/main/docbook/en/modules/architecture.xml 2010-03-04 18:15:19 UTC (rev 18923) @@ -1,11 +1,11 @@ -<?xml version='1.0' encoding="UTF-8"?> +<?xml version="1.0" encoding="UTF-8"?> <!-- ~ Hibernate, Relational Persistence for Idiomatic Java ~ - ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ Copyright (c) 2010, Red Hat Inc or third-party contributors as ~ indicated by the @author tags or express copyright attribution ~ statements applied by the authors. All third-party contributions are - ~ distributed under license by Red Hat Middleware LLC. + ~ distributed under license by Red Hat Inc. ~ ~ 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,24 +22,23 @@ ~ 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 id="architecture"> <title>Architecture</title> <section> <title>Definitions</title> - <para>EJB3 is part of the Java EE 5.0 platform. Persistence in EJB3 is - available in EJB3 containers, as well as for standalone J2SE applications + <para>JPA 2 is part of the Java EE 6.0 platform. Persistence in JPA is + available in containers like EJB 3 or the more modern CDI (Java Context + and Dependency Injection), as well as in standalone Java SE applications that execute outside of a particular container. The following programming interfaces and artifacts are available in both environments.</para> <variablelist spacing="compact"> <varlistentry> - <term> - <literal>EntityManagerFactory</literal> - </term> + <term><literal>EntityManagerFactory</literal></term> <listitem> <para>An entity manager factory provides entity manager instances, @@ -52,9 +51,7 @@ </varlistentry> <varlistentry> - <term> - <literal>EntityManager</literal> - </term> + <term><literal>EntityManager</literal></term> <listitem> <para>The <literal>EntityManager</literal> API is used to access a @@ -128,7 +125,7 @@ </section> <section> - <title>EJB container environment</title> + <title>In container environment (eg. EJB 3)</title> <section> <title>Container-managed entity manager</title> @@ -170,16 +167,16 @@ <para>The most common case is to bind the persistence context scope to the current transaction scope. This is only doable when JTA transactions are used: the persistence context is associated with the JTA transaction - life cycle. When a entity manager is invoked, the persistence context is - also opened, if there is no persistence context associated with the + life cycle. When an entity manager is invoked, the persistence context + is also opened, if there is no persistence context associated with the current JTA transaction. Otherwise, the associated persistence context is used. The persistence context ends when the JTA transaction completes. This means that during the JTA transaction, an application will be able to work on managed entities of the same persistence context. In other words, you don't have to pass the entity manager's - persistence context across your EJB method calls, but simply use - dependency injection or lookup whenever you need an entity - manager.</para> + persistence context across your managed beans (CDI) or EJBs method + calls, but simply use dependency injection or lookup whenever you need + an entity manager.</para> <para>You can also use an extended persistence context. This can be combined with stateful session beans, if you use a container-managed @@ -194,16 +191,18 @@ view of the application user, and implement it using an extended persistence context. Please refer to the Hibernate reference manual or the book Hibernate In Action for more information about this pattern. - JBoss Seam is a framework that link together JSF and EJB3 around the - notion of conversation and unit of work. For an application-managed + </para> + + <para>JBoss Seam 3 is built on top of CDI and has at it's core concept + the notion of conversation and unit of work. For an application-managed entity manager the persistence context is created when the entity manager is created and kept until the entity manager is closed. In an extended persistence context, all modification operations (persist, merge, remove) executed outside a transaction are queued until the persistence context is attached to a transaction. The transaction typically occurs at the user process end, allowing the whole process to - be commited or rollbacked. For application-managed entity manager only - support the exctended persistence context.</para> + be committed or rollbacked. For application-managed entity manager only + support the extended persistence context.</para> <para>A resource-local entity manager or an entity manager created with <literal>EntityManagerFactory.createEntityManager()</literal> @@ -235,7 +234,8 @@ <para>If a stateless session bean, message-driven bean, or stateful session bean with a transaction-scoped persistence context calls a stateful session bean with an extended persistence context in the - same JTA transaction, an IllegalStateException is thrown.</para> + same JTA transaction, an + <classname>IllegalStateException</classname> is thrown.</para> </listitem> <listitem> @@ -265,7 +265,7 @@ <para>If a stateful session bean with an extended persistence context calls a stateful session bean with a different extended persistence context in the same transaction, an - IllegalStateException is thrown.</para> + <classname>IllegalStateException</classname> is thrown.</para> </listitem> </itemizedlist> </section> @@ -274,7 +274,7 @@ <section id="architecture-javase" revision="1"> <title>Java SE environments</title> - <para>In a Java SE environment only extented context application-managed + <para>In a Java SE environment only extended context application-managed entity managers are available. You can retrieve an entity manger using the <literal>EntityManagerFactory</literal> API. Only resource-local entity managers are available. In other words, JTA transactions and persistence @@ -288,4 +288,4 @@ closed when the entity manager is closed. Many resource-local transaction share the same persistence context, in this case.</para> </section> -</chapter> \ No newline at end of file +</chapter> Modified: core/trunk/entitymanager/src/main/docbook/en/modules/batch.xml =================================================================== --- core/trunk/entitymanager/src/main/docbook/en/modules/batch.xml 2010-03-03 22:37:31 UTC (rev 18922) +++ core/trunk/entitymanager/src/main/docbook/en/modules/batch.xml 2010-03-04 18:15:19 UTC (rev 18923) @@ -2,10 +2,10 @@ <!-- ~ Hibernate, Relational Persistence for Idiomatic Java ~ - ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ Copyright (c) 2008, Red Hat Inc or third-party contributors as ~ indicated by the @author tags or express copyright attribution ~ statements applied by the authors. All third-party contributions are - ~ distributed under license by Red Hat Middleware LLC. + ~ distributed under license by Red Hat Inc. ~ ~ 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 Modified: core/trunk/entitymanager/src/main/docbook/en/modules/configuration.xml =================================================================== --- core/trunk/entitymanager/src/main/docbook/en/modules/configuration.xml 2010-03-03 22:37:31 UTC (rev 18922) +++ core/trunk/entitymanager/src/main/docbook/en/modules/configuration.xml 2010-03-04 18:15:19 UTC (rev 18923) @@ -1,11 +1,11 @@ -<?xml version='1.0' encoding="UTF-8"?> +<?xml version="1.0" encoding="UTF-8"?> <!-- ~ Hibernate, Relational Persistence for Idiomatic Java ~ - ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ Copyright (c) 2008, Red Hat Inc or third-party contributors as ~ indicated by the @author tags or express copyright attribution ~ statements applied by the authors. All third-party contributions are - ~ distributed under license by Red Hat Middleware LLC. + ~ distributed under license by Red Hat Inc. ~ ~ 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,22 +22,64 @@ ~ 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 id="configuration"> <title id="setup">Setup and configuration</title> <section> <title>Setup</title> - <para>The EJB 3.0 / JPA compatible Hibernate EntityManager is built on top - of Hibernate core and Hibernate Annotations. You have to use compatible - versions of each module. Please consult the compatibility matrix in the - hibernate.org download section. The following libraries have to be in your - classpath: hibernate3.jar, hibernate-annotations.jar, + <para>The JPA 2.0 compatible Hibernate EntityManager is built on top of + the core of Hibernate and Hibernate Annotations. Starting from version + 3.5, we have bundled in a single Hibernate distribution all the necessary + modules:</para> + + <itemizedlist> + <listitem> + <para>Hibernate Core: the native Hibernate APIs and core engine</para> + </listitem> + + <listitem> + <para>Hibernate Annotations: the annotation-based mapping</para> + </listitem> + + <listitem> + <para>Hibernate EntityManager: the JPA 2.0 APIs and livecycle semantic + implementation</para> + </listitem> + </itemizedlist> + + <para>The following libraries have to be in your classpath: + hibernate-core.jar, hibernate-annotations.jar, hibernate-commons-annotations.jar, hibernate-entitymanager.jar and all needed third party libraries for each package (incl. - ejb-persistence.jar).</para> + hibernate-jpa-2.0-api.jar).</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>If you use Maven, add the following dependencies</para> + + <programlisting>&lt;project ...&gt; + ... + &lt;dependencies&gt; + &lt;dependency&gt; + &lt;groupId&gt;org.hibernate&lt;/groupId&gt; + &lt;artifactId&gt;hibernate-entitymanager&lt;/artifactId&gt; + &lt;version&gt;${hibernate-core-version}&lt;/version&gt; + &lt;/dependency&gt; + &lt;/dependencies&gt; +&lt;/project&gt;</programlisting> + + <para>All the required dependencies like hibernate-core and + hibernate-annotations will be dragged transitively.</para> </section> <section id="setup-configuration" @@ -52,16 +94,16 @@ A persistence archive is a JAR file which must define a <literal>persistence.xml</literal> file that resides in the <filename>META-INF</filename> folder. All properly annotated classes - included in the archive (ie having an <literal>@Entity</literal> + included in the archive (ie. having an <literal>@Entity</literal> annotation), all annotated packages and all Hibernate hbm.xml files included in the archive will be added to the persistence unit configuration, so by default, your persistence.xml will be quite minimalist:</para> <programlisting>&lt;persistence xmlns="http://java.sun.com/xml/ns/persistence" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" - version="1.0"&gt; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd" + version="2.0"&gt; &lt;persistence-unit name="sample"&gt; &lt;jta-data-source&gt;java:/DefaultDS&lt;/jta-data-source&gt; &lt;properties&gt; @@ -75,9 +117,9 @@ <filename><literal>persistence.xml</literal></filename> file</para> <programlisting>&lt;persistence xmlns="http://java.sun.com/xml/ns/persistence" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" - version="1.0"&gt; + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd" + version="2.0"&gt; &lt;persistence-unit name="manager1" transaction-type="JTA"&gt; &lt;provider&gt;org.hibernate.ejb.HibernatePersistence&lt;/provider&gt; &lt;jta-data-source&gt;java:/DefaultDS&lt;/jta-data-source&gt; @@ -86,6 +128,8 @@ &lt;class&gt;org.acme.Employee&lt;/class&gt; &lt;class&gt;org.acme.Person&lt;/class&gt; &lt;class&gt;org.acme.Address&lt;/class&gt; + &lt;shared-cache-mode&gt;ENABLE_SELECTOVE&lt;/shared-cache-mode&gt; + &lt;validation-mode&gt;CALLBACK&lt;/validation-mode&gt; &lt;properties&gt; &lt;property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/&gt; &lt;property name="hibernate.hbm2ddl.auto" value="create-drop"/&gt; @@ -199,6 +243,100 @@ </varlistentry> <varlistentry> + <term>shared-cache-mode</term> + + <listitem> + <para>By default, entities are elected for second-level cache if + annotated with <classname>@Cacheable</classname>. You can + however:</para> + + <itemizedlist> + <listitem> + <para><literal>ALL</literal>: force caching for all + entities</para> + </listitem> + + <listitem> + <para><literal>NONE</literal>: disable caching for all + entities (useful to take second-level cache out of the + equation)</para> + </listitem> + + <listitem> + <para><literal>ENABLE_SELECTIVE</literal> (default): enable + caching when explicitly marked</para> + </listitem> + + <listitem> + <para><literal>DISABLE_SELECTIVE</literal>: enable caching + unless explicitly marked as + <classname>@Cacheable(false)</classname> (not + recommended)</para> + </listitem> + </itemizedlist> + + <para> See Hibernate Annotation's documentation for more + details.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term>validation-mode</term> + + <listitem> + <para>By default, Bean Validation (and Hibernate Validator) is + activated. When an entity is created, updated (and optionally + deleted), it is validated before being sent to the database. The + database schema generated by Hibernate also reflects the + constraints declared on the entity.</para> + + <para>You can fine-tune that if needed:</para> + + <itemizedlist> + <listitem> + <para><literal>AUTO</literal>: if Bean Validation is present + in the classpath, CALLBACK and DDL are activated.</para> + </listitem> + + <listitem> + <para><literal>CALLBACK</literal>: entities are validated on + creation, update and deletion. If no Bean Validation provider + is present, an exception is raised at initialization + time.</para> + </listitem> + + <listitem> + <para><literal>DDL</literal>: (not standard, see below) + database schemas are entities are validated on creation, + update and deletion. If no Bean Validation provider is + present, an exception is raised at initialization time.</para> + </listitem> + + <listitem> + <para><literal>NONE</literal>: Bean Validation is not used at + all</para> + </listitem> + </itemizedlist> + + <para>Unfortunately, <literal>DDL</literal> is not standard mode + (though extremely useful) and you will not be able to put it in + <literal>&lt;validation-mode&gt;</literal>. To use it, add a + regular property</para> + + <programlisting>&lt;property name="javax.persistence.validation.mode"&gt; + ddl +&lt;/property&gt;</programlisting> + + <para>With this approach, you can mix ddl and callback + modes:</para> + + <programlisting>&lt;property name="javax.persistence.validation.mode"&gt; + ddl, callback +&lt;/property&gt;</programlisting> + </listitem> + </varlistentry> + + <varlistentry> <term><code>properties</code></term> <listitem> @@ -206,63 +344,165 @@ properties. This is where you will define your Hibernate specific configurations. This is also where you will have to specify JDBC connection information as well.</para> + + <para>Here is a list of JPA 2 standard properties. Be sure to also + Hibernate Core's documentation to see Hibernate specific + properties.</para> + + <itemizedlist> + <listitem> + <para><literal>javax.persistence.lock.timeout</literal> + pessimistic lock timeout in milliseconds + (<classname>Integer</classname> or + <classname>String</classname>), this is a hint used by + Hibernate but requires support by your underlying + database.</para> + </listitem> + + <listitem> + <para><literal>javax.persistence.query.timeout</literal> query + timeout in milliseconds (<classname>Integer</classname> or + <classname>String</classname>), this is a hint used by + Hibernate but requires support by your underlying database + (TODO is that 100% true or do we use some other + tricks).</para> + </listitem> + + <listitem> + <para><literal>javax.persistence.validation.mode</literal> + corresponds to the <literal>validation-mode</literal> element. + Use it if you wish to use the non standard + <literal>DDL</literal> value.</para> + </listitem> + + <listitem> + <para>javax.persistence.validation.group.pre-persist defines + the group or list of groups to validate before persisting an + entity. This is a comma separated fully qualified class name + string (eg <code>com.acme.groups.Common</code> or + <code>com.acme.groups.Common, + javax.validation.groups.Default</code>)</para> + </listitem> + </itemizedlist> + + <note> + <para>To know more about Bean Validation and Hibernate + Validator, check out Hibernate Validator's reference + documentation as well as Hibernate Annotations's documentation + on Bean Validation.</para> + </note> + + <para>The following properties can only be used in a SE + environment where no datasource/JNDI is available:</para> + + <itemizedlist> + <listitem> + <para><literal>javax.persistence.jdbc.driver</literal>: the + fully qualified class name of the driver class</para> + </listitem> + + <listitem> + <para><literal>javax.persistence.jdbc.url</literal>: the + driver specific URL</para> + </listitem> + + <listitem> + <para><literal>javax.persistence.jdbc.user</literal> the user + name used for the database connection</para> + </listitem> + + <listitem> + <para><literal>javax.persistence.jdbc.password</literal> the + password used for the database connection</para> + </listitem> + </itemizedlist> </listitem> </varlistentry> </variablelist> <para>Be sure to define the grammar definition in the - <literal>persistence</literal> element since the EJB3 specification - requires the schema validation. If the systemId ends with - <literal>persistence_1_0.xsd</literal>, Hibernate entityManager will use - the version embedded in the hibernate-entitymanager.jar. No internet - access will be processed.</para> + <literal>persistence</literal> element since the JPA specification + requires schema validation. If the <literal>systemId</literal> ends with + <literal>persistence_2_0.xsd</literal>, Hibernate entityManager will use + the version embedded in the hibernate-entitymanager.jar. It won't fetch + the resource from the internet.</para> <programlisting>&lt;persistence xmlns="http://java.sun.com/xml/ns/persistence" - xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" - xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd" - version="1.0"&gt;</programlisting> + xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" + xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd" + version="2.0"&gt;</programlisting> </section> <section id="setup-configuration-bootstrapping" revision="1"> <title>Bootstrapping</title> - <para>The EJB3 specification defines a bootstrap procedure to access the + <para>The JPA specification defines a bootstrap procedure to access the <classname>EntityManagerFactory</classname> and the <classname>EntityManager</classname>. The bootstrap class is <classname>javax.persistence.Persistence</classname>, e.g.</para> <programlisting>EntityManagerFactory emf = Persistence.createEntityManagerFactory("manager1"); + //or -Map configOverrides = new HashMap(); + +Map&lt;String, Object&gt; configOverrides = new HashMap&lt;String, Object&gt;(); configOverrides.put("hibernate.hbm2ddl.auto", "create-drop"); EntityManagerFactory programmaticEmf = Persistence.createEntityManagerFactory("manager1", configOverrides);</programlisting> <para>The first version is equivalent to the second with an empty map. The map version is a set of overrides that will take precedence over any - properties defined in your persistence.xml files. There are a couple of - EJB3 properties usable in the map:</para> + properties defined in your <filename>persistence.xml</filename> files. + All the properties defined in <xref + linkend="setup-configuration-packaging" /> can be passed to the + <methodname>createEntityManagerFactory</methodname> method and there are + a few additional ones:</para> <itemizedlist> <listitem> - <para>javax.persistence.provider to define the provider class - used</para> + <para><literal>javax.persistence.provider</literal> to define the + provider class used</para> </listitem> <listitem> - <para>javax.persistence.transactionType to define the transaction - type used (either JTA or RESOURCE_LOCAL)</para> + <para><literal>javax.persistence.transactionType</literal> to define + the transaction type used (either <literal>JTA</literal> or + <literal>RESOURCE_LOCAL</literal>)</para> </listitem> <listitem> - <para>javax.persistence.jtaDataSource to define the JTA datasource - name in JNDI</para> + <para><literal>javax.persistence.jtaDataSource</literal> to define + the JTA datasource name in JNDI</para> </listitem> <listitem> - <para>javax.persistence.nonJtaDataSource to define the non JTA - datasource name in JNDI</para> + <para><literal>javax.persistence.nonJtaDataSource</literal> to + define the non JTA datasource name in JNDI</para> </listitem> + + <listitem> + <para><literal>javax.persistence.lock.timeout</literal> pessimistic + lock timeout in milliseconds (<classname>Integer</classname> or + <classname>String</classname>)</para> + </listitem> + + <listitem> + <para><literal>javax.persistence.query.timeout</literal> query + timeout in milliseconds (<classname>Integer</classname> or + <classname>String</classname>)</para> + </listitem> + + <listitem> + <para><literal>javax.persistence.sharedCache.mode</literal> + corresponds to the <literal>share-cache-mode</literal> element + defined in <xref linkend="setup-configuration-packaging" />.</para> + </listitem> + + <listitem> + <para><literal>javax.persistence.validation.mode</literal> + corresponds to the <literal>validation-mode</literal> element + defined in <xref linkend="setup-configuration-packaging" />.</para> + </listitem> </itemizedlist> <para>When <code>Persistence.createEntityManagerFactory()</code> is @@ -423,7 +663,7 @@ though.</para> </note> - <para>Here is a typical configuration in a J2SE environment</para> + <para>Here is a typical configuration in a Java SE environment</para> <programlisting>&lt;persistence&gt; &lt;persistence-unit name="manager1" transaction-type="RESOURCE_LOCAL"&gt; @@ -431,11 +671,11 @@ &lt;class&gt;org.hibernate.ejb.test.Distributor&lt;/class&gt; &lt;class&gt;org.hibernate.ejb.test.Item&lt;/class&gt; &lt;properties&gt; - &lt;property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/&gt; - &lt;property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver"/&gt; - &lt;property name="hibernate.connection.username" value="sa"/&gt; - &lt;property name="hibernate.connection.password" value=""/&gt; - &lt;property name="hibernate.connection.url" value="jdbc:hsqldb:."/&gt; + &lt;property name="<literal>javax.persistence.jdbc.driver</literal>" value="org.hsqldb.jdbcDriver"/&gt; + &lt;property name="<literal>javax.persistence.jdbc.user</literal>" value="sa"/&gt; + &lt;property name="<literal>javax.persistence.jdbc.password</literal>" value=""/&gt; + &lt;property name="<literal>javax.persistence.jdbc.url</literal>" value="jdbc:hsqldb:."/&gt; + &lt;property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/ &lt;property name="hibernate.max_fetch_depth" value="3"/&gt; &lt;!-- cache configuration --&gt; @@ -603,8 +843,8 @@ </tgroup> </table> - <para>Note that the JACC*EventListeners are removed if the security is not - enabled.</para> + <para>Note that the <classname>JACC*EventListeners</classname> are removed + if the security is not enabled.</para> <para>You can configure the event listeners either through the properties (see <xref linkend="setup-configuration" />) or through the @@ -636,12 +876,13 @@ manager factory is a wrapper on top of a session factory. Calls to the entityManagerFactory are thread safe.</para> - <para>Thanks to the EntityManagerFactory, you can retrieve an extended - entity manager. The extended entity manager keep the same persistence - context for the lifetime of the entity manager: in other words, the - entities are still managed between two transactions (unless you call - entityManager.clear() in between). You can see an entity manager as a - small wrapper on top of an Hibernate session.</para> + <para>Thanks to the <classname>EntityManagerFactory</classname>, you can + retrieve an extended entity manager. The extended entity manager keep the + same persistence context for the lifetime of the entity manager: in other + words, the entities are still managed between two transactions (unless you + call <methodname>entityManager.clear()</methodname> in between). You can + see an entity manager as a small wrapper on top of an Hibernate + session.</para> <para>TODO explains emf.createEntityManager(Map)</para> </section> @@ -655,4 +896,4 @@ be no performance cost. For more information on Hibernate Validator, please refer to the Hibernate Annotations reference guide.</para> </section> -</chapter> \ No newline at end of file +</chapter> Modified: core/trunk/entitymanager/src/main/docbook/en/modules/entitymanagerapi.xml =================================================================== --- core/trunk/entitymanager/src/main/docbook/en/modules/entitymanagerapi.xml 2010-03-03 22:37:31 UTC (rev 18922) +++ core/trunk/entitymanager/src/main/docbook/en/modules/entitymanagerapi.xml 2010-03-04 18:15:19 UTC (rev 18923) @@ -2,10 +2,10 @@ <!-- ~ Hibernate, Relational Persistence for Idiomatic Java ~ - ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ Copyright (c) 2008, Red Hat Inc or third-party contributors as ~ indicated by the @author tags or express copyright attribution ~ statements applied by the authors. All third-party contributions are - ~ distributed under license by Red Hat Middleware LLC. + ~ distributed under license by Red Hat Inc. ~ ~ 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 Modified: core/trunk/entitymanager/src/main/docbook/en/modules/listeners.xml =================================================================== --- core/trunk/entitymanager/src/main/docbook/en/modules/listeners.xml 2010-03-03 22:37:31 UTC (rev 18922) +++ core/trunk/entitymanager/src/main/docbook/en/modules/listeners.xml 2010-03-04 18:15:19 UTC (rev 18923) @@ -2,10 +2,10 @@ <!-- ~ Hibernate, Relational Persistence for Idiomatic Java ~ - ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ Copyright (c) 2008, Red Hat Inc or third-party contributors as ~ indicated by the @author tags or express copyright attribution ~ statements applied by the authors. All third-party contributions are - ~ distributed under license by Red Hat Middleware LLC. + ~ distributed under license by Red Hat Inc. ~ ~ 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 Modified: core/trunk/entitymanager/src/main/docbook/en/modules/query_ejbql.xml =================================================================== --- core/trunk/entitymanager/src/main/docbook/en/modules/query_ejbql.xml 2010-03-03 22:37:31 UTC (rev 18922) +++ core/trunk/entitymanager/src/main/docbook/en/modules/query_ejbql.xml 2010-03-04 18:15:19 UTC (rev 18923) @@ -2,10 +2,10 @@ <!-- ~ Hibernate, Relational Persistence for Idiomatic Java ~ - ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ Copyright (c) 2008, Red Hat Inc or third-party contributors as ~ indicated by the @author tags or express copyright attribution ~ statements applied by the authors. All third-party contributions are - ~ distributed under license by Red Hat Middleware LLC. + ~ distributed under license by Red Hat Inc. ~ ~ 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 Modified: core/trunk/entitymanager/src/main/docbook/en/modules/query_native.xml =================================================================== --- core/trunk/entitymanager/src/main/docbook/en/modules/query_native.xml 2010-03-03 22:37:31 UTC (rev 18922) +++ core/trunk/entitymanager/src/main/docbook/en/modules/query_native.xml 2010-03-04 18:15:19 UTC (rev 18923) @@ -2,10 +2,10 @@ <!-- ~ Hibernate, Relational Persistence for Idiomatic Java ~ - ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ Copyright (c) 2008, Red Hat Inc or third-party contributors as ~ indicated by the @author tags or express copyright attribution ~ statements applied by the authors. All third-party contributions are - ~ distributed under license by Red Hat Middleware LLC. + ~ distributed under license by Red Hat Inc. ~ ~ 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 Modified: core/trunk/entitymanager/src/main/docbook/en/modules/transactions.xml =================================================================== --- core/trunk/entitymanager/src/main/docbook/en/modules/transactions.xml 2010-03-03 22:37:31 UTC (rev 18922) +++ core/trunk/entitymanager/src/main/docbook/en/modules/transactions.xml 2010-03-04 18:15:19 UTC (rev 18923) @@ -2,10 +2,10 @@ <!-- ~ Hibernate, Relational Persistence for Idiomatic Java ~ - ~ Copyright (c) 2008, Red Hat Middleware LLC or third-party contributors as + ~ Copyright (c) 2008, Red Hat Inc or third-party contributors as ~ indicated by the @author tags or express copyright attribution ~ statements applied by the authors. All third-party contributions are - ~ distributed under license by Red Hat Middleware LLC. + ~ distributed under license by Red Hat Inc. ~ ~ 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