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

HHH-4933 Work on HEM doc, refreshing it for JPA 2. architecture and configuration refreshed 

git-svn-id: https://svn.jboss.org/repos/hibernate/core/trunk@18923 1b8cb986-b30d-0410-93ca-fae66ebed9b2
This commit is contained in:
Emmanuel Bernard 2010-03-04 18:15:19 +00:00
parent 0065a221a3
commit 5b595bcf26
10 changed files with 437 additions and 147 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
annotations/src/main/docbook/en/modules/setup.xml
View File

@ -51,7 +51,7 @@
<dependencies> <dependencies>
<dependency> <dependency>
<groupId>org.hibernate</groupId> <groupId>org.hibernate</groupId>
<artifactId>hibernate-core</artifactId> <artifactId>hibernate-annotations</artifactId>
<version>${hibernate-core-version}</version> <version>${hibernate-core-version}</version>
</dependency> </dependency>
</dependencies> </dependencies>
@ -66,8 +66,8 @@
<para>First, set up your classpath (after you have created a new project <para>First, set up your classpath (after you have created a new project
in your favorite IDE): <itemizedlist> in your favorite IDE): <itemizedlist>
<listitem> <listitem>
<para>Copy all Hibernate3 core and required 3rd party library <para>Copy <filename>hibernate-core.jar</filename> and required 3rd
files.</para> party library files.</para>
</listitem> </listitem>
<listitem> <listitem>

153
entitymanager/src/main/docbook/en/master.xml
View File

@ -1,4 +1,4 @@
<?xml version='1.0' encoding='UTF-8'?> <?xml version="1.0" encoding="UTF-8"?>
<!-- <!--
~ Hibernate, Relational Persistence for Idiomatic Java ~ Hibernate, Relational Persistence for Idiomatic Java
~ ~
@ -22,80 +22,129 @@
~ 51 Franklin Street, Fifth Floor ~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA ~ 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 version "WORKING">
<!ENTITY today "TODAY"> <!ENTITY today "TODAY">
]> ]>
<book> <book>
<bookinfo> <bookinfo>
<title>Hibernate EntityManager</title> <title>Hibernate EntityManager</title>
<subtitle>User guide</subtitle> <subtitle>User guide</subtitle>
<releaseinfo>&version;</releaseinfo>
<edition>1.0</edition> <releaseinfo>&version;</releaseinfo>
<pubsnumber>1</pubsnumber>
<pubdate>&today;</pubdate> <edition>1.0</edition>
<productnumber>&version;</productnumber>
<issuenum>1</issuenum> <pubsnumber>1</pubsnumber>
<mediaobject>
<imageobject> <pubdate>&today;</pubdate>
<imagedata fileref="images/hibernate_logo_a.png" format="PNG"/>
</imageobject> <productnumber>&version;</productnumber>
</mediaobject>
<copyright> <issuenum>1</issuenum>
<year>2005</year>
<holder>Red Hat Inc.</holder> <mediaobject>
</copyright> <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> </bookinfo>
<toc/> <toc></toc>
<preface> <preface>
<title>Introducing EJB3 Persistence</title> <title>Introducing JPA Persistence</title>
<para>The EJB3 specification recognizes the interest and the success of
the transparent object/relational mapping paradigm. The EJB3 specification <para>The JPA specification recognizes the interest and the success of the
standardizes the basic APIs and the metadata needed for any transparent object/relational mapping paradigm. It standardizes the basic
object/relational persistence mechanism. APIs and the metadata needed for any object/relational persistence
<emphasis>Hibernate EntityManager</emphasis> mechanism. <emphasis>Hibernate EntityManager</emphasis> implements the
implements the programming interfaces and programming interfaces and lifecycle rules as defined by the JPA 2.0
lifecycle rules as defined by the EJB3 persistence specification. Together specification. Together with <emphasis>Hibernate Annotations</emphasis>,
with<emphasis>Hibernate Annotations</emphasis>, this wrapper implements a this wrapper implements a complete (and standalone) JPA persistence
complete (and standalone) EJB3 persistence solution on top of the mature solution on top of the mature Hibernate Core. You may use a combination of
Hibernate core. You may use a combination of all three together, all three together, annotations without JPA programming interfaces and
annotations without EJB3 programming interfaces and lifecycle, or even lifecycle, or even pure native Hibernate Core, depending on the business
pure native Hibernate, depending on the business and technical needs of and technical needs of your project. You can at all times fall back to
your project. You can at all times fall back to Hibernate native APIs, or Hibernate native APIs, or if required, even to native JDBC and SQL.</para>
if required, even to native JDBC and SQL.
</para>
</preface> </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 href="modules/architecture.xml"
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/entitymanagerapi.xml"/> xmlns:xi="http://www.w3.org/2001/XInclude" />
<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 href="modules/configuration.xml"
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/listeners.xml"/> xmlns:xi="http://www.w3.org/2001/XInclude" />
<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 href="modules/entitymanagerapi.xml"
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/query_criteria.xml"/> xmlns:xi="http://www.w3.org/2001/XInclude" />
<xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="modules/query_native.xml"/>
<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> <bibliography>
<title>References</title> <title>References</title>
<biblioentry id="JPA2"> <biblioentry id="JPA2">
<abbrev id="JPA2_ABBREV">JPA 2 Specification</abbrev> <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> <collab>
<collabname>Java Persistence 2.0 Expert Group</collabname> <collabname>Java Persistence 2.0 Expert Group</collabname>
</collab> </collab>
<copyright> <copyright>
<year>2009</year> <year>2009</year>
<holder>SUN MICROSYSTEMS, INC.</holder> <holder>SUN MICROSYSTEMS, INC.</holder>
</copyright> </copyright>
<bibliomisc>
<email>jsr-317-feedback@sun.com</email> <bibliomisc><email>jsr-317-feedback@sun.com</email> <ulink
<ulink url="http://jcp.org/en/jsr/detail?id=317">JSR 317 JCP Page</ulink> url="http://jcp.org/en/jsr/detail?id=317">JSR 317 JCP
</bibliomisc> Page</ulink></bibliomisc>
</biblioentry> </biblioentry>
</bibliography> </bibliography>
</book> </book>

