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

jboss-cvs-commits at lists.jboss.org jboss-cvs-commits at lists.jboss.org
Thu Mar 24 18:17:57 EDT 2011


Author: marius.bogoevici
Date: 2011-03-24 18:17:55 -0400 (Thu, 24 Mar 2011)
New Revision: 111024

Modified:
   projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Appendix_A.xml
   projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Migration_Guide.xml
   projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml
Log:
Extra content

Modified: projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Appendix_A.xml
===================================================================
--- projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Appendix_A.xml	2011-03-24 20:19:52 UTC (rev 111023)
+++ projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Appendix_A.xml	2011-03-24 22:17:55 UTC (rev 111024)
@@ -5,11 +5,15 @@
 %BOOK_ENTITIES;
 ]>
 <appendix>
-  <title id="appendix_maven_deps">POM.xml for the introductory example</title>
+  <title id="appendix_maven_deps">Content of pom.xml files for the
+  examples</title>
 
   <section>
-    <para>In order to</para>
+    <title>Content of pom.xml file for the introductory example
+    (getting-started)</title>
 
+    <para></para>
+
     <programlisting>&lt;project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
    xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"&gt;
    &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
@@ -78,7 +82,7 @@
          &lt;artifactId&gt;spring-context&lt;/artifactId&gt;
          &lt;version&gt;3.0.5.RELEASE&lt;/version&gt;
       &lt;/dependency&gt;
-      &lt;dependency&gt;
+      &lt;dependency&gt;s
          &lt;groupId&gt;org.springframework&lt;/groupId&gt;
          &lt;artifactId&gt;spring-context-support&lt;/artifactId&gt;
          &lt;version&gt;3.0.5.RELEASE&lt;/version&gt;
@@ -125,4 +129,317 @@
 &lt;/project&gt;
 </programlisting>
   </section>
