[jboss-cvs] JBossAS SVN: r110931 - projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US.

jboss-cvs-commits at lists.jboss.org jboss-cvs-commits at lists.jboss.org
Wed Mar 16 14:01:20 EDT 2011


Author: marius.bogoevici
Date: 2011-03-16 14:01:20 -0400 (Wed, 16 Mar 2011)
New Revision: 110931

Modified:
   projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Getting_Started_Introductory_Example.xml
   projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml
Log:
Updated

Modified: projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Getting_Started_Introductory_Example.xml
===================================================================
--- projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Getting_Started_Introductory_Example.xml	2011-03-16 15:41:28 UTC (rev 110930)
+++ projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Getting_Started_Introductory_Example.xml	2011-03-16 18:01:20 UTC (rev 110931)
@@ -75,8 +75,8 @@
       <title>Creating the Maven project structure</title>
 
       <para>Creating a Maven-based web application from JBDS is fairly easy,
-      if the m2eclipse plugin (both core an WTP integration) is installed.
-      </para>
+      if the m2eclipse plugin (both core an WTP integration) is
+      installed.</para>
 
       <para>Go to New-&gt;Maven Project (may need to select the 'Other' option
       first). Leave the 'Create a simple project' option unchecked, as we want
@@ -92,8 +92,8 @@
       'org.jboss.spring.getting.started' although no package will be created
       at this point, so the option is not in use.</para>
 
-      <para>So, after doing all this, the end result should look similar to
-      this:</para>
+      <para>The following dependencies need to be included in your
+      application:</para>
 
       <para>The artifact may not create the Java source folder, so you may
       have to add it yourself. Go to 'New'-&gt;Source Folder and enter a value
@@ -182,7 +182,7 @@
       declaratively, which with this particular setup means that
       getForUsername() will execute in its own transaction, if a transaction
       isn't started yet (this may change with other configuration options, as
-      Spring supports different transaction propagation modes). </para>
+      Spring supports different transaction propagation modes).</para>
 
       <programlisting>@Service
 public class UserDaoImpl implements UserDao {
@@ -200,7 +200,7 @@
 
       <para>In the web tier, we will need a controller and a web page for
       displaying the results. So we will create the UserController class
-      first. </para>
+      first.</para>
 
       <programlisting>@Controller
 @RequestMapping("say-hello")
@@ -236,7 +236,7 @@
       which will be mapped to it also depends on the rest of the Spring
       configuration. Spring MVC uses the Front Controller pattern, which means
       that the requests are dispatched by a servlet, and the mappings in this
-      class are relative to the mapping of the servlet. </para>
+      class are relative to the mapping of the servlet.</para>
 
       <para>The class serves as backing to a web form, and different methods
       need to execute when the form page is initially requested (GET) and data
@@ -330,7 +330,7 @@
       <para>The ContextLoaderListener will boostrap an application context
       containing the business components, while the DispatcherServlet will
       create an application context using the former as its parent (and thus
-      having access to its bean definitions). </para>
+      having access to its bean definitions).</para>
 
       <para>From src/main/webapp/WEB-INF, create a Spring bean definition
       file, by selecting New-&gt;Spring Bean Definition File and enter a file

Modified: projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml
===================================================================
--- projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml	2011-03-16 15:41:28 UTC (rev 110930)
+++ projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml	2011-03-16 18:01:20 UTC (rev 110931)
@@ -141,12 +141,13 @@
     </section>
 
     <section>
-      <title>Defining a JPA persistence unit</title>
+      <title>Using JPA</title>
 
-      <para>Spring applications that use JPA are advised to managed
-      persistence unit and access them from JNDI. In order to bind the entity
-      manager or entity manager factory under a well-established name,
-      applications can use special Hibernate configuration properties.</para>
+      <para>Spring applications can retrieve the persistence units deployed by
+      the container by looking them up in JNDI. In order to be able to bind
+      the entity manager or entity manager factory under a well-established
+      name and subsequently look them up, applications can use special
+      Hibernate configuration properties.</para>
 
       <example>
         <title>Persistence unit definition</title>
@@ -194,8 +195,11 @@
 }</programlisting></para>
       </example>
 
-      <para>An EntityManagerFactory can also be used directly, when the
-      scenario requires an application-managed entityManager.</para>
+      <para>As an alternative, an EntityManagerFactory can also be used
+      directly, either relying on Spring's ability of performing
+      @PersistenceContext injection with a transactional EntityManager or when
+      the scenario requires an application-managed entityManager. Here is an
+      example of acquiring the entityManagerFactory from JNDI.</para>
 
       <example>
         <title>Spring bean representing an entity manager factory</title>
@@ -207,15 +211,82 @@
       example a service that delegates to multiple DAOs which have to be
       enrolled in the same transaction), it is not typical to access
       EntityManagerFactories directly. Rather, components should access the
-      JNDI-bound EntityManager. However, EntityManagerFactory beans are
-      typically used in scenarios that span multiple transactions such as
-      conversations. For example, Spring Web Flow requires access to an
-      EntityManager in order to provide a conversation-scoped persistence
-      context. In such a case, you can use the JNDI-bound
-      EntityManagerFactory.</para>
+      JNDI-bound EntityManager, as it is JTA-synchronized and will be shared
+      with non-Spring components that use JPA as well (e.g. EJBs). </para>
 
