[jboss-cvs] JBossAS SVN: r110931 - projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Wed Mar 16 14:01:20 EDT 2011
Author: marius.bogoevici
Date: 2011-03-16 14:01:20 -0400 (Wed, 16 Mar 2011)
New Revision: 110931
Modified:
projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Getting_Started_Introductory_Example.xml
projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml
Log:
Updated
Modified: projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Getting_Started_Introductory_Example.xml
===================================================================
--- projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Getting_Started_Introductory_Example.xml 2011-03-16 15:41:28 UTC (rev 110930)
+++ projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Getting_Started_Introductory_Example.xml 2011-03-16 18:01:20 UTC (rev 110931)
@@ -75,8 +75,8 @@
<title>Creating the Maven project structure</title>
<para>Creating a Maven-based web application from JBDS is fairly easy,
- if the m2eclipse plugin (both core an WTP integration) is installed.
- </para>
+ if the m2eclipse plugin (both core an WTP integration) is
+ installed.</para>
<para>Go to New->Maven Project (may need to select the 'Other' option
first). Leave the 'Create a simple project' option unchecked, as we want
@@ -92,8 +92,8 @@
'org.jboss.spring.getting.started' although no package will be created
at this point, so the option is not in use.</para>
- <para>So, after doing all this, the end result should look similar to
- this:</para>
+ <para>The following dependencies need to be included in your
+ application:</para>
<para>The artifact may not create the Java source folder, so you may
have to add it yourself. Go to 'New'->Source Folder and enter a value
@@ -182,7 +182,7 @@
declaratively, which with this particular setup means that
getForUsername() will execute in its own transaction, if a transaction
isn't started yet (this may change with other configuration options, as
- Spring supports different transaction propagation modes). </para>
+ Spring supports different transaction propagation modes).</para>
<programlisting>@Service
public class UserDaoImpl implements UserDao {
@@ -200,7 +200,7 @@
<para>In the web tier, we will need a controller and a web page for
displaying the results. So we will create the UserController class
- first. </para>
+ first.</para>
<programlisting>@Controller
@RequestMapping("say-hello")
@@ -236,7 +236,7 @@
which will be mapped to it also depends on the rest of the Spring
configuration. Spring MVC uses the Front Controller pattern, which means
that the requests are dispatched by a servlet, and the mappings in this
- class are relative to the mapping of the servlet. </para>
+ class are relative to the mapping of the servlet.</para>
<para>The class serves as backing to a web form, and different methods
need to execute when the form page is initially requested (GET) and data
@@ -330,7 +330,7 @@
<para>The ContextLoaderListener will boostrap an application context
containing the business components, while the DispatcherServlet will
create an application context using the former as its parent (and thus
- having access to its bean definitions). </para>
+ having access to its bean definitions).</para>
<para>From src/main/webapp/WEB-INF, create a Spring bean definition
file, by selecting New->Spring Bean Definition File and enter a file
Modified: projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml
===================================================================
--- projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml 2011-03-16 15:41:28 UTC (rev 110930)
+++ projects/docs/enterprise/WFK/Spring_Developer_Guide/en-US/Spring_On_JBoss_Best_Practices.xml 2011-03-16 18:01:20 UTC (rev 110931)
@@ -141,12 +141,13 @@
</section>
<section>
- <title>Defining a JPA persistence unit</title>
+ <title>Using JPA</title>
- <para>Spring applications that use JPA are advised to managed
- persistence unit and access them from JNDI. In order to bind the entity
- manager or entity manager factory under a well-established name,
- applications can use special Hibernate configuration properties.</para>
+ <para>Spring applications can retrieve the persistence units deployed by
+ the container by looking them up in JNDI. In order to be able to bind
+ the entity manager or entity manager factory under a well-established
+ name and subsequently look them up, applications can use special
+ Hibernate configuration properties.</para>
<example>
<title>Persistence unit definition</title>
@@ -194,8 +195,11 @@
}</programlisting></para>
</example>
- <para>An EntityManagerFactory can also be used directly, when the
- scenario requires an application-managed entityManager.</para>
+ <para>As an alternative, an EntityManagerFactory can also be used
+ directly, either relying on Spring's ability of performing
+ @PersistenceContext injection with a transactional EntityManager or when
+ the scenario requires an application-managed entityManager. Here is an
+ example of acquiring the entityManagerFactory from JNDI.</para>
<example>
<title>Spring bean representing an entity manager factory</title>
@@ -207,15 +211,82 @@
example a service that delegates to multiple DAOs which have to be
enrolled in the same transaction), it is not typical to access
EntityManagerFactories directly. Rather, components should access the
- JNDI-bound EntityManager. However, EntityManagerFactory beans are
- typically used in scenarios that span multiple transactions such as
- conversations. For example, Spring Web Flow requires access to an
- EntityManager in order to provide a conversation-scoped persistence
- context. In such a case, you can use the JNDI-bound
- EntityManagerFactory.</para>
+ JNDI-bound EntityManager, as it is JTA-synchronized and will be shared
+ with non-Spring components that use JPA as well (e.g. EJBs). </para>
- <para>You can find a more detailed usage example in the Sportsclub
- application.</para>
+ <para>One important limitation of working with JNDI-bound EntityManagers
+ and EntityManagerFactories is the lack of support for read-only
+ transactions in Spring. When declaring transactions, Spring applications
+ may specify that the transaction is intended to be read-only:</para>
+
+ <example>
+ <title>A Spring class declaring a read-only transaction</title>
+
+ <programlisting>@Transaction(readOnly = true)
+public List<Account> getAllAccounts() {
+ return return entityManager.createQuery("SELECT a FROM Account").getResultList();;
+ }</programlisting>
+ </example>
+
+ <para>A common misconception is that the readOnly flag will prevent the
+ transaction from committing. What it actually means is that the
+ application is not expected to change the entities retrieved in the
+ persistence context, therefore it can be flushed at the end of the
+ transaction. As such, the readOnly flag is a hint to Spring, which will
+ attempt to prevent the persistence context (and in the case of using
+ Hibernate as a persistence provider, underlying SessionFactory) from
+ being automatically flushed upon commit. The expected benefit of this
+ operation mode is a performance increase, as the persistence context
+ will be simply discarded when the transaction ends. It should be noted
+ that support for this mode is not obligatory in Spring, and applications
+ are not expected to rely on this behaviour at all time (cf. Spring
+ reference documentation for details).</para>
+
+ <para>This behaviour is supported by Spring-defined
+ EntityManagerFactories for certain JPA providers (Hibernate which is the
+ JPA provider for JBoss being one of them), but not when the
+ EntityManager or EntityManagerFactory is provided from JNDI. Therefore,
+ in any circumstance when the application needs support for readOnly
+ persistence contexts, a JTA-integrated
+ LocalContainerEntityManagerFactoryBean should be used instead. An
+ example of such a bean definition for JBoss is provided here:</para>
+
+ <example>
+ <title>A Spring-defined JTA-based entity manager factory</title>
+
+ <para><programlisting> <bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalContainerEntityManagerFactoryBean">
+ <property name="jpaVendorAdapter">
+ <bean class="org.springframework.orm.jpa.vendor.HibernateJpaVendorAdapter"/>
+ </property>
+ <property name="jpaProperties">
+ <props>
+ <prop key="hibernate.transaction.manager_lookup_class">
+ org.hibernate.transaction.JBossTransactionManagerLookup
+ </prop>
+ </props>
+ </property>
+ </bean></programlisting>The above definition relies upon a
+ META-INF/persistence.xml file being provided in the deployment.
+ However, in such a case it may be worth considering whether it is
+ necessary to have a container-deployed persistence unit as well, since
+ the Spring application will not use it. If that is not the case, you
+ can use another location as shown here:e</para>
+
+ <para>When doing so, it is worth considering whether the application
+ still needs JBoss to deploy a persistence unit. If not, the
+ persistence unit definition file can be placed in an alternative
+ location, and the Spring bean definition can be changed as in the
+ following example. </para>
+ </example>
+
+ <example>
+ <title>Using an alternative location for persistence.xml </title>
+
+ <para><programlisting><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>
</section>
</section>
@@ -260,14 +331,13 @@
<para>Whenever a message arrives to the destination, it will be converted
to the argument type of the method <emphasis>pojoHandlerMethod</emphasis>
of the messageDrivenPojo bean which will be invoked by the container. Any
- regular bean can be a message-driven POJO, the only restriction beigng
- that the handling method must have a single argument. Spring will take
- care of converting message content to the expected argument type. For a
- JCA-based container, the invocation will be automatically enrolled in a
- JTA transaction.</para>
+ regular bean can be a message-driven POJO, the only restriction being that
+ the handling method must have a single argument. Spring will take care of
+ converting message content to the expected argument type. For a JCA-based
+ container, the invocation will be automatically enrolled in a JTA
+ transaction.</para>
- <para>A message-driven POJO example is provided in the following
- listing:</para>
+ <para>A message-driven POJO is provided in the following listing:</para>
<para><example>
<title>A message-driven POJO is a regular bean type</title>
@@ -328,7 +398,7 @@
transparently and shared with other components.</para>
<para>Please note that in the case of message-driven beans, the message
- handling invocations are already enrolled in a JTA transaction. </para>
+ handling invocations are already enrolled in a JTA transaction.</para>
</section>
<section>
@@ -357,9 +427,8 @@
</section>
<section>
- <title>This needs content to build</title>
- <para>
- This needs content to build.
- </para>
+ <title>This needs content to build</title>
+
+ <para>This needs content to build.</para>
</section>
</chapter>
More information about the jboss-cvs-commits
mailing list