+
+  <section>
+    <title>Modified starting pom.xml file for Petclinic migration</title>
+
+    <programlisting>&lt;project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+         xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd"&gt;
+    &lt;modelVersion&gt;4.0.0&lt;/modelVersion&gt;
+    &lt;groupId&gt;org.springframework.samples&lt;/groupId&gt;
+    &lt;artifactId&gt;petclinic&lt;/artifactId&gt;
+    &lt;name&gt;petclinic&lt;/name&gt;
+    &lt;packaging&gt;war&lt;/packaging&gt;
+    &lt;version&gt;1.0.0-SNAPSHOT&lt;/version&gt;
+    &lt;properties&gt;
+        &lt;spring.version&gt;3.0.0.RELEASE&lt;/spring.version&gt;
+        &lt;slf4j.version&gt;1.5.6&lt;/slf4j.version&gt;
+    &lt;/properties&gt;
+    &lt;dependencies&gt;
+
+        &lt;!-- Spring --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.springframework&lt;/groupId&gt;
+            &lt;artifactId&gt;spring-context&lt;/artifactId&gt;
+            &lt;version&gt;${spring.version}&lt;/version&gt;
+            &lt;exclusions&gt;
+                &lt;!-- Exclude Commons Logging in favor of SLF4j --&gt;
+                &lt;exclusion&gt;
+                    &lt;groupId&gt;commons-logging&lt;/groupId&gt;
+                    &lt;artifactId&gt;commons-logging&lt;/artifactId&gt;
+                &lt;/exclusion&gt;
+            &lt;/exclusions&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.springframework&lt;/groupId&gt;
+            &lt;artifactId&gt;spring-orm&lt;/artifactId&gt;
+            &lt;version&gt;${spring.version}&lt;/version&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.springframework&lt;/groupId&gt;
+            &lt;artifactId&gt;spring-oxm&lt;/artifactId&gt;
+            &lt;version&gt;${spring.version}&lt;/version&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.springframework&lt;/groupId&gt;
+            &lt;artifactId&gt;spring-web&lt;/artifactId&gt;
+            &lt;version&gt;${spring.version}&lt;/version&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.springframework&lt;/groupId&gt;
+            &lt;artifactId&gt;spring-webmvc&lt;/artifactId&gt;
+            &lt;version&gt;${spring.version}&lt;/version&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.springframework&lt;/groupId&gt;
+            &lt;artifactId&gt;spring-aspects&lt;/artifactId&gt;
+            &lt;version&gt;${spring.version}&lt;/version&gt;
+        &lt;/dependency&gt;
+        &lt;!-- AspectJ --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.aspectj&lt;/groupId&gt;
+            &lt;artifactId&gt;aspectjweaver&lt;/artifactId&gt;
+            &lt;version&gt;1.6.8&lt;/version&gt;
+        &lt;/dependency&gt;
+
+        &lt;!-- Logging --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.slf4j&lt;/groupId&gt;
+            &lt;artifactId&gt;slf4j-api&lt;/artifactId&gt;
+            &lt;version&gt;${slf4j.version}&lt;/version&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.slf4j&lt;/groupId&gt;
+            &lt;artifactId&gt;slf4j-jcl&lt;/artifactId&gt;
+            &lt;version&gt;${slf4j.version}&lt;/version&gt;
+            &lt;scope&gt;runtime&lt;/scope&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.slf4j&lt;/groupId&gt;
+            &lt;artifactId&gt;slf4j-log4j12&lt;/artifactId&gt;
+            &lt;version&gt;${slf4j.version}&lt;/version&gt;
+            &lt;scope&gt;runtime&lt;/scope&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;log4j&lt;/groupId&gt;
+            &lt;artifactId&gt;log4j&lt;/artifactId&gt;
+            &lt;version&gt;1.2.15&lt;/version&gt;
+            &lt;scope&gt;runtime&lt;/scope&gt;
+            &lt;exclusions&gt;
+                &lt;exclusion&gt;
+                    &lt;groupId&gt;com.sun.jdmk&lt;/groupId&gt;
+                    &lt;artifactId&gt;jmxtools&lt;/artifactId&gt;
+                &lt;/exclusion&gt;
+                &lt;exclusion&gt;
+                    &lt;groupId&gt;com.sun.jmx&lt;/groupId&gt;
+                    &lt;artifactId&gt;jmxri&lt;/artifactId&gt;
+                &lt;/exclusion&gt;
+            &lt;/exclusions&gt;
+        &lt;/dependency&gt;
+
+        &lt;!-- DataSource --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;commons-dbcp&lt;/groupId&gt;
+            &lt;artifactId&gt;commons-dbcp&lt;/artifactId&gt;
+            &lt;version&gt;1.2.2&lt;/version&gt;
+            &lt;scope&gt;runtime&lt;/scope&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;commons-pool&lt;/groupId&gt;
+            &lt;artifactId&gt;commons-pool&lt;/artifactId&gt;
+            &lt;version&gt;1.5.3&lt;/version&gt;
+            &lt;scope&gt;runtime&lt;/scope&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.hsqldb&lt;/groupId&gt;
+            &lt;artifactId&gt;hsqldb&lt;/artifactId&gt;
+            &lt;version&gt;1.8.0.10&lt;/version&gt;
+            &lt;scope&gt;runtime&lt;/scope&gt;
+        &lt;/dependency&gt;
+        &lt;!-- MySQL JDBC Connector --&gt;
+        &lt;!--
+              &lt;dependency&gt; &lt;groupId&gt;com.mysql.jdbc&lt;/groupId&gt;
+              &lt;artifactId&gt;com.springsource.com.mysql.jdbc&lt;/artifactId&gt;
+              &lt;version&gt;5.1.6&lt;/version&gt; &lt;/dependency&gt;
+          --&gt;
+
+        &lt;!-- Hibernate --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.hibernate&lt;/groupId&gt;
+            &lt;artifactId&gt;hibernate-core&lt;/artifactId&gt;
+            &lt;version&gt;3.3.1.GA&lt;/version&gt;
+        &lt;/dependency&gt;
+
+        &lt;!-- JPA --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;javax.persistence&lt;/groupId&gt;
+            &lt;artifactId&gt;persistence-api&lt;/artifactId&gt;
+            &lt;version&gt;1.0&lt;/version&gt;
+        &lt;/dependency&gt;
+
+        &lt;dependency&gt;
+            &lt;groupId&gt;toplink.essentials&lt;/groupId&gt;
+            &lt;artifactId&gt;toplink-essentials&lt;/artifactId&gt;
+            &lt;version&gt;2.0-58g&lt;/version&gt;
+        &lt;/dependency&gt;
+        &lt;!-- Hibernate JPA Provider --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.hibernate&lt;/groupId&gt;
+            &lt;artifactId&gt;hibernate-entitymanager&lt;/artifactId&gt;
+            &lt;version&gt;3.4.0.GA&lt;/version&gt;
+            &lt;exclusions&gt;
+                &lt;!-- Exclude Commons Logging in favor of SLF4j --&gt;
+                &lt;exclusion&gt;
+                    &lt;groupId&gt;commons-logging&lt;/groupId&gt;
+                    &lt;artifactId&gt;commons-logging&lt;/artifactId&gt;
+                &lt;/exclusion&gt;
+            &lt;/exclusions&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.hibernate&lt;/groupId&gt;
+            &lt;artifactId&gt;hibernate-annotations&lt;/artifactId&gt;
+            &lt;version&gt;3.4.0.GA&lt;/version&gt;
+            &lt;exclusions&gt;
+                &lt;!-- Exclude Commons Logging in favor of SLF4j --&gt;
+                &lt;exclusion&gt;
+                    &lt;groupId&gt;commons-logging&lt;/groupId&gt;
+                    &lt;artifactId&gt;commons-logging&lt;/artifactId&gt;
+                &lt;/exclusion&gt;
+            &lt;/exclusions&gt;
+        &lt;/dependency&gt;
+        &lt;!-- Open JPA Provider --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.apache.openjpa&lt;/groupId&gt;
+            &lt;artifactId&gt;openjpa&lt;/artifactId&gt;
+            &lt;version&gt;1.1.0&lt;/version&gt;
+            &lt;exclusions&gt;
+                &lt;!-- Exclude Commons Logging in favor of SLF4j --&gt;
+                &lt;exclusion&gt;
+                    &lt;groupId&gt;commons-logging&lt;/groupId&gt;
+                    &lt;artifactId&gt;commons-logging&lt;/artifactId&gt;
+                &lt;/exclusion&gt;
+            &lt;/exclusions&gt;
+        &lt;/dependency&gt;
+
+        &lt;!-- Servlet --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;javax.servlet&lt;/groupId&gt;
+            &lt;artifactId&gt;servlet-api&lt;/artifactId&gt;
+            &lt;version&gt;2.5&lt;/version&gt;
+            &lt;scope&gt;provided&lt;/scope&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;javax.servlet.jsp&lt;/groupId&gt;
+            &lt;artifactId&gt;jsp-api&lt;/artifactId&gt;
+            &lt;version&gt;2.1&lt;/version&gt;
+            &lt;scope&gt;provided&lt;/scope&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;javax.servlet.jsp.jstl&lt;/groupId&gt;
+            &lt;artifactId&gt;jstl-api&lt;/artifactId&gt;
+            &lt;version&gt;1.2&lt;/version&gt;
+            &lt;exclusions&gt;
+                &lt;exclusion&gt;
+                    &lt;groupId&gt;javax.el&lt;/groupId&gt;
+                    &lt;artifactId&gt;el-api&lt;/artifactId&gt;
+                &lt;/exclusion&gt;
+            &lt;/exclusions&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;taglibs&lt;/groupId&gt;
+            &lt;artifactId&gt;standard&lt;/artifactId&gt;
+            &lt;version&gt;1.1.2&lt;/version&gt;
+        &lt;/dependency&gt;
+
+        &lt;!-- Rome RSS --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;rome&lt;/groupId&gt;
+            &lt;artifactId&gt;rome&lt;/artifactId&gt;
+            &lt;version&gt;0.9&lt;/version&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.jdom&lt;/groupId&gt;
+            &lt;artifactId&gt;jdom&lt;/artifactId&gt;
+            &lt;version&gt;1.1&lt;/version&gt;
+            &lt;scope&gt;runtime&lt;/scope&gt;
+        &lt;/dependency&gt;
+
+        &lt;!-- Test dependencies --&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;junit&lt;/groupId&gt;
+            &lt;artifactId&gt;junit&lt;/artifactId&gt;
+            &lt;version&gt;4.7&lt;/version&gt;
+            &lt;scope&gt;test&lt;/scope&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;org.springframework&lt;/groupId&gt;
+            &lt;artifactId&gt;spring-test&lt;/artifactId&gt;
+            &lt;version&gt;${spring.version}&lt;/version&gt;
+            &lt;scope&gt;test&lt;/scope&gt;
+        &lt;/dependency&gt;
+        &lt;dependency&gt;
+            &lt;groupId&gt;javax.transaction&lt;/groupId&gt;
+            &lt;artifactId&gt;transaction-api&lt;/artifactId&gt;
+            &lt;version&gt;1.1&lt;/version&gt;
+            &lt;scope&gt;test&lt;/scope&gt;
+        &lt;/dependency&gt;
+
+    &lt;/dependencies&gt;
+
+    &lt;repositories&gt;
+        &lt;repository&gt;
+            &lt;id&gt;jboss-public-repository-group&lt;/id&gt;
+            &lt;name&gt;JBoss Public Maven Repository Group&lt;/name&gt;
+            &lt;url&gt;https://repository.jboss.org/nexus/content/groups/public/&lt;/url&gt;
+            &lt;layout&gt;default&lt;/layout&gt;
+            &lt;releases&gt;
+                &lt;enabled&gt;true&lt;/enabled&gt;
+                &lt;updatePolicy&gt;never&lt;/updatePolicy&gt;
+            &lt;/releases&gt;
+            &lt;snapshots&gt;
+                &lt;enabled&gt;true&lt;/enabled&gt;
+                &lt;updatePolicy&gt;never&lt;/updatePolicy&gt;
+            &lt;/snapshots&gt;
+        &lt;/repository&gt;
+    &lt;/repositories&gt;
+
+
+    &lt;build&gt;
+        &lt;plugins&gt;
+            &lt;plugin&gt;
+                &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
+                &lt;artifactId&gt;maven-compiler-plugin&lt;/artifactId&gt;
+                &lt;configuration&gt;
+                    &lt;verbose&gt;true&lt;/verbose&gt;
+                    &lt;source&gt;1.5&lt;/source&gt;
+                    &lt;target&gt;1.5&lt;/target&gt;
+                    &lt;showWarnings&gt;true&lt;/showWarnings&gt;
+                &lt;/configuration&gt;
+            &lt;/plugin&gt;
+            &lt;plugin&gt;
+                &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
+                &lt;artifactId&gt;maven-surefire-plugin&lt;/artifactId&gt;
+                &lt;configuration&gt;
+                    &lt;includes&gt;
+                        &lt;include&gt;**/*Tests.java&lt;/include&gt;
+                    &lt;/includes&gt;
+                &lt;/configuration&gt;
+            &lt;/plugin&gt;
+            &lt;plugin&gt;
+                &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
+                &lt;artifactId&gt;maven-war-plugin&lt;/artifactId&gt;
+                &lt;configuration&gt;
+                    &lt;warName&gt;petclinic&lt;/warName&gt;
+                &lt;/configuration&gt;
+            &lt;/plugin&gt;
+            &lt;plugin&gt;
+                &lt;groupId&gt;org.apache.maven.plugins&lt;/groupId&gt;
+                &lt;artifactId&gt;maven-dependency-plugin&lt;/artifactId&gt;
+                &lt;executions&gt;
+                    &lt;execution&gt;
+                        &lt;id&gt;install&lt;/id&gt;
+                        &lt;phase&gt;install&lt;/phase&gt;
+                        &lt;goals&gt;
+                            &lt;goal&gt;sources&lt;/goal&gt;
+                        &lt;/goals&gt;
+                    &lt;/execution&gt;
+                &lt;/executions&gt;
+            &lt;/plugin&gt;
+        &lt;/plugins&gt;
+    &lt;/build&gt;
+&lt;/project&gt;
+</programlisting>
+
+    <para></para>
+  </section>
 </appendix>

Modified: projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Migration_Guide.xml
===================================================================
--- projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Migration_Guide.xml	2011-03-24 20:19:52 UTC (rev 111023)
+++ projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Migration_Guide.xml	2011-03-24 22:17:55 UTC (rev 111024)
@@ -12,7 +12,7 @@
   JBoss Enterprise Web Server. At the same time, more sophisticated
   environments such as JBoss Enterprise Application Platform and JBoss
   Enterprise Web Platform offer a wider variety of middleware services such as
-  transaction management, messaging or web service integration. </para>
+  transaction management, messaging or web service integration.</para>
 
   <para>In this chapter we will illustrate how Spring applications which have
   been originally developed for servlet containers can be migrated to take
@@ -53,6 +53,71 @@
     factories, connection factories and transaction managers.</para>
 
     <simplesect>
+      <title>Avoiding the inclusion of server-provided dependencies</title>
+
+      <para>The JBoss Enterprise platforms already provide a number of
+      dependencies that are required by applications. This is unlike servlet
+      containers, where applications need to package a significant number of
+      libraries in order to provide access to certain Java EE 5 technologies.
+      So, one of the first things that needs to be considered in the migration
+      process is changing the deployable build by removing the libraries which
+      are already provided by the application server. It is not just an
+      improvement which reduces the size of the final build, but also a
+      requirement, since the inclusion of those libraries will, most likely,
+      result in classloading errors. For an analogy, this is in all respects
+      similar to what applications already do with respect to the Servlet API
+      when running in a </para>
+
+      <para>Some examples of libraries provided by JBoss AS which do not need
+      to be included in the application are:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>The Java EE 5 APIs (JPA, JSTL, JMS and many others);</para>
+        </listitem>
+
+        <listitem>
+          <para>Hibernate (including Hibernate as a JPA provider)</para>
+        </listitem>
+
+        <listitem>
+          <para>JSF</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>Please consult the list of components included in JBoss EAP for a
+      complete list. Of course, the components mentioned above may be required
+      as compile-time dependencies, so please make sure that they are included
+      in the project, but not packaged in the final build. In Maven builds,
+      this can be achieved by setting the scope to 'provided' and in JBDS by
+      unchecking the 'Exported' flag for the dependency. Other build systems
+      have their own respective mechanisms of achieving the same goal.</para>
+
+      <para>On the other hand, components and frameworks that are not part of
+      the Java EE 5 implementation but are certified for use with JBoss AS 5
+      need to be included in your application. Such components are:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>Spring Framework (consult the Spring Installation Guide for
+          more details)</para>
+        </listitem>
+
+        <listitem>
+          <para>Snowdrop</para>
+        </listitem>
+
+        <listitem>
+          <para>Facelets</para>
+        </listitem>
+
+        <listitem>
+          <para>RichFaces</para>
+        </listitem>
+      </itemizedlist>
+    </simplesect>
+
+    <simplesect>
       <title>Migrating datasource definitions</title>
 
       <para>Almost all servlet containers support the usage of JNDI-bound
@@ -80,11 +145,13 @@
         administration guide on how to deploy the,) which are JNDI-accessible.
         In order to replace the above defined datasource with a managed,
         JNDI-accessible datasource, you need to replace the bean definition
-        with a JNDI object reference as in <xref linkend="???" />.</para>
+        with a JNDI object reference as in <xref
+        linkend="jboss-managed-ds" />.</para>
       </example>
 
       <example>
-        <title>Using a JBoss managed datasource in Spring</title>
+        <title id="jboss-managed-ds">Using a JBoss managed datasource in
+        Spring</title>
 
         <programlisting>&lt;jee:jndi-lookup id="dataSource" jndi-name="java:/ExampleDsJndiName" expected-type="javax.sql.DataSource"/&gt;</programlisting>
 
@@ -169,7 +236,7 @@
       isn't. More specifically, a persistence unit definition contained in a
       META-INF/persistence.xml file will be automatically deployed by the
       container, cannot declare a RESOURCE_LOCAL transaction type and must
-      include a JTA datasource reference. </para>
+      include a JTA datasource reference.</para>
 
       <para>On the other hand, it is quite common for applications that are
       deployed in a servlet container to use RESOURCE_LOCAL transactions as
@@ -263,7 +330,7 @@
         definition as in the following example (please note that it is not
         necessary to provide values for both 'jboss.entity.manager.jndi.name'
         and 'jboss.entity.manager.factory.jndi.name', but at least the entity
-        manager or the entity manager factory </para>
+        manager or the entity manager factory</para>
       </example>
 
       <example>
@@ -334,25 +401,290 @@
   <section>
     <title>Spring's PetClinic</title>
 
-    <para>The PetClinic application is one </para>
+    <para>Our first migration use case is based on the Spring PetClinic sample
+    application, which can be checked out from
+    https://src.springframework.org/svn/spring-samples/petclinic/trunk/.</para>
 
-    <para>The migration of the default Petclinic example to JBoss is fairly
-    simple and involves the following steps:</para>
+    <para>The example provides a number of alternative data access
+    implementations that can be used alternatively by changing the web.xml
+    file. We will show the migration strategies in each and every case, noting
+    that only one of these strategies is used at a time.</para>
 
+    <simplesect>
+      <title>Preliminary changes</title>
+
+      <para>Before starting the actual migration process, we will make a few
+      adjustments to the POM file, in order to retrieve dependencies from
+      Maven Central and/or the JBoss repository. The changes consist of
+      renaming artifacts and do not affect the structure of the project, in
+      the sense that the final build will be equivalent with the original in
+      terms of included dependencies, except that it will built with
+      components retrieved from Maven Central and the JBoss repository. The
+      changed pom can be found in Appendix A, and you can just copy its
+      contents over the original pom.xml.</para>
+    </simplesect>
+
+    <simplesect>
+      <title>Adjusting dependencies</title>
+
+      <para>One of the first things that we need to focus on is adjusting
+      dependency scopes. They will need to change as follows:</para>
+
+      <itemizedlist>
+        <listitem>
+          <para>commons-dbcp:commons-dbcp, commons-pool:commons:pool and
+          org.hsqldb:hsqldb become test-scoped dependencies - a pooled
+          datasource will be retrieved from JNDI at runtime, so they are
+          needed only for running tests;</para>
+        </listitem>
+
+        <listitem>
+          <para>javax.persistence:persistence-api,
+          org.hibernate:hibernate-core, org.hibernate:hibernate-entitymanager,
+          org.hibernate:hibernate-annotations become provided-scope
+          dependencies - JBoss enterprise platforms include a JPA
+          implementation, so there is no need for the application to include
+          these libraries in the WAR, however they are needed for compiling
+          the application, however, they are needed for compiling and running
+          unit tests;</para>
+        </listitem>
+
+        <listitem>
+          <para>javax.servlet.jsp.jstl:jstl-api needs to be set as a provided
+          dependency again, since it is available in JBoss;</para>
+        </listitem>
+
+        <listitem>
+          <para>toplink.essentials:toplink-essentials and
+          org.apache.openjpa:openjpa will be removed from the dependency set -
+          since we will use Hibernate exclusively as a JPA provider.</para>
+        </listitem>
+      </itemizedlist>
+
+      <para>At this point, the set of dependencies of the application is
+      compatible with JBoss.</para>
+    </simplesect>
+
+    <simplesect>
+      <title>Renaming files</title>
+
+      <para>A slightly unexpected set of changes is caused by the naming of
+      the application context definition files. In particular, the file
+      applicationContext-hibernate.xml found in
+      /src/main/webapp/WEB-INF/spring may cause problems when deployed in
+      JBoss EAP, since the Hibernate deployer will try to process it, which
+      can result in a deployment failure. So we will rename the four
+      applicationContext-*.xml files from /src/main/webapp/WEB-INF/spring to:
+      applicationContextDataSource.xml, applicationContextHibernate.xml,
+      applicationContextJdbc.xml and applicationContextJpa.xml, respectively.
+      Since they are referred from web.xml, that file has to change as
+      well.</para>
+    </simplesect>
+
+    <simplesect>
+      <title>Switching to a JTA and managed persistence context model</title>
+
+      <para>First, we need to make the persistence unit definition deployable
+      by JBoss. In order to do so, we will copy jpa-persistence.xml to
+      /src/test/resources/META-INF (check the test section to see why) and
+      rename it to persistence.xml. After that we will change its contents to
+      make it Java EE 5-compatible as described in the previous sections. The
+      end result is:</para>
+
+      <example>
+        <title>Migrated persistence.xml definition</title>
+
+        <para><programlisting lang="xml">&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;
+
+ &lt;persistence-unit name="PetClinic" transaction-type="JTA"&gt;
+
+  &lt;jta-data-source&gt;java:/DefaultDS&lt;/jta-data-source&gt;
+ &lt;!-- Explicitly define mapping file path, else Hibernate won't find the default --&gt;
+  &lt;mapping-file&gt;META-INF/orm.xml&lt;/mapping-file&gt;
+
+  &lt;!-- Prevent annotation scanning. In this app we are purely driven by orm.xml --&gt;
+  &lt;exclude-unlisted-classes&gt;true&lt;/exclude-unlisted-classes&gt;
+
+  &lt;properties&gt;
+     &lt;property name="jboss.entity.manager.factory.jndi.name" value="java:/petclinic/emf"/&gt;            
+  &lt;/properties&gt;
+ &lt;/persistence-unit&gt;
+&lt;/persistence&gt;</programlisting></para>
+      </example>
+
+      <para>For this migration, we will just use the default datasource
+      provided by JBoss - but feel free to replace with a datasource JNDI name
+      that is specific to your environment. As well, we will instruct the
+      deployer to bind the EntityManagerFactory in JNDI under a specific
+      name.</para>
+
+      <para>Now that we intend to use a Java EE datasource, we need to reflect
+      that in the configuration file. Go to applicationContextDataSource.xml,
+      comment the DBCP-based datasource definition, and uncomment the one
+      using the &lt;jee:jndi-lookup/&gt; element. Now the datasource will be
+      provided by a JNDI lookup.</para>
+
+      <para>For simple JDBC access, we need to switch the transaction model to
+      JTA. Therefore, we need to change the applicationContextJdbc.xml file by
+      replacing the DataSourceTransactionManager bean definition with the one
+      using the JtaTransactionManager (or the
+      &lt;tx:jta-transaction-manager/&gt; element),</para>
+
+      <para>For Hibernate access, we also need to adjust the definition of the
+      Hibernate SessionFactory, in order to make it JTA-aware. We will modify
+      applicationContextHibernate.xml next by adding the JTA configuration
+      properties to the SessionFactory definition, removing the
+      HibernateTransactionManager and switching transaction management to JTA
+      by uncommenting the JtaTransactionManager bean definition.<example>
+          <title>Migrated SessionFactory and transaction manager
+          /definition</title>
+
+          <para></para>
+
+          <programlisting lang="xml">	&lt;bean id="sessionFactory" class="org.springframework.orm.hibernate3.LocalSessionFactoryBean"
+			p:dataSource-ref="dataSource" p:mappingResources="petclinic.hbm.xml"&gt;
+		&lt;property name="hibernateProperties"&gt;
+			&lt;props&gt;
+				&lt;prop key="hibernate.dialect"&gt;${hibernate.dialect}&lt;/prop&gt;
+				&lt;prop key="hibernate.show_sql"&gt;${hibernate.show_sql}&lt;/prop&gt;
+				&lt;prop key="hibernate.generate_statistics"&gt;${hibernate.generate_statistics}&lt;/prop&gt;
+                &lt;prop key="hibernate.current_session_context_class"&gt;jta&lt;/prop&gt;
+                &lt;prop key="transaction.manager_lookup_class"&gt;org.hibernate.transaction.JBossTransactionManagerLookup&lt;/prop&gt;
+                &lt;prop key="hibernate.transaction.factory_class"&gt;org.hibernate.transaction.JTATransactionFactory&lt;/prop&gt;
+			&lt;/props&gt;
+		&lt;/property&gt;
+		&lt;property name="eventListeners"&gt;
+			&lt;map&gt;
+				&lt;entry key="merge"&gt;
+					&lt;bean class="org.springframework.orm.hibernate3.support.IdTransferringMergeEventListener"/&gt;
+				&lt;/entry&gt;
+			&lt;/map&gt;
+		&lt;/property&gt;
+	&lt;/bean&gt;
+
+
+	&lt;bean id="transactionManager" class="org.springframework.transaction.jta.JtaTransactionManager"/&gt;
+
+</programlisting>
+        </example></para>
+
+      <para>Finally, we will to change the JPA configuration. In order to do
+      so, we will remove the EntityManagerFactory bean definition from
+      applicationContextJpa and replace it with an EntityManagerFactory
+      lookup, as well as changing transaction management to JTA.</para>
+
+      <example>
+        <title>Migrated JPA EntityManagerFactory definition and </title>
+
+        <para><programlisting>    &lt;jee:jndi-lookup id="entityManagerFactory" jndi-name="java:/petclinic/emf" expected-type="javax.persistence.EntityManagerFactory"/&gt;
+
+    &lt;tx:jta-transaction-manager/&gt;
+</programlisting></para>
+      </example>
+    </simplesect>
+
+    <simplesect>
+      <title>Adjusting unit tests</title>
+
+      <para>The most important change to the unit tests is caused by switching
+      our JPA from Spring-managed to container-managed. As such, unit tests,
+      which run outside a container, will still need to have access to a
+      EntityManagerFactory. So, we will use the original jpa-persistence.xml
+      file, which we copied underneath /src/test/resources/META-INF while we
+      were doing the migration. </para>
+
+      <para>We also need to make sure that OpenJpaEntityManagerClinicTests and
+      EntityManagerClinicTests do not run during the build (since we aren't
+      using neither OpenJpa nor Toplink). This can be simply done by
+      annotating them with @Ignore.</para>
+
+      <para>This concludes the migration of Spring's Petclinic application to
+      JBoss. You can build the project using maven and copy the resulting war
+      (target/petclinic.war) to $JBOSS_HOME/server/&lt;profile&gt;/deploy, or
+      you can import the Maven project in JBDS (if you have the m2eclipse
+      plugin installed).</para>
+    </simplesect>
+  </section>
+
+  <section>
+    <title>Spring Travel</title>
+
+    <para>The case of Spring Travel
+    (https://src.springframework.org/svn/spring-samples/travel/) is very
+    similar to Petclinic, in the sense that it will need to follow the series
+    of steps for migration:</para>
+
     <itemizedlist>
       <listitem>
-        <para>switching to a managed datasource;</para>
+        <para>Before the migration: adapting the POM to use the JBoss
+        repositories or Maven central (one particular concern is that the
+        example is using a version of Hibernate - the migrated POM may
+        ;</para>
       </listitem>
 
       <listitem>
-        <para>switching transaction management strategy to JTA;</para>
+        <para>Setting the proper scopes for dependencies;</para>
       </listitem>
+
+      <listitem>
+        <para>Switching datasources, transaction managers, persistence unit
+        and entity manager factories to JTA.</para>
+      </listitem>
     </itemizedlist>
-  </section>
 
-  <section>
-    <title>Spring Travel</title>
+    <para>Because of the similarities, we will leave the details out. However,
+    the reason why we have chosen Spring Travel as the second migration case
+    is because of it is in a particular respect different from
+    Petclinic.</para>
 
-    <para></para>
+    <simplesect>
+      <title>The special case of flow-scoped persistence </title>
+
+      <para>While in general using a JNDI-provided EntityMangerFactory or
+      EntityManager is a better suited solution, there are cases when using a
+      JTA-based LocalContainerEntityManagerFactory may be necessary. As shown
+      in the previous chapter, this is necessary when the application relies
+      on the support for the read-only transactions in Spring. In the
+      particular case of Spring Webflow, this is necessary when the
+      application uses a flow-scoped persistence context. In such cases, the
+      persistence context is flushed only when the flow ends so any other
+      transactional operations must complete without saving the persistence
+      context (which is what, in short, the read-only flag is supposed to do).
+      <footnote>
+          <para>For details on flow-scoped persistence contexts and their
+          usage, please consult the Spring Web Flow documentation</para>
+        </footnote> </para>
+
+      <para>Since the project will not use a JNDI-based persistence unit
+      anymore, we can suppress its deployment by renaming the persistence.xml
+      file to jpa-persistence.xml.</para>
+
+      <para>The EntityManagerFactory bean definition found in data.xml needs
+      to change as follows:</para>
+
+      <example>
+        <title>Changing Spring Travel's EntityManagerFactory bean definition
+        to support JTA</title>
+
+        <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="persistenceXmlLocation" value="classpath*:META-INF/persistence.xml"/&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>
+
+        <para></para>
+      </example>
+    </simplesect>
   </section>
 </chapter>

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-24 20:19:52 UTC (rev 111023)
+++ projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml	2011-03-24 22:17:55 UTC (rev 111024)
@@ -581,7 +581,7 @@
         classpath (otherwise said, it performs a
         'classpath*:beanRefContext.xml' lookup), which contains a single
         application context definition. Example <xref linkend="???" />
-        contains the definition of such a file. </para>
+        contains the definition of such a file.</para>
 
         <example>
           <title>Simple beanRefContext.xml file used by a
@@ -620,7 +620,7 @@
         deployable module (EAR, WAR, or EJB-JAR) and match a specific pattern
         (by default, *-spring.xml), will bootstrap ApplicationContexts which
         are further registered in JNDI under a name which can be configured
-        from within the context definition. </para>
+        from within the context definition.</para>
 
         <example id="spring-deployer-xml">
           <title>Spring beans configuration file (example-spring.xml)</title>
@@ -674,7 +674,7 @@
 
       <para>EJB references can be defined as Spring beans using the
       <code>&lt;jee:local-slsb&gt;<code></code>&lt;jee:remote-slsb&gt;</code>
-      elements, as in example </para>
+      elements, as in example</para>
 
       <example>
         <title>Definiting an EJB reference as a Spring bean</title>



More information about the jboss-cvs-commits mailing list