[jboss-cvs] JBossAS SVN: r105608 - projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Jun 2 20:53:04 EDT 2010
Author: misty at redhat.com
Date: 2010-06-02 20:53:03 -0400 (Wed, 02 Jun 2010)
New Revision: 105608
Modified:
projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Persistence.xml
Log:
JBPAPP-4387
Modified: projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Persistence.xml
===================================================================
--- projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Persistence.xml 2010-06-02 23:30:05 UTC (rev 105607)
+++ projects/docs/enterprise/EAP/trunk/5.x/Seam_Reference_Guide/en-US/Persistence.xml 2010-06-03 00:53:03 UTC (rev 105608)
@@ -88,7 +88,7 @@
Seam transaction management is enabled by default for all JSF requests, but can be disabled in <filename>components.xml</filename>:
</para>
-<programlisting role="XML"><![CDATA[<core:init transaction-management-enabled="false"/>
+<programlisting language="XML" role="XML"><![CDATA[<core:init transaction-management-enabled="false"/>
<transaction:no-transaction />]]>
</programlisting>
@@ -100,7 +100,7 @@
Seam provides a transaction management abstraction for beginning, committing, rolling back, and synchronizing with transactions. By default, Seam uses a JTA transaction component to integrate with container-managed and programmatic EJB transactions. If you work in a Java EE 5 environment, install the EJB synchronization component in <filename>components.xml</filename>:
</para>
-<programlisting role="XML"><![CDATA[<transaction:ejb-transaction />]]>
+<programlisting language="XML" role="XML"><![CDATA[<transaction:ejb-transaction />]]>
</programlisting>
<para>
However, if you work in a non-EE 5 container, Seam attempts to auto-detect the correct transaction synchronization mechanism. If Seam is unable to detect the correct mechanism, you may need to configure one of the following:
@@ -131,19 +131,19 @@
To configure JPA RESOURCE_LOCAL transaction management, add the following to your <filename>components.xml</filename>, where <literal>#{em}</literal> is the name of the <literal>persistence:managed-persistence-context</literal> component. If your managed persistence context is named <literal>entityManager</literal>, you may leave out the <literal>entity-manager</literal> attribute. (For further information, see <xref linkend="persistence.seam-managed-persistence-contexts" />.)
</para>
-<programlisting role="XML"><![CDATA[<transaction:entity-transaction entity-manager="#{em}"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<transaction:entity-transaction entity-manager="#{em}"/>]]>
</programlisting>
<para>
To configure Hibernate managed transactions, declare the following in your <filename>components.xml</filename>, where <literal>#{hibernateSession}</literal> is the name of the project's <literal>persistence:managed-hibernate-session</literal> component. If your managed hibernate session is named <literal>session</literal>, you can opt to leave out the <literal>session</literal> attribute. (For further information, see <xref linkend="persistence.seam-managed-persistence-contexts"/>.)
</para>
-<programlisting role="XML"><![CDATA[<transaction:hibernate-transaction session="#{hibernateSession}"/>]]>
+<programlisting language="XML" role="XML"><![CDATA[<transaction:hibernate-transaction session="#{hibernateSession}"/>]]>
</programlisting>
<para>
To explicitly disable Seam managed transactions, declare the following in your <filename>components.xml</filename>:
</para>
-<programlisting role="XML"><![CDATA[<transaction:no-transaction />]]>
+<programlisting language="XML" role="XML"><![CDATA[<transaction:no-transaction />]]>
</programlisting>
<para>
For information about configuring Spring-managed transactions see <xref linkend="spring-transactions" />.
@@ -176,7 +176,7 @@
Configuring a managed persistence context is easy. In <filename>components.xml</filename>, write:
</para>
-<programlisting role="XML"><![CDATA[<persistence:managed-persistence-context name="bookingDatabase"
+<programlisting language="XML" role="XML"><![CDATA[<persistence:managed-persistence-context name="bookingDatabase"
auto-create="true"
persistence-unit-jndi-name="java:/EntityManagerFactories/bookingData"/>]]>
</programlisting>
@@ -187,15 +187,14 @@
You must bind the <literal>EntityManagerFactory</literal> into JNDI. In JBoss, you can do this by adding the following property setting to <filename>persistence.xml</filename>.
</para>
-<programlisting role="XML"><![CDATA[<property name="jboss.entity.manager.factory.jndi.name"
+<programlisting language="XML" role="XML"><![CDATA[<property name="jboss.entity.manager.factory.jndi.name"
value="java:/EntityManagerFactories/bookingData"/>]]>
</programlisting>
<para>
Now we can inject our <literal>EntityManager</literal> with:
</para>
-<programlisting role="JAVA"><![CDATA[@In EntityManager bookingDatabase;]]>
-</programlisting>
+<programlisting language="Java" role="JAVA">@In EntityManager bookingDatabase;</programlisting>
<para>
If you use EJB3, and mark your class or method <literal>@TransactionAttribute(REQUIRES_NEW)</literal>, then the transaction and persistence context should not propagate to method calls on this object. However, since the Seam-managed persistence context propagates to any component within the conversation, it propagates to methods marked <literal>REQUIRES_NEW</literal>. Therefore, if you mark a method <literal>REQUIRES_NEW</literal>, you should access the entity manager with <literal>@PersistenceContext</literal>.
</para>
@@ -207,7 +206,7 @@
Seam-managed Hibernate sessions work in a similar fashion. In <filename>components.xml</filename>:
</para>
-<programlisting role="XML"><![CDATA[<persistence:hibernate-session-factory name="hibernateSessionFactory"/>
+<programlisting language="XML" role="XML"><![CDATA[<persistence:hibernate-session-factory name="hibernateSessionFactory"/>
<persistence:managed-hibernate-session name="bookingDatabase"
auto-create="true"
@@ -217,7 +216,7 @@
Here, <literal>java:/bookingSessionFactory</literal> is the name of the session factory specified in <filename>hibernate.cfg.xml</filename>.
</para>
-<programlisting role="XML"><![CDATA[<session-factory name="java:/bookingSessionFactory">
+<programlisting language="XML" role="XML"><![CDATA[<session-factory name="java:/bookingSessionFactory">
<property name="transaction.flush_before_completion">true</property>
<property name="connection.release_mode">after_statement</property>
<property name="transaction.manager_lookup_class">
@@ -241,8 +240,7 @@
We can now inject a managed Hibernate <literal>Session</literal> into our JavaBean components with the following code:
</para>
-<programlisting role="JAVA"><![CDATA[@In Session bookingDatabase;]]>
-</programlisting>
+<programlisting language="Java" role="JAVA">@In Session bookingDatabase;</programlisting>
</section>
<section>
@@ -260,41 +258,41 @@
Seam lets you specify <literal>FlushModeType.MANUAL</literal> when beginning a conversation. Currently, this works only when Hibernate is the underlying persistence provider, but we plan to support other equivalent vendor extensions.
</para>
-<programlisting role="JAVA"><![CDATA[@In EntityManager em; //a Seam-managed persistence context
+<programlisting language="Java" role="JAVA">@In EntityManager em; //a Seam-managed persistence context
@Begin(flushMode=MANUAL)
public void beginClaimWizard() {
claim = em.find(Claim.class, claimId);
-}]]>
+}
</programlisting>
<para>
Now, the <literal>claim</literal> object remains managed by the persistence context for the entire conversation. We can make changes to the claim:
</para>
-<programlisting role="JAVA"><![CDATA[public void addPartyToClaim() {
+<programlisting language="Java" role="JAVA">public void addPartyToClaim() {
Party party = ....;
claim.addParty(party);
-}]]>
+}
</programlisting>
<para>
But these changes will not be flushed to the database until we explicitly force synchronization to occur:
</para>
-<programlisting role="JAVA"><![CDATA[@End public void commitClaim() {
+<programlisting language="Java" role="JAVA">@End public void commitClaim() {
em.flush();
-}]]>
+}
</programlisting>
<para>
You can also set the <literal>flushMode</literal> to <literal>MANUAL</literal> from pages.xml, for example in a navigation rule:
</para>
-<programlisting role="XML"><![CDATA[<begin-conversation flush-mode="MANUAL" />]]>
+<programlisting language="XML" role="XML"><![CDATA[<begin-conversation flush-mode="MANUAL" />]]>
</programlisting>
<para>
You can set any Seam-managed persistence context to use manual flush mode:
</para>
-<programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+<programlisting language="XML" role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
xmlns:core="http://jboss.com/products/seam/core">
<core:manager conversation-timeout="120000"
default-flush-mode="manual" />
@@ -313,28 +311,28 @@
Regardless of your vendor, there are several approaches to using the delegate in your Seam components. One approach is:
</para>
-<programlisting role="JAVA"><![CDATA[@In EntityManager entityManager;
+<programlisting language="Java" role="JAVA">@In EntityManager entityManager;
@Create public void init() {
((Session)entityManager.getDelegate() ).enableFilter("currentVersions");
-}]]>
+}
</programlisting>
<para>
If you, like most Java users, would rather avoid using typecasts, you can also access the delegate by adding the following line to <filename>components.xml</filename>:
</para>
-<programlisting role="XML"><![CDATA[<factory name="session" scope="STATELESS" auto-create="true"
+<programlisting language="XML" role="XML"><![CDATA[<factory name="session" scope="STATELESS" auto-create="true"
value="#{entityManager.delegate}"/>]]>
</programlisting>
<para>
The session can now be injected directly:
</para>
-<programlisting role="JAVA"><![CDATA[@In Session session;
+<programlisting language="Java" role="JAVA">@In Session session;
@Create
public void init() {
session.enableFilter("currentVersions");
-}]]>
+}
</programlisting>
</section>
@@ -344,24 +342,24 @@
Seam proxies the <literal>EntityManager</literal> or <literal>Session</literal> object whenever you use a Seam-managed persistence context or inject a container-managed persistence context with <literal>@PersistenceContext</literal>. This lets you safely and efficiently use EL expressions in your query strings. For example, this:
</para>
-<programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=#{user.username}")
- .getSingleResult();]]>
+<programlisting language="Java" role="JAVA">User user = em.createQuery("from User where username=#{user.username}")
+ .getSingleResult();
</programlisting>
<para>
is equivalent to:
</para>
-<programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=:username")
+<programlisting language="Java" role="JAVA">User user = em.createQuery("from User where username=:username")
.setParameter("username", user.getUsername())
- .getSingleResult();]]>
+ .getSingleResult();
</programlisting>
<warning>
<para>
This should <emphasis>never</emphasis> be written as:
</para>
-<programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username="
- + user.getUsername()).getSingleResult(); //BAD!]]>
+<programlisting language="Java" role="JAVA">User user = em.createQuery("from User where username="
+ + user.getUsername()).getSingleResult(); //BAD!
</programlisting>
<para>
This is inefficient, but more importantly, it is vulnerable to SQL injection attacks.
@@ -378,7 +376,7 @@
Seam-managed persistence contexts can have a list of filters defined, which will be enabled whenever an <literal>EntityManager</literal> or Hibernate <literal>Session</literal> is first created. (These can only be used when Hibernate is the underlying persistence provider.)
</para>
-<programlisting role="XML"><![CDATA[<persistence:filter name="regionFilter">
+<programlisting language="XML" role="XML"><![CDATA[<persistence:filter name="regionFilter">
<persistence:name>region</persistence:name>
<persistence:parameters>
<key>regionCode</key>
More information about the jboss-cvs-commits
mailing list