Menu
▾
▴
[Hibernate-commits] Hibernate Code SVN: r9643 - in trunk/HibernateExt/ejb: . doc/reference/en doc/reference/en/modules lib src/resources src/resources/org src/resources/org/hibernate src/resources/org/hibernate/ejb
Author: epbernard
Date: 2006-03-17 03:42:25 -0500 (Fri, 17 Mar 2006)
New Revision: 9643
Added:
trunk/HibernateExt/ejb/src/resources/org/
trunk/HibernateExt/ejb/src/resources/org/hibernate/
trunk/HibernateExt/ejb/src/resources/org/hibernate/ejb/
trunk/HibernateExt/ejb/src/resources/org/hibernate/ejb/persistence_1_0.xsd
Modified:
trunk/HibernateExt/ejb/
trunk/HibernateExt/ejb/doc/reference/en/master.xml
trunk/HibernateExt/ejb/doc/reference/en/modules/architecture.xml
trunk/HibernateExt/ejb/doc/reference/en/modules/batch.xml
trunk/HibernateExt/ejb/doc/reference/en/modules/configuration.xml
trunk/HibernateExt/ejb/doc/reference/en/modules/entitymanagerapi.xml
trunk/HibernateExt/ejb/doc/reference/en/modules/transactions.xml
trunk/HibernateExt/ejb/lib/ejb3-persistence.jar
Log:
doc
EJB API
persistence_1_0.xsd in resource
Property changes on: trunk/HibernateExt/ejb
___________________________________________________________________
Name: svn:ignore
- build.properties
build
target
test_output
+ build.properties
build
target
test_output
classes
Modified: trunk/HibernateExt/ejb/doc/reference/en/master.xml
===================================================================
--- trunk/HibernateExt/ejb/doc/reference/en/master.xml 2006-03-16 23:51:58 UTC (rev 9642)
+++ trunk/HibernateExt/ejb/doc/reference/en/master.xml 2006-03-17 08:42:25 UTC (rev 9643)
@@ -16,7 +16,7 @@
<subtitle>User guide</subtitle>
- <releaseinfo>3.1 beta 6</releaseinfo>
+ <releaseinfo>3.1 beta 7</releaseinfo>
<mediaobject>
<imageobject>
Modified: trunk/HibernateExt/ejb/doc/reference/en/modules/architecture.xml
===================================================================
--- trunk/HibernateExt/ejb/doc/reference/en/modules/architecture.xml 2006-03-16 23:51:58 UTC (rev 9642)
+++ trunk/HibernateExt/ejb/doc/reference/en/modules/architecture.xml 2006-03-17 08:42:25 UTC (rev 9643)
@@ -5,7 +5,7 @@
<section>
<title>Definitions</title>
- <para>EJB3 is part of the J2EE 5.0 platform. Persistence in EJB3 is
+ <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
that execute outside of a particular container. The following programming
interfaces and artifacts are available in both environments.</para>
@@ -108,13 +108,14 @@
<section>
<title>Container-managed entity manager</title>
- <para>The most common and widely used entity manager in a J2EE
+ <para>The most common and widely used entity manager in a Java EE
environment is the container-managed entity manager. In this mode, the
container is responsible for the opening and closing of the entity
manager (this is transparent to the application). It is also responsible
for transaction boundaries. A container-managed entity manager is
obtained in an application through dependency injection or through JNDI
- lookup, A container-managed entity manger requires JTA.</para>
+ lookup, A container-managed entity manger requires the use of a JTA
+ transaction.</para>
</section>
<section>
@@ -142,25 +143,18 @@
context available across several transactions.</para>
<para>The most common case is to bind the persistence context scope to
- the current transaction scope. This is particularly convenient 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 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.
- For a resource-local entity manager, a new persistence context begins
- when a new resource transaction is started (through
- <literal>EntityTransaction.begin()</literal>) and ends when the resource
- transaction is completed. If the entity manager is invoked outside the
- scope of a transaction, the persistence context is created and destroyed
- to service only the method call, all entities loaded from the database
- will become detached at the end of the method call. This is similar to
- auto-commit behavior in traditional JDBC.</para>
+ 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
+ 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>
<para>You can also use an extended persistence context. This can be
combined with stateful session beans, if you use a container-managed
@@ -175,13 +169,16 @@
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.
- 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 of a transaction
- are queued until the persistence context is executed in a transaction.
- The transaction typically occurs at the user process end, allowing the
- whole process to be commited or rollbacked.</para>
+ JBoss Seam is a framework tht link together JSF and EJB3 around 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>
<para>A resource-local entity manager or an entity manager created with
<literal>EntityManagerFactory.createEntityManager()</literal>
@@ -194,22 +191,15 @@
<title>Persistence context propagation</title>
<para>Persistence context propagation occurs for container-managed
- entity managers and for entity managers obtained through
- <literal>EntityManagerFactory.getEntityManager()</literal>.</para>
+ entity managers.</para>
<para>In a transaction-scoped container managed entity manager (common
case in a J2EE environment), the JTA transaction propagation is the same
- as the persistence context resource propagation. In other words, all
+ as the persistence context resource propagation. In other words,
container-managed transaction-scoped entity managers retrieved within a
given JTA transaction all share the same persistence context. In
Hibernate terms, this means all managers share the same session.</para>
- <para>When a JTA-bound and application-managed entity manager is
- retrieved with <code>EntityManagerFactory.getEntityManager()</code>, the
- entity manager returned is associated to the persistence context bound
- to the JTA transaction. If no persistence context is associated yet, a
- new one is created and associated.</para>
-
<para>Important: persistence context are never shared between different
JTA transactions or between entity manager that do not came from the
same entity manager factory. There are some noteworthy exceptions for
@@ -259,27 +249,16 @@
<section>
<title>J2SE environments</title>
- <para>In a J2SE environment only application-managed entity managers are
- available. You can retrieve an entity manger using the
+ <para>In a J2SE environment only extented 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
context propagation are not supported in J2SE (you will have to propagate
the persistence context yourself, e.g. using the thread local session
pattern popular in the Hibernate community).</para>
- <note>
- <para>Hibernate3 supports the notion of persistence context propagation
- strategy, which will probably be extended to Hibernate Entity Manager,
- in the near future.</para>
- </note>
-
- <para>However you can still choose between two different entity manager
- strategies. The first one, transaction-scoped entity manager will create a
- persistence context each time <literal>EntityTransaction.begin()</literal>
- is called. This persistence context will be closed at transaction
- completion. The second strategy available is the extended context. In that
- case, a persistence context is created when the entity manager is
- retrieved (using
+ <para>Extended context means that a persistence context is created when
+ the entity manager is retrieved (using
<literal>EntityManagerFactory.createEntityManager(EXTENDED)</literal> )
and closed when the entity manager is closed. Many resource-local
transaction share the same persistence context, in this case.</para>
Modified: trunk/HibernateExt/ejb/doc/reference/en/modules/batch.xml
===================================================================
--- trunk/HibernateExt/ejb/doc/reference/en/modules/batch.xml 2006-03-16 23:51:58 UTC (rev 9642)
+++ trunk/HibernateExt/ejb/doc/reference/en/modules/batch.xml 2006-03-17 08:42:25 UTC (rev 9643)
@@ -57,7 +57,7 @@
.setParameter( "newName", newName )
.setParameter( "oldName", oldName )
.executeUpdate();
-entityManager.getTrasnaction().commit();
+entityManager.getTransaction().commit();
entityManager.close();</programlisting>
<para>To execute an EJB-QL <literal>DELETE</literal>, use the same
@@ -72,7 +72,7 @@
int deletedEntities = entityManager.createQuery( hqlDelete )
.setParameter( "oldName", oldName )
.executeUpdate();
-entityManager.getTrasnaction().commit();
+entityManager.getTransaction().commit();
entityManager.close();</programlisting>
<para>The <literal>int</literal> value returned by the
Modified: trunk/HibernateExt/ejb/doc/reference/en/modules/configuration.xml
===================================================================
--- trunk/HibernateExt/ejb/doc/reference/en/modules/configuration.xml 2006-03-16 23:51:58 UTC (rev 9642)
+++ trunk/HibernateExt/ejb/doc/reference/en/modules/configuration.xml 2006-03-17 08:42:25 UTC (rev 9643)
@@ -7,9 +7,9 @@
<para>The EJB3 compatible Hibernate EntityManager is built on top of
Hibernate core and Hibernate Annotations. You have to use compatible
- versions of each module. This version is known to work on Hibernate 3.1.1
- and Hibernate Annotations 3.1beta8. The following libraries have to be in
- your classpath: hibernate3.jar, hibernate-annotations.jar,
+ versions of each module. This version is known to work on Hibernate
+ 3.2alpha2 and Hibernate Annotations 3.1beta9. The following libraries have
+ to be in your classpath: hibernate3.jar, hibernate-annotations.jar,
hibernate-entity-manager.jar and all needed third party libraries for each
package.(incl. ejb-persistence.jar).</para>
</section>
@@ -18,19 +18,25 @@
xreflabel="Configuration and bootstrapping">
<title>Configuration and bootstrapping</title>
- <para>The configuration for entity managers both inside an application
- server and in a standalone application reside in a persistence archive. 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>
- 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>
+ <section id="setup-configuration-packaging">
+ <title>Packaging</title>
- <programlisting><persistence>
- <persistence-unit>
+ <para>The configuration for entity managers both inside an application
+ server and in a standalone application reside in a persistence archive.
+ 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>
+ 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><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">
+ <persistence-unit name="sample">
<jta-data-source>java:/DefaultDS</jta-data-source>
<properties>
<property name="hibernate.dialect" value="org.hibernate.dialect.HSQLDialect"/>
@@ -39,11 +45,13 @@
</persistence-unit>
</persistence></programlisting>
- <para>Here's a more complete example of a
- <filename><literal>persistence.xml</literal></filename> file</para>
+ <para>Here's a more complete example of a
+ <filename><literal>persistence.xml</literal></filename> file</para>
- <programlisting>
-<persistence>
+ <programlisting><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">
<persistence-unit name="manager1" transaction-type="JTA">
<provider>org.hibernate.ejb.HibernatePersistence</provider>
<jta-data-source>java:/DefaultDS</jta-data-source>
@@ -57,287 +65,319 @@
<property name="hibernate.hbm2ddl.auto" value="create-drop"/>
</properties>
</persistence-unit>
-</persistence>
- </programlisting>
+</persistence></programlisting>
- <variablelist spacing="compact">
- <varlistentry>
- <term>
- <code>name</code>
- </term>
+ <variablelist spacing="compact">
+ <varlistentry>
+ <term>
+ <code>name</code>
+ </term>
- <listitem>
- <para>(attribute) Every entity manager must have a name. If no name
- is specified, the name of the archive file is used minus the
- <literal>.jar</literal> suffix.</para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>(attribute) Every entity manager must have a name.</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>
- <code>transaction-type</code>
- </term>
+ <varlistentry>
+ <term>
+ <code>transaction-type</code>
+ </term>
- <listitem>
- <para>(attribute) Transaction type used. Either JTA or
- RESOURCE_LOCAL (default JTA).</para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>(attribute) Transaction type used. Either JTA or
+ RESOURCE_LOCAL (default JTA).</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>
- <code>provider</code>
- </term>
+ <varlistentry>
+ <term>
+ <code>provider</code>
+ </term>
- <listitem>
- <para>The provider is a fully-qualified class name of the EJB
- Persistence provider. You do not have to define it if you don't work
- with several EJB3 implementations. This is needed when you are using
- multiple vendor implementations of EJB Persistence.</para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>The provider is a fully-qualified class name of the EJB
+ Persistence provider. You do not have to define it if you don't
+ work with several EJB3 implementations. This is needed when you
+ are using multiple vendor implementations of EJB
+ Persistence.</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term><code>jta-data-source</code>,
- <code>non-jta-data-source</code></term>
+ <varlistentry>
+ <term><code>jta-data-source</code>,
+ <code>non-jta-data-source</code></term>
- <listitem>
- <para>This is the JNDI name of where the javax.sql.DataSource is
- located. When running without a JNDI available Datasource, you must
- specify JDBC connections with Hibernate specific properties (see
- below).</para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>This is the JNDI name of where the javax.sql.DataSource is
+ located. When running without a JNDI available Datasource, you
+ must specify JDBC connections with Hibernate specific properties
+ (see below).</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>
- <code>mapping-file</code>
- </term>
+ <varlistentry>
+ <term>
+ <code>mapping-file</code>
+ </term>
- <listitem>
- <para>The class element specifies a EJB3 compliant XML mapping file
- that you will map. This feature is currently not supported.</para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>The class element specifies a EJB3 compliant XML mapping
+ file that you will map. This feature is currently not
+ supported.</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>
- <code>jar-file</code>
- </term>
+ <varlistentry>
+ <term>
+ <code>jar-file</code>
+ </term>
- <listitem>
- <para>The jar-file elements specifies a jar to analyse. All properly
- annotated classes, annotated packages and all hbm.xml files part of
- this jar file will be added to the persistence unit configuration.
- This element is mainly used in Java EE environment. Use of this one
- in Java SE should be considered as non portable, in this case a
- absolute url is needed.</para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>The jar-file elements specifies a jar to analyse. All
+ properly annotated classes, annotated packages and all hbm.xml
+ files part of this jar file will be added to the persistence unit
+ configuration. This element is mainly used in Java EE environment.
+ Use of this one in Java SE should be considered as non portable,
+ in this case a absolute url is needed.</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>
- <code>exclude-unlisted-classes</code>
- </term>
+ <varlistentry>
+ <term>
+ <code>exclude-unlisted-classes</code>
+ </term>
- <listitem>
- <para>Do not check the main jar file for annotated classes. Only
- explicit classes will be part of the persistence unit.</para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>Do not check the main jar file for annotated classes. Only
+ explicit classes will be part of the persistence unit.</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>
- <code>class</code>
- </term>
+ <varlistentry>
+ <term>
+ <code>class</code>
+ </term>
- <listitem>
- <para>The class element specifies a fully qualified class name that
- you will map. By default all properly annotated classes and all
- hbm.xml files found inside the archive are added to the persistence
- unit configuration. You can add some external entity through the
- class element though. As an extension to the specification, you can
- add a package name in the <literal><class></literal> element
- (eg
- <code><class>org.hibernate.eg</class></code>).</para>
- </listitem>
- </varlistentry>
+ <listitem>
+ <para>The class element specifies a fully qualified class name
+ that you will map. By default all properly annotated classes and
+ all hbm.xml files found inside the archive are added to the
+ persistence unit configuration. You can add some external entity
+ through the class element though. As an extension to the
+ specification, you can add a package name in the
+ <literal><class></literal> element (eg
+ <code><class>org.hibernate.eg</class></code>).</para>
+ </listitem>
+ </varlistentry>
- <varlistentry>
- <term>
- <code>properties</code>
- </term>
+ <varlistentry>
+ <term>
+ <code>properties</code>
+ </term>
- <listitem>
- <para>The properties element is used to specify vendor specific
- 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>
- </listitem>
- </varlistentry>
- </variablelist>
+ <listitem>
+ <para>The properties element is used to specify vendor specific
+ 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>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <para>The EJB3 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>
+ <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>
- <programlisting>EntityManagerFactory emf = Persistence.createEntityManagerFactory("manager1");
+ <programlisting><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"></programlisting>
+ </section>
+
+ <section id="setup-configuration-bootstrapping">
+ <title>Bootstrapping</title>
+
+ <para>The EJB3 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();
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>
+ <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>
- <itemizedlist>
- <listitem>
- <para>javax.persistence.provider to define the provider class
- used</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>javax.persistence.provider 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>
- </listitem>
+ <listitem>
+ <para>javax.persistence.transactionType to define the transaction
+ type used (either JTA or RESOURCE_LOCAL)</para>
+ </listitem>
- <listitem>
- <para>javax.persistence.jtaDataSource to define the JTA datasource
- name in JNDI</para>
- </listitem>
+ <listitem>
+ <para>javax.persistence.jtaDataSource 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>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para>javax.persistence.nonJtaDataSource to define the non JTA
+ datasource name in JNDI</para>
+ </listitem>
+ </itemizedlist>
- <para>When <code>Persistence.createEntityManagerFactory()</code> is
- called, the persistence implementation will search your classpath for any
- <code>META-INF/persistence.xml</code> files using the
- <code>ClassLoader.getResource("META-INF/persistence.xml")</code> method.
- From this list of resources, it will try to find an entity manager that
- matches the name you specify in the command line with what is specified in
- the persistence.xml file. If no persistence.xml with the correct name are
- found, a <classname>PersistenceException</classname> is raised. If there
- is only one persistence.xml in your classpath, you don't have to declare
- any entity manager factory name (however, if several files are found, a
- <literal>PersistenceException</literal> is raised).</para>
+ <para>When <code>Persistence.createEntityManagerFactory()</code> is
+ called, the persistence implementation will search your classpath for
+ any <code>META-INF/persistence.xml</code> files using the
+ <code>ClassLoader.getResource("META-INF/persistence.xml")</code> method.
+ From this list of resources, it will try to find an entity manager that
+ matches the name you specify in the command line with what is specified
+ in the persistence.xml file. If no persistence.xml with the correct name
+ are found, a <classname>PersistenceException</classname> is
+ raised.</para>
- <programlisting>EntityManagerFactory emf = Persistence.createEntityManagerFactory(null);</programlisting>
+ <para>Apart from Hibernate system-level settings, all the properties
+ available in Hibernate can be set in <code>properties</code> element of
+ the persistence.xml file or as an override in the map you pass to
+ <code>createEntityManagerFactory()</code>. Please refer to the Hibernate
+ reference documentation for a complete listing. There are however a
+ couple of properties available in the EJB3 provider only.</para>
- <para>Apart from Hibernate system-level settings, all the properties
- available in Hibernate can be set in <code>properties</code> element of
- the persistence.xml file or as an override in the map you pass to
- <code>createEntityManagerFactory()</code>. Please refer to the Hibernate
- reference documentation for a complete listing. There are however a couple
- of properties available in the EJB3 provider only.</para>
+ <para></para>
- <para></para>
+ <table>
+ <title>Hibernate Entity Manager specific properties</title>
- <table>
- <title>Hibernate Entity Manager specific properties</title>
+ <tgroup cols="2">
+ <colspec align="left" colname="c1" />
- <tgroup cols="2">
- <colspec align="left" colname="c1" />
+ <colspec colname="c2" colwidth="2*" />
- <colspec colname="c2" colwidth="2*" />
+ <thead>
+ <row>
+ <entry>Property name</entry>
- <thead>
- <row>
- <entry>Property name</entry>
+ <entry>Description</entry>
+ </row>
+ </thead>
- <entry>Description</entry>
- </row>
- </thead>
+ <tbody>
+ <row>
+ <entry>hibernate.ejb.classcache.<classname></entry>
- <tbody>
- <row>
- <entry>hibernate.ejb.classcache.<classname></entry>
+ <entry>class cache strategy [comma cache region] of the class
+ Default to no cache, and default region cache to
+ fully.qualified.classname (eg.
+ hibernate.ejb.classcache.com.acme.Cat read-write or
+ hibernate.ejb.classcache.com.acme.Cat read-write,
+ MyRegion).</entry>
+ </row>
- <entry>class cache strategy [comma cache region] of the class
- Default to no cache, and default region cache to
- fully.qualified.classname (eg.
- hibernate.ejb.classcache.com.acme.Cat read-write or
- hibernate.ejb.classcache.com.acme.Cat read-write,
- MyRegion).</entry>
- </row>
+ <row>
+ <entry>hibernate.ejb.collectioncache.<collectionrole></entry>
- <row>
- <entry>hibernate.ejb.collectioncache.<collectionrole></entry>
+ <entry>collection cache strategy [comma cache region] of the
+ class Default to no cache, and default region cache to
+ fully.qualified.classname.role (eg.
+ hibernate.ejb.classcache.com.acme.Cat read-write or
+ hibernate.ejb.classcache.com.acme.Cat read-write,
+ MyRegion).</entry>
+ </row>
- <entry>collection cache strategy [comma cache region] of the class
- Default to no cache, and default region cache to
- fully.qualified.classname.role (eg.
- hibernate.ejb.classcache.com.acme.Cat read-write or
- hibernate.ejb.classcache.com.acme.Cat read-write,
- MyRegion).</entry>
- </row>
+ <row>
+ <entry>hibernate.ejb.cfgfile</entry>
- <row>
- <entry>hibernate.ejb.cfgfile</entry>
+ <entry>XML configuration file to use to configure Hibernate (eg.
+ <filename>/hibernate.cfg.xml</filename>).</entry>
+ </row>
- <entry>XML configuration file to use to configure Hibernate (eg.
- <filename>/hibernate.cfg.xml</filename>).</entry>
- </row>
+ <row>
+ <entry>hibernate.archive.autodetection</entry>
- <row>
- <entry>hibernate.archive.autodetection</entry>
+ <entry>Determine which element is auto discovered by Hibernate
+ Entity Manager while parsing the .par archive. (default to
+ <literal>class,hbm</literal>).</entry>
+ </row>
- <entry>Determine which element is auto discovered by Hibernate
- Entity Manager while parsing the .par archive. (default to
- <literal>class,hbm</literal>).</entry>
- </row>
+ <row>
+ <entry>hibernate.ejb.interceptor</entry>
- <row>
- <entry>hibernate.ejb.interceptor</entry>
+ <entry>An optional Hibernate interceptor. This interceptor has
+ to implement <classname>org.hibernate.Interceptor</classname>
+ and have a no-arg constructor.</entry>
+ </row>
- <entry>An optional Hibernate interceptor. This interceptor has to
- implement <classname>org.hibernate.Interceptor</classname> and
- have a no-arg constructor.</entry>
- </row>
+ <row>
+ <entry>hibernate.ejb.naming_strategy</entry>
- <row>
- <entry>hibernate.ejb.naming_strategy</entry>
+ <entry>An optional naming strategy. The default naming strategy
+ used is <classname>EJB3NamingStrategy</classname>. You also
+ might want to consider the
+ <classname>DefaultComponentSafeNamingStrategy</classname>.</entry>
+ </row>
- <entry>An optional naming strategy. The default naming strategy
- used is <classname>EJB3NamingStrategy</classname>. You also might
- want to consider the
- <classname>DefaultComponentSafeNamingStrategy</classname>.</entry>
- </row>
+ <row>
+ <entry>hibernate.ejb.event.<eventtype></entry>
- <row>
- <entry>hibernate.ejb.event.<eventtype></entry>
+ <entry>Event listener list for a given eventtype. The list of
+ event listeners is a comma separated fully qualified class name
+ list (eg. hibernate.ejb.event.pre-load
+ com.acme.SecurityListener, com.acme.AuditListener)</entry>
+ </row>
- <entry>Event listener list for a given eventtype. The list of
- event listeners is a comma separated fully qualified class name
- list (eg. hibernate.ejb.event.pre-load com.acme.SecurityListener,
- com.acme.AuditListener)</entry>
- </row>
+ <row>
+ <entry>hibernate.ejb.use_class_enhancer</entry>
- <row>
- <entry>hibernate.ejb.use_class_enhancer</entry>
+ <entry>Whether or not use Application server class enhancement
+ at deployment time (default to false)</entry>
+ </row>
- <entry>Whether or not use Application server class enhancement at
- deployment time (default to false)</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <row>
+ <entry>hibernate.ejb.discard_pc_on_close</entry>
- <para>Note that you can mix XML <literal><class></literal>
- declaration and <literal>hibernate.ejb.cfgfile</literal> usage in the same
- configuration. Be aware of the potential clashed. The properties set in
- <filename>persistence.xml</filename> will override the one in the defined
- <filename>hibernate.cfg.xml</filename>.</para>
+ <entry>Whether or not em.close() actually discard the
+ persistence context right away or wait for the transaction
+ completion defore discarding it (default to falseuse Application
+ server class enhancement at deployment time (default to false,
+ ie wait the transaction completion)</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
- <para>Here is a typical configuration in a J2SE environment</para>
+ <para>Note that you can mix XML <literal><class></literal>
+ declaration and <literal>hibernate.ejb.cfgfile</literal> usage in the
+ same configuration. Be aware of the potential clashed. The properties
+ set in <filename>persistence.xml</filename> will override the one in the
+ defined <filename>hibernate.cfg.xml</filename>.</para>
- <programlisting><persistence>
+ <note>
+ <para>It is important that you do not override
+ <literal>hibernate.transaction.factory_class</literal>, Hibernate
+ EntityManager automatically set the appropriate transaction factory
+ depending on the EntityManager type (ie <literal>JTA</literal> versus
+ <literal>RESOURSE_LOCAL</literal>). If you are working in a Java EE
+ environment, you might want to set the
+ <literal>hibernate.transaction.manager_lookup_class</literal>
+ though.</para>
+ </note>
+
+ <para>Here is a typical configuration in a J2SE environment</para>
+
+ <programlisting><persistence>
<persistence-unit name="manager1" transaction-type="RESOURCE_LOCAL">
<class>org.hibernate.ejb.test.Cat</class>
<class>org.hibernate.ejb.test.Distributor</class>
@@ -360,16 +400,16 @@
<persistence-unit>
</persistence></programlisting>
- <para>To ease the programmatic configuration, Hibernate Entity Manager
- provide a proprietary API. This API is very similar to the
- <classname>Configuration</classname> API and share the same concepts:
- <classname>Ejb3Configuration</classname>. Refer to the JavaDoc and the
- Hibernate reference guide for more detailed informations on how to use
- it.</para>
+ <para>To ease the programmatic configuration, Hibernate Entity Manager
+ provide a proprietary API. This API is very similar to the
+ <classname>Configuration</classname> API and share the same concepts:
+ <classname>Ejb3Configuration</classname>. Refer to the JavaDoc and the
+ Hibernate reference guide for more detailed informations on how to use
+ it.</para>
- <para>TODO: me more descriptive on some APIs like setDatasource()</para>
+ <para>TODO: me more descriptive on some APIs like setDatasource()</para>
- <programlisting>Ejb3Configuration cfg = new Ejb3Configuration();
+ <programlisting>Ejb3Configuration cfg = new Ejb3Configuration();
EntityManagerFactory emf =
cfg.configure("/mypath/hibernate.cfg.xml") //add a regular hibernate.cfg.xml
.addProperties( properties ) //add some properties
@@ -378,6 +418,7 @@
.addClass( NonAnnotatedClass.class ) //add an hbm.xml file using the Hibernate convention
.addFile( "/mypath/MyOtherCLass.hbm.xml ) //add an hbm.xml file
.createEntityManagerFactory(); //Create the entity manager factory</programlisting>
+ </section>
</section>
<section>
@@ -533,7 +574,7 @@
<programlisting>// Use persistence.xml configuration
EntityManagerFactory emf = Peristence.createEntityManagerFactory("manager1")
-EntityManager em = emf.createEntityManager(); // Retrieve a transactional-scoped entity manager
+EntityManager em = emf.createEntityManager(); // Retrieve an application managed entity manager
// Work with the EM
em.close();
...
@@ -543,19 +584,17 @@
initialization time and closed at application end. It's creation is an
expensive process. For those who are familiar with Hibernate, an entity
manager factory is very much like a session factory. Actually, an entity
- manager factory is a wrapper on top of a session factory.</para>
+ manager factory is a wrapper on top of a session factory. Calls to the
+ entityManagerFactory are thread safe.</para>
- <para>There are two kinds of entity managers. The transaction-scoped
- entity manager (default) create and destroy a persistence context for each
- transaction: in other words, the managed entities are detached once the
- transaction ends. The extended entity manager keep the same persistence
+ <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.
- <code>emf.createEntityManager()</code> creates a transaction-scoped entity
- manager and
- <code>emf.createEntityManager(PersistenceContextType.EXTENDED)</code>
- creates an extended entity manager. You can see an entity manager as a
+ 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>TODO explains emf.createEntityManager(Map)</para>
</section>
<section>
Modified: trunk/HibernateExt/ejb/doc/reference/en/modules/entitymanagerapi.xml
===================================================================
--- trunk/HibernateExt/ejb/doc/reference/en/modules/entitymanagerapi.xml 2006-03-16 23:51:58 UTC (rev 9642)
+++ trunk/HibernateExt/ejb/doc/reference/en/modules/entitymanagerapi.xml 2006-03-17 08:42:25 UTC (rev 9643)
@@ -178,7 +178,7 @@
<programlisting>Iterator results = em.createQuery(
"select cat.color, min(cat.birthdate), count(cat) from Cat cat " +
"group by cat.color")
- .list()
+ .getResultList()
.iterator();
while ( results.hasNext() ) {
@@ -229,7 +229,7 @@
<programlisting>Query q = em.createQuery("select cat from DomesticCat cat");
q.setFirstResult(20);
q.setMaxResults(10);
-List cats = q.list(); //return cats from the 20th position to 29th</programlisting>
+List cats = q.getResultList(); //return cats from the 20th position to 29th</programlisting>
<para>Hibernate knows how to translate this limit query into the
native SQL of your DBMS.</para>
@@ -249,7 +249,7 @@
<programlisting>Query q = em.createNamedQuery("eg.DomesticCat.by.name.and.minimum.weight");
q.setString(1, name);
q.setInt(2, minWeight);
-List cats = q.list();</programlisting>
+List cats = q.getResultList();</programlisting>
<para>Note that the actual program code is independent of the query
language that is used, you may also define native SQL queries in
@@ -271,7 +271,7 @@
mechanism to work):</para>
<programlisting>@SqlResultSetMapping(name="getItem", entities =
- @EntityResult(name="org.hibernate.ejb.test.Item", fields= {
+ @EntityResult(entityClass=org.hibernate.ejb.test.Item.class, fields= {
@FieldResult(name="name", column="itemname"),
@FieldResult(name="descr", column="itemdescription")
})
@@ -378,13 +378,6 @@
<entry>Cache mode used for this query</entry>
</row>
-
- <row>
- <entry>org.hibernate.callable</entry>
-
- <entry>For native queries, whether or not the query is of type
- callable or not (default to false)</entry>
- </row>
</tbody>
</tgroup>
</table>
@@ -560,7 +553,7 @@
</section>
<section>
- <title>Flushing the persistence context</title>
+ <title>Flush the persistence context</title>
<section>
<title>In a transaction</title>
@@ -635,13 +628,9 @@
<para>It is possible to change the default behavior so that flush occurs
less frequently. The <classname>FlushModeType</classname> for an entity
- manager defines three different modes: only flush at commit time, flush
- automatically using the explained routine, or never flush unless
- <methodname>flush()</methodname> is called explicitly. The last mode is
- useful for long running extended perstence contexts, where the context
- and its entity manager is kept open (but disconnected from the JDBC data
- source) possibly for a long time. TODO: Add link to disconnection
- discussion, however, disconnection is implementation specific.</para>
+ manager defines two different modes: only flush at commit time or flush
+ automatically using the explained routine unless
+ <methodname>flush()</methodname> is called explicitly.</para>
<programlisting>em = emf.createEntityManager();
Transaction tx = em.getTransaction().begin();
@@ -659,20 +648,26 @@
<para>During flush, an exception might happen (e.g. if a DML operation
violates a constraint). TODO: Add link to exception handling.</para>
+
+ <para>Hibernate provides more flush modes than the one described in the
+ EJB3 specification. Please refer to the Hibernate core reference
+ documentation for more informations.</para>
</section>
<section>
<title>Outside a transaction</title>
- <para>When running an <literal>EXTENDED</literal> persistence context
- outside a transaction, all the modification operations are queued (ie
- not flushed to the database). This is actually done, by setting the
- <literal>FlushMode</literal> to <literal>NONE</literal> when the Entity
- Manager is executed outside an active transaction.</para>
-
- <para>When the transaction comes to an active state, the queued
- operations are flushed to the database (by setting the
- <literal>FlushMode</literal> to its previous state.</para>
+ <para>In an <literal>EXTENDED</literal> persistence context, all read
+ only operations of the entity manager can be executed outside a
+ transaction (<literal>find()</literal>,
+ <literal>getReference()</literal>, <literal>refresh()</literal>, and
+ read queries). Some modifications operations can be executed outside a
+ transaction, but they are queued until the persistence context join a
+ transaction. This is the case of <literal>persist()</literal>,
+ <literal><literal>merge()</literal></literal>,
+ <literal>remove()</literal>. Some operations cannot be called outside a
+ transaction: <literal>flush()</literal>, <literal>lock()</literal>, and
+ update/delete queries.</para>
</section>
</section>
@@ -754,4 +749,29 @@
</listitem>
</itemizedlist>
</section>
+
+ <section>
+ <title>Locking</title>
+
+ <para>The default locking system in EJB3 is mostly based on optimistic
+ locking (ie using a version column to check any concurrency issues). EJB3
+ has defined an additional mechanism to increase the concurrency
+ guaranties. You can apply a lock on a given entity (and it's associated
+ entities if <literal>LOCK</literal> is cascaded) through the
+ <methodname>lock(Object entity)</methodname> method. Depending on the
+ concurrency guaranties you requires, you choose a lock mode:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para><literal>LockMode.READ</literal> prevents dirty-reads and non
+ repeatable read on a given entity.</para>
+ </listitem>
+
+ <listitem>
+ <para><literal>LockMode.WRITE</literal> prevents dirty-reads and non
+ repeatable read on a given entity and force an increase of the version
+ number if any.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
</chapter>
\ No newline at end of file
Modified: trunk/HibernateExt/ejb/doc/reference/en/modules/transactions.xml
===================================================================
--- trunk/HibernateExt/ejb/doc/reference/en/modules/transactions.xml 2006-03-16 23:51:58 UTC (rev 9642)
+++ trunk/HibernateExt/ejb/doc/reference/en/modules/transactions.xml 2006-03-17 08:42:25 UTC (rev 9643)
@@ -21,7 +21,7 @@
match the concept of entity manager and persistence context. One is an API
and programming object, the other a definition of scope. However, keep in
mind the essential difference. A persistence context is usually bound to a
- JTA transaction in J2EE, and a persistence context starts and ends at
+ JTA transaction in Java EE, and a persistence context starts and ends at
transaction boundaries (transaction-scoped) unless you use an extended
entity manager. Please refer to <xref
linkend="architecture-ejb-persistctxscope" /> for more information.</para>
@@ -80,13 +80,13 @@
two is one-to-one and this model is a perfect fit for many
applications.</para>
- <para>This is the default EJB3 persistence model in a J2EE environment
- (JTA bounded, transaction-scoped persistence context); injected (or
- looked up) entity managers share the same persistence context for a
- particular JTA transaction. The beauty of EJB3 is that you don't have to
- care about that anymore and just see data access through entity manager
- and demaraction of transaction scope on session beans as completely
- orthogonal.</para>
+ <para>This is the default EJB3 persistence model in a Java EE
+ environment (JTA bounded, transaction-scoped persistence context);
+ injected (or looked up) entity managers share the same persistence
+ context for a particular JTA transaction. The beauty of EJB3 is that you
+ don't have to care about that anymore and just see data access through
+ entity manager and demaraction of transaction scope on session beans as
+ completely orthogonal.</para>
<para>The challenge is the implementation of this (and other) behavior
outside an EJB3 container: not only has the
@@ -209,24 +209,6 @@
the context of optimistic concurrency control.</para>
<para>TODO: This note should probably come later.</para>
-
- <note>
-
-
- <title>Recommended approach</title>
-
-
-
- <para>The
- <emphasis>entitymanager-per-application-transaction</emphasis> is
- avaliable out-of-the-box in an EJB3 container using a Stateful Session
- Bean that keeps the state of an extended entity manager and its
- persistence context. To enable this extended persistence context,
- annotate your bean as
- <literal>@PersistenceContext(EXTENDED).</literal></para>
-
- TODO: What exactly am I supposed to do? This is incomplete...
- </note>
</sect2>
<sect2 id="transactions-basics-identity">
@@ -379,7 +361,7 @@
non-managed environment, an <literal>EntityManagerFactory</literal> is
usually responsible for its own database connection pool. The application
developer has to manually set transaction boundaries, in other words,
- begin, commit, or rollback database transactions himself. A managed
+ begin, commit, or rollback database transactions itself. A managed
environment usually provides container-managed transactions, with the
transaction assembly defined declaratively through annotations of EJB
session beans, for example. Programmatic transaction demarcation is then
@@ -396,8 +378,8 @@
</listitem>
<listitem>
- <para>close the entity manager (if running outside an EJB3
- container)</para>
+ <para>close the entity manager (if using an application-managed entity
+ manager)</para>
</listitem>
<listitem>
@@ -429,7 +411,7 @@
tx.commit();
}
catch (RuntimeException e) {
- if (tx != null) tx.rollback();
+ if ( tx != null && tx.isActive() ) tx.rollback();
throw e; // or display error message
}
finally {
@@ -455,6 +437,36 @@
yourself and you should use J2EE/EJB container services whenever they
are available. Exception handling is discussed later in this
chapter.</para>
+
+ <sect3>
+ <title>EntityTransaction</title>
+
+ <para>In a JTA environment, you don't need any extra API to interact
+ with the transaction in your environment. Simply use transaction
+ declaration or the JTA APIs.</para>
+
+ <para>If you are using a <literal>RESOURCE_LOCAL</literal> entity
+ manager, you need to demarcate your transaction boundaries through the
+ <literal>EntityTransaction</literal> API. You can get an
+ <literal>EntityTransaction</literal> through
+ <literal>entityManager.getTransaction()</literal>. This
+ <literal>EntityTransaction</literal> API provides the regular
+ <methodname>begin()</methodname>, <methodname>commit()</methodname>,
+ <methodname>rollback()</methodname> and
+ <methodname>isActive()</methodname> methods. It also provide a way to
+ mark a transaction as rollback only, ie force the transaction to
+ rollback. This is very similar to the JTA operation
+ <methodname>setRollbackOnly()</methodname>. When a
+ <literal>commit()</literal> operation fail and/or if the transaction
+ is marked as <literal>setRollbackOnly()</literal>, the
+ <literal>commit()</literal> method will try to rollback the
+ transaction and raise a
+ <literal>javax.transaction.RollbackException</literal>.</para>
+
+ <para>In a <literal>JTA</literal> entity manager,
+ <literal>entityManager.getTransaction()</literal> calls are not
+ permitted.</para>
+ </sect3>
</sect2>
<sect2 id="transactions-demarcation-jta">
@@ -469,9 +481,6 @@
<para>If you use bean-managed transactions (BMT), the code will look
like this:</para>
- <para>TODO: Check if UserTransaction is now really rollback() and not
- setRollbackOnly()</para>
-
<programlisting>// BMT idiom
@Resource public UserTransaction utx;
@Resource public EntityManagerFactory factory;
@@ -506,15 +515,9 @@
as per the EJB specification (system exception vs. application
exception).</para>
- <para>TODO: Check if this configuration is still the same for EJB3
- entity manager factory</para>
-
- <para>Note that you should choose
- <literal>org.hibernate.transaction.JTATransactionFactory</literal> in a
- BMT session bean, and
- <literal>org.hibernate.transaction.CMTTransactionFactory</literal> in a
- CMT session bean, when you configure Hibernate's transaction factory.
- Remember to also set
+ <para>It is important to let Hibernate EntityManager define the
+ <literal>hibernate.transaction.factory_class</literal> (ie not
+ overriding this value). Remember to also set
<literal>org.hibernate.transaction.manager_lookup_class</literal>.</para>
<para>If you work in a CMT environment, you might also want to use the
@@ -523,26 +526,18 @@
variable to hold the entity manager, but a single EJB request might
execute in different threads (e.g. session bean calling another session
bean). The EJB3 container takes care of the persistence context
- propagation for you. Either using injection or using
- <methodname>EntityManagerFactory.getEntityManager()</methodname>, the
- EJB3 container will return an entity manager with the same persistence
+ propagation for you. Either using injection or lookup, the EJB3
+ container will return an entity manager with the same persistence
context bound to the JTA context if any, or create a new one and bind it
(see <xref linkend="architecture-ejb-persistctxpropagation" /> .)</para>
<para>Our entity manager/transaction management idiom for CMT and EJB3
container-use is reduced to this:</para>
- <programlisting>// CMT idiom through factory
-EntityManager em = factory.getEntityManager();
+ <programlisting>//CMT idiom through injection
+@PersistenceContext(name="sample") EntityManager em;</programlisting>
-// do some work
-...
-
-/ /CMT idiom through injection
-@Resource EntityManager em;</programlisting>
-
- <para>In other words, all you have to do in a managed environment is
- call <literal>EntityManagerFactory.getEntityManager()</literal> or
+ <para>In other words, all you have to do in a managed environment is to
inject the <literal>EntityManager</literal>, do your data access work,
and leave the rest to the container. Transaction boundaries are set
declaratively in the annotations or deployment descriptors of your
@@ -662,6 +657,86 @@
</sect2>
</sect1>
+ <sect1>
+ <title>EXTENDED Persistence Context</title>
+
+ <para>All application managed entity manager and container managed
+ persistence contexts defined as such are <literal>EXTENDED</literal>. This
+ means that the persistence context type goes beyond the transaction life
+ cycle. We should then understand what happens to operations made outside
+ the scope of a transaction.</para>
+
+ <para>In an <literal>EXTENDED</literal> persistence context, all read only
+ operations of the entity manager can be executed outside a transaction
+ (<literal>find()</literal>, <literal>getReference()</literal>,
+ <literal>refresh()</literal>, and read queries). Some modifications
+ operations can be executed outside a transaction, but they are queued
+ until the persistence context join a transaction: this is the case of
+ <literal>persist()</literal>,
+ <literal><literal>merge()</literal></literal>,
+ <literal>remove()</literal>. Some operations cannot be called outside a
+ transaction: <literal>flush()</literal>, <literal>lock()</literal>, and
+ update/delete queries.</para>
+
+ <sect2>
+ <title>Container Managed Entity Manager</title>
+
+ <para>When using an EXTENDED persistence context with a container
+ managed entity manager, the lifecycle of the persistence context is
+ binded to the lifecycle of the Stateful Session Bean. Plus if the entity
+ manager is created outside a transaction, modifications operations
+ (persist, merge, remove) are queued in the persistence context and not
+ executed to the database.</para>
+
+ <para>When a method of the stateful session bean involved or starting a
+ transaction is later called, the entity manager join the transaction.
+ All queued operation will then be executed to synchronize the
+ persistence context.</para>
+
+ <para>This is perfect to implement the
+ <literal>entitymanager-per-conversation</literal> pattern. A stateful
+ session bean represents the conversation implementation. All
+ intermediate conversation work will be processed in methods not
+ involving transaction. The end of the conversation will be processed
+ inside a <literal>JTA</literal> transaction. Hence all queued operations
+ will be executed to the database and commited. If you are interested in
+ the notion of conversation inside your application, have a look at JBoss
+ Seam. Jboss Seam emphasizes the concept of conversation and entity
+ manager lifecycle and bind EJB3 and JSF together.</para>
+ </sect2>
+
+ <sect2>
+ <title>Application Managed Entity M...
[truncated message content] |