52
entitymanager/src/main/docbook/en/modules/architecture.xml
View File

@ -1,11 +1,11 @@
<?xml version='1.0' encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!-- <!--
~ Hibernate, Relational Persistence for Idiomatic Java ~ 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 ~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are ~ 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, ~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU ~ copy, or redistribute it subject to the terms and conditions of the GNU
@ -22,24 +22,23 @@
~ 51 Franklin Street, Fifth Floor ~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA ~ Boston, MA 02110-1301 USA
--> -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="architecture"> <chapter id="architecture">
<title>Architecture</title> <title>Architecture</title>
<section> <section>
<title>Definitions</title> <title>Definitions</title>
<para>EJB3 is part of the Java EE 5.0 platform. Persistence in EJB3 is <para>JPA 2 is part of the Java EE 6.0 platform. Persistence in JPA is
available in EJB3 containers, as well as for standalone J2SE applications 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 that execute outside of a particular container. The following programming
interfaces and artifacts are available in both environments.</para> interfaces and artifacts are available in both environments.</para>
<variablelist spacing="compact"> <variablelist spacing="compact">
<varlistentry> <varlistentry>
<term> <term><literal>EntityManagerFactory</literal></term>
<literal>EntityManagerFactory</literal>
</term>
<listitem> <listitem>
<para>An entity manager factory provides entity manager instances, <para>An entity manager factory provides entity manager instances,
@ -52,9 +51,7 @@
</varlistentry> </varlistentry>
<varlistentry> <varlistentry>
<term> <term><literal>EntityManager</literal></term>
<literal>EntityManager</literal>
</term>
<listitem> <listitem>
<para>The <literal>EntityManager</literal> API is used to access a <para>The <literal>EntityManager</literal> API is used to access a
@ -128,7 +125,7 @@
</section> </section>
<section> <section>
<title>EJB container environment</title> <title>In container environment (eg. EJB 3)</title>
<section> <section>
<title>Container-managed entity manager</title> <title>Container-managed entity manager</title>
@ -170,16 +167,16 @@
<para>The most common case is to bind the persistence context scope to <para>The most common case is to bind the persistence context scope to
the current transaction scope. This is only doable when JTA transactions the current transaction scope. This is only doable when JTA transactions
are used: the persistence context is associated with the JTA transaction are used: the persistence context is associated with the JTA transaction
life cycle. When a entity manager is invoked, the persistence context is life cycle. When an entity manager is invoked, the persistence context
also opened, if there is no persistence context associated with the is also opened, if there is no persistence context associated with the
current JTA transaction. Otherwise, the associated persistence context current JTA transaction. Otherwise, the associated persistence context
is used. The persistence context ends when the JTA transaction is used. The persistence context ends when the JTA transaction
completes. This means that during the JTA transaction, an application completes. This means that during the JTA transaction, an application
will be able to work on managed entities of the same persistence 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 context. In other words, you don't have to pass the entity manager's
persistence context across your EJB method calls, but simply use persistence context across your managed beans (CDI) or EJBs method
dependency injection or lookup whenever you need an entity calls, but simply use dependency injection or lookup whenever you need
manager.</para> an entity manager.</para>
<para>You can also use an extended persistence context. This can be <para>You can also use an extended persistence context. This can be
combined with stateful session beans, if you use a container-managed 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 view of the application user, and implement it using an extended
persistence context. Please refer to the Hibernate reference manual or persistence context. Please refer to the Hibernate reference manual or
the book Hibernate In Action for more information about this pattern. the book Hibernate In Action for more information about this pattern.
JBoss Seam is a framework that link together JSF and EJB3 around the </para>
notion of conversation and unit of work. For an application-managed
<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 entity manager the persistence context is created when the entity
manager is created and kept until the entity manager is closed. In an manager is created and kept until the entity manager is closed. In an
extended persistence context, all modification operations (persist, extended persistence context, all modification operations (persist,
merge, remove) executed outside a transaction are queued until the merge, remove) executed outside a transaction are queued until the
persistence context is attached to a transaction. The transaction persistence context is attached to a transaction. The transaction
typically occurs at the user process end, allowing the whole process to typically occurs at the user process end, allowing the whole process to
be commited or rollbacked. For application-managed entity manager only be committed or rollbacked. For application-managed entity manager only
support the exctended persistence context.</para> support the extended persistence context.</para>
<para>A resource-local entity manager or an entity manager created with <para>A resource-local entity manager or an entity manager created with
<literal>EntityManagerFactory.createEntityManager()</literal> <literal>EntityManagerFactory.createEntityManager()</literal>
@ -235,7 +234,8 @@
<para>If a stateless session bean, message-driven bean, or stateful <para>If a stateless session bean, message-driven bean, or stateful
session bean with a transaction-scoped persistence context calls a session bean with a transaction-scoped persistence context calls a
stateful session bean with an extended persistence context in the 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>
<listitem> <listitem>
@ -265,7 +265,7 @@
<para>If a stateful session bean with an extended persistence <para>If a stateful session bean with an extended persistence
context calls a stateful session bean with a different extended context calls a stateful session bean with a different extended
persistence context in the same transaction, an persistence context in the same transaction, an
IllegalStateException is thrown.</para> <classname>IllegalStateException</classname> is thrown.</para>
</listitem> </listitem>
</itemizedlist> </itemizedlist>
</section> </section>
@ -274,7 +274,7 @@
<section id="architecture-javase" revision="1"> <section id="architecture-javase" revision="1">
<title>Java SE environments</title> <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 entity managers are available. You can retrieve an entity manger using the
<literal>EntityManagerFactory</literal> API. Only resource-local entity <literal>EntityManagerFactory</literal> API. Only resource-local entity
managers are available. In other words, JTA transactions and persistence managers are available. In other words, JTA transactions and persistence