-      <para>You can find a more detailed usage example in the Sportsclub
-      application.</para>
+      <para>One important limitation of working with JNDI-bound EntityManagers
+      and EntityManagerFactories is the lack of support for read-only
+      transactions in Spring. When declaring transactions, Spring applications
+      may specify that the transaction is intended to be read-only:</para>
+
+      <example>
+        <title>A Spring class declaring a read-only transaction</title>
+
+        <programlisting>@Transaction(readOnly = true)
+public List&lt;Account&gt; getAllAccounts() {
+     return return entityManager.createQuery("SELECT a FROM Account").getResultList();;
+  }</programlisting>
+      </example>
+
+      <para>A common misconception is that the readOnly flag will prevent the
+      transaction from committing. What it actually means is that the
+      application is not expected to change the entities retrieved in the
+      persistence context, therefore it can be flushed at the end of the
+      transaction. As such, the readOnly flag is a hint to Spring, which will
+      attempt to prevent the persistence context (and in the case of using
+      Hibernate as a persistence provider, underlying SessionFactory) from
+      being automatically flushed upon commit. The expected benefit of this
+      operation mode is a performance increase, as the persistence context
+      will be simply discarded when the transaction ends. It should be noted
+      that support for this mode is not obligatory in Spring, and applications
+      are not expected to rely on this behaviour at all time (cf. Spring
+      reference documentation for details).</para>
+
+      <para>This behaviour is supported by Spring-defined
+      EntityManagerFactories for certain JPA providers (Hibernate which is the
+      JPA provider for JBoss being one of them), but not when the
+      EntityManager or EntityManagerFactory is provided from JNDI. Therefore,
+      in any circumstance when the application needs support for readOnly
+      persistence contexts, a JTA-integrated
+      LocalContainerEntityManagerFactoryBean should be used instead. An
+      example of such a bean definition for JBoss is provided here:</para>
+
+      <example>
+        <title>A Spring-defined JTA-based entity manager factory</title>
+
+        <para><programlisting>    &lt;bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"&gt;
+        &lt;property name="jpaVendorAdapter"&gt;
+            &lt;bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter"/&gt;
+        &lt;/property&gt;
+        &lt;property name="jpaProperties"&gt;
+            &lt;props&gt;
+                &lt;prop key="hibernate.transaction.manager_lookup_class"&gt;
+                    org.hibernate.transaction.JBossTransactionManagerLookup
+                &lt;/prop&gt;
+            &lt;/props&gt;
+        &lt;/property&gt;
+    &lt;/bean&gt;</programlisting>The above definition relies upon a
+        META-INF/persistence.xml file being provided in the deployment.
+        However, in such a case it may be worth considering whether it is
+        necessary to have a container-deployed persistence unit as well, since
+        the Spring application will not use it. If that is not the case, you
+        can use another location as shown here:e</para>
+
+        <para>When doing so, it is worth considering whether the application
+        still needs JBoss to deploy a persistence unit. If not, the
+        persistence unit definition file can be placed in an alternative
+        location, and the Spring bean definition can be changed as in the
+        following example. </para>
+      </example>
+
+      <example>
+        <title>Using an alternative location for persistence.xml </title>
+
+        <para><programlisting>&lt;bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean"&gt;
+        &lt;property name="persistenceXmlLocation" value="classpath*:META-INF/persistence-booking.xml"/&gt;
+&lt;!-- other properties (ommitted) --&gt;
+    &lt;/bean&gt;</programlisting></para>
+      </example>
     </section>
   </section>
 
@@ -260,14 +331,13 @@
     <para>Whenever a message arrives to the destination, it will be converted
     to the argument type of the method <emphasis>pojoHandlerMethod</emphasis>
     of the messageDrivenPojo bean which will be invoked by the container. Any
-    regular bean can be a message-driven POJO, the only restriction beigng
-    that the handling method must have a single argument. Spring will take
-    care of converting message content to the expected argument type. For a
-    JCA-based container, the invocation will be automatically enrolled in a
-    JTA transaction.</para>
+    regular bean can be a message-driven POJO, the only restriction being that
+    the handling method must have a single argument. Spring will take care of
+    converting message content to the expected argument type. For a JCA-based
+    container, the invocation will be automatically enrolled in a JTA
+    transaction.</para>
 
-    <para>A message-driven POJO example is provided in the following
-    listing:</para>
+    <para>A message-driven POJO is provided in the following listing:</para>
 
     <para><example>
         <title>A message-driven POJO is a regular bean type</title>
@@ -328,7 +398,7 @@
     transparently and shared with other components.</para>
 
     <para>Please note that in the case of message-driven beans, the message
-    handling invocations are already enrolled in a JTA transaction. </para>
+    handling invocations are already enrolled in a JTA transaction.</para>
   </section>
 
   <section>
@@ -357,9 +427,8 @@
   </section>
 
   <section>
-   <title>This needs content to build</title>
-   <para>
-   This needs content to build.
-   </para>
+    <title>This needs content to build</title>
+
+    <para>This needs content to build.</para>
   </section>
 </chapter>



More information about the jboss-cvs-commits mailing list