[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Gavin King
gavin.king at jboss.com
Fri Jul 14 14:12:23 EDT 2006
User: gavin
Date: 06/07/14 14:12:23
Modified: doc/reference/en/modules annotations.xml concepts.xml
controls.xml
Log:
@Factory/@Unwrap/@Create/@Destory
Revision Changes Path
1.39 +25 -1 jboss-seam/doc/reference/en/modules/annotations.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: annotations.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/annotations.xml,v
retrieving revision 1.38
retrieving revision 1.39
diff -u -b -r1.38 -r1.39
--- annotations.xml 13 Jul 2006 02:33:44 -0000 1.38
+++ annotations.xml 14 Jul 2006 18:12:23 -0000 1.39
@@ -317,8 +317,32 @@
<para>
Specifies that the method of the component is used to initialize the
value of the named context variable, when the context variable has
- no value.
+ no value. This style is used with methods that return
+ <literal>void</literal>.
</para>
+ <programlisting><![CDATA[@Factory("processInstance", scope=CONVERSATION)]]></programlisting>
+ <para>
+ Specifies that the method returns a value that Seam should use to
+ initialize the value of the named context variable, when the context
+ variable has no value. This style is used with methods that return
+ a value.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — specifies the name of the
+ context variable. If the method is a getter method, default to
+ the JavaBeans property name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>scope</literal> — specifies the scope that Seam
+ should bind the returned value to. Only meaningful for factory
+ methods which return a value.
+ </para>
+ </listitem>
+ </itemizedlist>
</listitem>
</varlistentry>
</variablelist>
1.30 +120 -0 jboss-seam/doc/reference/en/modules/concepts.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: concepts.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/concepts.xml,v
retrieving revision 1.29
retrieving revision 1.30
diff -u -b -r1.29 -r1.30
--- concepts.xml 14 Jul 2006 03:26:32 -0000 1.29
+++ concepts.xml 14 Jul 2006 18:12:23 -0000 1.30
@@ -712,6 +712,19 @@
</components>]]></programlisting>
<para>
+ You can even create an "alias" for a commonly used expression:
+ </para>
+
+ <programlisting><![CDATA[<components>
+
+ <component name="userName"
+ class="org.jboss.seam.core.Alias">
+ <property name="expression">#{actor.id}</property>
+ </component>
+
+</components>]]></programlisting>
+
+ <para>
Sometimes we want to reuse the same <literal>components.xml</literal> file with
minor changes during both deployment and testing. Seam let's you place wildcards
of the form <literal>@wildcard@</literal> in the <literal>components.xml</literal>
@@ -1300,4 +1313,111 @@
</sect1>
+ <sect1>
+ <title>Lifecycle methods</title>
+ <para>
+ Session bean and entity bean Seam components support all the usual EJB 3.0 lifecycle
+ callback (<literal>@PostConstruct</literal>, <literal>@PreDestroy</literal>, etc).
+ But Seam also defines its own component lifecycle callbacks.
+ </para>
+ <para>
+ The <literal>@Create</literal> method is called every time Seam instantiates a
+ component. Unlike the <literal>@PostConstruct</literal> method, this method is
+ called after the component is fully constructed by the EJB container, and has
+ access to all the usual Seam functionality (bijection, etc). Components may
+ define only one <literal>@Create</literal> method.
+ </para>
+ <para>
+ The <literal>@Destroy</literal> method is called when the context that the Seam
+ component is bound to ends. Components may define only one <literal>@Destroy</literal>
+ method. Stateful session bean components <emphasis>must</emphasis> define a method
+ annotated <literal>@Destroy @Remove</literal>.
+ </para>
+ <para>
+ Finally, a related annotation is the <literal>@Startup</literal> annotation, which
+ may be applied to any application or session scoped component. The
+ <literal>@Startup</literal> annotation tells Seam to instantiate the component
+ immediately, when the context begins, instead of waiting until it is first
+ referenced by a client. It is possible to control the order of instantiation
+ of startup components by specifying <literal>@Startup(depends={....})</literal>.
+ </para>
+ </sect1>
+
+ <sect1>
+ <title>Factory and manager components</title>
+ <para>
+ We often need to work with objects that are not Seam components. But we still want
+ to be able to inject them into our components using <literal>@In</literal> and
+ use them in value and method binding expressions, etc. Sometimes, we even need
+ to tie them into the Seam context lifecycle (<literal>@Destroy</literal>, for
+ example). So the Seam contexts can contain objects which are not Seam components,
+ and Seam provides a couple of nice features that make it easier to work with
+ non-component objects bound to contexts.
+ </para>
+
+ <para>
+ The <emphasis>factory component pattern</emphasis> lets a Seam component act
+ as the instantiator for a non-component object. A <emphasis>factory method</emphasis>
+ will be called when a context variable is referenced but has no value bound to it.
+ We define factory methods using the <literal>@Factory</literal> annotation. The
+ factory method binds a value to the context variable, and determines the scope
+ of the bound value. There are two styles of factory method. The first style
+ returns a value, which is bound to the context by Seam:
+ </para>
+
+ <programlisting><![CDATA[@Factory(scope=CONVERSATION)
+public List<Customer> getCustomerList() {
+ return ... ;
+} ]]></programlisting>
+
+ <para>
+ The second style is a method of type <literal>void</literal> which binds the
+ value to the context variable itself:
+ </para>
+
+ <programlisting><![CDATA[@DataModel List<Customer> customerList;
+
+ at Factory("customerList")
+public void initCustomerList() {
+ customerList = ... ;
+} ]]></programlisting>
+
+ <para>
+ In both cases, the factory method is called when we reference the
+ <literal>customerList</literal> context variable and its value is null,
+ and then has no further part to play in the lifecycle of the value. An
+ even more powerful pattern is the <emphasis>manager component pattern</emphasis>.
+ In this case, we have a Seam component that is bound to a context variable,
+ that manages the value of the context variable, while remaining invisible
+ to clients.
+ </para>
+
+ <para>
+ A manager component is any component with an <literal>@Unwrap</literal>
+ method. This method returns the value that will be visable to clients,
+ and is called <emphasis>every time</emphasis> a context variable is
+ referenced.
+ </para>
+
+ <programlisting><![CDATA[@Name("customerList")
+ at Scope(CONVERSATION)
+public class CustomerListManager
+{
+ ...
+
+ @Unwrap
+ public List<Customer> getCustomerList() {
+ return ... ;
+ }
+}]]></programlisting>
+
+ <para>
+ This pattern is especially useful if we have some heavyweight object that
+ needs a cleanup operation when the context ends. In this case, the
+ manager component may perform cleanup in the <literal>@Destroy</literal>
+ method.
+ </para>
+
+ </sect1>
+
</chapter>
\ No newline at end of file
1.3 +4 -1 jboss-seam/doc/reference/en/modules/controls.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: controls.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/controls.xml,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -b -r1.2 -r1.3
--- controls.xml 14 Jul 2006 17:09:14 -0000 1.2
+++ controls.xml 14 Jul 2006 18:12:23 -0000 1.3
@@ -30,7 +30,10 @@
<term><literal><s:cache></literal></term>
<listitem>
<para>
- Cache the rendered page fragment using JBoss Cache.
+ Cache the rendered page fragment using JBoss Cache. Note that
+ <literal><s:cache></literal> actually uses the instance
+ of JBoss Cache managed by the built-in <literal>pojoCache</literal>
+ component.
</para>
<itemizedlist>
<listitem>
More information about the jboss-cvs-commits
mailing list