[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><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">
<modelVersion>4.0.0</modelVersion>
@@ -78,7 +82,7 @@
<artifactId>spring-context</artifactId>
<version>3.0.5.RELEASE</version>
</dependency>
- <dependency>
+ <dependency>s
<groupId>org.springframework</groupId>
<artifactId>spring-context-support</artifactId>
<version>3.0.5.RELEASE</version>
@@ -125,4 +129,317 @@
</project>
</programlisting>
</section>
+
+ <section>
+ <title>Modified starting pom.xml file for Petclinic migration</title>
+
+ <programlisting><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">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.springframework.samples</groupId>
+ <artifactId>petclinic</artifactId>
+ <name>petclinic</name>
+ <packaging>war</packaging>
+ <version>1.0.0-SNAPSHOT</version>
+ <properties>
+ <spring.version>3.0.0.RELEASE</spring.version>
+ <slf4j.version>1.5.6</slf4j.version>
+ </properties>
+ <dependencies>
+
+ <!-- Spring -->
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-context</artifactId>
+ <version>${spring.version}</version>
+ <exclusions>
+ <!-- Exclude Commons Logging in favor of SLF4j -->
+ <exclusion>
+ <groupId>commons-logging</groupId>
+ <artifactId>commons-logging</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-orm</artifactId>
+ <version>${spring.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-oxm</artifactId>
+ <version>${spring.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-web</artifactId>
+ <version>${spring.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-webmvc</artifactId>
+ <version>${spring.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-aspects</artifactId>
+ <version>${spring.version}</version>
+ </dependency>
+ <!-- AspectJ -->
+ <dependency>
+ <groupId>org.aspectj</groupId>
+ <artifactId>aspectjweaver</artifactId>
+ <version>1.6.8</version>
+ </dependency>
+
+ <!-- Logging -->
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-api</artifactId>
+ <version>${slf4j.version}</version>
+ </dependency>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-jcl</artifactId>
+ <version>${slf4j.version}</version>
+ <scope>runtime</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.slf4j</groupId>
+ <artifactId>slf4j-log4j12</artifactId>
+ <version>${slf4j.version}</version>
+ <scope>runtime</scope>
+ </dependency>
+ <dependency>
+ <groupId>log4j</groupId>
+ <artifactId>log4j</artifactId>
+ <version>1.2.15</version>
+ <scope>runtime</scope>
+ <exclusions>
+ <exclusion>
+ <groupId>com.sun.jdmk</groupId>
+ <artifactId>jmxtools</artifactId>
+ </exclusion>
+ <exclusion>
+ <groupId>com.sun.jmx</groupId>
+ <artifactId>jmxri</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+
+ <!-- DataSource -->
+ <dependency>
+ <groupId>commons-dbcp</groupId>
+ <artifactId>commons-dbcp</artifactId>
+ <version>1.2.2</version>
+ <scope>runtime</scope>
+ </dependency>
+ <dependency>
+ <groupId>commons-pool</groupId>
+ <artifactId>commons-pool</artifactId>
+ <version>1.5.3</version>
+ <scope>runtime</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.hsqldb</groupId>
+ <artifactId>hsqldb</artifactId>
+ <version>1.8.0.10</version>
+ <scope>runtime</scope>
+ </dependency>
+ <!-- MySQL JDBC Connector -->
+ <!--
+ <dependency> <groupId>com.mysql.jdbc</groupId>
+ <artifactId>com.springsource.com.mysql.jdbc</artifactId>
+ <version>5.1.6</version> </dependency>
+ -->
+
+ <!-- Hibernate -->
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-core</artifactId>
+ <version>3.3.1.GA</version>
+ </dependency>
+
+ <!-- JPA -->
+ <dependency>
+ <groupId>javax.persistence</groupId>
+ <artifactId>persistence-api</artifactId>
+ <version>1.0</version>
+ </dependency>
+
+ <dependency>
+ <groupId>toplink.essentials</groupId>
+ <artifactId>toplink-essentials</artifactId>
+ <version>2.0-58g</version>
+ </dependency>
+ <!-- Hibernate JPA Provider -->
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-entitymanager</artifactId>
+ <version>3.4.0.GA</version>
+ <exclusions>
+ <!-- Exclude Commons Logging in favor of SLF4j -->
+ <exclusion>
+ <groupId>commons-logging</groupId>
+ <artifactId>commons-logging</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-annotations</artifactId>
+ <version>3.4.0.GA</version>
+ <exclusions>
+ <!-- Exclude Commons Logging in favor of SLF4j -->
+ <exclusion>
+ <groupId>commons-logging</groupId>
+ <artifactId>commons-logging</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ <!-- Open JPA Provider -->
+ <dependency>
+ <groupId>org.apache.openjpa</groupId>
+ <artifactId>openjpa</artifactId>
+ <version>1.1.0</version>
+ <exclusions>
+ <!-- Exclude Commons Logging in favor of SLF4j -->
+ <exclusion>
+ <groupId>commons-logging</groupId>
+ <artifactId>commons-logging</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+
+ <!-- Servlet -->
+ <dependency>
+ <groupId>javax.servlet</groupId>
+ <artifactId>servlet-api</artifactId>
+ <version>2.5</version>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>javax.servlet.jsp</groupId>
+ <artifactId>jsp-api</artifactId>
+ <version>2.1</version>
+ <scope>provided</scope>
+ </dependency>
+ <dependency>
+ <groupId>javax.servlet.jsp.jstl</groupId>
+ <artifactId>jstl-api</artifactId>
+ <version>1.2</version>
+ <exclusions>
+ <exclusion>
+ <groupId>javax.el</groupId>
+ <artifactId>el-api</artifactId>
+ </exclusion>
+ </exclusions>
+ </dependency>
+ <dependency>
+ <groupId>taglibs</groupId>
+ <artifactId>standard</artifactId>
+ <version>1.1.2</version>
+ </dependency>
+
+ <!-- Rome RSS -->
+ <dependency>
+ <groupId>rome</groupId>
+ <artifactId>rome</artifactId>
+ <version>0.9</version>
+ </dependency>
+ <dependency>
+ <groupId>org.jdom</groupId>
+ <artifactId>jdom</artifactId>
+ <version>1.1</version>
+ <scope>runtime</scope>
+ </dependency>
+
+ <!-- Test dependencies -->
+ <dependency>
+ <groupId>junit</groupId>
+ <artifactId>junit</artifactId>
+ <version>4.7</version>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>org.springframework</groupId>
+ <artifactId>spring-test</artifactId>
+ <version>${spring.version}</version>
+ <scope>test</scope>
+ </dependency>
+ <dependency>
+ <groupId>javax.transaction</groupId>
+ <artifactId>transaction-api</artifactId>
+ <version>1.1</version>
+ <scope>test</scope>
+ </dependency>
+
+ </dependencies>
+
+ <repositories>
+ <repository>
+ <id>jboss-public-repository-group</id>
+ <name>JBoss Public Maven Repository Group</name>
+ <url>https://repository.jboss.org/nexus/content/groups/public/</url>
+ <layout>default</layout>
+ <releases>
+ <enabled>true</enabled>
+ <updatePolicy>never</updatePolicy>
+ </releases>
+ <snapshots>
+ <enabled>true</enabled>
+ <updatePolicy>never</updatePolicy>
+ </snapshots>
+ </repository>
+ </repositories>
+
+
+ <build>
+ <plugins>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-compiler-plugin</artifactId>
+ <configuration>
+ <verbose>true</verbose>
+ <source>1.5</source>
+ <target>1.5</target>
+ <showWarnings>true</showWarnings>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-surefire-plugin</artifactId>
+ <configuration>
+ <includes>
+ <include>**/*Tests.java</include>
+ </includes>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-war-plugin</artifactId>
+ <configuration>
+ <warName>petclinic</warName>
+ </configuration>
+ </plugin>
+ <plugin>
+ <groupId>org.apache.maven.plugins</groupId>
+ <artifactId>maven-dependency-plugin</artifactId>
+ <executions>
+ <execution>
+ <id>install</id>
+ <phase>install</phase>
+ <goals>
+ <goal>sources</goal>
+ </goals>
+ </execution>
+ </executions>
+ </plugin>
+ </plugins>
+ </build>
+</project>
+</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><jee:jndi-lookup id="dataSource" jndi-name="java:/ExampleDsJndiName" expected-type="javax.sql.DataSource"/></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"><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="PetClinic" transaction-type="JTA">
+
+ <jta-data-source>java:/DefaultDS</jta-data-source>
+ <!-- Explicitly define mapping file path, else Hibernate won't find the default -->
+ <mapping-file>META-INF/orm.xml</mapping-file>
+
+ <!-- Prevent annotation scanning. In this app we are purely driven by orm.xml -->
+ <exclude-unlisted-classes>true</exclude-unlisted-classes>
+
+ <properties>
+ <property name="jboss.entity.manager.factory.jndi.name" value="java:/petclinic/emf"/>
+ </properties>
+ </persistence-unit>
+</persistence></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 <jee:jndi-lookup/> 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
+ <tx:jta-transaction-manager/> 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"> <bean id="sessionFactory" class="org.springframework.orm.hibernate3.LocalSessionFactoryBean"
+ p:dataSource-ref="dataSource" p:mappingResources="petclinic.hbm.xml">
+ <property name="hibernateProperties">
+ <props>
+ <prop key="hibernate.dialect">${hibernate.dialect}</prop>
+ <prop key="hibernate.show_sql">${hibernate.show_sql}</prop>
+ <prop key="hibernate.generate_statistics">${hibernate.generate_statistics}</prop>
+ <prop key="hibernate.current_session_context_class">jta</prop>
+ <prop key="transaction.manager_lookup_class">org.hibernate.transaction.JBossTransactionManagerLookup</prop>
+ <prop key="hibernate.transaction.factory_class">org.hibernate.transaction.JTATransactionFactory</prop>
+ </props>
+ </property>
+ <property name="eventListeners">
+ <map>
+ <entry key="merge">
+ <bean class="org.springframework.orm.hibernate3.support.IdTransferringMergeEventListener"/>
+ </entry>
+ </map>
+ </property>
+ </bean>
+
+
+ <bean id="transactionManager" class="org.springframework.transaction.jta.JtaTransactionManager"/>
+
+</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> <jee:jndi-lookup id="entityManagerFactory" jndi-name="java:/petclinic/emf" expected-type="javax.persistence.EntityManagerFactory"/>
+
+ <tx:jta-transaction-manager/>
+</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/<profile>/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><bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
+ <property name="jpaVendorAdapter">
+ <bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter"/>
+ </property>
+ <property name="persistenceXmlLocation" value="classpath*:META-INF/persistence.xml"/>
+ <property name="jpaProperties">
+ <props>
+ <prop key="hibernate.transaction.manager_lookup_class">
+ org.hibernate.transaction.JBossTransactionManagerLookup
+ </prop>
+ </props>
+ </property>
+</bean></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><jee:local-slsb><code></code><jee:remote-slsb></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