[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Gavin King
gavin.king at jboss.com
Wed Nov 29 05:28:03 EST 2006
User: gavin
Date: 06/11/29 05:28:03
Modified: doc/reference/en/modules concepts.xml configuration.xml
framework.xml jms.xml tutorial.xml
Log:
updates
Revision Changes Path
1.43 +398 -593 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.42
retrieving revision 1.43
diff -u -b -r1.42 -r1.43
--- concepts.xml 27 Nov 2006 03:28:16 -0000 1.42
+++ concepts.xml 29 Nov 2006 10:28:03 -0000 1.43
@@ -1,11 +1,16 @@
<chapter id="concepts">
<title>The contextual component model</title>
- <para> The two core concepts in Seam are the notion of a <emphasis>context</emphasis> and the notion of a
+ <para>
+ The two core concepts in Seam are the notion of a <emphasis>context</emphasis> and the notion of a
<emphasis>component</emphasis>. Components are stateful objects, usually EJBs, and an instance of a
component is associated with a context, and given a name in that context. <emphasis>Bijection</emphasis>
provides a mechanism for aliasing internal component names (instance variables) to contextual names, allowing
- component trees to be dynamically assembled, and reassembled by Seam. </para>
- <para> Let's start by describing the contexts built in to Seam. </para>
+ component trees to be dynamically assembled, and reassembled by Seam.
+ </para>
+
+ <para>
+ Let's start by describing the contexts built in to Seam.
+ </para>
<sect1>
<title>Seam contexts</title>
@@ -38,127 +43,175 @@
</listitem>
</itemizedlist>
- <para> You will recognize some of these contexts from servlet and related specifications. However, two of them
+ <para>
+ You will recognize some of these contexts from servlet and related specifications. However, two of them
might be new to you: <emphasis>conversation context</emphasis>, and <emphasis>business process
context</emphasis>. One reason state management in web applications is so fragile and error-prone is that
the three built-in contexts (request, session and application) are not especially meaningful from the point
of view of the business logic. A user login session, for example, is a fairly arbitrary construct in terms
of the actual application work flow. Therefore, most Seam components are scoped to the conversation or
business process contexts, since they are the contexts which are most meaningful in terms of the
- application. </para>
+ application.
+ </para>
- <para> Let's look at each context in turn. </para>
+ <para>
+ Let's look at each context in turn.
+ </para>
<sect2>
<title>Stateless context</title>
- <para> Components which are truly stateless (stateless session beans, primarily) always live in the
+ <para>
+ Components which are truly stateless (stateless session beans, primarily) always live in the
stateless context (this is really a non-context). Stateless components are not very interesting, and are
- arguably not very object-oriented. Nevertheless, they are important and often useful. </para>
+ arguably not very object-oriented. Nevertheless, they are important and often useful.
+ </para>
</sect2>
<sect2>
<title>Event context</title>
- <para> The event context is the "narrowest" stateful context, and is a generalization of the notion of the
+ <para>
+ The event context is the "narrowest" stateful context, and is a generalization of the notion of the
web request context to cover other kinds of events. Nevertheless, the event context associated with the
lifecycle of a JSF request is the most important example of an event context, and the one you will work
with most often. Components associated with the event context are destroyed at the end of the request,
- but their state is available and well-defined for at least the lifecycle of the request. </para>
- <para> When you invoke a Seam component via RMI, or Seam Remoting, the event context is created and
- distroyed just for the invocation. </para>
+ but their state is available and well-defined for at least the lifecycle of the request.
+ </para>
+ <para>
+ When you invoke a Seam component via RMI, or Seam Remoting, the event context is created and
+ destroyed just for the invocation.
+ </para>
</sect2>
<sect2>
<title>Page context</title>
- <para> The page context allows you to associate state with a particular instance of a rendered page. You can
+ <para>
+ The page context allows you to associate state with a particular instance of a rendered page. You can
initialize state in your event listener, or while actually rendering the page, and then have access to
it from any event that originates from that page. This is especially useful for functionality like
clickable lists, where the list is backed by changing data on the server side. The state is actually
serialized to the client, so this construct is extremely robust with respect to multi-window operation
- and the back button. </para>
+ and the back button.
+ </para>
</sect2>
<sect2>
<title>Conversation context</title>
- <para> The conversation context is a truly central concept in Seam. A <emphasis>conversation</emphasis> is a
+ <para>
+ The conversation context is a truly central concept in Seam. A <emphasis>conversation</emphasis> is a
unit of work from the point of view of the user. It might span several interactions with the user,
several requests, and several database transactions. But to the user, a conversation solves a single
problem. For example, "book hotel", "approve contract", "create order" are all conversations. You might
- like to think of a conversation implementing a single "use case", but the relationship is not
- necessarily quite exact. </para>
- <para> A conversation holds state associated with "what the user is doing now, in this window". A single
+ like to think of a conversation implementing a single "use case" or "user story", but the relationship
+ is not necessarily quite exact.
+ </para>
+ <para>
+ A conversation holds state associated with "what the user is doing now, in this window". A single
user may have multiple conversations in progress at any point in time, usually in multiple windows. The
conversation context allows us to ensure that state from the different conversations does not collide
- and cause bugs. </para>
- <para> It might take you some time to get used to thinking of applications in terms of conversations. But
+ and cause bugs.
+ </para>
+ <para>
+ It might take you some time to get used to thinking of applications in terms of conversations. But
once you get used to it, we think you'll love the notion, and never be able to not think in terms of
- conversations again! </para>
- <para> Some conversations last for just a single request. Conversations that span multiple requests must be
- demarcated using annotations provided by Seam. </para>
- <para> Some conversations are also <emphasis>tasks</emphasis>. A task is a conversation that is significant
+ conversations again!
+ </para>
+ <para>
+ Some conversations last for just a single request. Conversations that span multiple requests must be
+ demarcated using annotations provided by Seam.
+ </para>
+ <para>
+ Some conversations are also <emphasis>tasks</emphasis>. A task is a conversation that is significant
in terms of a long-running business process, and has the potential to trigger a business process state
transition when it is successfully completed. Seam provides a special set of annotations for task
- demarcation. </para>
- <para> Conversations may be <emphasis>nested</emphasis>, with one conversation taking place "inside" a wider
- conversation. This is an advanced feature. </para>
- <para> Usually, conversation state is actually held by Seam in the servlet session between requests. Seam
+ demarcation.
+ </para>
+ <para>
+ Conversations may be <emphasis>nested</emphasis>, with one conversation taking place "inside" a wider
+ conversation. This is an advanced feature.
+ </para>
+ <para>
+ Usually, conversation state is actually held by Seam in the servlet session between requests. Seam
implements configurable <emphasis>conversation timeout</emphasis>, automatically destroying inactive
conversations, and thus ensuring that the state held by a single user login session does not grow
- without bound if the user abandons conversations. </para>
- <para> Seam serializes processing of concurrent requests that take place in the same long-running
- conversation context, in the same process. </para>
- <para> Alternatively, Seam may be configured to keep conversational state in the client browser. </para>
+ without bound if the user abandons conversations.
+ </para>
+ <para>
+ Seam serializes processing of concurrent requests that take place in the same long-running
+ conversation context, in the same process.
+ </para>
+ <para>
+ Alternatively, Seam may be configured to keep conversational state in the client browser.
+ </para>
</sect2>
<sect2>
<title>Session context</title>
- <para> A session context holds state associated with the user login session. While there are some cases
+ <para>
+ A session context holds state associated with the user login session. While there are some cases
where it is useful to share state between several conversations, we generally frown on the use of
- session context for holding components other than global information about the logged in user. </para>
- <para> In a JSR-168 portal environment, the session context represents the portlet session. </para>
+ session context for holding components other than global information about the logged in user.
+ </para>
+ <para>
+ In a JSR-168 portal environment, the session context represents the portlet session.
+ </para>
</sect2>
<sect2>
<title>Business process context</title>
- <para> The business process context holds state associated with the long running business process. This
+ <para>
+ The business process context holds state associated with the long running business process. This
state is managed and made persistent by the BPM engine (JBoss jBPM). The business process spans multiple
interactions with multiple users, so this state is shared between multiple users, but in a well-defined
manner. The current task determines the current business process instance, and the lifecycle of the
business process is defined externally using a <emphasis>process definition language</emphasis>, so
- there are no special annotations for business process demarcation. </para>
+ there are no special annotations for business process demarcation.
+ </para>
</sect2>
<sect2>
<title>Application context</title>
- <para> The application context is the familiar servlet context from the servlet spec. Application context is
+ <para>
+ The application context is the familiar servlet context from the servlet spec. Application context is
mainly useful for holding static information such as configuration data, reference data or metamodels.
- For example, Seam stores its own configuration and metamodel in the application context. </para>
+ For example, Seam stores its own configuration and metamodel in the application context.
+ </para>
</sect2>
<sect2>
<title>Context variables</title>
- <para> A context defines a namespace, a set of <emphasis>context variables</emphasis>. These work much the
+ <para>
+ A context defines a namespace, a set of <emphasis>context variables</emphasis>. These work much the
same as session or request attributes in the servlet spec. You may bind any value you like to a context
- variable, but usually we bind Seam component instances to context variables. </para>
+ variable, but usually we bind Seam component instances to context variables.
+ </para>
- <para> So, within a context, a component instance is identified by the context variable name (this is
+ <para>
+ So, within a context, a component instance is identified by the context variable name (this is
usually, but not always, the same as the component name). You may programatically access a named
component instance in a particular scope via the <literal>Contexts</literal> class, which provides
- access to several thread-bound instances of the <literal>Context</literal> interface: </para>
+ access to several thread-bound instances of the <literal>Context</literal> interface:
+ </para>
<programlisting><![CDATA[User user = (User) Contexts.getSessionContext().get("user");]]></programlisting>
- <para> You may also set or change the value associated with a name: </para>
+ <para>
+ You may also set or change the value associated with a name:
+ </para>
<programlisting><![CDATA[Contexts.getSessionContext().set("user", user);]]></programlisting>
- <para> Usually, however, we obtain components from a context via injection, and put component instances into
- a context via outjection. </para>
+ <para>
+ Usually, however, we obtain components from a context via injection, and put component instances into
+ a context via outjection.
+ </para>
</sect2>
<sect2>
<title>Context search priority</title>
- <para> Sometimes, as above, component instances are obtained from a particular known scope. Other times, all
- stateful scopes are searched, in <emphasis>priority order</emphasis>. The order is as follows: </para>
+ <para>
+ Sometimes, as above, component instances are obtained from a particular known scope. Other times, all
+ stateful scopes are searched, in <emphasis>priority order</emphasis>. The order is as follows:
+ </para>
<itemizedlist>
<listitem>
@@ -181,46 +234,60 @@
</listitem>
</itemizedlist>
- <para> You can perform a priority search by calling <literal>Contexts.lookupInStatefulContexts()</literal>.
- Whenever you access a component by name from a JSF page, a priority search occurs. </para>
+ <para>
+ You can perform a priority search by calling <literal>Contexts.lookupInStatefulContexts()</literal>.
+ Whenever you access a component by name from a JSF page, a priority search occurs.
+ </para>
</sect2>
<sect2>
<title>Concurrency model</title>
- <para> Neither the servlet nor EJB specifications define any facilities for managing concurrent requests
+ <para>
+ Neither the servlet nor EJB specifications define any facilities for managing concurrent requests
originating from the same client. The servlet container simply lets all threads run concurrently and
leaves enforcing threadsafeness to application code. The EJB container allows stateless components to be
- accessed concurrently, and throws an exception if multiple threads access a stateful session bean. </para>
- <para> This behavior might have been okay in old-style web applications which were based around
+ accessed concurrently, and throws an exception if multiple threads access a stateful session bean.
+ </para>
+ <para>
+ This behavior might have been okay in old-style web applications which were based around
fine-grained, synchronous requests. But for modern applications which make heavy use of many
fine-grained, asynchronous (AJAX) requests, concurrency is a fact of life, and must be supported by the
- programming model. Seam weaves a concurrency management layer into its context model. </para>
- <para> The Seam session and application contexts are multithreaded. Seam will allow concurrent requests in a
+ programming model. Seam weaves a concurrency management layer into its context model.
+ </para>
+ <para>
+ The Seam session and application contexts are multithreaded. Seam will allow concurrent requests in a
context to be processed concurrently. The event and page contexts are by nature single threaded. The
business process context is strictly speaking multi-threaded, but in practice concurrency is
sufficiently rare that this fact may be disregarded most of the time. Finally, Seam enforces a
<emphasis>single thread per conversation per process</emphasis> model for the conversation context
- by serializing concurrent requests in the same long-running conversation context. </para>
- <para> Since the session context is multithreaded, and often contains volatile state, session scope
+ by serializing concurrent requests in the same long-running conversation context.
+ </para>
+ <para>
+ Since the session context is multithreaded, and often contains volatile state, session scope
components are always protected by Seam from concurrent access. Seam serializes requests to session
scope session beans and JavaBeans by default (and detects and breaks any deadlocks that occur). This is
not the default behaviour for application scoped components however, since application scoped components
do not usually hold volatile state and because synchronization at the global level is
<emphasis>extremely</emphasis> expensive. However, you can force a serialized threading model on any
- session bean or JavaBean component by adding the <literal>@Synchronized</literal> annotation. </para>
- <para> This concurrency model means that AJAX clients can safely use volatile session and conversational
- state, without the need for any special work on the part of the developer. </para>
+ session bean or JavaBean component by adding the <literal>@Synchronized</literal> annotation.
+ </para>
+ <para>
+ This concurrency model means that AJAX clients can safely use volatile session and conversational
+ state, without the need for any special work on the part of the developer.
+ </para>
</sect2>
</sect1>
<sect1>
<title>Seam components</title>
- <para> Seam components are POJOs (Plain Old Java Objects). In particular, they are JavaBeans or EJB 3.0
+ <para>
+ Seam components are POJOs (Plain Old Java Objects). In particular, they are JavaBeans or EJB 3.0
enterprise beans. While Seam does not require that components be EJBs and can even be used without an EJB
3.0 compliant container, Seam was designed with EJB 3.0 in mind and includes deep integration with EJB 3.0.
- Seam supports the following <emphasis>component types</emphasis>. </para>
+ Seam supports the following <emphasis>component types</emphasis>.
+ </para>
<itemizedlist>
<listitem>
@@ -242,79 +309,116 @@
<sect2>
<title>Stateless session beans</title>
- <para> Stateless session bean components are not able to hold state across multiple invocations. Therefore,
+ <para>
+ Stateless session bean components are not able to hold state across multiple invocations. Therefore,
they usually work by operating upon the state of other components in the various Seam contexts. They may
- be used as JSF action listeners, but cannot provide properties to JSF components for display. </para>
- <para> Stateless session beans always live in the stateless context. </para>
- <para> Stateless session beans are the least interesting kind of Seam component. </para>
+ be used as JSF action listeners, but cannot provide properties to JSF components for display.
+ </para>
+ <para>
+ Stateless session beans always live in the stateless context.
+ </para>
+ <para>
+ Stateless session beans are the least interesting kind of Seam component.
+ </para>
</sect2>
<sect2>
<title>Stateful session beans</title>
- <para> Stateful session bean components are able to hold state not only across multiple invocations of the
+ <para>
+ Stateful session bean components are able to hold state not only across multiple invocations of the
bean, but also across multiple requests. Application state that does not belong in the database should
usually be held by stateful session beans. This is a major difference between Seam and many other web
application frameworks. Instead of sticking information about the current conversation directly in the
<literal>HttpSession</literal>, you should keep it in instance variables of a stateful session bean
that is bound to the conversation context. This allows Seam to manage the lifecycle of this state for
you, and ensure that there are no collisions between state relating to different concurrent
- conversations. </para>
- <para> Stateful session beans are often used as JSF action listener, and as backing beans that provide
- properties to JSF components for display or form submission. </para>
- <para> By default, stateful session beans are bound to the conversation context. They may never be bound to
- the page or stateless contexts. </para>
- <para> Concurrent requests to session-scoped stateful session beans are always serialized by Seam. </para>
+ conversations.
+ </para>
+ <para>
+ Stateful session beans are often used as JSF action listener, and as backing beans that provide
+ properties to JSF components for display or form submission.
+ </para>
+ <para>
+ By default, stateful session beans are bound to the conversation context. They may never be bound to
+ the page or stateless contexts.
+ </para>
+ <para>
+ Concurrent requests to session-scoped stateful session beans are always serialized by Seam.
+ </para>
</sect2>
<sect2>
<title>Entity beans</title>
- <para> Entity beans may be bound to a context variable and function as a seam component. Because entities
+ <para>
+ Entity beans may be bound to a context variable and function as a seam component. Because entities
have a persistent identity in addition to their contextual identity, entity instances are usually bound
- explicitly in Java code, rather than being instantiated implicitly by Seam. </para>
- <para> Entity bean components do not support bijection or context demarcation. Nor does invocation of an
- entity bean trigger validation. </para>
- <para> Entity beans are not usually used as JSF action listeners, but do often function as backing beans
+ explicitly in Java code, rather than being instantiated implicitly by Seam.
+ </para>
+ <para>
+ Entity bean components do not support bijection or context demarcation. Nor does invocation of an
+ entity bean trigger validation.
+ </para>
+ <para>
+ Entity beans are not usually used as JSF action listeners, but do often function as backing beans
that provide properties to JSF components for display or form submission. In particular, it is common to
use an entity as a backing bean, together with a stateless session bean action listener to implement
- create/update/delete type functionality. </para>
+ create/update/delete type functionality.
+ </para>
<para> By default, entity beans are bound to the conversation context. They may never be bound to the
- stateless context. </para>
- <para> Note that it in a clustered environment is somewhat less efficient to bind an entity bean directly to
+ stateless context.
+ </para>
+ <para>
+ Note that it in a clustered environment is somewhat less efficient to bind an entity bean directly to
a conversation or session scoped Seam context variable than it would be to hold a reference to the
entity bean in a stateful session bean. For this reason, not all Seam applications define entity beans
- to be Seam components. </para>
+ to be Seam components.
+ </para>
</sect2>
<sect2>
<title>JavaBeans</title>
- <para> Javabeans may be used just like a stateless or stateful session bean. However, they do not provide
+ <para>
+ Javabeans may be used just like a stateless or stateful session bean. However, they do not provide
the functionality of a session bean (declarative transaction demarcation, declarative security,
- efficient clustered state replication, EJB 3.0 persistence, timeout methods, etc). </para>
- <para> In a later chapter, we show you how to use Seam and Hibernate without an EJB container. In this use
+ efficient clustered state replication, EJB 3.0 persistence, timeout methods, etc).
+ </para>
+ <para>
+ In a later chapter, we show you how to use Seam and Hibernate without an EJB container. In this use
case, components are JavaBeans instead of session beans. Note, however, that in many application servers
it is somewhat less efficient to cluster conversation or session scoped Seam JavaBean components than it
- is to cluster stateful session bean components. </para>
- <para> By default, JavaBeans are bound to the event context. </para>
- <para> Concurrent requests to session-scoped JavaBeans are always serialized by Seam. </para>
+ is to cluster stateful session bean components.
+ </para>
+ <para>
+ By default, JavaBeans are bound to the event context.
+ </para>
+ <para>
+ Concurrent requests to session-scoped JavaBeans are always serialized by Seam.
+ </para>
</sect2>
<sect2>
<title>Message-driven beans</title>
- <para> Message-driven beans may function as a seam component. However, message-driven beans are called quite
+ <para>
+ Message-driven beans may function as a seam component. However, message-driven beans are called quite
differently to other Seam components - instead of invoking them via the context variable, they listen
- for messages sent to a JMS queue or topic. </para>
- <para> Message-driven beans may not be bound to a Seam context. Nor do they have access to the session or
+ for messages sent to a JMS queue or topic.
+ </para>
+ <para>
+ Message-driven beans may not be bound to a Seam context. Nor do they have access to the session or
conversation state of their "caller". However, they do support bijection and some other Seam
- functionality. </para>
+ functionality.
+ </para>
</sect2>
<sect2>
<title>Interception</title>
- <para> In order to perform its magic (bijection, context demarcation, validation, etc), Seam must intercept
+ <para>
+ In order to perform its magic (bijection, context demarcation, validation, etc), Seam must intercept
component invocations. For JavaBeans, Seam is in full control of instantiation of the component, and no
special configuration is needed. For entity beans, interception is not required since bijection and
context demarcation are not defined. For session beans, we must register an EJB interceptor for the
- session bean component. We could use an annotation, as follows: </para>
+ session bean component. We could use an annotation, as follows:
+ </para>
<programlisting><![CDATA[@Stateless
@Interceptors(SeamInterceptor.class)
@@ -322,7 +426,9 @@
...
}]]></programlisting>
- <para> But a much better way is to define the interceptor in <literal>ejb-jar.xml</literal>. </para>
+ <para>
+ But a much better way is to define the interceptor in <literal>ejb-jar.xml</literal>.
+ </para>
<programlisting><![CDATA[<interceptors>
<interceptor>
@@ -341,8 +447,10 @@
<sect2>
<title>Component names</title>
- <para> Almost all seam components need a name. We assign a name to a component using the
- <literal>@Name</literal> annotation: </para>
+ <para>
+ Almost all seam components need a name. We assign a name to a component using the
+ <literal>@Name</literal> annotation:
+ </para>
<programlisting><![CDATA[@Name("loginAction")
@Stateless
@@ -350,11 +458,14 @@
...
}]]></programlisting>
- <para> This name is the <emphasis>seam component name</emphasis> and is not related to any other name
+ <para>
+ This name is the <emphasis>seam component name</emphasis> and is not related to any other name
defined by the EJB specification. However, seam component names work just like JSF managed bean names
- and you can think of the two concepts as identical. </para>
+ and you can think of the two concepts as identical.
+ </para>
- <para> Just like in JSF, a seam component instance is usually bound to a context variable with the same name
+ <para>
+ Just like in JSF, a seam component instance is usually bound to a context variable with the same name
as the component name. So, for example, we would access the <literal>LoginAction</literal> using
<literal>Contexts.getStatelessContext().get("loginAction")</literal>. In particular, whenever Seam
itself instantiates a component, it binds the new instance to a variable with the component name.
@@ -363,9 +474,12 @@
role in the system. For example, the currently logged in <literal>User</literal> might be bound to the
<literal>currentUser</literal> session context variable, while a <literal>User</literal> that is the
subject of some administration functionality might be bound to the <literal>user</literal> conversation
- context variable. </para>
+ context variable.
+ </para>
- <para> For very large applications, and for built-in seam components, qualified names are often used. </para>
+ <para>
+ For very large applications, and for built-in seam components, qualified names are often used.
+ </para>
<programlisting><![CDATA[@Name("com.jboss.myapp.loginAction")
@Stateless
@@ -374,27 +488,35 @@
...
}]]></programlisting>
- <para> Unfortunately, JSF's expression language interprets a period as a property dereference. So, inside a
- JSF expression, we use <literal>$</literal> to indicate a qualified component name: </para>
+ <para>
+ Unfortunately, JSF's expression language interprets a period as a property dereference. So, inside a
+ JSF expression, we use <literal>$</literal> to indicate a qualified component name:
+ </para>
<programlisting><![CDATA[<h:commandButton type="submit" value="Login"
action="#{com$jboss$myapp$loginAction.login}"/>]]></programlisting>
- <para> Since this is ugly, Seam also provides a means of aliasing a qualified name to a simple name. Add a
- line like this to the <literal>components.xml</literal> file: </para>
+ <para>
+ Since this is ugly, Seam also provides a means of aliasing a qualified name to a simple name. Add a
+ line like this to the <literal>components.xml</literal> file:
+ </para>
<programlisting><![CDATA[<factory name="loginAction" scope="STATELESS" value="#{com$jboss$myapp$loginAction}"/>]]></programlisting>
- <para> All of the built-in Seam components have qualified names, but most of them are aliased to a simple
- name by the <literal>components.xml</literal> file included in the Seam jar. </para>
+ <para>
+ All of the built-in Seam components have qualified names, but most of them are aliased to a simple
+ name by the <literal>components.xml</literal> file included in the Seam jar.
+ </para>
</sect2>
<sect2>
<title>Defining the component scope</title>
- <para> We can override the default scope (context) of a component using the <literal>@Scope</literal>
+ <para>
+ We can override the default scope (context) of a component using the <literal>@Scope</literal>
annotation. This lets us define what context a component instance is bound to, when it is instantiated
- by Seam. </para>
+ by Seam.
+ </para>
<programlisting><![CDATA[@Name("user")
@Entity
@@ -404,19 +526,22 @@
}]]></programlisting>
<para>
- <literal>org.jboss.seam.ScopeType</literal> defines an enumeration of possible scopes. </para>
+ <literal>org.jboss.seam.ScopeType</literal> defines an enumeration of possible scopes.
+ </para>
</sect2>
<sect2>
<title>Components with multiple roles</title>
- <para> Some Seam component classes can fulfill more than one role in the system. For example, we often have
+ <para>
+ Some Seam component classes can fulfill more than one role in the system. For example, we often have
a <literal>User</literal> class which is usually used as a session-scoped component representing the
current user but is used in user administration screens as a conversation-scoped component. The
<literal>@Role</literal> annotation lets us define an additional named role for a component, with a
different scope—it lets us bind the same component class to different context variables. (Any
Seam component <emphasis>instance</emphasis> may be bound to multiple context variables, but this lets
- us do it at the class level, and take advantage of auto-instantiation.) </para>
+ us do it at the class level, and take advantage of auto-instantiation.)
+ </para>
<programlisting><![CDATA[@Name("user")
@Entity
@@ -426,7 +551,9 @@
...
}]]></programlisting>
- <para> The <literal>@Roles</literal> annotation lets us specify as many additional roles as we like. </para>
+ <para>
+ The <literal>@Roles</literal> annotation lets us specify as many additional roles as we like.
+ </para>
<programlisting><![CDATA[@Name("user")
@Entity
@@ -441,23 +568,32 @@
<sect2>
<title>Built-in components</title>
- <para> Like many good frameworks, Seam eats its own dogfood and is implemented mostly as a set of built-in
+ <para>
+ Like many good frameworks, Seam eats its own dogfood and is implemented mostly as a set of built-in
Seam interceptors (see later) and Seam components. This makes it easy for applications to interact with
built-in components at runtime or even customize the basic functionality of Seam by replacing the
built-in components with custom implementations. The built-in components are defined in the Seam
- namespace <literal>org.jboss.seam.core</literal> and the Java package of the same name. </para>
- <para> The built-in components may be injected, just like any Seam components, but they also provide
- convenient static <literal>instance()</literal> methods: </para>
+ namespace <literal>org.jboss.seam.core</literal> and the Java package of the same name.
+ </para>
+ <para>
+ The built-in components may be injected, just like any Seam components, but they also provide
+ convenient static <literal>instance()</literal> methods:
+ </para>
<programlisting><![CDATA[FacesMessages.instance().add("Welcome back, #{user.name}!");]]></programlisting>
- <para> Seam was designed to integrate tightly in a Java EE 5 environment. However, we understand that there
+ <para>
+ Seam was designed to integrate tightly in a Java EE 5 environment. However, we understand that there
are many projects which are not running in a full EE environment. We also realize the critical
importance of easy unit and integration testing using frameworks such as TestNG and JUnit. So, we've
made it easy to run Seam in Java SE environments by allowing you to boostrap certain critical
- infrastructure normally only found in EE environments by installing built-in Seam components. </para>
- <para> For example, you can run your EJB3 components in Tomcat or an integration test suite just by
+ infrastructure normally only found in EE environments by installing built-in Seam components.
+ </para>
+ <para>
+ For example, you can run your EJB3 components in Tomcat or an integration test suite just by
installing the built-in component <literal>org.jboss.seam.core.ejb</literal>, which automatically
- bootstraps the JBoss Embeddable EJB3 container and deploys your EJB components. </para>
- <para> Or, if you're not quite ready for the Brave New World of EJB 3.0, you can write a Seam application
+ bootstraps the JBoss Embeddable EJB3 container and deploys your EJB components.
+ </para>
+ <para>
+ Or, if you're not quite ready for the Brave New World of EJB 3.0, you can write a Seam application
that uses only JavaBean components, together with Hibernate3 for persistence, by installing the built-in
component <literal>org.jboss.seam.core.hibernate</literal>. When using Hibernate outside of a J2EE
environment, you will also probably need a JTA transaction manager and JNDI server, which are available
@@ -466,405 +602,6 @@
</para>
</sect2>
-
- </sect1>
-
- <sect1>
- <title>Configuring components</title>
- <para> Seam provides two basic approaches to configuring components: configuration via property settings in a
- properties file or <literal>web.xml</literal>, and configuration via <literal>components.xml</literal>. </para>
-
- <sect2>
- <title>Configuring components via property settings</title>
- <para> Seam components may be provided with configuration properties either via servlet context parameters,
- or via a properties file named <literal>seam.properties</literal> in the root of the classpath. </para>
- <para> The configurable Seam component must expose a JavaBeans-style property setter methods for the
- configurable attributes. If a seam component named <literal>com.jboss.myapp.settings</literal> has a
- setter method named <literal>setLocale()</literal>, we can provide a property named
- <literal>com.jboss.myapp.settings.locale</literal> in the <literal>seam.properties</literal> file or
- as a servlet context parameter, and Seam will set the value of the <literal>locale</literal> attribute
- whenever it instantiates the component. </para>
- <para> The same mechanism is used to configure Seam itself. For example, to set the conversation timeout, we
- provide a value for <literal>org.jboss.seam.core.manager.conversationTimeout</literal> in
- <literal>web.xml</literal> or <literal>seam.properties</literal>. (There is a built-in Seam
- component named <literal>org.jboss.seam.core.manager</literal> with a setter method named
- <literal>setConversationTimeout()</literal>.) </para>
- </sect2>
-
- <sect2>
- <title>Configuring components via <literal>components.xml</literal></title>
- <para> The <literal>components.xml</literal> file is a bit more powerful than property settings. It lets
- you: </para>
-
- <itemizedlist>
- <listitem>
- <para> Configure components that have been installed automatically—including both built-in
- components, and application components that have been annotated with the
- <literal>@Name</literal> annotation and picked up by Seam's deployment scanner. </para>
- </listitem>
- <listitem>
- <para> Install classes with no <literal>@Name</literal> annotation as Seam components—this
- is most useful for certain kinds of infrastructural components which can be installed multiple
- times different names (for example Seam-managed persistence contexts). </para>
- </listitem>
- <listitem>
- <para> Install components that <emphasis>do</emphasis> have a <literal>@Name</literal> annotation
- but are not installed by default because of an <literal>@Install</literal> annotation that
- indicates the component should not be installed. </para>
- </listitem>
- <listitem>
- <para> Override the scope of a component. </para>
- </listitem>
- </itemizedlist>
-
- <para> A <literal>components.xml</literal> file may appear in one of three different places: </para>
-
- <itemizedlist>
- <listitem>
- <para> The <literal>WEB-INF</literal> directory of a <literal>war</literal>. </para>
- </listitem>
- <listitem>
- <para> The <literal>META-INF</literal> directory of a <literal>jar</literal>. </para>
- </listitem>
- <listitem>
- <para> Any directory of a <literal>jar</literal> that contains classes with an
- <literal>@Name</literal> annotation. </para>
- </listitem>
- </itemizedlist>
-
- <para> Usually, Seam components are installed when the deployment scanner discovers a class with a
- <literal>@Name</literal> annotation sitting in an archive with a <literal>seam.properties</literal>
- file, unless that component contains an <literal>@Install</literal> annotation that indicates it should
- not be installed. The <literal>components.xml</literal> file lets us handle special cases where we need
- to override the annotations. </para>
-
- <para> For example, the following <literal>components.xml</literal> file installs the JBoss Embeddable EJB3
- container: </para>
-
- <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components" xmlns:core="http://jboss.com/products/seam/core">
- <core:ejb />
-</components>]]></programlisting>
-
- <para>Seam also provides a generic component installation mechanism. This requires components to be be
- configured in a slightly more verbose way:</para>
-
- <programlisting><![CDATA[<components>
- <component class="org.jboss.seam.core.Ejb"/>
-</components>]]></programlisting>
- <para> This one installs and configures two different Seam-managed persistence contexts: </para>
-
- <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components" xmlns:core="http://jboss.com/products/seam/core"
- <core:managed-persistence-context name="customerDatabase"
- persistence-unit-jndi-name="java:/customerEntityManagerFactory"/>
- <core:managed-persistence-context name="accountingDatabase"
- persistence-unit-jndi-name="java:/accountingEntityManagerFactory"/>
-</components>]]></programlisting>
-
- <para>To use the generic component tag, you need to add the Java class of the component and specify
- properties as separate elements. </para>
-
- <programlisting><![CDATA[<components>
- <component name="customerDatabase"
- class="org.jboss.seam.core.ManagedPersistenceContext">
- <property name="persistenceUnitJndiName">java:/customerEntityManagerFactory</property>
- </component>
-
- <component name="accountingDatabase"
- class="org.jboss.seam.core.ManagedPersistenceContext">
- <property name="persistenceUnitJndiName">java:/accountingEntityManagerFactory</property>
- </component>
-</components>]]></programlisting>
-
- <para> This example creates a session-scoped Seam-managed persistence context (this is not recommended in
- practice): </para>
-
- <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components" xmlns:core="http://jboss.com/products/seam/core"
- <core:managed-persistence-context name="productDatabase" scope="session"
- persistence-unit-jndi-name="java:/productEntityManagerFactory"/>
-</components>]]></programlisting>
-
- <programlisting><![CDATA[<components>
- <component name="productDatabase"
- scope="session"
- class="org.jboss.seam.core.ManagedPersistenceContext">
- <property name="persistenceUnitJndiName">java:/productEntityManagerFactory</property>
- </component>
-
-</components>]]></programlisting>
-
- <para> The <literal><factory></literal> declaration lets you specify a value or method binding
- expression that will be evaluated to initialize the value of a context variable when it is first
- referenced. </para>
-
- <programlisting><![CDATA[<components>
-
- <factory name="contact" method="#{contactManager.loadContact}" scope="CONVERSATION"/>
-
-</components>]]></programlisting>
-
- <para> You can create an "alias" (a second name) for a Seam component like so: </para>
-
- <programlisting><![CDATA[<components>
-
- <factory name="user" value="#{actor}" scope="STATELESS"/>
-
-</components>]]></programlisting>
-
- <para> You can even create an "alias" for a commonly used expression: </para>
-
- <programlisting><![CDATA[<components>
-
- <factory name="contact" value="#{contactManager.contact}" scope="STATELESS"/>
-
-</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> file which can be replaced either by your Ant build script (at
- deployment time) or by providing a file named <literal>components.properties</literal> in the classpath
- (at development time). You'll see this approach used in the Seam examples. </para>
-
- </sect2>
-
- <sect2>
- <title>Fine-grained configuration files</title>
- <para> If you have a large number of components that need to be configured in XML, it makes much more sense
- to split up the information in <literal>components.properties</literal> into many small files. Seam lets
- you put configuration for a class named, for example, <literal>com.helloworld.Hello</literal> in a
- resource named <literal>com/helloworld/Hello.component.xml</literal>. (You might be familiar with this
- pattern, since it is the same one we use in Hibernate.) The root element of the file may be either a
- <literal><components></literal> or <literal><component></literal>
- element. </para>
-
- <para> The first option lets you define multiple components in the file: </para>
-
- <programlisting><![CDATA[<components>
- <component class="com.helloworld.Hello" name="hello">
- <property name="name">#{user.name}</property>
- </component>
- <factory name="message" value="#{hello.message}"/>
-</components>]]></programlisting>
-
- <para> The second option only lets you define or configure one component, but is less noisy: </para>
-
- <programlisting><![CDATA[<component name="hello">
- <property name="name">#{user.name}</property>
-</component>]]></programlisting>
-
- <para> In the second option, the class name is implied by the file in which the component definition
- appears. </para>
-
- <para> Alternatively, you may put configuration for all classes in the <literal>com.helloworld</literal>
- package in <literal>com/helloworld/components.xml</literal>. </para>
- </sect2>
-
- <sect2>
- <title>Configurable property types</title>
- <para> Properties of string, primitive or primitive wrapper type may be configured just as you would expect: </para>
-
- <programlisting><![CDATA[org.jboss.seam.core.manager.conversationTimeout 60000]]></programlisting>
-
- <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components" xmlns:core="http://jboss.com/products/seam/core">
- <core:manager conversation-timeout="60000"/>
-</components>]]></programlisting>
-
- <programlisting><![CDATA[<component name="org.jboss.seam.core.manager">
- <property name="conversationTimeout">60000</property>
-</component>]]></programlisting>
-
- <para> Arrays, sets and lists of strings or primitives are also supported: </para>
-
- <programlisting><![CDATA[org.jboss.seam.core.jbpm.processDefinitions order.jpdl.xml, return.jpdl.xml, inventory.jpdl.xml]]></programlisting>
-
- <programlisting><![CDATA[<core:jbpm>
- <core:process-definitions>
- <value>order.jpdl.xml</value>
- <value>return.jpdl.xml</value>
- <value>inventory.jpdl.xml</value>
- </core:process-definitions>
-</core:jbpm>]]></programlisting>
-
- <programlisting><![CDATA[<component name="org.jboss.seam.core.jbpm">
- <property name="processDefinitions">
- <value>order.jpdl.xml</value>
- <value>return.jpdl.xml</value>
- <value>inventory.jpdl.xml</value>
- </property>
-</component>]]></programlisting>
-
- <para> Even maps with String-valued keys and string or primitive values are supported: </para>
-
- <programlisting><![CDATA[<component name="issueEditor">
- <property name="issueStatuses">
- <key>open</key> <value>open issue</value>
- <key>resolved</key> <value>issue resolved by developer</value>
- <key>closed</key> <value>resolution accepted by user</value>
- </property>
-</component>]]></programlisting>
-
- <para> Finally, you may wire together components using a value-binding expression. Note that this is quite
- different to injection using <literal>@In</literal>, since it happens at component instantiation time
- instead of invocation time. It is therefore much more similar to the dependency injection facilities
- offered by traditional IoC containers like JSF or Spring. </para>
-
-
- <programlisting><![CDATA[<drools:managed-working-memory name="policyPricingWorkingMemory" rule-base="#{policyPricingRules}"/>]]></programlisting>
-
- <programlisting><![CDATA[<component name="policyPricingWorkingMemory"
- class="org.jboss.seam.drools.ManagedWorkingMemory">
- <property name="ruleBase">#{policyPricingRules}</property>
-</component>]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Using Namespaces</title>
- <para> Throughout the examples, there has been two competing ways of declaring components: with and without
- namespaces. The following shows a standard minimal components.xml file without namespaces.</para>
-
- <programlisting><?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE components PUBLIC "-//JBoss/Seam Component Configuration DTD 1.1//EN"
- "http://jboss.com/products/seam/components-1.1.dtd">
-<components>
- <component class="org.jboss.seam.core.init">
- <property name="debug">false</property>
- <property name="jndiPattern">@jndiPattern@</property>
- </component>
-
- <component name="org.jboss.sean.core.ejb" installed="@embeddedEjb@" />
-</components></programlisting>
-
- <para>The generic version uses the seam components DTD. While the XML setup overhead is minimal, the actual
- content XML is quite verbose. Additionally, the components and attributes cannot be validated at
- development time. </para>
-
- <para>The namespace version looks like this:</para>
-
- <programlisting>
-<?xml version="1.0" encoding="UTF-8"?>
-<components xmlns="http://jboss.com/products/seam/components"
- xmlns:core="http://jboss.com/products/seam/core"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation=
- "http://jboss.com/products/seam/core http://jboss.com/products/seam/core-1.1.xsd
- http://jboss.com/products/seam/components http://jboss.com/products/seam/components-1.1.xsd">
- <core:init jndi-pattern="@jndiPattern@"/>
- <core:ejb installed="@embeddedEjb@"/>
-</components>
-</programlisting>
-
- <para>While there is a bit more XML setup overhead, the actual XML content is lean and easy to understand.
- The schemas provide detailed information about each component and the attributes available, allowing XML
- editors to offer intelligent auto-complete options. The use of namespaced elements makes generating and
- maintaining correct components.xml files much simpler. </para>
-
- <para> We recommend Seam users prefer the namespaced XML configuration to the plain XML. While this works
- great for the built-in Seam components, Seam obviously doesn't define any namespaces that can be used
- for user components. Seam does support mixing the two models, allowing the use of the generic
- <component> declarations of user components, but it also allows you to quickly declare
- namespaces to be used for application-specific components. </para>
-
- <para>Any Java package can be associated with an XML namespace using the <literal>@Namespace</literal>
- annotation on the package. Package annotations are declared in a file names
- <literal>package-info.java</literal> in the package directory. Here is an example from the seampay demo:</para>
-
- <programlisting>@Namespace(value="http://jboss.com/products/seam/examples/seampay")
-package org.jboss.seam.example.seampay;
-
-import org.jboss.seam.annotations.*;</programlisting>
-
- <para>Seam will scan for package annotations and associate the namespace with components in the given Java
- package. With this annotation, it becomes possible to use the namespace in an XML document to refer to
- application components. Note that it is not necessary to associate an XML schema with a namespace to
- create a valid document using namespaces. </para>
-
-
- <programlisting><components xmlns="http://jboss.com/products/seam/components"
- xmlns:pay="http://jboss.com/products/seam/examples/seampay"
- ... >
-
- <pay:payment-home name="paymentHome"
- new-instance="#{newPayment}"
- created-message="Created a new payment to #{newPayment.payee}" />
-
- <pay:payment name="newPayment"
- payee="Somebody"
- account="#{selectedAccount}"
- payment-date="#{currentDatetime}"
- created-date="#{currentDatetime}" />
- ...
-</components></programlisting>
-
- <para>This example illustrates the two usage models of a namespaced element. In the first example, the
- <literal><pay:payment-home></literal> references the <literal>paymentHome</literal>
- component: </para>
-
- <programlisting>
-package org.jboss.seam.example.seampay;
-...
- at Name("paymentHome")
-public class PaymentController
- extends EntityHome<Payment>
-{
- ...
-}</programlisting>
-
- <para>The element name is the hyphenated form of the component name. The attributes of the element map are
- the hyphenated form of the properties. Note that if we were using the generic XML it would be necessary
- to use lower camel case property names, <literal>updatedMessage</literal> instead of
- <literal>updated-message</literal>, for example. </para>
-
- <para> In the second component, the <pay:payment> element will locate the
- <literal>Payment</literal> class in the <literal>org.jboss.seam.example.seampay</literal> package. This
- connection is made because the namespace of the declaration is bound to that specific Java package. In
- this case <literal>Payment</literal> is an entity that is being declared as a Seam component:</para>
-
- <programlisting>package org.jboss.seam.example.seampay;
-...
- at Entity
-public class Payment
- implements Serializable
-{
- ...
-}</programlisting>
-
- <para>
- Although the attribute form is preferred, it is always possible to configure component properties using elements.
- </para>
-
- <programlisting><pay:payment-home name="paymentHome">
- <pay:new-instance>#{newPayment}</pay:new-instance>
- <pay:created-message>Created a new payment to #{newPayment.payee}</pay:created-message>
-</pay:payment-home></programlisting>
-
- <para>This usage would not generally make sense for simple values, but it can be very
- valuable when setting list or map values. The following shows a hypothetical <literal>someList</literal>
- attribute:
- </para>
-
- <programlisting><pay:payment-home name="paymentHome" new-instance="#{newPayment}"
- created-message="Created a new payment to #{newPayment.payee}">
- <pay:some-list>
- <value>one</value>
- <value>two</value>
- <value>three</value>
- </pay:some-list>
-</pay:payment-home></programlisting>
-
- <para>Even in this case, it is often preferable to use the attribute form of a list
- of values:</para>
-
- <programlisting><pay:payment-home name="paymentHome"
- new-instance="#{newPayment}"
- created-message="Created a new payment to #{newPayment.payee}"
- some-list="one,two,three"/></programlisting>
-
- <para>Seam does not yet provide a mechanism to automatically generate a schema for a set of components.
- If validation is desirable for application components, it is necessary to generate one manually.
- The schema definitions for the standard Seam packages can be used for guidance.
- </para>
- </sect2>
-
</sect1>
<sect1>
@@ -878,35 +615,43 @@
stateless components, this is reasonable. From the point of view of a client, all instances of a particular
stateless component are interchangeable. On the other hand, Seam emphasizes the use of stateful components.
So traditional dependency injection is no longer a very useful construct. Seam introduces the notion of
- <emphasis>bijection</emphasis> as a generalization of injection. In contrast to injection, bijection is: </para>
+ <emphasis>bijection</emphasis> as a generalization of injection. In contrast to injection, bijection is:
+ </para>
<itemizedlist>
<listitem>
<para>
<emphasis>contextual</emphasis> - bijection is used to assemble stateful components from various
different contexts (a component from a "wider" context may even have a reference to a component from
- a "narrower" context) </para>
+ a "narrower" context)
+ </para>
</listitem>
<listitem>
<para>
<emphasis>bidirectional</emphasis> - values are injected from context variables into attributes of
the component being invoked, and also <emphasis>outjected</emphasis> from the component attributes
back out to the context, allowing the component being invoked to manipulate the values of contextual
- variables simply by setting its own instance variables </para>
+ variables simply by setting its own instance variables
+ </para>
</listitem>
<listitem>
<para>
<emphasis>dynamic</emphasis> - since the value of contextual variables changes over time, and since
- Seam components are stateful, bijection takes place every time a component is invoked </para>
+ Seam components are stateful, bijection takes place every time a component is invoked
+ </para>
</listitem>
</itemizedlist>
- <para> In essence, bijection lets you alias a context variable to a component instance variable, by specifying
+ <para>
+ In essence, bijection lets you alias a context variable to a component instance variable, by specifying
that the value of the instance variable is injected, outjected, or both. Of course, we use annotations to
- enable bijection. </para>
+ enable bijection.
+ </para>
- <para> The <literal>@In</literal> annotation specifies that a value should be injected, either into an instance
- variable: </para>
+ <para>
+ The <literal>@In</literal> annotation specifies that a value should be injected, either into an instance
+ variable:
+ </para>
<programlisting><![CDATA[@Name("loginAction")
@Stateless
@@ -916,7 +661,9 @@
...
}]]></programlisting>
- <para> or into a setter method: </para>
+ <para>
+ or into a setter method:
+ </para>
<programlisting><![CDATA[@Name("loginAction")
@Stateless
@@ -933,15 +680,21 @@
}]]></programlisting>
- <para> By default, Seam will do a priority search of all contexts, using the name of the property or instance
+ <para>
+ By default, Seam will do a priority search of all contexts, using the name of the property or instance
variable that is being injected. You may wish to specify the context variable name explicitly, using, for
- example, <literal>@In("currentUser")</literal>. </para>
+ example, <literal>@In("currentUser")</literal>.
+ </para>
- <para> If you want Seam to create an instance of the component when there is no existing component instance
+ <para>
+ If you want Seam to create an instance of the component when there is no existing component instance
bound to the named context variable, you should specify <literal>@In(create=true)</literal>. If the value is
- optional (it can be null), specify <literal>@In(required=false)</literal>. </para>
+ optional (it can be null), specify <literal>@In(required=false)</literal>.
+ </para>
- <para> You can even inject the value of an expression: </para>
+ <para>
+ You can even inject the value of an expression:
+ </para>
<programlisting><![CDATA[@Name("loginAction")
@Stateless
@@ -951,10 +704,14 @@
...
}]]></programlisting>
- <para> (There is much more information about component lifecycle and injection in the next chapter.) </para>
+ <para>
+ (There is much more information about component lifecycle and injection in the next chapter.)
+ </para>
- <para> The <literal>@Out</literal> annotation specifies that an attribute should be outjected, either from an
- instance variable: </para>
+ <para>
+ The <literal>@Out</literal> annotation specifies that an attribute should be outjected, either from an
+ instance variable:
+ </para>
<programlisting><![CDATA[@Name("loginAction")
@Stateless
@@ -964,7 +721,9 @@
...
}]]></programlisting>
- <para> or from a getter method: </para>
+ <para>
+ or from a getter method:
+ </para>
<programlisting><![CDATA[@Name("loginAction")
@Stateless
@@ -980,7 +739,9 @@
...
}]]></programlisting>
- <para> An attribute may be both injected and outjected: </para>
+ <para>
+ An attribute may be both injected and outjected:
+ </para>
<programlisting><![CDATA[@Name("loginAction")
@Stateless
@@ -990,7 +751,9 @@
...
}]]></programlisting>
- <para> or: </para>
+ <para>
+ or:
+ </para>
<programlisting><![CDATA[@Name("loginAction")
@Stateless
@@ -1015,27 +778,37 @@
<sect1>
<title>Lifecycle methods</title>
- <para> Session bean and entity bean Seam components support all the usual EJB 3.0 lifecycle callback
+ <para>
+ Session bean and entity bean Seam components support all the usual EJB 3.0 lifecycle callback
(<literal>@PostConstruct</literal>, <literal>@PreDestroy</literal>, etc). Seam extends all of these
callbacks except <literal>@PreDestroy</literal> to JavaBean components. 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
+ 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
+ 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
+ <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>
+ specifying <literal>@Startup(depends={....})</literal>.
+ </para>
</sect1>
<sect1>
<title>Logging</title>
- <para> Who is not totally fed up with seeing noisy code like this? </para>
+ <para>
+ Who is not totally fed up with seeing noisy code like this?
+ </para>
<programlisting><![CDATA[private static final Log log = LogFactory.getLog(CreateOrderAction.class);
@@ -1048,12 +821,16 @@
return new Order(user, product, quantity);
}]]></programlisting>
- <para> It is difficult to imagine how the code for a simple log message could possibly be more verbose. There is
+ <para>
+ It is difficult to imagine how the code for a simple log message could possibly be more verbose. There is
more lines of code tied up in logging than in the actual business logic! I remain totally astonished that
- the Java community has not come up with anything better in 10 years. </para>
+ the Java community has not come up with anything better in 10 years.
+ </para>
- <para> Seam provides a logging API built on top of Apache commons-logging that simplifies this code
- significantly: </para>
+ <para>
+ Seam provides a logging API built on top of Apache commons-logging that simplifies this code
+ significantly:
+ </para>
<programlisting><![CDATA[@Logger private Log log;
@@ -1062,13 +839,17 @@
return new Order(user, product, quantity);
}]]></programlisting>
- <para> Note that we don't need the noisy <literal>if ( log.isDebugEnabled() )</literal> guard, since string
+ <para>
+ Note that we don't need the noisy <literal>if ( log.isDebugEnabled() )</literal> guard, since string
concatenation happens <emphasis>inside</emphasis> the <literal>debug()</literal> method. Note also that we
don't usually need to specify the log category explicitly, since Seam knows what component it is injecting
- the <literal>Log</literal> into. </para>
+ the <literal>Log</literal> into.
+ </para>
- <para> If <literal>User</literal> and <literal>Product</literal> are Seam components available in the current
- contexts, it gets even better: </para>
+ <para>
+ If <literal>User</literal> and <literal>Product</literal> are Seam components available in the current
+ contexts, it gets even better:
+ </para>
<programlisting><![CDATA[@Logger private Log log;
@@ -1081,25 +862,31 @@
<sect1>
<title>The <literal>Mutable</literal> interface and <literal>@ReadOnly</literal></title>
- <para> Many application servers feature an amazingly broken implementation of <literal>HttpSession</literal>
+ <para>
+ Many application servers feature an amazingly broken implementation of <literal>HttpSession</literal>
clustering, where changes to the state of mutable objects bound to the session are only replicated when the
application calls <literal>setAttribute()</literal> explicitly. This is a source of bugs that can not
effectively be tested for at development time, since they will only manifest when failover occurs.
Furthermore, the actual replication message contains the entire serialized object graph bound to the session
- attribute, which inefficient. </para>
+ attribute, which inefficient.
+ </para>
- <para> Of course, EJB stateful session beans must perform automatic dirty checking and replication of mutable
+ <para>
+ Of course, EJB stateful session beans must perform automatic dirty checking and replication of mutable
state and a sophisticated EJB container can introduce optimizations such as attribute-level replication.
Unfortunately, not all Seam users have the good fortune to be working in an environment that supports EJB
3.0. So, for session and conversation scoped JavaBean and entity bean components, Seam provides an extra
- layer of cluster-safe state management over the top of the web container session clustering. </para>
+ layer of cluster-safe state management over the top of the web container session clustering.
+ </para>
- <para> For session or conversation scoped JavaBean components, Seam automatically forces replication to occur by
+ <para>
+ For session or conversation scoped JavaBean components, Seam automatically forces replication to occur by
calling <literal>setAttribute()</literal> once in every request that the component was invoked by the
application. Of course, this strategy is inefficient for read-mostly components. You can control this
behavior by implementing the <literal>org.jboss.seam.core.Mutable</literal> interface, or by extending
<literal>org.jboss.seam.core.AbstractMutable</literal>, and writing your own dirty-checking logic inside
- the component. For example, </para>
+ the component. For example,
+ </para>
<programlisting><![CDATA[@Name("account")
public class Account extends AbstractMutable
@@ -1121,7 +908,9 @@
}]]></programlisting>
- <para> Or, you can use the <literal>@ReadOnly</literal> annotation to achieve a similar effect: </para>
+ <para>
+ Or, you can use the <literal>@ReadOnly</literal> annotation to achieve a similar effect:
+ </para>
<programlisting><![CDATA[@Name("account")
public class Account
@@ -1144,10 +933,12 @@
}]]></programlisting>
- <para> For session or conversation scoped entity bean components, Seam automatically forces replication to occur
+ <para>
+ For session or conversation scoped entity bean components, Seam automatically forces replication to occur
by calling <literal>setAttribute()</literal> once in every request. This strategy is not efficient, so
session or conversation scope entity beans should be used with care. You can always write a stateful session
- bean or JavaBean component to "manage" the entity bean instance. For example, </para>
+ bean or JavaBean component to "manage" the entity bean instance. For example,
+ </para>
<programlisting><![CDATA[@Stateful
@Name("account")
@@ -1165,33 +956,41 @@
}]]></programlisting>
- <para> Note that the <literal>EntityHome</literal> class in the Seam Framework provides a great example of this
- pattern. </para>
+ <para>
+ Note that the <literal>EntityHome</literal> class in the Seam Framework provides a great example of this
+ pattern.
+ </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
+ <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>
+ 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
+ <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>
+ 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>
+ <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;
@@ -1200,15 +999,19 @@
customerList = ... ;
} ]]></programlisting>
- <para> In both cases, the factory method is called when we reference the <literal>customerList</literal> context
+ <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>
+ remaining invisible to clients.
+ </para>
- <para> A manager component is any component with an <literal>@Unwrap</literal> method. This method returns the
+ <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>
+ referenced.
+ </para>
<programlisting><![CDATA[@Name("customerList")
@Scope(CONVERSATION)
@@ -1222,9 +1025,11 @@
}
}]]></programlisting>
- <para> This pattern is especially useful if we have some heavyweight object that needs a cleanup operation when
+ <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>
+ method.
+ </para>
</sect1>
1.31 +1 -1 jboss-seam/doc/reference/en/modules/configuration.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: configuration.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/configuration.xml,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -b -r1.30 -r1.31
--- configuration.xml 27 Nov 2006 03:28:16 -0000 1.30
+++ configuration.xml 29 Nov 2006 10:28:03 -0000 1.31
@@ -1,5 +1,5 @@
<chapter id="configuration">
- <title>Configuring Seam</title>
+ <title>Configuring Seam and packaging Seam applications</title>
<para>
Configuration is a very boring topic and an extremely tedious pastime.
Unfortunately, several lines of XML are required to integrate Seam into
1.10 +7 -6 jboss-seam/doc/reference/en/modules/framework.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: framework.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/framework.xml,v
retrieving revision 1.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
--- framework.xml 27 Nov 2006 03:28:16 -0000 1.9
+++ framework.xml 29 Nov 2006 10:28:03 -0000 1.10
@@ -296,10 +296,11 @@
<framework:entity-home name="personHome"
entity-class="eg.Person"
- new-instance="#{newPerson}"
- created-message="New person #{person.firstName} #{person.lastName} created"
- deleted-message="Person #{person.firstName} #{person.lastName} deleted"
- updated-message="Person #{person.firstName} #{person.lastName} updated"/>
+ new-instance="#{newPerson}">
+ <framework:created-message>New person #{person.firstName} #{person.lastName} created</framework:created-message>
+ <framework:deleted-message>Person #{person.firstName} #{person.lastName} deleted</framework:deleted-message>
+ <framework:updated-message>Person #{person.firstName} #{person.lastName} updated</framework:updated-message>
+</framework:entity-home>
<component name="newPerson" class="eg.Person">
<property name="nationality">#{country}</property>
1.11 +1 -1 jboss-seam/doc/reference/en/modules/jms.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: jms.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/jms.xml,v
retrieving revision 1.10
retrieving revision 1.11
diff -u -b -r1.10 -r1.11
--- jms.xml 27 Nov 2006 03:28:17 -0000 1.10
+++ jms.xml 29 Nov 2006 10:28:03 -0000 1.11
@@ -226,7 +226,7 @@
<para>
You also need to list topics and queues in <literal>components.xml</literal>
- to install a Seam managed <literal>TopicPublisher</literal>s and
+ to install Seam managed <literal>TopicPublisher</literal>s and
<literal>QueueSender</literal>s:
</para>
1.74 +1 -1 jboss-seam/doc/reference/en/modules/tutorial.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: tutorial.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/tutorial.xml,v
retrieving revision 1.73
retrieving revision 1.74
diff -u -b -r1.73 -r1.74
--- tutorial.xml 27 Nov 2006 03:28:17 -0000 1.73
+++ tutorial.xml 29 Nov 2006 10:28:03 -0000 1.74
@@ -526,7 +526,7 @@
<para>
This code configures a property named <literal>jndiPattern</literal> of a built-in
- Seam <literal>init</literal> component, which happens to be named <literal>org.jboss.seam.core.init</literal>.
+ Seam component named <literal>org.jboss.seam.core.init</literal>.
</para>
</section>
More information about the jboss-cvs-commits
mailing list