4
entitymanager/src/main/docbook/en/modules/batch.xml
View File

@ -2,10 +2,10 @@
<!-- <!--
~ Hibernate, Relational Persistence for Idiomatic Java ~ 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 ~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are ~ 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, ~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU ~ copy, or redistribute it subject to the terms and conditions of the GNU

345
entitymanager/src/main/docbook/en/modules/configuration.xml
View File

@ -1,11 +1,11 @@
<?xml version='1.0' encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<!-- <!--
~ Hibernate, Relational Persistence for Idiomatic Java ~ 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 ~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are ~ 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, ~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU ~ copy, or redistribute it subject to the terms and conditions of the GNU
@ -22,22 +22,64 @@
~ 51 Franklin Street, Fifth Floor ~ 51 Franklin Street, Fifth Floor
~ Boston, MA 02110-1301 USA ~ Boston, MA 02110-1301 USA
--> -->
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
<chapter id="configuration"> <chapter id="configuration">
<title id="setup">Setup and configuration</title> <title id="setup">Setup and configuration</title>
<section> <section>
<title>Setup</title> <title>Setup</title>
<para>The EJB 3.0 / JPA compatible Hibernate EntityManager is built on top <para>The JPA 2.0 compatible Hibernate EntityManager is built on top of
of Hibernate core and Hibernate Annotations. You have to use compatible the core of Hibernate and Hibernate Annotations. Starting from version
versions of each module. Please consult the compatibility matrix in the 3.5, we have bundled in a single Hibernate distribution all the necessary
hibernate.org download section. The following libraries have to be in your modules:</para>
classpath: hibernate3.jar, hibernate-annotations.jar,
<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 hibernate-commons-annotations.jar, hibernate-entitymanager.jar and all
needed third party libraries for each package (incl. 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>
<section id="setup-configuration" <section id="setup-configuration"
@ -52,16 +94,16 @@
A persistence archive is a JAR file which must define a A persistence archive is a JAR file which must define a
<literal>persistence.xml</literal> file that resides in the <literal>persistence.xml</literal> file that resides in the
<filename>META-INF</filename> folder. All properly annotated classes <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 annotation), all annotated packages and all Hibernate hbm.xml files
included in the archive will be added to the persistence unit included in the archive will be added to the persistence unit
configuration, so by default, your persistence.xml will be quite configuration, so by default, your persistence.xml will be quite
minimalist:</para> minimalist:</para>
<programlisting>&lt;persistence xmlns="http://java.sun.com/xml/ns/persistence" <programlisting>&lt;persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="1.0"&gt; version="2.0"&gt;
&lt;persistence-unit name="sample"&gt; &lt;persistence-unit name="sample"&gt;
&lt;jta-data-source&gt;java:/DefaultDS&lt;/jta-data-source&gt; &lt;jta-data-source&gt;java:/DefaultDS&lt;/jta-data-source&gt;
&lt;properties&gt; &lt;properties&gt;
@ -75,9 +117,9 @@
<filename><literal>persistence.xml</literal></filename> file</para> <filename><literal>persistence.xml</literal></filename> file</para>
<programlisting>&lt;persistence xmlns="http://java.sun.com/xml/ns/persistence" <programlisting>&lt;persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="1.0"&gt; version="2.0"&gt;
&lt;persistence-unit name="manager1" transaction-type="JTA"&gt; &lt;persistence-unit name="manager1" transaction-type="JTA"&gt;
&lt;provider&gt;org.hibernate.ejb.HibernatePersistence&lt;/provider&gt; &lt;provider&gt;org.hibernate.ejb.HibernatePersistence&lt;/provider&gt;
&lt;jta-data-source&gt;java:/DefaultDS&lt;/jta-data-source&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.Employee&lt;/class&gt;
&lt;class&gt;org.acme.Person&lt;/class&gt; &lt;class&gt;org.acme.Person&lt;/class&gt;
&lt;class&gt;org.acme.Address&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;properties&gt;
&lt;property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/&gt; &lt;property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/&gt;
&lt;property name="hibernate.hbm2ddl.auto" value="create-drop"/&gt; &lt;property name="hibernate.hbm2ddl.auto" value="create-drop"/&gt;
@ -198,6 +242,100 @@
</listitem> </listitem>
</varlistentry> </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> <varlistentry>
<term><code>properties</code></term> <term><code>properties</code></term>
@ -206,62 +344,164 @@
properties. This is where you will define your Hibernate specific properties. This is where you will define your Hibernate specific
configurations. This is also where you will have to specify JDBC configurations. This is also where you will have to specify JDBC
connection information as well.</para> 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> </listitem>
</varlistentry> </varlistentry>
</variablelist> </variablelist>
<para>Be sure to define the grammar definition in the <para>Be sure to define the grammar definition in the
<literal>persistence</literal> element since the EJB3 specification <literal>persistence</literal> element since the JPA specification
requires the schema validation. If the systemId ends with requires schema validation. If the <literal>systemId</literal> ends with
<literal>persistence_1_0.xsd</literal>, Hibernate entityManager will use <literal>persistence_2_0.xsd</literal>, Hibernate entityManager will use
the version embedded in the hibernate-entitymanager.jar. No internet the version embedded in the hibernate-entitymanager.jar. It won't fetch
access will be processed.</para> the resource from the internet.</para>
<programlisting>&lt;persistence xmlns="http://java.sun.com/xml/ns/persistence" <programlisting>&lt;persistence xmlns="http://java.sun.com/xml/ns/persistence"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 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" xsi:schemaLocation="http://java.sun.com/xml/ns/persistence http://java.sun.com/xml/ns/persistence/persistence_2_0.xsd"
version="1.0"&gt;</programlisting> version="2.0"&gt;</programlisting>
</section> </section>
<section id="setup-configuration-bootstrapping" revision="1"> <section id="setup-configuration-bootstrapping" revision="1">
<title>Bootstrapping</title> <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>EntityManagerFactory</classname> and the
<classname>EntityManager</classname>. The bootstrap class is <classname>EntityManager</classname>. The bootstrap class is
<classname>javax.persistence.Persistence</classname>, e.g.</para> <classname>javax.persistence.Persistence</classname>, e.g.</para>
<programlisting>EntityManagerFactory emf = Persistence.createEntityManagerFactory("manager1"); <programlisting>EntityManagerFactory emf = Persistence.createEntityManagerFactory("manager1");
//or //or
Map configOverrides = new HashMap();
Map&lt;String, Object&gt; configOverrides = new HashMap&lt;String, Object&gt;();
configOverrides.put("hibernate.hbm2ddl.auto", "create-drop"); configOverrides.put("hibernate.hbm2ddl.auto", "create-drop");
EntityManagerFactory programmaticEmf = EntityManagerFactory programmaticEmf =
Persistence.createEntityManagerFactory("manager1", configOverrides);</programlisting> Persistence.createEntityManagerFactory("manager1", configOverrides);</programlisting>
<para>The first version is equivalent to the second with an empty map. <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 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 properties defined in your <filename>persistence.xml</filename> files.
EJB3 properties usable in the map:</para> 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> <itemizedlist>
<listitem> <listitem>
<para>javax.persistence.provider to define the provider class <para><literal>javax.persistence.provider</literal> to define the
used</para> provider class used</para>
</listitem> </listitem>
<listitem> <listitem>
<para>javax.persistence.transactionType to define the transaction <para><literal>javax.persistence.transactionType</literal> to define
type used (either JTA or RESOURCE_LOCAL)</para> the transaction type used (either <literal>JTA</literal> or
<literal>RESOURCE_LOCAL</literal>)</para>
</listitem> </listitem>
<listitem> <listitem>
<para>javax.persistence.jtaDataSource to define the JTA datasource <para><literal>javax.persistence.jtaDataSource</literal> to define
name in JNDI</para> the JTA datasource name in JNDI</para>
</listitem> </listitem>
<listitem> <listitem>
<para>javax.persistence.nonJtaDataSource to define the non JTA <para><literal>javax.persistence.nonJtaDataSource</literal> to
datasource name in JNDI</para> 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> </listitem>
</itemizedlist> </itemizedlist>
@ -423,7 +663,7 @@ EntityManagerFactory programmaticEmf =
though.</para> though.</para>
</note> </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; <programlisting>&lt;persistence&gt;
&lt;persistence-unit name="manager1" transaction-type="RESOURCE_LOCAL"&gt; &lt;persistence-unit name="manager1" transaction-type="RESOURCE_LOCAL"&gt;
@ -431,11 +671,11 @@ EntityManagerFactory programmaticEmf =
&lt;class&gt;org.hibernate.ejb.test.Distributor&lt;/class&gt; &lt;class&gt;org.hibernate.ejb.test.Distributor&lt;/class&gt;
&lt;class&gt;org.hibernate.ejb.test.Item&lt;/class&gt; &lt;class&gt;org.hibernate.ejb.test.Item&lt;/class&gt;
&lt;properties&gt; &lt;properties&gt;
&lt;property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/&gt; &lt;property name="<literal>javax.persistence.jdbc.driver</literal>" value="org.hsqldb.jdbcDriver"/&gt;
&lt;property name="hibernate.connection.driver_class" value="org.hsqldb.jdbcDriver"/&gt; &lt;property name="<literal>javax.persistence.jdbc.user</literal>" value="sa"/&gt;
&lt;property name="hibernate.connection.username" value="sa"/&gt; &lt;property name="<literal>javax.persistence.jdbc.password</literal>" value=""/&gt;
&lt;property name="hibernate.connection.password" value=""/&gt; &lt;property name="<literal>javax.persistence.jdbc.url</literal>" value="jdbc:hsqldb:."/&gt;
&lt;property name="hibernate.connection.url" 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;property name="hibernate.max_fetch_depth" value="3"/&gt;
&lt;!-- cache configuration --&gt; &lt;!-- cache configuration --&gt;
@ -603,8 +843,8 @@ EntityManagerFactory emf =
</tgroup> </tgroup>
</table> </table>
<para>Note that the JACC*EventListeners are removed if the security is not <para>Note that the <classname>JACC*EventListeners</classname> are removed
enabled.</para> if the security is not enabled.</para>
<para>You can configure the event listeners either through the properties <para>You can configure the event listeners either through the properties
(see <xref linkend="setup-configuration" />) or through the (see <xref linkend="setup-configuration" />) or through the
@ -636,12 +876,13 @@ emf.close(); //close at application end</programlisting>
manager factory is a wrapper on top of a session factory. Calls to the manager factory is a wrapper on top of a session factory. Calls to the
entityManagerFactory are thread safe.</para> entityManagerFactory are thread safe.</para>
<para>Thanks to the EntityManagerFactory, you can retrieve an extended <para>Thanks to the <classname>EntityManagerFactory</classname>, you can
entity manager. The extended entity manager keep the same persistence retrieve an extended entity manager. The extended entity manager keep the
context for the lifetime of the entity manager: in other words, the same persistence context for the lifetime of the entity manager: in other
entities are still managed between two transactions (unless you call words, the entities are still managed between two transactions (unless you
entityManager.clear() in between). You can see an entity manager as a call <methodname>entityManager.clear()</methodname> in between). You can
small wrapper on top of an Hibernate session.</para> see an entity manager as a small wrapper on top of an Hibernate
session.</para>
<para>TODO explains emf.createEntityManager(Map)</para> <para>TODO explains emf.createEntityManager(Map)</para>
</section> </section>

