[jboss-cvs] jboss-seam/doc/reference/en/modules ...
Norman Richards
norman.richards at jboss.com
Sun Nov 26 22:28:17 EST 2006
User: nrichards
Date: 06/11/26 22:28:17
Modified: doc/reference/en/modules concepts.xml
configuration.xml drools.xml framework.xml i18n.xml
jms.xml remoting.xml tutorial.xml
Log:
update for namespaces
Revision Changes Path
1.42 +976 -1138 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.41
retrieving revision 1.42
diff -u -b -r1.41 -r1.42
--- concepts.xml 20 Nov 2006 20:14:27 -0000 1.41
+++ concepts.xml 27 Nov 2006 03:28:16 -0000 1.42
@@ -1,472 +1,320 @@
<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 <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>
+ <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>
<sect1>
<title>Seam contexts</title>
- <para>
- Seam contexts are created and destroyed by the framework. The application does not
- control context demarcation via explicit Java API calls. Context are usually implicit.
- In some cases, however, contexts are demarcated via annotations.
- </para>
- <para>
- The basic Seam contexts are:
- </para>
+ <para> Seam contexts are created and destroyed by the framework. The application does not control context
+ demarcation via explicit Java API calls. Context are usually implicit. In some cases, however, contexts are
+ demarcated via annotations. </para>
+ <para> The basic Seam contexts are: </para>
<itemizedlist>
<listitem>
- <para>
- Stateless context
- </para>
+ <para> Stateless context </para>
</listitem>
<listitem>
- <para>
- Event (or request) context
- </para>
+ <para> Event (or request) context </para>
</listitem>
<listitem>
- <para>
- Page context
- </para>
+ <para> Page context </para>
</listitem>
<listitem>
- <para>
- Conversation context
- </para>
+ <para> Conversation context </para>
</listitem>
<listitem>
- <para>
- Session context
- </para>
+ <para> Session context </para>
</listitem>
<listitem>
- <para>
- Business process context
- </para>
+ <para> Business process context </para>
</listitem>
<listitem>
- <para>
- Application context
- </para>
+ <para> Application context </para>
</listitem>
</itemizedlist>
- <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>
+ <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>
- <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
- 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>
+ <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>
</sect2>
<sect2>
<title>Event context</title>
- <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>
+ <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>
</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 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>
+ <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>
</sect2>
<sect2>
<title>Conversation context</title>
- <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
- 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
- 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
+ <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
+ 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
+ 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
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 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>
+ 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>
</sect2>
<sect2>
<title>Session context</title>
- <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>
+ <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>
</sect2>
<sect2>
<title>Business process context</title>
- <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>
+ <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>
</sect2>
<sect2>
<title>Application context</title>
- <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>
+ <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>
</sect2>
<sect2>
<title>Context variables</title>
- <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>
-
- <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>
+ <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>
+
+ <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>
<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>
- <para>
- Event context
- </para>
+ <para> Event context </para>
</listitem>
<listitem>
- <para>
- Page context
- </para>
+ <para> Page context </para>
</listitem>
<listitem>
- <para>
- Conversation context
- </para>
+ <para> Conversation context </para>
</listitem>
<listitem>
- <para>
- Session context
- </para>
+ <para> Session context </para>
</listitem>
<listitem>
- <para>
- Business process context
- </para>
+ <para> Business process context </para>
</listitem>
<listitem>
- <para>
- Application context
- </para>
+ <para> Application context </para>
</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
- 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 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 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 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>
+ <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
+ 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
+ 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
+ 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>
</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
- 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>
+ <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>
<itemizedlist>
<listitem>
- <para>
- EJB 3.0 stateless session beans
- </para>
+ <para> EJB 3.0 stateless session beans </para>
</listitem>
<listitem>
- <para>
- EJB 3.0 stateful session beans
- </para>
+ <para> EJB 3.0 stateful session beans </para>
</listitem>
<listitem>
- <para>
- EJB 3.0 entity beans
- </para>
+ <para> EJB 3.0 entity beans </para>
</listitem>
<listitem>
- <para>
- JavaBeans
- </para>
+ <para> JavaBeans </para>
</listitem>
<listitem>
- <para>
- EJB 3.0 message-driven beans
- </para>
+ <para> EJB 3.0 message-driven beans </para>
</listitem>
</itemizedlist>
<sect2>
<title>Stateless session beans</title>
- <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>
+ <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>
</sect2>
<sect2>
<title>Stateful session beans</title>
- <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>
+ <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>
</sect2>
<sect2>
<title>Entity beans</title>
- <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 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>
- <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 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>
+ <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
+ 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>
+ <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
+ 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>
</sect2>
<sect2>
<title>JavaBeans</title>
- <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 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>
+ <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
+ 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>
</sect2>
<sect2>
<title>Message-driven beans</title>
- <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 conversation state of their "caller". However, they do support bijection
- and some other Seam functionality.
- </para>
+ <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
+ conversation state of their "caller". However, they do support bijection and some other Seam
+ functionality. </para>
</sect2>
<sect2>
<title>Interception</title>
- <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>
+ <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>
<programlisting><![CDATA[@Stateless
@Interceptors(SeamInterceptor.class)
@@ -474,9 +322,7 @@
...
}]]></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>
@@ -495,10 +341,8 @@
<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
@@ -506,31 +350,22 @@
...
}]]></programlisting>
- <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>
-
- <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. However, again like JSF, it is possible for the application
- to bind a component to some other context variable by programmatic API call. This is
- only useful if a particular component serves more than one 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>
+ <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>
+
+ <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.
+ However, again like JSF, it is possible for the application to bind a component to some other context
+ variable by programmatic API call. This is only useful if a particular component serves more than one
+ 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>
- <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
@@ -539,36 +374,27 @@
...
}]]></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>
- annotation. This lets us define what context a component instance is bound to, when it is
- instantiated by Seam.
- </para>
+ <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>
<programlisting><![CDATA[@Name("user")
@Entity
@@ -578,23 +404,19 @@
}]]></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 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>
+ <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>
<programlisting><![CDATA[@Name("user")
@Entity
@@ -604,10 +426,7 @@
...
}]]></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
@@ -622,43 +441,28 @@
<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 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>
+ <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>
<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 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 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 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 via the built-in component
- <literal>org.jboss.seam.core.microcontainer</literal>.
- This lets you use the bulletproof JTA/JCA pooling datasource from JBoss application
- server in an SE environment like Tomcat!
+ <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
+ 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
+ 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
+ via the built-in component <literal>org.jboss.seam.core.microcontainer</literal>. This lets you use the
+ bulletproof JTA/JCA pooling datasource from JBoss application server in an SE environment like Tomcat!
</para>
</sect2>
@@ -667,107 +471,99 @@
<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>
+ <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>
+ <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>
+ <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 (this is the case for certain
- built-in components).
- </para></listitem>
- <listitem><para>
- Override the scope of a component.
- </para></listitem>
+ <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>
+ <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>
+ <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. The <literal>components.xml</literal>
- file lets us handle special cases where that is not the case.
- </para>
+ <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>
+ <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>
- <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>
- <programlisting><![CDATA[<components>
+ <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>
@@ -777,16 +573,17 @@
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>
+ <para> This example creates a session-scoped Seam-managed persistence context (this is not recommended in
+ practice): </para>
- <programlisting><![CDATA[<components>
+ <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">
@@ -795,11 +592,9 @@
</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>
+ <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>
@@ -807,9 +602,7 @@
</components>]]></programlisting>
- <para>
- You can create an "alias" (a second name) for a Seam component like so:
- </para>
+ <para> You can create an "alias" (a second name) for a Seam component like so: </para>
<programlisting><![CDATA[<components>
@@ -817,9 +610,7 @@
</components>]]></programlisting>
- <para>
- You can even create an "alias" for a commonly used expression:
- </para>
+ <para> You can even create an "alias" for a commonly used expression: </para>
<programlisting><![CDATA[<components>
@@ -827,34 +618,25 @@
</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>
+ <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> 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>
+ <para> The first option lets you define multiple components in the file: </para>
<programlisting><![CDATA[<components>
<component class="com.helloworld.Hello" name="hello">
@@ -863,46 +645,45 @@
<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>
+ <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> 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>
+ <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>
+ <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>
+ <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>
@@ -911,9 +692,7 @@
</property>
</component>]]></programlisting>
- <para>
- Even maps with String-valued keys and string or primitive values are supported:
- </para>
+ <para> Even maps with String-valued keys and string or primitive values are supported: </para>
<programlisting><![CDATA[<component name="issueEditor">
<property name="issueStatuses">
@@ -923,13 +702,13 @@
</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>
+ <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">
@@ -938,60 +717,196 @@
</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>
<title>Bijection</title>
<para>
- <emphasis>Dependency injection</emphasis> or <emphasis>inversion of control</emphasis> is by now
- a familiar concept to most Java developers. Dependency injection allows a component to obtain a
- reference to another component by having the container "inject" the other component to a setter
- method or instance variable. In all dependency injection implementations that we have seen,
- injection occurs when the component is constructed, and the reference does not subsequently
- change for the lifetime of the component instance. For 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>Dependency injection</emphasis> or <emphasis>inversion of control</emphasis> is by now a familiar
+ concept to most Java developers. Dependency injection allows a component to obtain a reference to another
+ component by having the container "inject" the other component to a setter method or instance variable. In
+ all dependency injection implementations that we have seen, injection occurs when the component is
+ constructed, and the reference does not subsequently change for the lifetime of the component instance. For
+ 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>
<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>
+ <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>
</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>
+ <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>
</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>
+ <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>
</listitem>
</itemizedlist>
- <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>
+ <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>
- <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
@@ -1001,9 +916,7 @@
...
}]]></programlisting>
- <para>
- or into a setter method:
- </para>
+ <para> or into a setter method: </para>
<programlisting><![CDATA[@Name("loginAction")
@Stateless
@@ -1020,21 +933,15 @@
}]]></programlisting>
- <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>
+ <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>
+
+ <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>
- <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>
-
- <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
@@ -1044,14 +951,10 @@
...
}]]></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
@@ -1061,9 +964,7 @@
...
}]]></programlisting>
- <para>
- or from a getter method:
- </para>
+ <para> or from a getter method: </para>
<programlisting><![CDATA[@Name("loginAction")
@Stateless
@@ -1079,9 +980,7 @@
...
}]]></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
@@ -1091,9 +990,7 @@
...
}]]></programlisting>
- <para>
- or:
- </para>
+ <para> or: </para>
<programlisting><![CDATA[@Name("loginAction")
@Stateless
@@ -1118,40 +1015,27 @@
<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).
- 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 <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>
+ <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
+ <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>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);
@@ -1164,17 +1048,12 @@
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 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>
+ <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>
- <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;
@@ -1183,17 +1062,13 @@
return new Order(user, product, quantity);
}]]></programlisting>
- <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>
+ <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>
- <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;
@@ -1206,35 +1081,25 @@
<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> 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>
-
- <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>
-
- <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>
+ <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>
+
+ <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>
+
+ <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>
<programlisting><![CDATA[@Name("account")
public class Account extends AbstractMutable
@@ -1256,10 +1121,7 @@
}]]></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
@@ -1282,13 +1144,10 @@
}]]></programlisting>
- <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>
+ <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>
<programlisting><![CDATA[@Stateful
@Name("account")
@@ -1306,44 +1165,33 @@
}]]></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 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>
+ <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>
+ <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;
@@ -1352,22 +1200,15 @@
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>
+ <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")
@Scope(CONVERSATION)
@@ -1381,12 +1222,9 @@
}
}]]></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>
+ <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>
1.30 +624 -635 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.29
retrieving revision 1.30
diff -u -b -r1.29 -r1.30
--- configuration.xml 20 Nov 2006 19:56:49 -0000 1.29
+++ configuration.xml 27 Nov 2006 03:28:16 -0000 1.30
@@ -121,9 +121,7 @@
For JBoss AS, the following pattern is correct:
</para>
- <programlisting><![CDATA[<component name="org.jboss.seam.core.init">
- <property name="jndiPattern">myEarName/#{ejbName}/local</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<core:init jndi-name="myEarName/#{ejbName}/local" />]]></programlisting>
<para>
Or:
@@ -145,9 +143,7 @@
the one to use:
</para>
- <programlisting><![CDATA[<component name="org.jboss.seam.core.init">
- <property name="jndiPattern">#{ejbName}/local</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<core:init jndi-name="#{ejbName}/local" />]]></programlisting>
<para>
Or:
@@ -315,7 +311,7 @@
following line to <literal>components.xml</literal>:
</para>
- <programlisting><![CDATA[<component class="org.jboss.seam.core.Ejb"/>]]></programlisting>
+ <programlisting><![CDATA[<core:ejb />]]></programlisting>
<para>
This setting installs the built-in component named <literal>org.jboss.seam.core.ejb</literal>.
@@ -529,10 +525,8 @@
<literal>components.xml</literal>, we can write:
</para>
- <programlisting><![CDATA[<component name="bookingDatabase" auto-create="true"
- class="org.jboss.seam.core.ManagedPersistenceContext">
- <property name="persistenceUnitJndiName">java:/EntityManagerFactories/bookingData</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<core:managed-persistence-context name="bookingDatabase" auto-create="true"
+ persistence-unit-jndi-name="java:/EntityManagerFactories/bookingData"/>]]></programlisting>
<para>
This configuration creates a conversation-scoped Seam component named
@@ -618,13 +612,10 @@
To configure our Seam component, as usual, we use <literal>components.xml</literal>:
</para>
- <programlisting><![CDATA[<component name="hibernateSessionFactory"
- class="org.jboss.seam.core.HibernateSessionFactory"/>
+ <programlisting><![CDATA[<core:managed-hibernate-session name="hibernateSessionFactory"/>
-<component name="bookingDatabase" auto-create="true"
- class="org.jboss.seam.core.ManagedHibernateSession">
- <property name="sessionFactoryJndiName">java:/bookingSessionFactory</property>
-</component>]]></programlisting>
+<core:managed-hibernate-session name="bookingDatabase" auto-create="true"
+ session-factory-jndi-name="java:/bookingSessionFactory"/>]]></programlisting>
<para>
Where <literal>java:/bookingSessionFactory</literal> is the name of the session factory
@@ -737,12 +728,10 @@
bootstraps the microcontainer. As before, we probably want to use a Seam managed session.
</para>
- <programlisting><![CDATA[<component class="org.jboss.seam.core.Microcontainer"/>
+ <programlisting><![CDATA[<core:microcontainer/>
-<component name="bookingDatabase" auto-create="true"
- class="org.jboss.seam.core.ManagedHibernateSession">
- <property name="sessionFactoryJndiName">java:/bookingSessionFactory</property>
-</component>]]></programlisting>
+<core:managed-hibernate-session name="bookingDatabase" auto-create="true"
+ session-factory-jndi-name="java:/bookingSessionFactory"/>]]></programlisting>
<para>
Where <literal>java:/bookingSessionFactory</literal> is the name of the Hibernate session
@@ -855,16 +844,16 @@
<literal>components.xml</literal>:
</para>
- <programlisting><![CDATA[<component class="org.jboss.seam.core.Jbpm">
- <property name="pageflowDefinitions">
- createDocument.jpdl.xml
- editDocument.jpdl.xml
- approveDocument.jpdl.xml
- </property>
- <property name="processDefinitions">
- documentLifecycle.jpdl.xml
- </property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<core:jbpm>
+ <core:pageflow-definitions>
+ <value>createDocument.jpdl.xml</value>
+ <value>editDocument.jpdl.xml</value>
+ <value>approveDocument.jpdl.xml</value>
+ </core:pageflow-definitions>
+ <core:process-definitions>
+ <value>documentLifecycle.jpdl.xml</value>
+ </core:process-definitions>
+</core:jbpm>]]></programlisting>
<para>
No further special configuration is needed if you only have pageflows.
1.12 +184 -186 jboss-seam/doc/reference/en/modules/drools.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: drools.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/drools.xml,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -b -r1.11 -r1.12
--- drools.xml 20 Nov 2006 19:24:19 -0000 1.11
+++ drools.xml 27 Nov 2006 03:28:16 -0000 1.12
@@ -20,10 +20,11 @@
this component via <literal>components.xml</literal>:
</para>
- <programlisting><![CDATA[<component name="policyPricingRules"
- class="org.jboss.seam.drools.RuleBase">
- <property name="ruleFiles">policyPricingRules.drl</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<drools:rule-base name="policyPricingRules">
+ <drools:rule-files>
+ <value>policyPricingRules</value>
+ </drools:rule-files>
+</drools:rule-base>]]></programlisting>
<para>
This component compiles rules from a set of <literal>.drl</literal>
@@ -38,11 +39,11 @@
definition:
</para>
- <programlisting><![CDATA[<component name="policyPricingRules"
- class="org.jboss.seam.drools.RuleBase">
- <property name="ruleFiles">policyPricingRules.drl</property>
- <property name="dslFile">policyPricing.dsl</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<drools:rule-base name="policyPricingRules" dsl-file="policyPricing.dsl">
+ <drools:rule-files>
+ <value>policyPricingRules</value>
+ </drools:rule-files>
+</drools:rule-base>]]></programlisting>
<para>
Next, we need to make an instance of <literal>org.drools.WorkingMemory</literal>
@@ -50,10 +51,7 @@
accumulates facts relating to the current conversation.)
</para>
- <programlisting><![CDATA[<component name="policyPricingWorkingMemory" auto-create="true"
- class="org.jboss.seam.drools.ManagedWorkingMemory">
- <property name="ruleBase">#{policyPricingRules}</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<drools:managed-working-memory name="policyPricingMemory" auto-create="true" rule-base="#{policyPricingRules}"/>]]></programlisting>
<para>
Notice that we gave the <literal>policyPricingWorkingMemory</literal> a
1.9 +494 -515 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.8
retrieving revision 1.9
diff -u -b -r1.8 -r1.9
--- framework.xml 21 Nov 2006 16:20:13 -0000 1.8
+++ framework.xml 27 Nov 2006 03:28:16 -0000 1.9
@@ -40,11 +40,9 @@
<literal>Contact</literal> entity:
</para>
- <programlisting><![CDATA[<component name="personHome" class="org.jboss.seam.framework.EntityHome">
- <property name="entityClass">eg.Person</property>
- <property name="id">#{param.personId}</property>
- <property name="entityManager">#{personDatabase}</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<framework:entity-home name="personHome" entity-class="eg.Person" entity-manager="#{personDatabase}">
+ <framework:id>#{param.personId}</framework:id>
+</framework:entity-home>]]></programlisting>
<para>
If that looks a bit too much like "programming in XML" for
@@ -120,9 +118,7 @@
configuration:
</para>
- <programlisting><![CDATA[<component name="personHome" class="org.jboss.seam.framework.EntityHome">
- <property name="entityClass">eg.Person</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<framework:entity-home name="personHome" entity-class="eg.Person" />]]></programlisting>
<para>
Or via extension:
@@ -161,9 +157,7 @@
<programlisting><![CDATA[<factory name="person" value="#{personHome.instance}"/>
-<component name="personHome" class="org.jboss.seam.framework.EntityHome">
- <property name="entityClass">eg.Person</property>
-</component>]]></programlisting>
+<framework:entity-home name="personHome" entity-class="eg.Person" />]]></programlisting>
<para>
(If we are using configuration.)
@@ -239,10 +233,7 @@
<programlisting><![CDATA[<factory name="person" value="#{personHome.instance}"/>
-<component name="personHome" class="org.jboss.seam.framework.EntityHome">
- <property name="entityClass">eg.Person</property>
- <property name="newInstance">#{newPerson}</property>
-</component>
+<framework:entity-home name="personHome" entity-class="eg.Person" new-instance="#{newPerson}"/>
<component name="newPerson" class="eg.Person">
<property name="nationality">#{country}</property>
@@ -303,13 +294,12 @@
<programlisting><![CDATA[<factory name="person" value="#{personHome.instance}"/>
-<component name="personHome" class="org.jboss.seam.framework.EntityHome">
- <property name="entityClass">eg.Person</property>
- <property name="newInstance">#{newPerson}</property>
- <property name="createdMessage">New person #{person.firstName} #{person.lastName} created</property>
- <property name="deletedMessage">Person #{person.firstName} #{person.lastName} deleted</property>
- <property name="updatedMessage">Person #{person.firstName} #{person.lastName} updated</property>
-</component>
+<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"/>
<component name="newPerson" class="eg.Person">
<property name="nationality">#{country}</property>
@@ -368,9 +358,7 @@
can use a Query object. For example:
</para>
- <programlisting><![CDATA[<component name="people" class="org.jboss.seam.framework.EntityQuery">
- <property name="ejbql">select p from Person p</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<framework:entity-query name="people" eqbql="select p from Person p"/>]]></programlisting>
<para>
We can use it from a JSF page:
@@ -389,11 +377,7 @@
We probably need to support pagination:
</para>
- <programlisting><![CDATA[<component name="people" class="org.jboss.seam.framework.EntityQuery">
- <property name="ejbql">select p from Person p</property>
- <property name="order">lastName</property>
- <property name="maxResults">20</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<framework:entity-query name="people" eqbql="select p from Person p" order="lastName" max-results="20"/>]]></programlisting>
<para>
The JSF code for a pagination control is a bit verbose, but manageable:
@@ -432,15 +416,12 @@
<programlisting><![CDATA[<component name="examplePerson" class="Person"/>
-<component name="people" class="org.jboss.seam.framework.EntityQuery">
- <property name="ejbql">select p from Person p</property>
- <property name="order">lastName</property>
- <property name="maxResults">20</property>
- <restrictions>
+<framework:entity-query name="people" eqbql="select p from Person p" order="lastName" max-results="20">
+ <framework:restrictions>
<value>lower(firstName) like lower( #{examplePerson.firstName} + '%' )</value>
<value>lower(lastName) like lower( #{examplePerson.lastName} + '%' )</value>
- </restriction>
-</component>]]></programlisting>
+ </framework:restrictions>
+</framework:entity-query>]]></programlisting>
<para>
Notice the use of an "example" object.
@@ -486,31 +467,29 @@
persistence provider.)
</para>
- <programlisting><![CDATA[<component name="regionFilter"
- class="org.jboss.seam.core.Filter">
- <property name="name">region</property>
- <property name="parameters">
- <key>regionCode</key><value>#{region.code}</value>
- </property>
-</component>
-
-<component name="currentFilter"
- class="org.jboss.seam.core.Filter">
- <property name="name">current</property>
- <property name="parameters">
- <key>date</key><value>#{currentDate}</value>
- </property>
-</component>
-
-<component name="personDatabase"
- class="org.jboss.seam.core.ManagedPersistenceContext">
- <property name="persistenceUnitJndiName">java:/EntityManagerFactories/personDatabase</property>
- <property name="filters">
+ <programlisting><![CDATA[<core:filter name="regionFilter">
+ <core:name>region</core:name>
+ <core:parameters>
+ <key>regionCode</key>
+ <value>#{region.code}</value>
+ </core:parameters>
+</core:filter>
+
+<core:filter name="currentFilter">
+ <core:name>current</core:name>
+ <core:parameters>
+ <key>date</key>
+ <value>#{currentDate}</value>
+ </core:parameters>
+</core:filter>
+
+<core:managed-persistence-context name="personDatabase"
+ persistence-unit-jndi-name="java:/EntityManagerFactories/personDatabase">
+ <core:filters>
<value>#{regionFilter}</value>
<value>#{currentFilter}</value>
- </property>
-</component>]]></programlisting>
+ </core:filters>
+</core:managed-persistence-context>]]></programlisting>
</section>
-
</chapter>
\ No newline at end of file
1.14 +318 -321 jboss-seam/doc/reference/en/modules/i18n.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: i18n.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/i18n.xml,v
retrieving revision 1.13
retrieving revision 1.14
diff -u -b -r1.13 -r1.14
--- i18n.xml 26 Nov 2006 21:35:12 -0000 1.13
+++ i18n.xml 27 Nov 2006 03:28:16 -0000 1.14
@@ -125,12 +125,12 @@
messages.
</para>
- <programlisting><![CDATA[<component name="org.jboss.seam.core.resourceBundle">
- <property name="bundleNames">
+ <programlisting><![CDATA[<core:resource-bundle>
+ <core:bundle-names>
<value>mycompany_messages</value>
<value>standard_messages</value>
- </property>
-</component>]]></programlisting>
+ </core:bundle-names>
+</core:resource-bundle>]]></programlisting>
<para>
If you want to define a message just for a particular page, you
@@ -242,13 +242,13 @@
First, configure the set of supported themes:
</para>
- <programlisting><![CDATA[<component name="org.jboss.seam.theme.themeSelector">
- <property name="availableThemes">
+ <programlisting><![CDATA[<theme:theme-selector cookie-enabled="true">
+ <theme:available-themes>
<value>default</value>
<value>accessible</value>
<value>printable</value>
- </property>
-</component>]]></programlisting>
+ </theme:available-themes>
+</theme:theme-selector>]]></programlisting>
<para>
Note that the first theme listed is the default theme.
@@ -304,21 +304,18 @@
<para>
The locale selector, theme selector and timezone selector all support
persistence of locale and theme preference to a cookie. Simply set the
- <literal>cookieEnabled</literal> configuration property:
+ <literal>cookie-enabled</literal> configuration property:
</para>
- <programlisting><![CDATA[<component name="org.jboss.seam.theme.themeSelector">
- <property name="availableThemes">
+ <programlisting><![CDATA[<theme:theme-selector cookie-enabled="true">
+ <theme:available-themes>
<value>default</value>
<value>accessible</value>
<value>printable</value>
- </property>
- <property name="cookieEnabled">true</property>
-</component>
-
-<component name="localeSelector">
- <property name="cookieEnabled">true</property>
-</component>]]></programlisting>
+ </theme:available-themes>
+</theme:theme-selector>
+
+<core:locale-selector cookie-enabled="true"/>]]></programlisting>
</section>
1.10 +298 -304 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.9
retrieving revision 1.10
diff -u -b -r1.9 -r1.10
--- jms.xml 20 Nov 2006 19:24:19 -0000 1.9
+++ jms.xml 27 Nov 2006 03:28:17 -0000 1.10
@@ -28,7 +28,7 @@
<literal>components.xml</literal>:
</para>
- <programlisting><![CDATA[<component class="org.jboss.seam.core.Dispatcher"/>]]></programlisting>
+ <programlisting><![CDATA[<core:dispatcher/>]]></programlisting>
<para>
Note that this functionality is not available in environments which do not support EJB 3.0.
@@ -230,15 +230,9 @@
<literal>QueueSender</literal>s:
</para>
- <programlisting><![CDATA[<component name="stockTickerPublisher" auto-create="true"
- class="org.jboss.seam.jms.ManagedTopicPublisher">
- <property name="topicJndiName">topic/stockTickerTopic</property>
-</component>
-
-<component name="paymentQueueSender" auto-create="true"
- class="org.jboss.seam.jms.ManagedQueueSender">
- <property name="queueJndiName">queue/paymentQueue</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<jms:managed-topic-publisher name="stockTickerPublisher" auto-create="true" topic-jndi-name="topic/stockTickerTopic"/>
+
+<jms:managed-queue-sender name="paymentQueueSender" auto-create="true" queue-jndi-name="queue/paymentQueue"/>]]></programlisting>
</sect2>
1.18 +557 -728 jboss-seam/doc/reference/en/modules/remoting.xml
(In the diff below, changes in quantity of whitespace are not shown.)
Index: remoting.xml
===================================================================
RCS file: /cvsroot/jboss/jboss-seam/doc/reference/en/modules/remoting.xml,v
retrieving revision 1.17
retrieving revision 1.18
diff -u -b -r1.17 -r1.18
--- remoting.xml 6 Aug 2006 13:59:20 -0000 1.17
+++ remoting.xml 27 Nov 2006 03:28:17 -0000 1.18
@@ -1,20 +1,14 @@
<chapter id="remoting">
<title>Remoting</title>
- <para>
- Seam provides a convenient method of remotely accessing components from a web page, using
- AJAX (Asynchronous Javascript and XML). The framework for this functionality is provided
- with almost no up-front development effort - your components only require simple annotating
- to become accessible via AJAX. This chapter describes the steps required to build an
- AJAX-enabled web page, then goes on to explain the features of the Seam Remoting framework in
- more detail.
- </para>
+ <para> Seam provides a convenient method of remotely accessing components from a web page, using AJAX (Asynchronous
+ Javascript and XML). The framework for this functionality is provided with almost no up-front development effort -
+ your components only require simple annotating to become accessible via AJAX. This chapter describes the steps
+ required to build an AJAX-enabled web page, then goes on to explain the features of the Seam Remoting framework in
+ more detail. </para>
<sect1>
<title>Configuration</title>
- <para>
- To use remoting, the Seam Remoting servlet must first be configured in your
- <literal>web.xml</literal> file:
- </para>
+ <para> To use remoting, the Seam Remoting servlet must first be configured in your <literal>web.xml</literal> file: </para>
<programlisting>
<![CDATA[
@@ -30,11 +24,9 @@
]]>
</programlisting>
- <para>
- The next step is to import the necessary Javascript into your web page. There are a minimum
- of two scripts that must be imported. The first one contains all the client-side framework
- code that enables remoting functionality:
- </para>
+ <para> The next step is to import the necessary Javascript into your web page. There are a minimum of two scripts
+ that must be imported. The first one contains all the client-side framework code that enables remoting
+ functionality: </para>
<programlisting>
<![CDATA[
@@ -42,14 +34,11 @@
]]>
</programlisting>
- <para>
- The second script contains the stubs and type definitions for the components you wish to call.
- It is generated dynamically based on the local interface of your components, and includes
- type definitions for all of the classes that can be used to call the remotable methods of the interface.
- The name of the script reflects the name of your component. For example, if you have a stateless
- session bean annotated with <literal>@Name("customerAction")</literal>, then your script tag
- should look like this:
- </para>
+ <para> The second script contains the stubs and type definitions for the components you wish to call. It is
+ generated dynamically based on the local interface of your components, and includes type definitions for all of
+ the classes that can be used to call the remotable methods of the interface. The name of the script reflects the
+ name of your component. For example, if you have a stateless session bean annotated with
+ <literal>@Name("customerAction")</literal>, then your script tag should look like this: </para>
<programlisting>
<![CDATA[
@@ -57,9 +46,8 @@
]]>
</programlisting>
- <para>
- If you wish to access more than one component from the same page, then include them all as parameters of your script tag:
- </para>
+ <para> If you wish to access more than one component from the same page, then include them all as parameters of your
+ script tag: </para>
<programlisting>
<![CDATA[
@@ -72,23 +60,17 @@
<sect1>
<title>The "Seam" object</title>
- <para>
- Client-side interaction with your components is all performed via the <literal>Seam</literal>
- Javascript object. This object is defined in <literal>remote.js</literal>, and you'll be using it to
- make asynchronous calls against your component. It is split into two areas of functionality;
- <literal>Seam.Component</literal> contains methods for working with components and
- <literal>Seam.Remoting</literal> contains methods for
- executing remote requests. The easiest way to become familiar with this object is to start with a
- simple example.
- </para>
+ <para> Client-side interaction with your components is all performed via the <literal>Seam</literal> Javascript
+ object. This object is defined in <literal>remote.js</literal>, and you'll be using it to make asynchronous calls
+ against your component. It is split into two areas of functionality; <literal>Seam.Component</literal> contains
+ methods for working with components and <literal>Seam.Remoting</literal> contains methods for executing remote
+ requests. The easiest way to become familiar with this object is to start with a simple example. </para>
<sect2>
<title>A Hello World example</title>
- <para>
- Let's step through a simple example to see how the <literal>Seam</literal> object works.
- First of all, let's create a new Seam component called <literal>helloAction</literal>.
- </para>
+ <para> Let's step through a simple example to see how the <literal>Seam</literal> object works. First of all,
+ let's create a new Seam component called <literal>helloAction</literal>. </para>
<programlisting>
<![CDATA[
@@ -115,10 +97,8 @@
]]>
</programlisting>
- <para>
- That's all the server-side code we need to write. Now for our web page - create a new page and
- import the following scripts:
- </para>
+ <para> That's all the server-side code we need to write. Now for our web page - create a new page and import the
+ following scripts: </para>
<programlisting>
<![CDATA[
@@ -127,9 +107,7 @@
]]>
</programlisting>
- <para>
- To make this a fully interactive user experience, let's add a button to our page:
- </para>
+ <para> To make this a fully interactive user experience, let's add a button to our page: </para>
<programlisting>
<![CDATA[
@@ -137,9 +115,7 @@
]]>
</programlisting>
- <para>
- We'll also need to add some more script to make our button actually do something when it's clicked:
- </para>
+ <para> We'll also need to add some more script to make our button actually do something when it's clicked: </para>
<programlisting>
<![CDATA[
@@ -160,67 +136,52 @@
]]>
</programlisting>
- <para>
- We're done! Deploy your application and browse to your page. Click the button, and enter
- a name when prompted. A message box will display the hello message confirming that the call
- was successful. If you want to save some time, you'll find the full source code for this
- Hello World example in Seam's <literal>/examples/remoting/helloworld</literal> directory.
- </para>
+ <para> We're done! Deploy your application and browse to your page. Click the button, and enter a name when
+ prompted. A message box will display the hello message confirming that the call was successful. If you want to
+ save some time, you'll find the full source code for this Hello World example in Seam's
+ <literal>/examples/remoting/helloworld</literal> directory. </para>
- <para>
- So what does the code of our script actually do? Let's break it down into smaller pieces. To start with,
+ <para> So what does the code of our script actually do? Let's break it down into smaller pieces. To start with,
you can see from the Javascript code listing that we have implemented two methods - the first method is
- responsible for prompting the user for their name and then making a remote request. Take a look at the
- following line:
- </para>
+ responsible for prompting the user for their name and then making a remote request. Take a look at the following
+ line: </para>
<programlisting>
Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);
</programlisting>
- <para>
- The first section of this line, <literal>Seam.Component.getInstance("helloAction")</literal> returns a
- proxy, or "stub" for our <literal>helloAction</literal> component. We can invoke the methods of our
- component against this stub, which is exactly what happens with the remainder of the line:
- <literal>sayHello(name, sayHelloCallback);</literal>.
- </para>
+ <para> The first section of this line, <literal>Seam.Component.getInstance("helloAction")</literal> returns a
+ proxy, or "stub" for our <literal>helloAction</literal> component. We can invoke the methods of our component
+ against this stub, which is exactly what happens with the remainder of the line: <literal>sayHello(name,
+ sayHelloCallback);</literal>. </para>
- <para>
- What this line of code in its completeness does, is invoke the <literal>sayHello</literal> method of our
+ <para> What this line of code in its completeness does, is invoke the <literal>sayHello</literal> method of our
component, passing in <literal>name</literal> as a parameter. The second parameter,
- <literal>sayHelloCallback</literal> isn't a parameter of our component's <literal>sayHello</literal>
- method, instead it tells the Seam Remoting framework that once it receives the response to our request,
- it should pass it to the <literal>sayHelloCallback</literal> Javascript method. This callback parameter
- is entirely optional, so feel free to leave it out if you're calling a method with a <literal>void</literal>
- return type or if you don't care about the result.
- </para>
+ <literal>sayHelloCallback</literal> isn't a parameter of our component's <literal>sayHello</literal> method,
+ instead it tells the Seam Remoting framework that once it receives the response to our request, it should pass
+ it to the <literal>sayHelloCallback</literal> Javascript method. This callback parameter is entirely optional,
+ so feel free to leave it out if you're calling a method with a <literal>void</literal> return type or if you
+ don't care about the result. </para>
- <para>
- The <literal>sayHelloCallback</literal> method, once receiving the response to our remote request
- then pops up an alert message displaying the result of our method call.
- </para>
+ <para> The <literal>sayHelloCallback</literal> method, once receiving the response to our remote request then pops
+ up an alert message displaying the result of our method call. </para>
</sect2>
<sect2>
<title>Seam.Component</title>
- <para>
- The <literal>Seam.Component</literal> Javascript object provides a number of client-side methods for working with
- your Seam components. The two main methods, <literal>newInstance()</literal> and <literal>getInstance()</literal>
- are documented in the following sections however their main difference is that <literal>newInstance()</literal>
- will always create a new instance of a component type, and <literal>getInstance()</literal> will return a
- singleton instance.
- </para>
+ <para> The <literal>Seam.Component</literal> Javascript object provides a number of client-side methods for
+ working with your Seam components. The two main methods, <literal>newInstance()</literal> and
+ <literal>getInstance()</literal> are documented in the following sections however their main difference is
+ that <literal>newInstance()</literal> will always create a new instance of a component type, and
+ <literal>getInstance()</literal> will return a singleton instance. </para>
<sect3>
<title>Seam.Component.newInstance()</title>
- <para>
- Use this method to create a new instance of an entity or Javabean component. The object returned
- by this method will have the same getter/setter methods as its server-side counterpart, or
- alternatively if you wish you can access its fields directly.
- Take the following Seam entity component for example:
- </para>
+ <para> Use this method to create a new instance of an entity or Javabean component. The object returned by this
+ method will have the same getter/setter methods as its server-side counterpart, or alternatively if you wish
+ you can access its fields directly. Take the following Seam entity component for example: </para>
<programlisting>
@Name("customer")
@@ -257,17 +218,13 @@
}
</programlisting>
- <para>
- To create a client-side Customer you would write the following code:
- </para>
+ <para> To create a client-side Customer you would write the following code: </para>
<programlisting>
var customer = Seam.Component.newInstance("customer");
</programlisting>
- <para>
- Then from here you can set the fields of the customer object:
- </para>
+ <para> Then from here you can set the fields of the customer object: </para>
<programlisting>
customer.setFirstName("John");
@@ -280,18 +237,14 @@
<sect3>
<title>Seam.Component.getInstance()</title>
- <para>
- The <literal>getInstance()</literal> method is used to get a reference to a Seam session
- bean component stub, which can then be used to remotely execute methods against your
- component. This method returns a singleton for the specified component, so calling it twice
- in a row with the same component name will return the same instance of the component.
- </para>
-
- <para>
- To continue our example from before, if we have created a new <literal>customer</literal> and
- we now wish to save it, we would pass it to the <literal>saveCustomer()</literal> method of our
- <literal>customerAction</literal> component:
- </para>
+ <para> The <literal>getInstance()</literal> method is used to get a reference to a Seam session bean component
+ stub, which can then be used to remotely execute methods against your component. This method returns a
+ singleton for the specified component, so calling it twice in a row with the same component name will return
+ the same instance of the component. </para>
+
+ <para> To continue our example from before, if we have created a new <literal>customer</literal> and we now wish
+ to save it, we would pass it to the <literal>saveCustomer()</literal> method of our
+ <literal>customerAction</literal> component: </para>
<programlisting>
Seam.Component.getInstance("customerAction").saveCustomer(customer);
@@ -301,10 +254,8 @@
<sect3>
<title>Seam.Component.getComponentName()</title>
- <para>
- Passing an object into this method will return its component name if it is a component, or
- <literal>null</literal> if it is not.
- </para>
+ <para> Passing an object into this method will return its component name if it is a component, or
+ <literal>null</literal> if it is not. </para>
<programlisting>
if (Seam.Component.getComponentName(instance) == "customer")
@@ -319,20 +270,17 @@
<sect2>
<title>Seam.Remoting</title>
- <para>
- Most of the client side functionality for Seam Remoting is contained within the <literal>Seam.Remoting</literal>
- object. While you shouldn't need to directly call most of its methods, there are a couple of important ones
- worth mentioning.
- </para>
+ <para> Most of the client side functionality for Seam Remoting is contained within the
+ <literal>Seam.Remoting</literal> object. While you shouldn't need to directly call most of its methods, there
+ are a couple of important ones worth mentioning. </para>
<sect3>
<title>Seam.Remoting.createType()</title>
- <para>
- If your application contains or uses Javabean classes that aren't Seam components, you may need to create these
- types on the client side to pass as parameters into your component method. Use the <literal>createType()</literal>
- method to create an instance of your type. Pass in the fully qualified Java class name as a parameter:
- </para>
+ <para> If your application contains or uses Javabean classes that aren't Seam components, you may need to create
+ these types on the client side to pass as parameters into your component method. Use the
+ <literal>createType()</literal> method to create an instance of your type. Pass in the fully qualified Java
+ class name as a parameter: </para>
<programlisting>
var widget = Seam.Remoting.createType("com.acme.widgets.MyWidget");
@@ -342,11 +290,9 @@
<sect3>
<title>Seam.Remoting.getTypeName()</title>
- <para>
- This method is the equivalent of <literal>Seam.Component.getComponentName()</literal> but for non-component types.
- It will return the name of the type for an object instance, or <literal>null</literal> if the type is not
- known. The name is the fully qualified name of the type's Java class.
- </para>
+ <para> This method is the equivalent of <literal>Seam.Component.getComponentName()</literal> but for
+ non-component types. It will return the name of the type for an object instance, or <literal>null</literal> if
+ the type is not known. The name is the fully qualified name of the type's Java class. </para>
</sect3>
</sect2>
</sect1>
@@ -354,10 +300,8 @@
<sect1>
<title>Client Interfaces</title>
- <para>
- In the configuration section above, the interface, or "stub" for our component is imported into our
- page via <literal>seam/remoting/interface.js</literal>:
- </para>
+ <para> In the configuration section above, the interface, or "stub" for our component is imported into our page via
+ <literal>seam/remoting/interface.js</literal>: </para>
<programlisting>
<![CDATA[
@@ -365,82 +309,63 @@
]]>
</programlisting>
- <para>
- By including this script in our page, the interface definitions for our component, plus any other
- components or types that are required to execute the methods of our component are generated and
- made available for the remoting framework to use.
- </para>
-
- <para>
- There are two types of client stub that can be generated, "executable" stubs and "type" stubs.
- Executable stubs are behavioural, and are used to execute methods against your session bean components,
- while type stubs contain state and represent the types that can be passed in as parameters or returned
- as a result.
- </para>
-
- <para>
- The type of client stub that is generated depends on the type of your Seam component. If the component is
- a session bean, then an executable stub will be generated, otherwise if it's an entity or JavaBean, then
- a type stub will be generated. There is one exception to this rule; if your component is a JavaBean (ie it
- is not a session bean nor an entity bean) and any of its methods are annotated with @WebRemote, then
- an executable stub will be generated for it instead of a type stub. This allows you to use remoting to
- call methods of your JavaBean components in a non-EJB environment where you don't have access to session beans.
- </para>
+ <para> By including this script in our page, the interface definitions for our component, plus any other components
+ or types that are required to execute the methods of our component are generated and made available for the
+ remoting framework to use. </para>
+
+ <para> There are two types of client stub that can be generated, "executable" stubs and "type" stubs. Executable
+ stubs are behavioural, and are used to execute methods against your session bean components, while type stubs
+ contain state and represent the types that can be passed in as parameters or returned as a result. </para>
+
+ <para> The type of client stub that is generated depends on the type of your Seam component. If the component is a
+ session bean, then an executable stub will be generated, otherwise if it's an entity or JavaBean, then a type stub
+ will be generated. There is one exception to this rule; if your component is a JavaBean (ie it is not a session
+ bean nor an entity bean) and any of its methods are annotated with @WebRemote, then an executable stub will be
+ generated for it instead of a type stub. This allows you to use remoting to call methods of your JavaBean
+ components in a non-EJB environment where you don't have access to session beans. </para>
</sect1>
<sect1>
<title>The Context</title>
- <para>
- The Seam Remoting Context contains additional information which is sent and received as part of a remoting
- request/response cycle. At this stage it only contains the conversation ID but may be expanded in the future.
- </para>
+ <para> The Seam Remoting Context contains additional information which is sent and received as part of a remoting
+ request/response cycle. At this stage it only contains the conversation ID but may be expanded in the future. </para>
<sect2>
<title>Setting and reading the Conversation ID</title>
</sect2>
- <para>
- If you intend on using remote calls within the scope of a conversation then you need to be able to read or
+ <para> If you intend on using remote calls within the scope of a conversation then you need to be able to read or
set the conversation ID in the Seam Remoting Context. To read the conversation ID after making a remote request
- call <literal>Seam.Remoting.getContext().getConversationId()</literal>. To set the conversation ID before
- making a request, call <literal>Seam.Remoting.getContext().setConversationId()</literal>.
- </para>
+ call <literal>Seam.Remoting.getContext().getConversationId()</literal>. To set the conversation ID before making a
+ request, call <literal>Seam.Remoting.getContext().setConversationId()</literal>. </para>
- <para>
- If the conversation ID hasn't been explicitly set with <literal>Seam.Remoting.getContext().setConversationId()</literal>,
- then it will be automatically assigned the first valid conversation ID that is returned by any remoting call.
- If you are working with multiple conversations within your page, then you may need to explicitly set the conversation ID
- before each call. If you are working with just a single conversation, then you don't need to do anything special.
- </para>
+ <para> If the conversation ID hasn't been explicitly set with
+ <literal>Seam.Remoting.getContext().setConversationId()</literal>, then it will be automatically assigned the
+ first valid conversation ID that is returned by any remoting call. If you are working with multiple conversations
+ within your page, then you may need to explicitly set the conversation ID before each call. If you are working
+ with just a single conversation, then you don't need to do anything special. </para>
</sect1>
<sect1>
<title>Batch Requests</title>
- <para>
- Seam Remoting allows multiple component calls to be executed within a single request. It is recommended that
- this feature is used wherever it is appropriate to reduce network traffic.
- </para>
+ <para> Seam Remoting allows multiple component calls to be executed within a single request. It is recommended that
+ this feature is used wherever it is appropriate to reduce network traffic. </para>
- <para>
- The method <literal>Seam.Remoting.startBatch()</literal> will start a new batch, and any component calls
+ <para> The method <literal>Seam.Remoting.startBatch()</literal> will start a new batch, and any component calls
executed after starting a batch are queued, rather than being sent immediately. When all the desired component
- calls have been added to the batch, the <literal>Seam.Remoting.executeBatch()</literal> method will send a
- single request containing all of the queued calls to the server, where they will be executed in order. After the
- calls have been executed, a single response containining all return values will be returned to the client and
- the callback functions (if provided) triggered in the same order as execution.
- </para>
-
- <para>
- If you start a new batch via the <literal>startBatch()</literal> method but then decide you don't want to
- send it, the <literal>Seam.Remoting.cancelBatch()</literal> method will discard any calls that were queued
- and exit the batch mode.
- </para>
+ calls have been added to the batch, the <literal>Seam.Remoting.executeBatch()</literal> method will send a single
+ request containing all of the queued calls to the server, where they will be executed in order. After the calls
+ have been executed, a single response containining all return values will be returned to the client and the
+ callback functions (if provided) triggered in the same order as execution. </para>
+
+ <para> If you start a new batch via the <literal>startBatch()</literal> method but then decide you don't want to
+ send it, the <literal>Seam.Remoting.cancelBatch()</literal> method will discard any calls that were queued and
+ exit the batch mode. </para>
- <para>
- To see an example of a batch being used, take a look at <literal>/examples/remoting/chatroom</literal>.
+ <para> To see an example of a batch being used, take a look at <literal>/examples/remoting/chatroom</literal>.
</para>
</sect1>
@@ -450,38 +375,29 @@
<sect2>
<title>Primitives / Basic Types</title>
- <para>
- This section describes the support for basic data types. On the server side these values
- are generally compatible with either their primitive type or their corresponding wrapper class.
- </para>
+ <para> This section describes the support for basic data types. On the server side these values are generally
+ compatible with either their primitive type or their corresponding wrapper class. </para>
<sect3>
<title>String</title>
- <para>
- Simply use Javascript String objects when setting String parameter values.
- </para>
+ <para> Simply use Javascript String objects when setting String parameter values. </para>
</sect3>
<sect3>
<title>Number</title>
- <para>
- There is support for all number types supported by Java. On the client side, number values
- are always serialized as their String representation and then on the server side they are
- converted to the correct destination type. Conversion into either a primitive or wrapper
- type is supported for <literal>Byte</literal>, <literal>Double</literal>,
- <literal>Float</literal>, <literal>Integer</literal>, <literal>Long</literal> and
- <literal>Short</literal> types.
- </para>
+ <para> There is support for all number types supported by Java. On the client side, number values are always
+ serialized as their String representation and then on the server side they are converted to the correct
+ destination type. Conversion into either a primitive or wrapper type is supported for <literal>Byte</literal>,
+ <literal>Double</literal>, <literal>Float</literal>, <literal>Integer</literal>, <literal>Long</literal> and
+ <literal>Short</literal> types. </para>
</sect3>
<sect3>
<title>Boolean</title>
- <para>
- Booleans are represented client side by Javascript Boolean values, and server side by
- a Java boolean.
+ <para> Booleans are represented client side by Javascript Boolean values, and server side by a Java boolean.
</para>
</sect3>
</sect2>
@@ -489,18 +405,14 @@
<sect2>
<title>JavaBeans</title>
- <para>
- In general these will be either Seam entity or JavaBean components, or some other non-component class. Use
+ <para> In general these will be either Seam entity or JavaBean components, or some other non-component class. Use
the appropriate method (either <literal>Seam.Component.newInstance()</literal> for Seam components or
- <literal>Seam.Remoting.createType()</literal> for everything else) to create a new instance of the object.
- </para>
+ <literal>Seam.Remoting.createType()</literal> for everything else) to create a new instance of the object. </para>
- <para>
- It is important to note that only objects that are created by either of these two methods should be used
- as parameter values, where the parameter is not one of the other valid types mentioned anywhere else in
- this section. In some situations you may have a component method where the exact parameter type cannot
- be determined, such as:
- </para>
+ <para> It is important to note that only objects that are created by either of these two methods should be used as
+ parameter values, where the parameter is not one of the other valid types mentioned anywhere else in this
+ section. In some situations you may have a component method where the exact parameter type cannot be determined,
+ such as: </para>
<programlisting>
@Name("myAction")
@@ -511,12 +423,10 @@
}
</programlisting>
- <para>
- In this case you might want to pass in an instance of your <literal>myWidget</literal> component, however the
- interface for <literal>myAction</literal> won't include <literal>myWidget</literal> as it is not
- directly referenced by any of its methods. To get around this, <literal>MyWidget</literal> needs to
- be explicitly imported:
- </para>
+ <para> In this case you might want to pass in an instance of your <literal>myWidget</literal> component, however
+ the interface for <literal>myAction</literal> won't include <literal>myWidget</literal> as it is not directly
+ referenced by any of its methods. To get around this, <literal>MyWidget</literal> needs to be explicitly
+ imported: </para>
<programlisting>
<![CDATA[
@@ -524,32 +434,26 @@
]]>
</programlisting>
- <para>
- This will then allow a <literal>myWidget</literal> object to be created with
+ <para> This will then allow a <literal>myWidget</literal> object to be created with
<literal>Seam.Component.newInstance("myWidget")</literal>, which can then be passed to
- <literal>myAction.doSomethingWithObject()</literal>.
- </para>
+ <literal>myAction.doSomethingWithObject()</literal>. </para>
</sect2>
<sect2>
<title>Dates and Times</title>
- <para>
- Date values are serialized into a String representation that is accurate to the millisecond.
- On the client side, use a Javascript Date object to work with date values. On the server side,
- use any <literal>java.util.Date</literal> (or descendent, such as <literal>java.sql.Date</literal>
- or <literal>java.sql.Timestamp</literal> class.
- </para>
+ <para> Date values are serialized into a String representation that is accurate to the millisecond. On the client
+ side, use a Javascript Date object to work with date values. On the server side, use any
+ <literal>java.util.Date</literal> (or descendent, such as <literal>java.sql.Date</literal> or
+ <literal>java.sql.Timestamp</literal> class. </para>
</sect2>
<sect2>
<title>Enums</title>
- <para>
- On the client side, enums are treated the same as Strings. When setting the value for an enum parameter,
- simply use the String representation of the enum. Take the following component as an example:
- </para>
+ <para> On the client side, enums are treated the same as Strings. When setting the value for an enum parameter,
+ simply use the String representation of the enum. Take the following component as an example: </para>
<programlisting>
@Name("paintAction")
@@ -562,19 +466,15 @@
}
</programlisting>
- <para>
- To call the <literal>paint()</literal> method with the color <literal>red</literal>, pass the parameter
- value as a String literal:
- </para>
+ <para> To call the <literal>paint()</literal> method with the color <literal>red</literal>, pass the parameter
+ value as a String literal: </para>
<programlisting>
Seam.Component.getInstance("paintAction").paint("red");
</programlisting>
- <para>
- The inverse is also true - that is, if a component method returns an enum parameter (or contains an enum
- field anywhere in the returned object graph) then on the client-side it will be represented as a String.
- </para>
+ <para> The inverse is also true - that is, if a component method returns an enum parameter (or contains an enum
+ field anywhere in the returned object graph) then on the client-side it will be represented as a String. </para>
</sect2>
<sect2>
@@ -583,39 +483,31 @@
<sect3>
<title>Bags</title>
- <para>
- Bags cover all collection types including arrays, collections, lists, sets, (but excluding Maps - see the
- next section for those),
- and are implemented client-side as a Javascript array. When calling a component method that accepts one of
- these types as a parameter, your parameter should be a Javascript array. If a component method
- returns one of these types, then the return value will also be a Javascript array. The remoting
- framework is clever enough on the server side to convert the bag to an appropriate type for
- the component method call.
- </para>
+ <para> Bags cover all collection types including arrays, collections, lists, sets, (but excluding Maps - see the
+ next section for those), and are implemented client-side as a Javascript array. When calling a component
+ method that accepts one of these types as a parameter, your parameter should be a Javascript array. If a
+ component method returns one of these types, then the return value will also be a Javascript array. The
+ remoting framework is clever enough on the server side to convert the bag to an appropriate type for the
+ component method call. </para>
</sect3>
<sect3>
<title>Maps</title>
- <para>
- As there is no native support for Maps within Javascript, a simple Map implementation is provided with
- the Seam Remoting framework. To create a Map which can be used as a parameter to a remote call,
- create a new <literal>Seam.Remoting.Map</literal> object:
- </para>
+ <para> As there is no native support for Maps within Javascript, a simple Map implementation is provided with
+ the Seam Remoting framework. To create a Map which can be used as a parameter to a remote call, create a new
+ <literal>Seam.Remoting.Map</literal> object: </para>
<programlisting>
var map = new Seam.Remoting.Map();
</programlisting>
- <para>
- This Javascript implementation provides basic methods for working with Maps:
- <literal>size()</literal>, <literal>isEmpty()</literal>, <literal>keySet()</literal>,
- <literal>values()</literal>, <literal>get(key)</literal>, <literal>put(key, value)</literal>,
- <literal>remove(key)</literal> and <literal>contains(key)</literal>. Each of these methods are
- equivalent to their Java counterpart. Where the method returns a collection, such as
- <literal>keySet()</literal> and <literal>values()</literal>, a Javascript Array object will be
- returned that contains the key or value objects (respectively).
- </para>
+ <para> This Javascript implementation provides basic methods for working with Maps: <literal>size()</literal>,
+ <literal>isEmpty()</literal>, <literal>keySet()</literal>, <literal>values()</literal>,
+ <literal>get(key)</literal>, <literal>put(key, value)</literal>, <literal>remove(key)</literal> and
+ <literal>contains(key)</literal>. Each of these methods are equivalent to their Java counterpart. Where the
+ method returns a collection, such as <literal>keySet()</literal> and <literal>values()</literal>, a Javascript
+ Array object will be returned that contains the key or value objects (respectively). </para>
</sect3>
</sect2>
</sect1>
@@ -623,47 +515,33 @@
<sect1>
<title>Debugging</title>
- <para>
- To aid in tracking down bugs, it is possible to enable a debug mode which will display the
- contents of all the packets send back and forth between the client and server in a popup window.
- To enable debug mode, either execute the <literal>setDebug()</literal> method in Javascript:
- </para>
+ <para> To aid in tracking down bugs, it is possible to enable a debug mode which will display the contents of all
+ the packets send back and forth between the client and server in a popup window. To enable debug mode, either
+ execute the <literal>setDebug()</literal> method in Javascript: </para>
<programlisting>
Seam.Remoting.setDebug(true);
</programlisting>
- <para>
- Or configure it via components.xml:
- </para>
+ <para> Or configure it via components.xml: </para>
- <programlisting>
- <component name="org.jboss.seam.remoting.remotingConfig">
- <property name="debug">true</property>
- </component>
- </programlisting>
+ <programlisting><remoting:remoting-config debug="true"/></programlisting>
- <para>
- To turn off debugging, call <literal>setDebug(false)</literal>. If you want to write your own
- messages to the debug log, call <literal>Seam.Remoting.log(message)</literal>.
- </para>
+ <para> To turn off debugging, call <literal>setDebug(false)</literal>. If you want to write your own messages to the
+ debug log, call <literal>Seam.Remoting.log(message)</literal>. </para>
</sect1>
<sect1>
<title>The Loading Message</title>
- <para>
- The default loading message that appears in the top right corner of the screen can be
- modified, its rendering customised or even turned off completely.
- </para>
+ <para> The default loading message that appears in the top right corner of the screen can be modified, its rendering
+ customised or even turned off completely. </para>
<sect2>
<title>Changing the message</title>
- <para>
- To change the message from the default "Please Wait..." to something different, set the
- value of <literal>Seam.Remoting.loadingMessage</literal>:
- </para>
+ <para> To change the message from the default "Please Wait..." to something different, set the value of
+ <literal>Seam.Remoting.loadingMessage</literal>: </para>
<programlisting>
Seam.Remoting.loadingMessage = "Loading...";
@@ -673,11 +551,9 @@
<sect2>
<title>Hiding the loading message</title>
- <para>
- To completely suppress the display of the loading message, override the implementation
- of <literal>displayLoadingMessage()</literal> and <literal>hideLoadingMessage()</literal> with
- functions that instead do nothing:
- </para>
+ <para> To completely suppress the display of the loading message, override the implementation of
+ <literal>displayLoadingMessage()</literal> and <literal>hideLoadingMessage()</literal> with functions that
+ instead do nothing: </para>
<programlisting>
// don't display the loading indicator
@@ -689,11 +565,9 @@
<sect2>
<title>A Custom Loading Indicator</title>
- <para>
- It is also possible to override the loading indicator to display an animated icon, or anything
- else that you want. To do this override the <literal>displayLoadingMessage()</literal> and
- <literal>hideLoadingMessage()</literal> messages with your own implementation:
- </para>
+ <para> It is also possible to override the loading indicator to display an animated icon, or anything else that
+ you want. To do this override the <literal>displayLoadingMessage()</literal> and
+ <literal>hideLoadingMessage()</literal> messages with your own implementation: </para>
<programlisting>
Seam.Remoting.displayLoadingMessage = function() {
@@ -710,28 +584,20 @@
<sect1>
<title>Controlling what data is returned</title>
- <para>
- When a remote method is executed, the result is serialized into an XML response that is returned
- to the client. This response is then unmarshaled by the client into a Javascript object. For
- complex types (i.e. Javabeans) that include references to other objects, all of these referenced objects
- are also serialized as part of the response. These objects may reference other objects, which may
- reference other objects, and so forth. If left unchecked, this object "graph" could potentially
- be enormous, depending on what relationships exist between your objects. And as a side issue (besides
- the potential verbosity of the response), you might also wish to prevent sensitive information from being
- exposed to the client.
- </para>
+ <para> When a remote method is executed, the result is serialized into an XML response that is returned to the
+ client. This response is then unmarshaled by the client into a Javascript object. For complex types (i.e.
+ Javabeans) that include references to other objects, all of these referenced objects are also serialized as part
+ of the response. These objects may reference other objects, which may reference other objects, and so forth. If
+ left unchecked, this object "graph" could potentially be enormous, depending on what relationships exist between
+ your objects. And as a side issue (besides the potential verbosity of the response), you might also wish to
+ prevent sensitive information from being exposed to the client. </para>
+
+ <para> Seam Remoting provides a simple means to "constrain" the object graph, by specifying the
+ <literal>exclude</literal> field of the remote method's <literal>@WebRemote</literal> annotation. This field
+ accepts a String array containing one or more paths specified using dot notation. When invoking a remote method,
+ the objects in the result's object graph that match these paths are excluded from the serialized result packet. </para>
- <para>
- Seam Remoting provides a simple means to "constrain" the object graph, by specifying the
- <literal>exclude</literal> field of the remote method's <literal>@WebRemote</literal> annotation.
- This field accepts a String array containing one or more paths specified using dot notation. When invoking
- a remote method, the objects in the result's object graph that match these paths are excluded from the
- serialized result packet.
- </para>
-
- <para>
- For all our examples, we'll use the following <literal>Widget</literal> class:
- </para>
+ <para> For all our examples, we'll use the following <literal>Widget</literal> class: </para>
<programlisting>
@Name("widget")
@@ -750,23 +616,20 @@
<sect2>
<title>Constraining normal fields</title>
- <para>
- If your remote method returns an instance of <literal>Widget</literal>, but you don't want to expose the
- <literal>secret</literal> field because it contains sensitive information, you would constrain it like this:
- </para>
+ <para> If your remote method returns an instance of <literal>Widget</literal>, but you don't want to expose the
+ <literal>secret</literal> field because it contains sensitive information, you would constrain it like this: </para>
<programlisting>
@WebRemote(exclude = {"secret"})
public Widget getWidget();
</programlisting>
- <para>
- The value "secret" refers to the <literal>secret</literal> field of the returned object. Now, suppose that we
- don't care about exposing this particular field to the client. Instead, notice that the <literal>Widget</literal>
- value that is returned has a field <literal>child</literal> that is also a <literal>Widget</literal>. What if we
- want to hide the <literal>child</literal>'s <literal>secret</literal> value instead? We can do this by using
- dot notation to specify this field's path within the result's object graph:
- </para>
+ <para> The value "secret" refers to the <literal>secret</literal> field of the returned object. Now, suppose that
+ we don't care about exposing this particular field to the client. Instead, notice that the
+ <literal>Widget</literal> value that is returned has a field <literal>child</literal> that is also a
+ <literal>Widget</literal>. What if we want to hide the <literal>child</literal>'s <literal>secret</literal>
+ value instead? We can do this by using dot notation to specify this field's path within the result's object
+ graph: </para>
<programlisting>
@WebRemote(exclude = {"child.secret"})
@@ -778,27 +641,23 @@
<sect2>
<title>Constraining Maps and Collections</title>
- <para>
- The other place that objects can exist within an object graph are within a <literal>Map</literal> or
- some kind of collection (<literal>List</literal>, <literal>Set</literal>, <literal>Array</literal>, etc).
- Collections are easy, and are treated like any other field. For example, if our <literal>Widget</literal>
- contained a list of other <literal>Widget</literal>s in its <literal>widgetList</literal> field, to
- constrain the <literal>secret</literal> field of the <literal>Widget</literal>s in this list the annotation
- would look like this:
- </para>
+ <para> The other place that objects can exist within an object graph are within a <literal>Map</literal> or some
+ kind of collection (<literal>List</literal>, <literal>Set</literal>, <literal>Array</literal>, etc). Collections
+ are easy, and are treated like any other field. For example, if our <literal>Widget</literal> contained a list
+ of other <literal>Widget</literal>s in its <literal>widgetList</literal> field, to constrain the
+ <literal>secret</literal> field of the <literal>Widget</literal>s in this list the annotation would look like
+ this: </para>
<programlisting>
@WebRemote(exclude = {"widgetList.secret"})
public Widget getWidget();
</programlisting>
- <para>
- To constrain a <literal>Map</literal>'s key or value, the notation is slightly different. Appending
+ <para> To constrain a <literal>Map</literal>'s key or value, the notation is slightly different. Appending
<literal>[key]</literal> after the <literal>Map</literal>'s field name will constrain the
- <literal>Map</literal>'s key object values, while <literal>[value]</literal> will constrain the value
- object values. The following example demonstrates how the values of the <literal>widgetMap</literal>
- field have their <literal>secret</literal> field constrained:
- </para>
+ <literal>Map</literal>'s key object values, while <literal>[value]</literal> will constrain the value object
+ values. The following example demonstrates how the values of the <literal>widgetMap</literal> field have their
+ <literal>secret</literal> field constrained: </para>
<programlisting>
@WebRemote(exclude = {"widgetMap[value].secret"})
@@ -809,12 +668,10 @@
<sect2>
<title>Constraining objects of a specific type</title>
- <para>
- There is one last notation that can be used to constrain the fields of a type of object no matter
- where in the result's object graph it appears. This notation uses either the name of the component
- (if the object is a Seam component) or the fully qualified class name (only if the object is not a
- Seam component) and is expressed using square brackets:
- </para>
+ <para> There is one last notation that can be used to constrain the fields of a type of object no matter where in
+ the result's object graph it appears. This notation uses either the name of the component (if the object is a
+ Seam component) or the fully qualified class name (only if the object is not a Seam component) and is expressed
+ using square brackets: </para>
<programlisting>
@WebRemote(exclude = {"[widget].secret"})
@@ -826,9 +683,7 @@
<sect2>
<title>Combining Constraints</title>
- <para>
- Constraints can also be combined, to filter objects from multiple paths within the object graph:
- </para>
+ <para> Constraints can also be combined, to filter objects from multiple paths within the object graph: </para>
<programlisting>
@WebRemote(exclude = {"widgetList.secret", "widgetMap[value].secret"})
@@ -841,34 +696,26 @@
<sect1>
<title>JMS Messaging</title>
- <para>
- Seam Remoting provides experimental support for JMS Messaging. This section describes the JMS support
- that is currently implemented, but please note that this may change in the future. It is currently not
- recommended that this feature is used within a production environment.
- </para>
+ <para> Seam Remoting provides experimental support for JMS Messaging. This section describes the JMS support that is
+ currently implemented, but please note that this may change in the future. It is currently not recommended that
+ this feature is used within a production environment. </para>
<sect2>
<title>Configuration</title>
- <para>
- Before you can subscribe to a JMS topic, you must first configure a list of the topics that can be
+ <para> Before you can subscribe to a JMS topic, you must first configure a list of the topics that can be
subscribed to by Seam Remoting. List the topics under
- <literal>org.jboss.seam.remoting.messaging.subscriptionRegistry.allowedTopics</literal>
- in <literal>seam.properties</literal>, <literal>web.xml</literal> or <literal>components.xml</literal>.
- </para>
+ <literal>org.jboss.seam.remoting.messaging.subscriptionRegistry.allowedTopics</literal> in
+ <literal>seam.properties</literal>, <literal>web.xml</literal> or <literal>components.xml</literal>. </para>
- <programlisting><![CDATA[<component name="org.jboss.seam.remoting.messaging.subscriptionRegistry">
- <property name="allowedTopics">chatroomTopic, stockTickerTopic</property>
-</component>]]></programlisting>
+ <programlisting><![CDATA[<remoting:remoting-config poll-timeout="5" poll-interval="1"/>]]></programlisting>
</sect2>
<sect2>
<title>Subscribing to a JMS Topic</title>
- <para>
- The following example demonstrates how to subscribe to a JMS Topic:
- </para>
+ <para> The following example demonstrates how to subscribe to a JMS Topic: </para>
<programlisting>
function subscriptionCallback(message)
@@ -880,29 +727,23 @@
Seam.Remoting.subscribe("topicName", subscriptionCallback);
</programlisting>
- <para>
- The <literal>Seam.Remoting.subscribe()</literal> method accepts two parameters, the first being the name
- of the JMS Topic to subscribe to, the second being the callback function to invoke when a message is
- received.
- </para>
+ <para> The <literal>Seam.Remoting.subscribe()</literal> method accepts two parameters, the first being the name of
+ the JMS Topic to subscribe to, the second being the callback function to invoke when a message is received. </para>
- <para>
- There are two types of messages supported, Text messages and Object messages. If you need to test for the
- type of message that is passed to your callback function you can use the <literal>instanceof</literal>
- operator to test whether the message is a <literal>Seam.Remoting.TextMessage</literal> or
- <literal>Seam.Remoting.ObjectMessage</literal>. A <literal>TextMessage</literal> contains the text value
- in its <literal>text</literal> field (or alternatively call <literal>getText()</literal> on it), while an
- <literal>ObjectMessage</literal> contains its object value in its <literal>object</literal> field (or call
- its <literal>getObject()</literal> method).
- </para>
+ <para> There are two types of messages supported, Text messages and Object messages. If you need to test for the
+ type of message that is passed to your callback function you can use the <literal>instanceof</literal> operator
+ to test whether the message is a <literal>Seam.Remoting.TextMessage</literal> or
+ <literal>Seam.Remoting.ObjectMessage</literal>. A <literal>TextMessage</literal> contains the text value in
+ its <literal>text</literal> field (or alternatively call <literal>getText()</literal> on it), while an
+ <literal>ObjectMessage</literal> contains its object value in its <literal>object</literal> field (or call its
+ <literal>getObject()</literal> method). </para>
</sect2>
<sect2>
<title>Unsubscribing from a Topic</title>
- <para>
- To unsubscribe from a topic, call <literal>Seam.Remoting.unsubscribe()</literal> and pass in the topic name:
- </para>
+ <para> To unsubscribe from a topic, call <literal>Seam.Remoting.unsubscribe()</literal> and pass in the topic
+ name: </para>
<programlisting>
Seam.Remoting.unsubscribe("topicName");
@@ -912,35 +753,25 @@
<sect2>
<title>Tuning the Polling Process</title>
- <para>
- There are two parameters which you can modify to control how polling occurs. The first one is
- <literal>Seam.Remoting.pollInterval</literal>, which controls how long to wait between subsequent
- polls for new messages. This parameter is expressed in seconds, and its default setting is 10.
- </para>
-
- <para>
- The second parameter is <literal>Seam.Remoting.pollTimeout</literal>, and is also expressed as seconds.
- It controls how long a request to the server should wait for a new message before timing out and sending
- an empty response. Its default is 0 seconds, which means that when the server is polled, if there are no
- messages ready for delivery then an empty response will be immediately returned.
- </para>
-
- <para>
- Caution should be used when setting a high <literal>pollTimeout</literal> value; each request that
- has to wait for a message means that a server thread is tied up until a message is received, or until the
- request times out. If many such requests are being served simultaneously, it could mean a large
- number of threads become tied up because of this reason.
- </para>
+ <para> There are two parameters which you can modify to control how polling occurs. The first one is
+ <literal>Seam.Remoting.pollInterval</literal>, which controls how long to wait between subsequent polls for
+ new messages. This parameter is expressed in seconds, and its default setting is 10. </para>
+
+ <para> The second parameter is <literal>Seam.Remoting.pollTimeout</literal>, and is also expressed as seconds. It
+ controls how long a request to the server should wait for a new message before timing out and sending an empty
+ response. Its default is 0 seconds, which means that when the server is polled, if there are no messages ready
+ for delivery then an empty response will be immediately returned. </para>
+
+ <para> Caution should be used when setting a high <literal>pollTimeout</literal> value; each request that has to
+ wait for a message means that a server thread is tied up until a message is received, or until the request times
+ out. If many such requests are being served simultaneously, it could mean a large number of threads become tied
+ up because of this reason. </para>
+
+ <para> It is recommended that you set these options via components.xml, however they can be overridden via
+ Javascript if desired. The following example demonstrates how to configure the polling to occur much more
+ aggressively. You should set these parameters to suitable values for your application: </para>
- <para>
- It is recommended that you set these options via components.xml, however they can be overridden via
- Javascript if desired. The following example demonstrates how to configure the polling to occur much
- more aggressively. You should set these parameters to suitable values for your application:
- </para>
-
- <para>
- Via components.xml:
- </para>
+ <para> Via components.xml: </para>
<programlisting>
<![CDATA[
@@ -951,9 +782,7 @@
]]>
</programlisting>
- <para>
- Via JavaScript:
- </para>
+ <para> Via JavaScript: </para>
<programlisting>
// Only wait 1 second between receiving a poll response and sending the next poll request.
1.73 +2359 -2363jboss-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.72
retrieving revision 1.73
diff -u -b -r1.72 -r1.73
--- tutorial.xml 20 Nov 2006 19:24:19 -0000 1.72
+++ tutorial.xml 27 Nov 2006 03:28:17 -0000 1.73
@@ -518,19 +518,15 @@
</para>
<example>
- <programlisting><![CDATA[<components>
-
- <component name="org.jboss.seam.core.init">
- <!-- JNDI name pattern for JBoss EJB 3.0 -->
- <property name="jndiPattern">#{ejbName}/local</property>
- </component>
-
+ <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:core="http://jboss.com/products/seam/core">
+ <core:init jndi-pattern="@jndiPattern@"/>
</components>]]></programlisting>
</example>
<para>
This code configures a property named <literal>jndiPattern</literal> of a built-in
- Seam component named <literal>org.jboss.seam.core.init</literal>.
+ Seam <literal>init</literal> component, which happens to be named <literal>org.jboss.seam.core.init</literal>.
</para>
</section>
More information about the jboss-cvs-commits
mailing list