Author: laubai Date: 2009-11-24 02:59:12 -0500 (Tue, 24 Nov 2009) New Revision: 11671 Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Spring.xml Log: Edited Spring chapter. Modified: tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Spring.xml =================================================================== --- tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Spring.xml 2009-11-24 07:37:05 UTC (rev 11670) +++ tags/JBPAPP_4_3_CP07_FP_CR1a/doc/Seam_Reference_Guide/en-US/Spring.xml 2009-11-24 07:59:12 UTC (rev 11671) @@ -11,9 +11,11 @@ <para>Spring integration in Seam is marked as technology preview, so standard support is not guaranteed.</para> </note> - <para>Note! The Spring integration code is included in the jboss-seam-ioc library. This dependency is required for + <note> + <para>The Spring integration code is included in the jboss-seam-ioc library. This dependency is required for all seam-spring integration techniques covered in this chapter.</para> - + </note> + <para>Seam's support for Spring provides the ability to: </para> <itemizedlist> @@ -83,18 +85,18 @@ </bean> ]]></programlisting> - <para>Now for the caveat!</para> + <para> + However, Spring, unlike Seam, was not designed to support a stateful component model with multiple contexts. Spring injection does not occur at method invocation time, but when the Spring bean is instantiated. + </para> + + <para> + The instance available when the bean is instantiated will be used for the entire life of the bean. Say you inject a Seam conversation-scoped component instance directly into a singleton Spring bean — that singleton will hold a reference to the same instance long after the conversation is over. This is called scope <emphasis>impedance</emphasis>. + </para> + + <para> + Seam bijection maintains scope impedance naturally as an invocation flows through the system. In Spring, we must inject a proxy of the Seam component, and resolve the reference when the proxy is invoked. + </para> - <para> Seam was designed from the ground up to support a stateful component model with multiple contexts. Spring - was not. Unlike Seam bijection, Spring injection does not occur at method invocation time. Instead, - injection happens only when the Spring bean is instantiated. So the instance available when the bean is - instantiated will be the same instance that the bean uses for the entire life of the bean. For example, if a - Seam <literal>CONVERSATION</literal>-scoped component instance is directly injected into a singleton Spring - bean, that singleton will hold a reference to the same instance long after the conversation is over! We call - this problem <emphasis>scope impedance</emphasis>. Seam bijection ensures that scope impedance is maintained - naturally as an invocation flows through the system. In Spring, we need to inject a proxy of the Seam - component, and resolve the reference when the proxy is invoked.</para> - <para>The <literal>&lt;seam:instance/&gt;</literal> tag lets us automatically proxy the Seam component.</para> <programlisting role="XML"><![CDATA[<seam:instance id="seamManagedEM" name="someManagedEMComponent" proxy="true"/> @@ -106,7 +108,7 @@ <para> This example shows one way to use a Seam-managed persistence context from a Spring bean. (For a more robust way to use Seam-managed persistence contexts as a replacement for the Spring <literal>OpenEntityManagerInView</literal> filter see section on - <xref linkend="spring-persistence"/>Using a Seam Managed Persistence Context in Spring)</para> + <xref linkend="spring-persistence"/>.</para> </section> <section> @@ -197,7 +199,7 @@ <para> The prefix of the scope name may be changed by specifying the <literal>prefix</literal> attribute in the <literal>configure-scopes</literal> definition. (The default prefix is <literal>seam.</literal>) </para> - <para> By default an instance of a Spring Component registered in this way is not automatically created when + <para> By default an instance of a Spring component registered in this way is not automatically created when referenced using <literal>@In</literal>. To have an instance auto-created you must either specify <literal>@In(create=true)</literal> at the injection point to identify a specific bean to be auto created or you can use the <literal>default-auto-create</literal> attribute of <literal>configure-scopes</literal> to make all spring beans who use a seam scope auto created.</para> @@ -228,9 +230,9 @@ transaction APIs (JPA, Hibernate, JDO, and JTA) Spring also provides tight integrations with many application server TransactionManagers such as Websphere and Weblogic. Spring transaction management exposes support for many advanced features such as nested - transactions and supports full Java EE transaction propagation rules like REQUIRES_NEW and NOT_SUPPORTED. For more + transactions and supports full Java EE transaction propagation rules like REQUIRES_NEW and NOT_SUPPORTED. <!--For more information see the spring documentation - <ulink url="http://static.springframework.org/spring/docs/2.0.x/reference/t... + <ulink url="http://static.springframework.org/spring/docs/2.0.x/reference/t... <para>To configure Seam to use Spring transactions enable the SpringTransaction component like so:</para> @@ -251,7 +253,7 @@ an persistence context beyond the scope of a single web request (<literal>OpenEntityManagerInViewFilter</literal>). So, it would be nice if Spring developers could have access to a Seam managed persistence context using all of the same tools Spring provides - for integration with JPA(e.g. <literal>PersistenceAnnotationBeanPostProcessor</literal>, + for integration with JPA (for example, <literal>PersistenceAnnotationBeanPostProcessor</literal>, <literal>JpaTemplate</literal>, etc.)</para> <para>Seam provides a way for Spring to access a Seam managed persistence context with @@ -282,8 +284,8 @@ <property name="persistenceContextName" value="entityManager"/> </bean>]]></programlisting> - <para>Where 'persistenceContextName' is the name of the Seam managed persistence context component. By default - this EntityManagerFactory has a unitName equal to the Seam component name or in this case 'entityManager'. + <para>Where <literal>persistenceContextName</literal> is the name of the Seam managed persistence context component. By default + this EntityManagerFactory has a unitName equal to the Seam component name or in this case <literal>entityManager</literal>. If you wish to provide a different unitName you can do so by providing a persistenceUnitName like so: </para> @@ -330,18 +332,15 @@ <title>Using a Seam Managed Hibernate Session in Spring</title> <para>The Seam Spring integration also provides support for complete access to a Seam managed Hibernate session - using spring's tools. This integration is very similar to the <xref linkend="spring-persistence"/>JPA integration.</para> + using spring's tools. This integration is very similar to the <xref linkend="spring-persistence"/>.</para> - <para>Like Spring's JPA integration spring's propagation model allows only one open EntityManager per - EntityManagerFactory per transaction??? to be available to spring tools. So, the Seam Session integration works - by wrapping a proxy SessionFactory around a Seam managed Hibernate session - context.</para> + <para>Spring's propagation model allows only one open <literal>EntityManager</literal> per <literal>EntityManagerFactory</literal> to be available to Spring tools, so Seam integrates by wrapping a proxy <literal>SessionFactory</literal> around a Seam-managed Hibernate session context. </para> <programlisting role="XML"><![CDATA[<bean id="seamSessionFactory" class="org.jboss.seam.ioc.spring.SeamManagedSessionFactoryBean"> <property name="sessionName" value="hibernateSession"/> </bean>]]></programlisting> - <para>Where 'sessionName' is the name of the <literal>persistence:managed-hibernate-session</literal> component. + <para>Where <literal>sessionName</literal> is the name of the <literal>persistence:managed-hibernate-session</literal> component. This SessionFactory can then be used in any Spring provided tools. The integration also provides support for calls to <literal>SessionFactory.getCurrentInstance()</literal> as long as you call getCurrentInstance() on the <literal>SeamManagedSessionFactory</literal>.</para> @@ -389,7 +388,7 @@ <para>Spring provides an abstraction for executing code asynchronously called a <literal>TaskExecutor</literal>. The Spring Seam integration allows for the use of a Spring <literal>TaskExecutor</literal> for executing immediate <literal>@Asynchronous</literal> method calls. To enable this functionality install the - <literal>SpringTaskExecutorDispatchor</literal> and provide a spring bean defined taskExecutor like so:</para> + <literal>SpringTaskExecutorDispatcher</literal> and provide a spring bean defined taskExecutor like so:</para> <programlisting role="XML"><![CDATA[<spring:task-executor-dispatcher task-executor="#{springThreadPoolTaskExecutor}"/>]]></programlisting>