4
entitymanager/src/main/docbook/en/modules/entitymanagerapi.xml
View File

@ -2,10 +2,10 @@
<!-- <!--
~ Hibernate, Relational Persistence for Idiomatic Java ~ 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 ~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are ~ 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, ~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU ~ copy, or redistribute it subject to the terms and conditions of the GNU

4
entitymanager/src/main/docbook/en/modules/listeners.xml
View File

@ -2,10 +2,10 @@
<!-- <!--
~ Hibernate, Relational Persistence for Idiomatic Java ~ 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 ~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are ~ 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, ~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU ~ copy, or redistribute it subject to the terms and conditions of the GNU

4
entitymanager/src/main/docbook/en/modules/query_ejbql.xml
View File

@ -2,10 +2,10 @@
<!-- <!--
~ Hibernate, Relational Persistence for Idiomatic Java ~ 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 ~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are ~ 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, ~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU ~ copy, or redistribute it subject to the terms and conditions of the GNU

4
entitymanager/src/main/docbook/en/modules/query_native.xml
View File

@ -2,10 +2,10 @@
<!-- <!--
~ Hibernate, Relational Persistence for Idiomatic Java ~ 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 ~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are ~ 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, ~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU ~ copy, or redistribute it subject to the terms and conditions of the GNU

4
entitymanager/src/main/docbook/en/modules/transactions.xml
View File

@ -2,10 +2,10 @@
<!-- <!--
~ Hibernate, Relational Persistence for Idiomatic Java ~ 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 ~ indicated by the @author tags or express copyright attribution
~ statements applied by the authors. All third-party contributions are ~ 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, ~ This copyrighted material is made available to anyone wishing to use, modify,
~ copy, or redistribute it subject to the terms and conditions of the GNU ~ copy, or redistribute it subject to the terms and conditions of the GNU