[jboss-cvs] JBossAS SVN: r111040 - projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Sun Mar 27 17:06:36 EDT 2011
Author: marius.bogoevici
Date: 2011-03-27 17:06:36 -0400 (Sun, 27 Mar 2011)
New Revision: 111040
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:
More changes
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-25 20:56:40 UTC (rev 111039)
+++ projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Migration_Guide.xml 2011-03-27 21:06:36 UTC (rev 111040)
@@ -66,7 +66,7 @@
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>
+ 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>
@@ -577,7 +577,7 @@
lookup, as well as changing transaction management to JTA.</para>
<example>
- <title>Migrated JPA EntityManagerFactory definition and </title>
+ <title>Migrated JPA EntityManagerFactory definition and</title>
<para><programlisting> <jee:jndi-lookup id="entityManagerFactory" jndi-name="java:/petclinic/emf" expected-type="javax.persistence.EntityManagerFactory"/>
@@ -594,7 +594,7 @@
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>
+ 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
@@ -641,7 +641,7 @@
Petclinic.</para>
<simplesect>
- <title>The special case of flow-scoped persistence </title>
+ <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
@@ -656,11 +656,13 @@
<footnote>
<para>For details on flow-scoped persistence contexts and their
usage, please consult the Spring Web Flow documentation</para>
- </footnote> </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>
+ file to jpa-persistence.xml and disabling class scanning by setting the
+ metadata-complete flag in web.xml (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-03-25 20:56:40 UTC (rev 111039)
+++ projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml 2011-03-27 21:06:36 UTC (rev 111040)
@@ -147,16 +147,19 @@
<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 be able to bind
- the entity manager or entity manager factory under a well-established
- name and subsequently look them up, applications can use special
- Hibernate configuration properties.</para>
+ <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 be able to
+ bind the entity manager or entity manager factory under a
+ well-established name and subsequently look them up, applications can
+ use special Hibernate configuration properties.</para>
- <programlisting language="xml"><persistence xmlns="http://java.sun.com/xml/ns/persistence" version="1.0">
+ <example>
+ <title>Persistence unit definition</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>
@@ -166,29 +169,29 @@
</properties>
</persistence-unit>
</persistence></programlisting>
- </example>
+ </example>
- <para>Spring applications can use either container-managed entity
- managers or, if necessary, application-managed entity managers (case in
- which 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 (case
+ in which 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"/></programlisting>
+ </example>
- <para>Such an EntityManager can be used directly if injected in
- component classes such as DAOs. When doing so, the</para>
+ <para>Such an EntityManager can be used directly if injected in
+ component classes such as DAOs. When doing so, the</para>
- <example>
- <title>Hibernate-based DAO: a SessionFactory is injected directly in
- the bean</title>
+ <example>
+ <title>Hibernate-based DAO: a SessionFactory is injected directly in
+ the bean</title>
- <para><programlisting language="xml">public class HibernateAccountDao {
+ <para><programlisting language="xml">public class HibernateAccountDao {
@Autowired EntityManager entityManager;
public List<Account> getAllAccounts() {
@@ -196,75 +199,79 @@
}
...
}</programlisting></para>
- </example>
+ </example>
- <para>As an alternative, an EntityManagerFactory can also be used
- directly, either relying on Spring's ability of performing
- @PersistenceContext injection with a transactional EntityManager or when
- the scenario requires an application-managed entityManager. Here is an
- example of acquiring the entityManagerFactory from JNDI.</para>
+ <para>As an alternative, an EntityManagerFactory can also be used
+ directly, either relying on Spring's ability of performing
+ @PersistenceContext injection with a transactional EntityManager or
+ when the scenario requires an application-managed entityManager. Here
+ is an example of acquiring the entityManagerFactory from JNDI.</para>
- <example>
- <title>Spring bean representing an entity manager factory</title>
+ <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 (for
- example a service that delegates to multiple DAOs which have to be
- enrolled in the same transaction), it is not typical to access
- EntityManagerFactories directly, even if Spring supports injection into
- fields annotated with @PersistenceContext if an EntityManagerFactory
- 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 (e.g. EJBs).</para>
+ <para>In general, for implementing transaction-aware components (for
+ example a service that delegates to multiple DAOs which have to be
+ enrolled in the same transaction), it is not typical to access
+ EntityManagerFactories directly, even if Spring supports injection
+ into fields annotated with @PersistenceContext if an
+ EntityManagerFactory 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 (e.g. EJBs).</para>
- <para>A comprehensive example of using JPA-driven data access in
- Spring-based applications can be found in the Sportsclub demo
- application, included in the Web Framework Kit distribution.</para>
+ <para>A comprehensive example of using JPA-driven data access in
+ Spring-based applications can be found in the Sportsclub demo
+ application, included in the Web Framework Kit distribution.</para>
+ </section>
- <para>One important limitation of working with JNDI-bound EntityManagers
- and EntityManagerFactories is the lack of support for read-only
- transactions in Spring. When declaring transactions, Spring applications
- may specify that the transaction is intended to be read-only as in
- example</para>
+ <section>
+ <title>PersistenceUnit created by Spring</title>
- <example id="transactional-method-read-only">
- <title>A Spring method declaring a read-only transaction</title>
+ <para>One important limitation of working with JNDI-bound
+ EntityManagers and EntityManagerFactories is the lack of support for
+ read-only transactions in Spring. When declaring transactions, Spring
+ applications may specify that the transaction is intended to be
+ read-only as in example</para>
- <programlisting language="java">@Transaction(readOnly = true)
+ <example id="transactional-method-read-only">
+ <title>A Spring method declaring a read-only transaction</title>
+
+ <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 readOnly flag will prevent the
- transaction from committing. What it actually means is that the
- application is not expected to change the entities retrieved in the
- persistence context, therefore it can be flushed at the end of the
- transaction. As such, the readOnly flag is a hint to Spring, which will
- attempt to prevent the persistence context (and in the case of using
- Hibernate as a persistence provider, underlying SessionFactory) from
- being automatically flushed upon commit. The expected benefit of this
- operation mode is a performance increase, as the persistence context
- will be simply discarded when the transaction ends. It should be noted
- that support for this mode is not obligatory in Spring, and applications
- are not expected to rely on this behaviour at all time (cf. Spring
- reference documentation for details).</para>
+ <para>A common misconception is that the readOnly flag will prevent
+ the transaction from committing. What it actually means is that the
+ application is not expected to change the entities retrieved in the
+ persistence context, therefore it can be flushed at the end of the
+ transaction. As such, the readOnly flag is a hint to Spring, which
+ will attempt to prevent the persistence context (and in the case of
+ using Hibernate as a persistence provider, underlying SessionFactory)
+ from being automatically flushed upon commit. The expected benefit of
+ this operation mode is a performance increase, as the persistence
+ context will be simply discarded when the transaction ends. It should
+ be noted that support for this mode is not obligatory in Spring, and
+ applications are not expected to rely on this behaviour at all time
+ (cf. Spring reference documentation for details).</para>
- <para>This behaviour is supported by Spring-defined
- EntityManagerFactories for certain JPA providers (Hibernate which is the
- JPA provider for JBoss being one of them), but not when the
- EntityManager or EntityManagerFactory is provided from JNDI. Therefore,
- in any circumstance when the application needs support for readOnly
- persistence contexts, a JTA-integrated
- LocalContainerEntityManagerFactoryBean should be used instead. An
- example of such a bean definition for JBoss is provided here:</para>
+ <para>This behaviour is supported by Spring-defined
+ EntityManagerFactories for certain JPA providers (Hibernate which is
+ the JPA provider for JBoss being one of them), but not when the
+ EntityManager or EntityManagerFactory is provided from JNDI.
+ Therefore, in any circumstance when the application needs support for
+ readOnly persistence contexts, a JTA-integrated
+ LocalContainerEntityManagerFactoryBean should be used instead. An
+ example of such a bean definition for JBoss is provided here:</para>
- <example>
- <title>A Spring-defined JTA-based entity manager factory</title>
+ <example>
+ <title>A Spring-defined JTA-based entity manager factory</title>
- <para><programlisting><bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
+ <para><programlisting><bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
<property name="jpaVendorAdapter">
<bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter"/>
</property>
@@ -277,58 +284,59 @@
</property>
</bean></programlisting></para>
- <para>The above definition relies upon a META-INF/persistence.xml file
- being provided in the deployment. However, in such a case it may be
- worth considering whether it is necessary to have a container-deployed
- persistence unit as well, since the Spring application will not use
- it. If that is not the case, you can use another location as shown in
- example <xref linkend="alt-location" />.</para>
- </example>
+ <para>The above definition relies upon a META-INF/persistence.xml
+ file being provided in the deployment. However, in such a case it
+ may be worth considering whether it is necessary to have a
+ container-deployed persistence unit as well, since the Spring
+ application will not use it. If that is not the case, you can use
+ another location as shown in example <xref
+ linkend="alt-location" />.</para>
+ </example>
- <example>
- <title>Using an alternative location for persistence.xml</title>
+ <example>
+ <title>Using an alternative location for persistence.xml</title>
- <para><programlisting lang="XML" language="xml"><bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
+ <para><programlisting lang="XML" 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></para>
- </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 persistence.xml or otherwise. In such cases, the list of
- entities must be provided explicitely 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 persistence.xml or otherwise. In such cases, the list of
+ entities must be provided explicitely through one of the following
+ methods:</para>
- <itemizedlist>
- <listitem>
- <para>By enumerating the persistent classes in persistence.xml (or
- however the persistence unit configuration file is named);</para>
- </listitem>
+ <itemizedlist>
+ <listitem>
+ <para>By enumerating the persistent classes in persistence.xml (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 persistence.xml;</para>
- </listitem>
+ <listitem>
+ <para>By packaging the entities in a jar file and provide a
+ <jar-file/> configuration entry in persistence.xml;</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;
@@ -369,6 +377,7 @@
}
}
</programlisting>
+ </example>
<para>A bean of this class can be injected in the
LocalContainerEntityManagerFactoryBean as follows:<example>
@@ -384,7 +393,77 @@
</property>
</bean></programlisting></para>
</example></para>
- </example>
+ </section>
+
+ <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>In certain cases, however, the presence of
+ @PersistenceContext/@PersistenceUnit annotations on Spring beans may
+ cause deployment errors, when the persistence.xml file has been
+ renamed (for example in order to use a Spring-based
+ EntityManagerFactory as shown previously). 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 EAP will scan the deployment classes and will
+ validate that, if such annotations are found, the corresponding
+ managed persistence units exist as well, which is not the case if the
+ persistence.xml file has been renamed.</para>
+
+ <para>This situation can be solved simply, either by disabling the
+ scanning of deployment classes or by using @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 simply 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>
+
+ <programlisting><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>f you are using a container-deployed EntityManagerFactory,
+ then you can simply 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>
+
+ <example>
+ <title>Using a SharedEntityManager bean to create an injectable
+ transaction-aware EntityManager</title>
+
+ <programlisting><bean id="entityManagerWrapper" class="org.springframework.orm.jpa.support.SharedEntityManagerBean">
+ <property name="entityManagerFactory" ref="entityManagerFactory"/>
+</bean></programlisting>
+ </example>
+ </section>
</section>
</section>
@@ -503,12 +582,6 @@
same transaction.</para>
<simplesect>
- <title>JTA and database persistence</title>
-
- <para></para>
- </simplesect>
-
- <simplesect>
<title>JTA and messaging integration</title>
<para>As described in <xref linkend="messaging_integration" />, the
@@ -564,7 +637,7 @@
<title>Injecting a Spring Bean into EJBs using Spring's native
support</title>
- <programlisting>@Stateless
+ <programlisting language="java">@Stateless
@Interceptors(SpringBeanAutowiringInterceptor.class)
public class InjectedEjbImpl implements InjectedEjb {
@@ -580,21 +653,22 @@
existence of one or more files named beanRefContext.xml on the
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>
+ application context definition. Example <xref
+ linkend="singletonBFL" /> contains the definition of such a
+ file.</para>
- <example>
+ <example id="singletonBFL">
<title>Simple beanRefContext.xml file used by a
ContextSingletonBeanFactoryLocator and the corresponding
simpleContext.xml</title>
- <programlisting><beans>
+ <programlisting language="xml"><beans>
<bean class="org.springframework.context.support.ClassPathXmlApplicationContext">
<constructor-arg value="classpath*:simpleContext.xml" />
</bean>
</beans</programlisting>
- <programlisting><beans>
+ <programlisting language="xml"><beans>
<bean id="springBean" class="example.SpringBean"/>
</beans></programlisting>
@@ -625,7 +699,7 @@
<example id="spring-deployer-xml">
<title>Spring beans configuration file (example-spring.xml)</title>
- <programlisting><beans>
+ <programlisting language="xml"><beans>
<description>BeanFactory=(MyApp)</description>
<bean id="springBean" class="example.SpringBean"/>
</beans></programlisting>
@@ -643,7 +717,7 @@
<example>
<title>Injecting a Spring bean into an EJB using Snowdrop</title>
- <para><programlisting>@Stateless
+ <para><programlisting language="java">@Stateless
@Interceptors(SpringLifecycleInterceptor.class)
public class InjectedEjbImpl implements InjectedEjb
{
@@ -673,13 +747,13 @@
</itemizedlist>
<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>
+ <code><jee:local-slsb>/<jee:remote-slsb></code> elements, as
+ in example <xref linkend="ejb-reference" /></para>
- <example>
+ <example id="ejb-reference">
<title>Definiting an EJB reference as a Spring bean</title>
- <programlisting><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
More information about the jboss-cvs-commits
mailing list