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>
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-core</artifactId>
<artifactId>hibernate-annotations</artifactId>
<version>${hibernate-core-version}</version>
</dependency>
</dependencies>
@ -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>

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
~
@ -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>jsr-317-feedback@sun.com</email>
<ulink url="http://jcp.org/en/jsr/detail?id=317">JSR 317 JCP Page</ulink>
</bibliomisc>
<bibliomisc><email>jsr-317-feedback@sun.com</email> <ulink
url="http://jcp.org/en/jsr/detail?id=317">JSR 317 JCP
Page</ulink></bibliomisc>
</biblioentry>
</bibliography>
</book>

54
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
~
~ 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>
</chapter>

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

@ -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

347
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
~
~ 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;
@ -198,6 +242,100 @@
</listitem>
</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>
@ -206,62 +344,164 @@
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>
@ -423,7 +663,7 @@ EntityManagerFactory programmaticEmf =
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 @@ EntityManagerFactory programmaticEmf =
&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 @@ EntityManagerFactory emf =
</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 @@ emf.close(); //close at application end</programlisting>
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 @@ emf.close(); //close at application end</programlisting>
be no performance cost. For more information on Hibernate Validator,
please refer to the Hibernate Annotations reference guide.</para>
</section>
</chapter>
</chapter>

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

@ -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

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

@ -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

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

@ -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

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

@ -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

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

@ -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