[seam-commits] Seam SVN: r13824 - modules/persistence/trunk/docs/src/main/docbook/en-US.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Mon Oct 11 05:10:41 EDT 2010
Author: swd847
Date: 2010-10-11 05:10:41 -0400 (Mon, 11 Oct 2010)
New Revision: 13824
Modified:
modules/persistence/trunk/docs/src/main/docbook/en-US/persistence-general.xml
Log:
work on seam-persistence documentation
Modified: modules/persistence/trunk/docs/src/main/docbook/en-US/persistence-general.xml
===================================================================
--- modules/persistence/trunk/docs/src/main/docbook/en-US/persistence-general.xml 2010-10-11 07:24:25 UTC (rev 13823)
+++ modules/persistence/trunk/docs/src/main/docbook/en-US/persistence-general.xml 2010-10-11 09:10:41 UTC (rev 13824)
@@ -78,14 +78,178 @@
</para>
</section>
+
+ <section id="persistence.transactions" >
+ <title>Transaction Management</title>
+
+ <para>
+ Unlike EJB session beans CDI beans are not transactional by default. Seam
+ brings declarative transaction management to CDI beans by enabling them to
+ use <code>@TransactionAttribute</code>. Seam also provides the
+ <code>@Transactional</code> annotation, for environments where java EE
+ APIs are not present.
+ </para>
+ <section>
+ <title>Configuration</title>
+ <para>
+ If you are in an EE 6 environment then no configuration is necessary,
+ simply drop the seam-persistence jar into your app and you are ready
+ to go.
+ </para>
+ <para>
+ If you are not in an EE environment you may need to configure some
+ things with seam-xml. You may need the following entries in your
+ beans.xml file:
+ </para>
+ <programlisting role="XML"><![CDATA[<beans xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:s="urn:java:ee"
+ xmlns:t="urn:java:org.jboss.seam.persistence.transaction"
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/javaee
+ http://docs.jboss.org/cdi/beans_1_0.xsd">
+ <t:SeSynchronizations>
+ <s:modifies/>
+ </t:SeSynchronizations>
+
+ <t:EntityTransaction>
+ <s:modifies />
+ </t:EntityTransaction>
+
+</beans>]]></programlisting>
+ <para>
+ Lets look at these individually.
+ </para>
+
+ <programlisting role="XML"><![CDATA[<t:SeSynchronizations>
+ <s:modifies/>
+</t:SeSynchronizations>]]></programlisting>
+
+ <para>
+ Seam will attempt to use JTA synchronizations if possible. If not then you need to install the
+ <code>SeSynchronzations</code> bean to allow seam to handle synchronizations manually.
+ Synchronizations allow seam to respond to transaction events such as
+ <literal>beforeCompletion()</literal> and <literal>afterCompletion()</literal>, and are needed
+ for the proper operation of the
+ <link linkend="persistence.seam-managed-persistence-contexts">Seam Managed Persistence Context</link>.
+ </para>
+
+ <programlisting role="XML"><![CDATA[<t:EntityTransaction>
+ <s:modifies />
+</t:EntityTransaction>]]></programlisting>
+
+ <para>
+ By default seam will attempt to look up <literal>java:comp/UserTransaction</literal> from JNDI
+ (or alternatively retrieve it from the EJBContext if a container managed transaction is active).
+ Installing <code>EntityTransaction</code> tells seam to use the JPA <code>EntityTransaction</code>
+ instead. To use this you must have a
+ <link linkend="persistence.seam-managed-persistence-contexts">Seam Managed Persistence Context</link>
+ installed with qualifier <code>@Default</code>.
+ </para>
+ <para>
+ TODO: document how to use different qualifiers.
+ </para>
+ <note>
+ <para>
+ You should avoid <code>EntityTransaction</code> if you have more than one persistence unit in your
+ application. Seam does not support installing multiple <code>EntityTransaction</code> beans, and
+ the <code>EntityTransaction</code> interface does not support two phase commit, so unless you are
+ careful you may have data consistency issues. If you need multiple persistence units in your
+ application then we highly recommend using an EE 6 compatible server, such as Jboss 6.
+ </para>
+ </note>
+
+ </section>
+
+ <section>
+ <title>Declarative Transaction Management</title>
+
+ <para>
+ Seam adds declarative transaction support to managed beans. Seam re-uses the EJB
+ <code>@TransactionAttribute</code> for this purpose, however it also provides
+ an alternative <code>@Transactional</code> annotation for environments where
+ the EJB API's are not available. An alternative to <code>@ApplicationException</code>,
+ <code>@SeamApplicationException</code> is also provided. Unlike EJBs managed beans
+ are not transactional by default, you can change this by adding the
+ <code>@TransactionAttribute</code> to the bean class.
+ </para>
+
+ <para>
+ If you are using seam managed transactions you do not need to worry about declarative
+ transaction management. Seam will automatically start a transaction for you at the
+ start of the faces request, and commit it before the render response phase.
+ </para>
+
+ <warning>
+ <para>
+ <code>@SeamApplicationException</code> will not control transaction rollback
+ when using EJB container managed transactions. If you are in an EE environment
+ then you should always use the EJB API's, namely <code>@TransactionAttribute</code>
+ and <code>@ApplicationException</code>.
+ </para>
+ </warning>
+ <note>
+ <para>
+ <code>TransactionAttributeType.REQUIRES_NEW</code> and
+ <code>TransactionAttributeType.NOT_SUPPORTED</code> are not yet supported on managed
+ beans. This will be added before seam-persistence goes final.
+ </para>
+ </note>
+ <para>
+ Lets have a look at some code. Annotations applied at a method level override annotations
+ applied at the class level.
+ </para>
+ <programlisting role="JAVA">@TransactionAttribute /*Defaults to TransactionAttributeType.REQUIRED */
+class TransactionaBean
+{
+
+ /* This is a transactional method, when this method is called a transaction
+ * will be started if one does not already exist.
+ * This behavior is inherited from the @TransactionAttribute annotation on
+ * the class.
+ */
+ void doWork()
+ {
+ ...
+ }
+
+ /* This a transaction will not be started for this method, however it */
+ /* will not complain if there is an existing transaction active. */
+ @TransactionAttributeType(TransactionAttributeType.SUPPORTED)
+ void doMoreWork()
+ {
+ ...
+ }
+
+ /* This method will throw an exception if there is no transaction active when */
+ /* it is invoked. */
+
+ @TransactionAttributeType(TransactionAttributeType.MANDATORY)
+ void doEvenMoreWork()
+ {
+ ...
+ }
+
+ /* This method will throw an exception if there is a transaction active when */
+ /* it is invoked. */
+ @TransactionAttributeType(TransactionAttributeType.NOT_SUPPORTED)
+ void doOtherWork()
+ {
+ ...
+ }
+} </programlisting>
+ </section>
+
+ </section>
+
<section id="persistence.seam-managed-persistence-contexts">
<title>Seam-managed persistence contexts</title>
<para>
- If you're using Seam outside of a Java EE 5 environment, you can't rely upon the
+ If you're using Seam outside of a Java EE environment, you can't rely upon the
container to manage the persistence context lifecycle for you. Even if you are
- in an EE 5 environment, you might have a complex application with many loosely
+ in an EE environment, you might have a complex application with many loosely
coupled components that collaborate together in the scope of a single conversation,
and in this case you might find that propagation of the persistence context between
component is tricky and error-prone.
@@ -109,27 +273,36 @@
EntityManagerFactory producerField;
</programlisting>
<para>
- This is just an ordinary resource producer field as defined by the CDI specification, however the presence of the <literal>@SeamManaged</literal>
- annotation tells seam to create a seam managed persistence context from this <literal>EntityManagerFactory</literal>. This managed
- persistence context can be injected normally, and has the same scope and qualifiers that are specified on the resource producer field.
+ This is just an ordinary resource producer field as defined by the CDI
+ specification, however the presence of the <literal>@SeamManaged</literal>
+ annotation tells seam to create a seam managed persistence context from
+ this <literal>EntityManagerFactory</literal>. This managed
+ persistence context can be injected normally, and has the same scope and
+ qualifiers that are specified on the resource producer field.
</para>
<para>
- This will work even in a SE environment where <code>@PersistenceUnit</code> injection is not normally supported. This is because
- the seam persistence extensions will bootstrap the <code>EntityManagerFactory</code> for you.
+ This will work even in a SE environment where <code>@PersistenceUnit</code>
+ injection is not normally supported. This is because the seam persistence
+ extensions will bootstrap the <code>EntityManagerFactory</code> for you.
</para>
- <note>
- <para>
- The more eagle eyed among you may have noticed that the resource producer field appears to be conversation scoped, which the CDI
- specification does not require containers to support. This is in fact not the case, as the @ConversationScoped annotation is removed
- by the seam persistence portable extension. It only specifies the scope of the created SMPC, not the EntityManagerFactory.
- </para>
- </note>
+
<para>
Now we can have our <literal>EntityManager</literal> injected using:
</para>
<programlisting role="JAVA"><![CDATA[@Inject EntityManager entityManager;]]></programlisting>
+ <note>
+ <para>
+ The more eagle eyed among you may have noticed that the resource producer
+ field appears to be conversation scoped, which the CDI specification does
+ not require containers to support. This is actually not the case, as the
+ @ConversationScoped annotation is removed by the seam persistence portable
+ extension. It only specifies the scope of the created SMPC, not the
+ EntityManagerFactory.
+ </para>
+ </note>
+
<warning>
<para>
If you are using EJB3 and mark your class or method
@@ -159,7 +332,7 @@
<para>
As with any optimistic transaction management, transaction isolation and consistency
can be achieved via use of optimistic locking. Fortunately, both Hibernate and EJB
- 3.0 make it very easy to use optimistic locking, by providing the
+ 3.1 make it very easy to use optimistic locking, by providing the
<literal>@Version</literal> annotation.
</para>
@@ -168,13 +341,11 @@
at the end of each transaction. This is sometimes the desired behavior. But very
often, we would prefer that all changes are held in memory and only written to
the database when the conversation ends successfully. This allows for truly
- atomic conversations. As the result of a truly stupid and shortsighted decision
- by certain non-JBoss, non-Sun and non-Sybase members of the EJB 3.0 expert group,
- there is currently no simple, usable and portable way to implement atomic
- conversations using EJB 3.0 persistence. However, Hibernate provides this feature
- as a vendor extension to the <literal>FlushModeType</literal>s defined by the
- specification, and it is our expectation that other vendors will soon provide
- a similar extension.
+ atomic conversations. Unfortunately there is currently no simple, usable and
+ portable way to implement atomic conversations using EJB 3.1 persistence.
+ However, Hibernate provides this feature as a vendor extension to the
+ <literal>FlushModeType</literal>s defined by the specification, and it is
+ our expectation that other vendors will soon provide a similar extension.
</para>
<para>
@@ -187,7 +358,7 @@
TODO: The next section needs to be updated to seam 3.
</para>
- <programlisting role="JAVA"><![CDATA[@In EntityManager em; //a Seam-managed persistence context
+ <programlisting role="JAVA"><![CDATA[@Inject EntityManager em; //a Seam-managed persistence context
@Begin(flushMode=MANUAL)
public void beginClaimWizard() {
@@ -282,7 +453,6 @@
session.enableFilter("myfilter");
}
</programlisting>
-
</section>
</section>
More information about the seam-commits
mailing list