[jboss-cvs] JBossAS SVN: r111235 - projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Thu Apr 21 15:51:23 EDT 2011
Author: marius.bogoevici
Date: 2011-04-21 15:51:23 -0400 (Thu, 21 Apr 2011)
New Revision: 111235
Modified:
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:
Some code adjustments
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-04-21 16:00:18 UTC (rev 111234)
+++ projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Migration_Guide.xml 2011-04-21 19:51:23 UTC (rev 111235)
@@ -7,25 +7,24 @@
<chapter id="Migration_Guide">
<title>Migrating applications to JBoss EAP and EWP</title>
- <!-- <para>Spring applications that have been designed to run in a servlet
+ <!-- <para>Spring applications that have been designed to run in a servlet
container such as Tomcat and Jetty will find an ideal running environment in
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> -->
- <para>This chapter explores how Spring applications that have
- been originally developed for servlet containers can be migrated to take
- advantage of the JBoss middleware service support and infrastructure.
- Sample applications provided by the Spring frameworks will be used to do so.
- </para>
+ <para>This chapter explores how Spring applications that have been
+ originally developed for servlet containers can be migrated to take
+ advantage of the JBoss middleware service support and infrastructure. Sample
+ applications provided by the Spring frameworks will be used to do so.</para>
<section>
<title>General Migration Mechanics</title>
<para>Migrating applications from a servlet container to one of the
- enterprise platforms is a process that addresses two
- distinct concerns:</para>
+ enterprise platforms is a process that addresses two distinct
+ concerns:</para>
<itemizedlist>
<listitem>
@@ -44,24 +43,24 @@
</listitem>
</itemizedlist>
- <para>Except for rare situations, migrating applications does not
- involve changes to the Java code, or the Spring bean configuration
- definitions that define the business logic of the application (bean
- wiring, aspect definitions, and controllers). The definitions that
- relate to the infrastructure are:
- datasources, session factories, entity managers, and entity managers.
- </para>
+ <para>Except for rare situations, migrating applications does not involve
+ changes to the Java code, or the Spring bean configuration definitions
+ that define the business logic of the application (bean wiring, aspect
+ definitions, and controllers). The definitions that relate to the
+ infrastructure are: datasources, session factories, entity managers, and
+ entity managers.</para>
+
<itemizedlist>
<listitem>
- <para>factories</para>
+ <para>factories</para>
</listitem>
+
<listitem>
- <para>
- connection factories
- </para>
+ <para>connection factories</para>
</listitem>
+
<listitem>
- <para>transaction manager</para>
+ <para>transaction manager</para>
</listitem>
</itemizedlist>
@@ -72,18 +71,17 @@
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.
- One of the things 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
- result in classloading errors. <!--For an analogy, this is in all respects
+ One of the things 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 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 Enterprise Application
- Platform which do not need
- to be included in the application are:</para>
+ <para>Some examples of libraries provided by JBoss Enterprise
+ Application Platform which do not need to be included in the application
+ are:</para>
<itemizedlist>
<listitem>
@@ -99,23 +97,23 @@
</listitem>
</itemizedlist>
- <para> The components above may be required
- as compile-time dependencies, so they need to be 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
- JBoss Developer Studio by unchecking the
+ <para>The components above may be required as compile-time dependencies,
+ so they need to be 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 JBoss Developer Studio by unchecking the
<guilabel>Exported</guilabel> flag for the dependency. Other build
- systems have their own respective mechanisms of achieving the same goal.</para>
+ systems have their own respective mechanisms of achieving the same
+ goal.</para>
- <para>However, components and frameworks that are not part of
- the Java EE 5 implementation but are certified for use with JBoss Enterprise
- Application Platform 5 need to be included in your application.
- These components are:</para>
+ <para>However, components and frameworks that are not part of the Java
+ EE 5 implementation but are certified for use with JBoss Enterprise
+ Application Platform 5 need to be included in your application. These
+ components are:</para>
<itemizedlist>
<listitem>
- <para>Spring Framework (consult the <citetitle>Spring Installation Guide</citetitle> for
- more details)</para>
+ <para>Spring Framework (consult the <citetitle>Spring Installation
+ Guide</citetitle> for more details)</para>
</listitem>
<listitem>
@@ -135,18 +133,17 @@
<simplesect>
<title>Migrating Datasource Definitions</title>
- <para>Most servlet containers support the use of JNDI-bound
- resources, and binding Datasources in JNDI allows for managing
- connectivity parameters such as URLs, credentials, and pool sizes
- connectivity parameters such as URLs, credentials, and pool sizes
- independently from the application code. However, Spring applications often
- rely on independent connection pool bean
- definitions, such as the ones used by commons-dbcp or c3po (see example
- <xref linkend="dbcp-ref" />).</para>
+ <para>Most servlet containers support the use of JNDI-bound resources,
+ and binding Datasources in JNDI allows for managing connectivity
+ parameters such as URLs, credentials, and pool sizes connectivity
+ parameters such as URLs, credentials, and pool sizes independently from
+ the application code. However, Spring applications often rely on
+ independent connection pool bean definitions, such as the ones used by
+ commons-dbcp or c3po (see example <xref linkend="dbcp-ref" />).</para>
<example id="dbcp-ref">
- <title>Example commons-dbcp DataSource definition in a
- servlet container</title>
+ <title>Example commons-dbcp DataSource definition in a servlet
+ container</title>
<programlisting language="XML"><bean id="dataSource" class="org.apache.commons.dbcp.BasicDataSource" destroy-method="close">
<property name="driverClassName" value="org.postgresql.Driver" />
@@ -155,38 +152,35 @@
<property name="password" value="password" />
</bean></programlisting>
- <para>JBoss provides an efficient way of deploying and
- maintaining managed datasources (see section <xref
- linkend="managed_ds" /> for more details and the <citetitle>JBoss Enterprise
- Application Platform Administration and Configuration Guide</citetitle>
- for how to deploy them,) which are JNDI-accessible.
- In order to replace the above defined datasource with a managed,
- JNDI-accessible datasource, replace the bean definition
- with a JNDI object reference as in <xref
+ <para>JBoss provides an efficient way of deploying and maintaining
+ managed datasources (see section <xref linkend="managed_ds" /> for
+ more details and the <citetitle>JBoss Enterprise Application Platform
+ Administration and Configuration Guide</citetitle> for how to deploy
+ them,) which are JNDI-accessible. In order to replace the above
+ defined datasource with a managed, JNDI-accessible datasource, replace
+ the bean definition with a JNDI object reference as in <xref
linkend="jboss-managed-ds" />.</para>
</example>
<example id="jboss-managed-ds">
- <title>Using a JBoss managed datasource in
- Spring</title>
+ <title>Using a JBoss managed datasource in Spring</title>
<programlisting language="XML"><jee:jndi-lookup id="dataSource" jndi-name="java:/ExampleDsJndiName" expected-type="javax.sql.DataSource"/></programlisting>
<para>Preserving the bean id is important for the case when the bean
- is injected by name. Indicating the expected type specifically
- is important for @Autowired scenarios.</para>
+ is injected by name. Indicating the expected type specifically is
+ important for @Autowired scenarios.</para>
</example>
</simplesect>
<simplesect>
<title>Migrating Hibernate SessionFactories to JTA</title>
- <para> User running applications on the JBoss Enterprise
- Application Platform are encouraged to use JTA for transaction
- management. In such cases, the
- infrastructure changes consist of altering the session factory
- definition to allow for JTA-backed session context and replacing the
- local Spring-based transaction manager with a
+ <para>User running applications on the JBoss Enterprise Application
+ Platform are encouraged to use JTA for transaction management. In such
+ cases, the infrastructure changes consist of altering the session
+ factory definition to allow for JTA-backed session context and replacing
+ the local Spring-based transaction manager with a
HibernateTransactionManager.</para>
<para>Listing <xref linkend="hibernate_sf" /> contains typical bean
@@ -213,11 +207,11 @@
<property name="sessionFactory" ref="sessionFactory"/>
</bean>
</programlisting>
-
- <para>These definitions can be migrated to use JTA (the datasource is
- assumed to be a managed datasource, as shown previously).</para>
</example>
+ <para>These definitions can be migrated to use JTA (the datasource is
+ assumed to be a managed datasource, as shown previously).</para>
+
<example>
<title>JTA-based SessionFactory and transaction manager</title>
@@ -238,33 +232,34 @@
<tx:jta-transaction-manager id="transactionManager"/>
</programlisting>
</example>
+
<note>
- <para>The definitions of the 'sessionFactory' bean is
- virtually unchanged; the only difference is the addition of the
- properties required for setting up the JTA-based context management
- and the transaction manager change.</para>
- </note>
+ <para>The definitions of the 'sessionFactory' bean is virtually
+ unchanged; the only difference is the addition of the properties
+ required for setting up the JTA-based context management and the
+ transaction manager change.</para>
+ </note>
</simplesect>
<simplesect>
<title>Migrating JPA-based Applications</title>
- <para>The most important aspect in
- the case of JPA is that fully-fledged Java EE 5 environments have certain
- restrictions regarding what is deployable by the container and what
- is not. Specifically, a persistence unit definition contained in a
- <filename>META-INF/persistence.xml</filename> file will be automatically deployed by the
- container, cannot declare a RESOURCE_LOCAL transaction type, and must
- include a JTA datasource reference.</para>
+ <para>The most important aspect in the case of JPA is that fully-fledged
+ Java EE 5 environments have certain restrictions regarding what is
+ deployable by the container and what is not. Specifically, a persistence
+ unit definition contained in a
+ <filename>META-INF/persistence.xml</filename> file will be automatically
+ deployed by the container, cannot declare a RESOURCE_LOCAL transaction
+ type, and must include a JTA datasource reference.</para>
- <para>However, it is quite common for applications that are
- deployed in a servlet container to use RESOURCE_LOCAL transactions as
- shown in example <xref linkend="jpa-servlet-container" />. It may also not
+ <para>However, it is quite common for applications that are deployed in
+ a servlet container to use RESOURCE_LOCAL transactions as shown in
+ example <xref linkend="jpa-servlet-container" />. It may also not
specify any transaction type (which is equivalent to setting a JTA
transaction type, but is ignored when the persistence unit is
initialized by Spring and a resource-local model will be used instead).
- It is also atypical for servlet-container based applications to use
- JTA datasources, as seen in the same example <xref
+ It is also atypical for servlet-container based applications to use JTA
+ datasources, as seen in the same example <xref
linkend="jpa-servlet-container" />.</para>
<example id="jpa-servlet-container">
@@ -313,9 +308,8 @@
and will lead to the a deployment failure if found in the typical
<filename>META-INF/persistence.xml</filename> location.</para>
- <para>
- To solve this problem and turn it into an application that can be deployed in JBoss:
- </para>
+ <para>To solve this problem and turn it into an application that can be
+ deployed in JBoss:</para>
<itemizedlist>
<listitem>
@@ -332,8 +326,8 @@
<para>When renaming the persistence unit, the alternate location can be
provided as a property to the LocalContainerEntityManagerFactoryBean as
described in example <xref linkend="jpa-pu-with-alternate-pxml" />. For
- details about using the LocalContainerEntityManagerFactoryBean in JBoss and
- its implications, please refer to the previous chapter.</para>
+ details about using the LocalContainerEntityManagerFactoryBean in JBoss
+ and its implications, please refer to the previous chapter.</para>
<example id="jpa-pu-with-alternate-pxml">
<title>LocalContainerEntityManagerFactoryBean with alternate
@@ -344,12 +338,14 @@
<!-- other properties (ommitted) -->
</bean></programlisting>
- <para>A more effective approach is converting the <filename>persistence.xml</filename>
- definition to a JTA-based model and using JNDI lookup for retrieving
- the entity manager. For this, convert the persistence unit
- definition as in the following example (please note that it is not
- necessary to provide values for <emphasis>both</emphasis> 'jboss.entity.manager.jndi.name'
- and 'jboss.entity.manager.factory.jndi.name', but one must be specified)</para>
+ <para>A more effective approach is converting the
+ <filename>persistence.xml</filename> definition to a JTA-based model
+ and using JNDI lookup for retrieving the entity manager. For this,
+ convert the persistence unit definition as in the following example
+ (please note that it is not necessary to provide values for
+ <emphasis>both</emphasis> 'jboss.entity.manager.jndi.name' and
+ 'jboss.entity.manager.factory.jndi.name', but one must be
+ specified)</para>
</example>
<example>
@@ -365,59 +361,73 @@
</properties>
</persistence-unit></programlisting>
- <para>The EntityManagerFactory or a JTA-synchronized
- EntityManager can be retrieved from JNDI as follows:
- <example>
- <title>EntityManager retrieved by JNDI lookup and JTA transaction
- manager (works with @Autowired)</title>
+ <para>The EntityManagerFactory or a JTA-synchronized EntityManager can
+ be retrieved from JNDI as follows: </para>
+ </example>
- <programlisting language="XML"><jee:jndi-lookup id="entityManager" jndi-name="java:/example/EntityManager" expected-type="javax.persistence.EntityManager"/>
+ <example>
+ <title>EntityManager retrieved by JNDI lookup and JTA transaction
+ manager (works with @Autowired)</title>
+ <programlisting language="XML"><jee:jndi-lookup id="entityManager" jndi-name="java:/example/EntityManager" expected-type="javax.persistence.EntityManager"/>
+
<tx:jta-transaction-manager/></programlisting>
+ </example>
- <para>If the original application relied on Spring to inject the
- EntityManager using the @PersistenceContext annotation into
- services and DAOs, using the EntityManager will require
- changing the annotation to @Autowired (as the bean is an
- EntityManager). In such cases, it may be better to look up
- for the EntityManagerFactory instead, and leave Spring to create
- the EntityManager.</para>
+ <para>If the original application relied on Spring to inject the
+ EntityManager using the @PersistenceContext annotation into services and
+ DAOs, using the EntityManager will require changing the annotation to
+ @Autowired (as the bean is an EntityManager). In such cases, it may be
+ better to look up for the EntityManagerFactory instead, and leave Spring
+ to create the EntityManager.</para>
- <para>A particular concern when migrating JPA-based application is
- the choice of a JPA provider. While servlet-container-based
- applications have to include a JPA implementation and specify the
- nature of the provider explicitly, JBoss Enterprise Application
- Platform uses Hibernate as a JPA provider.
- <example>
- <title>EntityManagerFactory retrieved by JNDI lookup and JTA
- transaction manager (works with @PersistenceContext)</title>
+ <para>A particular concern when migrating JPA-based application is the
+ choice of a JPA provider. While servlet-container-based applications
+ have to include a JPA implementation and specify the nature of the
+ provider explicitly, JBoss Enterprise Application Platform uses
+ Hibernate as a JPA provider.</para>
- <programlisting language="XML"><jee:jndi-lookup id="entityManager" jndi-name="java:/example/EntityManager" expected-type="javax.persistence.EntityManager"/>
+ <example>
+ <title>EntityManagerFactory retrieved by JNDI lookup and JTA
+ transaction manager (works with @PersistenceContext)</title>
+ <programlisting language="XML"><jee:jndi-lookup id="entityManager" jndi-name="java:/example/EntityManager" expected-type="javax.persistence.EntityManager"/>
+
<tx:jta-transaction-manager/></programlisting>
+ </example>
- <para>If the original application relied on Spring to inject
- the EntityManager using the @PersistenceContext annotation
- into services and DAOs, using the EntityManager
- will require changing the annotation to @Autowired (as the
- bean is an EntityManager). In such cases, it may be
- better to look up for the EntityManagerFactory instead,
- and leave Spring to create the EntityManager.</para>
+ <para>If the original application relied on Spring to inject the
+ EntityManager using the @PersistenceContext annotation into services and
+ DAOs, using the EntityManager will require changing the annotation to
+ @Autowired (as the bean is an EntityManager). In such cases, it may be
+ better to look up for the EntityManagerFactory instead, and leave Spring
+ to create the EntityManager.</para>
- <para>A particular concern when migrating JPA-based
- application is the choice of a JPA provider. While
- servlet-container-based applications have to include a JPA
- implementation and specify the nature of the provider
- explicitely, JBoss Enterprise Application Platform uses
- Hibernate as the unique JPA
- provider. In such cases, using an application-server deployed
- persistence unit simplifies the process.</para>
- </example></para>
- </example></para>
- </example>
+ <para>A particular concern when migrating JPA-based application is the
+ choice of a JPA provider. While servlet-container-based applications
+ have to include a JPA implementation and specify the nature of the
+ provider explicitely, JBoss Enterprise Application Platform uses
+ Hibernate as the unique JPA provider. In such cases, using an
+ application-server deployed persistence unit simplifies the
+ process.</para>
</simplesect>
+
+ <simplesect>
+ <title>Comparative Maven structure and building the examples</title>
+
+ <para>In what follows we will detail the changes made to a couple of
+ Spring examples in order to migrate them to JBoss. You can find the
+ finished examples in the WFK distribution. You will notice that each
+ example has two profiles: 'ews' and 'eap'. Each of these profiles
+ contributes with a different set of configuration files, applicable in
+ the EWS/servlet container scenario and the EAP scenario,
+ respectively.</para>
+
+ <para>The different files can be found in the /src/environments/eap and
+ /src/environments/ews respectively.</para>
+ </simplesect>
</section>
<section>
@@ -428,29 +438,30 @@
https://src.springframework.org/svn/spring-samples/petclinic/trunk/.</para>
<para>The example provides a number of alternative data access
- implementations that can be used alternatively by changing the <filename>web.xml</filename>
- file. This shows the migration strategies in each case, noting
- that only one of these strategies is used at a time.</para>
+ implementations that can be used alternatively by changing the
+ <filename>web.xml</filename> file. This shows the migration strategies in
+ each 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, a few
- adjustments to the POM file will be made, in order to retrieve dependencies from
- Maven Central 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 its content can be copied
- over to the original <filename>pom.xml</filename>.</para>
+ <para>Before starting the actual migration process, a few adjustments to
+ the POM file will be made, in order to retrieve dependencies from Maven
+ Central 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 its content can be copied over to the
+ original <filename>pom.xml</filename>.</para>
</simplesect>
<simplesect>
<title>Adjusting Dependencies</title>
- <para>One of the first things that need focus is adjusting
- dependency scopes. They will need to change as follows:</para>
+ <para>One of the first things that need focus is adjusting dependency
+ scopes. They will need to change as follows:</para>
<itemizedlist>
<listitem>
@@ -466,9 +477,9 @@
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, but they are needed for compiling
- the application. They are also needed for compiling and running
- unit tests;</para>
+ these libraries in the WAR, but they are needed for compiling the
+ application. They are also needed for compiling and running unit
+ tests;</para>
</listitem>
<listitem>
@@ -493,64 +504,63 @@
<para>A slightly unexpected set of changes is caused by the naming of
the application context definition files. In particular, the file
<filename>applicationContext-hibernate.xml</filename> found in
- <filename>/src/main/webapp/WEB-INF/spring</filename> may cause problems when deployed in
- JBoss Enterprise Applicaton Platform, since the Hibernate deployer will try to process it. This
- can result in a deployment failure. To avoid this, rename the four
- applicationContext-*.xml files from /src/main/webapp/WEB-INF/spring to:
- </para>
- <itemizedlist>
- <listitem>
- <para>applicationContextDataSource.xml</para>
- </listitem>
- <listitem>
- <para>
- applicationContextHibernate.xml
- </para>
- </listitem>
- <listitem>
- <para>
- applicationContextJdbc.xml
- </para>
- </listitem>
- <listitem>
- <para>
- applicationContextJpa.xm
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Since they are referred from <filename>web.xml</filename>, that file has to change as
- well.</para>
+ <filename>/src/main/webapp/WEB-INF/spring</filename> may cause problems
+ when deployed in JBoss Enterprise Applicaton Platform, since the
+ Hibernate deployer will try to process it. This can result in a
+ deployment failure. To avoid this, rename the four
+ applicationContext-*.xml files from /src/main/webapp/WEB-INF/spring
+ to:</para>
+
+ <itemizedlist>
+ <listitem>
+ <para>applicationContextDataSource.xml</para>
+ </listitem>
+
+ <listitem>
+ <para>applicationContextHibernate.xml</para>
+ </listitem>
+
+ <listitem>
+ <para>applicationContextJdbc.xml</para>
+ </listitem>
+
+ <listitem>
+ <para>applicationContextJpa.xm</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>Since they are referred from <filename>web.xml</filename>, that
+ file has to change as well.</para>
</simplesect>
<simplesect>
<title>Switching to a JTA and Managed Persistence Context Model</title>
- <para>The persistence unit definition must be made deployable
- by JBoss. In order to do so,
- </para>
- <procedure>
- <step>
- <para>Copy <filename>jpa-persistence.xml</filename> to
- <filename>/src/test/resources/META-INF</filename> </para>
- </step>
- <step>
- <para>
- Rename it to <filename>persistence.xml</filename>
- </para>
- </step>
- <step>
- <para>
- Change its contents to
- make it Java EE 5-compatible as described in the previous sections.
- </para>
- </step>
- <step>
- <title>Result</title>
- <example>
- <title>Migrated persistence.xml definition</title>
+ <para>The persistence unit definition must be made deployable by
+ JBoss. In order to do so,</para>
- <programlisting language="XML"><persistence xmlns="http://java.sun.com/xml/ns/persistence"
+ <procedure>
+ <step>
+ <para>Copy <filename>jpa-persistence.xml</filename> to
+ <filename>/src/test/resources/META-INF</filename></para>
+ </step>
+
+ <step>
+ <para>Rename it to <filename>persistence.xml</filename></para>
+ </step>
+
+ <step>
+ <para>Change its contents to make it Java EE 5-compatible as
+ described in the previous sections.</para>
+ </step>
+
+ <step>
+ <title>Result</title>
+
+ <example>
+ <title>Migrated persistence.xml definition</title>
+
+ <programlisting language="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">
@@ -564,38 +574,47 @@
<!-- 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>
- </example>
- </step>
- </procedure>
- <para>For this migration, the default datasource
- provided by JBoss will be used. You are able to replace it with a
- datasource JNDI name that is specific to your environment. The
- deployer will be instructed to bind the EntityManagerFactory in
- JNDI under a specific name.</para>
+ </example>
+ </step>
- <para>Since a Java EE datasource, this needs to be reflected
- in the configuration file. Go to <filename>applicationContextDataSource.xml</filename>,
- 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>
+ <step>
+ In order to make the managed datasource to Spring, we will need to bind it in JNDI. In order to do so, add the following code to the web.xml definition.
- <para>For simple JDBC access, the transaction model needs to
- be switched to JTA. The <filename>applicationContextJdbc.xml</filename> file
- must be changed by replacing the DataSourceTransactionManager bean
- definition with the one using the JtaTransactionManager (or the
+ <programlisting><persistence-unit-ref>
+ <persistence-unit-ref-name>persistence/petclinic-emf</persistence-unit-ref-name>
+ <persistence-unit-name>PetClinic</persistence-unit-name>
+</persistence-unit-ref> </programlisting>
+ </step>
+ </procedure>
+
+ <para>We also need a managed datasource. In this case we will use the
+ default datasource provided by JBoss. You are able to replace it with a
+ datasource JNDI name that is specific to your environment. The deployer
+ will be instructed to bind the EntityManagerFactory in JNDI under a
+ specific name.</para>
+
+ <para>Since a Java EE datasource, this needs to be reflected in the
+ configuration file. Go to
+ <filename>applicationContextDataSource.xml</filename>, 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, the transaction model needs to be switched
+ to JTA. The <filename>applicationContextJdbc.xml</filename> file must be
+ changed by replacing the DataSourceTransactionManager bean definition
+ with the one using the JtaTransactionManager (or the
<tx:jta-transaction-manager/> element).</para>
- <para>For Hibernate access, the definition of the
- Hibernate SessionFactory must be adjusted in order to make it JTA-aware.
- The <filename>applicationContextHibernate.xml</filename> is modified
- 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>
+ <para>For Hibernate access, the definition of the Hibernate
+ SessionFactory must be adjusted in order to make it JTA-aware. The
+ <filename>applicationContextHibernate.xml</filename> is modified 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>
@@ -630,15 +649,16 @@
</programlisting>
</example></para>
- <para>The JPA configuration also has to be changed. In order to do
- so, remove the EntityManagerFactory bean definition from
+ <para>The JPA configuration also has to be changed. In order to do so,
+ 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>
+ <title>Migrated JPA EntityManagerFactory definition and transaction
+ manager</title>
- <para><programlisting language="XML"> <jee:jndi-lookup id="entityManagerFactory" jndi-name="java:/petclinic/emf" expected-type="javax.persistence.EntityManagerFactory"/>
+ <para><programlisting language="XML"> <jee:jndi-lookup id="entityManagerFactory" jndi-name="java:comp/env/persistence/petclinic-emf" expected-type="javax.persistence.EntityManagerFactory"/>
<tx:jta-transaction-manager/>
</programlisting></para>
@@ -651,19 +671,21 @@
<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. Use the original <filename>jpa-persistence.xml</filename>
- file, which was copied underneath /src/test/resources/META-INF while doing the migration.</para>
+ EntityManagerFactory. Use the original
+ <filename>jpa-persistence.xml</filename> file, which was copied
+ underneath /src/test/resources/META-INF while doing the
+ migration.</para>
- <para>You also need to make sure that OpenJpaEntityManagerClinicTests and
- EntityManagerClinicTests do not run during the build (since
- OpenJpa nor Toplink are being used). Do this by
- annotating them with @Ignore.</para>
+ <para>You also need to make sure that OpenJpaEntityManagerClinicTests
+ and EntityManagerClinicTests do not run during the build (since OpenJpa
+ nor Toplink are being used). Do this 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 JBoss Developer Studio (if
- you have the m2eclipse plugin installed).</para>
+ you can import the Maven project in JBoss Developer Studio (if you have
+ the m2eclipse plugin installed).</para>
</simplesect>
</section>
@@ -693,7 +715,7 @@
</listitem>
</itemizedlist>
- <!-- <para>Because of the similarities, we will leave the details out. However,
+ <!-- <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> -->
@@ -710,17 +732,17 @@
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 the read-only flag is intended to do).
- <footnote>
+ context (which is what the read-only flag is intended 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, its deployment can be suppressed by renaming the <filename>persistence.xml</filename>
- file to <filename>jpa-persistence.xml</filename> and disabling class scanning by setting the
- metadata-complete flag in <filename>web.xml</filename> (see previous chapter for
- details).</para>
+ anymore, its deployment can be suppressed by renaming the
+ <filename>persistence.xml</filename> file to
+ <filename>jpa-persistence.xml</filename> and disabling class scanning by
+ setting the metadata-complete flag in <filename>web.xml</filename> (see
+ previous chapter for details).</para>
<para>The EntityManagerFactory bean definition found in data.xml needs
to change as follows:</para>
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-04-21 16:00:18 UTC (rev 111234)
+++ projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml 2011-04-21 19:51:23 UTC (rev 111235)
@@ -8,14 +8,13 @@
<title>Best Practices and Integration Guidelines</title>
<para>The Spring Framework is a flexible environment for developing
- enterprise applications. This means that the developer can choose
- between a number of alternatives for accessing middleware
- services.</para>
+ enterprise applications. This means that the developer can choose between a
+ number of alternatives for accessing middleware services.</para>
<para>JBoss is a feature-rich application server, which provides a complex
- set of middleware services. Spring developers can take
- advantage of those services by opting to use the dedicated Java EE
- integration features of Spring.</para>
+ set of middleware services. Spring developers can take advantage of those
+ services by opting to use the dedicated Java EE integration features of
+ Spring.</para>
<section>
<title>Setting Up Data Access</title>
@@ -23,8 +22,8 @@
<para>Spring applications can either deploy their own data access
infrastructure, or rely on a managed infrastructure provided by the
application server. The recommended practice for JBoss is to use the
- server-provided infrastructure. In general, use a managed
- infrastructure using JTA transaction management.</para>
+ server-provided infrastructure. In general, use a managed infrastructure
+ using JTA transaction management.</para>
<para>The following subsections detail the configuration strategy
for:</para>
@@ -51,16 +50,15 @@
<title>Database Access Through Managed Datasources</title>
<para>On JBoss it is recommended that managed datasources are used.
- These are accessible via JNDI, and can be deployed through a simple configuration
- file.</para>
+ These are accessible via JNDI, and can be deployed through a simple
+ configuration file.</para>
- <para>The definition for such a datasource is included in a file
- that ends in -ds.xml (for example, <filename>sportsclub-ds.xml</filename>). It can either
- be copied into the deploy directory of the target JBoss application
- server configuration for
- deployment at startup, or be included in the META-INF directory
- of the application for being deployed together with the
- application.</para>
+ <para>The definition for such a datasource is included in a file that
+ ends in -ds.xml (for example, <filename>sportsclub-ds.xml</filename>).
+ It can either be copied into the deploy directory of the target JBoss
+ application server configuration for deployment at startup, or be
+ included in the META-INF directory of the application for being deployed
+ together with the application.</para>
<example>
<title>Managed Datasource Configuration</title>
@@ -76,9 +74,9 @@
</datasources></programlisting>
</example>
- <para>The datasource is bound in JNDI at java:/ExampleDsJndiName.
- It can be referenced from a Spring ApplicationContext by using the
- following definition:</para>
+ <para>The datasource is bound in JNDI at java:/ExampleDsJndiName. It can
+ be referenced from a Spring ApplicationContext by using the following
+ definition:</para>
<example>
<title>Defining a Managed Datasource Spring Bean</title>
@@ -86,8 +84,8 @@
<programlisting language="XML"><jee:jndi-lookup id="dataSource" jndi-name="java:/ExampleDsJndiName" expected-type="javax.sql.DataSource"/></programlisting>
</example>
- <para>A datasource bean can be injected in any regular Spring bean
- (for example, a JBDS DAO).</para>
+ <para>A datasource bean can be injected in any regular Spring bean (for
+ example, a JBDS DAO).</para>
</section>
<section>
@@ -95,8 +93,8 @@
<para>Applications that use Hibernate directly (as opposed to JPA)
should take advantage of the fact that Hibernate is already included in
- the application server. This means that applications do not need to include a
- Hibernate distribution.</para>
+ the application server. This means that applications do not need to
+ include a Hibernate distribution.</para>
<para>Spring applications can use one of Spring's
SessionFactory-instantiating FactoryBeans, and a managed datasource (see
@@ -104,16 +102,17 @@
<example>
<title>SessionFactory Bean Definition</title>
- <programlisting language="XML">
+
+ <programlisting language="XML">
<bean id="sessionFactory" class="org.springframework.orm.hibernate3.annotation.AnnotationSessionFactoryBean">
<property name="dataSource" ref="dataSource"/>
...
</bean></programlisting>
</example>
- <para>JTA transaction management and Hibernate-JTA session
- management integration is recommended. You can use these by
- setting up the following properties:</para>
+ <para>JTA transaction management and Hibernate-JTA session management
+ integration is recommended. You can use these by setting up the
+ following properties:</para>
<example>
<title>JTA session management setup properties</title>
@@ -140,29 +139,30 @@
...
}</programlisting>
</example>
-
<para>A comprehensive example of using Hibernate-driven data access in
Spring-based applications can be found in the Sportsclub example
- application. It can be found in your distribution of JBoss Web Framework Kit.</para>
+ application. It can be found in your distribution of JBoss Web Framework
+ Kit.</para>
</section>
- </section>
- <section>
- <title>Using JPA</title>
+ </section>
- <section>
- <title>PersistenceUnit Deployed by the Container</title>
+ <section>
+ <title>Using JPA</title>
- <para>Spring applications can retrieve the persistence units deployed
- by the container by looking them up in JNDI. In order 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>
+ <section>
+ <title>PersistenceUnit Deployed by the Container</title>
- <example>
- <title>Persistence Unit Definition</title>
+ <para>Spring applications can retrieve the persistence units deployed by
+ the container by looking them up in JNDI. In order 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 or web.xml.</para>
- <programlisting language="XML"><persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
+ <example>
+ <title>Persistence Unit Definition with JNDI bindings</title>
+
+ <programlisting language="XML"><persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
<persistence-unit name="sportsclubPU">
<jta-data-source>java:/ExampleDsJndiName</jta-data-source>
<properties>
@@ -172,28 +172,62 @@
</properties>
</persistence-unit>
</persistence></programlisting>
- </example>
+ </example>
- <para>Spring applications can use either container-managed entity
- managers or, if necessary, application-managed entity managers (in this case,
- they will be provided with the corresponding entity manager
- factories). A container-managed entity manager can be accessed as a
- Spring Bean as follows:</para>
+ <para>Spring applications can use either container-managed entity
+ managers or, if necessary, application-managed entity managers (in this
+ case, they will be provided with the corresponding entity manager
+ factories). A container-managed entity manager can be accessed as a
+ Spring Bean as follows:</para>
- <example>
- <title>Spring Bean Representing a Container-managed Entity
- manager</title>
+ <example>
+ <title>Spring Bean Representing a Container-managed Entity
+ manager</title>
- <programlisting language="XML"><jee:jndi-lookup id="entityManager" jndi-name="java:/example/em"/></programlisting>
- </example>
+ <programlisting language="XML"><jee:jndi-lookup id="entityManager" jndi-name="java:/example/em" expected-type="javax.persistence.EntityManagerFactory"/></programlisting>
+ </example>
- <para>Such an EntityManager can be used directly if injected in
- component classes such as DAOs. <!-- When doing so, the COMMENTED OUT UNTIL THE SENTENCE IS COMPLETE--></para>
+ <para>Persistence units and persistence contexts can be also bound in
+ JNDI through web.xml as follows:</para>
- <example>
- <title>Hibernate-based DAO: a SessionFactory is Injected Directly in
- the Bean</title>
-<programlisting language="Java">public class HibernateAccountDao {
+ <example>
+ <title>Binding a persistence context and a persistence unit in
+ web.xml</title>
+
+ <programlisting><web-app>
+
+ <!-- rest of content ommitted -->
+
+ <persistence-context-ref>
+ <persistence-context-ref-name>persistence/sportsclub</persistence-context-ref-name>
+ <persistence-context-name>sportsclubPU</persistence-context-name>
+ </persistence-context-ref>
+
+ <persistence-unit-ref>
+ <persistence-unit-ref-name>persistence/sportsclub-emf</persistence-unit-ref-name>
+ <persistence-unit-name>sportsclubPU</persistence-unit-name>
+ </persistence-unit-ref>
+</web-app></programlisting>
+ </example>
+
+ <para>In this case, the corresponding Spring bean is shown below. Note
+ that the binding takes place in the java:comp/env context.</para>
+
+ <example>
+ <title>Spring Bean Representing a Container-managed Entity
+ manager</title>
+
+ <programlisting language="XML"><jee:jndi-lookup id="entityManager" jndi-name="java:/comp/env/persistence/sportsclub-emf" expected-type="javax.persistence.EntityManagerFactory"/></programlisting>
+ </example>
+
+ <para>Such an EntityManager can be used directly if injected in
+ component classes such as DAOs. <!-- When doing so, the COMMENTED OUT UNTIL THE SENTENCE IS COMPLETE--></para>
+
+ <example>
+ <title>Hibernate-based DAO: a SessionFactory is Injected Directly in
+ the Bean</title>
+
+ <programlisting language="Java">public class HibernateAccountDao {
@Autowired EntityManager entityManager;
public List<Account> getAllAccounts() {
@@ -201,80 +235,79 @@
}
...
}</programlisting>
- </example>
+ </example>
- <para>As an alternative, an EntityManagerFactory can also be used
- directly, either relying on Spring's ability to perform
- @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>
+ <para>As an alternative, an EntityManagerFactory can also be used
+ directly, either relying on Spring's ability to perform
+ @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>
+ <example>
+ <title>Spring Bean Representing an Entity Manager Factory</title>
- <programlisting language="XML"><jee:jndi-lookup id="entityManagerFactory" jndi-name="java:/example/emf"/></programlisting>
- </example>
+ <programlisting language="XML"><jee:jndi-lookup id="entityManagerFactory" jndi-name="java:/example/emf"/></programlisting>
+ </example>
- <para>In general, for implementing transaction-aware components,
- it is not typical to access EntityManagerFactories directly
- (for example a service that delegates to multiple DAOs which have to be
- enrolled in the same transaction). This is true even if Spring supports injection
- into fields annotated with @PersistenceContext when an
- EntityManagerFactory is provided. Rather, components should access the
- JNDI-bound EntityManager, as it is JTA-synchronized and will be shared
- with non-Spring components that use JPA as well (for example EJBs).</para>
+ <para>In general, for implementing transaction-aware components, it is
+ not typical to access EntityManagerFactories directly (for example a
+ service that delegates to multiple DAOs which have to be enrolled in the
+ same transaction). This is true even if Spring supports injection into
+ fields annotated with @PersistenceContext when an EntityManagerFactory
+ is provided. Rather, components should access the JNDI-bound
+ EntityManager, as it is JTA-synchronized and will be shared with
+ non-Spring components that use JPA as well (for example EJBs).</para>
- <para>A comprehensive example of using JPA-driven data access in
- Spring-based applications can be found in the Sportsclub example
- application, included in the Web Framework Kit distribution.</para>
- </section>
+ <para>A comprehensive example of using JPA-driven data access in
+ Spring-based applications can be found in the Sportsclub example
+ application, included in the Web Framework Kit distribution.</para>
+ </section>
- <section>
- <title>PersistenceUnit Created by Spring</title>
+ <section>
+ <title>PersistenceUnit Created by Spring</title>
- <para><!--One important limitation of working with JNDI-bound
+ <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 a transaction is intended to be
- read-only as in example <xref linkend="transactional-method-read-only"/>.
- </para>
+ read-only transactions in Spring. --> When declaring transactions,
+ Spring applications may specify that a transaction is intended to be
+ read-only as in example <xref
+ linkend="transactional-method-read-only" />.</para>
- <example id="transactional-method-read-only">
- <title>A Spring Method Declaring a Read-Only Transaction</title>
+ <example id="transactional-method-read-only">
+ <title>A Spring Method Declaring a Read-Only Transaction</title>
- <programlisting language="Java">@Transaction(readOnly = true)
+ <programlisting language="Java">@Transaction(readOnly = true)
public List<Account> getAllAccounts() {
return entityManager.createQuery("SELECT a FROM Account").getResultList();
}</programlisting>
- </example>
+ </example>
- <para>A common misconception is that the Read-Only flag will prevent
- the transaction from committing. In fact, it means 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 Read-Only 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 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>A common misconception is that the Read-Only flag will prevent the
+ transaction from committing. In fact, it means 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 Read-Only 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 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 (the JPA
- provider for JBoss, Hibernate, is one of them), but not when the
- EntityManager or EntityManagerFactory is provided from JNDI.
- Therefore, in any circumstance when the application needs support for
- Read-Only persistence contexts, a JTA-integrated
- LocalContainerEntityManagerFactoryBean should be used instead. An
- example of a bean definition for JBoss is provided here:</para>
+ <para>This behaviour is supported by Spring-defined
+ EntityManagerFactories for certain JPA providers (the JPA provider for
+ JBoss, Hibernate, is one of them), but not when the EntityManager or
+ EntityManagerFactory is provided from JNDI. Therefore, in any
+ circumstance when the application needs support for Read-Only
+ persistence contexts, a JTA-integrated
+ LocalContainerEntityManagerFactoryBean should be used instead. An
+ example of a bean definition for JBoss is provided here:</para>
- <example>
- <title>A Spring-defined JTA-based Entity Manager Factory</title>
+ <example>
+ <title>A Spring-defined JTA-based Entity Manager Factory</title>
- <programlisting language="XML"><bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
+ <programlisting language="XML"><bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
<property name="jpaVendorAdapter">
<bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter"/>
</property>
@@ -287,58 +320,61 @@
</property>
</bean></programlisting>
- <para>The above definition relies upon a <filename>META-INF/persistence.xml</filename>
- file being provided in the deployment. However, if it is not present,
- it may not be 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 in example <xref
- linkend="alt-location" />.</para>
- </example>
+ <para>The above definition relies upon a
+ <filename>META-INF/persistence.xml</filename> file being provided in
+ the deployment. However, if it is not present, it may not be 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 in example <xref
+ linkend="alt-location" />.</para>
+ </example>
- <example id="alt-location">
- <title>Using an Alternative Location for Persistence.xml</title>
-<programlisting language="XML"><bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
+ <example id="alt-location">
+ <title>Using an Alternative Location for Persistence.xml</title>
+
+ <programlisting language="XML"><bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
<property name="persistenceXmlLocation" value="classpath*:META-INF/persistence-booking.xml"/>
<!-- other properties (ommitted) -->
</bean></programlisting>
- </example>
+ </example>
- <para>When using the LocalContainerManagedEntityFactoryBean in JBoss,
- the WEB-INF/classes location will not be scanned for persistent
- entities, even if the persistence unit definition file is located in
- WEB-INF/classes/META-INF. This happens irrespective of whether the
- file is named <filename>persistence.xml</filename>.
- In this case, the list of entities must be provided explicitly
- through one of the following methods:</para>
+ <para>When using the LocalContainerManagedEntityFactoryBean in JBoss,
+ the WEB-INF/classes location will not be scanned for persistent
+ entities, even if the persistence unit definition file is located in
+ WEB-INF/classes/META-INF. This happens irrespective of whether the file
+ is named <filename>persistence.xml</filename>. In this case, the list of
+ entities must be provided explicitly through one of the following
+ methods:</para>
- <itemizedlist>
- <listitem>
- <para>By enumerating the persistent classes in <filename>persistence.xml</filename> (or
- however the persistence unit configuration file is named);</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>By enumerating the persistent classes in
+ <filename>persistence.xml</filename> (or however the persistence
+ unit configuration file is named);</para>
+ </listitem>
- <listitem>
- <para>By packaging the entities in a jar file and provide a
- <jar-file/> configuration entry in <filename>persistence.xml</filename>;</para>
- </listitem>
+ <listitem>
+ <para>By packaging the entities in a jar file and provide a
+ <jar-file/> configuration entry in
+ <filename>persistence.xml</filename>;</para>
+ </listitem>
- <listitem>
- <para>Using a PersistenceUnitPostprocessor;</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para>Using a PersistenceUnitPostprocessor;</para>
+ </listitem>
+ </itemizedlist>
- <para>The first two solutions are based on the standard functionality
- of JPA. The third solution, however, is Spring-specific and involves
- implementing a PersistenceUnitPostprocessor class that will add the
- persistent classes directly to the PersistenceUnitInfo object, as in
- the following example:</para>
+ <para>The first two solutions are based on the standard functionality of
+ JPA. The third solution, however, is Spring-specific and involves
+ implementing a PersistenceUnitPostprocessor class that will add the
+ persistent classes directly to the PersistenceUnitInfo object, as in the
+ following example:</para>
- <example>
- <title>Example of a PersistenceUnitPostProcessor Implementation That
- Adds all Classes Annotated with @Entity</title>
+ <example>
+ <title>Example of a PersistenceUnitPostProcessor Implementation That
+ Adds all Classes Annotated with @Entity</title>
- <programlisting language="Java">package org.springframework.webflow.samples.booking;
+ <programlisting language="Java">package org.springframework.webflow.samples.booking;
import java.io.IOException;
@@ -379,15 +415,16 @@
}
}
</programlisting>
- </example>
+ </example>
- <para>A bean of this class can be injected in the
- LocalContainerEntityManagerFactoryBean as follows:
- </para>
- <example>
- <title>Adding the PersistenceUnitPostProcessor to the Context
- Definition</title>
- <programlisting language="XML"><bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
+ <para>A bean of this class can be injected in the
+ LocalContainerEntityManagerFactoryBean as follows:</para>
+
+ <example>
+ <title>Adding the PersistenceUnitPostProcessor to the Context
+ Definition</title>
+
+ <programlisting language="XML"><bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
<!-- other properties -->
<property name="persistenceUnitPostProcessors">
<list>
@@ -395,106 +432,102 @@
</list>
</property>
</bean></programlisting>
- </example>
- </section>
+ </example>
+ </section>
- <section>
- <title>@PersistenceContext and @PersistenceUnit Injection</title>
+ <section>
+ <title>@PersistenceContext and @PersistenceUnit Injection</title>
- <para>Spring does @PersistenceContext injection into Spring components
- on its own. In order to do so, applications need to be have access to
- an EntityManagerFactory bean (either created by Spring or looked up in
- JNDI). </para>
+ <para>Spring does @PersistenceContext injection into Spring components
+ on its own. In order to do so, applications need to be have access to an
+ EntityManagerFactory bean (either created by Spring or looked up in
+ JNDI).</para>
- <para>In certain cases, however, the presence of
- @PersistenceContext/@PersistenceUnit annotations in Spring beans may
- cause deployment errors, when the <filename>persistence.xml</filename> file has been
- renamed (for example in order to use a Spring-based
- EntityManagerFactory). In a Java EE 5 environment,
- the @PersistenceContext and @PersistenceUnit annotations are used for
- supporting the container-driven injection of container-managed
- persistence contexts and persistence units, respectively. During
- deployment, JBoss Enterprise Application Platform scans the
- deployment classes. It will validate that, if such annotations are found, the corresponding
- managed persistence units exist as well. This is not the case if the
- <filename>persistence.xml</filename> file has been renamed.</para>
+ <para>In certain cases, however, the presence of
+ @PersistenceContext/@PersistenceUnit annotations in Spring beans may
+ cause deployment errors, when the <filename>persistence.xml</filename>
+ file has been renamed (for example in order to use a Spring-based
+ EntityManagerFactory). In a Java EE 5 environment, the
+ @PersistenceContext and @PersistenceUnit annotations are used for
+ supporting the container-driven injection of container-managed
+ persistence contexts and persistence units, respectively. During
+ deployment, JBoss Enterprise Application Platform scans the deployment
+ classes. It will validate that, if such annotations are found, the
+ corresponding managed persistence units exist as well. This is not the
+ case if the <filename>persistence.xml</filename> file has been
+ renamed.</para>
- <para>This situation can be solved either by disabling the
- scanning of deployment classes, or by using the @Autowire injection.
- </para>
+ <para>This situation can be solved either by disabling the scanning of
+ deployment classes, or by using the @Autowire injection.</para>
- <para>In the case of Spring-based deployments, the injection of
- components and resources is done by Spring and not by JBoss, so in
- most cases it is not necessary for JBoss to perform the scanning at
- all. For web applications conforming to the Servlet 2.5 specification
- this can be set up through the metadata-complete attribute
- (applications that use the Servlet 2.4 standard do not exhibit this
- problem at all, since annotation-based injection is not supported by
- the container).</para>
+ <para>In the case of Spring-based deployments, the injection of
+ components and resources is done by Spring and not by JBoss, so in most
+ cases it is not necessary for JBoss to perform the scanning at all. For
+ web applications conforming to the Servlet 2.5 specification this can be
+ set up through the metadata-complete attribute (applications that use
+ the Servlet 2.4 standard do not exhibit this problem at all, since
+ annotation-based injection is not supported by the container).</para>
- <example>
- <title>The Metadata-complete Flag Can Be Used to Disable Class
- Scanning by JBoss</title>
+ <example>
+ <title>The Metadata-complete Flag Can Be Used to Disable Class
+ Scanning by JBoss</title>
- <programlisting language="XML"><web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
+ <programlisting language="XML"><web-app version="2.5" xmlns="http://java.sun.com/xml/ns/javaee"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://java.sun.com/xml/ns/javaee http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
metadata-complete="true"></programlisting>
- <para>An alternative is to use @Autowired instead of
- @PersistenceUnit/@PersistenceContext. In the case of
- @PersistenceUnit/EntityManagerFactory injection, it is just a matter
- of replacing the annotation, but @PersistenceContext requires an
- extra step. </para>
+ <para>An alternative is to use @Autowired instead of
+ @PersistenceUnit/@PersistenceContext. In the case of
+ @PersistenceUnit/EntityManagerFactory injection, it is just a matter
+ of replacing the annotation, but @PersistenceContext requires an extra
+ step.</para>
- <para>If you are using a container-deployed EntityManagerFactory,
- you can register bind the EntityManager in JNDI, as
- explained in the previous subsection, and use a JNDI lookup bean to
- retrieve it.</para>
+ <para>If you are using a container-deployed EntityManagerFactory, you
+ can register bind the EntityManager in JNDI, as explained in the
+ previous subsection, and use a JNDI lookup bean to retrieve it.</para>
- <para>If you are using a Spring-deployed EntityManagerFactory, you
- can autowire a transaction-aware EntityManager by adding a
- SharedEntityManagerBean definition as in the following
- example.</para>
- </example>
+ <para>If you are using a Spring-deployed EntityManagerFactory, you can
+ autowire a transaction-aware EntityManager by adding a
+ SharedEntityManagerBean definition as in the following example.</para>
+ </example>
- <example>
- <title>Using a SharedEntityManager Bean to Create an Injectable
- Transaction-aware EntityManager</title>
+ <example>
+ <title>Using a SharedEntityManager Bean to Create an Injectable
+ Transaction-aware EntityManager</title>
- <programlisting language="XML"><bean id="entityManagerWrapper" class="org.springframework.orm.jpa.support.SharedEntityManagerBean">
+ <programlisting language="XML"><bean id="entityManagerWrapper" class="org.springframework.orm.jpa.support.SharedEntityManagerBean">
<property name="entityManagerFactory" ref="entityManagerFactory"/>
</bean></programlisting>
- </example>
- </section>
-
+ </example>
+ </section>
- <section id="messaging_integration">
- <title>Messaging (JMS) Integration</title>
+ <section id="messaging_integration">
+ <title>Messaging (JMS) Integration</title>
- <para>Spring applications have two distinct mechanisms of integrating with
- JMS. One is by using the JmsTemplate which simplifies the usage of the JMS
- API for both sending and receiving messages, and the other is by
- implementing message-driven POJOs.</para>
+ <para>Spring applications have two distinct mechanisms of integrating
+ with JMS. One is by using the JmsTemplate which simplifies the usage of
+ the JMS API for both sending and receiving messages, and the other is by
+ implementing message-driven POJOs.</para>
- <para>The best practice in JBoss is to use the JmsTemplate for sending
- messages, but not for receiving them. <!--This is because the message-driven/event-driven
+ <para>The best practice in JBoss is to use the JmsTemplate for sending
+ messages, but not for receiving them. <!--This is because the message-driven/event-driven
paradigm is a superior approach both as a programming style and
performance-wise than polling/blocking via
JmsTemplate.receiveMessage(). --></para>
- <para>Spring applications can implement message-driven POJOs by wiring
- MessageListener beans (or POJOs via a MessageListenerAdapter) into a
- MessageListenerContainer.</para>
+ <para>Spring applications can implement message-driven POJOs by wiring
+ MessageListener beans (or POJOs via a MessageListenerAdapter) into a
+ MessageListenerContainer.</para>
- <para>A typical message-driven POJO can be seen in example <xref
- linkend="listing-message-driven-pojo" />.</para>
+ <para>A typical message-driven POJO can be seen in example <xref
+ linkend="listing-message-driven-pojo" />.</para>
- <example id="listing-message-driven-pojo">
- <title>A message-driven POJO is a simple Java class with a
- single-argument method</title>
+ <example id="listing-message-driven-pojo">
+ <title>A message-driven POJO is a simple Java class with a
+ single-argument method</title>
- <programlisting language="Java">
+ <programlisting language="Java">
public class MessageDrivenPojo
{
@Autowire PaymentProcessor paymentProcessor;
@@ -505,20 +538,21 @@
}
}
</programlisting>
- </example>
+ </example>
- <para>Spring provides two dfferent types of MessageListenerContainers;
- 'native' JMS, and JCA-based. The Enterprise Application Platform uses
- the JCA MessageListenerContainer due to better integration with the
- application server for server message and delivery session, connection,
- and message consumer management. In order to minimize the
- amount of proprietary code, Snowdrop's namespace support for
- JMS/JCA integration can be used <!--(see Snowdrop documentation for details) -->.</para>
+ <para>Spring provides two dfferent types of MessageListenerContainers;
+ 'native' JMS, and JCA-based. The Enterprise Application Platform uses
+ the JCA MessageListenerContainer due to better integration with the
+ application server for server message and delivery session, connection,
+ and message consumer management. In order to minimize the amount of
+ proprietary code, Snowdrop's namespace support for JMS/JCA integration
+ can be used <!--(see Snowdrop documentation for details) -->.</para>
- <example>
- <title>Using the JCA Message Listener Containers and Namespace Support
- in JBoss</title>
-<programlisting language="XML"> <jms:jca-listener-container resource-adapter="resourceAdapter" acknowledge="auto"
+ <example>
+ <title>Using the JCA Message Listener Containers and Namespace Support
+ in JBoss</title>
+
+ <programlisting language="XML"> <jms:jca-listener-container resource-adapter="resourceAdapter" acknowledge="auto"
activation-spec-factory="activationSpecFactory">
<jms:listener destination="/someDestination" ref="messageDrivenPojo"
method="pojoHandlerMethod"/>
@@ -530,115 +564,114 @@
<jboss:resource-adapter id="resourceAdapter"/>
<bean id="messageDrivenPojo" class="example.MessageDrivenPojo"/></programlisting>
- </example>
+ </example>
- <para>When a message arrives, the container will invoke the messageDrivenPojo bean.
- The message will then be converted to the argument type of the pojoHandlerMethod
- inside that bean. Any regular bean can be a message-driven POJO; the only restriction is 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>
- </section>
+ <para>When a message arrives, the container will invoke the
+ messageDrivenPojo bean. The message will then be converted to the
+ argument type of the pojoHandlerMethod inside that bean. Any regular
+ bean can be a message-driven POJO; the only restriction is 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>
+ </section>
- <section>
- <title>Transaction Management</title>
+ <section>
+ <title>Transaction Management</title>
- <para>Spring provides a declarative transaction model including
- transaction propagation semantics, so that applications can declare
- transaction boundaries around specific methods either through annotation
- or via XML. An example using annotations can be found in <xref
- linkend="transactional-method-read-only" /> and more extensively in the
- Sportsclub example application. It is
- important to note that the model is the same regardless of whether the
- transactions being used are local transactions or JTA transactions.
- Spring will wrap components in a transactional proxy which will delegate
- to a transaction manager; which is declared separately as a Spring bean.
- Through its PlatformTransactionManager abstraction, Spring lets developers
- to choose between using resource-local transactions or delegating to the
- transaction manager provided by the application server.</para>
+ <para>Spring provides a declarative transaction model including
+ transaction propagation semantics, so that applications can declare
+ transaction boundaries around specific methods either through annotation
+ or via XML. An example using annotations can be found in <xref
+ linkend="transactional-method-read-only" /> and more extensively in the
+ Sportsclub example application. It is important to note that the model
+ is the same regardless of whether the transactions being used are local
+ transactions or JTA transactions. Spring will wrap components in a
+ transactional proxy which will delegate to a transaction manager; which
+ is declared separately as a Spring bean. Through its
+ PlatformTransactionManager abstraction, Spring lets developers to choose
+ between using resource-local transactions or delegating to the
+ transaction manager provided by the application server.</para>
- <para>Transaction support in JBoss Enterprise Application Platform is
- provided by JBoss Transaction Service, a highly configurable transaction
- manager. To use the JBoss Transaction Service in
- a Spring application, use the standard Spring JTA
- transaction manager definition.</para>
+ <para>Transaction support in JBoss Enterprise Application Platform is
+ provided by JBoss Transaction Service, a highly configurable transaction
+ manager. To use the JBoss Transaction Service in a Spring application,
+ use the standard Spring JTA transaction manager definition.</para>
- <example>
- <title>JTA Transaction Manager Definition in Spring</title>
+ <example>
+ <title>JTA Transaction Manager Definition in Spring</title>
- <programlisting language="XML"><tx:jta-transaction-manager id="transactionManager"/></programlisting>
- </example>
+ <programlisting language="XML"><tx:jta-transaction-manager id="transactionManager"/></programlisting>
+ </example>
- <para>The use of this transaction manager allows Spring to create JTA
- transactions (for example, through Spring declarative transaction
- management), or to enroll in existing transactions, if any. It requires the
- use of managed datasources, JTA-integrated session factories or
- container-deployed persistence units, and ensures that the underlying
- database connections, sessions, and persistence contexts are managed
- transparently and shared with other components. <!-- One of the strongest
+ <para>The use of this transaction manager allows Spring to create JTA
+ transactions (for example, through Spring declarative transaction
+ management), or to enroll in existing transactions, if any. It requires
+ the use of managed datasources, JTA-integrated session factories or
+ container-deployed persistence units, and ensures that the underlying
+ database connections, sessions, and persistence contexts are managed
+ transparently and shared with other components. <!-- One of the strongest
arguments in favour of using JTA across the application is that it ensures
that all resources involved in a complex operation are enrolled in the
same transaction. --></para>
- <simplesect>
- <title>JTA and Messaging Integration</title>
+ <simplesect>
+ <title>JTA and Messaging Integration</title>
- <para>As described in <xref linkend="messaging_integration" />, the
- recommended integration method for receiving JMS messages is through a
- JCA-endpoint based MessageListenerContainer. The processing of a message
- (that is, during the call to the message handling method) is wrapped in a
- JTA transaction. As a result, any other JTA-aware resources
- (datasources, entity manager factories, session factories, JMS sessions)
- will participate in the same transaction.</para>
+ <para>As described in <xref linkend="messaging_integration" />, the
+ recommended integration method for receiving JMS messages is through a
+ JCA-endpoint based MessageListenerContainer. The processing of a
+ message (that is, during the call to the message handling method) is
+ wrapped in a JTA transaction. As a result, any other JTA-aware
+ resources (datasources, entity manager factories, session factories,
+ JMS sessions) will participate in the same transaction.</para>
- <para>Spring's JMS utility classes such as JmsTemplate and even the
- DefaultMessageListenerContainer support injection with a Spring
- transaction manager abstraction. By injecting them with the JTA-based
- implementation defined as previously described, you can ensure that the
- JMS-based operations are enrolled in JTA transactions as well.</para>
- </simplesect>
- </section>
+ <para>Spring's JMS utility classes such as JmsTemplate and even the
+ DefaultMessageListenerContainer support injection with a Spring
+ transaction manager abstraction. By injecting them with the JTA-based
+ implementation defined as previously described, you can ensure that
+ the JMS-based operations are enrolled in JTA transactions as
+ well.</para>
+ </simplesect>
+ </section>
- <section>
- <title>EJB Integration</title>
+ <section>
+ <title>EJB Integration</title>
- <para>Although there is overlap between EJB and Spring,
- mixing the two component models together is common. It consists of
- having components of one type delegating
- functionality to components of the other type. The best practice is to
- provide the delegate components via injection, which can happen in any
- direction (Spring to EJB and EJB to Spring).</para>
+ <para>Although there is overlap between EJB and Spring, mixing the two
+ component models together is common. It consists of having components of
+ one type delegating functionality to components of the other type. The
+ best practice is to provide the delegate components via injection, which
+ can happen in any direction (Spring to EJB and EJB to Spring).</para>
- <section>
- <title>Injecting Spring Beans Into EJBs</title>
+ <section>
+ <title>Injecting Spring Beans Into EJBs</title>
- <para>For JBoss Enterprise Application Platform 5 there are two
- major options of injecting Spring
- beans into EJBs:</para>
+ <para>For JBoss Enterprise Application Platform 5 there are two major
+ options of injecting Spring beans into EJBs:</para>
- <itemizedlist>
- <listitem>
- <para>Using Spring's native support for EJB integration</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>Using Spring's native support for EJB integration</para>
+ </listitem>
- <listitem>
- <para>Using Snowdrop</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para>Using Snowdrop</para>
+ </listitem>
+ </itemizedlist>
- <simplesect>
- <title>Using Spring's Native Support for EJB Integration</title>
+ <simplesect>
+ <title>Using Spring's Native Support for EJB Integration</title>
- <para>Spring supports injection into EJBs through its
- SpringBeanAutowiringInterceptor, which honours the @Autowired
- annotation.</para>
+ <para>Spring supports injection into EJBs through its
+ SpringBeanAutowiringInterceptor, which honours the @Autowired
+ annotation.</para>
- <example>
- <title>Injecting a Spring Bean into EJBs Using Spring's Native
- Support</title>
+ <example>
+ <title>Injecting a Spring Bean into EJBs Using Spring's Native
+ Support</title>
- <programlisting language="Java">@Stateless
+ <programlisting language="Java">@Stateless
@Interceptors(SpringBeanAutowiringInterceptor.class)
public class InjectedEjbImpl implements InjectedEjb {
@@ -646,80 +679,82 @@
private SpringBean springBean;
}</programlisting>
- </example>
+ </example>
- <para>The injected Spring beans are retrieved from an
- ApplicationContext located using a ContextSingletonBeanFactoryLocator,
- which uses a two-step method for locating contexts. It relies on the
- existence of one or more files named <filename>beanRefContext.xml</filename> on the
- classpath (in other words, it performs a
- 'classpath*:beanRefContext.xml' lookup), which contains a single
- application context definition. Example <xref
- linkend="singletonBFL" /> contains the definition of such a
- file.</para>
+ <para>The injected Spring beans are retrieved from an
+ ApplicationContext located using a
+ ContextSingletonBeanFactoryLocator, which uses a two-step method for
+ locating contexts. It relies on the existence of one or more files
+ named <filename>beanRefContext.xml</filename> on the classpath (in
+ other words, it performs a 'classpath*:beanRefContext.xml' lookup),
+ which contains a single application context definition. Example
+ <xref linkend="singletonBFL" /> contains the definition of such a
+ file.</para>
- <example id="singletonBFL">
- <title>Simple beanRefContext.xml File Used by a
- ContextSingletonBeanFactoryLocator and the Corresponding
- simpleContext.xml</title>
+ <example id="singletonBFL">
+ <title>Simple beanRefContext.xml File Used by a
+ ContextSingletonBeanFactoryLocator and the Corresponding
+ simpleContext.xml</title>
- <programlisting language="XML"><beans>
+ <programlisting language="XML"><beans>
<bean class="org.springframework.context.support.ClassPathXmlApplicationContext">
<constructor-arg value="classpath*:simpleContext.xml" />
</bean>
</beans</programlisting>
- <programlisting language="XML"><beans>
+ <programlisting language="XML"><beans>
<bean id="springBean" class="example.SpringBean"/>
</beans></programlisting>
- <!-- <para>For more details, including how to customize the behaviour of
+ <!-- <para>For more details, including how to customize the behaviour of
SpringBeanAutowiringInterceptor, please consult the Spring Framework
reference documentation.</para> -->
- </example>
- </simplesect>
+ </example>
+ </simplesect>
- <simplesect>
- <title>Using Snowdrop</title>
+ <simplesect>
+ <title>Using Snowdrop</title>
- <para>Snowdrop is a package of JBoss-specific extensions to Spring,
- which is included with JBoss Web Framework Kit. This section provides an
- overview on how to inject Spring beans into EJBs using Snowdrop
- support. For more details and a more elaborate example, please consult
- the <citetitle>Snowdrop User Guide</citetitle> and the
- <citetitle>Sportsclub Example</citetitle>.</para>
+ <para>Snowdrop is a package of JBoss-specific extensions to Spring,
+ which is included with JBoss Web Framework Kit. This section
+ provides an overview on how to inject Spring beans into EJBs using
+ Snowdrop support. For more details and a more elaborate example,
+ please consult the <citetitle>Snowdrop User Guide</citetitle> and
+ the <citetitle>Sportsclub Example</citetitle>.</para>
- <para>Snowdrop supports the bootstrapping of Spring application
- contexts through its JBoss-specific Spring deployer. This
- identifies Spring bean configuration files (regular application context
- XML definitions) which are deployed in the META-INF directory of a
- deployable module (EAR, WAR, or EJB-JAR) and match a specific pattern
- (by default, *-spring.xml). It will bootstrap ApplicationContexts, which
- are further registered in JNDI under a name which can be configured
- from within the context definition.</para>
+ <para>Snowdrop supports the bootstrapping of Spring application
+ contexts through its JBoss-specific Spring deployer. This identifies
+ Spring bean configuration files (regular application context XML
+ definitions) which are deployed in the META-INF directory of a
+ deployable module (EAR, WAR, or EJB-JAR) and match a specific
+ pattern (by default, *-spring.xml). It will bootstrap
+ ApplicationContexts, which are further registered in JNDI under a
+ name which can be configured from within the context
+ definition.</para>
- <example id="spring-deployer-xml">
- <title>Spring Beans Configuration File (example-spring.xml)</title>
+ <example id="spring-deployer-xml">
+ <title>Spring Beans Configuration File
+ (example-spring.xml)</title>
- <programlisting language="XML"><beans>
+ <programlisting language="XML"><beans>
<description>BeanFactory=(MyApp)</description>
<bean id="springBean" class="example.SpringBean"/>
</beans></programlisting>
- </example>
+ </example>
- <para>Example <xref linkend="spring-deployer-xml" /> contains a
- minimal Spring bean definition file. The Spring deployer will
- bootstrap a context that contains a 'springBean' bean and will
- register it in JNDI under the 'MyApp' name.</para>
+ <para>Example <xref linkend="spring-deployer-xml" /> contains a
+ minimal Spring bean definition file. The Spring deployer will
+ bootstrap a context that contains a 'springBean' bean and will
+ register it in JNDI under the 'MyApp' name.</para>
- <para>Beans defined in such contexts can be injected into EJBs, by
- using the Snowdrop-specific SpringLifecycleInterceptor and @Spring
- annotation.</para>
+ <para>Beans defined in such contexts can be injected into EJBs, by
+ using the Snowdrop-specific SpringLifecycleInterceptor and @Spring
+ annotation.</para>
- <example>
- <title>Injecting a Spring Bean into an EJB Using Snowdrop</title>
+ <example>
+ <title>Injecting a Spring Bean into an EJB Using Snowdrop</title>
- <programlisting language="Java">@Stateless
+ <programlisting language="Java">@Stateless
@Interceptors(SpringLifecycleInterceptor.class)
public class InjectedEjbImpl implements InjectedEjb
{
@@ -728,34 +763,34 @@
/* rest of the class definition ommitted */
}</programlisting>
- </example>
- </simplesect>
- </section>
+ </example>
+ </simplesect>
+ </section>
- <section>
- <title>Accessing EJBs from Spring Beans</title>
+ <section>
+ <title>Accessing EJBs from Spring Beans</title>
- <para>Injecting stateless EJBs in Spring components is also possible.
- There are two ways this can be done:</para>
+ <para>Injecting stateless EJBs in Spring components is also possible.
+ There are two ways this can be done:</para>
- <itemizedlist>
- <listitem>
- <para>EJB reference bean definitions</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>EJB reference bean definitions</para>
+ </listitem>
- <listitem>
- <para>using the @EJB annotation in SpringA</para>
- </listitem>
- </itemizedlist>
+ <listitem>
+ <para>using the @EJB annotation in SpringA</para>
+ </listitem>
+ </itemizedlist>
- <para>EJB references can be defined as Spring beans using the
- <code><jee:local-slsb>/<jee:remote-slsb></code> elements, as
- in example <xref linkend="ejb-reference" /></para>
+ <para>EJB references can be defined as Spring beans using the
+ <code><jee:local-slsb>/<jee:remote-slsb></code> elements,
+ as in example <xref linkend="ejb-reference" /></para>
- <example id="ejb-reference">
- <title>Defining an EJB Reference as a Spring Bean</title>
+ <example id="ejb-reference">
+ <title>Defining an EJB Reference as a Spring Bean</title>
- <programlisting language="XML"><beans xmlns="http://www.springframework.org/schema/beans"
+ <programlisting language="XML"><beans xmlns="http://www.springframework.org/schema/beans"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:jee="http://www.springframework.org/schema/jee"
xsi:schemaLocation="http://www.springframework.org/schema/beans http://www.springframework.org/schema/beans/spring-beans.xsd
@@ -768,39 +803,39 @@
</beans></programlisting>
- <para>The EJB references are regular Spring beans and can be injected
- as any other Spring beans would.</para>
- </example>
+ <para>The EJB references are regular Spring beans and can be
+ injected as any other Spring beans would.</para>
+ </example>
- <example>
- <title>Injecting an EJB Reference Defined as a Spring Bean</title>
+ <example>
+ <title>Injecting an EJB Reference Defined as a Spring Bean</title>
- <programlisting language="Java">public class ConsumerBean {
+ <programlisting language="Java">public class ConsumerBean {
@Autowire ExampleEjb exampleEJB;
}</programlisting>
- <para>Spring also supports injection directly with EJB references, as
- in the following example:</para>
- </example>
+ <para>Spring also supports injection directly with EJB references,
+ as in the following example:</para>
+ </example>
- <example>
- <title>Injecting an EJB Using Annotations</title>
+ <example>
+ <title>Injecting an EJB Using Annotations</title>
- <programlisting language="Java">public class ConsumerBean {
+ <programlisting language="Java">public class ConsumerBean {
@EJB(mappedName="ejb/exampleEJB")
ExampleEjb exampleEJB;
}</programlisting>
- <para>Unlike @EJB references in EJBs, which may not specify a name or
- mappedName relying upon the container to resolve the reference
- automatically, @EJB references in Spring beans must specify the JNDI
- location where the EJB is expected to be found.</para>
- </example>
+ <para>Unlike @EJB references in EJBs, which may not specify a name
+ or mappedName relying upon the container to resolve the reference
+ automatically, @EJB references in Spring beans must specify the JNDI
+ location where the EJB is expected to be found.</para>
+ </example>
+ </section>
</section>
</section>
- </section>
</chapter>
More information about the jboss-cvs-commits
mailing list