[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Gavin King
gavin.king at jboss.com
Thu Feb 22 16:59:58 EST 2007
User: gavin
Date: 07/02/22 16:59:58
Modified: doc/reference/en/modules spring.xml
Log:
minor
Revision Changes Path
1.6 +47 -53 jboss-seam/doc/reference/en/modules/spring.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: spring.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/spring.xml,v
retrieving revision 1.5
retrieving revision 1.6
diff -u -b -r1.5 -r1.6
--- spring.xml 22 Feb 2007 21:15:24 -0000 1.5
+++ spring.xml 22 Feb 2007 21:59:58 -0000 1.6
@@ -26,13 +26,10 @@
<section>
<title>Injecting Seam components into Spring beans</title>
- <para> Seam provides extensive support for injection of Seam component instances into Spring beans using the
- <literal>SeamFactoryBean</literal>. The functionality of the SeamFactoryBean is encapsulated by the
- <literal><seam:instance/></literal> namespace handler. This section will cover use of the
- namespace handler. </para>
-
- <para> To enable the Seam namespace handler in Spring the following must be added to the spring beans definition
- file. </para>
+ <para> Injecting Seam component instances into Spring beans is accomplished using the
+ <literal><seam:instance/></literal> namespace handler. To enable the Seam
+ namespace handler, the namespace must be added to the Spring beans
+ definition file:</para>
<programlisting><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans"
xmlns:seam="http://jboss.com/products/seam/spring"
@@ -42,8 +39,7 @@
http://jboss.com/products/seam/spring
http://jboss.com/products/seam/spring-1.1.xsd">]]></programlisting>
- <para> Once the namespace handler has been defined in the instances of Seam components can then be injected into
- Spring beans like so: </para>
+ <para> Now any Seam component may be injected into any Spring bean: </para>
<programlisting><![CDATA[<bean id="someSpringBean" class="SomeSpringBeanClass" scope="prototype">
<property name="someProperty">
@@ -59,7 +55,8 @@
</property>
</bean>]]></programlisting>
- <para> Seam component instances may even be made available for injection into Spring beans by a Spring bean id. </para>
+ <para> Seam component instances may even be made available for injection into Spring beans by
+ a Spring bean id. </para>
<programlisting><![CDATA[<seam:instance name="someComponent" id="someSeamComponentInstance"/>
@@ -68,21 +65,20 @@
</bean>
]]></programlisting>
- <para> When injecting Seam components into Spring beans care must be taken that scope impedance is maintained.
- Unlike with Seam bijection, instances are not injected into Spring beans on every method invocation. Instead
- instances are only injected when a Spring bean is instantiated so the instance provided when a Spring bean
- is instantiated will be the instance that spring bean uses for the life of the bean. For example, if a Seam
- <literal>CONVERSATION</literal> scoped component instance is injected into a singleton Spring bean, that
- singleton will contain the <literal>CONVERSATION</literal> scoped instance available when the Spring bean is
- instantiated for the life of that singleton instance. If another request invokes a method on the Spring
- singleton it could be working with a prior conversation's Seam instance. </para>
-
- <para>Making Seam-scoped component instances available to Spring singletons requires the use of a proxy.
- <literal>SeamFactoryBean</literal> provides Spring with provides a proxy for Seam components instead of
- providing the actual Seam component. The target of the proxy, the actual instance executed on, will be
- determined by looking up the appropriate contextual object at invocation time. This functionality is
- currently utilized (for example) to provide rough Seam extended persistence context support to Spring
- singletons: </para>
+ <para>Now for the caveat!</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 empedance</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><seam:instance/></literal> tag lets us automatically proxy the Seam component.</para>
<programlisting><![CDATA[<seam:instance id="seamManagedEM" name="someManagedEMComponent" proxy="true"/>
@@ -90,15 +86,16 @@
<property name="entityManager" ref="seamManagedEM">
</bean>]]></programlisting>
- <para> (Tighter integration with Seam managed persistence contexts as a replacement for the Spring
- <literal>OpenEntityManagerInView</literal> filter will be available in a future release) </para>
+ <para> This example shows one way to use a Seam-managed persistence context from a Spring bean. (A more robust
+ way to use Seam-managed persistence contexts as a replacement for the Spring
+ <literal>OpenEntityManagerInView</literal> filter will be provided in a future release.)</para>
</section>
<section>
<title>Injecting Spring beans into Seam components</title>
- <para> It is often useful to be able to inject Spring beans into Seam component instances. This can be done in
- two ways. </para>
+ <para> It is even easier to inject Spring beans into Seam component instances. Actually, there are
+ two possible approaches: </para>
<itemizedlist>
<listitem>
@@ -115,10 +112,8 @@
</para>
<para> The Spring <literal>DelegatingVariableResolver</literal> is an integration point Spring provides for
- integrating Spring with JSF. The <literal>VariableResolver</literal> makes all Spring beans available in
- EL expressions by simply identifying the name of the Spring bean in an expression such as
- <literal>#{someSpringBean}</literal>. To enable this approach the Spring
- <literal>DelegatingVariableResolver</literal> must be added to the
+ integrating Spring with JSF. This <literal>VariableResolver</literal> makes all Spring beans available in
+ EL by their bean id. You'll need to add the <literal>DelegatingVariableResolver</literal> to
<literal>faces-config.xml</literal>: </para>
<programlisting><![CDATA[<application>
@@ -127,14 +122,13 @@
</variable-resolver>
</application>]]></programlisting>
- <para> This will make Spring beans available for injection using the <literal>@In</literal> annotation with
- an expression: </para>
+ <para> Then you can inject Spring beans using <literal>@In</literal>: </para>
<programlisting><![CDATA[@In("#{bookingService}")
private BookingService bookingService;]]></programlisting>
- <para>The use of Spring beans in EL is not limited to injection. Spring components may be invoked in any
- place that EL expressions are used in Seam: process and pageflow definitions, working memory assertions,
+ <para>The use of Spring beans in EL is not limited to injection. Spring beans may be used anywhere
+ that EL expressions are used in Seam: process and pageflow definitions, working memory assertions,
etc... </para>
</section>
@@ -170,34 +164,34 @@
<title>Seam-scoped Spring beans</title>
<para> The Seam integration package also lets you use Seam's contexts as Spring 2.0 style custom scopes.
- This lets you declare any Spring bean in any of Seam's contexts. However, note that Spring's component
- model was never architected to support statefulness, so please use this feature with great care.
+ This lets you declare any Spring bean in any of Seam's contexts. However, note once again that Spring's
+ component model was never architected to support statefulness, so please use this feature with great care.
In particular, clustering of session or conversation scoped Spring beans is deeply problematic, and
- injection of a bean or component from a wider scope into a bean of a narrower scope should be avoided. </para>
+ care must be taken when injecting a bean or component from a wider scope into a bean of a narrower scope.</para>
- <para> By specifying <literal><seam:configure-scopes/></literal> in a Spring bean factory all of
- the Seam scopes will be available to Spring beans as custom scopes. To make a Spring bean managed
- by a Seam scope in this way, specify the Seam scope in the <literal>scope</literal> attribute of the bean
+ <para> By specifying <literal><seam:configure-scopes/></literal> once in a Spring bean factory configuration,
+ all of the Seam scopes will be available to Spring beans as custom scopes. To associate a Spring bean
+ with a particular Seam scope, specify the Seam scope in the <literal>scope</literal> attribute of the bean
definition. </para>
<programlisting><![CDATA[<!-- Only needs to be specified once per bean factory-->
<seam:configure-scopes/>
+
<bean id="someSpringBean" class="SomeSpringBeanClass" scope="seam.CONVERSATION"/>]]></programlisting>
- <para> The prefix for the scope name can be changed by specifying a the <literal>prefix</literal> attribute in
- the <literal>configure-scopes</literal> definition with the desired prefix. The default prefix is
- <literal>seam.</literal>
+ <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> Seam scoped Spring beans defined this way can be injected into other Spring beans without the use of
- <literal><seam:instance/></literal> however, like all Seam component instances care must
- be taken to ensure scope impedance is maintained. Normally in Spring to overcome this scope impedance
- problem the Spring namespace decorator <literal><aop:scoped-proxy/></literal> would be used on
- the bean definition. However, Spring beans created this way are <emphasis>not</emphasis> compatible with
- <literal><aop:scoped-proxy/></literal>. If you need to inject a Seam-scoped Spring bean
- into a singleton <literal><seam:instance/></literal> can be used: </para>
+ <para> Seam-scoped Spring beans defined this way can be injected into other Spring beans without the use of
+ <literal><seam:instance/></literal>. However, care must be taken to ensure scope impedance is
+ maintained. The normal approach used in Spring is to specify <literal><aop:scoped-proxy/></literal>
+ in the bean definition. However, Seam-scoped Spring beans are <emphasis>not</emphasis> compatible with
+ <literal><aop:scoped-proxy/></literal>. So if you need to inject a Seam-scoped Spring bean
+ into a singleton, <literal><seam:instance/></literal> must be used: </para>
<programlisting><![CDATA[<bean id="someSpringBean" class="SomeSpringBeanClass" scope="seam.CONVERSATION"/>
+
<bean id="someSingleton">
<property name="someSeamScopedSpringBean">
<seam:instance name="someSpringBean" proxy="true"/>
More information about the jboss-cvs-commits
mailing list