[seam-commits] Seam SVN: r12794 - branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Tue May 25 10:38:54 EDT 2010
Author: manaRH
Date: 2010-05-25 10:38:51 -0400 (Tue, 25 May 2010)
New Revision: 12794
Added:
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Clustering_EJBPassivation.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Migration.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide.ent
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide.xml
Removed:
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/master.xml
Modified:
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Annotations.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Author_Group.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Book_Info.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Cache.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Components.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Concepts.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Configuration.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Controls.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Conversations.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Dependencies.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Drools.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Elenhancements.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Events.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Excel.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Feedback.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Framework.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Gettingstarted.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Groovy.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Gwt.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Hsearch.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/I18n.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Itext.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Jbpm.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Jms.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Mail.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Performance.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Persistence.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Preface.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Remoting.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Revision_History.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Security.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Spring.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Testing.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Text.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Tools.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Tutorial.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Validation.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Webservices.xml
branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Xml.xml
Log:
merged Documentation from https://svn.jboss.org/repos/jbossas/projects/docs/enterprise/5.0.1/Seam_Reference_Guide/en-US/
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Annotations.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Annotations.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Annotations.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,1572 +1,1215 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="annotations">
- <title>Seam annotations</title>
-
- <para>
- When you write a Seam application, you'll use a lot of annotations. Seam
- lets you use annotations to achieve a declarative style of programming.
- Most of the annotations you'll use are defined by the EJB 3.0
- specification. The annotations for data validation are defined by the
- Hibernate Validator package. Finally, Seam defines its own set of
- annotations, which we'll describe in this chapter.
- </para>
-
- <para>
- All of these annotations are defined in the package
- <literal>org.jboss.seam.annotations</literal>.
- </para>
-
- <section>
- <title>Annotations for component definition</title>
- <para>
- The first group of annotations lets you define a Seam component. These
- annotations appear on the component class.
- </para>
-
- <variablelist>
- <varlistentry id="name-annotation">
- <term>
- <literal>@Name</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Name("componentName")]]></programlisting>
- <para>
- Defines the Seam component name for a class. This annotation
- is required for all Seam components.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="scope-annotation">
- <term>
- <literal>@Scope</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Scope(ScopeType.CONVERSATION)]]></programlisting>
- <para>
- Defines the default context of the component. The possible
- values are defined by the <literal>ScopeType</literal>
- enumeration: <literal>EVENT, PAGE, CONVERSATION, SESSION, BUSINESS_PROCESS, APPLICATION, STATELESS</literal>.
- </para>
- <para>
- When no scope is explicitly specified, the default depends
- upon the component type. For stateless session beans, the
- default is <literal>STATELESS</literal>. For entity beans and
- stateful session beans, the default is
- <literal>CONVERSATION</literal>. For JavaBeans, the default is
- <literal>EVENT</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="role-annotation">
- <term>
- <literal>@Role</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Role(name="roleName", scope=ScopeType.SESSION)]]></programlisting>
- <para>
- Allows a Seam component to be bound to multiple contexts
- variables. The <literal>@Name</literal>/<literal>@Scope</literal>
- annotations define a "default role". Each <literal>@Role</literal>
- annotation defines an additional role.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>name</literal> — the context variable
- name.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>scope</literal> — the context variable
- scope. When no scope is explicitly specified, the
- default depends upon the component type, as above.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry id="roles-annotation">
- <term>
- <literal>@Roles</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Roles({
- @Role(name="user", scope=ScopeType.CONVERSATION),
- @Role(name="currentUser", scope=ScopeType.SESSION)
- })]]></programlisting>
- <para>
- Allows specification of multiple additional roles.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="intercept-annotation">
- <term>
- <literal>@BypassInterceptors</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@BypassInterceptors]]></programlisting>
- <para>
- Disables Seam all interceptors on a particular component or
- method of a component.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="jndiname-annotation">
- <term>
- <literal>@JndiName</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@JndiName("my/jndi/name")]]></programlisting>
- <para>
- Specifies the JNDI name that Seam will use to look up the EJB
- component. If no JNDI name is explicitly specified, Seam will
- use the JNDI pattern specified by
- <literal>org.jboss.seam.core.init.jndiPattern</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="conversational-annotation">
- <term>
- <literal>@Conversational</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Conversational]]></programlisting>
- <para>
- Specifies that a conversation scope component is
- conversational, meaning that no method of the component may be
- called unless a long-running conversation is active.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="pernestedconversation-annotation">
- <term>
- <literal>@PerNestedConversation</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@PerNestedConversation]]></programlisting>
- <para>
- Limits the scope of a CONVERSATION-scoped component to just
- the parent conversation in which it was instantiated. The
- component instance will not be visible to nested child
- conversations, which will get their own instance.
- </para>
- <para>
- Warning: this is ill-defined, since it implies that a
- component will be visible for some part of a request cycle,
- and invisible after that. It is not recommended that
- applications use this feature!
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="startup-annotation">
- <term>
- <literal>@Startup</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Scope(APPLICATION) @Startup(depends="org.jboss.seam.bpm.jbpm")]]></programlisting>
- <para>
- Specifies that an application scope component is started
- immediately at initialization time. This is mainly used for
- certain built-in components that bootstrap critical
- infrastructure such as JNDI, datasources, etc.
- </para>
- <programlisting role="JAVA"><![CDATA[@Scope(SESSION) @Startup]]></programlisting>
- <para>
- Specifies that a session scope component is started
- immediately at session creation time.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>depends</literal> — specifies that the
- named components must be started first, if they are
- installed.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry id="install-annotation">
- <term>
- <literal>@Install</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Install(false)]]></programlisting>
- <para>
- Specifies whether or not a component should be installed by
- default. The lack of an <literal>@Install</literal> annotation
- indicates a component should be installed.
- </para>
- <programlisting role="JAVA"><![CDATA[@Install(dependencies="org.jboss.seam.bpm.jbpm")]]></programlisting>
- <para>
- Specifies that a component should only be stalled if the
- components listed as dependencies are also installed.
- </para>
- <programlisting role="JAVA"><![CDATA[@Install(genericDependencies=ManagedQueueSender.class)]]></programlisting>
- <para>
- Specifies that a component should only be installed if a
- component that is implemented by a certain class is installed.
- This is useful when the dependency doesn't have a single
- well-known name.
- </para>
- <programlisting role="JAVA"><![CDATA[@Install(classDependencies="org.hibernate.Session")]]></programlisting>
- <para>
- Specifies that a component should only be installed if the
- named class is in the classpath.
- </para>
- <programlisting role="JAVA"><![CDATA[@Install(precedence=BUILT_IN)]]></programlisting>
- <para>
- Specifies the precedence of the component. If multiple
- components with the same name exist, the one with the higher
- precedence will be installed. The defined precendence values
- are (in ascending order):
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>BUILT_IN</literal> — Precedence of all
- built-in Seam components
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>FRAMEWORK</literal> — Precedence to use
- for components of frameworks which extend Seam
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>APPLICATION</literal> — Precedence of
- application components (the default precedence)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>DEPLOYMENT</literal> — Precedence to use
- for components which override application components in
- a particular deployment
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>MOCK</literal> — Precedence for mock
- objects used in testing
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
-
- <varlistentry id="synchronized-annotation">
- <term>
- <literal>@Synchronized</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Synchronized(timeout=1000)]]></programlisting>
- <para>
- Specifies that a component is accessed concurrently by
- multiple clients, and that Seam should serialize requests. If
- a request is not able to obtain its lock on the component in
- the given timeout period, an exception will be raised.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="readonly-annotation">
- <term>
- <literal>@ReadOnly</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@ReadOnly]]></programlisting>
- <para>
- Specifies that a JavaBean component or component method does
- not require state replication at the end of the invocation.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="autocreate-annotation">
- <term>
- <literal>@AutoCreate</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@AutoCreate]]></programlisting>
- <para>
- Specifies that a component will be automatically created, even
- if the client does not specify <literal>create=true</literal>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>Annotations for bijection</title>
- <para>
- The next two annotations control bijection. These attributes occur on
- component instance variables or property accessor methods.
- </para>
-
- <variablelist>
- <varlistentry id="in-annotation">
- <term>
- <literal>@In</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@In]]></programlisting>
- <para>
- Specifies that a component attribute is to be injected from a
- context variable at the beginning of each component
- invocation. If the context variable is null, an exception
- will be thrown.
- </para>
- <programlisting role="JAVA"><![CDATA[@In(required=false)]]></programlisting>
- <para>
- Specifies that a component attribute is to be injected from a
- context variable at the beginning of each component
- invocation. The context variable may be null.
- </para>
- <programlisting role="JAVA"><![CDATA[@In(create=true)]]></programlisting>
- <para>
- Specifies that a component attribute is to be injected from a
- context variable at the beginning of each component
- invocation. If the context variable is null, an instance of
- the component is instantiated by Seam.
- </para>
- <programlisting role="JAVA"><![CDATA[@In(value="contextVariableName")]]></programlisting>
- <para>
- Specifies the name of the context variable explicitly, instead
- of using the annotated instance variable name.
- </para>
- <programlisting role="JAVA"><![CDATA[@In(value="#{customer.addresses['shipping']}")]]></programlisting>
- <para>
- Specifies that a component attribute is to be injected by
- evaluating a JSF EL expression at the beginning of each
- component invocation.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — specifies the name of
- the context variable. Default to the name of the
- component attribute. Alternatively, specifies a JSF EL
- expression, surrounded by <literal>#{...}</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>create</literal> — specifies that Seam
- should instantiate the component with the same name as
- the context variable if the context variable is
- undefined (null) in all contexts. Default to false.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>required</literal> — specifies Seam
- should throw an exception if the context variable is
- undefined in all contexts.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry id="out-annotation">
- <term>
- <literal>@Out</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Out]]></programlisting>
- <para>
- Specifies that a component attribute that is a Seam component
- is to be outjected to its context variable at the end of the
- invocation. If the attribute is null, an exception is thrown.
- </para>
- <programlisting role="JAVA"><![CDATA[@Out(required=false)]]></programlisting>
- <para>
- Specifies that a component attribute that is a Seam component
- is to be outjected to its context variable at the end of the
- invocation. The attribute may be null.
- </para>
- <programlisting role="JAVA"><![CDATA[@Out(scope=ScopeType.SESSION)]]></programlisting>
- <para>
- Specifies that a component attribute that is
- <emphasis>not</emphasis> a Seam component type is to be
- outjected to a specific scope at the end of the invocation.
- </para>
- <para>
- Alternatively, if no scope is explicitly specified, the scope
- of the component with the <literal>@Out</literal> attribute is
- used (or the <literal>EVENT</literal> scope if the component
- is stateless).
- </para>
- <programlisting role="JAVA"><![CDATA[@Out(value="contextVariableName")]]></programlisting>
- <para>
- Specifies the name of the context variable explicitly, instead
- of using the annotated instance variable name.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — specifies the name of
- the context variable. Default to the name of the
- component attribute.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>required</literal> — specifies Seam
- should throw an exception if the component attribute is
- null during outjection.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- Note that it is quite common for these annotations to occur together,
- for example:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@In(create=true) @Out private User currentUser;]]></programlisting>
-
- <para>
- The next annotation supports the <emphasis>manager component</emphasis>
- pattern; a Seam component manages the lifecycle of an
- instance of some other class that is to be injected. It appears on a
- component getter method.
- </para>
-
- <variablelist>
- <varlistentry id="unwrap-annotation">
- <term>
- <literal>@Unwrap</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Unwrap]]></programlisting>
- <para>
- Specifies that the object returned by the annotated getter
- method is the thing that is injected instead of the component
- instance itself.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- The next annotation supports the <emphasis>factory component</emphasis>
- pattern; a Seam component is responsible for initializing the
- value of a context variable. This is especially useful for initializing
- any state needed for rendering the response to a non-faces request. It
- appears on a component method.
- </para>
-
- <variablelist >
- <varlistentry id="factory-annotation">
- <term>
- <literal>@Factory</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Factory("processInstance") public void createProcessInstance() { ... }]]></programlisting>
- <para>
- Specifies that the method of the component is used to
- initialize the value of the named context variable, when the
- context variable has no value. This style is used with methods
- that return <literal>void</literal>.
- </para>
- <programlisting role="JAVA"><![CDATA[@Factory("processInstance", scope=CONVERSATION) public ProcessInstance createProcessInstance() { ... }]]></programlisting>
- <para>
- Specifies that the method returns a value that Seam should use
- to initialize the value of the named context variable, when
- the context variable has no value. This style is used with
- methods that return a value. If no scope is explicitly
- specified, the scope of the component with the
- <literal>@Factory</literal> method is used (unless the
- component is stateless, in which case the <literal>EVENT</literal>
- context is used).
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — specifies the name of
- the context variable. If the method is a getter method,
- default to the JavaBeans property name.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>scope</literal> — specifies the scope
- that Seam should bind the returned value to. Only
- meaningful for factory methods which return a value.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>autoCreate</literal> — specifies that
- this factory method should be automatically called
- whenever the variable is asked for, even if
- <literal>@In</literal> does not specify
- <literal>create=true</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- This annotation lets you inject a <literal>Log</literal>:
- </para>
-
- <variablelist>
- <varlistentry id="logger-annotation">
- <term>
- <literal>@Logger</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Logger("categoryName")]]></programlisting>
- <para>
- Specifies that a component field is to be injected with an
- instance of <literal>org.jboss.seam.log.Log</literal>. For
- entity beans, the field must be declared as static.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — specifies the name of
- the log category. Default to the name of the component
- class.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- The last annotation lets you inject a request parameter value:
- </para>
-
- <variablelist>
- <varlistentry id="requestparameter-annotation">
- <term>
- <literal>@RequestParameter</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@RequestParameter("parameterName")]]></programlisting>
- <para>
- Specifies that a component attribute is to be injected with the
- value of a request parameter. Basic type conversions are
- performed automatically.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — specifies the name of
- the request parameter. Default to the name of the
- component attribute.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </section>
-
- <section>
- <title>Annotations for component lifecycle methods</title>
- <para>
- These annotations allow a component to react to its own lifecycle
- events. They occur on methods of the component. There may be only one
- of each per component class.
- </para>
-
- <variablelist>
- <varlistentry id="create-annotation">
- <term>
- <literal>@Create</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Create]]></programlisting>
- <para>
- Specifies that the method should be called when an instance of
- the component is instantiated by Seam. Note that create
- methods are only supported for JavaBeans and stateful session
- beans.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="destroy-annotation">
- <term>
- <literal>@Destroy</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Destroy]]></programlisting>
- <para>
- Specifies that the method should be called when the context
- ends and its context variables are destroyed. Note that
- destroy methods are only supported for JavaBeans and stateful session
- beans.
- </para>
- <para>
- Destroy methods should be used only for cleanup.
- <emphasis>Seam catches, logs and swallows any exception that
- propagates out of a destroy method.</emphasis>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="observer-annotation">
- <term>
- <literal>@Observer</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Observer("somethingChanged")]]></programlisting>
- <para>
- Specifies that the method should be called when a
- component-driven event of the specified type occurs.
- </para>
- <programlisting role="JAVA"><![CDATA[@Observer(value="somethingChanged",create=false)]]></programlisting>
- <para>
- Specifies that the method should be called when an event of
- the specified type occurs but that an instance should not be
- created if one doesn't exist. If an instance does not exist
- and create is false, the event will not be observed. The
- default value for create is true.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </section>
-
- <section>
- <title>Annotations for context demarcation</title>
- <para>
- These annotations provide declarative conversation demarcation. They
- appear on methods of Seam components, usually action listener methods.
- </para>
-
- <para>
- Every web request has a conversation context associated with it. Most
- of these conversations end at the end of the request. If you want a
- conversation that span multiple requests, you must "promote" the
- current conversation to a <emphasis>long-running conversation</emphasis>
- by calling a method marked with <literal>@Begin</literal>.
- </para>
-
- <variablelist id="begin-annotation">
- <varlistentry>
- <term>
- <literal>@Begin</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Begin]]></programlisting>
- <para>
- Specifies that a long-running conversation begins when this
- method returns a non-null outcome without exception.
- </para>
- <programlisting role="JAVA"><![CDATA[@Begin(join=true)]]></programlisting>
- <para>
- Specifies that if a long-running conversation is already in
- progress, the conversation context is simply propagated.
- </para>
- <programlisting role="JAVA"><![CDATA[@Begin(nested=true)]]></programlisting>
- <para>
- Specifies that if a long-running conversation is already in
- progress, a new <emphasis>nested</emphasis> conversation
- context begins. The nested conversation will end when the next
- <literal>@End</literal> is encountered, and the outer
- conversation will resume. It is perfectly legal for multiple
- nested conversations to exist concurrently in the same outer
- conversation.
- </para>
- <programlisting role="JAVA"><![CDATA[@Begin(pageflow="process definition name")]]></programlisting>
- <para>
- Specifies a jBPM process definition name that defines the
- pageflow for this conversation.
- </para>
- <programlisting role="JAVA"><![CDATA[@Begin(flushMode=FlushModeType.MANUAL)]]></programlisting>
- <para>
- Specify the flush mode of any Seam-managed persistence
- contexts. <literal>flushMode=FlushModeType.MANUAL</literal>
- supports the use of <emphasis>atomic conversations</emphasis>
- where all write operations are queued in the conversation
- context until an explicit call to <literal>flush()</literal>
- (which usually occurs at the end of the conversation).
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>join</literal> — determines the behavior
- when a long-running conversation is already in progress.
- If <literal>true</literal>, the context is propagated.
- If <literal>false</literal>, an exception is thrown.
- Default to <literal>false</literal>. This setting is
- ignored when <literal>nested=true</literal> is
- specified.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>nested</literal> — specifies that a
- nested conversation should be started if a long-running
- conversation is already in progress.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>flushMode</literal> — set the flush mode
- of any Seam-managed Hibernate sessions or JPA
- persistence contexts that are created during this
- conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pageflow</literal> — a process definition
- name of a jBPM process definition deployed via
- <literal>org.jboss.seam.bpm.jbpm.pageflowDefinitions.</literal>
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry id="end-annotation">
- <term>
- <literal>@End</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@End]]></programlisting>
- <para>
- Specifies that a long-running conversation ends when this
- method returns a non-null outcome without exception.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>beforeRedirect</literal> — by default,
- the conversation will not actually be destroyed until
- after any redirect has occurred. Setting
- <literal>beforeRedirect=true</literal> specifies that
- the conversation should be destroyed at the end of
- the current request, and that the redirect will be
- processed in a new temporary conversation context.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>root</literal> — by default,
- ending a nested conversation simply pops the conversation
- stack and resumes the outer conversation. Setting
- <literal>root=true</literal> specifies that the root
- conversation should be destroyed which effectively destroys
- the entire conversation stack. If the conversation is not
- nested, the current conversation is simply ended.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry id="starttask-annotation">
- <term>
- <literal>@StartTask</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@StartTask]]></programlisting>
- <para>
- "Starts" a jBPM task. Specifies that a long-running
- conversation begins when this method returns a non-null
- outcome without exception. This conversation is associated
- with the jBPM task specified in the named request
- parameter. Within the context of this conversation, a
- business process context is also defined, for the business
- process instance of the task instance.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The jBPM <literal>TaskInstance</literal> will be
- available in a request context variable named
- <literal>taskInstance</literal>. The jBPM
- <literal>ProcessInstance</literal> will be available
- in a request context variable named
- <literal>processInstance</literal>. (Of course, these
- objects are available for injection via
- <literal>@In</literal>.)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>taskIdParameter</literal> — the name
- of a request parameter which holds the id of the
- task. Default to <literal>"taskId"</literal>, which
- is also the default used by the Seam
- <literal>taskList</literal> JSF component.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>flushMode</literal> — set the flush
- mode of any Seam-managed Hibernate sessions or JPA
- persistence contexts that are created during this
- conversation.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
-
- <varlistentry id="begintask-annotation">
- <term>
- <literal>@BeginTask</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@BeginTask]]></programlisting>
- <para>
- Resumes work on an incomplete jBPM task. Specifies that a
- long-running conversation begins when this method returns a
- non-null outcome without exception. This conversation is
- associated with the jBPM task specified in the named
- request parameter. Within the context of this conversation,
- a business process context is also defined, for the
- business process instance of the task instance.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- The jBPM <literal>org.jbpm.taskmgmt.exe.TaskInstance</literal>
- will be available in a request context variable named
- <literal>taskInstance</literal>. The jBPM
- <literal>org.jbpm.graph.exe.ProcessInstance</literal>
- will be available in a request context variable named
- <literal>processInstance</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>taskIdParameter</literal> — the name
- of a request parameter which holds the id of the
- task. Default to <literal>"taskId"</literal>, which
- is also the default used by the Seam
- <literal>taskList</literal> JSF component.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>flushMode</literal> — set the flush
- mode of any Seam-managed Hibernate sessions or JPA
- persistence contexts that are created during this
- conversation.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry id="endtask-annotation">
- <term>
- <literal>@EndTask</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@EndTask]]></programlisting>
- <para>
- "Ends" a jBPM task. Specifies that a long-running
- conversation ends when this method returns a non-null
- outcome, and that the current task is complete. Triggers a
- jBPM transition. The actual transition triggered will be
- the default transition unless the application has called
- <literal>Transition.setName()</literal> on the built-in
- component named <literal>transition</literal>.
- </para>
- <programlisting role="JAVA"><![CDATA[@EndTask(transition="transitionName")]]></programlisting>
- <para>
- Triggers the given jBPM transition.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>transition</literal> — the name of the
- jBPM transition to be triggered when ending the task.
- Defaults to the default transition.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>beforeRedirect</literal> — by default,
- the conversation will not actually be destroyed until
- after any redirect has occurred. Setting
- <literal>beforeRedirect=true</literal> specifies that
- the conversation should be destroyed at the end of
- the current request, and that the redirect will be
- processed in a new temporary conversation context.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry id="createprocess-annotation">
- <term>
- <literal>@CreateProcess</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@CreateProcess(definition="process definition name")]]></programlisting>
- <para>
- Creates a new jBPM process instance when the method returns
- a non-null outcome without exception. The
- <literal>ProcessInstance</literal> object will be available
- in a context variable named
- <literal>processInstance</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>definition</literal> — the name of the
- jBPM process definition deployed via
- <literal>org.jboss.seam.bpm.jbpm.processDefinitions</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry id="resumeprocess-annotation">
- <term>
- <literal>@ResumeProcess</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@ResumeProcess(processIdParameter="processId")]]></programlisting>
- <para>
- Re-enters the scope of an existing jBPM process instance
- when the method returns a non-null outcome without
- exception. The <literal>ProcessInstance</literal> object
- will be available in a context variable named
- <literal>processInstance</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>processIdParameter</literal> — the name
- a request parameter holding the process id. Default to
- <literal>"processId"</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
-
- <varlistentry id="transition-annotation">
- <term>
- <literal>@Transition</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Transition("cancel")]]></programlisting>
- <para>
- Marks a method as signalling a transition in the current jBPM
- process instance whenever the method returns a non-null
- result.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>Annotations for use with Seam JavaBean components in a J2EE environment</title>
- <para>
- Seam provides an annotation that lets you force a rollback of the JTA
- transaction for certain action listener outcomes.
- </para>
-
- <variablelist>
- <varlistentry id="transactional-annotation">
- <term>
- <literal>@Transactional</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Transactional]]></programlisting>
- <para>
- Specifies that a JavaBean component should have a similar
- transactional behavior to the default behavior of a session
- bean component. ie. method invocations should take place in a
- transaction, and if no transaction exists when the method is
- called, a transaction will be started just for that method.
- This annotation may be applied at either class or method level.
- </para>
- <para>
- <emphasis>Do not use this annotation on EJB 3.0 components,
- use <literal>@TransactionAttribute</literal>!</emphasis>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>@ApplicationException</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@ApplicationException]]></programlisting>
- <para>
- Synonym for javax.ejb.ApplicationException, for use in a pre
- Java EE 5 environment. Applied to an exception to denote that
- it is an application exception and should be reported to the
- client directly(i.e., unwrapped).
- </para>
- <para>
- <emphasis>Do not use this annotation on EJB 3.0 components,
- use <literal>@javax.ejb.ApplicationException</literal>
- instead</emphasis>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>rollback</literal> — by default
- <literal>false</literal>, if <literal>true</literal>
- this exception should set the transaction to rollback
- only
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>end</literal> — by default
- <literal>false</literal>, if <literal>true</literal> this
- exception should end the current long-running
- conversation
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>@Interceptors</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Interceptors({DVDInterceptor, CDInterceptor})]]></programlisting>
- <para>
- Synonym for javax.interceptors.Interceptors, for use in a pre
- Java EE 5 environment. Note that this may only be used as a
- meta-annotation. Declares an ordered list of interceptors for
- a class or method.
- </para>
- <para>
- <emphasis>Do not use this annotations on EJB 3.0 components,
- use <literal>@javax.interceptor.Interceptors</literal>
- instead</emphasis>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- These annotations are mostly useful for JavaBean Seam components. If
- you use EJB 3.0 components, you should use the standard Java EE5
- annotation.
- </para>
- </section>
-
- <section>
- <title>Annotations for exceptions</title>
-
- <para>
- These annotations let you specify how Seam should handle an exception
- that propagates out of a Seam component.
- </para>
-
- <variablelist>
- <varlistentry id="redirect-annotation">
- <term>
- <literal>@Redirect</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Redirect(viewId="error.jsp")]]></programlisting>
- <para>
- Specifies that the annotated exception causes a browser
- redirect to a specified view id.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>viewId</literal> — specifies the JSF view
- id to redirect to. You can use EL here.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>message</literal> — a message to be
- displayed, default to the exception message.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>end</literal> — specifies that the
- long-running conversation should end, default to
- <literal>false</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry id="httperror-annotation">
- <term>
- <literal>@HttpError</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@HttpError(errorCode=404)]]></programlisting>
- <para>
- Specifies that the annotated exception causes a HTTP error to
- be sent.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>errorCode</literal> — the HTTP error
- code, default to <literal>500</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>message</literal> — a message to be sent
- with the HTTP error, default to the exception message.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>end</literal> — specifies that the
- long-running conversation should end, default to
- <literal>false</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>Annotations for Seam Remoting</title>
- <para>
- Seam Remoting requires that the local interface of a session bean be
- annotated with the following annotation:
- </para>
-
- <variablelist>
- <varlistentry id="webremote-annotation">
- <term>
- <literal>@WebRemote</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@WebRemote(exclude="path.to.exclude")]]></programlisting>
- <para>
- Indicates that the annotated method may be called from
- client-side JavaScript. The <literal>exclude</literal>
- property is optional and allows objects to be excluded from
- the result's object graph (see the <xref linkend="remoting"/> chapter for more
- details).
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </section>
-
- <section>
- <title>Annotations for Seam interceptors</title>
- <para>
- The following annotations appear on Seam interceptor classes.
- </para>
- <para>
- Please refer to the documentation for the EJB 3.0 specification for
- information about the annotations required for EJB interceptor definition.
- </para>
-
- <variablelist>
- <varlistentry id="interceptor-annotation">
- <term>
- <literal>@Interceptor</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Interceptor(stateless=true)]]></programlisting>
- <para>
- Specifies that this interceptor is stateless and Seam may
- optimize replication.
- </para>
- <programlisting role="JAVA"><![CDATA[@Interceptor(type=CLIENT)]]></programlisting>
- <para>
- Specifies that this interceptor is a "client-side"
- interceptor that is called before the EJB container.
- </para>
- <programlisting role="JAVA"><![CDATA[@Interceptor(around={SomeInterceptor.class, OtherInterceptor.class})]]></programlisting>
- <para>
- Specifies that this interceptor is positioned higher in
- the stack than the given interceptors.
- </para>
- <programlisting role="JAVA"><![CDATA[@Interceptor(within={SomeInterceptor.class, OtherInterceptor.class})]]></programlisting>
- <para>
- Specifies that this interceptor is positioned deeper in
- the stack than the given interceptors.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </section>
-
- <section>
- <title>Annotations for asynchronicity</title>
- <para>
- The following annotations are used to declare an asynchronous method,
- for example:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Asynchronous public void scheduleAlert(Alert alert, @Expiration Date date) { ... }]]></programlisting>
- <programlisting role="JAVA"><![CDATA[@Asynchronous public Timer scheduleAlerts(Alert alert,
- @Expiration Date date,
- @IntervalDuration long interval) { ... }]]></programlisting>
-
- <variablelist>
- <varlistentry id="asynchronous-annotation">
- <term>
- <literal>@Asynchronous</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Asynchronous]]></programlisting>
- <para>
- Specifies that the method call is processed asynchronously.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="duration-annotation">
- <term>
- <literal>@Duration</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Duration]]></programlisting>
- <para>
- Specifies that a parameter of the asynchronous call is the
- duration before the call is processed (or first processed for
- recurring calls).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="expiration-annotation">
- <term>
- <literal>@Expiration</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Expiration]]></programlisting>
- <para>
- Specifies that a parameter of the asynchronous call is the
- datetime at which the call is processed (or first processed
- for recurring calls).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="intervalduration-annotation">
- <term>
- <literal>@IntervalDuration</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@IntervalDuration]]></programlisting>
- <para>
- Specifies that an asynchronous method call recurs, and that
- the annotationed parameter is duration between recurrences.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>Annotations for use with JSF</title>
- <para>
- The following annotations make working with JSF easier.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>
- <literal>@Converter</literal>
- </term>
- <listitem>
- <para>
- Allows a Seam component to act as a JSF converter. The
- annotated class must be a Seam component, and must
- implement <literal>javax.faces.convert.Converter</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>id</literal> — the JSF converter id.
- Defaults to the component name.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>forClass</literal> — if specified,
- register this component as the default converter for
- a type.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>@Validator</literal>
- </term>
- <listitem>
- <para>
- Allows a Seam component to act as a JSF validator. The
- annotated class must be a Seam component, and must
- implement <literal>javax.faces.validator.Validator</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>id</literal> — the JSF validator id.
- Defaults to the component name.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <section>
- <title>Annotations for use with <literal>dataTable</literal></title>
- <para>
- The following annotations make it easy to implement clickable
- lists backed by a stateful session bean. They appear on
- attributes.
- </para>
+<chapter id="annotations" >
+ <title>Seam annotations</title>
+ <para>
+ Seam uses annotations to achieve a declarative style of programming. Most annotations are defined by the Enterprise JavaBean 3.0 (EJB3) specification, and the annotations used in data validation are defined by the Hibernate Validator package. However, Seam also defines its own set of annotations, which are described in this chapter.
+ </para>
+ <para>
+ All of these annotations are defined in the <literal>org.jboss.seam.annotations</literal> package.
+ </para>
+ <section>
+ <title>Annotations for component definition</title>
+ <para>
+ This group of annotations is used to define a Seam component. These annotations appear on the component class.
+ </para>
+ <variablelist>
+ <varlistentry id="name-annotation">
+ <term> <literal>@Name</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Name("componentName")]]></programlisting>
+ <para>
+ Defines the Seam component name for a class. This annotation is required for all Seam components.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="scope-annotation">
+ <term> <literal>@Scope</literal> </term>
+ <listitem>
+
+ <programlisting role="JAVA"><![CDATA[@Scope(ScopeType.CONVERSATION)
+ ]]></programlisting>
+ <para>
+ Defines the default context of the component. The possible values are defined by the <literal>ScopeType</literal> enumeration: <literal>EVENT</literal>, <literal>PAGE</literal>, <literal>CONVERSATION</literal>, <literal>SESSION</literal>, <literal>BUSINESS_PROCESS</literal>, <literal>APPLICATION</literal>, or <literal>STATELESS</literal>.
+ </para>
+ <para>
+ When no scope is explicitly specified, the default varies with the component type. For stateless session beans, the default is <literal>STATELESS</literal>. For entity beans and stateful session beans, the default is <literal>CONVERSATION</literal>. For JavaBeans, the default is <literal>EVENT</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="role-annotation">
+ <term> <literal>@Role</literal> </term>
+ <listitem>
+
+ <programlisting role="JAVA"><![CDATA[@Role(name="roleName", scope=ScopeType.SESSION)]]></programlisting>
+ <para>
+ Allows a Seam component to be bound to multiple context variables. The <literal>@Name</literal> and <literal>@Scope</literal> annotations define a <emphasis>default role</emphasis>. Each <literal>@Role</literal> annotation defines an additional role.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>name</literal> — the context variable name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>scope</literal> — the context variable scope. When no scope is explicitly specified, the default depends upon the component type, as above.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="roles-annotation">
+ <term> <literal>@Roles</literal> </term>
+ <listitem>
+
+ <programlisting role="JAVA"><![CDATA[@Roles({ @Role(name="user", scope=ScopeType.CONVERSATION),
+ @Role(name="currentUser", scope=ScopeType.SESSION) })
+ ]]></programlisting>
+ <para>
+ Allows you to specify multiple additional roles.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="intercept-annotation">
+ <term> <literal>@BypassInterceptors</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@BypassInterceptors
+]]></programlisting>
+ <para>
+ Disables all Seam interceptors on a particular component or component method.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="jndiname-annotation">
+ <term> <literal>@JndiName</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@JndiName("my/jndi/name")
+]]></programlisting>
+ <para>
+ Specifies the JNDI name that Seam will use to look up the EJB component. If no JNDI name is explicitly specified, Seam will use the JNDI pattern specified by <literal>org.jboss.seam.core.init.jndiPattern</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="conversational-annotation">
+ <term> <literal>@Conversational</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Conversational
+]]></programlisting>
+ <para>
+ Specifies that a conversation scope component is conversational, meaning that no method of the component may be called unless a long-running conversation is active.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="pernestedconversation-annotation">
+ <term> <literal>@PerNestedConversation</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@PerNestedConversation
+]]></programlisting>
+ <para>
+ Limits the scope of a conversation-scoped component to the parent conversation in which it was instantiated. The component instance will not be visible to nested child conversations, which will operate within their own instances.
+ </para>
+ <warning>
+ <para>
+ This is not a recommended application feature. It implies that a component will be visible only for a specific part of a request cycle.
+ </para>
+ </warning>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="startup-annotation">
+ <term> <literal>@Startup</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Scope(APPLICATION)
+ at Startup(depends="org.jboss.seam.bpm.jbpm")
+]]></programlisting>
+ <para>
+ Specifies that an application-scoped component will start immediately at initialization time. This is used for built-in components that bootstrap critical infrastructure, such as JNDI, datasources, etc.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Scope(SESSION)
+ at Startup
+]]></programlisting>
+ <para>
+ Specifies that a session-scoped component will start immediately at session creation time.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>depends</literal> — specifies that the named components must be started first, if they are installed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="install-annotation">
+ <term> <literal>@Install</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Install(false)
+]]></programlisting>
+ <para>
+ Specifies that a component should not be installed by default. (If you do not specify this annotation, the component will be installed.)
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Install(dependencies="org.jboss.seam.bpm.jbpm")
+]]></programlisting>
+ <para>
+ Specifies that a component should only be installed if the components listed as dependencies are also installed.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Install(genericDependencies=ManagedQueueSender.class)
+]]></programlisting>
+ <para>
+ Specifies that a component should only be installed if a component that is implemented by a certain class is installed. This is useful when a required dependency does not have a single well-known name.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Install(classDependencies="org.hibernate.Session")
+]]></programlisting>
+ <para>
+ Specifies that a component should only be installed if the named class is included on the classpath.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Install(precedence=BUILT_IN)
+]]></programlisting>
+ <para>
+ Specifies the precedence of the component. If multiple components with the same name exist, the one with the higher precedence will be installed. The defined precendence values are (in ascending order):
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>BUILT_IN</literal> — precedence of all built-in Seam components.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>FRAMEWORK</literal> — precedence to use for components of frameworks which extend Seam.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>APPLICATION</literal> — precedence of application components (the default precedence).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>DEPLOYMENT</literal> — precedence to use for components which override application components in a particular deployment.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>MOCK</literal> — precedence for mock objects used in testing.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="synchronized-annotation">
+ <term> <literal>@Synchronized</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Synchronized(timeout=1000)
+]]></programlisting>
+ <para>
+ Specifies that a component is accessed concurrently by multiple clients, and that Seam should serialize requests. If a request is not able to obtain its lock on the component in the given timeout period, an exception will be raised.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="readonly-annotation">
+ <term> <literal>@ReadOnly</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@ReadOnly
+]]></programlisting>
+ <para>
+ Specifies that a JavaBean component or component method does not require state replication at the end of the invocation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="autocreate-annotation">
+ <term> <literal>@AutoCreate</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@AutoCreate
+]]></programlisting>
+ <para>
+ Specifies that a component will be automatically created, even if the client does not specify <literal>create=true</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
- <variablelist>
- <varlistentry id="datamodel-annotation">
- <term>
- <literal>@DataModel</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@DataModel("variableName")]]></programlisting>
- <para>
- Outjects a property of type <literal>List</literal>,
- <literal>Map</literal>, <literal>Set</literal> or
- <literal>Object[]</literal> as a JSF
- <literal>DataModel</literal> into the scope of the owning
- component (or the <literal>EVENT</literal> scope if the
- owning component is <literal>STATELESS</literal>). In the
- case of <literal>Map</literal>, each row of the
- <literal>DataModel</literal> is a
- <literal>Map.Entry</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — name of the
- conversation context variable. Default to the
- attribute name.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>scope</literal> — if
- <literal>scope=ScopeType.PAGE</literal> is explicitly
- specified, the <literal>DataModel</literal> will be
- kept in the <literal>PAGE</literal> context.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry id="datamodelselection-annotation">
- <term>
- <literal>@DataModelSelection</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@DataModelSelection]]></programlisting>
- <para>
- Injects the selected value from the JSF
- <literal>DataModel</literal> (this is the element of the
- underlying collection, or the map value). If only one
- <literal>@DataModel</literal> attribute is defined for a
- component, the selected value from that
- <literal>DataModel</literal> will be injected. Otherwise,
- the component name of each
- <literal>@DataModel</literal> must be specified in the
- value attribute for each
- <literal>@DataModelSelection</literal>.
- </para>
- <para>
- If <literal>PAGE</literal> scope is specified on the
- associated <literal>@DataModel</literal>, then, in addition
- to the DataModel Selection being injected, the associated
- DataModel will also be injected. In this case, if the
- property annotated with <literal>@DataModel</literal> is
- a getter method, then a setter method for the property must
- also be part of the Business API of the containing Seam
- Component.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — name of the
- conversation context variable. Not needed if there is
- exactly one <literal>@DataModel</literal> in the
- component.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry id="datamodelselectionindex-annotation">
- <term>
- <literal>@DataModelSelectionIndex</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@DataModelSelectionIndex]]></programlisting>
- <para>
- Exposes the selection index of the JSF
- <literal>DataModel</literal> as an attribute of the
- component (this is the row number of the underlying
- collection, or the map key). If only one
- <literal>@DataModel</literal> attribute is defined for a
- component, the selected value from that
- <literal>DataModel</literal> will be injected. Otherwise,
- the component name of each <literal>@DataModel</literal>
- must be specified in the value attribute for each
- <literal>@DataModelSelectionIndex</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — name of the
- conversation context variable. Not needed if there
- is exactly one <literal>@DataModel</literal> in the
- component.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
- </section>
-
- <section>
- <title>Meta-annotations for databinding</title>
- <para>
- These meta-annotations make it possible to implement similar
- functionality to <literal>@DataModel</literal> and
- <literal>@DataModelSelection</literal> for other datastructures apart
- from lists.
- </para>
-
- <variablelist >
- <varlistentry id="databinderclass-annotation">
- <term>
- <literal>@DataBinderClass</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@DataBinderClass(DataModelBinder.class)]]></programlisting>
- <para>
- Specifies that an annotation is a databinding annotation.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry id="dataselectorclass-annotation">
- <term>
- <literal>@DataSelectorClass</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@DataSelectorClass(DataModelSelector.class)]]></programlisting>
- <para>
- Specifies that an annotation is a dataselection annotation.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>Annotations for packaging</title>
- <para>
- This annotation provides a mechanism for declaring information about a
- set of components that are packaged together. It can be applied to any
- Java package.
- </para>
-
-
- <variablelist>
- <varlistentry id="namespace-annotation">
- <term>
- <literal>@Namespace</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Namespace(value="http://jboss.com/products/seam/example/seampay")]]></programlisting>
- <para>
- Specifies that components in the current package are associated
- with the given namespace. The declared namespace can be used as
- an XML namespace in a <literal>components.xml</literal> file to
- simplify application configuration.
- </para>
- <programlisting role="JAVA"><![CDATA[@Namespace(value="http://jboss.com/products/seam/core", prefix="org.jboss.seam.core")]]></programlisting>
- <para>
- Specifies a namespace to associate with a given package.
- Additionally, it specifies a component name prefix to be
- applied to component names specified in the XML file. For
- example, an XML element named <literal>init</literal> that is
- associated with this namespace would be understood to actually
- refer to a component named
- <literal>org.jboss.seam.core.init</literal>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>Annotations for integrating with the servlet container</title>
- <para>
- These annotations allow you to integrate your Seam components with the
- servlet container.
- </para>
-
-
- <variablelist >
- <varlistentry>
- <term>
- <literal>@Filter</literal>
- </term>
- <listitem>
- <para>
- Use the Seam component (which implements
- <literal>javax.servlet.Filter</literal>) annotated with
- <literal>@Filter</literal> as a servlet filter. It will be
- executed by Seam's master filter.
- </para>
- <itemizedlist>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Filter(around={"seamComponent", "otherSeamComponent"})]]></programlisting>
- <para>
- Specifies that this filter is positioned higher in the
- stack than the given filters.
- </para>
- </listitem>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Filter(within={"seamComponent", "otherSeamComponent"})]]></programlisting>
- <para>
- Specifies that this filter is positioned deeper in the
- stack than the given filters.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- </section>
-
-
+ <section>
+ <title>Annotations for bijection</title>
+ <para>
+ The next two annotations control bijection. These attributes occur on component instance variables or property accessor methods.
+ </para>
+ <variablelist>
+ <varlistentry id="in-annotation">
+ <term> <literal>@In</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@In
+]]></programlisting>
+ <para>
+ Specifies that a component attribute is to be injected from a context variable at the beginning of each component invocation. If the context variable is null, an exception will be thrown.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In(required=false)
+]]></programlisting>
+ <para>
+ Specifies that a component attribute is to be injected from a context variable at the beginning of each component invocation. The context variable may be null.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In(create=true)
+]]></programlisting>
+ <para>
+ Specifies that a component attribute is to be injected from a context variable at the beginning of each component invocation. If the context variable is null, an instance of the component is instantiated by Seam.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In(value="contextVariableName")
+]]></programlisting>
+ <para>
+ Specifies the name of the context variable explicitly, instead of using the annotated instance variable name.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In(value="#{customer.addresses['shipping']}")
+]]></programlisting>
+ <para>
+ Specifies that a component attribute is to be injected by evaluating a JSF EL expression at the beginning of each component invocation.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — specifies the name of the context variable. Defaults to the name of the component attribute. Alternatively, specifies a JSF EL expression, surrounded by <literal>#{...}</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>create</literal> — specifies that Seam should instantiate the component with the same name as the context variable, if the context variable is undefined (null) in all contexts. Defaults to <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>required</literal> — specifies that Seam should throw an exception if the context variable is undefined in all contexts.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="out-annotation">
+ <term> <literal>@Out</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Out
+]]></programlisting>
+ <para>
+ Specifies that a component attribute that is a Seam component is to be outjected to its context variable at the end of the invocation. If the attribute is null, an exception is thrown.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Out(required=false)
+]]></programlisting>
+ <para>
+ Specifies that a component attribute that is a Seam component is to be outjected to its context variable at the end of the invocation. The attribute can be null.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Out(scope=ScopeType.SESSION)
+]]></programlisting>
+ <para>
+ Specifies that a component attribute that is <emphasis>not</emphasis> a Seam component type is to be outjected to a specific scope at the end of the invocation.
+ </para>
+ <para>
+ Alternatively, if no scope is explicitly specified, the scope of the component with the <literal>@Out</literal> attribute isused (or the <literal>EVENT</literal> scope if the component is stateless).
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Out(value="contextVariableName")
+]]></programlisting>
+ <para>
+ Specifies the name of the context variable explicitly, instead of using the annotated instance variable name.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — specifies the name of the context variable. Default to the name of the component attribute.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>required</literal> — specifies that Seam should throw an exception if the component attribute is null during outjection.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ These annotations commonly occur together, as in the following example:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In(create=true)
+ at Out private User currentUser;
+]]></programlisting>
+ <para>
+ The next annotation supports the <emphasis>manager component</emphasis> pattern, where a Seam component manages the lifecycle of an instance of some other class that is to be injected. It appears on a component getter method.
+ </para>
+ <variablelist>
+ <varlistentry id="unwrap-annotation">
+ <term> <literal>@Unwrap</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Unwrap
+]]></programlisting>
+ <para>
+ Specifies that the object returned by the annotated getter method will be injected instead of the component.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The next annotation supports the <emphasis>factory component</emphasis> pattern, in which a Seam component is responsible for initializing the value of a context variable. This is especially useful for initializing any state required to render a response to a non-Faces request. It appears on a component method.
+ </para>
+ <variablelist>
+ <varlistentry id="factory-annotation">
+ <term> <literal>@Factory</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Factory("processInstance")
+public void createProcessInstance() { ... }
+]]></programlisting>
+ <para>
+ Specifies that the component method be used to initialize the value of the named context variable, when the context variable has no value. This style is used with methods that return <literal>void</literal>.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Factory("processInstance", scope=CONVERSATION)
+public ProcessInstance createProcessInstance() { ... }
+]]></programlisting>
+ <para>
+ Specifies that the value returned by the method should be used to initialize the value of the named context variable, if the context variable has no value. This style is used with methods that return a value. If no scope is explicitly specified, the scope of the component with the <literal>@Factory</literal> method is used (unless the component is stateless, in which case the <literal>EVENT</literal> context is used).
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — specifies the name of the context variable. If the method is a getter method, this defaults to the JavaBeans property name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>scope</literal> — specifies the scope to which Seam should bind the returned value. Only meaningful for factory methods that return a value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>autoCreate</literal> — specifies that this factory method should be automatically called whenever the variable is asked for, even if <literal>@In</literal> does not specify <literal>create=true</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The following annotation lets you inject a <literal>Log</literal>:
+ </para>
+ <variablelist>
+ <varlistentry id="logger-annotation">
+ <term> <literal>@Logger</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Logger("categoryName")
+]]></programlisting>
+ <para>
+ Specifies that a component field is to be injected with an instance of <literal>org.jboss.seam.log.Log</literal>. For entity beans, the field must be declared as <literal>static</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — specifies the name of the log category. Defaults to the name of the component class.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The final annotation lets you inject a request parameter value:
+ </para>
+ <variablelist>
+ <varlistentry id="requestparameter-annotation">
+ <term> <literal>@RequestParameter</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@RequestParameter("parameterName")
+]]></programlisting>
+ <para>
+ Specifies that a component attribute is to be injected with the value of a request parameter. Basic type conversions are performed automatically.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — specifies the name of the request parameter. Defaults to the name of the component attribute.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Annotations for component lifecycle methods</title>
+ <para>
+ These annotations allow a component to react to its own lifecycle events. They occur on methods of the component. Only one of these annotations may be used in any one component class.
+ </para>
+ <variablelist>
+ <varlistentry id="create-annotation">
+ <term> <literal>@Create</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Create
+]]></programlisting>
+ <para>
+ Specifies that the method should be called when an instance of the component is instantiated by Seam. Create methods are only supported for JavaBeans and stateful session beans.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="destroy-annotation">
+ <term> <literal>@Destroy</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Destroy
+]]></programlisting>
+ <para>
+ Specifies that the method should be called when the context ends and its context variables are destroyed. Destroy methods are only supported for JavaBeans and stateful session beans.
+ </para>
+ <para>
+ Destroy methods should be used only for cleanup. Seam catches, logs and swallows any exception that propagates out of a destroy method.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="observer-annotation">
+ <term> <literal>@Observer</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Observer("somethingChanged")
+]]></programlisting>
+ <para>
+ Specifies that the method should be called when a component-driven event of the specified type occurs.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Observer(value="somethingChanged",create=false)
+]]></programlisting>
+ <para>
+ Specifies that the method should be called when an event of the specified type occurs, but that an instance should not be created if it does not already exist. If an instance does not exist and create is set to <literal>false</literal>, the event will not be observed. The default value is <literal>true</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Annotations for context demarcation</title>
+ <para>
+ These annotations provide declarative conversation demarcation. They appear on Seam component methods, usually action listener methods.
+ </para>
+ <para>
+ Every web request is associated with a conversation context. Most of these conversations end when the request is complete. To span a conversation across multiple requests, you must "promote" the conversation to a <emphasis>long-running conversation</emphasis> by calling a method marked with <literal>@Begin</literal>.
+ </para>
+ <variablelist>
+ <varlistentry id="begin-annotation">
+ <term> <literal>@Begin</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Begin
+]]></programlisting>
+ <para>
+ Specifies that a long-running conversation begins when this method returns a non-null outcome without exception.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Begin(join=true)
+]]></programlisting>
+ <para>
+ Specifies that, if a long-running conversation is already in progress, the conversation context is propagated.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Begin(nested=true)
+]]></programlisting>
+ <para>
+ Specifies that, if a long-running conversation is already in progress, a new <emphasis>nested</emphasis> conversation context should begin. The nested conversation will end when the next <literal>@End</literal> is encountered, and the outer conversation will resume. Multiple nested conversations can exist concurrently in the same outere conversation.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Begin(pageflow="process definition name")
+]]></programlisting>
+ <para>
+ Specifies a jBPM process definition name that defines the pageflow for this conversation.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Begin(flushMode=FlushModeType.MANUAL)
+]]></programlisting>
+ <para>
+ Specifies the flush mode of any Seam-managed persistence contexts. <literal>flushMode=FlushModeType.MANUAL</literal> supports the use of <emphasis>atomic conversations</emphasis>, where all write operations are queued in the conversation context until an explicit call to <literal>flush()</literal> (which usually occurs at the end of the conversation) is made.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>join</literal> — determines the behavior when a long-running conversation is already in progress. If <literal>true</literal>, the context is propagated. If <literal>false</literal>, an exception is thrown. Defaults to <literal>false</literal>. This setting is ignored when <literal>nested=true</literal> is specified.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>nested</literal> — specifies that a nested conversation should be started if a long-running conversation is already in progress.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>flushMode</literal> — sets the flush mode of any Seam-managed Hibernate sessions or JPA persistence contexts that are created during this conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pageflow</literal> — the name of a jBPM process definition deployed via <literal>org.jboss.seam.bpm.jbpm.pageflowDefinitions</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="end-annotation">
+ <term> <literal>@End</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@End
+]]></programlisting>
+ <para>
+ Specifies that a long-running conversation ends when this method returns a non-null outcome without exception.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>beforeRedirect</literal> — by default, the conversation will not actually be destroyed until after any redirect has occurred. Setting <literal>beforeRedirect=true</literal> specifies that the conversation should be destroyed at the end of the current request, and that the redirect will be processed in a new temporary conversation context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>root</literal> — by default, ending a nested conversation simply pops the conversation stack and resumes the outer conversation. Setting <literal>root=true</literal> specifies that the root conversation should be destroyed, which destroys the entire conversation stack. If the conversation is not nested, the current conversation is destroyed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="starttask-annotation">
+ <term> <literal>@StartTask</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@StartTask
+]]></programlisting>
+ <para>
+ Starts a jBPM task. Specifies that a long-running conversation begins when this method returns a non-null outcome without exception. This conversation is associated with the jBPM task specified in the named request parameter. Within the context of this conversation, a business process context is also defined, for the business process instance of the task instance.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The jBPM <literal>TaskInstance</literal> is available in the <literal>taskInstance</literal> request context variable. The jBPM <literal>ProcessInstance</literal> is available in the <literal>processInstance</literal> request context variable. These objects can be injected with <literal>@In</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>taskIdParameter</literal> — the name of a request parameter which holds the task ID. Default to <literal>"taskId"</literal>, which is also the default used by the Seam <literal>taskList</literal> JSF component.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>flushMode</literal> — sets the flush mode of any Seam-managed Hibernate sessions or JPA persistence contexts that are created during this conversation.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="begintask-annotation">
+ <term> <literal>@BeginTask</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@BeginTask
+]]></programlisting>
+ <para>
+ Resumes work on an incomplete jBPM task. Specifies that a long-running conversation begins when this method returns a non-null outcome without exception. This conversation is associated with the jBPM task specified in the named request parameter. Within the context of this conversation, a business process context is also defined, for the business process instance of the task instance.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The jBPM <literal>org.jbpm.taskmgmt.exe.TaskInstance</literal> is available in the <literal>taskInstance</literal> request context variable. The jBPM <literal>org.jbpm.graph.exe.ProcessInstance</literal> is available in the <literal>processInstance</literal> request context variable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>taskIdParameter</literal> — the name of a request parameter which holds the ID of the task. Defaults to <literal>"taskId"</literal>, which is also the default used by the Seam <literal>taskList</literal> JSF component.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>flushMode</literal> — sets the flush mode of any Seam-managed Hibernate sessions or JPA persistence contexts that are created during this conversation.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="endtask-annotation">
+ <term> <literal>@EndTask</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@EndTask
+]]></programlisting>
+ <para>
+ Ends a jBPM task. Specifies that a long-running conversation ends when this method returns a non-null outcome, and that the current task is complete. Triggers a jBPM transition. The actual transition triggered will be the default transition unless the application has called <literal>Transition.setName()</literal> on the built-in component named <literal>transition</literal>.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@EndTask(transition="transitionName")
+]]></programlisting>
+ <para>
+ Triggers the specified jBPM transition.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>transition</literal> — the name of the jBPM transition to be triggered when ending the task. Defaults to the default transition.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>beforeRedirect</literal> — by default, the conversation will not actually be destroyed until after any redirect has occurred. Setting <literal>beforeRedirect=true</literal> specifies that the conversation should be destroyed at the end of the current request, and that the redirect will be processed in a new temporary conversation context.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="createprocess-annotation">
+ <term> <literal>@CreateProcess</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@CreateProcess(definition="process definition name")
+]]></programlisting>
+ <para>
+ Creates a new jBPM process instance when the method returns a non-null outcome without exception. The <literal>ProcessInstance</literal> object will be available in a context variable named <literal>processInstance</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>definition</literal> — the name of the jBPM process definition deployed via <literal>org.jboss.seam.bpm.jbpm.processDefinitions</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="resumeprocess-annotation">
+ <term> <literal>@ResumeProcess</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@ResumeProcess(processIdParameter="processId")
+]]></programlisting>
+ <para>
+ Re-enters the scope of an existing jBPM process instance when the method returns a non-null outcome without exception. The <literal>ProcessInstance</literal> object will be available in a context variable named <literal>processInstance</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>processIdParameter</literal> — the name of the request parameter that holds the process ID. Defaults to <literal>"processId"</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="transition-annotation">
+ <term> <literal>@Transition</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Transition("cancel")
+]]></programlisting>
+ <para>
+ Marks a method as signalling a transition in the current jBPM process instance whenever the method returns a non-null result.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Annotations for use with Seam JavaBean components in a J2EE environment</title>
+ <para>
+ Seam provides an annotation that lets you force a rollback of the JTA transaction for certain action listener outcomes.
+ </para>
+ <variablelist>
+ <varlistentry id="transactional-annotation">
+ <term> <literal>@Transactional</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Transactional
+]]></programlisting>
+ <para>
+ Specifies that a JavaBean component should have similar transactional behavior to the default behavior of a session bean component. That is, method invocations should take place in a transaction, and if no transaction exists when the method is called, a transaction will be started just for that method. This annotation can be applied at either class or method level.
+ </para>
+ <note>
+ <para>
+ This annotation should not be used on EJB3 components — use <literal>@TransactionAttribute</literal> instead.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <literal>@ApplicationException</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@ApplicationException
+]]></programlisting>
+ <para>
+ Applied to an exception to denote that it is an application exception and should be reported to the client directly — that is, unwrapped. Operates identically to <literal>javax.ejb.ApplicationException</literal> when used in a pre-Java EE 5 environment.
+ </para>
+ <note>
+ <para>
+ This annotation should not be used on EJB3 components — use <literal>@javax.ejb.ApplicationException</literal> instead.
+ </para>
+ </note>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>rollback</literal> — by default <literal>false</literal>, if <literal>true</literal> this exception sets the transaction to rollback only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>end</literal> — by default <literal>false</literal>, if <literal>true</literal>, this exception ends the current long-running conversation.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <literal>@Interceptors</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Interceptors({DVDInterceptor, CDInterceptor})
+]]></programlisting>
+ <para>
+ Declares an ordered list of interceptors for a class or method. Operates identically to <literal>javax.interceptors.Interceptors</literal> when used in a pre-Java EE 5 environment. Note that this may only be used as a meta-annotation.
+ </para>
+ <note>
+ <para>
+ This annotation should not be used on EJB3 components — use <literal>@javax.interceptor.Interceptors</literal> instead.
+ </para>
+ </note>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ These annotations are used primarily for JavaBean Seam components. If you use EJB3 components, you should use the standard Java EE 5 annotations.
+ </para>
+ </section>
+
+ <section>
+ <title>Annotations for exceptions</title>
+ <para>
+ These annotations let you specify how Seam handles any exceptions propagating from a Seam component.
+ </para>
+ <variablelist>
+ <varlistentry id="redirect-annotation">
+ <term> <literal>@Redirect</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Redirect(viewId="error.jsp")
+]]></programlisting>
+ <para>
+ Specifies that the annotated exception causes a browser redirect to a specified view ID.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>viewId</literal> — specifies the JSF view ID to redirect to. You can use EL here.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>message</literal> — a message to be displayed. Defaults to the exception message.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>end</literal> — specifies that the long-running conversation should end. Defaults to <literal>false</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="httperror-annotation">
+ <term> <literal>@HttpError</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@HttpError(errorCode=404)
+]]></programlisting>
+ <para>
+ Specifies that the annotated exception causes a HTTP error to be sent.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>errorCode</literal> — the HTTP error code. Defaults to <literal>500</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>message</literal> — a message to be sent with the HTTP error. Defaults to the exception message.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>end</literal> — specifies that the long-running conversation should end. Defaults to <literal>false</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Annotations for Seam Remoting</title>
+ <para>
+ Seam Remoting requires that the local interface of a session bean be annotated with the following annotation:
+ </para>
+ <variablelist>
+ <varlistentry id="webremote-annotation">
+ <term> <literal>@WebRemote</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@WebRemote(exclude="path.to.exclude")
+]]></programlisting>
+ <para>
+ Indicates that the annotated method may be called from client-side JavaScript. The <literal>exclude</literal> property is optional, and allows objects to be excluded from the result's object graph. (See the <xref linkend="remoting" /> chapter for more details.)
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Annotations for Seam interceptors</title>
+ <para>
+ The following annotations appear on Seam interceptor classes.
+ </para>
+ <para>
+ Please refer to the documentation for the EJB3 specification for information about the annotations required to define EJB interceptors.
+ </para>
+ <variablelist>
+ <varlistentry id="interceptor-annotation">
+ <term> <literal>@Interceptor</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Interceptor(stateless=true)
+]]></programlisting>
+ <para>
+ Specifies that this interceptor is stateless and Seam may optimize replication.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Interceptor(type=CLIENT)
+]]></programlisting>
+ <para>
+ Specifies that this interceptor is a "client-side" interceptor, called prior to the EJB container.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Interceptor(around={SomeInterceptor.class, OtherInterceptor.class})
+]]></programlisting>
+ <para>
+ Specifies that this interceptor is positioned higher in the stack than the given interceptors.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Interceptor(within={SomeInterceptor.class, OtherInterceptor.class})
+]]></programlisting>
+ <para>
+ Specifies that this interceptor is positioned deeper in the stack than the given interceptors.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Annotations for asynchronicity</title>
+ <para>
+ The following annotations are used to declare an asynchronous method, as in the following example:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Asynchronous public void scheduleAlert(Alert alert,
+ @Expiration Date date) {
+ ...
+}
+]]>
+</programlisting>
+
+<programlisting role="JAVA"><![CDATA[@Asynchronous public Timer scheduleAlerts(Alert alert,
+ @Expiration Date date,
+ @IntervalDuration long interval) {
+ ...
+}
+]]></programlisting>
+ <variablelist>
+ <varlistentry id="asynchronous-annotation">
+ <term> <literal>@Asynchronous</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Asynchronous
+]]></programlisting>
+ <para>
+ Specifies that the method call is processed asynchronously.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="duration-annotation">
+ <term> <literal>@Duration</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Duration
+]]></programlisting>
+ <para>
+ Specifies the parameter of the asynchronous call that relates to the duration before the call is processed (or first processed, for recurring calls).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="expiration-annotation">
+ <term> <literal>@Expiration</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Expiration
+]]></programlisting>
+ <para>
+ Specifies the parameter of the asynchronous call that relates to the date and time at which the call is processed (or first processed, for recurring calls).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="intervalduration-annotation">
+ <term> <literal>@IntervalDuration</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@IntervalDuration
+]]></programlisting>
+ <para>
+ Specifies that an asynchronous method call recurs. The associated parameter defines the duration of the interval between recurrences.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Annotations for use with JSF</title>
+ <para>
+ The following annotations make it easier to work with JSF.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term> <literal>@Converter</literal> </term>
+ <listitem>
+ <para>
+ Allows a Seam component to act as a JSF converter. The annotated class must be a Seam component, and must implement <literal>javax.faces.convert.Converter</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>id</literal> — the JSF converter ID. Defaults to the component name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>forClass</literal> — if specified, registers this component as the default converter for a type.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <literal>@Validator</literal> </term>
+ <listitem>
+ <para>
+ Allows a Seam component to act as a JSF validator. The annotated class must be a Seam component, and must implement <literal>javax.faces.validator.Validator</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>id</literal> — the JSF validator ID. Defaults to the component name.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <section>
+ <title>Annotations for use with <literal>dataTable</literal></title>
+ <para>
+ The following annotations make it easy to implement clickable lists backed by a stateful session bean. They appear on attributes.
+ </para>
+ <variablelist>
+ <varlistentry id="datamodel-annotation">
+ <term> <literal>@DataModel</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@DataModel("variableName")
+]]></programlisting>
+ <para>
+ Outjects a property of type <literal>List</literal>, <literal>Map</literal>, <literal>Set</literal> or <literal>Object[]</literal> as a JSF <literal>DataModel</literal> into the scope of the owning component (or the <literal>EVENT</literal> scope, if the owning component is <literal>STATELESS</literal>). In the case of <literal>Map</literal>, each row of the <literal>DataModel</literal> is a <literal>Map.Entry</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — name of the conversation context variable. Default to the attribute name.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>scope</literal> — if <literal>scope=ScopeType.PAGE</literal> is explicitly specified, the <literal>DataModel</literal> will be kept in the <literal>PAGE</literal> context.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="datamodelselection-annotation">
+ <term> <literal>@DataModelSelection</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@DataModelSelection
+]]></programlisting>
+ <para>
+ Injects the selected value from the JSF <literal>DataModel</literal>. (This is the element of the underlying collection, or the map value.) If only one <literal>@DataModel</literal> attribute is defined for a component, the selected value from that <literal>DataModel</literal> will be injected. Otherwise, the component name of each <literal>@DataModel</literal> must be specified in the value attribute for each <literal>@DataModelSelection</literal>.
+ </para>
+ <para>
+ If <literal>PAGE</literal> scope is specified on the associated <literal>@DataModel</literal>, then the associated DataModel will be injected in addition to the DataModel Selection. In this case, if the property annotated with <literal>@DataModel</literal> is a getter method, then a setter method for the property must also be part of the Business API of the containing Seam Component.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — name of the conversation context variable. Not needed if there is exactly one <literal>@DataModel</literal> in the component.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="datamodelselectionindex-annotation">
+ <term> <literal>@DataModelSelectionIndex</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@DataModelSelectionIndex
+]]></programlisting>
+ <para>
+ Exposes the selection index of the JSF <literal>DataModel</literal> as an attribute of the component. (This is the row number of the underlying collection, or the map key.) If only one <literal>@DataModel</literal> attribute is defined for a component, the selected value from that <literal>DataModel</literal> will be injected. Otherwise, the component name of each <literal>@DataModel</literal> must be specified in the value attribute for each <literal>@DataModelSelectionIndex</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — name of the conversation context variable. This is not required if there is exactly one <literal>@DataModel</literal> in the component.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Meta-annotations for databinding</title>
+ <para>
+ These meta-annotations make it possible to implement similar functionality to <literal>@DataModel</literal> and <literal>@DataModelSelection</literal> for other datastructures apart from lists.
+ </para>
+ <variablelist>
+ <varlistentry id="databinderclass-annotation">
+ <term> <literal>@DataBinderClass</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@DataBinderClass(DataModelBinder.class)
+]]></programlisting>
+ <para>
+ Specifies that an annotation is a databinding annotation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry id="dataselectorclass-annotation">
+ <term> <literal>@DataSelectorClass</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@DataSelectorClass(DataModelSelector.class)
+]]></programlisting>
+ <para>
+ Specifies that an annotation is a dataselection annotation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Annotations for packaging</title>
+ <para>
+ This annotation provides a mechanism for declaring information about a set of components that are packaged together. It can be applied to any Java package.
+ </para>
+ <variablelist>
+ <varlistentry id="namespace-annotation">
+ <term> <literal>@Namespace</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Namespace(value="http://jboss.com/products/seam/example/seampay")
+]]></programlisting>
+ <para>
+ Specifies that components in the current package are associated with the given namespace. The declared namespace can be used as an XML namespace in a <filename>components.xml</filename> file to simplify application configuration.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Namespace(value="http://jboss.com/products/seam/core",
+ prefix="org.jboss.seam.core")
+]]>
+</programlisting>
+ <para>
+ Specifies a namespace to associate with a given package. Additionally, it specifies a component name prefix to be applied to component names specified in the XML file. For example, an XML element named <literal>init</literal> that is associated with this namespace would be understood to actually refer to a component named <literal>org.jboss.seam.core.init</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Annotations for integrating with the Servlet container</title>
+ <para>
+ These annotations allow you to integrate your Seam components with the Servlet container.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term> <literal>@Filter</literal> </term>
+ <listitem>
+ <para>
+ When used to annotate a Seam component implementing <literal>javax.servlet.Filter</literal>, designates that component as a servlet filter to be executed by Seam's master filter.
+ </para>
+ <itemizedlist>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Filter(around={"seamComponent", "otherSeamComponent"})
+]]></programlisting>
+ <para>
+ Specifies that this filter is positioned higher in the stack than the given filters.
+ </para>
+ </listitem>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Filter(within={"seamComponent", "otherSeamComponent"})
+]]></programlisting>
+ <para>
+ Specifies that this filter is positioned deeper in the stack than the given filters.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Author_Group.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Author_Group.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Author_Group.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,132 +1,137 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE authorgroup PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<authorgroup>
- <author>
- <firstname>Gavin</firstname>
- <surname>King</surname>
- </author>
- <author>
- <firstname>Pete</firstname>
- <surname>Muir</surname>
- </author>
- <author>
- <firstname>Norman</firstname>
- <surname>Richards</surname>
- </author>
- <author>
- <firstname>Shane</firstname>
- <surname>Bryzak</surname>
- </author>
- <author>
- <firstname>Michael</firstname>
- <surname>Yuan</surname>
- </author>
- <author>
- <firstname>Mike</firstname>
- <surname>Youngstrom</surname>
- </author>
- <author>
- <firstname>Christian</firstname>
- <surname>Bauer</surname>
- </author>
- <author>
- <firstname>Jay</firstname>
- <surname>Balunas</surname>
- </author>
- <author>
- <firstname>Dan</firstname>
- <surname>Allen</surname>
- </author>
- <author>
- <firstname>Max</firstname>
- <othername>Rydahl</othername>
- <surname>Andersen</surname>
- </author>
- <author>
- <firstname>Emmanuel</firstname>
- <surname>Bernard</surname>
- </author>
- <author>
- <firstname>Nicklas</firstname>
- <surname>Karlsson</surname>
- </author>
- <author>
- <firstname>Daniel</firstname>
- <surname>Roth</surname>
- </author>
- <author>
- <firstname>Matt</firstname>
- <surname>Drees</surname>
- </author>
- <author>
- <firstname>Jacob</firstname>
- <surname>Orshalick</surname>
- </author>
- <author>
- <firstname>Marek</firstname>
- <surname>Novotny</surname>
- </author>
- <othercredit>
- <firstname>James</firstname>
- <surname>Cobb</surname>
- <affiliation>
- <shortaffil>Graphic Design</shortaffil>
- </affiliation>
- </othercredit>
- <othercredit>
- <firstname>Cheyenne</firstname>
- <surname>Weaver</surname>
- <affiliation>
- <shortaffil>Graphic Design</shortaffil>
- </affiliation>
- </othercredit>
- <othercredit>
- <firstname>Mark</firstname>
- <surname>Newton</surname>
- </othercredit>
- <othercredit>
- <firstname>Steve</firstname>
- <surname>Ebersole</surname>
- </othercredit>
- <othercredit>
- <firstname>Michael</firstname>
- <surname>Courcy</surname>
- <affiliation>
- <shortaffil>French Translation</shortaffil>
- </affiliation>
- </othercredit>
- <othercredit>
- <firstname>Nicola</firstname>
- <surname>Benaglia</surname>
- <affiliation>
- <shortaffil>Italian Translation</shortaffil>
- </affiliation>
- </othercredit>
- <othercredit>
- <firstname>Stefano</firstname>
- <surname>Travelli</surname>
- <affiliation>
- <shortaffil>Italian Translation</shortaffil>
- </affiliation>
- </othercredit>
- <othercredit>
+
+<authorgroup >
+ <author>
+ <firstname>Gavin</firstname>
+ <surname>King</surname>
+ </author>
+ <author>
+ <firstname>Pete</firstname>
+ <surname>Muir</surname>
+ </author>
+ <author>
+ <firstname>Norman</firstname>
+ <surname>Richards</surname>
+ </author>
+ <author>
+ <firstname>Shane</firstname>
+ <surname>Bryzak</surname>
+ </author>
+ <author>
+ <firstname>Michael</firstname>
+ <surname>Yuan</surname>
+ </author>
+ <author>
+ <firstname>Mike</firstname>
+ <surname>Youngstrom</surname>
+ </author>
+ <author>
+ <firstname>Christian</firstname>
+ <surname>Bauer</surname>
+ </author>
+ <author>
+ <firstname>Jay</firstname>
+ <surname>Balunas</surname>
+ </author>
+ <author>
+ <firstname>Dan</firstname>
+ <surname>Allen</surname>
+ </author>
+ <author>
+ <firstname>Max</firstname>
+ <othername>Rydahl</othername>
+ <surname>Andersen</surname>
+ </author>
+ <author>
+ <firstname>Emmanuel</firstname>
+ <surname>Bernard</surname>
+ </author>
+ <author>
+ <firstname>Nicklas</firstname>
+ <surname>Karlsson</surname>
+ </author>
+ <author>
+ <firstname>Daniel</firstname>
+ <surname>Roth</surname>
+ </author>
+ <author>
+ <firstname>Matt</firstname>
+ <surname>Drees</surname>
+ </author>
+ <author>
+ <firstname>Jacob</firstname>
+ <surname>Orshalick</surname>
+ </author>
+ <author>
+ <firstname>Marek</firstname>
+ <surname>Novotny</surname>
+ </author>
+ <othercredit>
+ <firstname>James</firstname>
+ <surname>Cobb</surname>
+ <affiliation>
+ <shortaffil>Graphic Design</shortaffil>
+ </affiliation>
+ </othercredit>
+ <othercredit>
+ <firstname>Cheyenne</firstname>
+ <surname>Weaver</surname>
+ <affiliation>
+ <shortaffil>Graphic Design</shortaffil>
+ </affiliation>
+ </othercredit>
+ <othercredit>
+ <firstname>Mark</firstname>
+ <surname>Newton</surname>
+ </othercredit>
+ <othercredit>
+ <firstname>Steve</firstname>
+ <surname>Ebersole</surname>
+ </othercredit>
+ <othercredit>
+ <firstname>Michael</firstname>
+ <surname>Courcy</surname>
+ <affiliation>
+ <shortaffil>French Translation</shortaffil>
+ </affiliation>
+ </othercredit>
+ <othercredit>
+ <firstname>Nicola</firstname>
+ <surname>Benaglia</surname>
+ <affiliation>
+ <shortaffil>Italian Translation</shortaffil>
+ </affiliation>
+ </othercredit>
+ <othercredit>
+ <firstname>Stefano</firstname>
+ <surname>Travelli</surname>
+ <affiliation>
+ <shortaffil>Italian Translation</shortaffil>
+ </affiliation>
+ </othercredit>
+ <othercredit>
<firstname>Francesco</firstname>
<surname>Milesi</surname>
<affiliation>
<shortaffil>Italian Translation</shortaffil>
</affiliation>
</othercredit>
- <othercredit>
- <firstname>Japan</firstname>
- <surname>JBoss User Group</surname>
- <affiliation>
- <shortaffil>Japanese Translation</shortaffil>
- </affiliation>
- </othercredit>
- <editor>
- <firstname>Samson</firstname>
- <surname>Kittoli</surname>
- </editor>
-
+ <othercredit>
+ <firstname>Japan</firstname>
+ <surname>JBoss User Group</surname>
+ <affiliation>
+ <shortaffil>Japanese Translation</shortaffil>
+ </affiliation>
+ </othercredit>
+ <editor>
+ <firstname>Samson</firstname>
+ <surname>Kittoli</surname>
+ </editor>
+ <editor>
+ <firstname>Laura</firstname>
+ <surname>Bailey</surname>
+ </editor>
</authorgroup>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Book_Info.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Book_Info.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Book_Info.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,10 +1,38 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<bookinfo>
- <title>Seam - Contextual Components</title>
- <subtitle>A Framework for Enterprise Java</subtitle>
- <xi:include href="Version_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+<bookinfo id="Seam_Reference_Guide">
+ <title>Seam Reference Guide</title>
+ <subtitle>for Use with JBoss Enterprise Application Platform 5.0.1</subtitle>
+ <edition>2.0</edition>
+ <pubsnumber>1.2</pubsnumber>
+ <productname>JBoss Enterprise Application Platform</productname>
+ <productnumber>5.0.1</productnumber>
+<!-- <pubdate>Sep, 2007</pubdate> -->
+ <isbn>N/A</isbn>
+ <abstract><para>This book is a Reference Guide for JBoss Enterprise Application Platform 5.0.1</para>
+ </abstract>
+ <corpauthor>
+ <inlinemediaobject>
+ <imageobject>
+ <imagedata fileref="Common_Content/images/title_logo.svg" />
+ </imageobject>
+ </inlinemediaobject>
+ </corpauthor>
+ <copyright>
+ <year>&YEAR;</year>
+ <holder>&HOLDER;</holder>
+ </copyright>
+ <!-- Comment it out -->
+ <xi:include href="Version_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Common_Content/Legal_Notice.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <!--FOR JDOCBOOK:-->
+ <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude">
+ <xi:include href="fallback_content/Legal_Notice.xml"
+ xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include>
+ </xi:fallback>
+ </xi:include>
+ <xi:include href="Author_Group.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
</bookinfo>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Cache.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Cache.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Cache.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,318 +1,208 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="cache">
- <title>Caching</title>
+<chapter id="cache" >
+ <title>Caching</title>
+ <para>
+ The database is the primary bottleneck in almost all enterprise applications, and the least-scalable tier of the runtime environment, so anything we can do to reduce the number of times the database is accessed can dramatically improve application performance.
+ </para>
+ <para>
+ A well-designed Seam application will feature a rich, multi-layered caching strategy that impacts every layer of the application, including:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A cache for the database. This is vital, but cannot scale like a cache in the application tier.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A secondary cache of data from the database, provided by your ORM solution (Hibernate, or another JPA implementation). In a clustered environment, keeping cache data transactionally consistent with both the database and the rest of the cluster can be very expensive to implement effectively. Therefore, this secondary cache is best used to store data that is rarely updated, and shared between many users. In traditional stateless architectures, this space is often used (ineffectively) to store conversational state.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Seam conversational context, which is a cache of conversational state. Components in the conversation context store state relating to the current user interaction.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Seam-managed persistence context, which acts as a cache of data read in the current conversation. (An Enterprise JavaBean [EJB] container-managed persistence context associated with a conversation-scoped stateful session bean can be used in place of a Seam-managed persistence context.) Seam optimizes the replication of Seam-managed persistence contexts in a clustered environment, and optimistic locking provides sufficient transactional consistency with the database. Unless you read thousands of objects into a single persistence context, the performance implications of this cache are minimal.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Seam application context, which can be used to cache non-transactional state. State held here is not visible to other nodes in the cluster.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Seam <literal>cacheProvider</literal> component within the application, which integrates JBossCache or EHCache into the Seam environment. State held here is visible to other nodes if your cache supports running in clustered mode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Finally, Seam can cache rendered fragments of a JSF page. Unlike the ORM secondary cache, this is not automatically invalidated when data is updated, so you will need to write application code to perform explicit invalidation, or set appropriate expiry policies.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ For more information about the secondary cache, you will need to refer to the documentation of your ORM solution, since this can be quite complex. In this section, we discuss the use of caching directly via the <literal>cacheProvider</literal> component, or caching as stored page fragments, via the <literal><s:cache></literal> control.
+ </para>
+ <section>
+ <title>Using Caching in Seam</title>
+ <para>
+ The built-in <literal>cacheProvider</literal> component manages an instance of:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term> JBoss Cache 3.2.x </term>
+ <listitem>
+ <para>
+ <literal>org.jboss.cache.Cache</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> EHCache </term>
+ <listitem>
+ <para>
+ <literal>net.sf.ehcache.CacheManager</literal>
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ Any immutable Java object placed in the cache will be stored there and replicated across the cluster (if replication is supported and enabled). To keep mutable objects in the cache, read the underlying caching project documentation for information about notifying the cache of changes made to stored objects.
+ </para>
+ <para>
+ To use <literal>cacheProvider</literal>, you need to include the JARs of the cache implementation in your project:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term> JBoss Cache 3.2.x </term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>jbosscache-core.jar</literal> - JBoss Cache 3.2.x
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>jgroups.jar</filename> — JGroups 2.6.x
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> EHCache </term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename>ehcache.jar</filename> — EHCache 1.2.3
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
- <para>
- In almost all enterprise applications, the database is the primary
- bottleneck, and the least scalable tier of the runtime environment. People
- from a PHP/Ruby environment will try to tell you that so-called "shared
- nothing" architectures scale well. While that may be literally true, I
- don't know of many interesting multi-user applications which can be
- implemented with no sharing of resources between different nodes of the
- cluster. What these silly people are really thinking of is a "share
- nothing except for the database" architecture. Of course, sharing the
- database is the primary problem with scaling a multi-user
- application — so the claim that this architecture is highly scalable
- is absurd, and tells you a lot about the kind of applications that these
- folks spend most of their time working on.
- </para>
-
- <para>
- Almost anything we can possibly do to share the database
- <emphasis>less often</emphasis> is worth doing.
- </para>
-
- <para>
- This calls for a cache. Well, not just one cache. A well designed Seam
- application will feature a rich, multi-layered caching strategy that
- impacts every layer of the application:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- The database, of course, has its own cache. This is super-important,
- but can't scale like a cache in the application tier.
- </para>
- </listitem>
- <listitem>
- <para>
- Your ORM solution (Hibernate, or some other JPA implementation) has
- a second-level cache of data from the database. This is a very
- powerful capability, but is often misused. In a clustered
- environment, keeping the data in the cache transactionally
- consistent across the whole cluster, and with the database, is quite
- expensive. It makes most sense for data which is shared between many
- users, and is updated rarely. In traditional stateless
- architectures, people often try to use the second-level cache for
- conversational state. This is always bad, and is especially wrong in
- Seam.
- </para>
- </listitem>
- <listitem>
- <para>
- The Seam conversation context is a cache of conversational state.
- Components you put into the conversation context can hold and cache
- state relating to the current user interaction.
- </para>
- </listitem>
- <listitem>
- <para>
- In particular, the Seam-managed persistence context (or an extended
- EJB container-managed persistence context associated with a
- conversation-scoped stateful session bean) acts as a cache of data
- that has been read in the current conversation. This cache tends to
- have a pretty high hitrate! Seam optimizes the replication of
- Seam-managed persistence contexts in a clustered environment, and
- there is no requirement for transactional consistency with the
- database (optimistic locking is sufficient) so you don't need to
- worry too much about the performance implications of this cache,
- unless you read thousands of objects into a single persistence
- context.
- </para>
- </listitem>
- <listitem>
- <para>
- The application can cache non-transactional state in the Seam
- application context. State kept in the application context is of
- course not visible to other nodes in the cluster.
- </para>
- </listitem>
- <listitem>
- <para>
- The application can cache transactional state using the Seam
- <literal>cacheProvider</literal> component, which integrates
- JBossCache or EHCache into the Seam environment.
- This state will be visible to other nodes if your cache supports
- running in a clustered mode.
- </para>
- </listitem>
- <listitem>
- <para>
- Finally, Seam lets you cache rendered fragments of a JSF page.
- Unlike the ORM second-level cache, this cache is not automatically
- invalidated when data changes, so you need to write application code
- to perform explicit invalidation, or set appropriate expiration
- policies.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- For more information about the second-level cache, you'll need to refer to
- the documentation of your ORM solution, since this is an extremely complex
- topic. In this section we'll discuss the use of caching directly, via
- the <literal>cacheProvider</literal> component, or as the page fragment cache,
- via the <literal><s:cache></literal> control.
- </para>
-
- <section>
- <title>Using Caching in Seam</title>
-
- <para>
- The built-in <literal>cacheProvider</literal> component manages an instance
- of:
- </para>
-
- <variablelist>
- <varlistentry>
- <term>
- JBoss Cache 3.2.x
- </term>
- <listitem>
- <para>
- <literal>org.jboss.cache.Cache</literal>
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- EHCache
- </term>
- <listitem>
- <para>
- <literal>net.sf.ehcache.CacheManager</literal>
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- You can safely put any immutable Java object in the cache, and it will
- be stored in the cache and replicated across the cluster (assuming that
- replication is supported and enabled). If you want to keep mutable
- objects in the cache read the documentation of the underling caching
- project documentation to discover how to notify the cache of changes to
- the cache.
- </para>
-
- <para>
- To use <literal>cacheProvider</literal>, you need to include the jars
- of the cache implementation in your project:
- </para>
-
- <variablelist>
- <varlistentry>
- <term>
- JBoss Cache 3.2.x
- </term>
- <listitem>
- <itemizedlist>
- <listitem>
- <para>
- <literal>jbosscache-core.jar</literal> - JBoss Cache 3.2.x
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>jgroups.jar</literal> - JGroups 2.6.x
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- EHCache
- </term>
- <listitem>
- <itemizedlist>
- <listitem>
- <para>
- <literal>ehcache.jar</literal> - EHCache 1.2.3
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- For an EAR depoyment of Seam, we recommend that the cache jars and
- configuration go directly into the EAR.
- </para>
-
- <para>
- You'll also need to provide a configuration file for JBossCache. Place
- <literal>cache-configuration.xml</literal> with an appropriate cache
- configuration into the classpath (e.g. the ejb jar or
- <literal>WEB-INF/classes</literal>). JBossCache has many scary and
- confusing configuration settings, so we won't discuss them here. Please
- refer to the JBossCache documentation for more information.
- </para>
-
- <para>
- You can find a sample <literal>cache-configuration.xml</literal> in
- <literal>examples/blog/resources/META-INF/cache-configuration.xml</literal>.
- </para>
-
- <para>
- EHCache will run in it's default configuration without a configuration
- file
- </para>
-
- <para>
- To alter the configuration file in use, configure your cache in
- <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ <para>
+ In <filename>EAR</filename> deployments of Seam, we recommend that cache <filename>JAR</filename>s and configuration go directly into the <filename>EAR</filename>.
+ </para>
+ <para>
+ You will also need to provide a configuration file for JBossCache. Place <filename>cache-configuration.xml</filename> with an appropriate cache configuration into the classpath — for example, the EJB JAR or <literal>WEB-INF/classes</literal>. Refer to the JBossCache documentation for more information about configuring the JBossCache.
+ </para>
+ <para>
+ You can find a sample <filename>cache-configuration.xml</filename> in <filename>examples/blog/resources/META-INF/cache-configuration.xml</filename>.
+ </para>
+ <para>
+ EHCache will run in its default configuration without a configuration file.
+ </para>
+ <para>
+ To alter the configuration file in use, configure your cache in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
xmlns:cache="http://jboss.com/products/seam/cache">
- <cache:jboss-cache3-provider configuration="META-INF/cache/cache-configuration.xml" />
-</components>]]></programlisting>
+ <cache:jboss-cache3-provider
+ configuration="META-INF/cache/cache-configuration.xml" />
+</components>
+]]></programlisting>
+ <para>
+ Now you can inject the cache into any Seam component:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("chatroomUsers")
+ at Scope(ScopeType.STATELESS)
- <para>Now you can inject the cache into any Seam component:</para>
-
- <programlisting role="JAVA"><![CDATA[@Name("chatroomUsers")
- at Scope(ScopeType.STATELESS)
-public class ChatroomUsers
-{
- @In CacheProvider cacheProvider;
-
- @Unwrap
- public Set<String> getUsers() throws CacheException {
- Set<String> userList = (Set<String>) cacheProvider.get("chatroom", "userList");
- if (userList==null) {
- userList = new HashSet<String>();
- cacheProvider.put("chatroom", "userList", userList);
- }
- return userList;
- }
-}]]></programlisting>
-
- <para>
- If you want to have multiple cache configurations in your
- application, use <literal>components.xml</literal> to configure
- multiple cache providers:
- </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+public class ChatroomUsers {
+ @In CacheProvider cacheProvider;
+ @Unwrap public Set<String> getUsers() throws CacheException {
+ Set<String> userList =
+ (Set<String>) cacheProvider.get("chatroom", "userList");
+ if (userList==null) {
+ userList = new HashSet<String>();
+ cacheProvider.put("chatroom", "userList", userList);
+ } return userList;
+ }
+}
+]]></programlisting>
+ <para>
+ If you want multiple cache configurations available to your application, use <filename>components.xml</filename> to configure multiple cache providers:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
xmlns:cache="http://jboss.com/products/seam/cache">
- <cache:jboss-cache3-provider name="myCache" configuration="myown/cache.xml"/>
- <cache:jboss-cache3-provider name="myOtherCache" configuration="myother/cache.xml"/>
-</components>]]></programlisting>
-
- </section>
-
- <section>
- <title>Page fragment caching</title>
-
- <para>
- The most interesting use of caching in Seam is the
- <literal><s:cache></literal> tag, Seam's solution to the problem
- of page fragment caching in JSF. <literal><s:cache></literal>
- uses <literal>pojoCache</literal> internally, so you need to follow the
- steps listed above before you can use it. (Put the jars in the EAR,
- wade through the scary configuration options, etc.)
- </para>
-
- <para>
- <literal><s:cache></literal> is used for caching some rendered
- content which changes rarely. For example, the welcome page of our blog
- displays the recent blog entries:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:cache key="recentEntries-#{blog.id}" region="welcomePageFragments">
- <h:dataTable value="#{blog.recentEntries}" var="blogEntry">
- <h:column>
- <h3>#{blogEntry.title}</h3>
- <div>
- <s:formattedText value="#{blogEntry.body}"/>
- </div>
- </h:column>
- </h:dataTable>
-</s:cache>]]></programlisting>
-
- <para>
- The <literal>key</literal> let's you have multiple cached versions of
- each page fragment. In this case, there is one cached version per blog.
- The <literal>region</literal> determines the cache or region node that
- all version will be stored in. Different nodes may have different
- expiry policies. (That's the stuff you set up using the aforementioned
- scary configuration options.)
- </para>
-
- <para>
- Of course, the big problem with <literal><s:cache></literal> is
- that it is too stupid to know when the underlying data changes (for
- example, when the blogger posts a new entry). So you need to evict the
- cached fragment manually:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public void post() {
- ...
- entityManager.persist(blogEntry);
- cacheProvider.remove("welcomePageFragments", "recentEntries-" + blog.getId() );
-}]]></programlisting>
-
- <para>
- Alternatively, if it is not critical that changes are immediately
- visible to the user, you could set a short expiry time on the
- cache node.
- </para>
-
- </section>
-
-</chapter>
+ <cache:jboss-cache3-provider name="myCache"
+ configuration="myown/cache.xml"/>
+ <cache:jboss-cache3-provider name="myOtherCache"
+ configuration="myother/cache.xml"/>
+</components>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Page fragment caching</title>
+ <para>
+ The <literal><s:cache></literal> tag is Seam's solution to the problem of page fragment caching in JSF. <literal><s:cache></literal> uses <literal>pojoCache</literal> internally, so you will need to follow the previous steps — place the <filename>JAR</filename>s in the <filename>EAR</filename> and edit additional configuration options — before you can use it.
+ </para>
+ <para>
+ <literal><s:cache></literal> stores some rendered content that is rarely updated. For example, the welcome page of our blog displays recent blog entries:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:cache key="recentEntries-#{blog.id}" region="welcomePageFragments">
+ <h:dataTable value="#{blog.recentEntries}" var="blogEntry">
+ <h:column>
+ <h3>#{blogEntry.title}</h3>
+ <div>
+ <s:formattedText value="#{blogEntry.body}"/>
+ </div>
+ </h:column>
+ </h:dataTable>
+</s:cache>
+]]></programlisting>
+ <para>
+ The <literal>key</literal> lets you store multiple versions of each page fragment. In this case, there is one cached version per blog. <!-- #modify: per blog, or per blog ENTRY? --> The <literal>region</literal> determines the cache or region node where all versions are stored. Different nodes may have differing expiry policies.
+ </para>
+ <para>
+ The <literal><s:cache></literal> cannot tell when the underlying data is updated, so you will need to manually remove the cached fragment when a change occurs:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public void post() {
+ ...
+ entityManager.persist(blogEntry);
+ cacheProvider.remove("welcomePageFragments",
+ "recentEntries-" + blog.getId());
+}
+]]></programlisting>
+ <para>
+ If changes need not be immediately visible to the user, you can set up a short expiry period on the cache node.
+ </para>
+ </section>
+
+</chapter>
\ No newline at end of file
Added: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Clustering_EJBPassivation.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Clustering_EJBPassivation.xml (rev 0)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Clustering_EJBPassivation.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -0,0 +1,309 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<chapter id="ClusteringAndEJBPassivation">
+ <title>Clustering and EJB Passivation</title>
+
+ <para>
+ Web clustering and EJB passivation share a common solution in Seam, so they are addressed together. This chapter focuses on the programming model and how it is affected by the use of clustering and EJB passivation. You will learn how Seam passivates component and entity instances, how passivation relates to clustering, and how to enable passivation. You will also learn how to deploy a Seam application into a cluster and verify that HTTP session replication is working correctly.
+ </para>
+ <para>
+ First, we will take you through some background information on clustering and show you an example deployment of a Seam application to a JBoss AS cluster.
+ </para>
+
+
+ <section id="clustering">
+ <title>Clustering</title>
+
+ <para>
+ Clustering, also known as <emphasis>web clustering</emphasis>, lets an application run on two or more parallel servers (<emphasis>nodes</emphasis>), while providing a client with a uniform view of the application. Load is distributed across servers such that if one or more servers fail, the application can still be accessed through any surviving nodes. This is crucial for scalable enterprise applications, since performance and availability can be improved just by adding nodes. However, this also provokes the question of what happens to state held on a server that fails.
+ </para>
+ <para>
+ So far, you know that Seam provides state management by including additional scopes and governing the life cycles of stateful (scoped) components. But Seam's state management goes beyond creating, storing, and destroying instances. Seam tracks changes to JavaBean components and stores those changes at strategic points during a request so that changes can be restored when the request shifts to a secondary node in the cluster. Monitoring and replicating stateful EJB components is already handled by the EJB server; Seam state management provides the same feature for stateful JavaBeans.
+ </para>
+ <para>
+ In addition to monitoring JavaBean components, Seam ensures that managed entity instances (that is, JPA and Hibernate entities) are not attached during replication. Seam keeps a record of entities to be loaded, and loads them automatically on the secondary node. <emphasis>You must be using a Seam-managed persistence context to use this feature.</emphasis> More information is provided later in this chapter<!--, under <xref linkend="" />-->.
+ </para>
+ <para>
+ Next we will take you through how to program for clustering.
+ </para>
+
+ <section id="clustering.programming">
+ <title>Programming for clustering</title>
+
+ <para>
+ Any session- or converation-scoped mutable JavaBean component to be used in a clustered environment must implement the <literal>org.jboss.seam.core.Mutable</literal> interface from the Seam API. As part of the contract, the component must maintain a <literal>dirtyflag</literal> event, which indicates whether the user has made changes to the form that must be saved. This event is reported and reset by the <literal>clearDirty()</literal> method, which is called to determine whether the component must be replicated. This lets you avoid using the Servlet API to add and remove the session attribute for every change to an object.
+ </para>
+
+ <para>
+ You must also make sure that all session- and conversation-scoped JavaBean components are <emphasis>serializable</emphasis>. All fields of a stateful component (EJB or JavaBean) must be serializable, unless marked <emphasis>transient</emphasis> or set to null in a <literal>@PrePassivate</literal> method. You can restore the value of a transient or nullified field in a <literal>@PostActivate</literal> method.
+ </para>
+ <para>
+ One area that can be problematic is in using <literal>List.subList</literal> to create a list, because the list created is not serializable. A similar situation can occur for a number of methods that create objects automatically. If you encounter a <exceptionname>java.io.NotSerializableException</exceptionname>, you can place a breakpoint on this exception and run the application server in debug mode to find the problem method.
+ </para>
+ <note>
+ <para>
+ Clustering does not work with components that are hot-deployed. Further, you should avoid using hot-deployable components in non-development environments.
+ </para>
+ </note>
+ </section>
+
+ <section id="clustering.deployment">
+ <title>Deploying a Seam application to a JBoss AS cluster with session replication</title>
+
+ <para>
+ The following procedure has been validated against a <application>seam-gen</application> application and the Seam Booking example.
+ </para>
+
+<para>
+ This section assumes that the IP addresses of the master and slave servers are <literal>192.168.1.2</literal> and <literal>192.168.1.3</literal>, respectively. The <literal>mod_jk</literal> load balancer was not use intentionally to make it easier to validate that both nodes are responding to requests and interchanging sessions.
+</para>
+
+<para>
+ The following log messages were generated out of the deployment of a WAR application, <filename>vehicles.war</filename>, and its corresponding datasource, <literal>vehiclesDatasource</literal>. The Booking example fully supports this process, and you can find instructions about deploying it to a cluster in the <filename>examples/booking/readme.txt</filename> file.
+</para>
+<para>
+ These instructions use the farm deployment method, but you can also deploy the application normally and let the two servers negotiate a master/slave relationship based on startup order.
+</para>
+<para>
+ All timestamps in this tutorial have been replaced with zeroes to reduce noise.
+</para>
+<note>
+ <title>A note about SELinux</title>
+ <para>
+ If your nodes are on different machines that run Red Hat Enterpise Linux or Fedora, they may not acknowledge each other automatically. JBoss AS clustering relies on the UDP (User Datagram Protocol) multi-casting provided by jGroups. The SELinux configuration that ships with Red Hat Enterprise Linux and Fedora blocks these packets by default. To allow the packets, modify the <literal>iptables</literal> rules (as root). The following commands apply to an IP address that matches <literal>192.168.1.x</literal>:
+ </para>
+ <programlisting>
+ /sbin/iptables -I RH-Firewall-1-INPUT 5 -p udp -d 224.0.0.0/4 -j ACCEPT
+ /sbin/iptables -I RH-Firewall-1-INPUT 9 -p udp -s 192.168.1.0/24 -j ACCEPT
+ /sbin/iptables -I RH-Firewall-1-INPUT 10 -p tcp -s 192.168.1.0/24 -j ACCEPT
+ /etc/init.d/iptables save
+ </programlisting>
+</note>
+<note>
+ <title>A note about Stateful Session Beans</title>
+ <para>
+ If you are deploying an application with stateful session beans and HTTP Session replication to a JBoss AS cluster, your stateful session bean classes must be annotated with <literal>@Clustered</literal> (from the JBoss EJB 3.0 annotation API) or marked as <literal>clustered</literal> in the <filename>jboss.xml</filename> descriptor. For details, see the Booking example.
+ </para>
+</note>
+</section>
+<section id="clustering.tutorial">
+ <title>Tutorial</title>
+ <orderedlist>
+ <listitem>
+ <para>
+ Create two instances of JBoss AS. (To do so, just extract the <filename>zip</filename> twice.)
+ </para>
+ <para>
+ Deploy the JDBC driver to <filename>server/all/lib/</filename> on both instances if you are not using HSQLDB.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Add <literal><distributable/></literal> as the first child element in <filename>WEB-INF/web.xml</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set the <varname>distributable</varname> property on <literal>org.jboss.seam.core.init</literal> to <literal>true</literal> to enable the <literal>ManagedEntityInterceptor</literal> (that is, <code><core:init distributable="true"></code> in <filename>WEB-INF/components.xml</filename>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Ensure that you have two IP addresses available (two computers, two network cards, or two IP addresses bound to the same interface). We assume that these two IP addresses are <literal>192.168.1.2</literal> and <literal>192.168.1.3</literal>.
+ </para>
+<!--#modify: to be rewritten with info from pmuir:
+On *nix, you can bind a new IP address to a network interface using the following command:
+
+ /sbin/ifconfig eth1:2 192.168.1.3
+
+Replace eth1 with your interface name and make the IP address conform to your network.
+
+If you're on Windows, follow these steps:
+
+ - Open your network adapter
+ - Click Properties
+ - Select Internet Protocol (TCP/IP) then click Properties
+ - Click Advanced...
+ - Select the IP settings tab and click Add...
+ - Type in an IP address, click Add
+ - Click OK on all open windows
+-->
+ </listitem>
+ <listitem>
+ <para>
+ Start the master JBoss AS instance on the first IP:
+ </para>
+ <programlisting> ./bin/run.sh -c all -b 192.168.1.2</programlisting>
+ <para>
+ The log should report one cluster member and zero other members.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Verify that the <filename>server/all/farm</filename> directory in the slave JBoss AS instance is empty.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Start the slave JBoss AS instance on the second IP:
+ </para>
+ <programlisting> ./bin/run.sh -c all -b 192.168.1.3</programlisting>
+ <para>
+ The log should report two cluster members and one other member. It should also show the state being retrieved from the master instance.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Deploy the <filename>-ds.xml</filename> to the <filename>server/all/farm</filename> of the master instance.
+ </para>
+ <para>
+ In the log of the master instance you should see acknowlegement of this deployment. You should see a corresponding message acknowledging deployment to the slave instance.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Deploy the application to the server/all/farm directory. You should see acknowledgement of deployment in the log of the master instance after normal application startup messages have finished. The slave instance log should show a corresponding message acknowledging deployment. (You may need to wait up to three minutes for the deployed archive to be transferred.)
+ </para>
+ </listitem>
+ </orderedlist>
+<para>
+ Your application is now running in a cluster with HTTP Session replication. The next step is to validate that the clustering is working correctly.
+</para>
+ </section>
+
+ <section id="clustering.validation">
+ <title>Validating the distributable services of an application running in a JBoss AS cluster </title>
+ <para>
+ Your application now starts successfully on two different JBoss AS servers, but it is important to validate that the two instances are exchanging HTTP Sessions correctly, so that the application continues to operate with the slave instance if the master instance is stopped.
+ </para>
+ <para>
+ First, browse to the application on the master instance to start the first HTTP Session. On the same instance, open the JBoss AS JMX Console and navigate to the following managed bean:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para><emphasis>Category:</emphasis> jboss.cache</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Entry:</emphasis> service=TomcatClusteringCache</para>
+ </listitem>
+ <listitem>
+ <para><emphasis>Method:</emphasis> printDetails()</para>
+ </listitem>
+ </itemizedlist>
+
+ <para>
+ Invoke the <literal>printDetails()</literal> method. This will present you with a tree of active HTTP Sessions. Verify that the session used by your browser corresponds to one of the sessions on the tree.
+ </para>
+
+ <para>
+ Next, switch to the slave instance and invoke the same method in the JMX Console. You should see an identical tree under this application's context path.
+ </para>
+
+ <para>
+ That these trees are identical proves that both servers claim to have identical sessions. Next, we must test that the data is serializing and iunserializing correctly.
+ </para>
+
+ <para>
+ Sign in via the URL of the master instance. Then, construct a URL for the second instance by placing the <literal>;jsessionid=XXXX</literal> immediately after the Servlet path and changing the IP address. (You should see that the session has carried over to the other instance.)</para>
+ <para>Now, kill the master instance and check that you can continue to use the application from the slave instance. Then, remove the deployed applications from the <filename>server/all/farm</filename> directory and restart the instance.</para>
+ <para>Change the IP in the URL back to that of the master instance, and browse to the new URL — you should see that the original session ID is still being used.</para>
+
+ <para>
+ You can watch objects passivate and activate by creating a session- or conversation-scoped Seam component and implementing the appropriate life-cycle methods. You can use methods from the <literal>HttpSessionActivationListener</literal> interface (which is automatically registered on all non-EJB components):</para>
+<programlisting role="JAVA"><![CDATA[public void sessionWillPassivate(HttpSessionEvent e);
+public void sessionDidActivate(HttpSessionEvent e);
+]]></programlisting>
+ <para>
+ Alternatively, you can mark two public void methods (without arguments) with <literal>@PrePassivate</literal> and <literal>@PostActivate</literal> respectively. Remember that passivation will occur at the end of every request, while activation will occur when a node is called.
+ </para>
+ <para>
+ In order to make replication transparent, Seam automatically keeps track of objects that have been changed. All that you need to do is maintain a <literal>dirtyflag</literal> on your session- or conversation-scoped component, and Seam will handle JPA entity instances for you.
+ </para>
+<!--Warning is unhelpful, but uncomment if required.
+ <warning>
+ <para>
+ Transient fields are not always reinitialized. This problem has been resolved with a patch to the <literal>SecurityInterceptor</literal>, but may occur elsewhere.
+ </para>
+ </warning>-->
+ </section>
+ </section>
+
+ <section>
+ <title>EJB Passivation and the ManagedEntityInterceptor</title>
+
+ <para>
+ The <literal>ManagedEntityInterceptor</literal> (MEI) is an optional interceptor in Seam. When enabled, it is applied to conversation-scoped components. To enable the MEI, set <varname>distributable</varname> to <literal>true</literal> on the <literal>org.jboss.seam.init.core</literal> component. You can also add or update the following component declaration in your <filename>components.xml</filename> file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<core:init distributable="true"/>
+]]></programlisting>
+
+ <para>
+ This does not enable HTTP Session replication, but it does let Seam handle the passivation of either EJB components or components in the HTTP Session.
+ </para>
+
+ <para>
+ The MEI ensures that, throughout the life of a conversation with at least one extended persistence context, any entity instances loaded by the persistence context remain managed — that is, they are not prematurely detached by a passivation event. This ensures the integrity of the extended persistence context, and therefore the integrity of its guarantees.</para>
+ <para>
+ There are two situations that threaten integrity: the passivation of a stateful session bean that hosts an extended persistence context, and the passivation of the HTTP Session.</para>
+
+ <section>
+ <title>The friction between passivation and persistence</title>
+
+ <para>
+ The <emphasis>persistence context</emphasis> is used to store entity instances (objects) that the persistence manager has loaded from the database. There is only ever one object per unique database record in a persistence context. It is often referred to as the <emphasis>first-level cache</emphasis> because it allows an application to avoid a call to the database when a record has been loaded into the persistence context.</para>
+ <para>
+ Objects in the persistence context can be modified, and once modified they are considered <emphasis>dirty</emphasis>. Changes are tracked by the persistence manager, which then migrates these changes to the database when necessary. The persistence context, therefore, maintains a set of pending changes to the database.
+ </para>
+ <para>
+ Database-oriented applications capture transactional information that must be transferred into the database immediately. This information cannot always be captured in one screen, and the user may need to decide whether to accept or reject the pending changes.</para>
+ <para>
+ These aspects of transactions have not necessarily been apparent from the user's perspective. The extended persistence context extends the user's understanding of transactions. It can hold changes for as long as the application requires, and then push these pending changes to the database via built-in persistence manager capabilities (<literal>EntityManager#flush()</literal>).
+ </para>
+ <para>
+ The persistence manager is linked to an entity instance via an <emphasis>object reference</emphasis>. Entity instances can be serialized, but the persistence manager cannot. Serialization can occur when either a stateful session bean or the HTTP Session is passivated. For the application to continue its activity, the relationship between the persistence manager and its entity instances must be maintained. MEI provides this support.</para>
+ </section>
+
+ <section>
+ <title>Case #1: Surviving EJB passivation</title>
+
+ <para>
+ Conversations were initially designed for stateful session beans because the EJB3 specification defines stateful session beans as the hosts of the extended persistence context. Seam introduces the <emphasis>Seam-managed persistence context</emphasis>, which works around a number of limitations in the specification. Both contexts can be used with stateful session beans.
+ </para>
+ <para>
+ For a stateful session bean to remain active, a client must hold a reference to the stateful session bean. Seam's conversation context is an ideal location for this reference, which means that the stateful session bean remains active for the duration of the conversation context. Further, <literal>EntityManager</literal>s that are injected into the stateful session bean with the <literal>@PersistenceContext(EXTENDED)</literal> annotation will be bound to the stateful session bean and remain active for the bean's lifetime. <literal>EntityManager</literal>s injected with the <literal>@In</literal> annotation are maintained by Seam and stored directly in the converstion context, so they remain active for the duration of the <emphasis>conversation</emphasis>, independent of the stateful session bean.
+ </para>
+ <para>
+ The Java EE container can also passivate a stateful session bean, but this method can be problematic. Rather than making the container responsible for this process, after each invocation of the stateful session bean, Seam transfers the reference to the entity instance from the stateful session bean to the current conversation, and therefore into the HTTP Session. This nullifies the associated fields on the stateful session bean. Seam then restores these references at the beginning of the subsequent invocation. Because Seam already stores the persistence manager in the conversation, stateful session bean passivation and activation has no adverse effect on the application.</para>
+
+ <important>
+ <para>
+ If your application uses stateful session beans that hold references to extended persistence contexts, and those beans can passivate, then you <emphasis>must</emphasis> use the MEI, regardless of whether you use a single instance or a cluster.
+ </para>
+ </important>
+
+ <para><!--#modify: add details here?-->
+ You can disable passivation on stateful session beans. See the <ulink
+ url="http://www.jboss.org/community/docs/DOC-9656">Ejb3DisableSfsbPassivation</ulink> page on the JBoss
+ Wiki for details.
+ </para>
+ </section>
+
+ <section>
+ <title>Case #2: Surviving HTTP session replication</title>
+
+ <para>
+ The HTTP Session is used when passivating stateful session beans, but in clustered environments that have enabled session replication, the HTTP Session can also be passivated. Since the persistence manager cannot be serialized, passivating the HTTP Session would normally involve destroying the persistence manager.</para>
+ <para>
+ When an entity instance is first placed into a conversation, Seam embeds the instance in a wrapper that contains information about reassociating the instance with the persistence manager post-serialization. When the application changes nodes (when a server fails, for instance), Seam's MEI reconstructs the persistence context. The persistence context is reconstructed from the database, so pending changes to the instance are lost. However, Seam's optimistic locking ensures that, where files have changed, only the most recent changes are accepted where multiple versions of an instance occur.
+ </para>
+
+ <important>
+ <para>
+ If your application is deployed in a cluster with HTTP Session replication, you <emphasis>must</emphasis> use the MEI.
+ </para>
+ </important>
+ </section>
+ </section>
+</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Components.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Components.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Components.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,1620 +1,1359 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="components">
- <title>Built-in Seam components</title>
- <para>
- This chapter describes Seam's built-in components, and their
- configuration properties. The built-in components will be created even if they
- are not listed in your <literal>components.xml</literal> file, but if you need to
- override default properties or specify more than one component of a certain type,
- <literal>components.xml</literal> is used.
- </para>
-
- <para>
- Note that you can replace any of the built in components with
- your own implementations simply by specifying the name of one
- of the built in components on your own class using
- <literal>@Name</literal>.
- </para>
+<chapter id="components" >
+ <title>Built-in Seam components</title>
+ <para>
+ This chapter describes Seam's built-in components, and their configuration properties. The built-in components are created automatically, even if they are not listed in your <filename>components.xml</filename> file. However, if you need to override default properties or specify more than one component of a certain type, you can do so in <filename>components.xml</filename>.
+ </para>
+ <para>
+ You can replace any of the built-in components with your own implementation by using <literal>@Name</literal> to name your own class after the appropriate built-in component.
+ </para>
+ <section>
+ <title>Context injection components</title>
+ <para>
+ The first set of built-in components support the injection of various contextual objects. For example, the following component instance variable would have the Seam session context object injected:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In private Context sessionContext;
+]]></programlisting>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.contexts</literal></term>
+ <listitem>
+ <para>
+ Component that provides access to Seam Context objects such as <literal>org.jboss.seam.core.contexts.sessionContext['user']</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.faces.facesContext</literal></term>
+ <listitem>
+ <para>
+ Manager component for the <literal>FacesContext</literal> context object. (This is not a true Seam context.)
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ All of these components are always installed.
+ </para>
+ </section>
+
+ <section>
+ <title>JSF-related components</title>
+ <para>
+ The following set of components are provided to supplement JSF.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.faces.dateConverter</literal></term>
+ <listitem>
+ <para>
+ Provides a default JSF converter for properties of type <literal>java.util.Date</literal>.
+ </para>
+ <para>
+ This converter is automatically registered with JSF, so developers need not specify a DateTimeConverter on an input field or page parameter. By default, it assumes the type to be a date (as opposed to a time or date plus time), and uses the short input style adjusted to the user's <literal>Locale</literal>. For <literal>Locale.US</literal>, the input pattern is <literal>mm/dd/yy</literal>. However, to comply with Y2K, the year is changed from two digits to four — <literal>mm/dd/yyyy</literal>.
+ </para>
+ <para>
+ You can override the input pattern globally by reconfiguring your component. Consult the JavaServer Faces documentation for this class to see examples.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.faces.facesMessages</literal></term>
+ <listitem>
+ <para>
+ Allows Faces success messages to propagate across a browser redirect.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>add(FacesMessage facesMessage)</literal> — adds a Faces message, which will be displayed during the next render response phase that occurs in the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>add(String messageTemplate)</literal> — adds a Faces message, rendered from the given message template, which may contain EL expressions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>add(Severity severity, String messageTemplate)</literal> — adds a Faces message, rendered from the given message template, which may contain EL expressions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>addFromResourceBundle(String key)</literal> — adds a Faces message, rendered from a message template defined in the Seam resource bundle which may contain EL expressions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>addFromResourceBundle(Severity severity, String key)</literal> — adds a Faces message, rendered from a message template defined in the Seam resource bundle, which may contain EL expressions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>clear()</literal> — clears all messages.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.faces.redirect</literal></term>
+ <listitem>
+ <para>
+ A convenient API for performing redirects with parameters. This is particularly useful for bookmarkable search results screens.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>redirect.viewId</literal> — the JSF view ID to redirect to.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>redirect.conversationPropagationEnabled</literal> — determines whether the conversation will propagate across the redirect.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>redirect.parameters</literal> — a map of request parameter name to value, to be passed in the redirect request.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>execute()</literal> — performs the redirect immediately.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>captureCurrentRequest()</literal> — stores the view ID and request parameters of the current GET request (in the conversation context) for later use by calling <literal>execute()</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.faces.httpError</literal></term>
+ <listitem>
+ <para>
+ A convenient API for sending HTTP errors.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.ui.renderStampStore</literal></term>
+ <listitem>
+ <para>
+ A component which maintains a collection of render stamps. A render stamp indicates whether a rendered form has been submitted. This is particularly useful in conjunction with JSF's client-side state saving method, because the form's status (posted or unposted) is controlled by the server rather than the client.
+ </para>
+ <para>
+ Client-side state saving is often used to unbind this check from the session. To do so, you will need an implementation that can store render stamps within the application (valid while the application runs), or the database (valid across server restarts).
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>maxSize</literal> — The maximum number of stamps to keep in the store. The default is <literal>100</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ The JSF components are installed when the class <literal>javax.faces.context.FacesContext</literal> is available on the classpath.
+ </para>
+ </section>
+
+ <section>
+ <title>Utility components</title>
+ <para>
+ The following components provide various functions that are useful across a broad range of applications.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.events</literal></term>
+ <listitem>
+ <para>
+ An API for raising events that can be observed via <literal>@Observer</literal> methods, or method bindings in <filename>components.xml</filename>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>raiseEvent(String type)</literal> — raises an event of a particular type and distributes it to all observers.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>raiseAsynchronousEvent(String type)</literal> — raises an event to be processed asynchronously by the EJB3 timer service.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>raiseTimedEvent(String type, ....)</literal> — schedules an event to be processed asynchronously by the EJB3 timer service.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>addListener(String type, String methodBinding)</literal> — adds an observer for a particular event type.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.interpolator</literal></term>
+ <listitem>
+ <para>
+ An API for interpolating the values of JSF EL expressions in Strings.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>interpolate(String template)</literal> — scans the template for JSF EL expressions of the form <literal>#{...}</literal> and replaces them with their evaluated values.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.expressions</literal></term>
+ <listitem>
+ <para>
+ An API for creating value and method bindings.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>createValueBinding(String expression)</literal> — creates a value binding object.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>createMethodBinding(String expression)</literal> — creates a method binding object.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.pojoCache</literal></term>
+ <listitem>
+ <para>
+ Manager component for a JBoss Cache <literal>PojoCache</literal> instance.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>pojoCache.cfgResourceName</literal> — the name of the configuration file. Defaults to <filename>treecache.xml</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ All of these components are always installed.
+ </para>
+ </section>
+
+ <section>
+ <title>Components for internationalization and themes</title>
+ <para>
+ These components make it easy to build internationalized user interfaces using Seam.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.locale</literal></term>
+ <listitem>
+ <para>
+ The Seam locale.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.international.timezone</literal></term>
+ <listitem>
+ <para>
+ The Seam timezone. The timezone is session-scoped.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.resourceBundle</literal></term>
+ <listitem>
+ <para>
+ The Seam resource bundle. The resource bundle is stateless. The Seam resource bundle performs a depth-first search for keys in a list of Java resource bundles.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.resourceLoader</literal></term>
+ <listitem>
+ <para>
+ The resource loader provides access to application resources and resource bundles.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>resourceLoader.bundleNames</literal> — the names of the Java resource bundles to search when the Seam resource bundle is used. Default to <literal>messages</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.international.localeSelector</literal></term>
+ <listitem>
+ <para>
+ Supports selection of the locale either at configuration time, or by the user at runtime.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>select()</literal> — selects the specified locale.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>localeSelector.locale</literal> — the actual <literal>java.util.Locale</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>localeSelector.localeString</literal> — the string representation of the locale.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>localeSelector.language</literal> — the language for the specified locale.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>localeSelector.country</literal> — the country for the specified locale.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>localeSelector.variant</literal> — the variant for the specified locale.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>localeSelector.supportedLocales</literal> — a list of <literal>SelectItem</literal>s representing the supported locales listed in <filename>jsf-config.xml</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>localeSelector.cookieEnabled</literal> — specifies that the locale selection should be persisted via a cookie.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.international.timezoneSelector</literal></term>
+ <listitem>
+ <para>
+ Supports selection of the timezone either at configuration time, or by the user at runtime.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>select()</literal> — selects the specified locale.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>timezoneSelector.timezone</literal> — the actual <literal>java.util.TimeZone</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>timezoneSelector.timeZoneId</literal> — the string representation of the timezone.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>timezoneSelector.cookieEnabled</literal> — specifies that the timezone selection should be persisted via a cookie.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.international.messages</literal></term>
+ <listitem>
+ <para>
+ A map containing internationalized messages rendered from message templates defined in the Seam resource bundle.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.theme.themeSelector</literal></term>
+ <listitem>
+ <para>
+ Supports selection of the theme either at configuration time, or by the user at runtime.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>select()</literal> — select the specified theme.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>theme.availableThemes</literal> — the list of defined themes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>themeSelector.theme</literal> — the selected theme.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>themeSelector.themes</literal> — a list of <literal>SelectItem</literal>s representing the defined themes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>themeSelector.cookieEnabled</literal> — specifies that the theme selection should be persisted via a cookie.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.theme.theme</literal></term>
+ <listitem>
+ <para>
+ A map containing theme entries.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ All of these components are always installed.
+ </para>
+ </section>
+
+ <section>
+ <title>Components for controlling conversations</title>
+ <para>
+ The following components allow you to control conversations through either the application or the user interface.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.conversation</literal></term>
+ <listitem>
+ <para>
+ An API for controlling the current Seam conversation's attributes from within the application.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>getId()</literal> — returns the current conversation ID.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>isNested()</literal> — specifies whether the current conversation is a nested conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>isLongRunning()</literal> — specifies whether the current conversation is a long-running conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>getId()</literal> — returns the current conversation ID.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>getParentId()</literal> — returns the conversation ID of the parent conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>getRootId()</literal> — returns the conversation ID of the root conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>setTimeout(int timeout)</literal> — sets the timeout for the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>setViewId(String outcome)</literal> — sets the view ID to use when switching back to the current conversation from the conversation switcher, conversation list, or breadcrumbs.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>setDescription(String description)</literal> — sets the description of the current conversation to be displayed in the conversation switcher, conversation list, or breadcrumbs.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>redirect()</literal> — redirects to the last well-defined view ID for this conversation. This is useful after login challenges.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>leave()</literal> — exits the scope of this conversation, without actually ending the conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>begin()</literal> — begins a long-running conversation (equivalent to <literal>@Begin</literal>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>beginPageflow(String pageflowName)</literal> — begin a long-running conversation with a pageflow (equivalent to <literal>@Begin(pageflow="...")</literal>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>end()</literal> — ends a long-running conversation (equivalent to <literal>@End</literal>).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pop()</literal> — pops the conversation stack, and returns to the parent conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>root()</literal> — returns to the root conversation of the conversation stack.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>changeFlushMode(FlushModeType flushMode)</literal> — changes the flush mode of the conversation.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.conversationList</literal></term>
+ <listitem>
+ <para>
+ A manager component for the conversation list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.conversationStack</literal></term>
+ <listitem>
+ <para>
+ A manager component for the conversation stack (breadcrumbs).
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.faces.switcher</literal></term>
+ <listitem>
+ <para>
+ The conversation switcher.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ All of these components are always installed.
+ </para>
+ </section>
+
+ <section>
+ <title>jBPM-related components</title>
+ <para>
+ The following components are used with jBPM.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.pageflow.pageflow</literal></term>
+ <listitem>
+ <para>
+ An API for controlling Seam pageflows.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>isInProcess()</literal> — returns <literal>true</literal> if there is currently a pageflow in process.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>getProcessInstance()</literal> — returns jBPM <literal>ProcessInstance</literal> for the current pageflow.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>begin(String pageflowName)</literal> — begins a pageflow in the context of the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>reposition(String nodeName)</literal> — repositions the current pageflow to a particular node.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.actor</literal></term>
+ <listitem>
+ <para>
+ An API that controls the attributes of the jBPM actor associated with the current session, from within the application.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>setId(String actorId)</literal> — sets the jBPM actor ID of the current user.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>getGroupActorIds()</literal> — returns a <literal>Set</literal> to which jBPM actor IDs for the current users groups may be added.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.transition</literal></term>
+ <listitem>
+ <para>
+ An API that controls the current task's jBPM transition from within the application.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>setName(String transitionName)</literal> — sets the jBPM transition name to be used when the current task is ended via <literal>@EndTask</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.businessProcess</literal></term>
+ <listitem>
+ <para>
+ An API for programmatic control of the association between the conversation and business process.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>businessProcess.taskId</literal> — the ID of the task associated with the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>businessProcess.processId</literal> — the ID of the process associated with the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>businessProcess.hasCurrentTask()</literal> — specifies whether a task instance is associated with the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>businessProcess.hasCurrentProcess()</literal> — specifies whether a process instance is associated with the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>createProcess(String name)</literal> — creates an instance of the named process definition and associates it with the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>startTask()</literal> — starts the task associated with the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>endTask(String transitionName)</literal> — ends the task associated with the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>resumeTask(Long id)</literal> — associates the task with the specified ID with the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>resumeProcess(Long id)</literal> — associates the process with the specified ID with the current conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>transition(String transitionName)</literal> — triggers the transition.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.taskInstance</literal></term>
+ <listitem>
+ <para>
+ A manager component for the jBPM <literal>TaskInstance</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.processInstance</literal></term>
+ <listitem>
+ <para>
+ A manager component for the jBPM <literal>ProcessInstance</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.jbpmContext</literal></term>
+ <listitem>
+ <para>
+ A manager component for an event-scoped <literal>JbpmContext</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.taskInstanceList</literal></term>
+ <listitem>
+ <para>
+ A manager component for the jBPM task list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.pooledTaskInstanceList</literal></term>
+ <listitem>
+ <para>
+ A manager component for the jBPM pooled task list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.taskInstanceListForType</literal></term>
+ <listitem>
+ <para>
+ A manager component for the jBPM task lists.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.pooledTask</literal></term>
+ <listitem>
+ <para>
+ An action handler for pooled task assignment.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.processInstanceFinder</literal></term>
+ <listitem>
+ <para>
+ A manager component for the process instance task list.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.processInstanceList</literal></term>
+ <listitem>
+ <para>
+ The process instance task list.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ All of these components are installed whenever the component <literal>org.jboss.seam.bpm.jbpm</literal> is installed.
+ </para>
+ </section>
+
+ <section>
+ <title>Security-related components</title>
+ <para>
+ These components relate to web-tier security.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.web.userPrincipal</literal></term>
+ <listitem>
+ <para>
+ A manager component for the current user <literal>Principal</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.web.isUserInRole</literal></term>
+ <listitem>
+ <para>
+ Allows JSF pages to choose to render a control, depending upon the roles available to the current principal, for example: <literal><h:commandButton value="edit" rendered="#{isUserInRole['admin']}"/></literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>JMS-related components</title>
+ <para>
+ These components are for use with managed <literal>TopicPublisher</literal>s and <literal>QueueSender</literal>s (see below).
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.jms.queueSession</literal></term>
+ <listitem>
+ <para>
+ A manager component for a JMS <literal>QueueSession</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.jms.topicSession</literal></term>
+ <listitem>
+ <para>
+ A manager component for a JMS <literal>TopicSession</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section id="components.mail">
+ <title>Mail-related components</title>
+ <para>
+ These components are for use with Seam's Email support.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.mail.mailSession</literal></term>
+ <listitem>
+ <para>
+ A manager component for a JavaMail <literal>Session</literal>. The session can be either looked up in the JNDI context (by setting the <literal>sessionJndiName</literal> property), or created from the configuration options. In this case, the <literal>host</literal> is mandatory.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.host</literal> — the hostname of the SMTP server to use.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.port</literal> — the port of the SMTP server to use.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.username</literal> — the username to use to connect to the SMTP server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.password</literal> — the password to use to connect to the SMTP server.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.debug</literal> — enables JavaMail debugging (very verbose).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.ssl</literal> — enables SSL connection to SMTP (will default to port 465).
+ </para>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.tls</literal> — enables TLS support in the mail session. Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.mail.mailSession.sessionJndiName</literal> — name under which a javax.mail.Session is bound to JNDI. If this is supplied, all other properties will be ignored.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Infrastructural components</title>
+ <para>
+ These components provide critical platform infrastructure. You can install a component that is not installed by default by setting <literal>install="true"</literal> on the component in <filename>components.xml</filename>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.init</literal></term>
+ <listitem>
+ <para>
+ This component contains initialization settings for Seam. Always installed.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.core.init.jndiPattern</literal> — the JNDI pattern used for looking up session beans.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.core.init.debug</literal> — enables Seam debug mode. During production, this should be set to <literal>false</literal>; you may see errors if the system is placed under any load while debug is enabled.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.core.init.clientSideConversations</literal> — when <literal>true</literal>, saves conversation context variables in the client rather than the <literal>HttpSession</literal>.
+ </para>
+ </listitem>
+ <!--
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.core.init.userTransactionName</literal> — the JNDI name to use when looking up the JTA <literal>UserTransaction</literal> object.
+ </para>
+ </listitem>
+ -->
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.manager</literal></term>
+ <listitem>
+ <para>
+ An internal component for Seam page and conversation context management. Always installed.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.core.manager.conversationTimeout</literal> — the conversation context timeout in milliseconds.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.core.manager.concurrentRequestTimeout</literal> — the maximum wait time for a thread attempting to gain a lock on the long-running conversation context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.core.manager.conversationIdParameter</literal> — the request parameter used to propagate the conversation ID. The default is <literal>conversationId</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.core.manager.conversationIsLongRunningParameter</literal> — the request parameter used to propagate that the conversation is long-running. The default is <literal>conversationIsLongRunning</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.core.manager.defaultFlushMode</literal> — sets the default flush mode on any Seam-managed Persistence Context. This defaults to <literal>AUTO</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.navigation.pages</literal></term>
+ <listitem>
+ <para>
+ An internal component for Seam workspace management. Always installed.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.navigation.pages.noConversationViewId</literal> — specifies the view ID to redirect to, globally, when a conversation entry is not found on the server side.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.navigation.pages.loginViewId</literal> — specifies the view ID to redirect to, globally, when an unauthenticated user attempts to access a protected view.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.navigation.pages.httpPort</literal> — specifies the port to use, globally, when the HTTP scheme is requested.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.navigation.pages.httpsPort</literal> — specifies the port to use, globally, when the HTTPS scheme is requested.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.navigation.pages.resources</literal> — specifies a list of resources to search for <filename>pages.xml</filename> style resources. The default is <filename>WEB-INF/pages.xml</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.bpm.jbpm</literal></term>
+ <listitem>
+ <para>
+ This component bootstraps a <literal>JbpmConfiguration</literal>. Install it as the <literal>org.jboss.seam.bpm.Jbpm</literal> class.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.bpm.jbpm.processDefinitions</literal> — specifies a list of jPDL file resource names to use for orchestrating business processes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.bpm.jbpm.pageflowDefinitions</literal> — specifies a list of jPDL file resource names to use for orchestrating conversation page flows.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.conversationEntries</literal></term>
+ <listitem>
+ <para>
+ An internal session-scoped component that records active long-running conversations between requests.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.faces.facesPage</literal></term>
+ <listitem>
+ <para>
+ An internal page-scoped component that records the conversation context associated with a page.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.persistence.persistenceContexts</literal></term>
+ <listitem>
+ <para>
+ An internal component that records the persistence contexts used in the current conversation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.jms.queueConnection</literal></term>
+ <listitem>
+ <para>
+ Manages a JMS <literal>QueueConnection</literal>. This is installed whenever managed <literal>QueueSender</literal> is installed.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.jms.queueConnection.queueConnectionFactoryJndiName</literal> — specifies the JNDI name of a JMS <literal>QueueConnectionFactory</literal>. The default is <literal>UIL2ConnectionFactory</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.jms.topicConnection</literal></term>
+ <listitem>
+ <para>
+ Manages a JMS <literal>TopicConnection</literal>. This is installed whenever managed <literal>TopicPublisher</literal> is installed.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.jms.topicConnection.topicConnectionFactoryJndiName</literal> — specifies the JNDI name of a JMS <literal>TopicConnectionFactory</literal>. The default is <literal>UIL2ConnectionFactory</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.persistence.persistenceProvider</literal></term>
+ <listitem>
+ <para>
+ An abstraction layer for non-standardized features of the JPA provider.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.validators</literal></term>
+ <listitem>
+ <para>
+ Caches instances of Hibernate Validator <literal>ClassValidator</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.faces.validation</literal></term>
+ <listitem>
+ <para>
+ Lets the application determine whether validation succeeded.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.debug.introspector</literal></term>
+ <listitem>
+ <para>
+ Provides support for the Seam Debug Page.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.debug.contexts</literal></term>
+ <listitem>
+ <para>
+ Provides support for the Seam Debug Page.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.exception.exceptions</literal></term>
+ <listitem>
+ <para>
+ An internal component for exception handling.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.transaction.transaction</literal></term>
+ <listitem>
+ <para>
+ An API for controlling transactions and abstracting the underlying transaction management implementation behind a JTA-compatible interface.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>org.jboss.seam.faces.safeActions</literal></term>
+ <listitem>
+ <para>
+ Determines that an action expression in an incoming URL is safe by checking that the action expression exists in the view.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Miscellaneous components</title>
+ <para>
+ Additional, uncategorized components.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.async.dispatcher</literal></term>
+ <listitem>
+ <para>
+ Dispatches stateless session beans for asynchronous methods.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.image</literal></term>
+ <listitem>
+ <para>
+ Used for image manipulation and interrogation.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.pojoCache</literal></term>
+ <listitem>
+ <para>
+ A manager component for a PojoCache instance.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <variablelist>
+ <varlistentry>
+ <term><literal>org.jboss.seam.core.uiComponent</literal></term>
+ <listitem>
+ <para>
+ Manages a map of UIComponents keyed by component ID.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ <section>
+ <title>Special components</title>
+ <para>
+ Certain Seam component classes can be installed multiple times under names specified in the Seam configuration. For example, the following lines in <filename>components.xml</filename> install and configure two Seam components:
+ </para>
+
+<programlisting role="XML"><![CDATA[<component name="bookingDatabase"
+ class="org.jboss.seam.persistence.ManagedPersistenceContext">
+ <property name="persistenceUnitJndiName">
+ java:/comp/emf/bookingPersistence
+ </ property>
+</component>
- <section>
- <title>Context injection components</title>
- <para>
- The first set of built in components exist purely to support
- injection of various contextual objects. For example, the
- following component instance variable would have the Seam
- session context object injected:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@In private Context sessionContext;]]></programlisting>
-
- <variablelist >
- <varlistentry>
- <term><literal>org.jboss.seam.core.contexts</literal></term>
- <listitem>
- <para>
- Component that provides access to Seam Context objects, for
- example <literal>org.jboss.seam.core.contexts.sessionContext['user']</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.faces.facesContext</literal></term>
- <listitem>
- <para>
- Manager component for the <literal>FacesContext</literal> context
- object (not a true Seam context)
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- All of these components are always installed.
- </para>
-
- </section>
-
- <section>
- <title>JSF-related components</title>
- <para>
- The following set of components are provided to supplement JSF.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.faces.dateConverter</literal></term>
- <listitem>
- <para>
- Provides a default JSF converter for properties of type
- <literal>java.util.Date</literal>.
- </para>
-
- <para>
- This converter is automatically registered with JSF. It
- is provided to save a developer from having to specify
- a DateTimeConverter on an input field or page
- parameter. By default, it assumes the type to be a date
- (as opposed to a time or date plus time) and uses the
- short input style adjusted to the Locale of the user.
- For Locale.US, the input pattern is mm/DD/yy. However,
- to comply with Y2K, the year is changed from two digits
- to four (e.g., mm/DD/yyyy).
- </para>
- <para>
- It's possible to override the input pattern globally
- using component configuration. Consult the JavaDoc for
- this class to see examples.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.faces.facesMessages</literal></term>
- <listitem>
- <para>
- Allows faces success messages to propagate across a browser redirect.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>add(FacesMessage facesMessage)</literal> — add
- a faces message, which will be displayed during the next render
- response phase that occurs in the current conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>add(String messageTemplate)</literal> — add
- a faces message, rendered from the given message template
- which may contain EL expressions.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>add(Severity severity, String messageTemplate)</literal> —
- add a faces message, rendered from the given message template
- which may contain EL expressions.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>addFromResourceBundle(String key)</literal> —
- add a faces message, rendered from a message template defined
- in the Seam resource bundle which may contain EL expressions.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>addFromResourceBundle(Severity severity, String key)</literal> —
- add a faces message, rendered from a message template defined
- in the Seam resource bundle which may contain EL expressions.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>clear()</literal> — clear all messages.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.faces.redirect</literal></term>
- <listitem>
- <para>
- A convenient API for performing redirects with parameters (this
- is especially useful for bookmarkable search results screens).
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>redirect.viewId</literal> — the JSF view id
- to redirect to.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>redirect.conversationPropagationEnabled</literal> —
- determines whether the conversation will propagate across the
- redirect.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>redirect.parameters</literal> — a map of
- request parameter name to value, to be passed in the redirect
- request.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>execute()</literal> — perform the redirect
- immediately.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>captureCurrentRequest()</literal> — stores
- the view id and request parameters of the current GET
- request (in the conversation context), for later use
- by calling <literal>execute()</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.faces.httpError</literal></term>
- <listitem>
- <para>
- A convenient API for sending HTTP errors.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.ui.renderStampStore</literal></term>
- <listitem>
- <para>
- A component (session-scoped by default) responsible for maintaining a
- collection of render stamps. A render stamp is an indicator as to whether a
- form which was rendered has been submitted. This store is useful when the
- client-side state saving method of JSF is being used because it puts the
- determination of whether a form has been posted in the control of the server
- rather than in the component tree which is maintained on the client.
- </para>
- <para>
- To unbind this check from the session (which is one of the main design goals
- of client-side state saving) an implementation must be provided that stores
- the render stamps in the application (valid as long as the application is
- running) or the database (valid across server restarts).
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>maxSize</literal> — The maximum number of stamps
- to be kept in the store. Default: 100
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- These components are installed when the class <literal>javax.faces.context.FacesContext</literal>
- is available on the classpath.
- </para>
- </section>
-
- <section>
- <title>Utility components</title>
- <para>
- These components are merely useful.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.core.events</literal></term>
- <listitem>
- <para>
- An API for raising events that can be observed via
- <literal>@Observer</literal> methods, or method
- bindings in <literal>components.xml</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>raiseEvent(String type)</literal> — raise
- an event of a particular type and distribute to all
- observers.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>raiseAsynchronousEvent(String type)</literal> —
- raise an event to be processed asynchronously by the EJB3
- timer service.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>raiseTimedEvent(String type, ....)</literal> —
- schedule an event to be processed asynchronously by the EJB3
- timer service.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>addListener(String type, String methodBinding)</literal>
- — add an observer for a particular event type.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.core.interpolator</literal></term>
- <listitem>
- <para>
- An API for interpolating the values of JSF EL expressions in
- Strings.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>interpolate(String template)</literal> — scan
- the template for JSF EL expressions of the form <literal>#{...}</literal>
- and replace them with their evaluated values.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.core.expressions</literal></term>
- <listitem>
- <para>
- An API for creating value and method bindings.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>createValueBinding(String expression)</literal> — create
- a value binding object.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>createMethodBinding(String expression)</literal> — create
- a method binding object.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.core.pojoCache</literal></term>
- <listitem>
- <para>
- Manager component for a JBoss Cache <literal>PojoCache</literal>
- instance.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>pojoCache.cfgResourceName</literal> — the name of
- the configuration file. Default to <literal>treecache.xml</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- All of these components are always installed.
- </para>
- </section>
-
- <section>
- <title>Components for internationalization and themes</title>
- <para>
- The next group of components make it easy to build internationalized user interfaces
- using Seam.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.core.locale</literal></term>
- <listitem>
- <para>
- The Seam locale.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.international.timezone</literal></term>
- <listitem>
- <para>
- The Seam timezone. The timezone is session scoped.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.core.resourceBundle</literal></term>
- <listitem>
- <para>
- The Seam resource bundle. The resource bundle is stateless. The Seam
- resource bundle performs a depth-first search for keys in a list of Java
- resource bundles.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.core.resourceLoader</literal></term>
- <listitem>
- <para>
- The resource loader provides access to application resources and resource bundles.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>resourceLoader.bundleNames</literal> — the names of
- the Java resource bundles to search when the Seam resource bundle is
- used. Default to <literal>messages</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.international.localeSelector</literal></term>
- <listitem>
- <para>
- Supports selection of the locale either at configuration time,
- or by the user at runtime.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>select()</literal> — select the specified locale.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>localeSelector.locale</literal> — the actual
- <literal>java.util.Locale</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>localeSelector.localeString</literal> — the
- stringified representation of the locale.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>localeSelector.language</literal> — the language for
- the specified locale.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>localeSelector.country</literal> — the country for
- the specified locale.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>localeSelector.variant</literal> — the variant for
- the specified locale.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>localeSelector.supportedLocales</literal> — a list
- of <literal>SelectItem</literal>s representing the supported locales
- listed in <literal>jsf-config.xml</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>localeSelector.cookieEnabled</literal> — specifies
- that the locale selection should be persisted via a cookie.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.international.timezoneSelector</literal></term>
- <listitem>
- <para>
- Supports selection of the timezone either at configuration time,
- or by the user at runtime.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>select()</literal> — select the specified locale.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>timezoneSelector.timezone</literal> — the actual
- <literal>java.util.TimeZone</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>timezoneSelector.timeZoneId</literal> — the
- stringified representation of the timezone.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>timezoneSelector.cookieEnabled</literal> — specifies
- that the timezone selection should be persisted via a cookie.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.international.messages</literal></term>
- <listitem>
- <para>
- A map containing internationalized messages rendered from message
- templates defined in the Seam resource bundle.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.theme.themeSelector</literal></term>
- <listitem>
- <para>
- Supports selection of the theme either at configuration time,
- or by the user at runtime.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>select()</literal> — select the specified theme.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>theme.availableThemes</literal> — the list of
- defined themes.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>themeSelector.theme</literal> — the selected
- theme.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>themeSelector.themes</literal> — a list
- of <literal>SelectItem</literal>s representing the defined
- themes.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>themeSelector.cookieEnabled</literal> — specifies
- that the theme selection should be persisted via a cookie.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.theme.theme</literal></term>
- <listitem>
- <para>
- A map containing theme entries.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
-
- <para>
- All of these components are always installed.
- </para>
- </section>
-
- <section>
- <title>Components for controlling conversations</title>
- <para>
- The next group of components allow control of conversations by the application or
- user interface.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.core.conversation</literal></term>
- <listitem>
- <para>
- API for application control of attributes of the current Seam conversation.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>getId()</literal> — returns the current conversation id
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>isNested()</literal> — is the current conversation a
- nested conversation?
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>isLongRunning()</literal> — is the current conversation a
- long-running conversation?
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>getId()</literal> — returns the current conversation id
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>getParentId()</literal> — returns the conversation id
- of the parent conversation
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>getRootId()</literal> — returns the conversation id
- of the root conversation
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>setTimeout(int timeout)</literal> — sets the timeout
- for the current conversation
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>setViewId(String outcome)</literal> — sets the view id
- to be used when switching back to the current conversation from the
- conversation switcher, conversation list, or breadcrumbs.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>setDescription(String description)</literal> — sets the
- description of the current conversation to be displayed in the
- conversation switcher, conversation list, or breadcrumbs.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>redirect()</literal> — redirect to the last well-defined
- view id for this conversation (useful after login challenges).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>leave()</literal> — exit the scope of this conversation,
- without actually ending the conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>begin()</literal> — begin a long-running conversation
- (equivalent to <literal>@Begin</literal>).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>beginPageflow(String pageflowName)</literal> — begin a
- long-running conversation with a pageflow (equivalent to
- <literal>@Begin(pageflow="...")</literal>).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>end()</literal> — end a long-running conversation
- (equivalent to <literal>@End</literal>).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pop()</literal> — pop the conversation stack, returning
- to the parent conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>root()</literal> — return to the root conversation of
- the conversation stack.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>changeFlushMode(FlushModeType flushMode)</literal> — change
- the flush mode of the conversation.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.core.conversationList</literal></term>
- <listitem>
- <para>
- Manager component for the conversation list.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.core.conversationStack</literal></term>
- <listitem>
- <para>
- Manager component for the conversation stack (breadcrumbs).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.faces.switcher</literal></term>
- <listitem>
- <para>
- The conversation switcher.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- All of these components are always installed.
- </para>
-
- </section>
-
- <section>
- <title>jBPM-related components</title>
- <para>
- These components are for use with jBPM.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.pageflow.pageflow</literal></term>
- <listitem>
- <para>
- API control of Seam pageflows.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>isInProcess()</literal> — returns <literal>true</literal>
- if there is currently a pageflow in process
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>getProcessInstance()</literal> — returns jBPM
- <literal>ProcessInstance</literal> for the current pageflow
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>begin(String pageflowName)</literal> — begin a pageflow
- in the context of the current conversation
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>reposition(String nodeName)</literal> — reposition the
- current pageflow to a particular node
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.actor</literal></term>
- <listitem>
- <para>
- API for application control of attributes of the jBPM actor associated
- with the current session.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>setId(String actorId)</literal> — sets the jBPM
- actor id of the current user.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>getGroupActorIds()</literal> — returns a
- <literal>Set</literal> to which jBPM actor ids for the
- current users groups may be added.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.transition</literal></term>
- <listitem>
- <para>
- API for application control of the jBPM transition for the current
- task.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>setName(String transitionName)</literal> — sets the
- jBPM transition name to be used when the current task is ended
- via <literal>@EndTask</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.businessProcess</literal></term>
- <listitem>
- <para>
- API for programmatic control of the association between the
- conversation and business process.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>businessProcess.taskId</literal> — the id of the task
- associated with the current conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>businessProcess.processId</literal> — the id of the process
- associated with the current conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>businessProcess.hasCurrentTask()</literal> — is a task
- instance associated with the current conversation?
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>businessProcess.hasCurrentProcess()</literal> — is a process
- instance associated with the current conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>createProcess(String name)</literal> — create an
- instance of the named process definition and associate it with
- the current conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>startTask()</literal> — start the task
- associated with the current conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>endTask(String transitionName)</literal> — end the task
- associated with the current conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>resumeTask(Long id)</literal> — associate the task with
- the given id with the current conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>resumeProcess(Long id)</literal> — associate the process
- with the given id with the current conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>transition(String transitionName)</literal> — trigger
- the transition.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.taskInstance</literal></term>
- <listitem>
- <para>
- Manager component for the jBPM <literal>TaskInstance</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.processInstance</literal></term>
- <listitem>
- <para>
- Manager component for the jBPM <literal>ProcessInstance</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.jbpmContext</literal></term>
- <listitem>
- <para>
- Manager component for an event-scoped <literal>JbpmContext</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.taskInstanceList</literal></term>
- <listitem>
- <para>
- Manager component for the jBPM task list.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.pooledTaskInstanceList</literal></term>
- <listitem>
- <para>
- Manager component for the jBPM pooled task list.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.taskInstanceListForType</literal></term>
- <listitem>
- <para>
- Manager component for the jBPM task lists.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.pooledTask</literal></term>
- <listitem>
- <para>
- Action handler for pooled task assignment.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.processInstanceFinder</literal></term>
- <listitem>
- <para>
- Manager for the process instance task list.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.processInstanceList</literal></term>
- <listitem>
- <para>
- The process instance task list.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- All of these components are installed whenever the component
- <literal>org.jboss.seam.bpm.jbpm</literal> is installed.
- </para>
-
- </section>
-
- <section>
- <title>Security-related components</title>
- <para>
- These components relate to web-tier security.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.web.userPrincipal</literal></term>
- <listitem>
- <para>
- Manager component for the current user <literal>Principal</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.web.isUserInRole</literal></term>
- <listitem>
- <para>
- Allows JSF pages to choose to render a control, depending upon
- the roles available to the current principal.
- <literal><h:commandButton value="edit" rendered="#{isUserInRole['admin']}"/></literal>.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>JMS-related components</title>
- <para>
- These components are for use with managed <literal>TopicPublisher</literal>s
- and <literal>QueueSender</literal>s (see below).
- </para>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.jms.queueSession</literal></term>
- <listitem>
- <para>
- Manager component for a JMS <literal>QueueSession</literal> .
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.jms.topicSession</literal></term>
- <listitem>
- <para>
- Manager component for a JMS <literal>TopicSession</literal> .
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section id="components.mail">
- <title>Mail-related components</title>
- <para>
- These components are for use with Seam's Email support
- </para>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.mail.mailSession</literal></term>
- <listitem>
- <para>
- Manager component for a JavaMail <literal>Session</literal>. The
- session can be either looked up in the JNDI context (by setting the
- <literal>sessionJndiName</literal> property) or it can created from the
- configuration options in which case the <literal>host</literal> is
- mandatory.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>org.jboss.seam.mail.mailSession.host</literal> — the hostname of the SMTP server to use
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.mail.mailSession.port</literal> — the port of the SMTP server to use
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.mail.mailSession.username</literal> — the username to use to connect to the SMTP server.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.mail.mailSession.password</literal> — the password to use to connect to the SMTP server
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.mail.mailSession.debug</literal> — enable JavaMail debugging (very verbose)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.mail.mailSession.ssl</literal> — enable SSL connection to SMTP (will default to port 465)
- </para>
- <para>
- <literal>org.jboss.seam.mail.mailSession.tls</literal> — by default true, enable TLS support in the mail session
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.mail.mailSession.sessionJndiName</literal> — name under which a javax.mail.Session is bound to JNDI.
- If supplied, all other properties will be ignored.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>Infrastructural components</title>
- <para>
- These components provide critical platform infrastructure. You can install a component
- which isn't installed by default by setting <literal>install="true"</literal> on the
- component in <literal>components.xml</literal>.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.core.init</literal></term>
- <listitem>
- <para>
- Initialization settings for Seam. Always installed.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>org.jboss.seam.core.init.jndiPattern</literal> — the JNDI
- pattern used for looking up session beans
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.core.init.debug</literal> — enable Seam
- debug mode. This should be set to false when in production. You may see
- errors if the system is placed under any load and debug is enabled.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.core.init.clientSideConversations</literal> —
- if set to <literal>true</literal>, Seam will save conversation context
- variables in the client instead of in the <literal>HttpSession</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.core.manager</literal></term>
- <listitem>
- <para>
- Internal component for Seam page and conversation context management.
- Always installed.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>org.jboss.seam.core.manager.conversationTimeout</literal> —
- the conversation context timeout in milliseconds.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.core.manager.concurrentRequestTimeout</literal> —
- maximum wait time for a thread attempting to gain a lock on the long-running
- conversation context.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.core.manager.conversationIdParameter</literal> —
- the request parameter used to propagate the conversation id, default
- to <literal>conversationId</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.core.manager.conversationIsLongRunningParameter</literal> —
- the request parameter used to propagate information about whether the conversation
- is long-running, default to <literal>conversationIsLongRunning</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.core.manager.defaultFlushMode</literal> —
- set the flush mode set by default on any Seam Managed Persistence Context.
- By default <literal>AUTO</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.navigation.pages</literal></term>
- <listitem>
- <para>
- Internal component for Seam workspace management. Always installed.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>org.jboss.seam.navigation.pages.noConversationViewId</literal>
- — global setting for the view id to redirect to when a
- conversation entry is not found on the server side.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.navigation.pages.loginViewId</literal>
- — global setting for the view id to redirect to when an
- unauthenticated user tries to access a protected view.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.navigation.pages.httpPort</literal>
- — global setting for the port to use when the http scheme
- is requested.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.navigation.pages.httpsPort</literal>
- — global setting for the port to use when the https scheme
- is requested.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.navigation.pages.resources</literal>
- — a list of resources to search for <literal>pages.xml</literal>
- style resources. Defaults to <literal>WEB-INF/pages.xml</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.bpm.jbpm</literal></term>
- <listitem>
- <para>
- Bootstraps a <literal>JbpmConfiguration</literal>. Install as class
- <literal>org.jboss.seam.bpm.Jbpm</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>org.jboss.seam.bpm.jbpm.processDefinitions</literal> —
- a list of resource names of jPDL files to be used for orchestration
- of business processes.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.bpm.jbpm.pageflowDefinitions</literal> —
- a list of resource names of jPDL files to be used for orchestration
- of conversation page flows.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.core.conversationEntries</literal></term>
- <listitem>
- <para>
- Internal session-scoped component recording the active long-running conversations
- between requests.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.faces.facesPage</literal></term>
- <listitem>
- <para>
- Internal page-scoped component recording the conversation context associated
- with a page.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.persistence.persistenceContexts</literal></term>
- <listitem>
- <para>
- Internal component recording the persistence contexts which were used in
- the current conversation.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.jms.queueConnection</literal></term>
- <listitem>
- <para>
- Manages a JMS <literal>QueueConnection</literal>. Installed whenever
- managed <literal>QueueSender</literal> is installed.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>org.jboss.seam.jms.queueConnection.queueConnectionFactoryJndiName</literal>
- — the JNDI name of a JMS <literal>QueueConnectionFactory</literal>. Default
- to <literal>UIL2ConnectionFactory</literal>
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.jms.topicConnection</literal></term>
- <listitem>
- <para>
- Manages a JMS <literal>TopicConnection</literal>. Installed whenever
- managed <literal>TopicPublisher</literal> is installed.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>org.jboss.seam.jms.topicConnection.topicConnectionFactoryJndiName</literal>
- — the JNDI name of a JMS <literal>TopicConnectionFactory</literal>. Default
- to <literal>UIL2ConnectionFactory</literal>
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.persistence.persistenceProvider</literal></term>
- <listitem>
- <para>
- Abstraction layer for non-standardized features of JPA provider.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.core.validators</literal></term>
- <listitem>
- <para>
- Caches instances of Hibernate Validator <literal>ClassValidator</literal>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.faces.validation</literal></term>
- <listitem>
- <para>
- Allows the application to determine whether validation
- failed or was successful.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.debug.introspector</literal></term>
- <listitem>
- <para>
- Support for the Seam Debug Page.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.debug.contexts</literal></term>
- <listitem>
- <para>
- Support for the Seam Debug Page.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.exception.exceptions</literal></term>
- <listitem>
- <para>
- Internal component for exception handling.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.transaction.transaction</literal></term>
- <listitem>
- <para>
- API for controlling transactions and abstracting the underlying
- transaction management implementation behind a JTA-compatible
- interface.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><literal>org.jboss.seam.faces.safeActions</literal></term>
- <listitem>
- <para>
- Decides if an action expression in an incoming URL is safe. This
- is done by checking that the action expression exists in the view.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
- <section>
- <title>Miscellaneous components</title>
- <para>
- These components don't fit into
- </para>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.async.dispatcher</literal></term>
- <listitem>
- <para>
- Dispatcher stateless session bean for asynchronous methods.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.core.image</literal></term>
- <listitem>
- <para>
- Image manipulation and interrogation.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.core.pojoCache</literal></term>
- <listitem>
- <para>
- Manager component for a PojoCache instance.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <variablelist>
- <varlistentry>
- <term><literal>org.jboss.seam.core.uiComponent</literal></term>
- <listitem>
- <para>
- Manages a map of UIComponents keyed by component id.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
-
-
-
- </section>
-
- <section>
- <title>Special components</title>
- <para>
- Certain special Seam component classes are installable multiple times under names
- specified in the Seam configuration. For example, the following lines in
- <literal>components.xml</literal> install and configure two Seam components:
- </para>
-
- <programlisting role="XML"><![CDATA[<component name="bookingDatabase"
- class="org.jboss.seam.persistence.ManagedPersistenceContext">
- <property name="persistenceUnitJndiName">java:/comp/emf/bookingPersistence</property>
-</component>
-
-<component name="userDatabase"
- class="org.jboss.seam.persistence.ManagedPersistenceContext">
- <property name="persistenceUnitJndiName">java:/comp/emf/userPersistence</property>
+<component name="userDatabase"
+ class="org.jboss.seam.persistence.ManagedPersistenceContext">
+ <property name="persistenceUnitJndiName">
+ java:/comp/emf/userPersistence
+ </ property>
</component>]]></programlisting>
-
- <para>
- The Seam component names are <literal>bookingDatabase</literal> and
- <literal>userDatabase</literal>.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><emphasis><entityManager></emphasis></term>
- <term><literal>org.jboss.seam.persistence.ManagedPersistenceContext</literal></term>
- <listitem>
- <para>
- Manager component for a conversation scoped managed <literal>EntityManager</literal>
- with an extended persistence context.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis><entityManager></emphasis>.entityManagerFactory
- — a value binding expression that evaluates to an instance of
- <literal>EntityManagerFactory</literal>.
- </para>
- <para>
- <emphasis><entityManager></emphasis>.persistenceUnitJndiName
- — the JNDI name of the entity manager factory, default to
- java:/<emphasis><managedPersistenceContext></emphasis>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis><entityManagerFactory></emphasis></term>
- <term><literal>org.jboss.seam.persistence.EntityManagerFactory</literal></term>
- <listitem>
- <para>
- Manages a JPA <literal>EntityManagerFactory</literal>. This is most useful
- when using JPA outside of an EJB 3.0 supporting environment.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>entityManagerFactory.persistenceUnitName</literal> —
- the name of the persistence unit.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- See the API JavaDoc for further configuration properties.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis><session></emphasis></term>
- <term><literal>org.jboss.seam.persistence.ManagedSession</literal></term>
- <listitem>
- <para>
- Manager component for a conversation scoped managed Hibernate <literal>Session</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis><session></emphasis>.sessionFactory
- — a value binding expression that evaluates to an instance of
- <literal>SessionFactory</literal>.
- </para>
- <para>
- <emphasis><session></emphasis>.sessionFactoryJndiName
- — the JNDI name of the session factory, default to
- java:/<emphasis><managedSession></emphasis>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis><sessionFactory></emphasis></term>
- <term><literal>org.jboss.seam.persistence.HibernateSessionFactory</literal></term>
- <listitem>
- <para>
- Manages a Hibernate <literal>SessionFactory</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal><sessionFactory>.cfgResourceName</literal> —
- the path to the configuration file. Default to <literal>hibernate.cfg.xml</literal>.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- See the API JavaDoc for further configuration properties.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis><managedQueueSender></emphasis></term>
- <term><literal>org.jboss.seam.jms.ManagedQueueSender</literal></term>
- <listitem>
- <para>
- Manager component for an event scoped managed JMS <literal>QueueSender</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis><managedQueueSender></emphasis>.queueJndiName
- — the JNDI name of the JMS queue.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis><managedTopicPublisher></emphasis></term>
- <term><literal>org.jboss.seam.jms.ManagedTopicPublisher</literal></term>
- <listitem>
- <para>
- Manager component for an event scoped managed JMS <literal>TopicPublisher</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis><managedTopicPublisher></emphasis>.topicJndiName
- — the JNDI name of the JMS topic.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis><managedWorkingMemory></emphasis></term>
- <term><literal>org.jboss.seam.drools.ManagedWorkingMemory</literal></term>
- <listitem>
- <para>
- Manager component for a conversation scoped managed Drools <literal>WorkingMemory</literal>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis><managedWorkingMemory></emphasis>.ruleBase
- — a value expression that evaluates to an instance of <literal>RuleBase</literal>.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis><ruleBase></emphasis></term>
- <term><literal>org.jboss.seam.drools.RuleBase</literal></term>
- <listitem>
- <para>
- Manager component for an application scoped Drools <literal>RuleBase</literal>.
- <emphasis>Note that this is not really intended for production usage, since
- it does not support dynamic installation of new rules.</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <emphasis><ruleBase></emphasis>.ruleFiles
- — a list of files containing Drools rules.
- </para>
- <para>
- <emphasis><ruleBase></emphasis>.dslFile
- — a Drools DSL definition.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis><entityHome></emphasis></term>
- <term><literal>org.jboss.seam.framework.EntityHome</literal></term>
- <listitem>
- <para></para>
- <!-- TODO: Document this -->
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis><hibernateEntityHome></emphasis></term>
- <term><literal>org.jboss.seam.framework.HibernateEntityHome</literal></term>
- <listitem>
- <para></para>
- <!-- TODO: Document this -->
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis><entityQuery></emphasis></term>
- <term><literal>org.jboss.seam.framework.EntityQuery</literal></term>
- <listitem>
- <para></para>
- <!-- TODO: Document this -->
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><emphasis><hibernateEntityQuery></emphasis></term>
- <term><literal>org.jboss.seam.framework.HibernateEntityQuery</literal></term>
- <listitem>
- <para></para>
- <!-- TODO: Document this -->
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
+ <para>
+ The Seam component names are <literal>bookingDatabase</literal> and <literal>userDatabase</literal>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis><entityManager></emphasis></term>
+ <term><literal>org.jboss.seam.persistence.ManagedPersistenceContext</literal></term>
+ <listitem>
+ <para>
+ A manager component for a conversation-scoped, managed <literal>EntityManager</literal> with an extended persistence context.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis><entityManager></emphasis>.entityManagerFactory — a value binding expression that evaluates to an instance of <literal>EntityManagerFactory</literal>.
+ </para>
+ <para>
+ <emphasis><entityManager></emphasis>.persistenceUnitJndiName — the JNDI name of the entity manager factory. By default, this is <literal>java:/<option><managedPersistenceContext></option></literal> .
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis><entityManagerFactory></emphasis></term>
+ <term><literal>org.jboss.seam.persistence.EntityManagerFactory</literal></term>
+ <listitem>
+ <para>
+ Manages a JPA <literal>EntityManagerFactory</literal>. This is most useful when using JPA outside of an environment with EJB3 support.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>entityManagerFactory.persistenceUnitName</literal> — the name of the persistence unit.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ See the API JavaDoc for further configuration properties.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis><session></emphasis></term>
+ <term><literal>org.jboss.seam.persistence.ManagedSession</literal></term>
+ <listitem>
+ <para>
+ A manager component for a conversation-scoped, managed Hibernate <literal>Session</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis><session></emphasis>.sessionFactory — a value binding expression that evaluates to an instance of <literal>SessionFactory</literal>.
+ </para>
+ <para>
+ <emphasis><session></emphasis>.sessionFactoryJndiName — the JNDI name of the session factory. By default, this is <literal>java:/<option><managedSession></option></literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis><sessionFactory></emphasis></term>
+ <term><literal>org.jboss.seam.persistence.HibernateSessionFactory</literal> </term>
+ <listitem>
+ <para>
+ Manages a Hibernate <literal>SessionFactory</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal><sessionFactory>.cfgResourceName</literal> — specifies the path to the configuration file. By default, this is <filename>hibernate.cfg.xml</filename>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ See the API JavaDoc for further configuration properties.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis><managedQueueSender></emphasis></term>
+ <term><literal>org.jboss.seam.jms.ManagedQueueSender</literal></term>
+ <listitem>
+ <para>
+ A manager component for an event scoped managed JMS <literal>QueueSender</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis><managedQueueSender></emphasis>.queueJndiName — the JNDI name of the JMS queue.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis><managedTopicPublisher></emphasis></term>
+ <term><literal>org.jboss.seam.jms.ManagedTopicPublisher</literal></term>
+ <listitem>
+ <para>
+ A manager component for an event-scoped, managed JMS <literal>TopicPublisher</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis><managedTopicPublisher></emphasis>.topicJndiName — the JNDI name of the JMS topic.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis><managedWorkingMemory></emphasis></term>
+ <term><literal>org.jboss.seam.drools.ManagedWorkingMemory</literal></term>
+ <listitem>
+ <para>
+ A manager component for a conversation-scoped, managed Drools <literal>WorkingMemory</literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis><managedWorkingMemory></emphasis>.ruleBase — a value expression that evaluates to an instance of <literal>RuleBase</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis><ruleBase></emphasis></term>
+ <term><literal>org.jboss.seam.drools.RuleBase</literal></term>
+ <listitem>
+ <para>
+ A manager component for an application-scoped Drools <literal>RuleBase</literal>. Note that this does not support dynamic installation of new rules, so it is not appropriate for use in production.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis><ruleBase></emphasis>.ruleFiles — a list of files containing Drools rules.
+ </para>
+ <para>
+ <emphasis><ruleBase></emphasis>.dslFile — a Drools DSL definition.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <!-- #modify: TODO - content required! <varlistentry> <term><emphasis><entityHome></emphasis></term> <term><literal>org.jboss.seam.framework.EntityHome</literal></term> <listitem> <para></para> </listitem> </varlistentry> <varlistentry> <term><emphasis><hibernateEntityHome></emphasis></term> <term><literal>org.jboss.seam.framework.HibernateEntityHome</literal></term > <listitem> <para></para> </listitem> </varlistentry> <varlistentry> <term><emphasis><entityQuery></emphasis></term> <term><literal>org.jboss.seam.framework.EntityQuery</literal></term> <listitem> <para></para> </listitem> </varlistentry> <varlistentry> <term><emphasis><hibernateEntityQuery></emphasis></term> <term><literal>org.jboss.seam.framework.HibernateEntityQuery</literal></ term> <listitem> <para></para> </listitem> </varlistentry> -->
+ </variablelist>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Concepts.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Concepts.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Concepts.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,1287 +1,956 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<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>
+<chapter id="concepts" >
+ <title>The contextual component model</title>
+ <para>
+ Seam's two core concepts are the notions of a <emphasis>context</emphasis> and a <emphasis>component</emphasis>. Components are stateful objects, usually Enterprise JavaBeans (EJBs). An instance of a component is associated with a context, and assigned a name within that context. <emphasis>Bijection</emphasis> provides a mechanism for aliasing internal component names (instance variables) to contextual names, which allows component trees to be dynamically assembled and reassembled by Seam.
+ </para>
+ <section>
+ <title>Seam contexts</title>
+ <para>
+ Seam has several built-in contexts, which are created and destroyed by the framework. The application does not control context demarcation via explicit Java API calls. Contexts are usually implicit. In some cases, however, contexts are demarcated with annotations.
+ </para>
+ <para>
+ There are a number of basic contexts:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Stateless context
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Event (for instance, a request) context
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Page context
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Conversation context
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Session context
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Business process context
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Application context
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Some of these contexts serve similar purposes in Servlet and related specifications. Two you may not have encountered previously are the <emphasis>conversation context</emphasis> and the <emphasis>business process context</emphasis>. One reason that 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 for business logic. A user login session, for example, is an arbitrary construct in terms of the application workflow. Therefore, most Seam components are scoped to the conversation or business process contexts, since these are the most meaningful contexts in terms of the application.
+ </para>
+ <section>
+ <title>Stateless context</title>
+ <para>
+ Components which are truly stateless (primarily stateless session beans) always operate in the stateless context — the absence of a context, since the instance Seam resolves is not stored. Stateless components are arguably object-oriented, but they are developed regularly and thus form an important part of any Seam application.
+ </para>
+ </section>
+
+ <section>
+ <title>Event context</title>
+ <para>
+ The event context is the "narrowest" stateful context, and expands the notion of the web request to cover other event types. 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 with RMI, or Seam Remoting, the event context is created and destroyed just for the invocation.
+ </para>
+ </section>
+
+ <section>
+ <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 rendering the page, and can then access it from any event that originates from that page. This is especially useful for functionality such as 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>
+ </section>
+
+ <section>
+ <title>Conversation context</title>
+ <para>
+ The conversation context is a central concept to Seam. A <emphasis>conversation</emphasis> is a single unit of work from the user's perspective. In reality, it may span several interactions with a user — several requests and several data transactions. But to the user, a conversation solves a single problem. For example, the processes of booking a hotel, approving a contract, and creating an order are all conversations. It may help to think of a conversation as implementing a single "use case", although the relationship is not necessarily this exact.
+ </para>
+ <para>
+ A conversation holds state associated with the user's present task, in the current window. A single user may have multiple conversations in progress at any point in time, usually spanning multiple windows. The conversation context ensures that state from the different conversations does not collide and cause bugs.
+ </para>
+ <para>
+ Some conversations last only for a single request. Conversations that span multiple requests must be demarcated with annotations provided by Seam.
+ </para>
+ <para>
+ Some conversations are also <emphasis>tasks</emphasis>. A task is a conversation that is significant to a long-running business process, and can trigger a business process state transition when completed successfully. Seam provides a special set of annotations for task demarcation.
+ </para>
+ <para>
+ Conversations can be <emphasis>nested</emphasis>, with one conversation taking place inside a broader conversation. This is an advanced feature.
+ </para>
+ <para>
+ Between requests, conversation state is usually held in the Servlet session. Seam implements configurable <emphasis>conversation timeout</emphasis> to automatically destroy inactive conversations, which ensures that the state held by a single user login session does not continue to grow if a user abandons a conversation. In the same process, Seam serializes the processing of concurrent requests in the same long-running conversation context.
+ </para>
+ <para>
+ Alternatively, Seam can also be configured to storce conversational state in the client browser.
+ </para>
+ </section>
+
+ <section>
+ <title>Session context</title>
+ <para>
+ A session context holds state associated with the user login session. There are some cases where it is useful for state to be shared between several conversations. However, session context should not usually hold 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>
+ </section>
+
+ <section>
+ <title>Business process context</title>
+ <para>
+ The business process context holds state associated with long-running business processes. This state is managed and made persistent by the BPM engine (in this case, JBoss jBPM). The business process spans multiple interactions with multiple users. State is shared between multiple users in a well-defined manner. The current task determines the current business process instance, and the business process lifecycle is defined externally with <emphasis>process definition language</emphasis>, so there are no special annotations for business process demarcation.
+ </para>
+ </section>
+
+ <section>
+ <title>Application context</title>
+ <para>
+ The application context is the Servlet context from the Servlet specification. Application context is used primarily to hold static information such as configuration data, reference data or metamodels. For example, Seam stores its own configuration and metamodel in the application context.
+ </para>
+ </section>
+
+ <section>
+ <title>Context variables</title>
+ <para>
+ A context defines a namespace through a set of <emphasis>context variables</emphasis>. These work similarly to session or request attributes in the Servlet specification. Any value may be bound to a context variable, but they are usually bound to Seam component instances.
+ </para>
+ <para>
+ The context variable name identifies a component instance within a context. (The context variable name usually matches the component name.) You can programmatically access a named component instance in a particula scope with the <literal>Contexts</literal> class, which provides access to several thread-bound instances of the <literal>Context</literal> interface:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[User user = (User) Contexts.getSessionContext().get("user");
+]]></programlisting>
+ <para>
+ You may also set or change the value associated with a name:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[Contexts.getSessionContext().set("user", user);
+]]></programlisting>
+ <para>
+ However, components are usually obtained from a context via <emphasis>injection</emphasis>. Component instances are subsequently given to contexts via <emphasis>outjection</emphasis>.
+ </para>
+ </section>
+
+ <section>
+ <title>Context search priority</title>
+ <para>
+ Sometimes, component instances are obtained from a particular known scope. At other times, all stateful scopes are searched, in the following order of priority:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Event context
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Page context
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Conversation context
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Session context
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Business process context
+ </para>
+ </listitem>
+ <listitem>
+ <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>
+ </section>
+
+ <section id="concurrency">
+ <title>Concurrency model</title>
+ <para>
+ Neither the Servlet, nor EJB specifications, define facilities for managing concurrent requests from the same client. The Servlet container lets all threads run concurrently, without ensuring threadsafeness. The EJB container allows concurrent access of stateless components, and throws an exception when multiple threads access a stateful session bean. This is sufficient for web applications based around fine-grained, synchronous requests. However, for modern applications, which frequently use asynchronous (AJAX) requests, concurrency support is vital. Therefore, Seam adds a concurrency management layer to its context model.
+ </para>
+ <para>
+ Session and application contexts are multi-threaded in Seam, allowing concurrent requests to be processed concurrently. Event and page contexts are single-threaded. Strictly, the business process context is multi-threaded, but concurrency here is rare, and can usually be disregarded. Seam serializes concurrent requests within a long-running conversation context in order to enforce a <emphasis>single thread per conversation per process</emphasis> model for the conversation context.
+ </para>
+ <para>
+ Because session context is multi-threaded and often contains volatile state, Seam always protects session-scoped components from concurrent access while Seam interceptors are enabled. If interceptors are disabled, any required thread safety must be implemented by the component itself. By default, Seam serializes requests to session-scoped session beans and JavaBeans, and detects and breaks any deadlocks that occur. However, this is not default behavior for application-scoped components, since they do not usually hold volatile state, and global synchronization is extremely expensive. Serialized threading models can be forced 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>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Seam components</title>
+ <para>
+ Seam components are Plain Old Java Objects (POJOs). Specifically, they are JavaBeans, or Enterpise JavaBean 3.0 (EJB3) enterprise beans. While Seam does not require components to be EJBs, and can be used without an EJB3-compliant container, Seam was designed with EJB3 in mind, and includes deep integration with EJB3. Seam supports the following <emphasis>component types</emphasis>:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ EJB3 stateless session beans
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ EJB3 stateful session beans
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ EJB3 entity beans (for instance, JPA entity classes)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ JavaBeans
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ EJB3 message-driven beans
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Spring beans (see <xref linkend="spring" />)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Stateless session beans</title>
+ <para>
+ Stateless session bean components cannot hold state across multiple invocations, so they usually operate upon the state of other components in the various Seam contexts. They can be used as JSF action listeners, but cannot provide properties to JSF components for display.
+ </para>
+ <para>
+ Stateless session beans always exist in the stateless context. They can be accessed concurrently as a new instance is used for each request. The EJB3 container assigns instances to requests. (Normally, instances are allocated from a reuseable pool, so instance variables can retain data from previous uses of the bean.)
+ </para>
+ <para>
+ Seam stateless session bean components are instantiated with either <literal>Component.getInstance()</literal> or <literal>@In(create=true)</literal>. They should not be directly instantiated via JNDI lookup or the <literal>new</literal> operator.
+ </para>
+ </section>
+
+ <section>
+ <title>Stateful session beans</title>
+ <para>
+ Stateful session bean components can not only hold state across multiple invocations of the bean, but also across multiple requests. Any application state that does not belong in the database should be held by stateful session beans. This is a major difference between Seam and many other web application frameworks. Current conversation data should be stored in the instance variables of a stateful session bean bound to the conversation context, rather than in the <literal>HttpSession</literal>. This lets Seam manage state lifecycle, and ensures there are no collisions between state relating to different concurrent conversations.
+ </para>
+ <para>
+ Stateful session beans are often used as JSF action listeners, and as backing beans to 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 to stateless contexts.
+ </para>
+ <para>
+ Seam serializes concurrent requests to session-scoped stateful session beans while Seam interceptors are enabled.
+ </para>
+ <para>
+ Seam stateful session bean components are instantiated with either <literal>Component.getInstance()</literal> or <literal>@In(create=true)</literal>. They should not be directly instantiated via JNDI lookup or the <literal>new</literal> operator.
+ </para>
+ </section>
+
+ <section>
+ <title>Entity beans</title>
+ <para>
+ Entity beans can function as a Seam component when bound to a context variable. 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 often function as backing beans to provide properties to JSF components for display or form submission. They are commonly used as a backing bean coupled 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, and can never be bound to the stateless context.
+ </para>
+ <note>
+ <para>
+ In a clustered environment, it is less efficient to bind an entity bean directly to a conversation (or session-scoped Seam context variable) than it is to refer to the entity bean with a stateful session bean. Not all Seam applications define entity beans as Seam components for this reason.
+ </para>
+ </note>
+ <para>
+ Seam entity bean components are instantiated with <literal>Component.getInstance()</literal> or <literal>@In(create=true)</literal>, or directly instantiated with the <literal>new</literal> operator.
+ </para>
+ </section>
+
+ <section>
+ <title>JavaBeans</title>
+ <para>
+ JavaBeans are used similarly to stateless or stateful session beans. However, they do not provide functions such as declarative transaction demarcation, declarative security, efficient clustered state replication, EJB3 persistence, timeout methods, etc.
+ </para>
+ <para>
+ In a later chapter<!-- #modify: " (insert xref here)" -->, we show you how to use Seam and Hibernate without an EJB container. In this case, components are JavaBeans rather than session beans.
+ </para>
+ <note>
+ <para>
+ In a clustered environment, it is less efficient to cluster conversation- or session-scoped Seam JavaBean components than it is to cluster stateful session bean components.
+ </para>
+ </note>
+ <para>
+ By default, JavaBeans are bound to the event context.
+ </para>
+ <para>
+ Seam always serializes concurrent requests to session-scoped JavaBeans.
+ </para>
+ <para>
+ Seam JavaBean components are instantiated with <literal>Component.getInstance()</literal> or <literal>@In(create=true)</literal>. They should not be directly instantiated using the <literal>new</literal> operator.
+ </para>
+ </section>
+
+ <section>
+ <title>Message-driven beans</title>
+ <para>
+ Message-driven beans can function as Seam components. However, their call method differs from that of other Seam components — rather than being invoked with the context variable, they listen for messages sent to JMS queues or topics.
+ </para>
+ <para>
+ Message-driven beans cannot be bound to Seam contexts, nor can they access the session or conversation state of their <emphasis>caller</emphasis>. However, they do support bijection and some other Seam functionality.
+ </para>
+ <para>
+ Message-driven beans are never instantiated by the application; they are instantiated by the EJB container when a message is received.
+ </para>
+ </section>
+
+ <section>
+ <title>Interception</title>
+ <para>
+ To perform actions such as bijection, context demarcation, and validation, Seam must intercept component invocations. For JavaBeans, Seam controls component instantiation completely, and no special configuration is required. For entity beans, interception is not required, since bijection and context demarcation are not defined. For session beans, an EJB interceptor must be registered for the session bean component. This can be done with an annotation, as follows:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateless
+ at Interceptors(SeamInterceptor.class)
+public class LoginAction implements Login { ... }
+]]></programlisting>
+ <para>
+ However, it is better to define the interceptor in <filename>ejb-jar.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<interceptors>
+ <interceptor>
+ <interceptor-class>
+ org.jboss.seam.ejb.SeamInterceptor
+ </interceptor-class>
+ </interceptor>
+</interceptors>
- <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>
-
- <itemizedlist>
- <listitem>
- <para> Stateless context </para>
- </listitem>
- <listitem>
- <para> Event (i.e., request) context </para>
- </listitem>
- <listitem>
- <para> Page context </para>
- </listitem>
- <listitem>
- <para> Conversation context </para>
- </listitem>
- <listitem>
- <para> Session context </para>
- </listitem>
- <listitem>
- <para> Business process context </para>
- </listitem>
- <listitem>
- <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>
- 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 (which is basically the absense of a context since the instance Seam resolves is not stored).
- Stateless components are not very interesting, and are arguably not very object-oriented. Nevertheless,
- they do get developed and used and are thus an important part of any Seam application.
- </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
- destroyed just for the invocation.
- </para>
- </sect2>
-
- <sect2>
- <title>Page context</title>
- <para>
- The page context allows you to associate state with a particular instance of a rendered page. You can
- 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" or "user story", but the relationship
- is not necessarily quite exact.
- </para>
- <para>
- A conversation holds state associated with "what the user is doing now, in this window". A single
- user may have multiple conversations in progress at any point in time, usually in multiple windows. The
- conversation context allows us to ensure that state from the different conversations does not collide
- and cause bugs.
- </para>
- <para>
- It might take you some time to get used to thinking of applications in terms of conversations. But
- 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>
- </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>
- </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>
- </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>
- </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>
-
- <programlisting role="JAVA"><![CDATA[User user = (User) Contexts.getSessionContext().get("user");]]></programlisting>
-
- <para>
- You may also set or change the value associated with a name:
- </para>
-
- <programlisting role="JAVA"><![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>
- </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>
-
- <itemizedlist>
- <listitem>
- <para> Event context </para>
- </listitem>
- <listitem>
- <para> Page context </para>
- </listitem>
- <listitem>
- <para> Conversation context </para>
- </listitem>
- <listitem>
- <para> Session context </para>
- </listitem>
- <listitem>
- <para> Business process context </para>
- </listitem>
- <listitem>
- <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>
-
- </sect2>
-
- <sect2 id="concurrency">
- <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 so long as the Seam interceptors
- are not disabled for that component. If interceptors are disabled, then any thread-safety that is
- required must be implemented by the component itself. 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>
-
- <itemizedlist>
- <listitem>
- <para> EJB 3.0 stateless session beans </para>
- </listitem>
- <listitem>
- <para> EJB 3.0 stateful session beans </para>
- </listitem>
- <listitem>
- <para> EJB 3.0 entity beans (i.e., JPA entity classes)</para>
- </listitem>
- <listitem>
- <para> JavaBeans </para>
- </listitem>
- <listitem>
- <para> EJB 3.0 message-driven beans </para>
- </listitem>
- <listitem>
- <para> Spring beans (see <xref linkend="spring"/>)</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 can be accessed concurrently as a new instance is used for each request.
- Assigning the instance to the request is the responsibility of the EJB3 container (normally instances
- will be allocated from a reusable pool meaning that you may find any instance variables contain data
- from previous uses of the bean).
- </para>
- <para>
- Stateless session beans are the least interesting kind of Seam component.
- </para>
- <para>
- Seam stateless session bean components may be instantiated using <literal>Component.getInstance()</literal>
- or <literal>@In(create=true)</literal>. They should not be directly instantiated via JNDI lookup
- or the <literal>new</literal> operator.
- </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 as long
- as the Seam interceptors are not disabled for the bean.
-
- </para>
- <para>
- Seam stateful session bean components may be instantiated using <literal>Component.getInstance()</literal>
- or <literal>@In(create=true)</literal>. They should not be directly instantiated via JNDI lookup
- or the <literal>new</literal> operator.
- </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>
- Seam entity bean components may be instantiated using <literal>Component.getInstance()</literal>,
- <literal>@In(create=true)</literal> or directly using the <literal>new</literal> operator.
- </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>
- Seam JavaBean components may be instantiated using <literal>Component.getInstance()</literal>
- or <literal>@In(create=true)</literal>. They should not be directly instantiated using the
- <literal>new</literal> operator.
- </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 are never instantiated by the application. They are instantiated by the EJB
- container when a message is received.
- </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>
-
- <programlisting role="JAVA"><![CDATA[@Stateless
- at Interceptors(SeamInterceptor.class)
-public class LoginAction implements Login {
- ...
-}]]></programlisting>
-
- <para>
- But a much better way is to define the interceptor in <literal>ejb-jar.xml</literal>.
- </para>
-
- <programlisting role="XML"><![CDATA[<interceptors>
- <interceptor>
- <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
- </interceptor>
-</interceptors>
-
-<assembly-descriptor>
- <interceptor-binding>
- <ejb-name>*</ejb-name>
- <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
- </interceptor-binding>
-</assembly-descriptor>]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Component names</title>
- <para>
- All seam components need a name. We can assign a name to a component using the
- <literal>@Name</literal> annotation:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("loginAction")
- at Stateless
-public class LoginAction implements Login {
- ...
-}]]></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>
- <literal>@Name</literal> is not the only way to define a component name, but we always need
- to specify the name <emphasis>somewhere</emphasis>. If we don't, then none of the other
- Seam annotations will function.
- </para>
-
- <para>
- Whenever Seam instantiates a component, it binds the new instance to a variable in the scope configured
- for the component that matches the component name. This behavior is identical to how JSF managed beans
- work, except that Seam allows you to configure this mapping using annotations rather than XML. You can
- also programmatically bind a component to a context variable. This is 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. Be careful, though, because through a
- programmatic assignment, it's possible to overwrite a context variable that has a reference to a Seam
- component, potentially confusing matters. </para>
- <para>
- For very large applications, and for built-in seam components, qualified component names are often used
- to avoid naming conflicts.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("com.jboss.myapp.loginAction")
- at Stateless
-public class LoginAction implements Login {
- ...
-}]]></programlisting>
-
- <para>
- We may use the qualified component name both in Java code and in JSF's expression language:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandButton type="submit" value="Login"
- action="#{com.jboss.myapp.loginAction.login}"/>]]></programlisting>
-
- <para>
- Since this is noisy, 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 role="XML"><![CDATA[<factory name="loginAction" scope="STATELESS" value="#{com.jboss.myapp.loginAction}"/>]]></programlisting>
-
- <para>
- All of the built-in Seam components have qualified names but can be accessed through
- their unqualified names due to the namespace import feature of Seam.
- The <literal>components.xml</literal> file included in the Seam JAR defines the following
- namespaces.
- </para>
-
-<programlisting><components xmlns="http://jboss.com/products/seam/components">
-
- <import>org.jboss.seam.core</import>
- <import>org.jboss.seam.cache</import>
- <import>org.jboss.seam.transaction</import>
- <import>org.jboss.seam.framework</import>
- <import>org.jboss.seam.web</import>
- <import>org.jboss.seam.faces</import>
- <import>org.jboss.seam.international</import>
- <import>org.jboss.seam.theme</import>
- <import>org.jboss.seam.pageflow</import>
- <import>org.jboss.seam.bpm</import>
- <import>org.jboss.seam.jms</import>
- <import>org.jboss.seam.mail</import>
- <import>org.jboss.seam.security</import>
- <import>org.jboss.seam.security.management</import>
- <import>org.jboss.seam.security.permission</import>
- <import>org.jboss.seam.captcha</import>
- <import>org.jboss.seam.excel.exporter</import>
- <!-- ... --->
-</components>
-</programlisting>
-
- <para>
- When attempting to resolve an unqualified name, Seam will check each of those namespaces, in order.
- You can include additional namespaces in your application's <literal>components.xml</literal> file
- for application-specific namespaces.
- </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>
-
- <programlisting role="JAVA"><![CDATA[@Name("user")
- at Entity
- at Scope(SESSION)
-public class User {
- ...
-}]]></programlisting>
-
- <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>
-
- <programlisting role="JAVA"><![CDATA[@Name("user")
- at Entity
- at Scope(CONVERSATION)
+<assembly-descriptor>
+ <interceptor-binding>
+ <ejb-name>*</ejb-name>
+ <interceptor-class>
+ org.jboss.seam.ejb.SeamInterceptor
+ </interceptor-class>
+ </interceptor-binding>
+</assembly-descriptor>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title>Component names</title>
+ <para>
+ All Seam components require names. Assign a name with the <literal>@Name</literal> annotation:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("loginAction")
+ at Stateless
+public class LoginAction implements Login { ... }
+]]></programlisting>
+ <para>
+ This is the <emphasis>Seam component name</emphasis>, and does not relate to any other name defined by the EJB specification. However, Seam component names work like JSF managed bean names, and can be thought of in identical terms.
+ </para>
+ <para>
+ <literal>@Name</literal> is not the only way to define a component name, but the name must always be specified. No other Seam annotation will function if a name is not defined.
+ </para>
+ <para>
+ When Seam instantiates a component, it binds the new instance to a variable matching the component name in the component's configured scope. This is identical to JSF managed bean behavior, except that Seam lets you configure this mapping with annotations rather than XML. You can also programmatically bind a component to a context variable. This is useful if a particular component serves multiple roles within the system. For example, the current <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. Take care when binding programmatically, because it is possible to overwrite context variables that reference Seam components.
+ </para>
+ <para>
+ For very large applications, and for built-in Seam components, qualified component names are often used to avoid naming conflicts.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("com.jboss.myapp.loginAction")
+ at Stateless
+public class LoginAction implements Login { ... }
+]]></programlisting>
+ <para>
+ The qualified component name can be used both in Java code and in JSF's expression language:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton type="submit" value="Login"
+ action="#{com.jboss.myapp.loginAction.login}"/>
+]]></programlisting>
+ <para>
+ Since this is noisy, Seam also provides a means of aliasing a qualified name to a simple name. Add a line like this to the <filename>components.xml</filename> file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<factory name="loginAction" scope="STATELESS"
+ value="#{com.jboss.myapp.loginAction}"/>
+]]></programlisting>
+ <para>
+ All built-in Seam components have qualified names, but can be accessed through their unqualified names with Seam's <emphasis>namespace-import</emphasis> feature. The <filename>components.xml</filename> file included in the Seam JAR defines the following namespaces:
+ </para>
+
+<programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components">
+ <import>org.jboss.seam.core</import>
+ <import>org.jboss.seam.cache</import>
+ <import>org.jboss.seam.transaction</import>
+ <import>org.jboss.seam.framework</import>
+ <import>org.jboss.seam.web</import>
+ <import>org.jboss.seam.faces</import>
+ <import>org.jboss.seam.international</import>
+ <import>org.jboss.seam.theme</import>
+ <import>org.jboss.seam.pageflow</import>
+ <import>org.jboss.seam.bpm</import>
+ <import>org.jboss.seam.jms</import>
+ <import>org.jboss.seam.mail</import>
+ <import>org.jboss.seam.security</import>
+ <import>org.jboss.seam.security.management</import>
+ <import>org.jboss.seam.security.permission</import>
+ <import>org.jboss.seam.captcha</import>
+ <import>org.jboss.seam.excel.exporter</import>
+ <!-- ... --->
+</components>
+]]></programlisting>
+ <para>
+ When attempting to resolve an unqualified name, Seam will check each of these namespaces, in order. Additional application-specific namespaces can be included in your application's <filename>components.xml</filename> file.
+ </para>
+ </section>
+
+ <section>
+ <title>Defining the component scope</title>
+ <para>
+ The <literal>@Scope</literal> annotation lets us override the scope (context) of a component to define the context a component instance is bound to when instantiated by Seam.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("user")
+ at Entity
+ at Scope(SESSION)
+public class User { ... }
+]]></programlisting>
+ <para>
+ <literal>org.jboss.seam.ScopeType</literal> defines an enumeration of possible scopes.
+ </para>
+ </section>
+
+ <section>
+ <title>Components with multiple roles</title>
+ <para>
+ Some Seam component classes can fulfill multiple roles in the system. For example, the <literal>User</literal> class is usually a session-scoped component representing the current user, but in user administration screens becomes 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> can be bound to multiple context variables, but this lets us do it at the class level to take advantage of automatic instantiation.)
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("user")
+ at Entity
+ at Scope(CONVERSATION)
@Role(name="currentUser", scope=SESSION)
-public class User {
- ...
-}]]></programlisting>
-
- <para>
- The <literal>@Roles</literal> annotation lets us specify as many additional roles as we like.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("user")
- at Entity
- at Scope(CONVERSATION)
- at Roles({@Role(name="currentUser", scope=SESSION),
- @Role(name="tempUser", scope=EVENT)})
-public class User {
- ...
-}]]></programlisting>
-
- </sect2>
-
- <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>
- <programlisting role="JAVA"><![CDATA[FacesMessages.instance().add("Welcome back, #{user.name}!");]]></programlisting>
- </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>
-
- <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>
- </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>
- </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>
- </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>
- The <literal>@In</literal> annotation specifies that a value should be injected, either into an instance
- variable:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("loginAction")
- at Stateless
+public class User { ... }
+]]></programlisting>
+ <para>
+ The <literal>@Roles</literal> annotation lets us specify additional roles as required.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("user")
+ at Entity
+ at Scope(CONVERSATION)
+ at Roles({ @Role(name="currentUser", scope=SESSION),
+ @Role(name="tempUser", scope=EVENT)})
+public class User { ... }
+]]></programlisting>
+ </section>
+
+ <section>
+ <title>Built-in components</title>
+ <para>
+ Seam is implemented as a set of built-in interceptors and components. This makes it easy for applications to interact with built-in components at runtime, or to customize basic Seam functionality 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 in the Java package of the same name.
+ </para>
+ <para>
+ The built-in components may be injected like any other Seam component, but they also provide convenient static <literal>instance()</literal> methods:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[FacesMessages.instance().add("Welcome back, #{user.name}!");
+]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Bijection</title>
+ <para>
+ <emphasis>Dependency injection</emphasis> or <emphasis>inversion of control</emphasis> (IoC) allows one component to reference another by having the container "inject" the component into a setter method or instance variable. In previous dependency injection implementations, injection occurred at component construction, and the reference did not change for the lifetime of the component instance. This is reasonable for stateless components — from the client's perspective, all instances of a particular stateless component are interchangeable. However, Seam emphasizes the use of stateful components, so traditional dependency injection as a construct is less useful. Seam introduces the notion of <emphasis>bijection</emphasis> as a generalization of injection. In contrast to injection, bijection is:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term>contextual</term>
+ <listitem>
+ <para>
+ Bijection is used to assemble stateful components from various different contexts. A component from a <emphasis>wider</emphasis> context can even refer to a component from a <emphasis>narrower</emphasis> context.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>bidirectional</term>
+ <listitem>
+ <para>
+ Values are injected from context variables into attributes of the invoked component, and returned (via outjection) to the context, allowing the invoked component to manipulate contextual variable values simply by setting its own instance variables.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term>dynamic</term>
+ <listitem>
+ <para>
+ 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>
+ </varlistentry>
+ </variablelist>
+ <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. Annotations are used to enable bijection.
+ </para>
+ <para>
+ The <literal>@In</literal> annotation specifies that a value should be injected, either into an instance variable:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("loginAction")
+ at Stateless
public class LoginAction implements Login {
- @In User user;
- ...
-}]]></programlisting>
-
- <para>
- or into a setter method:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("loginAction")
- at Stateless
+ @In User user;
+ ...
+}
+]]>
+</programlisting>
+ <para>
+ or into a setter method:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("loginAction")
+ at Stateless
public class LoginAction implements Login {
- User user;
-
- @In
- public void setUser(User user) {
- this.user=user;
- }
-
- ...
-}]]></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>
- 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>
- For some components, it can be repetitive to have to specify <literal>@In(create=true)</literal> everywhere
- they are used. In such cases, you can annotate the component <literal>@AutoCreate</literal>, and then it
- will always be created, whenever needed, even without the explicit use of <literal>create=true</literal>.
- </para>
-
- <para>
- You can even inject the value of an expression:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("loginAction")
- at Stateless
+ User user;
+ @In
+ public void setUser(User user) { this.user=user; }
+ ...
+}
+]]></programlisting>
+ <para>
+ By default, Seam performs a priority search of all contexts, using the name of the property or instance variable 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, where 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>
+ For some components, specifying <literal>@In(create=true)</literal> each time it is used can be repetitive. In such cases, annotate the component <literal>@AutoCreate</literal>. This way, it will always be created whenever required, even without the explicit use of <literal>create=true</literal>.
+ </para>
+ <para>
+ You can even inject the value of an expression:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("loginAction")
+ at Stateless
public class LoginAction implements Login {
- @In("#{user.username}") String username;
- ...
-}]]></programlisting>
-
- <para>
- Injected values are disinjected (i.e., set to <literal>null</literal>) immediately after method
- completion and outjection.
- </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>
-
- <programlisting role="JAVA"><![CDATA[@Name("loginAction")
- at Stateless
+ @In("#{user.username}") String username;
+ ...
+}
+]]></programlisting>
+ <para>
+ Injected values are disinjected (that is, set to <literal>null</literal>) immediately after method completion and outjection.
+ </para>
+ <para>
+ (More information about component lifecycle and injection can be found in the next chapter<!-- #modify: add xref -->.)
+ </para>
+ <para>
+ The <literal>@Out</literal> annotation specifies that an attribute should be outjected, either from an instance variable:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("loginAction")
+ at Stateless
public class LoginAction implements Login {
- @Out User user;
- ...
-}]]></programlisting>
-
- <para>
- or from a getter method:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("loginAction")
- at Stateless
+ @Out User user;
+ ...
+}
+]]></programlisting>
+ <para>
+ or from a getter method:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("loginAction")
+ at Stateless
public class LoginAction implements Login {
- User user;
-
- @Out
- public User getUser() {
- return user;
- }
-
- ...
-}]]></programlisting>
-
- <para>
- An attribute may be both injected and outjected:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("loginAction")
- at Stateless
+ User user;
+
+ @Out
+ public User getUser() {
+ return user;
+ }
+ ...
+}
+]]></programlisting>
+ <para>
+ An attribute may be both injected and outjected:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("loginAction")
+ at Stateless
public class LoginAction implements Login {
- @In @Out User user;
- ...
-}]]></programlisting>
-
- <para>
- or:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("loginAction")
- at Stateless
+ @In
+ @Out User user;
+ ...
+}
+]]></programlisting>
+ <para>
+ or:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("loginAction")
+ at Stateless
public class LoginAction implements Login {
- User user;
-
- @In
- public void setUser(User user) {
- this.user=user;
- }
-
- @Out
- public User getUser() {
- return user;
- }
-
+ User user;
+
+ @In
+ public void setUser(User user) {
+ this.user=user;
+ }
+
+ @Out
+ public User getUser() {
+ return user; }
...
-}]]></programlisting>
+}
+]]></programlisting>
+ </section>
+
+ <section>
+ <title>Lifecycle methods</title>
+ <para>
+ Session bean and entity bean Seam components support all common EJB3 lifecycle callbacks (<literal>@PostConstruct</literal>, <literal>@PreDestroy</literal>, etc.), but Seam also supports the use of any of these callbacks with JavaBean components. However, since these annotations are not available in a J2EE environment, Seam defines two additional component lifecycle callbacks, equivalent to <literal>@PostConstruct</literal> and <literal>@PreDestroy</literal>.
+ </para>
+ <para>
+ The <literal>@Create</literal> method is called after Seam instantiates a component. 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.
+ </para>
+ <para>
+ In addition, stateful session bean components <emphasis>must</emphasis> define a method with no parameters, annotated <literal>@Remove</literal>. This method is called by Seam when the context ends.
+ </para>
+ <para>
+ Finally, the <literal>@Startup</literal> annotation can 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>
+ </section>
+
+ <section>
+ <title>Conditional installation</title>
+ <para>
+ The <literal>@Install</literal> annotation controls conditional installation of components that are required in some deployment scenarios and not in others. This is useful when you want to:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ mock out an infrastructural component in a test,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ change a component's implementation in certain deployment scenarios, or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ install some components only if their dependencies are available. (This is useful for framework authors.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <literal>@Install</literal> lets you specify <emphasis>precedence</emphasis> and <emphasis>dependencies</emphasis>.
+ </para>
+ <para>
+ The precedence of a component is a number that Seam uses to decide which component to install when there are multiple classes with the same component name in the classpath. Seam will choose the component with the higher precendence. Some predefined precedence values are (in ascending order):
+ </para>
+ <orderedlist>
+ <listitem>
+ <para>
+ <literal>BUILT_IN</literal> — the lowest precedence components are the components built in to Seam.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>FRAMEWORK</literal> — components defined by third-party frameworks may override built-in components, but are overridden by application components.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>APPLICATION</literal> — the default precedence. This is appropriate for most application components.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>DEPLOYMENT</literal> — for application components which are deployment-specific.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>MOCK</literal> — for mock objects used in testing.
+ </para>
+ </listitem>
+ </orderedlist>
+ <para>
+ Suppose we have a component named <literal>messageSender</literal> that talks to a JMS queue.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("messageSender")
+public class MessageSender {
- </sect1>
+ public void sendMessage() {
+ //do something with JMS
+ }
+}
+ ]]></programlisting>
+ <para>
+ In our unit tests, there is no available JMS queue, so we would like to stub out this method. We'll create a <emphasis>mock</emphasis> component that exists in the classpath when unit tests are running, but is never deployed with the application:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("messageSender")
+ at Install(precedence=MOCK)
+public class MockMessageSender extends MessageSender {
+ public void sendMessage() {
+ //do nothing!
+ }
+}
+]]></programlisting>
+ <para>
+ The <literal>precedence</literal> helps Seam decide which version to use when it finds both components in the classpath.
+ </para>
+ <para>
+ If we are able to control precisely which classes are in the classpath, this works well. But if we are writing a reuseable framework with many dependencies, we do not want to have to break that framework across multiple <filename>jar</filename>s. We want to be able to decide which components to install based on other installed components, and classes available in the classpath. The <literal>@Install</literal> annotation also controls this functionality. Seam uses this mechanism internally to enable the conditional installation of many built-in components.
+ </para>
+ </section>
+
+ <section>
+ <title>Logging</title>
+ <para>
+ Before Seam, even the simplest log message required verbose code:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[private static final Log log = LogFactory.getLog(CreateOrderAction.class);
+
+public Order createOrder(User user, Product product, int quantity) {
+ if ( log.isDebugEnabled() ) {
+ log.debug("Creating new order for user: " + user.username() +
+ " product: " + product.name() + " quantity: " + quantity);
+ }
+ return new Order(user, product, quantity);
+}
+]]></programlisting>
+ <para>
+ Seam provides a logging API that simplifies this code significantly:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Logger private Log log;
- <sect1>
- <title>Lifecycle methods</title>
-
- <para>
- Session bean and entity bean Seam components support all the usual EJB 3.0 lifecycle callback
- (<literal>@PostConstruct</literal>, <literal>@PreDestroy</literal>, etc). But Seam also supports
- the use of any of these callbacks with JavaBean components. However, since these annotations are
- not available in a J2EE environment, Seam defines two additional component lifecycle callbacks,
- equivalent to <literal>@PostConstruct</literal> and <literal>@PreDestroy</literal>.
- </para>
-
- <para>
- The <literal>@Create</literal> method is called after Seam instantiates a component.
- 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.
- </para>
-
- <para>
- In addition, stateful session bean components <emphasis>must</emphasis> define a method with no parameters
- annotated <literal>@Remove</literal>. This method is called by Seam when the context ends.
- </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>Conditional installation</title>
-
- <para>
- The <literal>@Install</literal> annotation lets you control conditional installation of components that
- are required in some deployment scenarios and not in others. This is useful if:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- You want to mock out some infrastructural component in tests.
- </para>
- </listitem>
- <listitem>
- <para>
- You want change the implementation of a component in certain
- deployment scenarios.
- </para>
- </listitem>
- <listitem>
- <para>
- You want to install some components only if their dependencies are
- available (useful for framework authors).
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <literal>@Install</literal> works by letting you specify <emphasis>precedence</emphasis>
- and <emphasis>dependencies</emphasis>.
- </para>
-
- <para>
- The precedence of a component is a number that Seam uses to decide which component to
- install when there are multiple classes with the same component name in the classpath.
- Seam will choose the component with the higher precendence. There are some predefined
- precedence values (in ascending order):
- </para>
-
- <orderedlist>
- <listitem>
- <para>
- <literal>BUILT_IN</literal> — the lowest precedece components are
- the components built in to Seam.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>FRAMEWORK</literal> — components defined by third-party
- frameworks may override built-in components, but are overridden by
- application components.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>APPLICATION</literal> — the default precedence. This is
- appropriate for most application components.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>DEPLOYMENT</literal> — for application components which
- are deployment-specific.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>MOCK</literal> — for mock objects used in testing.
- </para>
- </listitem>
- </orderedlist>
-
- <para>
- Suppose we have a component named <literal>messageSender</literal> that talks to
- a JMS queue.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("messageSender")
-public class MessageSender {
- public void sendMessage() {
- //do something with JMS
- }
-}]]></programlisting>
-
- <para>
- In our unit tests, we don't have a JMS queue available, so we would like to stub
- out this method. We'll create a <emphasis>mock</emphasis> component that exists
- in the classpath when unit tests are running, but is never deployed with the
- application:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("messageSender")
- at Install(precedence=MOCK)
-public class MockMessageSender extends MessageSender {
- public void sendMessage() {
- //do nothing!
- }
-}]]></programlisting>
+public Order createOrder(User user, Product product, int quantity) {
+ log.debug("Creating new order for user: #0 product: #1 quantity: #2",
+ user.username(), product.name(), quantity);
+
+ return new Order(user, product, quantity);
+}
- <para>
- The <literal>precedence</literal> helps Seam decide which version to use when it finds
- both components in the classpath.
- </para>
-
- <para>
- This is nice if we are able to control exactly which classes are in the classpath. But
- if I'm writing a reusable framework with many dependecies, I don't want to have to
- break that framework across many jars. I want to be able to decide which components
- to install depending upon what other components are installed, and upon what classes
- are available in the classpath. The <literal>@Install</literal> annotation also
- controls this functionality. Seam uses this mechanism internally to enable conditional
- installation of many of the built-in components. However, you probably won't need to
- use it in your application.
- </para>
-
- </sect1>
-
- <sect1>
- <title>Logging</title>
-
- <para>
- Who is not totally fed up with seeing noisy code like this?
- </para>
-
- <programlisting role="JAVA"><![CDATA[private static final Log log = LogFactory.getLog(CreateOrderAction.class);
-
-public Order createOrder(User user, Product product, int quantity) {
- if ( log.isDebugEnabled() ) {
- log.debug("Creating new order for user: " + user.username() +
- " product: " + product.name()
- + " quantity: " + quantity);
- }
- 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>
- Seam provides a logging API that simplifies this code significantly:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Logger private Log log;
-
-public Order createOrder(User user, Product product, int quantity) {
- log.debug("Creating new order for user: #0 product: #1 quantity: #2", user.username(), product.name(), quantity);
- return new Order(user, product, quantity);
-}]]></programlisting>
-
- <para>
- It doesn't matter if you declare the <literal>log</literal> variable static or not — it will work
- either way, except for entity bean components which require the <literal>log</literal> variable to be
- static.
- </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>
-
- <!-- Lets not document this now, cos we should migrate to use the printf format
- <para>
- You can use <literal>java.text.MessageFormat</literal> formatted strings:
- </para>
-
- <programlisting role="JAVA"><![CDATA[log.debug("The time is {0,time}", new Date());]]></programlisting>
- -->
-
- <para>
- If <literal>User</literal> and <literal>Product</literal> are Seam components available in the current
- contexts, it gets even better:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Logger private Log log;
-
-public Order createOrder(User user, Product product, int quantity) {
- log.debug("Creating new order for user: #{user.username} product: #{product.name} quantity: #0", quantity);
- return new Order(user, product, quantity);
-}]]></programlisting>
-
- <para>
- Seam logging automagically chooses whether to send output to log4j or JDK logging. If log4j is in the
- classpath, Seam with use it. If it is not, Seam will use JDK logging.
- </para>
-
- </sect1>
-
- <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 is 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 role="JAVA"><![CDATA[@Name("account")
-public class Account extends AbstractMutable
-{
- private BigDecimal balance;
-
- public void setBalance(BigDecimal balance)
- {
- setDirty(this.balance, balance);
- this.balance = balance;
- }
-
- public BigDecimal getBalance()
- {
- return balance;
- }
-
- ...
-
-}]]></programlisting>
-
- <para>
- Or, you can use the <literal>@ReadOnly</literal> annotation to achieve a similar effect:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("account")
-public class Account
-{
- private BigDecimal balance;
-
- public void setBalance(BigDecimal balance)
- {
- this.balance = balance;
- }
-
- @ReadOnly
- public BigDecimal getBalance()
- {
- return balance;
- }
-
- ...
-
-}]]></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, <emphasis>unless the (conversation-scoped)
- entity is currently associated with a Seam-managed persistence context, in which case no replication is
- needed</emphasis>. This strategy is not necessarily 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 role="JAVA"><![CDATA[@Stateful
- at Name("account")
-public class AccountManager extends AbstractMutable
-{
- private Account account; // an entity bean
-
- @Unwrap
- public Account getAccount()
- {
- return account;
- }
-
- ...
-
-}]]></programlisting>
-
- <para>
- Note that the <literal>EntityHome</literal> class in the Seam Application Framework provides a great example
- of managing an entity bean instance using a Seam component.
- </para>
-
- </sect1>
-
- <sect1>
- <title>Factory and manager components</title>
- <para>
- We often need to work with objects that are not Seam components. But we still want to be able to inject
- them into our components using <literal>@In</literal> and use them in value and method binding expressions,
- etc. Sometimes, we even need to tie them into the Seam context lifecycle (<literal>@Destroy</literal>, for
- example). So the Seam contexts can contain objects which are not Seam components, and Seam provides a couple
- of nice features that make it easier to work with non-component objects bound to contexts.
- </para>
-
- <para>
- The <emphasis>factory component pattern</emphasis> lets a Seam component act as the instantiator for a
- non-component object. A <emphasis>factory method</emphasis> will be called when a context variable is
- referenced but has no value bound to it. We define factory methods using the <literal>@Factory</literal>
- annotation. The factory method binds a value to the context variable, and determines the scope of the bound
- value. There are two styles of factory method. The first style returns a value, which is bound to the
- context by Seam:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Factory(scope=CONVERSATION)
+]]></programlisting>
+ <para>
+ Except for entity bean components (which require the <literal>log</literal> variable to be static), this will work regardless of whether the <literal>log</literal> variable is declared static.
+ </para>
+ <para>
+ String concatenation occurs inside the <literal>debug()</literal> method, so the verbose <literal>if ( log.isDebugEnabled() )</literal> guard is unnecessary. Usually, we would not even need to explicitly specify the log category, since Seam knows where it is injecting the <literal>log</literal>.
+ </para>
+ <!-- #modify: Any progress here?
+ Lets not document this now, cos we should migrate to use the printf format <para> You can use <literal>java.text.MessageFormat</literal> formatted strings: </para> <programlisting role="JAVA"><![CDATA[log.debug("The time is {0,time}", new Date());]]></programlisting> --> <para>
+ If <literal>User</literal> and <literal>Product</literal> are Seam components available in the current contexts, the code is even more concise:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Logger private Log log;
+public Order createOrder(User user, Product product, int quantity) {
+ log.debug("Creating new order for user: #{user.username}
+ product: #{product.name} quantity: #0", quantity);
+ return new Order(user, product, quantity);
+}
+]]></programlisting>
+ <para>
+ Seam logging automatically chooses whether to send output to log4j or JDK logging — if log4j is in the classpath, it will be used; if not, Seam uses JDK logging.
+ </para>
+ </section>
+
+ <section>
+ <title>The <literal>Mutable</literal> interface and <literal>@ReadOnly</literal></title>
+ <para>
+ Many application servers feature <literal>HttpSession</literal> clustering where changes to the state of mutable objects bound to the session are replicated only when <literal>setAttribute</literal> is called explicitly. This can lead to bugs that manifest only upon failover, which cannot be effectively tested during development. Further, the replication messages themselves are inefficient, since they contain the entire serialized object graph, bound to the session attribute.
+ </para>
+ <para>
+ EJB stateful session beans must perform automatic dirty checking (that is, they must automatically detect object state changes to synchronize updated states with the database) and replicate mutable state. A sophisticated EJB container can introduce optimizations such as attribute-level replication. Unfortunately, not all Seam users will be working in an environment that supports EJB3. Therefore, Seam provides an extra layer of cluster-safe state management for session- and conversation-scoped JavaBean and entity bean components.
+ </para>
+ <para>
+ For session- or conversation-scoped JavaBean components, Seam automatically forces replication by calling <literal>setAttribute()</literal> once in every request where the component was invoked by the application. However, this strategy is inefficient for read-mostly components. 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 role="JAVA"><![CDATA[@Name("account")
+public class Account extends AbstractMutable {
+ private BigDecimal balance;
+ public void setBalance(BigDecimal balance) {
+ setDirty(this.balance, balance);
+ this.balance = balance;
+ }
+
+ public BigDecimal getBalance() {
+ return balance;
+ }
+ ...
+}
+]]></programlisting>
+ <para>
+ Or, you can use the <literal>@ReadOnly</literal> annotation to achieve a similar effect:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("account")
+public class Account {
+ private BigDecimal balance;
+ public void setBalance(BigDecimal balance) {
+ this.balance = balance;
+ }
+
+ @ReadOnly
+ public BigDecimal getBalance() {
+ return balance;
+ }
+ ...
+}
+]]></programlisting>
+ <para>
+ For session- or conversation-scoped entity bean components, Seam automatically forces replication by calling <literal>setAttribute()</literal> once in every request, unless the (conversation-scoped) entity is currently associated with a Seam-managed persistence context, in which case replication is unnecessary. This strategy is not necessarily 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 role="JAVA"><![CDATA[@Stateful @Name("account")
+public class AccountManager extends AbstractMutable {
+ private Account account; // an entity bean
+ @Unwrap
+ public Account getAccount() {
+ return account;
+ }
+ ...
+}
+]]></programlisting>
+ <para>
+ Note that the <literal>EntityHome</literal> class in the Seam Application Framework is an excellent example of managing an entity bean instance using a Seam component.
+ </para>
+ </section>
+
+ <section>
+ <title>Factory and manager components</title>
+ <para>
+ It is often necessary to work with objects that are not Seam components, but we still prefer to be able to inject them into our components with <literal>@In</literal>, use them in value- and method-binding expressions, and tie them into the Seam context lifecycle (<literal>@Destroy</literal>, for example). Therefore, Seam contexts can hold objects that are not Seam components, and Seam provides several features that simplify working 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. Factory methods are defined with 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 role="JAVA"><![CDATA[@Factory(scope=CONVERSATION)
public List<Customer> getCustomerList() {
- return ... ;
-} ]]></programlisting>
-
- <para>
- The second style is a method of type <literal>void</literal> which binds the value to the context
- variable itself:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@DataModel List<Customer> customerList;
-
- at Factory("customerList")
+ return ... ;
+}
+]]></programlisting>
+ <para>
+ The second style is a method of type <literal>void</literal>, which binds the value to the context variable itself:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@DataModel List<Customer> customerList;
+ at Factory("customerList")
public void initCustomerList() {
- customerList = ... ;
-} ]]></programlisting>
-
- <para>
- In both cases, the factory method is called when we reference the <literal>customerList</literal> context
- variable and its value is null, and then has no further part to play in the lifecycle of the value. An even
- more powerful pattern is the <emphasis>manager component pattern</emphasis>. In this case, we have a Seam
- component that is bound to a context variable, that manages the value of the context variable, while
- remaining invisible to clients.
- </para>
-
- <para>
- A manager component is any component with an <literal>@Unwrap</literal> method. This method returns the
- value that will be visable to clients, and is called <emphasis>every time</emphasis> a context variable is
- referenced.
- </para>
-
-
-
- <programlisting role="JAVA"><![CDATA[@Name("customerList")
- at Scope(CONVERSATION)
-public class CustomerListManager
-{
- ...
-
- @Unwrap
- public List<Customer> getCustomerList() {
- return ... ;
- }
+ customerList = ... ;
+}
+]]></programlisting>
+ <para>
+ In either case, the factory method is called when the <literal>customerList</literal> context variable is referenced, and its value is null. The factory method then has no further part in the lifecycle of the value. The <emphasis>manager component pattern</emphasis> is an even more powerful pattern. In this case, a Seam component bound to a context variable 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 visible to clients, and is called every time a context variable is referenced.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("customerList")
+ at Scope(CONVERSATION)
+public class CustomerListManager {
+ ...
+ @Unwrap
+ public List<Customer> getCustomerList() {
+ return ... ;
+ }
+}
+]]></programlisting>
+ <para>
+ The manager component pattern is especially useful where more control is required over component lifecycle. For example, if you have a heavyweight object that needs a cleanup operation when the context ends, you could <literal>@Unwrap</literal> the object, and perform cleanup in the <literal>@Destroy</literal> method of the manager component.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("hens")
+ at Scope(APPLICATION)
+public class HenHouse {
+ Set<Hen> hens;
+
+ @In(required=false) Hen hen;
+
+ @Unwrap
+ public List<Hen> getHens()
+ {
+ if (hens == null) {
+ // Setup our hens }
+ return hens;
+ }
+
+ @Observer({"chickBorn", "chickenBoughtAtMarket"})
+ public addHen() {
+ hens.add(hen);
+ }
+
+ @Observer("chickenSoldAtMarket")
+ public removeHen() {
+ hens.remove(hen);
+ }
+
+ @Observer("foxGetsIn")
+ public removeAllHens() {
+ hens.clear();
+ }
+
+ ...
+
}]]></programlisting>
-
- <para>
- The manager component pattern is especially useful if we have an object where you need more control over the
- lifecycle of the component. For example, if you have a heavyweight object that needs a cleanup operation when
- the context ends you could <literal>@Unwrap</literal> the object, and perform cleanup in the
- <literal>@Destroy</literal> method of the manager component.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("hens")
- at Scope(APPLICATION)
-public class HenHouse
-{
- Set<Hen> hens;
-
- @In(required=false) Hen hen;
-
- @Unwrap
- public List<Hen> getHens()
- {
- if (hens == null)
- {
- // Setup our hens
- }
- return hens;
- }
-
- @Observer({"chickBorn", "chickenBoughtAtMarket"})
- public addHen()
- {
- hens.add(hen);
- }
-
- @Observer("chickenSoldAtMarket")
- public removeHen()
- {
- hens.remove(hen);
- }
-
- @Observer("foxGetsIn")
- public removeAllHens()
- {
- hens.clear();
- }
- ...
-}]]> </programlisting>
-
- <para>
- Here the managed component observes many events which change the underlying object.
- The component manages these actions itself, and because the object is unwrapped
- on every access, a consistent view is provided.
- </para>
-
- </sect1>
-
+ <para>
+ Here, the managed component observes many events that change the underlying object. The component manages these actions itself, and because the object is unwrapped each time it is accessed, a consistent view is provided.
+ </para>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Configuration.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Configuration.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Configuration.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,675 +1,566 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="configuration">
- <title>Configuring Seam and packaging Seam applications</title>
- <para> Configuration is a very boring topic and an extremely tedious pastime. Unfortunately, several lines of XML
- are required to integrate Seam into your JSF implementation and servlet container. There's no need to be too put
- off by the following sections; you'll never need to type any of this stuff yourself, since you can just use
- seam-gen to start your application or you can copy and paste from the example applications! </para>
-
- <sect1>
- <title>Basic Seam configuration</title>
-
- <para> First, let's look at the basic configuration that is needed whenever we use Seam with JSF. </para>
-
- <sect2>
- <title>Integrating Seam with JSF and your servlet container</title>
-
- <para> Of course, you need a faces servlet! </para>
-
- <programlisting role="XML"><![CDATA[<servlet>
- <servlet-name>Faces Servlet</servlet-name>
- <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
- <load-on-startup>1</load-on-startup>
+<chapter id="configuration" >
+ <title>Configuring Seam and packaging Seam applications</title>
+ <para>
+ Configuration can be complex and tedious, but for the most part you will not need to write configuration data from scratch. Only a few lines of XML are required to integrate Seam with your JavaServer Faces (JSF) implementation and Servlet container, and for the most part you can either use seam-gen to start your application, or simply copy and paste from the example applications provided with Seam.
+ </para>
+ <section>
+ <title>Basic Seam configuration</title>
+ <para>
+ First, the basic configuration required whenever Seam is used with JSF.
+ </para>
+ <section>
+ <title>Integrating Seam with JSF and your servlet container</title>
+ <para>
+ First, define a Faces Servlet.
+ </para>
+
+<programlisting role="XML"><![CDATA[<servlet>
+ <servlet-name>Faces Servlet</servlet-name>
+ <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
+ <load-on-startup>1</load-on-startup>
</servlet>
-
+
<servlet-mapping>
- <servlet-name>Faces Servlet</servlet-name>
- <url-pattern>*.seam</url-pattern>
-</servlet-mapping>]]></programlisting>
-
- <para> (You can adjust the URL pattern to suit your taste.) </para>
-
- <para> In addition, Seam requires the following entry in your <literal>web.xml</literal> file: </para>
-
- <programlisting role="XML"><![CDATA[<listener>
- <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
-</listener>]]></programlisting>
-
- <para> This listener is responsible for bootstrapping Seam, and for destroying session and application
- contexts. </para>
-
- <para> Some JSF implementations have a broken implementation of server-side state saving that interferes
- with Seam's conversation propagation. If you have problems with conversation propagation during form
- submissions, try switching to client-side state saving. You'll need this in <literal>web.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<context-param>
- <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
- <param-value>client</param-value>
-</context-param>]]></programlisting>
-
- <para>
- There is a minor gray area in the JSF specification regarding the mutability of view state values. Since
- Seam uses the JSF view state to back its PAGE scope this can become an issue in some cases. If you're
- using server side state saving with the JSF-RI and you want a PAGE scoped bean to keep its exact value
- for a given view of a page you will need to specify the following context-param. Otherwise if a user
- uses the "back" button a PAGE scoped component will have the latest value if it has changed not the
- value of the "back" page. (see
- <ulink url="https://javaserverfaces-spec-public.dev.java.net/issues/show_bug.cgi?id=295">
- Spec Issue
- </ulink>
- ). This setting is not enabled by default because of the performance hit of serializing the JSF view
- with every request.
- </para>
-
- <programlisting role="XML"><![CDATA[<context-param>
- <param-name>com.sun.faces.serializeServerState</param-name>
- <param-value>true</param-value>
-</context-param>]]></programlisting>
- </sect2>
-
- <sect2>
- <title>Using Facelets</title>
-
- <para> If you want follow our advice and use Facelets instead of JSP, add the following lines to
- <literal>faces-config.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<application>
- <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
-</application>]]></programlisting>
-
- <para> And the following lines to <literal>web.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<context-param>
- <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
- <param-value>.xhtml</param-value>
-</context-param>]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Seam Resource Servlet</title>
-
- <para> The Seam Resource Servlet provides resources used by Seam Remoting, captchas (see the security
- chapter) and some JSF UI controls. Configuring the Seam Resource Servlet requires the following entry in
- <literal>web.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<servlet>
- <servlet-name>Seam Resource Servlet</servlet-name>
- <servlet-class>org.jboss.seam.servlet.SeamResourceServlet</servlet-class>
-</servlet>
-
-<servlet-mapping>
- <servlet-name>Seam Resource Servlet</servlet-name>
- <url-pattern>/seam/resource/*</url-pattern>
-</servlet-mapping>]]></programlisting>
- </sect2>
-
- <sect2>
- <title>Seam servlet filters</title>
-
- <para> Seam doesn't need any servlet filters for basic operation. However, there are several features which
- depend upon the use of filters. To make things easier, Seam lets you add and configure
- servlet filters just like you would configure other built-in Seam components. To take advantage of this
- feature, we must first install a master filter in <literal>web.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<filter>
- <filter-name>Seam Filter</filter-name>
- <filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
-</filter>
-
-<filter-mapping>
- <filter-name>Seam Filter</filter-name>
- <url-pattern>/*</url-pattern>
-</filter-mapping>]]></programlisting>
-
- <para>The Seam master filter <emphasis>must</emphasis> be the first filter specified in
- <literal>web.xml</literal>. This ensures it is run first. </para>
-
- <para>
- The Seam filters share a number of common attributes, you can set these in
- <literal>components.xml</literal> in addition to any parameters discussed
- below:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>url-pattern</literal> — Used to specify which requests are filtered, the
- default is all requests. <literal>url-pattern</literal> is a Tomcat style pattern
- which allows a wildcard suffix.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>regex-url-pattern</literal> — Used to specify which requests are filtered, the
- default is all requests. <literal>regex-url-pattern</literal> is a true regular expression
- match for request path.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>disabled</literal> — Used to disable a built in filter.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Note that the patterns are matched against the URI path of the request (see
- <literal>HttpServletRequest.getURIPath()</literal>) and that the name of the servlet context is
- removed before matching.
- </para>
-
- <para> Adding the master filter enables the following built-in filters. </para>
-
- <sect3>
- <title>Exception handling</title>
- <para> This filter provides the exception mapping functionality in <literal>pages.xml</literal> (almost
- all applications will need this). It also takes care of rolling back uncommitted transactions when
- uncaught exceptions occur. (According to the Java EE specification, the web container should do this
- automatically, but we've found that this behavior cannot be relied upon in all application servers.
- And it is certainly not required of plain servlet engines like Tomcat.) </para>
-
- <para> By default, the exception handling filter will process all requests, however this behavior may be
- adjusted by adding a <literal><web:exception-filter></literal> entry to
- <literal>components.xml</literal>, as shown in this example: </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:web="http://jboss.com/products/seam/web">
-
- <web:exception-filter url-pattern="*.seam"/>
-
-</components>]]></programlisting>
-
-
- </sect3>
-
- <sect3>
- <title>Conversation propagation with redirects</title>
- <para> This filter allows Seam to propagate the conversation context across browser redirects. It
- intercepts any browser redirects and adds a request parameter that specifies the Seam conversation
- identifier. </para>
-
- <para> The redirect filter will process all requests by default, but this behavior can also be adjusted
- in <literal>components.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<web:redirect-filter url-pattern="*.seam"/>]]></programlisting>
- </sect3>
-
-
- <sect3 id="configuration.filters.rewrite">
- <title>URL rewriting</title>
- <para> This filter allows Seam to apply URL rewriting for views based on configuration in the
- <literal>pages.xml</literal> file. This filter is not activate by default, but can be
- activated
- by adding the configuration to <literal>components.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<web:rewrite-filter view-mapping="*.seam"/>]]></programlisting>
-
-
- <para>The <literal>view-mapping</literal> parameter must match the servlet mapping defined for the Faces Servlet
- in the <literal>web.xml</literal> file. If ommitted, the rewrite filter assumes
- the pattern <literal>*.seam</literal>.
- </para>
- </sect3>
-
- <sect3>
- <title>Multipart form submissions</title>
- <para> This feature is necessary when using the Seam file upload JSF control. It detects multipart form
- requests and processes them according to the multipart/form-data specification (RFC-2388). To
- override the default settings, add the following entry to <literal>components.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<web:multipart-filter create-temp-files="true"
- max-request-size="1000000"
- url-pattern="*.seam"/>]]></programlisting>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>create-temp-files</literal> — If set to <literal>true</literal>, uploaded
- files are written to a temporary file (instead of held in memory). This may be an important
- consideration if large file uploads are expected. The default setting is
- <literal>false</literal>. </para>
- </listitem>
- <listitem>
- <para>
- <literal>max-request-size</literal> — If the size of a file upload request
- (determined by reading the <literal>Content-Length</literal> header in the request) exceeds
- this value, the request will be aborted. The default setting is 0 (no size limit). </para>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title>Character encoding</title>
- <para> Sets the character encoding of submitted form data. </para>
-
- <para> This filter is not installed by default and requires an entry in
- <literal>components.xml</literal> to enable it: </para>
-
- <programlisting role="XML"><![CDATA[<web:character-encoding-filter encoding="UTF-16"
- override-client="true"
- url-pattern="*.seam"/>]]></programlisting>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>encoding</literal> — The encoding to use. </para>
- </listitem>
- <listitem>
- <para>
- <literal>override-client</literal> — If this is set to <literal>true</literal>,
- the request encoding will be set to whatever is specified by <literal>encoding</literal> no
- matter whether the request already specifies an encoding or not. If set to
- <literal>false</literal>, the request encoding will only be set if the request doesn't
- already specify an encoding. The default setting is <literal>false</literal>. </para>
- </listitem>
- </itemizedlist>
- </sect3>
-
- <sect3>
- <title>RichFaces</title>
-
- <para>
- If RichFaces is used in your project, Seam will install the
- RichFaces Ajax filter for you, making sure to install it
- before all other built-in filters. You don't need to install
- the RichFaces Ajax filter in <literal>web.xml</literal>
- yourself.
- </para>
-
- <para>
- The RichFaces Ajax filter is only installed if the RichFaces
- jars are present in your project.
- </para>
-
- <para> To override the default settings, add the following entry to <literal>components.xml</literal>.
- The options are the same as those specified in the RichFaces Developer Guide: </para>
-
- <programlisting role="XML"><![CDATA[<web:ajax4jsf-filter force-parser="true"
- enable-cache="true"
- log4j-init-file="custom-log4j.xml"
- url-pattern="*.seam"/>]]></programlisting>
- <itemizedlist>
- <listitem>
- <para>
- <literal>force-parser</literal> — forces all JSF pages to be validated by
- Richfaces's XML syntax checker. If <literal>false</literal>, only AJAX responses are
- validated and converted to well-formed XML. Setting <literal>force-parser</literal> to
- <literal>false</literal> improves performance, but can provide visual artifacts on AJAX
- updates. </para>
- </listitem>
- <listitem>
- <para>
- <literal>enable-cache</literal> — enables caching of framework-generated resources
- (e.g. javascript, CSS, images, etc). When developing custom javascript or CSS, setting to
- true prevents the browser from caching the resource. </para>
- </listitem>
- <listitem>
- <para>
- <literal>log4j-init-file</literal> — is used to setup per-application logging. A
- path, relative to web application context, to the log4j.xml configuration file should be
- provided. </para>
- </listitem>
- </itemizedlist>
-
- </sect3>
-
- <sect3>
- <title>Identity Logging</title>
-
- <para>
- This filter adds the authenticated user name to the log4j mapped diagnostic context so that it
- can be included in formatted log output if desired, by adding %X{username} to the pattern.
- </para>
-
-
- <para> By default, the logging filter will process all requests, however this behavior may be
- adjusted by adding a <literal><web:logging-filter></literal> entry to
- <literal>components.xml</literal>, as shown in this example: </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:web="http://jboss.com/products/seam/web">
- <web:logging-filter url-pattern="*.seam"/>
-</components>]]></programlisting>
-
- </sect3>
-
- <sect3>
- <title>Context management for custom servlets</title>
- <para> Requests sent direct to some servlet other than the JSF servlet are not processed through the JSF
- lifecycle, so Seam provides a servlet filter that can be applied to any other servlet that needs
- access to Seam components. </para>
-
- <para> This filter allows custom servlets to interact with the Seam contexts. It sets up the Seam
- contexts at the beginning of each request, and tears them down at the end of the request. You should
- make sure that this filter is <emphasis>never</emphasis> applied to the JSF
- <literal>FacesServlet</literal>. Seam uses the phase listener for context management in a JSF
- request. </para>
-
- <para> This filter is not installed by default and requires an entry in
- <literal>components.xml</literal> to enable it: </para>
-
- <programlisting role="XML"><![CDATA[<web:context-filter url-pattern="/media/*"/>]]></programlisting>
-
- <para> The context filter expects to find the conversation id of any conversation context in a request
- parameter named <literal>conversationId</literal>. You are responsible for ensuring that it gets
- sent in the request. </para>
-
- <para> You are also responsible for ensuring propagation of any new conversation id back to the client.
- Seam exposes the conversation id as a property of the built in component
- <literal>conversation</literal>. </para>
-
- </sect3>
-
-
- <sect3>
- <title>Adding custom filters</title>
- <para> Seam can install your filters for you, allowing you to specify <emphasis>where</emphasis> in the
- chain your filter is placed (the servlet specification doesn't provide a well defined order if you
- specify your filters in a <literal>web.xml</literal>). Just add the <literal>@Filter</literal>
- annotation to your Seam component (which must implement <literal>javax.servlet.Filter</literal>): </para>
-
- <programlisting role="JAVA"><![CDATA[@Startup
- at Scope(APPLICATION)
- at Name("org.jboss.seam.web.multipartFilter")
- at BypassInterceptors
- at Filter(within="org.jboss.seam.web.ajax4jsfFilter")
-public class MultipartFilter extends AbstractFilter {]]></programlisting>
-
- <para> Adding the <literal>@Startup</literal> annotation means thar the component is available during
- Seam startup; bijection isn't available here (<literal>@BypassInterceptors</literal>); and the filter
- should be further down the chain than the RichFaces filter
- (<literal>@Filter(within="org.jboss.seam.web.ajax4jsfFilter")</literal>). </para>
-
- </sect3>
- </sect2>
-
- <sect2>
- <title>Integrating Seam with your EJB container</title>
-
- <para> In a Seam application, EJB components have a certain duality, as they are managed by both the EJB
- container and Seam. Actually, it's more that Seam resolves EJB component references, manages the
- lifetime of stateful session bean components, and also participates in each method call via
- interceptors. Let's start with the configuration of the Seam interceptor chain.</para>
-
- <para> We need to apply the <literal>SeamInterceptor</literal> to our Seam EJB components. This interceptor
- delegates to a set of built-in server-side interceptors that handle such concerns as bijection,
- conversation demarcation, and business process signals. The simplest way to do this across an entire
- application is to add the following interceptor configuration in <literal>ejb-jar.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<interceptors>
- <interceptor>
- <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
- </interceptor>
-</interceptors>
-
-<assembly-descriptor>
- <interceptor-binding>
- <ejb-name>*</ejb-name>
- <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
- </interceptor-binding>
-</assembly-descriptor>
+ <servlet-name>Faces Servlet</servlet-name>
+ <url-pattern>*.seam</url-pattern>
+</servlet-mapping>
]]></programlisting>
-
- <para> Seam needs to know where to go to find session beans in JNDI. One way to do this is specify the
- <literal>@JndiName</literal> annotation on every session bean Seam component. However, this is quite
- tedious. A better approach is to specify a pattern that Seam can use to calculate the JNDI name from the
- EJB name. Unfortunately, there is no standard mapping to global JNDI defined in the EJB3 specification,
- so this mapping is vendor-specific (and may depend on your own naming conventions as well). We usually
- specify this option in <literal>components.xml</literal>. </para>
-
- <para> For JBoss AS, the following pattern is correct: </para>
-
- <programlisting role="XML"><![CDATA[<core:init jndi-name="earName/#{ejbName}/local" />]]></programlisting>
-
- <para> In this case, <literal>earName</literal> is the name of the EAR in which the bean is deployed, Seam
- replaces <literal>#{ejbName}</literal> with the name of the EJB, and the final segment represents the
- type of interface (local or remote). </para>
-
- <para> Outside the context of an EAR (when using the JBoss Embeddable EJB3 container), the first segment is
- dropped since there is no EAR, leaving us with the following pattern: </para>
-
- <programlisting role="XML"><![CDATA[<core:init jndi-name="#{ejbName}/local" />]]></programlisting>
-
- <para> How these JNDI names are resolved and somehow locate an EJB component might appear a bit like black
- magic at this point, so let's dig into the details. First, let's talk about how the EJB components get
- into JNDI.</para>
-
- <para> The folks at JBoss don't care much for XML, if you can't tell. So when they designed JBoss AS, they
- decided that EJB components would get assigned a global JNDI name automatically, using the pattern
- just described (i.e., EAR name/EJB name/interface type). The EJB name is the first non-empty value
- from the following list: </para>
- <itemizedlist>
- <listitem>
- <para>The value of the <literal><ejb-name></literal> element in ejb-jar.xml</para>
- </listitem>
- <listitem>
- <para>The value of the <literal>name</literal> attribute in the @Stateless or @Stateful annotation</para>
- </listitem>
- <listitem>
- <para>The simple name of the bean class</para>
- </listitem>
- </itemizedlist>
-
- <para> Let's look at an example. Assume that you have the following EJB bean and interface defined. </para>
-
- <programlisting role="JAVA"><![CDATA[package com.example.myapp;
-
-import javax.ejb.Local;
-
- at Local
-public class Authenticator
-{
- boolean authenticate();
-}
-
-package com.example.myapp;
-
-import javax.ejb.Stateless;
-
- at Stateless
- at Name("authenticator")
-public class AuthenticatorBean implements Authenticator
-{
- public boolean authenticate() { ... }
-}
+
+ <para>
+ (You can adjust the URL pattern as you like.)
+ </para>
+ <para>
+ Seam also requires the following entry in your <filename>web.xml</filename> file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<listener>
+ <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
+</listener>
]]></programlisting>
-
- <para> Assuming your EJB bean class is deployed in an EAR named myapp, the global JNDI name
- myapp/AuthenticatorBean/local will be assigned to it on JBoss AS. As you learned, you can reference this
- EJB component as a Seam component with the name <literal>authenticator</literal> and Seam will take care
- of finding it in JNDI according to the JNDI pattern (or <literal>@JndiName</literal> annotation).
- </para>
-
- <para>So what about the rest of the application servers? Well, according to the Java EE spec, which most
- vendors try to adhere to religiously, you have to declare an EJB reference for your EJB in order for it
- to be assigned a JNDI name. That requires some XML. It also means that it is up to you to establish a
- JNDI naming convention so that you can leverage the Seam JNDI pattern. You might find the JBoss
- convention a good one to follow.</para>
-
- <para>There are two places you have to define the EJB reference when using Seam on non-JBoss application
- servers. If you are going to be looking up the Seam EJB component through JSF (in a JSF view or as a JSF
- action listener) or a Seam JavaBean component, then you must declare the EJB reference in web.xml. Here
- is the EJB reference for the example component just shown: </para>
-
- <programlisting role="XML"><![CDATA[<ejb-local-ref>
- <ejb-ref-name>myapp/AuthenticatorBean/local</ejb-ref-name>
- <ejb-ref-type>Session</ejb-ref-type>
- <local>org.example.vehicles.action.Authenticator</local>
-</ejb-local-ref>
+ <para>
+ This listener is responsible for bootstrapping Seam, and for destroying session and application contexts.
+ </para>
+ <para>
+ Some JSF implementations do not implement server-side state saving correctly, which interferes with Seam's conversation propagation. If you have problems with conversation propagation during form submissions, try switching to client-side state saving. To do so, add the following to <filename>web.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<context-param>
+ <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
+ <param-value>client</param-value>
+</context-param>
]]></programlisting>
+ <para>
+ The JSF specification is unclear about the mutability of view state values. Since Seam uses the JSF view state to back its <literal>PAGE</literal> scope, this can be problematic. If you use server-side state saving with the JSF-RI (JSF Reference Implementation), and you want a page-scoped bean to retain its exact value for a given page view, you must specify the context parameter as follows:
+ </para>
+
+<programlisting role="XML"><![CDATA[<context-param>
+ <param-name>com.sun.faces.serializeServerState</param-name>
+ <param-value>true</param-value>
+</context-param>
+]]></programlisting>
+ <para>
+ If this is not specified, a page-scoped component will contain the latest value of the page, and not the value of the "back" page, when the "back" button is used. (See <ulink url="https://javaserverfaces-spec-public.dev.java.net/issues/show_bug.cgi? id=295">this specification issue</ulink> for details.) This setting is not enabled by default because serializing the JSF view with every request lowers overall performance.
+ </para>
+ </section>
+
+ <section>
+ <title>Using Facelets</title>
+ <para>
+ To use the recommended Facelets over JavaServer Pages (JSP), add the following lines to <filename>faces-config.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<application>
+ <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
+</application>]]>
+</programlisting>
+ <para>
+ Then, add the following lines to <filename>web.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<context-param>
+ <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
+ <param-value>.xhtml</param-value>
+</context-param>
+]]></programlisting>
+<!--
+ <para>
+ Facelets logging does not work natively in JBoss AS — log messages do not reach the server log. Seam provides a bridge to fix this. Copy <literal>lib/interop/jboss-seam-jul.jar</literal> to <literal>$JBOSS_HOME/server/default/deploy/jboss-web.deployer/jsf-libs/</literal>, and include the <literal>jboss-seam-ui.jar</literal> in the <literal>WEB-INF/lib</literal> of your application. The Facelets logging catagories are itemized in the <ulink url="https://facelets.dev.java.net/nonav/docs/dev/docbook.html#config- logging">Facelets Developer Documentation</ulink>.
+ </para>
+ -->
+ </section>
+
+ <section>
+ <title>Seam Resource Servlet</title>
+ <para>
+ The Seam Resource Servlet provides resources used by Seam Remoting, CAPTCHAs (see the Security chapter) and some JSF UI controls. Configuring the Seam Resource Servlet requires the following entry in <filename>web.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<servlet>
+ <servlet-name>Seam Resource Servlet</servlet-name>
+ <servlet-class>
+ org.jboss.seam.servlet.SeamResourceServlet
+ </servlet-class>
+</servlet>
+<servlet-mapping>
+ <servlet-name>Seam Resource Servlet</servlet-name>
+ <url-pattern>/seam/resource/*</url-pattern>
+</servlet-mapping>
+]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Seam Servlet filters</title>
+ <para>
+ Seam does not require Servlet filters for basic operation, but there are several features that depend upon filter use. Seam lets you add and configure Servlet filters as you would configure other built-in Seam components. To use this configuration method, you must first install a master filter in <filename>web.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<filter>
+ <filter-name>Seam Filter</filter-name>
+ <filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
+</filter>
+<filter-mapping>
+ <filter-name>Seam Filter</filter-name>
+ <url-pattern>/*</url-pattern>
+</filter-mapping>
+]]></programlisting>
+ <para>
+ To ensure that it is run first, the Seam master filter <emphasis>must</emphasis> be the first filter specified in <filename>web.xml</filename>.
+ </para>
+ <para>
+ The Seam filters share a number of common attributes, which can be set in <filename>components.xml</filename>, along with any parameters discussed below:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>url-pattern</literal> — Specifies which requests are filtered. The default is all requests. <literal>url-pattern</literal> is a pattern which allows a wildcard suffix.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>regex-url-pattern</literal> — Specifies which requests are filtered. The default is all requests. <literal>regex-url-pattern</literal> is a true regular expression match for request path.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disabled</literal> — Disables a built in filter.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ These patterns are matched against the URI path of the request (see <literal>HttpServletRequest.getURIPath()</literal>), and the name of the Servlet context is removed before matching occurs.
+ </para>
+ <para>
+ Adding the master filter enables the following built-in filters:
+ </para>
+ <section>
+ <title>Exception handling</title>
+ <para>
+ This filter is required by most applications, and provides the exception mapping functionality in <filename>pages.xml</filename>. It also rolls back uncommitted transactions when uncaught exceptions occur. (The web container should do this automatically, but this does not occur reliably in some application servers.)
+ </para>
+ <para>
+ By default, the exception handling filter will process all requests, but you can adjust this behavior by adding a <literal><![CDATA[<web:exception-filter>]]></literal> entry to <filename>components.xml</filename>, like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:web="http://jboss.com/products/seam/web">
+ <web:exception-filter url-pattern="*.seam"/>
+</components>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Conversation propagation with redirects</title>
+ <para>
+ This filter allows Seam to propagate the conversation context across browser redirects. It intercepts any browser redirects and adds a request parameter that specifies the Seam conversation identifier.
+ </para>
+ <para>
+ The redirect filter processes all requests by default, but this behavior can also be adjusted in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<web:redirect-filter url-pattern="*.seam"/>]]>
+</programlisting>
+ </section>
+
+ <section id="configuration.filters.rewrite">
+ <title>URL rewriting</title>
+ <para>
+ This filter lets Seam apply URL rewriting for views, depending on its configuration in <filename>pages.xml</filename>. This filter is not active by default, but can be activated by adding the following configuration to <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<web:rewrite-filter view-mapping="*.seam"/>]]>
+</programlisting>
+ <para>
+ The <literal>view-mapping</literal> parameter must match the Servlet mapping defined for the Faces Servlet in the <filename>web.xml</filename> file. If omitted, the rewrite filter assumes the pattern <literal>*.seam</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Multipart form submissions</title>
+ <para>
+ This feature is required when you use the Seam <emphasis>file upload</emphasis> JSF control. It detects multipart form requests and processes them according the the multipart/form-data specification (RFC-2388). Add the following to <filename>components.xml</filename> to override settings:
+ </para>
+
+<programlisting role="XML"><![CDATA[<web:multipart-filter create-temp-files="true"
+ max-request-size="1000000" url-pattern="*.seam"/>
+ ]]></programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>create-temp-files</literal> — If <literal>true</literal>, uploaded files are written to a temporary file, rather than being held in memory. This can be important if you expect large file uploads. By default, this is set to <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>max-request-size</literal> — If the size of a file upload request exceeds this value, the request will be aborted. The default setting is <literal>0</literal> (no size limit). (The size of a file upload is determined by reading the <literal>Content-Length</literal> header in the request.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Character encoding</title>
+ <para>
+ This filter sets the character encoding of submitted form data. It is not installed by default, and requires an entry in <filename>components.xml</filename> to enable it:
+ </para>
+
+<programlisting role="XML"><![CDATA[<web:character-encoding-filter encoding="UTF-16"
+ override-client="true" url-pattern="*.seam"/>]]>
+</programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>encoding</literal> — The type of encoding to use.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>override-client</literal> — If set to <literal>true</literal>, the request encoding will be set to that specified by <literal>encoding</literal>, regardless of whether the request specifies a particular encoding. If set to <literal>false</literal>, the request encoding will only be set if the client has not already specified the request encoding. By default, this is set to <literal>false</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>RichFaces</title>
+ <para>
+ If RichFaces is used in your project, Seam automatically installs the RichFaces AJAX filter before all other built-in filters, so there is no need to add it to <filename>web.xml</filename> manually.
+ </para>
+ <para>
+ The RichFaces Ajax filter is installed only if the RichFaces <filename>JAR</filename>s are present in your project.
+ </para>
+ <para>
+ To override the default settings, add the following entry to <filename>components.xml</filename>. The options are the same as those specified in the RichFaces Developer Guide:
+ </para>
+
+<programlisting role="XML"><![CDATA[<web:ajax4jsf-filter force-parser="true" enable-cache="true"
+ log4j-init-file="custom-log4j.xml" url-pattern="*.seam"/>
+]]></programlisting>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>force-parser</literal> — forces all JSF pages to be validated by RichFaces's XML syntax checker. If <literal>false</literal>, only AJAX responses are validated and converted to well-formed XML. Setting <literal>force-parser</literal> to <literal>false</literal> improves performance, but can provide visual artifacts on AJAX updates.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>enable-cache</literal> — enables caching of framework-generated resources, such as JavaScript, CSS, images, etc. When developing custom JavaScript or CSS, setting this to <literal>true</literal> prevents the browser from caching the resource.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>log4j-init-file</literal> — is used to set up per-application logging. A path, relative to web application context, to the <filename>log4j.xml</filename> configuration file should be provided.<!-- #modify: does the user have to provide a path, or is there a path already provided? clarify plz -->
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Identity Logging</title>
+ <para>
+ This filter adds the authenticated username to the <literal>log4j</literal> mapped diagnostic context, so that it can be included in formatted log output by adding <literal>%X{username}</literal> to the pattern.
+ </para>
+ <para>
+ By default, the logging filter processes all requests. You can adjust this behavior by adding a <literal><![CDATA[<web:logging-filter>]]></literal> entry to <filename>components.xml</filename>, like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:web="http://jboss.com/products/seam/web">
+ <web:logging-filter url-pattern="*.seam"/>
+</components>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title>Context management for custom servlets</title>
+ <para>
+ Requests that are sent directly to Servlets other than the JSF Servlet are not processed in the JSF lifecycle, so Seam provides a Servlet filter that can be applied to any other Servlet requiring access to Seam components.
+ </para>
+ <para>
+ This filter lets custom Servlets interact with Seam contexts. It sets up Seam contexts at the beginning of each request, and removes them at the end of the request. This filter should <emphasis>never</emphasis> be applied to the JSF <literal>FacesServlet</literal> — Seam uses the phase listener to manage context in a JSF request.
+ </para>
+ <para>
+ This filter is not installed by default, and must be enabled in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<web:context-filter url-pattern="/media/*"/>
+]]></programlisting>
+ <para>
+ The context filter expects the conversation ID of any conversation context to be defined in the <literal>conversationId</literal> request parameter. You are responsible for ensuring that this is included in the request.
+ </para>
+ <para>
+ You are also responsible for ensuring that any new conversation ID propagates back to the client. Seam exposes the conversation ID as a property of the built in component <literal>conversation</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Adding custom filters</title>
+ <para>
+ Seam can install your filters for you. This allows you to specify your filter's placement in the chain — the Servlet specification does not provide a well-defined order when you specify your filters in <filename>web.xml</filename>. Add a <literal>@Filter</literal> annotation to your Seam component. (Your Seam component must implement <literal>javax.servlet.Filter</literal>.)
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Startup
+ at Scope(APPLICATION)
+ at Name("org.jboss.seam.web.multipartFilter")
+ at BypassInterceptors
+ at Filter(within="org.jboss.seam.web.ajax4jsfFilter")
+public class MultipartFilter extends AbstractFilter {...}
+]]></programlisting>
+ <para>
+ Adding the <literal>@Startup</literal> annotation makes the component available during Seam startup. Bijection is not available here (<literal>@BypassInterceptors</literal>), and the filter should be further down the chain than the RichFaces filter (<literal>@Filter(within="org.jboss.seam.web.ajax4jsfFilter")</literal>).
+ </para>
+ <!-- #modify: this could use further explanation. -->
+ </section>
+
+ </section>
+
+ <section>
+ <title>Integrating Seam with your EJB container</title>
+ <para>
+ EJB components in a Seam application are managed by both Seam and the EJB container. Seam resolves EJB component references, manages the lifetime of stateful session bean components, and participates in each method call via interceptors. To integrate Seam with your EJB container, you must first configure the interceptor chain.
+ </para>
+ <para>
+ Apply the <literal>SeamInterceptor</literal> to your Seam EJB components. This interceptor delegates to a set of built-in server-side interceptors that handle operations like bijection, conversation demarcation, and business process signals. The simplest way to do this across an entire application is to add the following interceptor configuration in <filename>ejb-jar.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<interceptors>
+ <interceptor>
+ <interceptor-class>
+ org.jboss.seam.ejb.SeamInterceptor
+ </interceptor-class>
+ </interceptor>
+</interceptors>
+<assembly-descriptor>
+ <interceptor-binding>
+ <ejb-name>*</ejb-name>
+ <interceptor-class>
+ org.jboss.seam.ejb.SeamInterceptor
+ </interceptor-class>
+ </interceptor-binding>
+</assembly-descriptor>
+]]></programlisting>
+ <para>
+ You must tell seam where to find session beans in JNDI. You could do this by specifying a <literal>@JndiName</literal> annotation on every session bean Seam component. A better approach is to specify a pattern with which Seam can calculate the JNDI name from the EJB name. However, the EJB3 specification does not define a standard method of mapping to global JNDI — this mapping is vendor-specific, and can also depend upon your naming conventions. We specify this option in <filename>components.xml</filename>:
+ </para>
+ <para>
+ For JBoss AS, the following pattern is correct:
+ </para>
+
+<programlisting role="XML"><![CDATA[<core:init jndi-name="earName/#{ejbName}/local" />
+]]></programlisting>
+ <para>
+ Here, <literal>earName</literal> is the name of the EAR in which the bean is deployed. Seam replaces <literal>#{ejbName}</literal> with the name of the EJB, and the final segment represents the type of interface (local or remote).
+ </para>
+ <para>
+ When outside the <filename>EAR</filename> context (for example, when using the JBoss Embeddable EJB3 container), the first segment is dropped, since there is no <filename>EAR</filename>, which leaves us with the following pattern:
+ </para>
+
+<programlisting role="XML"><![CDATA[<core:init jndi-name="#{ejbName}/local" />]]>
+</programlisting>
+ <para>
+ This process looks complicated, but in reality comprises few steps.
+ </para>
+ <para>
+ First, we will talk about how the EJB component is transferred to JNDI. To avoid using XML, JBoss AS uses the aforementioned pattern (that is, <filename>EAR</filename> name/EJB name/interface type) to automatically assign an EJB component a global JNDI name. The EJB name will be the first non-empty value out of the following:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ the <literal><![CDATA[<ejb-name>]]></literal> element in <filename>ejb-jar.xml</filename>,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the <literal>name</literal> attribute in the <literal>@Stateless</literal> or <literal>@Stateful</literal> annotation, or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the simple name of the bean class.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ For example, assume that you have the following EJB bean and interface defined:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[package com.example.myapp;
+import javax.ejb.Local;
- <para>This reference will cover most uses of the component in a Seam application. However, if you want to
- be able to inject a Seam EJB component into another Seam EJB component using <literal>@In</literal>, you
- need to define this EJB reference in another location. This time, it must be defined in ejb-jar.xml, and
- it's a bit tricker. </para>
+ at Local
+public class Authenticator {
+ boolean authenticate();
+}
- <para>Within the context of an EJB method call, you have to deal with a somewhat sheltered JNDI context.
- When Seam attempts to find another Seam EJB component to satisfy an injection point defined using
- <literal>@In</literal>, whether or not it finds it depends on whether an EJB reference exists in
- JNDI. Strictly speaking, you cannot simply resolve JNDI names as you please. You have to define
- the references explicitly. Fortunately, JBoss recognized how aggrevating this would be for the
- developer and all versions of JBoss automatically register EJBs so they are always available in
- JNDI, both to the web container and the EJB container. So if you are using JBoss, you can skip the next
- few paragraphs. However, if you are deploying to GlassFish, pay close attention.</para>
-
- <para>For application servers that stubbornly adhere to the EJB specification, EJB references must always be
- defined explicitly. But unlike with the web context, where a single resource reference covers all
- uses of the EJB from the web environment, you cannot declare EJB references globally in the EJB container.
- Instead, you have to specify the JNDI resources for a given EJB component one-by-one.</para>
- <para> Let's assume that we have an EJB named RegisterAction (the name is resolved using the three steps
- mentioned previously). That EJB has the following Seam injection:</para>
+package com.example.myapp;
+import javax.ejb.Stateless;
- <programlisting role="JAVA"><![CDATA[@In(create = true)
-Authenticator authenticator;
+ at Stateless
+ at Name("authenticator")
+public class AuthenticatorBean implements Authenticator {
+ public boolean authenticate() { ... }
+}
]]></programlisting>
-
- <para> In order for this injection to work, the link must be established in the ejb-jar.xml file as follows: </para>
-
- <programlisting role="XML"><![CDATA[<ejb-jar>
- <enterprise-beans>
- <session>
- <ejb-name>RegisterAction</ejb-name>
- <ejb-local-ref>
- <ejb-ref-name>myapp/AuthenticatorAction/local</ejb-ref-name>
- <ejb-ref-type>Session</ejb-ref-type>
- <local>com.example.myapp.Authenticator</local>
- </ejb-local-ref>
- </session>
- </enterprise-beans>
-
- ...
-
+ <para>
+ Assuming that your EJB bean class is deployed in an <filename>EAR</filename> named <literal>myapp</literal>, the global JNDI name assigned on the JBoss AS will be <literal>myapp/AuthenticatorBean/local</literal>. You can refer to this EJB component as a Seam component with the name <literal>authenticator</literal>, and Seam will use the JNDI pattern (or the <literal>@JndiName</literal> annotation) to locate it in JNDI.
+ </para>
+ <para>
+ For other application servers, you must declare an EJB reference for your EJB so that it is assigned a JNDI name. This does require some XML, and means that you must establish your own JNDI naming convention so that you can use the Seam JNDI pattern. It may be useful to follow the JBoss convention.
+ </para>
+ <para>
+ You must define the EJB references in two locations when using Seam with a non-JBoss application server. If you look up the Seam EJB component with JSF (in a JSF view, or as a JSF action listener) or a Seam JavaBean component, then you must declare the EJB reference in <filename>web.xml</filename>. The EJB reference that would be required for our example is:\
+ </para>
+
+<programlisting role="XML"><![CDATA[<ejb-local-ref>
+ <ejb-ref-name>myapp/AuthenticatorBean/local</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <local>org.example.vehicles.action.Authenticator</local>
+</ejb-local-ref>
+]]></programlisting>
+ <para>
+ This reference covers most uses of the component in a Seam application. If you want to be able to inject a Seam EJB component into another Seam EJB component with the <literal>@In</literal> annotation, you must define this EJB reference in a second location: <filename>ejb-jar.xml</filename>. This is slightly more complicated.
+ </para>
+ <para>
+ When Seam looks for a Seam EJB component to satisfy an injection point defined with <literal>@In</literal>, the component will only be found if it is referenced in JNDI. JBoss automatically registers EJBs to the JNDI so that they are always available to the web and EJB containers. Other containers require you to define your EJBs explicitly.
+ </para>
+ <para>
+ Application servers that adhere to the EJB specification require that EJB references are always explicitly defined. These cannot be declared globally — you must specify each JNDI resource for an EJB component individually.
+ </para>
+ <para>
+ Assuming that you have an EJB with a resolved name of <literal>RegisterAction</literal>, the following Seam injection applies:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In(create = true) Authenticator authenticator;
+]]></programlisting>
+ <para>
+ For this injection to work, you must also establish the link in <filename>ejb-jar.xml</filename>, like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<ejb-jar>
+ <enterprise-beans>
+ <session>
+ <ejb-name>RegisterAction</ejb-name>
+ <ejb-local-ref>
+ <ejb-ref-name>myapp/AuthenticatorAction/local</ejb-ref-name>
+ <ejb-ref-type>Session</ejb-ref-type>
+ <local>com.example.myapp.Authenticator</local>
+ </ejb-local-ref>
+ </session>
+ </enterprise-beans>
+
+ ...
+
</ejb-jar>
]]></programlisting>
-
- <para> Notice that the contents of the <literal><ejb-local-ref></literal> are identical to what we
- defined in web.xml. What we are doing is bringing the reference into the EJB context where it can be
- used by the RegisterAction bean. You will need to add one of these references for any injection of a
- Seam EJB compoenent into another Seam EJB component using <literal>@In</literal>. (You can see an
- example of this setup in the jee5/booking example).</para>
-
- <para> But what about <literal>@EJB</literal>? It's true that you can inject one EJB into another using
- <literal>@EJB</literal>. However, by doing so, you are injecting the actual EJB reference rather than the
- Seam EJB component instance. In this case, some Seam features will work, while others won't. That's
- because Seam's interceptor is invoked on any method call to an EJB component. But that only invokes
- Seam's server-side interceptor chain. What you lose is Seam's state management and Seam's client-side
- interceptor chain. Client-side interceptors handle concerns such as security and concurrency. Also, when
- injecting a SFSB, there is no guarantee that you will get the SFSB bound to the active session or
- conversation, whatever the case may be. Thus, you definitely want to inject the Seam EJB component using
- <literal>@In</literal>.</para>
-
- <para> That covers how JNDI names are defined and used. The lesson is that with some application servers,
- such as GlassFish, you are going to have to specify JNDI names for all EJB components explicitly, and
- sometimes twice! And even if you are following the same naming convention as JBoss AS, the JNDI pattern
- in Seam may need to be altered. For instance, the global JNDI names are automatically prefixed with
- java:comp/env on GlassFish, so you need to define the JNDI pattern as follows:</para>
-
- <programlisting role="XML"><![CDATA[<core:init jndi-name="java:comp/env/earName/#{ejbName}/local" />]]></programlisting>
-
- <para>
- Finally, let's talk about transactions. In an EJB3 environment, we recommend the use of a special
- built-in component for transaction management, that is fully aware of container transactions, and can
- correctly process transaction success events registered with the <literal>Events</literal> component. If
- you don't add this line to your <literal>components.xml</literal> file, Seam won't know when
- container-managed transactions end: </para>
-
- <programlisting role="XML"><![CDATA[<transaction:ejb-transaction/>]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Don't forget!</title>
-
- <para> There is one final item you need to know about. You must place a <literal>seam.properties</literal>,
- <literal>META-INF/seam.properties</literal> or <literal>META-INF/components.xml</literal> file in
- any archive in which your Seam components are deployed (even an empty properties file will do). At
- startup, Seam will scan any archives with <literal>seam.properties</literal> files for seam components. </para>
-
- <para> In a web archive (WAR) file, you must place a <literal>seam.properties</literal> file in the
- <literal>WEB-INF/classes</literal> directory if you have any Seam components included here. </para>
-
- <para> That's why all the Seam examples have an empty <literal>seam.properties</literal> file. You can't
- just delete this file and expect everything to still work! </para>
-
- <para> You might think this is silly and what kind of idiot framework designers would make an empty file
- affect the behavior of their software?? Well, this is a workaround for a limitation of the
- JVM — if we didn't use this mechanism, our next best option would be to force you to list every
- component explicitly in <literal>components.xml</literal>, just like some other competing frameworks do!
- I think you'll like our way better. </para>
-
- </sect2>
-
- </sect1>
-
- <sect1 id="alt-jpa-providers">
- <title>Using Alternate JPA Providers</title>
-
- <para> Seam comes packaged and configured with Hibernate as the default JPA provider.
- If you require using a different JPA provider you must tell <literal>seam</literal>
- about it.
- </para>
-
- <note>
- <title>This is a workaround</title>
- <para>
- Configuration of the JPA provider will be easier in the future and will
- not require configuration changes, unless you are adding a custom persistence provider
- implementation.
- </para>
- </note>
-
- <para>Telling seam about a different JPA provider can be be done in one of two ways:</para>
- <para>Update your application's <literal>components.xml</literal>
- so that the generic <literal>PersistenceProvider</literal> takes
- precedence over the hibernate version. Simply add the following
- to the file:
- </para>
- <programlisting role="XML"><![CDATA[<component name="org.jboss.seam.persistence.persistenceProvider"
- class="org.jboss.seam.persistence.PersistenceProvider"
- scope="stateless">
-</component>]]></programlisting>
- <para>If you want to take advantage of your JPA provider's
- non-standard features you will need to write you own implementation of
- the <literal>PersistenceProvider</literal>. Use
- <literal>HibernatePersistenceProvider</literal> as a starting
- point (don't forget to give back to the community :). Then you
- will need to tell <literal>seam</literal> to use it as before.
- </para>
- <programlisting role="XML"><![CDATA[<component name="org.jboss.seam.persistence.persistenceProvider"
- class="org.your.package.YourPersistenceProvider">
-</component>]]></programlisting>
- <para>All that is left is updating the <literal>persistence.xml</literal>
- file with the correct provider class, and what ever properties your
- provider needs. Don't forget to package your new provider's jar files in the
- application if they are needed.
- </para>
- </sect1>
-
- <sect1>
- <title>Configuring Seam in Java EE 5</title>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/ee5.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/ee5.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para> If you're running in a Java EE 5 environment, this is all the configuration required to start using Seam! </para>
-
- <sect2>
- <title>Packaging</title>
-
- <para> Once you've packaged all this stuff together into an EAR, the archive structure will look something
- like this: </para>
-
- <programlisting><![CDATA[my-application.ear/
+ <para>
+ The component is referenced here just as it was in <filename>web.xml</filename>. Identifying it here brings the reference into the EJB context, where it can be used by the <literal>RegisterAction</literal> bean. You must add one reference for each injection (via <literal>@In</literal>) of one Seam EJB component into another Seam EJB component. You can see an example of this setup in the <literal>jee5/booking</literal> example.
+ </para>
+ <para>
+ It is possible to inject one EJB into another with the <literal>@EJB</literal> annotation, but this injects the EJB reference rather than the Seam EJB component instance. Because Seam's interceptor is invoked on any <emphasis>method call</emphasis> to an EJB component, and using <literal>@EJB</literal> only invokes Seam's server-side interceptor chain, some Seam features will not work with <literal>@EJB</literal> injection. (Seam's state management and Seam's client-side interceptor chain, which handles security and concurrency, are two affected features.) When a stateful session bean is injected using the <literal>@EJB</literal> annotation, it will not necessarily bind to the active session or conversation, either, so we recommend injecting with <literal>@In</literal>.
+ </para>
+ <para>
+ Some application servers (such as Glassfish) require you to specify JNDI names for all EJB components explicitly, sometimes more than once. You may also need to alter the JNDI pattern used in Seam, even if you follow the JBoss AS naming convention. For example, in Glassfish the global JNDI names are automatically prefixed with <literal>java:comp/env</literal>, so you must define the JNDI pattern as follows:
+ </para>
+
+<programlisting role="XML"><![CDATA[<core:init jndi-name="java:comp/env/earName/#{ejbName}/local" />
+]]></programlisting>
+ <para>
+ For transaction management, we recommend using a special built-in component that is fully aware of container transactions, and can correctly process transaction success events registered with the <literal>Events</literal> component. To tell Seam when container-managed transactions end, add the following line to your <filename>components.xml</filename> file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<transaction:ejb-transaction/>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title>Remember</title>
+ <para>
+ The final requirement for integration is that a <literal>seam.properties</literal>, <literal>META-INF/seam.properties</literal> or <literal>META-INF/components.xml</literal> file be placed in any archive in which your Seam components are deployed. For web archive (WAR) files, place a <filename>seam.properties</filename> file inside the <literal>WEB-INF/classes</literal> directory in which your components are deployed.
+ </para>
+ <para>
+ Seam scans any archive with <filename>seam.properties</filename> files for Seam components at startup. The <filename>seam.properties</filename> file can be empty, but it must be included so that the component is recognized by Seam. This is a workaround for Java Virtual Machine (JVM) limitations — without the <filename>seam.properties</filename> file, you would need to list every component explicitly in <filename>components.xml</filename>.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="alt-jpa-providers">
+ <title>Using Alternate JPA Providers</title>
+ <para>
+ Seam comes packaged and configured with Hibernate as the default JPA provider. To use a different JPA provider, you must configure it with Seam.
+ </para>
+ <note>
+ <para>
+ This is a workaround — future versions of Seam will not require configuration changes to use alternative JPA providers, unless you add a custom persistence provider implementation.
+ </para>
+ </note>
+ <para>
+ There are two ways to tell Seam about your JPA provider. The first is to update your application's <filename>components.xml</filename> so that the generic <literal>PersistenceProvider</literal> takes precedence over the Hibernate version. Simply add the following to the file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<component name="org.jboss.seam.persistence.persistenceProvider"
+ class="org.jboss.seam.persistence.PersistenceProvider"
+ scope="stateless">
+</component>
+]]></programlisting>
+ <para>
+ To take advantage of any of your JPA provider's non-standard features, you must write your own implementation of the <literal>PersistenceProvider</literal>. (You can use <literal>HibernatePersistenceProvider</literal> as a starting point.) Tell Seam to use this <literal>PersistenceProvider</literal> like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<component name="org.jboss.seam.persistence.persistenceProvider"
+ class="org.your.package.YourPersistenceProvider">
+</component>
+]]></programlisting>
+ <para>
+ Now, update <filename>persistence.xml</filename> with the correct provider class, and any properties required by your provider. Remember to package any required <filename>JAR</filename> files with your application.
+ </para>
+ </section>
+
+ <section>
+ <title>Configuring Seam in Java EE 5</title>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/ee5.png" format="PNG" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/ee5.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+ <!-- #modify: This is unclear - is this preconfigured? What step is required to add JEE5 here? Might make sense to a Seam user, but not to me. :\ --> <para>
+ If you're running in a Java EE 5 environment, this is all the configuration required to start using Seam!
+ </para>
+ <section>
+ <title>Packaging</title>
+ <para>
+ Once packaged into an <filename>EAR</filename>, your archive will be structured similarly to the following:
+ </para>
+
+<programlisting><![CDATA[my-application.ear/
jboss-seam.jar
lib/
jboss-el.jar
@@ -702,103 +593,90 @@
LoginBean.class
Register.class
RegisterBean.class
- ...]]></programlisting>
-
- <para>
- You should declare <literal>jboss-seam.jar</literal> as an ejb module in <literal>META-INF/application.xml</literal>;
- <literal>jboss-el.jar</literal> should be placed in the EAR's lib directory (putting it in the EAR classpath.
- </para>
-
- <para> If you want to use jBPM or Drools, you must include the needed jars in the EAR's lib directory.</para>
-
- <para> If you want to use facelets (our recommendation), you must include
- <literal>jsf-facelets.jar</literal> in the <literal>WEB-INF/lib</literal> directory of the WAR. </para>
-
- <para> If you want to use the Seam tag library (most Seam applications do), you must include
- <literal>jboss-seam-ui.jar</literal> in the <literal>WEB-INF/lib</literal> directory of the WAR. If
- you want to use the PDF or email tag libraries, you need to put <literal>jboss-seam-pdf.jar</literal> or
- <literal>jboss-seam-mail.jar</literal> in <literal>WEB-INF/lib</literal>. </para>
-
- <para> If you want to use the Seam debug page (only works for applications using facelets), you must include
- <literal>jboss-seam-debug.jar</literal> in the <literal>WEB-INF/lib</literal> directory of the WAR. </para>
-
- <para> Seam ships with several example applications that are deployable in any Java EE container that
- supports EJB 3.0. </para>
-
- <para> I really wish that was all there was to say on the topic of configuration but unfortunately we're
- only about a third of the way there. If you're too overwhelmed by all this tedious configuration stuff,
- feel free to skip over the rest of this section and come back to it later. </para>
-
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>Configuring Seam in J2EE</title>
-
- <para> Seam is useful even if you're not yet ready to take the plunge into EJB 3.0. In this case you would use
- Hibernate3 or JPA instead of EJB 3.0 persistence, and plain JavaBeans instead of session beans. You'll miss
- out on some of the nice features of session beans but it will be very easy to migrate to EJB 3.0 when you're
- ready and, in the meantime, you'll be able to take advantage of Seam's unique declarative state management
- architecture. </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/hibernate-ee.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/hibernate-ee.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para> Seam JavaBean components do not provide declarative transaction demarcation like session beans do. You
- <emphasis>could</emphasis> manage your transactions manually using the JTA
- <literal>UserTransaction</literal> or declaratively using Seam's <literal>@Transactional</literal>
- annotation. But most applications will just use Seam managed transactions when using Hibernate with
- JavaBeans. </para>
-
- <para> The Seam distribution includes a version of the booking example application that uses Hibernate3 and
- JavaBeans instead of EJB3, and another version that uses JPA and JavaBeans. These example applications are
- ready to deploy into any J2EE application server. </para>
-
- <sect2>
- <title>Boostrapping Hibernate in Seam</title>
-
- <para> Seam will bootstrap a Hibernate <literal>SessionFactory</literal> from your
- <literal>hibernate.cfg.xml</literal> file if you install a built-in component: </para>
-
- <programlisting role="XML"><![CDATA[<persistence:hibernate-session-factory name="hibernateSessionFactory"/>]]></programlisting>
-
- <para> You will also need to configure a <emphasis>managed session</emphasis> if you want a Seam managed
- Hibernate <literal>Session</literal> to be available via injection. </para>
-
- <programlisting role="XML"><![CDATA[<persistence:managed-hibernate-session name="hibernateSession"
- session-factory="#{hibernateSessionFactory}"/>]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Boostrapping JPA in Seam</title>
-
- <para> Seam will bootstrap a JPA <literal>EntityManagerFactory</literal> from your
- <literal>persistence.xml</literal> file if you install this built-in component: </para>
-
- <programlisting role="XML"><![CDATA[<persistence:entity-manager-factory name="entityManagerFactory"/>]]></programlisting>
-
- <para> You will also need to configure a <emphasis>managed persistence context</emphasis> if you want a
- Seam managed JPA <literal>EntityManager</literal> to be available via injection. </para>
-
- <programlisting role="XML"><![CDATA[<persistence:managed-persistence-context name="entityManager"
- entity-manager-factory="#{entityManagerFactory}"/>]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Packaging</title>
-
- <para> We can package our application as a WAR, in the following structure: </para>
-
- <programlisting><![CDATA[my-application.war/
+ ...]]>
+</programlisting>
+ <para>
+ Declare <filename>jboss-seam.jar</filename> as an EJB module in <filename>META-INF/application.xml</filename>. Add <filename>jboss-el.jar</filename> to the <filename>EAR</filename> classpath by placing it in the <filename>EAR</filename>'s <literal>lib</literal> directory.
+ </para>
+ <para>
+ To use jBPM or Drools, include the required <filename>JAR</filename>s in the <filename>EAR</filename>'s <literal>lib</literal> directory.
+ </para>
+ <para>
+ Tp use Facelets, as recommended, include <filename>jsf-facelets.jar</filename> in the <literal>WEB-INF/lib</literal> directory of the <filename>WAR</filename>.
+ </para>
+ <para>
+ Most applications use the Seam tag library — to do so, include <filename>jboss-seam-ui.jar</filename> in the <literal>WEB-INF/lib</literal> directory of the WAR. To use the PDF or email tag libraries, you must also place <filename>jboss-seam-pdf.jar</filename> or <filename>jboss-seam-mail.jar</filename> in <literal>WEB-INF/lib</literal>.
+ </para>
+ <para>
+ To use the Seam debug page, include <filename>jboss-seam-debug.jar</filename> in the <literal>WEB-INF/lib</literal> directory of the <filename>WAR</filename>. Seam's debug page only works for applications using Facelets.)
+ </para>
+ <para>
+ Seam also ships with several example applications — these are deployable in any Java EE container with EJB3 support.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Configuring Seam in J2EE</title>
+ <para>
+ You can use Hibernate 3 or JPA instead of EJB3 persistence, and plain JavaBeans instead of session beans. You can still take advantage of Seam's declarative state management architecture, and it is easy to migrate to EJB3.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/hibernate-ee.png" format="PNG" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/hibernate-ee.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ Unlike session beans, Seam JavaBean components do not provide declarative transaction demarcation. Most applications use Seam-managed transactions when using Hibernate with JavaBeans, but you can also manage your transactions manually with the JTA <literal>UserTransaction</literal>, or declaratively with Seam's <literal>@Transactional</literal> annotation.
+ </para>
+ <para>
+ The Seam distribution includes extra versions of the booking example application — one uses Hibernate3 and JavaBeans instead of EJB3, and the other uses JPA and JavaBeans. These example applications are ready to deploy into any J2EE application server.
+ </para>
+ <section>
+ <title>Boostrapping Hibernate in Seam</title>
+ <para>
+ Install the following built-in component to have Seam bootstrap a Hibernate <literal>SessionFactory</literal> from your <literal>hibernate.cfg.xml</literal> file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<persistence:hibernate-session-factory name="hibernateSessionFactory"/>
+]]></programlisting>
+ <para>
+ To make a Seam-managed Hibernate <literal>Session</literal> available via injection, configure a <literal>managed session</literal> as follows:
+ </para>
+
+<programlisting role="XML"><![CDATA[<persistence:managed-hibernate-session name="hibernateSession"
+ session-factory="#{hibernateSessionFactory}"/>
+ ]]></programlisting>
+ </section>
+
+ <section>
+ <title>Boostrapping JPA in Seam</title>
+ <para>
+ Install the following built-in component to have Seam bootstrap a JPA <literal>EntityManagerFactory</literal> from your <filename>persistence.xml</filename> file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<persistence:entity-manager-factory name="entityManagerFactory"/>
+]]></programlisting>
+ <para>
+ To make a Seam-managed JPA <literal>EntityManager</literal> available via injection, configure a managed persistence context as follows:
+ </para>
+
+<programlisting role="XML"><![CDATA[<persistence:managed-persistence-context name="entityManager"
+ entity-manager-factory="#{entityManagerFactory}"/>
+ ]]></programlisting>
+ </section>
+
+ <section>
+ <title>Packaging</title>
+ <para>
+ Your application will have the following structure when packaged as a <filename>WAR</filename>:
+ </para>
+
+<programlisting><![CDATA[my-application.war/
META-INF/
MANIFEST.MF
WEB-INF/
@@ -828,58 +706,71 @@
...
login.jsp
register.jsp
- ...]]></programlisting>
+ ...
+]]></programlisting>
+ <para>
+ Some additional configuration is required in order to deploy Hibernate in a non-EE environment, such as TestNG.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Configuring Seam in Java SE, without JBoss Embedded</title>
+ <para>
+ To use Seam outside an EE environment, you must tell Seam how to manage transactions, since JTA will not be available. If you use JPA, you can tell Seam to use JPA resource-local transactions — that is, <literal>EntityTransaction</literal> — like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<transaction:entity-transaction entity-manager="#{entityManager}"/>
+]]></programlisting>
+ <para>
+ If you use Hibernate, you can tell Seam to use the Hibernate transaction API with the following:
+ </para>
+
+<programlisting role="XML"><![CDATA[<transaction:hibernate-transaction session="#{session}"/>
+]]></programlisting>
+ <para>
+ You must also define a datasource.
+ </para>
+ </section>
+
+ <section>
+ <title>Configuring Seam in Java SE, with JBoss Embedded</title>
+ <para>
+ JBoss Embedded lets you run EJB3 components outside the context of the Java EE 5 application server. This is particularly useful in testing.
+ </para>
+ <para>
+ The Seam booking example application includes a TestNG integration test suite that runs on Embedded JBoss via <literal>SeamTest</literal>.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/testng.png" format="PNG" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/testng.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+ <!--
+ <para>
+ You can also deploy the Booking example to Tomcat:
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/e-ejb3.png" format="PNG" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/e-ejb3.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
- <para> If we want to deploy Hibernate in a non-EE environment like Tomcat or TestNG, we need to do a little
- bit more work. </para>
-
- </sect2>
- </sect1>
-
- <sect1>
- <title>Configuring Seam in Java SE, without JBoss Embedded</title>
-
- <para> It is possible to use Seam completely outside of an EE environment. In this case, you need to tell Seam
- how to manage transactions, since there will be no JTA available. If you're using JPA, you can tell
- Seam to use JPA resource-local transactions, ie. <literal>EntityTransaction</literal>, like so: </para>
-
- <programlisting role="XML"><![CDATA[<transaction:entity-transaction entity-manager="#{entityManager}"/>]]></programlisting>
-
- <para> If you're using Hibernate, you can tell Seam to use the Hibernate transaction API like this: </para>
-
- <programlisting role="XML"><![CDATA[<transaction:hibernate-transaction session="#{session}"/>]]></programlisting>
-
- <para> Of course, you'll also need to define a datasource.</para>
-
- <para> A better alternative is to use JBoss Embedded to get access to the EE APIs. </para>
-
- </sect1>
-
- <sect1>
- <title>Configuring Seam in Java SE, with JBoss Embedded</title>
-
- <para> JBoss Embedded lets you run EJB3 components outside the context of the Java EE 5 application server. This
- is especially, but not only, useful for testing. </para>
-
- <para> The Seam booking example application includes a TestNG integration test suite that runs on JBoss Embedded
- via <literal>SeamTest</literal>. </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/testng.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/testng.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <sect2>
- <title>Packaging</title>
-
- <para> The archive structure of a WAR-based deployment on an servlet engine like Tomcat will look something
- like this: </para>
-
- <programlisting><![CDATA[my-application.war/
+-->
+ <section>
+ <title>Packaging</title>
+ <para>
+ A <filename>WAR</filename>-based deployment on a Servlet engine will be structured as follows:
+ </para>
+
+<programlisting><![CDATA[my-application.war/
META-INF/
MANIFEST.MF
WEB-INF/
@@ -910,69 +801,70 @@
...
login.jsp
register.jsp
- ...]]></programlisting>
-
- <para> Most of the Seam example applications may be deployed to Tomcat by running <literal>ant
- deploy.tomcat</literal>. </para>
-
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>Configuring jBPM in Seam</title>
- <para> Seam's jBPM integration is not installed by default, so you'll need to enable jBPM by installing a
- built-in component. You'll also need to explicitly list your process and pageflow definitions. In
- <literal>components.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<bpm:jbpm>
- <bpm:pageflow-definitions>
- <value>createDocument.jpdl.xml</value>
- <value>editDocument.jpdl.xml</value>
- <value>approveDocument.jpdl.xml</value>
- </bpm:pageflow-definitions>
- <bpm:process-definitions>
- <value>documentLifecycle.jpdl.xml</value>
- </bpm:process-definitions>
-</bpm:jbpm>]]></programlisting>
-
- <para> No further special configuration is needed if you only have pageflows. If you do have business process
- definitions, you need to provide a jBPM configuration, and a Hibernate configuration for jBPM. The Seam DVD
- Store demo includes example <literal>jbpm.cfg.xml</literal> and <literal>hibernate.cfg.xml</literal> files
- that will work with Seam: </para>
-
- <programlisting role="XML"><![CDATA[<jbpm-configuration>
-
- <jbpm-context>
- <service name="persistence">
- <factory>
- <bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory">
- <field name="isTransactionEnabled"><false/></field>
- </bean>
- </factory>
- </service>
- <service name="tx" factory="org.jbpm.tx.TxServiceFactory" />
- <service name="message" factory="org.jbpm.msg.db.DbMessageServiceFactory" />
- <service name="scheduler" factory="org.jbpm.scheduler.db.DbSchedulerServiceFactory" />
- <service name="logging" factory="org.jbpm.logging.db.DbLoggingServiceFactory" />
+ ...
+]]></programlisting>
+<!--
+ <para>
+ You can deploy most of Seam's example applications to Tomcat by running <literal>ant deploy.tomcat</literal>.
+ </para>
+-->
+ </section>
+
+ </section>
+
+ <section>
+ <title>Configuring jBPM in Seam</title>
+ <para>
+ Seam's jBPM integration is not installed by default. To enable jBPM, you must install a built-in component. You must also explicitly list your process and pageflow definitions. In <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<bpm:jbpm>
+ <bpm:pageflow-definitions>
+ <value>createDocument.jpdl.xml</value>
+ <value>editDocument.jpdl.xml</value>
+ <value>approveDocument.jpdl.xml</value>
+ </bpm:pageflow-definitions>
+ <bpm:process-definitions>
+ <value>documentLifecycle.jpdl.xml</value>
+ </bpm:process-definitions>
+</bpm:jbpm>
+]]></programlisting>
+ <para>
+ If you only have pageflows, no further configuration is required. If you have business process definitions, you must provide a jBPM configuration, and a Hibernate configuration for jBPM. The Seam DVD Store demo includes example <filename>jbpm.cfg.xml</filename> and <filename>hibernate.cfg.xml</filename> files that will work with Seam:
+ </para>
+
+<programlisting role="XML"><![CDATA[<jbpm-configuration>
+ <jbpm-context>
+ <service name="persistence">
+ <factory>
+ <bean class="org.jbpm.persistence.db.DbPersistenceServiceFactory">
+ <field name="isTransactionEnabled"><false/></field>
+ </bean>
+ </factory>
+ </service>
+ <service name="tx" factory="org.jbpm.tx.TxServiceFactory" />
+ <service name="message"
+ factory="org.jbpm.msg.db.DbMessageServiceFactory" />
+ <service name="scheduler"
+ factory="org.jbpm.scheduler.db.DbSchedulerServiceFactory" />
+ <service name="logging"
+ factory="org.jbpm.logging.db.DbLoggingServiceFactory" />
<service name="authentication"
- factory="org.jbpm.security.authentication.DefaultAuthenticationServiceFactory" />
- </jbpm-context>
-
-</jbpm-configuration>]]></programlisting>
-
- <para> The most important thing to notice here is that jBPM transaction control is disabled. Seam or EJB3 should
- control the JTA transactions. </para>
-
- <sect2>
- <title>Packaging</title>
-
- <para> There is not yet any well-defined packaging format for jBPM configuration and process/pageflow
- definition files. In the Seam examples we've decided to simply package all these files into the root of
- the EAR. In future, we will probably design some other standard packaging format. So the EAR looks
- something like this: </para>
-
- <programlisting><![CDATA[my-application.ear/
+ factory="org.jbpm.security.authentication
+ .DefaultAuthenticationServiceFactory"/>
+ </jbpm-context>
+</jbpm-configuration>
+]]></programlisting>
+ <para>
+ Note that jBPM transaction control is disabled — JTA transactions should be controlled by either Seam or EJB3.
+ </para>
+ <section>
+ <title>Packaging</title>
+ <para>
+ There is no well-defined packaging format for jBPM configuration and process or pageflow definition files. While other standard packaging formats may be developed, the Seam examples are packaged into the root of the <filename>EAR</filename>, and follow this structure:
+ </para>
+
+<programlisting><![CDATA[my-application.ear/
jboss-seam.jar
lib/
jboss-el.jar
@@ -1012,101 +904,89 @@
createDocument.jpdl.xml
editDocument.jpdl.xml
approveDocument.jpdl.xml
- documentLifecycle.jpdl.xml]]></programlisting>
+ documentLifecycle.jpdl.xml]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Configuring SFSB and Session Timeouts in JBoss AS</title>
+ <para>
+ The timeout for stateful session beans must be longer than the timeout for HTTP sessions, or the stateful session bean may timeout before the user's HTTP Session ends. The JBoss AS has a default session bean timeout of 30 minutes, which is configured in <filename>server/default/conf/standardjboss.xml</filename> — to change this, replace <literal>default</literal> with your own preferred configuration.
+ </para>
+ <para>
+ In the <literal>LRUStatefulContextCachePolicy</literal> cache configuration, modify the value of <literal>max-bean-life</literal> to change the default stateful session bean timeout:
+ </para>
+
+<programlisting role="XML"><![CDATA[<container-cache-conf>
+ <cache-policy>
+ org.jboss.ejb.plugins.LRUStatefulContextCachePolicy
+ </cache-policy>
+ <cache-policy-conf>
+ <min-capacity>50</min-capacity>
+ <max-capacity>1000000</max-capacity>
+ <remover-period>1800</remover-period>
- </sect2>
+ <!-- SFSB timeout in seconds; 1800 seconds == 30 minutes -->
+ <max-bean-life>1800</max-bean-life>
- </sect1>
+ <overager-period>300</overager-period>
+ <max-bean-age>600</max-bean-age>
+ <resizer-period>400</resizer-period>
+ <max-cache-miss-period>60</max-cache-miss-period>
+ <min-cache-miss-period>1</min-cache-miss-period>
+ <cache-load-factor>0.75</cache-load-factor>
+ </cache-policy-conf>
+</container-cache-conf>
+]]></programlisting>
+ <para>
+ You can modify the default HTTP Session timeout in <filename>server/default/deploy/jboss-web.deployer/conf/web.xml</filename> for JBoss 4.2.x or later. The following entry in the <filename>web.xml</filename> file controls the default session timeout for all web applications:
+ </para>
+
+<programlisting role="XML"><![CDATA[<session-config>
+ <!-- HTTP Session timeout, in minutes -->
+ <session-timeout>30</session-timeout>
+</session-config>
+]]></programlisting>
+ <para>
+ To override this value for your own application, simply include a modified version of this entry in your application's own <filename>web.xml</filename>.
+ </para>
+ </section>
+
+ <section>
+ <title>Running Seam in a Portlet</title>
+ <warning>
+ <title>JBoss Portlet Bridge integration is a Technology Preview</title>
+ <para>Technology Preview features are not fully supported under Red Hat subscription level agreements (SLAs), may not be functionally complete, and are not intended for production use. However, these features provide early access to upcoming product innovations, enabling customers to test functionality and provide feedback during the development process. As Red Hat considers making future iterations of Technology Preview features generally available, we will provide commercially reasonable efforts to resolve any reported issues that customers experience when using these features.</para>
+ </warning>
- <sect1>
- <title>Configuring SFSB and Session Timeouts in JBoss AS</title>
-
- <para> It is very important that the timeout for Stateful Session Beans is set higher than the timeout for HTTP
- Sessions, otherwise SFSB's may time out before the user's HTTP session has ended. JBoss Application Server
- has a default session bean timeout of 30 minutes, which is configured in
- <literal>server/default/conf/standardjboss.xml</literal> (replace <emphasis>default</emphasis> with your
- own configuration). </para>
-
- <para> The default SFSB timeout can be adjusted by modifying the value of <literal>max-bean-life</literal> in
- the <literal>LRUStatefulContextCachePolicy</literal> cache configuration: </para>
-
- <programlisting role="XML"><![CDATA[<container-cache-conf>
- <cache-policy>org.jboss.ejb.plugins.LRUStatefulContextCachePolicy</cache-policy>
- <cache-policy-conf>
- <min-capacity>50</min-capacity>
- <max-capacity>1000000</max-capacity>
- <remover-period>1800</remover-period>
-
- <!-- SFSB timeout in seconds; 1800 seconds == 30 minutes -->
- <max-bean-life>1800</max-bean-life>
-
- <overager-period>300</overager-period>
- <max-bean-age>600</max-bean-age>
- <resizer-period>400</resizer-period>
- <max-cache-miss-period>60</max-cache-miss-period>
- <min-cache-miss-period>1</min-cache-miss-period>
- <cache-load-factor>0.75</cache-load-factor>
- </cache-policy-conf>
-</container-cache-conf>]]></programlisting>
-
- <para> The default HTTP session timeout can be modified in
- <literal>server/default/deploy/jboss-web.deployer/conf/web.xml</literal> for JBoss 4.2.x or later. The following
- entry in this file controls the default session timeout for all web applications: </para>
-
- <programlisting role="XML"><![CDATA[<session-config>
- <!-- HTTP Session timeout, in minutes -->
- <session-timeout>30</session-timeout>
-</session-config>]]></programlisting>
-
- <para> To override this value for your own application, simply include this entry in your application's own
- <literal>web.xml</literal>. </para>
-
- </sect1>
-
- <sect1>
- <title>Running Seam in a Portlet</title>
-
- <para>
- If you want to run your Seam application in a portlet, take a look at
- the JBoss Portlet Bridge, an implementation of JSR-301 that supports
- JSF within a portlet, with extensions for Seam and RichFaces. See
- <ulink url="http://labs.jboss.com/portletbridge">http://labs.jboss.com/portletbridge</ulink>
- for more.
- </para>
-
- <note>
- <title>Technology preview </title>
- <para>Seam Integration with JBoss Portlet Bridge is marked as technology preview, so standard support is not guaranteed.</para>
- </note>
-
- </sect1>
-
- <sect1>
- <title>Deploying custom resources</title>
-
- <para>
- Seam scans all jars containing <literal>/seam.properties</literal>,
- <literal>/META-INF/components.xml</literal> or <literal>/META-INF/seam.properties</literal>
- on startup for resources. For example, all classes annotated with
- <literal>@Name</literal> are registered with Seam as Seam components.
- </para>
-
- <para>
- You may also want Seam to handle custom resources. A common use case
- is to handle a specific annotation and Seam provides specific
- support for this. First, tell Seam which annotations to handle in
- <literal>/META-INF/seam-deployment.properties</literal>:
- </para>
-
- <programlisting><![CDATA[# A colon-separated list of annotation types to handle
-org.jboss.seam.deployment.annotationTypes=com.acme.Foo:com.acme.Bar]]></programlisting>
-
- <para>
- Then, during application startup you can get hold of all classes
- annotated with <literal>@Foo</literal>:
- </para>
-
- <programlisting><![CDATA[@Name("fooStartup")
+ <para>
+ You can use the JBoss Portlet Bridge to run your Seam application in a portlet. The bridge supports JSF within a portlet, and includes extensions for Seam and RichFaces. See <ulink url="http://labs.jboss.com/portletbridge">http://labs.jboss.com/ portletbridge</ulink> for more information.
+ </para>
+
+ </section>
+
+ <section>
+ <title>Deploying custom resources</title>
+ <para>
+ On startup, Seam scans all <filename>JAR</filename>s containing <filename>/seam.properties</filename>, <filename>/META-INF/components.xml</filename> or <filename>/META-INF/seam.properties</filename> for resources. For example, all classes annotated with <literal>@Name</literal> are registered on startup as Seam components.
+ </para>
+ <para>
+ You can also use Seam to handle custom resources — that is, Seam can handle specific annotations. First, provide a list of annotation types to handle in the <literal>/META-INF/seam-deployment.properties</literal> files, like so:
+ </para>
+
+<programlisting><![CDATA[# A colon-separated list of annotation types to handle
+org.jboss.seam.deployment.annotationTypes=com.acme.Foo:com.acme.Bar
+]]></programlisting>
+ <para>
+ Then, collect all classes annotated with <literal>@Foo</literal> on application startup:
+ </para>
+<!--
+<programlisting><![CDATA[@Name("fooStartup") @Scope(APPLICATION) @Startup public class FooStartup { @In("#{deploymentStrategy.annotatedClasses['com.acme.Foo']}") private Set<Class<Object>> fooClasses; @In("#{hotDeploymentStrategy.annotatedClasses['com.acme.Foo']}") private Set<Class<Object>> hotFooClasses; @Create public void create() { for (Class clazz: fooClasses) { handleClass(clazz); } for (Class clazz: hotFooClasses) { handleClass(clazz); } } } ]]>
+</programlisting>
+-->
+<programlisting><![CDATA[@Name("fooStartup")
@Scope(APPLICATION)
@Startup
public class FooStartup {
@@ -1131,86 +1011,76 @@
// ...
}
-}]]></programlisting>
+}
+]]></programlisting>
- <para>
- You can also handle <emphasis>any</emphasis> resource. For example,
- you process any files with the extension <literal>.foo.xml</literal>.
- To do this, we need to write a custom deployment handler:
- </para>
-
- <programlisting><![CDATA[public class FooDeploymentHandler implements DeploymentHandler {
- private static DeploymentMetadata FOO_METADATA = new DeploymentMetadata()
- {
- public String getFileNameSuffix() {
- return ".foo.xml";
- }
- };
-
- public String getName() {
- return "fooDeploymentHandler";
- }
+ <para>
+ You can also set Seam to handle any resource. For example, if you want to process files with the <literal>.foo.xml</literal> extension, you can write a custom deployment handler:
+ </para>
+
+<programlisting><![CDATA[public class FooDeploymentHandler implements DeploymentHandler {
+ private static DeploymentMetadata FOO_METADATA = new DeploymentMetadata() {
- public DeploymentMetadata getMetadata() {
- return FOO_METADATA;
+ public String getFileNameSuffix() {
+ return ".foo.xml";
}
-}]]></programlisting>
+ };
+
+ public String getName() {
+ return "fooDeploymentHandler";
+ }
- <para>
- Here we are just building a list of any files with the suffix
- <literal>.foo.xml</literal>.
- </para>
-
- <para>
- Then, we need to register the deployment handler with Seam in
- <literal>/META-INF/seam-deployment.properties</literal>.
- You can register multiple deployment handler using a comma
- separated list.
- </para>
-
- <programlisting><![CDATA[# For standard deployment
-org.jboss.seam.deployment.deploymentHandlers=com.acme.FooDeploymentHandler
-# For hot deployment
-org.jboss.seam.deployment.hotDeploymentHandlers=com.acme.FooDeploymentHandler]]></programlisting>
-
- <para>
-
- </para>
-
- <para>
- Seam uses deployment handlers internally to install components and
- namespaces. You can easily access the deployment handler during an
- <literal>APPLICATION</literal> scoped component's startup:
- </para>
-
- <programlisting><![CDATA[@Name("fooStartup")
- at Scope(APPLICATION)
- at Startup
-public class FooStartup {
-
- @In("#{deploymentStrategy.deploymentHandlers['fooDeploymentHandler']}")
- private FooDeploymentHandler myDeploymentHandler;
-
- @In("#{hotDeploymentStrategy.deploymentHandlers['fooDeploymentHandler']}")
- private FooDeploymentHandler myHotDeploymentHandler;
-
- @Create
- public void create() {
- for (FileDescriptor fd: myDeploymentHandler.getResources()) {
- handleFooXml(fd);
- }
-
- for (FileDescriptor f: myHotDeploymentHandler.getResources()) {
- handleFooXml(fd);
- }
- }
-
- public void handleFooXml(FileDescriptor fd) {
- // ...
- }
-}]]></programlisting>
-
- </sect1>
-
+ public DeploymentMetadata getMetadata() {
+ return FOO_METADATA;
+ }
+}
+]]></programlisting>
+ <para>
+ This provides us with a list of all files with the <literal>.foo.xml</literal> suffix.
+ </para>
+ <para>
+ Next, register the deployment handler with Seam in <filename>/META-INF/seam-deployment.properties</filename>:
+ </para>
+
+<programlisting><![CDATA[# For standard deployment
+# org.jboss.seam.deployment.deploymentHandlers=
+# com.acme.FooDeploymentHandler
+
+# For hot deployment
+# org.jboss.seam.deployment.hotDeploymentHandlers=
+# com.acme.FooDeploymentHandler
+]]></programlisting>
+ <para>
+ You can register multiple deployment handlers with a comma-separated list.
+ </para>
+ <para>
+ Seam uses deployment handlers internally to install components and namespaces, so the <literal>handle()</literal> is called too early in Seam bootstrap to be useful. You can access the deployment handler easily during the startup of an application-scoped component:
+ </para>
+
+<programlisting><![CDATA[@Name("fooStartup")
+ at Scope(APPLICATION)
+ at Startup
+public class FooStartup {
+ @In("#{deploymentStrategy.deploymentHandlers['fooDeploymentHandler']}")
+ private FooDeploymentHandler myDeploymentHandler;
+ @In("#{hotDeploymentStrategy.deploymentHandlers['fooDeploymentHandler']}")
+ private FooDeploymentHandler myHotDeploymentHandler;
+ @Create public void create() {
+ for (FileDescriptor fd: myDeploymentHandler.getResources()) {
+ handleFooXml(fd);
+ }
+ for (FileDescriptor f: myHotDeploymentHandler.getResources()) {
+ handleFooXml(fd);
+ }
+ }
+
+ public void handleFooXml(FileDescriptor fd) {
+ // ...
+ }
+}
+]]></programlisting>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Controls.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Controls.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Controls.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,1192 +1,1143 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-
-<chapter id="controls">
- <title>Seam JSF controls</title>
- <para>
- Seam includes a number of JSF controls that are useful for working with
- Seam. These are intended to complement the built-in JSF controls, and
- controls from other third-party libraries. We recommend
- JBoss RichFaces and Apache MyFaces Trinidad tag libraries for use with Seam.
- We do not recommend the use of the Tomahawk tag library.
- </para>
-
- <section id="controls.tags">
- <title>Tags</title>
-
- <para>
- To use these tags, define the "<literal>s</literal>" namespace in your page
- as follows (facelets only):
- </para>
-
- <programlisting role="XHTML"><![CDATA[<html xmlns="http://www.w3.org/1999/xhtml"
- xmlns:s="http://jboss.com/products/seam/taglib">]]></programlisting>
-
- <para>
- The ui example demonstrates the use of a number of these tags.
- </para>
-
- <section>
- <title>Navigation Controls</title>
-
- <section>
- <title><literal><s:button></literal></title>
-
- <para><emphasis>Description</emphasis></para>
-
- <para>
- A button that supports invocation of an action with control over
- conversation propagation. <emphasis>Does not submit the
- form.</emphasis>
- </para>
- <para><emphasis>Attributes</emphasis></para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — the label.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>action</literal> — a method binding that
- specified the action
- listener.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>view</literal> — the JSF view id to link to.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fragment</literal> — the fragment
- identifier to link to.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>disabled</literal> — is the link disabled?
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>propagation</literal> — determines the
- conversation propagation style: <literal>begin</literal>,
- <literal>join</literal>, <literal>nest</literal>,
- <literal>none</literal> or <literal>end</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pageflow</literal> — a pageflow definition
- to begin. (This is only useful when
- <literal>propagation="begin"</literal> or
- <literal>propagation="join"</literal> is used).
- </para>
- </listitem>
- </itemizedlist>
-
- <para><emphasis>Usage</emphasis></para>
-
- <programlisting role="XHTML"><![CDATA[<s:button id="cancel"
- value="Cancel"
- action="#{hotelBooking.cancel}"/>]]></programlisting>
- <para>
- You can specify both <literal>view</literal> and
- <literal>action</literal> on <literal><s:link /></literal>.
- In this case, the action will be called once the redirect to the
- specified view has occured.
- </para>
-
- <para>
- The use of action listeners (including the default JSF action
- listener) is not supported with <literal><s:button /></literal>.
- </para>
-
- </section>
-
- <section>
- <title><literal><s:conversationId></literal></title>
-
- <para><emphasis>Description</emphasis></para>
-
- <para>
- Add the conversation id to JSF link or button (e.g.
- <literal><h:commandLink /></literal> ,
- <literal><s:button /></literal>).
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
-
- <para>None</para>
-
- </section>
-
- <section>
- <title><literal><s:taskId></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Add the task id to an output link (or similar JSF control),
- when the task is available via <literal>#{task}</literal>.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
-
- </section>
-
- <section>
- <title><literal><s:link></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- A link that supports invocation of an action with control over
- conversation propagation. <emphasis>Does not submit the
- form.</emphasis>
- </para>
-
- <para>
- The use of action listeners (including the default JSF action
- listener) is not supported with <literal><s:link /></literal>.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — the label.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>action</literal> — a method binding that
- specified the action listener.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>view</literal> — the JSF view id to link to.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fragment</literal> — the fragment identifier
- to link to.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>disabled</literal> — is the link disabled?
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>propagation</literal> — determines the
- conversation propagation style: <literal>begin</literal>,
- <literal>join</literal>, <literal>nest</literal>,
- <literal>none</literal> or <literal>end</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pageflow</literal> — a pageflow definition
- to begin. (This is only useful when using
- <literal>propagation="begin"</literal> or
- <literal>propagation="join"</literal>.)
- </para>
- </listitem>
- </itemizedlist>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:link id="register" view="/register.xhtml"
- value="Register New User"/>]]></programlisting>
- <para>
- You can specify both <literal>view</literal> and
- <literal>action</literal> on <literal><s:link /></literal>.
- In this case, the action will be called once the redirect to the
- specified view has occured.
- </para>
-
- </section>
-
- <section>
- <title><literal><s:conversationPropagation></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Customize the conversation propagation for a command link or button
- (or similar JSF control). <emphasis>Facelets only.</emphasis>
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>type</literal> — determines the conversation
- propagation style: <literal>begin</literal>,
- <literal>join</literal>, <literal>nest</literal>,
- <literal>none</literal> or <literal>end</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pageflow</literal> — a pageflow definition to
- begin. (This is only useful when using
- <literal>propagation="begin"</literal> or
- <literal>propagation="join"</literal>.)
- </para>
- </listitem>
- </itemizedlist>
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<h:commandButton value="Apply" action="#{personHome.update}">
- <s:conversationPropagation type="join" />
-</h:commandButton>]]></programlisting>
- </section>
-
- <section>
- <title>
- <literal><s:defaultAction></literal>
- </title>
-
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>
- Specify the default action to run when the form is submitted using
- the enter key.
- </para>
- <para>
- Currently you can only nest it inside buttons (e.g.
- <literal><h:commandButton /></literal>,
- <literal><a:commandButton /></literal> or
- <literal><tr:commandButton /></literal>).
- </para>
- <para>
- You must specify an id on the action source. You can only have one
- default action per form.
- </para>
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <para>None.</para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<h:commandButton id="foo" value="Foo" action="#{manager.foo}">
- <s:defaultAction />
-</h:commandButton>]]></programlisting>
- </section>
-
- </section>
-
- <section>
- <title>Converters and Validators</title>
-
- <section>
- <title><literal><s:convertDateTime></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>Perform date or time conversions in the Seam timezone.</para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>None.</para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<h:outputText value="#{item.orderDate}">
- <s:convertDateTime type="both" dateStyle="full"/>
-</h:outputText>]]></programlisting>
-
- </section>
-
- <section>
- <title><literal><s:convertEntity></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Assigns an entity converter to the current component. This is
- useful for radio button and dropdown controls.
- </para>
-
- <para>
- The converter works with any managed entity - either simple or
- composite. The converter should be able to find the items
- declared in the JSF controls on form submission, otherwise you
- will receive a validation error.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>None.</para>
-
- <para><emphasis>Configuration</emphasis></para>
-
- <para>
- You must use <emphasis>Seam managed transactions</emphasis> (see
- <xref linkend="persistence.seam-managed-transactions" />) with
- <literal><s:convertEntity /></literal>.
- </para>
-
- <para>
- If your <emphasis>Managed Persistence Context</emphasis> isn't
- called <literal>entityManager</literal>, then you need to set it
- in components.xml:
- </para>
- <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:ui="http://jboss.com/products/seam/ui">
-
- <ui:jpa-entity-loader entity-manager="#{em}" />]]></programlisting>
-
- <para>
- If you are using a <emphasis>Managed Hibernate Session</emphasis>
- then you need to set it in components.xml:
- </para>
- <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:ui="http://jboss.com/products/seam/ui">
-
- <ui:hibernate-entity-loader />]]></programlisting>
-
- <para>
- If your <emphasis>Managed Hibernate Session</emphasis> isn't
- called <literal>session</literal>, then you need to set it
- in components.xml:
- </para>
-
- <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:ui="http://jboss.com/products/seam/ui">
-
- <ui:hibernate-entity-loader session="#{hibernateSession}" />]]></programlisting>
-
- <para>
- If you want to use more than one entity manager with the entity
- converter, you can create a copy of the entity converter for each
- entity manager in <literal>components.xml</literal> - note how
- the entity converter delegates to the entity loader to perform
- persistence operations:
- </para>
-
- <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:ui="http://jboss.com/products/seam/ui">
-
- <ui:entity-converter name="standardEntityConverter" entity-loader="#{standardEntityLoader}" />
-
- <ui:jpa-entity-loader name="standardEntityLoader" entity-manager="#{standardEntityManager}" />
-
- <ui:entity-converter name="restrictedEntityConverter" entity-loader="#{restrictedEntityLoader}" />
-
- <ui:jpa-entity-loader name="restrictedEntityLoader" entity-manager="#{restrictedEntityManager}" />]]></programlisting>
-
- <programlisting><![CDATA[<h:selectOneMenu value="#{person.continent}">
- <s:selectItems value="#{continents.resultList}" var="continent"
- label="#{continent.name}" />
- <f:converter converterId="standardEntityConverter" />
-</h:selectOneMenu>]]></programlisting>
-
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{person.continent}" required="true">
- <s:selectItems value="#{continents.resultList}" var="continent"
- label="#{continent.name}"
- noSelectionLabel="Please Select..."/>
- <s:convertEntity />
-</h:selectOneMenu>]]></programlisting>
- </section>
-
- <section>
- <title><literal><s:convertEnum></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Assigns an enum converter to the current component. This is
- primarily useful for radio button and dropdown controls.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>None.</para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{person.honorific}">
- <s:selectItems value="#{honorifics}" var="honorific"
- label="#{honorific.label}"
- noSelectionLabel="Please select" />
- <s:convertEnum />
-</h:selectOneMenu>]]></programlisting>
- </section>
-
- <section>
- <title><literal><s:convertAtomicBoolean></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- <literal>javax.faces.convert.Converter</literal> for
- <literal>java.util.concurrent.atomic.AtomicBoolean</literal>.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting><![CDATA[<h:outputText value="#{item.valid}">
- <s:convertAtomicBoolean />
-</h:outputText>]]></programlisting>
- </section>
- <section>
- <title><literal><s:convertAtomicInteger></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- <literal>javax.faces.convert.Converter</literal> for
- <literal>java.util.concurrent.atomic.AtomicInteger</literal>.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting><![CDATA[<h:outputText value="#{item.id}">
- <s:convertAtomicInteger />
-</h:outputText>]]></programlisting>
- </section>
- <section>
- <title><literal><s:convertAtomicLong></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- <literal>javax.faces.convert.Converter</literal> for
- <literal>java.util.concurrent.atomic.AtomicLong</literal>.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting><![CDATA[<h:outputText value="#{item.id}">
- <s:convertAtomicLong />
-</h:outputText>]]></programlisting>
- </section>
-
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<!-- This Chapter has been updated on 04 November 2009 to reflect JBPAPP_5_0-CR5
+ sourced from:
+ https://svn.jboss.org/repos/seam/tags/JBPAPP_5_0-CR5/doc/Seam_Reference_Guide/en-US
+-->
+<chapter id="controls" >
+ <title>Seam JSF controls</title>
+ <para>
+ Seam includes a number of JavaServer Faces (JSF) controls to complement built-in controls, and controls from other third-party libraries. We recommend JBoss RichFaces and Apache MyFaces Trinidad tag libraries for use with Seam. We do not recommend the use of the Tomahawk tag library.
+ </para>
+ <section id="controls.tags">
+ <title>Tags</title>
+ <para>
+ To use these tags, define the <literal>s</literal> namespace in your page as follows (Facelets only):
+ </para>
- <section>
- <title><literal><s:validateEquality></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Tag to nest inside an input control to validate that its parent's
- value is equal (or not equal!) to the referenced control's value.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>for</literal> — The id of a control to validate against.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>message</literal> — Message to show on failure.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>required</literal> — False will disable a check that a value at all is inputted in fields.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>messageId</literal> — Message id to show on failure.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>operator</literal> — What operator to use when comparing the values
- Valid operators are:
- <itemizedlist>
- <listitem>
- <para>
- <literal>equal</literal> — Validates that value.equals(forValue)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>not_equal</literal> — Validates that !value.equals(forValue)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>greater</literal> — <![CDATA[Validates that ((Comparable)value).compareTo(forValue) > 0]]>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>greater_or_equal</literal> — <![CDATA[Validates that ((Comparable)value).compareTo(forValue) >= 0]]>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>less</literal> — <![CDATA[Validates that ((Comparable)value).compareTo(forValue) < 0]]>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>less_or_equal</literal> — <![CDATA[Validates that ((Comparable)value).compareTo(forValue) <= 0]]>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting><![CDATA[<h:inputText id="name" value="#{bean.name}"/>
-<h:inputText id="nameVerification" >
- <s:validateEquality for="name" />
-</h:inputText>]]></programlisting>
- </section>
-
-
-
-
-
- <section>
- <title><literal><s:validate></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- A non-visual control, validates a JSF input field against the
- bound property using Hibernate Validator.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<h:inputText id="userName" required="true"
- value="#{customer.userName}">
- <s:validate />
-</h:inputText>
-<h:message for="userName" styleClass="error" />]]></programlisting>
- </section>
-
- <section>
- <title><literal><s:validateAll></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- A non-visual control, validates all child JSF input fields
- against their bound properties using Hibernate Validator.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:validateAll>
- <div class="entry">
- <h:outputLabel for="username">Username:</h:outputLabel>
- <h:inputText id="username" value="#{user.username}"
- required="true"/>
- <h:message for="username" styleClass="error" />
- </div>
- <div class="entry">
- <h:outputLabel for="password">Password:</h:outputLabel>
+<programlisting role="XHTML"><![CDATA[<html xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:s="http://jboss.com/products/seam/taglib">
+]]></programlisting>
+ <para>
+ The user interface example demonstrates the use of a number of these tags.
+ </para>
+ <section>
+ <title>Navigation Controls</title>
+ <section>
+ <title><literal><![CDATA[<s:button>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ A button that supports invoking an action with control over conversation propagation. <emphasis>This button does not submit the form.</emphasis>
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — the button label.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>action</literal> — a method binding that specifies the action listener.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>view</literal> — specifies the JSF view ID to link to.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fragment</literal> — specifies the fragment identifier to link to.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disabled</literal> — specifies whether the link is disabled.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>propagation</literal> — determines the conversation propagation style: <literal>begin</literal>, <literal>join</literal>, <literal>nest</literal>, <literal>none</literal> or <literal>end</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pageflow</literal> — specifies a pageflow definition to begin. (Effective only when <literal>propagation="begin"</literal> or <literal>propagation="join"</literal> is used.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:button id="cancel" value="Cancel" action="#{hotelBooking.cancel}"/>
+]]></programlisting>
+ <para>
+ You can specify both <literal>view</literal> and <literal>action</literal> on <literal><![CDATA[<s:link />]]></literal>. In this case, the action will be called once the redirect to the specified view has occurred.
+ </para>
+ <para>
+ The use of action listeners (including the default JSF action listener) is not supported with <literal><![CDATA[<s:button />]]></literal>.
+ </para>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:conversationId>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Adds the conversation ID to a JSF link or button, for example:
+ </para>
+ <para>
+ <literal><![CDATA[<h:commandLink />]]></literal>, <literal><![CDATA[<s:button />]]></literal>.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:taskId>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Adds the task ID to an output link (or similar JSF control) when the task is available via <literal>#{task}</literal>.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:link>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ A link that supports invoking an action with control over conversation propagation. <emphasis>This does not submit the form.</emphasis>
+ </para>
+ <para>
+ The use of action listeners (including the default JSF action listener) is not supported with <literal><![CDATA[<s:link />]]></literal>.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — specifies the link label.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>action</literal> — a method binding that specifies the action listener.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>view</literal> — specifies the JSF view ID to link to.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fragment</literal> — specifies the fragment identifier to link to.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disabled</literal> — specifies whether the link is disabled.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>propagation</literal> — determines the conversation propagation style: <literal>begin</literal>, <literal>join</literal>, <literal>nest</literal>, <literal>none</literal> or <literal>end</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pageflow</literal> — specifies a pageflow definition to begin. (Effective only when using <literal>propagation="begin"</literal> or <literal>propagation="join"</literal>.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:link id="register" view="/register.xhtml" value="Register New User"/>
+]]></programlisting>
+ <para>
+ You can specify both <literal>view</literal> and <literal>action</literal> on <literal><![CDATA[<s:link />]]></literal>. In this case, the action will be called once the redirect to the specified view has occurred.
+ </para>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:conversationPropagation>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Customizes the conversation propagation for a command link or button (or similar JSF control). <emphasis>Facelets only.</emphasis>
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>type</literal> — determines the conversation propagation style: <literal>begin</literal>, <literal>join</literal>, <literal>nest</literal>, <literal>none</literal> or <literal>end</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pageflow</literal> — specifies a pageflow definition to begin. (Effective only useful when using <literal>propagation="begin"</literal> or <literal>propagation="join"</literal>.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton value="Apply" action="#{personHome.update}">
+ <s:conversationPropagation type="join" />
+</h:commandButton>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title> <literal><![CDATA[<s:defaultAction>]]></literal> </title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Specifies the default action to run when the form is submitted using the enter key.
+ </para>
+ <para>
+ Currently you this can only be nested inside buttons, such as <literal><![CDATA[<h:commandButton />]]></literal>, <literal><![CDATA[<a:commandButton />]]></literal> or <literal><![CDATA[<tr:commandButton />]]></literal>).
+ </para>
+ <para>
+ You must specify an ID on the action source, and only one default action can be specified per form.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton id="foo" value="Foo" action="#{manager.foo}">
+ <s:defaultAction />
+</h:commandButton>
+]]></programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Converters and Validators</title>
+ <section>
+ <title><literal><![CDATA[<s:convertDateTime>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Perform date or time conversions in the Seam timezone.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:outputText value="#{item.orderDate}">
+ <s:convertDateTime type="both" dateStyle="full"/>
+</h:outputText>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:convertEntity>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Assigns an entity converter to the current component. This is useful for radio button and dropdown controls.
+ </para>
+ <para>
+ The converter works with any managed entity - either simple or composite. If the converter cannot find the items declared in the JSF controls upon form submission, a validation error will occur.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Configuration</emphasis>
+ </para>
+ <para>
+ You must use <emphasis>Seam managed transactions</emphasis> (see <xref linkend="persistence.seam-managed-transactions" />) with <literal><![CDATA[<s:convertEntity />]]></literal>.
+ </para>
+ <para>
+ Your <emphasis>Managed Persistence Context</emphasis> must be named <literal>entityManager</literal> — if it is not, you can change its named in <literal>components.xml</literal>:
+ </para>
+
+<programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:ui="http://jboss.com/products/seam/ui">
+<ui:jpa-entity-loader entity-manager="#{em}" />
+]]></programlisting>
+ <para>
+ If you are using a <emphasis>Managed Hibernate Session</emphasis>, you must also set this in <literal>components.xml</literal>:
+ </para>
+
+<programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:ui="http://jboss.com/products/seam/ui">
+<ui:hibernate-entity-loader />
+]]></programlisting>
+ <para>
+ Your <emphasis>Managed Hibernate Session</emphasis> must be named <literal>session</literal> — if it is not, you can change its named in <filename>components.xml</filename>:
+ </para>
+
+<programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:ui="http://jboss.com/products/seam/ui">
+<ui:hibernate-entity-loader session="#{hibernateSession}" />
+]]></programlisting>
+ <para>
+ To use multiple entity managers with the entity converter, create a copy of the entity converter for each entity manager in <filename>components.xml</filename>. The entity converter delegates to the entity loader to perform persistence operations like so:
+ </para>
+
+<programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:ui="http://jboss.com/products/seam/ui">
+<ui:entity-converter name="standardEntityConverter"
+ entity-loader="#{standardEntityLoader}" />
+<ui:jpa-entity-loader name="standardEntityLoader"
+ entity-manager="#{standardEntityManager}" />
+<ui:entity-converter name="restrictedEntityConverter"
+ entity-loader="#{restrictedEntityLoader}" />
+<ui:jpa-entity-loader name="restrictedEntityLoader"
+ entity-manager="#{restrictedEntityManager}" />
+]]></programlisting>
+
+<programlisting><![CDATA[<h:selectOneMenu value="#{person.continent}">
+ <s:selectItems value="#{continents.resultList}"
+ var="continent" label="#{continent.name}" />
+ <f:converter converterId="standardEntityConverter" />
+</h:selectOneMenu>
+]]></programlisting>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{person.continent}" required="true">
+ <s:selectItems value="#{continents.resultList}" var="continent"
+ label="#{continent.name}" noSelectionLabel="Please Select..."/>
+ <s:convertEntity />
+</h:selectOneMenu>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:convertEnum>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Assigns an enum converter to the current component. This is primarily useful for radio button and dropdown controls.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{person.honorific}">
+ <s:selectItems value="#{honorifics}" var="honorific"
+ label="#{honorific.label}" noSelectionLabel="Please select" />
+ <s:convertEnum />
+</h:selectOneMenu>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:convertAtomicBoolean>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ <literal>javax.faces.convert.Converter</literal> for <literal>java.util.concurrent.atomic.AtomicBoolean</literal>.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting><![CDATA[<h:outputText value="#{item.valid}">
+ <s:convertAtomicBoolean />
+</h:outputText>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:convertAtomicInteger>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ <literal>javax.faces.convert.Converter</literal> for <literal>java.util.concurrent.atomic.AtomicInteger</literal>.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting><![CDATA[<h:outputText value="#{item.id}">
+ <s:convertAtomicInteger />
+</h:outputText>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:convertAtomicLong>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ <literal>javax.faces.convert.Converter</literal> for <literal>java.util.concurrent.atomic.AtomicLong</literal>.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting><![CDATA[<h:outputText value="#{item.id}">
+ <s:convertAtomicLong />
+</h:outputText>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:validateEquality>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Validates that an input control's parent's value is equal, or not equal, to the referenced control's value.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>for</literal> — The ID of a control to validate against.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>message</literal> — Message to show on failure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>required</literal> — False will disable a check that a value at all is inputted in fields.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>messageId</literal> — Message ID to show on failure.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>operator</literal> — The operator to use when comparing values. Valid operators are:
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>equal</literal> — validates that <literal>value.equals(forValue)</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>not_equal</literal> — validates that <literal>!value.equals(forValue)</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>greater</literal> — <![CDATA[validates that ((Comparable)value).compareTo(forValue) > 0]]>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>greater_or_equal</literal> — <![CDATA[validates that ((Comparable)value).compareTo(forValue) >= 0]]>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>less</literal> — <![CDATA[validates that ((Comparable)value).compareTo(forValue) < 0]]>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>less_or_equal</literal> — <![CDATA[validates that ((Comparable)value).compareTo(forValue) <= 0]]>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting><![CDATA[<h:inputText id="name" value="#{bean.name}"/>
+<h:inputText id="nameVerification" >
+ <s:validateEquality for="name" />
+</h:inputText>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:validate>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ A non-visual control that validates a JSF input field against the bound property with the Hibernate Validator.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:inputText id="userName" required="true" value="#{customer.userName}">
+ <s:validate />
+</h:inputText>
+<h:message for="userName" styleClass="error" />
+]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:validateAll>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ A non-visual control that validates all child JSF input fields against their bound properties with the Hibernate Validator.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:validateAll>
+ <div class="entry">
+ <h:outputLabel for="username">Username:</h:outputLabel>
+ <h:inputText id="username" value="#{user.username}" required="true"/>
+ <h:message for="username" styleClass="error" />
+ </div>
+ <div class="entry">
+ <h:outputLabel for="password">Password:</h:outputLabel>
<h:inputSecret id="password" value="#{user.password}"
- required="true"/>
- <h:message for="password" styleClass="error" />
- </div>
- <div class="entry">
- <h:outputLabel for="verify">Verify Password:</h:outputLabel>
+ required="true"/>
+ <h:message for="password" styleClass="error" />
+ </div>
+ <div class="entry">
+ <h:outputLabel for="verify">Verify Password:</h:outputLabel>
<h:inputSecret id="verify" value="#{register.verify}"
- required="true"/>
- <h:message for="verify" styleClass="error" />
- </div>
-</s:validateAll>]]></programlisting>
-
- </section>
-
- </section>
-
- <section>
- <title>Formatting</title>
-
- <section>
- <title><literal><s:decorate></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- "Decorate" a JSF input field when validation fails or when
- <literal>required="true"</literal> is set.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>template</literal> — the facelets template
- to use to decorate the component
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>enclose</literal> — if true, the template
- used to decorate the input field is enclosed by the
- element specified with the "element" attribute. By
- default this is a div element.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>element</literal> — the element to enclose
- the template used to decorate the input field. By default,
- the template is enclosed with a div element.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <literal>#{invalid}</literal> and <literal>#{required}</literal>
- are available inside <literal>s:decorate</literal>;
- <literal>#{required}</literal> evaluates to
- <literal>true</literal> if you have set the input component being
- decorated as required, and <literal>#{invalid}</literal>
- evaluates to <literal>true</literal> if a validation error occurs.
- </para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:decorate template="edit.xhtml">
- <ui:define name="label">Country:</ui:define>
- <h:inputText value="#{location.country}" required="true"/>
- </s:decorate>]]></programlisting>
- <programlisting role="XHTML"><![CDATA[<ui:composition xmlns="http://www.w3.org/1999/xhtml"
- xmlns:ui="http://java.sun.com/jsf/facelets"
- xmlns:h="http://java.sun.com/jsf/html"
- xmlns:f="http://java.sun.com/jsf/core"
- xmlns:s="http://jboss.com/products/seam/taglib">
-
- <div>
-
- <s:label styleClass="#{invalid?'error':''}">
- <ui:insert name="label"/>
- <s:span styleClass="required" rendered="#{required}">*</s:span>
- </s:label>
-
- <span class="#{invalid?'error':''}">
- <s:validateAll>
- <ui:insert/>
- </s:validateAll>
- </span>
-
- <s:message styleClass="error"/>
-
- </div>
-
-</ui:composition>]]></programlisting>
- </section>
-
- <section>
- <title><literal><s:div></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Render a HTML <literal><div></literal>.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:div rendered="#{selectedMember == null}">
- Sorry, but this member does not exist.
-</s:div>]]></programlisting>
- </section>
-
- <section>
- <title><literal><s:span></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Render a HTML <literal><span></literal>.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>title</literal> — Title for a span.
- </para>
- </listitem>
- </itemizedlist>
- </para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:span styleClass="required" rendered="#{required}" title="Small tooltip">*</s:span>]]></programlisting>
-
- </section>
-
- <section>
- <title><literal><s:fragment></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- A non-rendering component useful for enabling/disabling rendering
- of it's children.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:fragment rendered="#{auction.highBidder ne null}">
- Current bid:
-</s:fragment>]]></programlisting>
-
- </section>
-
- <section>
- <title><literal><s:label></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- "Decorate" a JSF input field with the label. The label is placed
- inside the HTML <literal><label></literal> tag, and is
- associated with the nearest JSF input component. It is often
- used with <literal><s:decorate></literal>.
- </para>
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>style</literal> — The control's style
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>styleClass</literal> — The control's style class
- </para>
- </listitem>
- </itemizedlist>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:label styleClass="label">
- Country:
-</s:label>
-<h:inputText value="#{location.country}" required="true"/>]]></programlisting>
- </section>
-
- <section>
- <title><literal><s:message></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- "Decorate" a JSF input field with the validation error message.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<f:facet name="afterInvalidField">
- <s:span>
-  Error: 
- <s:message/>
- </s:span>
-</f:facet>]]></programlisting>
-
- </section>
-
- </section>
-
- <section>
- <title>Seam Text</title>
-
- <section>
- <title><literal><s:validateFormattedText></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Checks that the submitted value is valid Seam Text
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <para>
- None.
- </para>
- </section>
-
- <section>
- <title><literal><s:formattedText></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Outputs <emphasis>Seam Text</emphasis>, a rich text markup useful
- for blogs, wikis and other applications that might use rich text.
- See the Seam Text chapter for full usage.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — an EL expression specifying
- the rich text markup to render.
- </para>
- </listitem>
- </itemizedlist>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:formattedText value="#{blog.text}"/>]]></programlisting>
-
- <para><emphasis>Example</emphasis></para>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/controls-seamtext.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/controls-seamtext.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- </section>
-
- </section>
-
- <section>
- <title>Form support</title>
-
- <section>
- <title><literal><s:token></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Produces a random token that is inserted into a hidden form field
- to help to secure JSF form posts against cross-site request
- forgery (XSRF) attacks. Note that the browser must have cookies
- enabled to submit forms that include this component.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>requireSession</literal> — indicates
- whether the session id should be included in the form
- signature, hence binding the token to the session. This
- value can be set to false if the "build before restore"
- mode of Facelets is activated (the default in JSF 2.0).
- (default: false)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>enableCookieNotice</literal> — indicates
- that a JavaScript check should be inserted into the page
- to verify that cookies are enabled in the browser. If
- cookies are not enabled, present a notice to the user that
- form posts will not work. (default: false)
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>allowMultiplePosts</literal> — indicates
- whether to allow the same form to be submitted multiple
- times with the same signature (as long as the view does
- not change). This is a common need if the form is perform
- Ajax calls but not rerendering itself or, at the very
- least, the UIToken component. The preferred approach is to
- have the UIToken component rerendered on any Ajax call
- where the UIToken component would be processed.
- (default: false)
- </para>
- </listitem>
- </itemizedlist>
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<h:form>
- <s:token enableCookieNotice="true" requireSession="false"/>
- ...
-</h:form>]]></programlisting>
- </section>
-
- <section>
- <title><literal><s:enumItem></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Creates a <literal>SelectItem</literal> from an enum value.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>enumValue</literal> — the string
- representation of the enum value.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>label</literal> — the label to be used when
- rendering the <literal>SelectItem</literal>.
- </para>
- </listitem>
- </itemizedlist>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<h:selectOneRadio id="radioList"
- layout="lineDirection"
- value="#{newPayment.paymentFrequency}">
+ required="true"/>
+ <h:message for="verify" styleClass="error" />
+ </div>
+</s:validateAll>
+]]></programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Formatting</title>
+ <section>
+ <title><literal><![CDATA[<s:decorate>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ "Decorates" a JSF input field when validation fails or when <literal>required="true"</literal> is set.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>template</literal> — the Facelets template used to decorate the component.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>enclose</literal> — if <literal>true</literal>, the template used to decorate the input field is enclosed by the element specified with the "element" attribute. (By default, this is a <literal>div</literal> element.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>element</literal> — the element enclosing the template that decorates the input field. By default, the template is enclosed with a <literal>div</literal> element.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <literal>#{invalid}</literal> and <literal>#{required}</literal> are available inside <literal>s:decorate</literal>. <literal>#{required}</literal> evaluates to <literal>true</literal> if the input component being decorated is set to <literal>required</literal>. <literal>#{invalid}</literal> evaluates to <literal>true</literal> if a validation error occurs.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:decorate template="edit.xhtml">
+ <ui:define name="label">Country:</ui:define>
+ <h:inputText value="#{location.country}" required="true"/>
+</s:decorate>]]>
+</programlisting>
+
+<programlisting role="XHTML"><![CDATA[<ui:composition xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:ui="http://java.sun.com/jsf/facelets"
+ xmlns:h="http://java.sun.com/jsf/html"
+ xmlns:f="http://java.sun.com/jsf/core"
+ xmlns:s="http://jboss.com/products/seam/taglib">
+ <div>
+ <s:label styleClass="#{invalid?'error':''}">
+ <ui:insert name="label"/>
+ <s:span styleClass="required" rendered="#{required}">*</s:span>
+ </s:label>
+ <span class="#{invalid?'error':''}">
+ <s:validateAll>
+ <ui:insert/>
+ </s:validateAll>
+ </span>
+ <s:message styleClass="error"/>
+ </div>
+</ui:composition>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:div>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Renders a HTML <literal><![CDATA[<div>]]></literal>.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:div rendered="#{selectedMember == null}">
+ Sorry, but this member does not exist.
+</s:div>
+ ]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:span>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Renders a HTML <literal><![CDATA[<span>]]></literal>.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>title</literal> — Title for a span.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:span styleClass="required" rendered="#{required}" title="Small tooltip">
+ *
+</s:span>
+ ]]></programlisting>
+ <!-- TSUZUKERU -->
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:fragment>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ A non-rendering component useful for enabling/disabling rendering of it's children.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:fragment rendered="#{auction.highBidder ne null}">
+ Current bid:
+</s:fragment>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:label>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ "Decorates" a JSF input field with the label. The label is placed inside the HTML <literal><![CDATA[<label>]]></literal> tag, and is associated with the nearest JSF input component. It is often used with <literal><![CDATA[<s:decorate>]]></literal>.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>style</literal> — The control's style.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>styleClass</literal> — The control's style class.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:label styleClass="label"> Country: </s:label>
+<h:inputText value="#{location.country}" required="true"/>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:message>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ "Decorates" a JSF input field with the validation error message.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<f:facet name="afterInvalidField">
+ <s:span>
+ Error:
+ <s:message/>
+ </s:span>
+</f:facet>]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Seam Text</title>
+ <section>
+ <title><literal><![CDATA[<s:validateFormattedText>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Checks that the submitted value is valid Seam Text.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <para>
+ None.
+ </para>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:formattedText>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Outputs <emphasis>Seam Text</emphasis>, a rich text markup useful for blogs, wikis and other applications that might use rich text. See the Seam Text chapter for full usage.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — an EL expression specifying the rich text markup to render.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:formattedText value="#{blog.text}"/>]]>
+</programlisting>
+ <para>
+ <emphasis>Example</emphasis>
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/controls-seamtext.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/controls-seamtext.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Form support</title>
+ <section>
+ <title><literal><![CDATA[<s:token>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Produces a random token to insert into a hidden form field in order to secure JSF form posts against Cross-Site Request Forgery (XSRF) attacks. The browser must have cookies enabled to submit forms that include this component.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>requireSession</literal> — indicates whether the session ID should be included in the form signature to bind the token to the session. The default value is <literal>false</literal>, but this should only be used if Facelets is in "build before restore" mode. ("Build before restore" is the default mode in JSF 2.0.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>enableCookieNotice</literal> — indicates that a JavaScript check should be inserted into the page to verify that cookies are enabled in the browser. If cookies are not enabled, present a notice to the user that form posts will not work. The default value is <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>allowMultiplePosts</literal> — indicates whether the same form is allowed to submit multiple times with the same signature (where the view has not changed). This is often required when the form is performing AJAX calls without rerendering itself or the UIToken component. It is better to rerender the UIToken component upon any AJAX call where the UIToken component would be processed. The default value is <literal>false</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:form>
+ <s:token enableCookieNotice="true" requireSession="false"/>
+ ...
+</h:form>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:enumItem>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Creates a <literal>SelectItem</literal> from an enum value.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>enumValue</literal> — the string representation of the enum value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>label</literal> — the label to be used when rendering the <literal>SelectItem</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:selectOneRadio id="radioList"
+ layout="lineDirection"
+ value="#{newPayment.paymentFrequency}">
<s:convertEnum />
<s:enumItem enumValue="ONCE" label="Only Once" />
<s:enumItem enumValue="EVERY_MINUTE" label="Every Minute" />
<s:enumItem enumValue="HOURLY" label="Every Hour" />
<s:enumItem enumValue="DAILY" label="Every Day" />
<s:enumItem enumValue="WEEKLY" label="Every Week" />
-</h:selectOneRadio>]]></programlisting>
- </section>
-
- <section>
- <title><literal><s:selectItems></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Creates a <literal>List<SelectItem></literal> from a List, Set, DataModel or Array.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — an EL expression
- specifying the data that backs the
- <literal>List<SelectItem></literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>var</literal>— defines the name of the local
- variable that holds the current object during iteration
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>label</literal> — the label to be used when
- rendering the <literal>SelectItem</literal>. Can reference
- the <literal>var</literal> variable.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>itemValue</literal> — Value to return to the
- server if this option is selected. Optional, by default the
- <literal>var</literal> object is used. Can reference the
- <literal>var</literal> variable.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>disabled</literal>
- — if true the <literal>SelectItem</literal> will be
- rendered disabled. Can reference the <literal>var</literal>
- variable.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>noSelectionLabel</literal> — specifies the
- (optional) label to place at the top of list (if
- <literal>required="true"</literal> is also specified then
- selecting this value will cause a validation error).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>hideNoSelectionLabel</literal> — if true,
- the <literal>noSelectionLabel</literal> will be hidden when
- a value is selected
- </para>
- </listitem>
- </itemizedlist>
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{person.age}"
- converter="ageConverter">
- <s:selectItems value="#{ages}" var="age" label="#{age}" />
-</h:selectOneMenu>]]></programlisting>
- </section>
-
- <section>
- <title><literal><s:fileUpload></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Renders a file upload control. This control must be used within
- a form with an encoding type of
- <literal>multipart/form-data</literal>, i.e:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:form enctype="multipart/form-data">]]></programlisting>
-
- <para>
- For multipart requests, the Seam Multipart servlet filter must
- also be configured in <literal>web.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<filter>
- <filter-name>Seam Filter</filter-name>
- <filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
-</filter>
-
-<filter-mapping>
- <filter-name>Seam Filter</filter-name>
- <url-pattern>/*</url-pattern>
-</filter-mapping>]]></programlisting>
-
- <para><emphasis>Configuration</emphasis></para>
-
- <para>
- The following configuration options for multipart requests may be
- configured in components.xml:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>createTempFiles</literal> — if this option
- is set to true, uploaded files are streamed to a temporary
- file instead of in memory.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>maxRequestSize</literal> — the maximum size
- of a file upload request, in bytes.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Here's an example:
- </para>
-
- <programlisting role="XML"><![CDATA[<component class="org.jboss.seam.web.MultipartFilter">
- <property name="createTempFiles">true</property>
- <property name="maxRequestSize">1000000</property>
-</component>]]></programlisting>
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>data</literal> — this value binding receives
- the binary file data. The receiving field should be
- declared as a <literal>byte[]</literal> or
- <literal>InputStream</literal> (required).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>contentType</literal> — this value binding
- receives the file's content type (optional).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fileName</literal> — this value binding
- receives the filename (optional).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fileSize</literal> — this value binding
- receives the file size (optional).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>accept</literal> — a comma-separated list of
- content types to accept, may not be supported by the
- browser. E.g. <literal>"images/png,images/jpg"</literal>,
- <literal>"images/*"</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>style</literal> — The control's style
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>styleClass</literal> — The control's style
- class
- </para>
- </listitem>
- </itemizedlist>
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:fileUpload id="picture" data="#{register.picture}"
- accept="image/png"
+</h:selectOneRadio>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:selectItems>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Creates a <literal>List<![CDATA[<SelectItem>]]></literal> from a List, Set, DataModel or Array.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — an EL expression specifying the data that backs the <literal>List<![CDATA[SelectItem>]]></literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>var</literal> — defines the name of the local variable that holds the current object during iteration.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>label</literal> — the label to be used when rendering the <literal>SelectItem</literal>. Can reference the <literal>var</literal> variable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>itemValue</literal> — specifies the value to return to the server if this option is selected. This is an optional attribute. If included, <literal>var</literal> is the default object used. Can reference the <literal>var</literal> variable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disabled</literal> — if this is set to <literal>true</literal>, the <literal>SelectItem</literal> will be rendered disabled. Can reference the <literal>var</literal> variable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>noSelectionLabel</literal> — specifies the (optional) label to place at the top of list. If <literal>required="true"</literal> is also specified then selecting this value will cause a validation error.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>hideNoSelectionLabel</literal> — if true, the <literal>noSelectionLabel</literal> will be hidden when a value is selected.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{person.age}" converter="ageConverter">
+ <s:selectItems value="#{ages}" var="age" label="#{age}" />
+</h:selectOneMenu>
+]]></programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:fileUpload>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Renders a file upload control. This control must be used within a form with an encoding type of <literal>multipart/form-data</literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:form enctype="multipart/form-data">
+]]></programlisting>
+ <para>
+ For multipart requests, the Seam Multipart servlet filter must also be configured in <filename>web.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<filter>
+ <filter-name>Seam Filter</filter-name>
+ <filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
+</filter>
+<filter-mapping>
+ <filter-name>Seam Filter</filter-name>
+ <url-pattern>/*</url-pattern>
+</filter-mapping>]]>
+</programlisting>
+ <para>
+ <emphasis>Configuration</emphasis>
+ </para>
+ <para>
+ The following configuration options for multipart requests can be configured in <literal>components.xml</literal>:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>createTempFiles</literal> — if this option is set to <literal>true</literal>, uploaded files are streamed to a temporary file rather than being held in memory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>maxRequestSize</literal> — the maximum size of a file upload request, in bytes.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Here's an example:
+ </para>
+
+<programlisting role="XML"><![CDATA[<component class="org.jboss.seam.web.MultipartFilter">
+ <property name="createTempFiles">true</property>
+ <property name="maxRequestSize">1000000</property>
+</component>]]>
+</programlisting>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>data</literal> — specifies the value binding that receives the binary file data. The receiving field must be declared as either a <literal>byte[]</literal> or <literal>InputStream</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>contentType</literal> — an optional attribute specifying the value binding that receives the file's content type.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fileName</literal> — an optional attribute specifying the value binding that receives the filename.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fileSize</literal> — an optional attribute specifying the value binding that receives the file size.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>accept</literal> — a comma-separated list of acceptable content types, for example, <literal>"images/png,images/jpg"</literal>, <literal>"images/*"</literal>. The types listed may not be supported by the browser.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>style</literal> — The control's style.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>styleClass</literal> — The control's style class.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:fileUpload id="picture"
+ data="#{register.picture}" accept="image/png"
contentType="#{register.pictureContentType}" />]]></programlisting>
-
- </section>
-
- </section>
-
- <section>
- <title>Other</title>
-
- <section>
- <title><literal><s:cache></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Cache the rendered page fragment using JBoss Cache. Note that
- <literal><s:cache></literal> actually uses the instance
- of JBoss Cache managed by the built-in
- <literal>pojoCache</literal> component.
- </para>
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>key</literal> — the key to cache rendered
- content, often a value expression. For example, if we were
- caching a page fragment that displays a document, we might
- use <literal>key="Document-#{document.id}"</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>enabled</literal> — a value expression that
- determines if the cache should be used.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>region</literal> — a JBoss Cache node to use
- (different nodes can have different expiry policies).
- </para>
- </listitem>
- </itemizedlist>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:cache key="entry-#{blogEntry.id}" region="pageFragments">
+ </section>
+
+ </section>
+
+ <section>
+ <title>Other</title>
+ <section>
+ <title><literal><![CDATA[<s:cache>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Caches the rendered page fragment using JBoss Cache. Note that <literal><![CDATA[<s:cache>]]></literal> actually uses the instance of JBoss Cache managed by the built-in <literal>pojoCache</literal> component.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>key</literal> — the key to cache rendered content, often a value expression. For example, if we were caching a page fragment that displays a document, we might use <literal>key="Document-#{document.id}"</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>enabled</literal> — a value expression that determines whether the cache should be used.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>region</literal> — specifies the JBoss Cache node to use. Different nodes can have different expiry policies.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:cache key="entry-#{blogEntry.id}" region="pageFragments">
<div class="blogEntry">
<h3>#{blogEntry.title}</h3>
<div>
@@ -1195,337 +1146,301 @@
<p>
[Posted on 
<h:outputText value="#{blogEntry.date}">
- <f:convertDateTime timezone="#{blog.timeZone}" locale="#{blog.locale}"
- type="both"/>
+ <f:convertDateTime timezone="#{blog.timeZone}"
+ locale="#{blog.locale}" type="both"/>
</h:outputText>]
</p>
</div>
-</s:cache>]]></programlisting>
-
- </section>
-
-
- <section>
- <title><literal><s:resource></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- A tag that acts a file download provider. It must be alone in the JSF page.
- To be able to use this contol, web.xml must be set up as follows.
- </para>
-
- <para><emphasis>Configuration</emphasis></para>
+</s:cache>
+]]></programlisting>
+ </section>
- <programlisting role="XML"><![CDATA[<servlet>
- <servlet-name>Document Store Servlet</servlet-name>
- <servlet-class>org.jboss.seam.document.DocumentStoreServlet</servlet-class>
-</servlet>
-<servlet-mapping>
- <servlet-name>Document Store Servlet</servlet-name>
- <url-pattern>/seam/docstore/*</url-pattern>
+ <section>
+ <title><literal><![CDATA[<s:resource>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ A tag that acts as a file download provider. It must be alone in the JSF page. To use this control, you must configure <literal>web.xml</literal> as follows:
+ </para>
+ <para>
+ <emphasis>Configuration</emphasis>
+ </para>
+
+<programlisting role="XML"><![CDATA[<servlet>
+ <servlet-name>Document Store Servlet</servlet-name>
+ <servlet-class>
+ org.jboss.seam.document.DocumentStoreServlet
+ </servlet-class>
+</servlet>
+<servlet-mapping>
+ <servlet-name>Document Store Servlet</servlet-name>
+ <url-pattern>/seam/docstore/*</url-pattern>
</servlet-mapping>
]]></programlisting>
-
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>data</literal> — Data that should be downloaded.
- May be a java.util.File, an InputStream or a byte array.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fileName</literal> — Filename of the file to be served
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>contentType</literal> — content type of the file to be downloaded
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>disposition</literal> — disposition to use. Default is inline
- </para>
- </listitem>
- </itemizedlist>
-
- <para><emphasis>Usage</emphasis></para>
- <para>Here is an example on how to use the tag:</para>
- <programlisting role="XHTML"><![CDATA[<s:resource xmlns="http://www.w3.org/1999/xhtml"
- xmlns:s="http://jboss.com/products/seam/taglib"
- data="#{resources.data}"
- contentType="#{resources.contentType}"
- fileName="#{resources.fileName}" />
-]]></programlisting>
-
- <para>The bean named <literal>resources</literal> is some backing bean that given
- some request parameters servers a specific file, see <literal>s:download</literal>.</para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>data</literal> — specifies data that should be downloaded. May be a java.util.File, an InputStream or a byte array.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fileName</literal> — the filename of the file to be served.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>contentType</literal> — the content type of the file to be downloaded.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>disposition</literal> — the disposition to use. The default disposition is <literal>inline</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ <para>
+ The tag is used as follows:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:resource xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:s="http://jboss.com/products/seam/taglib"
+ data="#{resources.data}" contentType="#{resources.contentType}"
+ fileName="#{resources.fileName}" />
+ ]]></programlisting>
+ <para>
+ Here, the bean named <literal>resources</literal> is some backing bean that, given some request parameters, serves a specific file — see <literal>s:download</literal>.
+ </para>
</section>
-
- <section>
- <title><literal><s:download></literal></title>
- <para><emphasis>Description</emphasis></para>
- <para>Builds a RESTful link to a <literal><s:resource></literal>.
- Nested <literal>f:param</literal> build up the url.
- </para>
-
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>src</literal> — Resource file serving files.
- </para>
- </listitem>
- </itemizedlist>
-
- <para><emphasis>Attributes</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:download src="/resources.xhtml">
- <f:param name="fileId" value="#{someBean.downloadableFileId}"/>
-</s:download>]]></programlisting>
-
- <para>
- Will produce something like:
- <literal><![CDATA[http://localhost/resources.seam?fileId=1]]></literal>
- </para>
- </section>
-
- <section>
- <title><literal><s:graphicImage></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- An extended <literal><h:graphicImage></literal> that allows
- the image to be created in a Seam Component; further transforms
- can be applied to the image.
- </para>
- <para>
- All attributes for <literal><h:graphicImage></literal> are
- supported, as well as:
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — image to display. Can be
- a path <literal>String</literal> (loaded from the
- classpath), a <literal>byte[]</literal>, a
- <literal>java.io.File</literal>, a
- <literal>java.io.InputStream</literal> or a
- <literal>java.net.URL</literal>. Currently supported image
- formats are <literal>image/png</literal>,
- <literal>image/jpeg</literal> and
- <literal>image/gif</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fileName</literal> — if not specified the
- served image will have a generated file name. If you want
- to name your file, you should specify it here. This name
- should be unique
- </para>
- </listitem>
- </itemizedlist>
-
- <para><emphasis>Transformations</emphasis></para>
- <para>
- To apply a transform to the image, you would nest a tag
- specifying the transform to apply. Seam currently supports these
- transforms:
- </para>
- <variablelist>
- <varlistentry>
- <term>
- <literal><s:transformImageSize></literal>
- </term>
- <listitem>
- <itemizedlist>
- <listitem>
- <para>
- <literal>width</literal> — new width of the
- image
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>height</literal> — new height of the
- image
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>maintainRatio</literal> — if
- <literal>true</literal>, and
- <emphasis>one</emphasis> of
- <literal>width</literal>/<literal>height</literal>
- are specified, the image will be resized with the
- dimension not specified being calculated to
- maintain the aspect ratio.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>factor</literal> — scale the image
- by the given factor
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal><s:transformImageBlur></literal>
- </term>
- <listitem>
- <itemizedlist>
- <listitem>
- <para>
- <literal>radius</literal> — perform a
- convolution blur with the given radius
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal><s:transformImageType></literal>
- </term>
- <listitem>
- <itemizedlist>
- <listitem>
- <para>
- <literal>contentType</literal> — alter the
- type of the image to either
- <literal>image/jpeg</literal> or
- <literal>image/png</literal>
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
-
- <para>
- It's easy to create your own transform - create a
- <literal>UIComponent</literal> which implements
- <literal>org.jboss.seam.ui.graphicImage.ImageTransform</literal>.
- Inside the <literal>applyTransform()</literal>method use
- <literal>image.getBufferedImage()</literal> to get the original
- image and <literal>image.setBufferedImage()</literal> to set your
- transformed image. Transforms are applied in the order specified
- in the view.
- </para>
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:graphicImage rendered="#{auction.image ne null}"
- value="#{auction.image.data}">
- <s:transformImageSize width="200" maintainRatio="true"/>
-</s:graphicImage>]]></programlisting>
- </section>
-
- <section>
- <title><literal><s:remote></literal></title>
-
- <para><emphasis>Description</emphasis></para>
- <para>
- Generates the Javascript stubs required to use Seam Remoting.
- </para>
-
- <para><emphasis>Attributes</emphasis></para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>include</literal> — a comma-separated list
- of the component names (or fully qualified class names)for
- which to generate Seam Remoting Javascript stubs. See
- <xref linkend="remoting"/> for more details.
- </para>
- </listitem>
- </itemizedlist>
-
- <para><emphasis>Usage</emphasis></para>
- <programlisting role="XHTML"><![CDATA[<s:remote include="customerAction,accountAction,com.acme.MyBean"/>]]></programlisting>
- </section>
- </section>
- </section>
-
-
- <section id="controls.annotations">
- <title>Annotations</title>
-
- <para>
- Seam also provides annotations to allow you to use Seam components as JSF
- converters and validators:
-
- </para>
- <variablelist>
- <varlistentry>
- <term>
- <literal>@Converter</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Name("itemConverter")
+
+ <section>
+ <title><literal><![CDATA[<s:download>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Builds a RESTful link to a <literal><![CDATA[<s:resource>]]></literal>. Nested <literal>f:param</literal> build up the url.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>src</literal> — Resource file serving files.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:download src="/resources.xhtml">
+ <f:param name="fileId" value="#{someBean.downloadableFileId}"/>
+</s:download>
+]]></programlisting>
+ <para>
+ This produces a link of a similar form to the following: <literal><![CDATA[http://localhost/resources.seam?fileId=1]]></literal>
+ </para>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:graphicImage>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ An extended <literal><![CDATA[<h:graphicImage>]]></literal> that allows the image to be created in a Seam Component. It is possible to transform the image further.
+ </para>
+ <para>
+ All <literal><![CDATA[<h:graphicImage>]]></literal> attributes are supported, in addition to:
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — specifies the image to display. Can be a path <literal>String</literal> (loaded from the classpath), a <literal>byte[]</literal>, a <literal>java.io.File</literal>, a <literal>java.io.InputStream</literal> or a <literal>java.net.URL</literal>. Currently supported image formats are <literal>image/png</literal>, <literal>image/jpeg</literal> and <literal>image/gif</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fileName</literal> — specifies the filename of the image. This name should be unique. If left unspecified, a unique filename will be generated for the image.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Transformations</emphasis>
+ </para>
+ <para>
+ To transform the image, nest a tag specifying which transformation to apply. Seam currently supports the following transformation tags:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term> <literal><![CDATA[<s:transformImageSize>]]></literal> </term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>width</literal> — specifies the new width of the image.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>height</literal> — specifies the new height of the image.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>maintainRatio</literal> — if <literal>true</literal>, and one of either <literal>width</literal> or <literal>height</literal> is specified, the image will be resized to maintain the <literal>height</literal>:<literal>width</literal> aspect ratio.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>factor</literal> — scales the image by the specified factor.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <literal><![CDATA[<s:transformImageBlur>]]></literal> </term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>radius</literal> — performs a convolution blur with the specified radius.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <literal><![CDATA[<s:transformImageType>]]></literal> </term>
+ <listitem>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>contentType</literal> — alters the image type to either <literal>image/jpeg</literal> or <literal>image/png</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ You can also create your own image transformation. Create a <literal>UIComponent</literal> that implements <literal>org.jboss.seam.ui.graphicImage.ImageTransform</literal>. Inside the <literal>applyTransform()</literal>method, use <literal>image.getBufferedImage()</literal> to get the original image and <literal>image.setBufferedImage()</literal> to set your transformed image. Transforms are applied in the order specified in the view.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:graphicImage rendered="#{auction.image ne null}"
+ value="#{auction.image.data}">
+ <s:transformImageSize width="200" maintainRatio="true"/>
+</s:graphicImage>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title><literal><![CDATA[<s:remote>]]></literal></title>
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Generates the Javascript stubs required to use Seam Remoting.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>include</literal> — a comma-separated list of the component names (or fully qualified class names) for which to generate Seam Remoting Javascript stubs. See <xref linkend="remoting" /> for more details.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:remote include="customerAction,accountAction,com.acme.MyBean"/>]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ </section>
+
+ <section id="controls.annotations">
+ <title>Annotations</title>
+ <para>
+ Seam also provides annotations to let you use Seam components as JSF converters and validators:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term> <literal>@Converter</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Name("itemConverter")
@BypassInterceptors
- at Converter
-public class ItemConverter implements Converter {
-
- @Transactional
- public Object getAsObject(FacesContext context, UIComponent cmp, String value) {
- EntityManager entityManager = (EntityManager) Component.getInstance("entityManager");
- entityManager.joinTransaction();
- // Do the conversion
- }
-
- public String getAsString(FacesContext context, UIComponent cmp, Object value) {
- // Do the conversion
- }
-
-}]]></programlisting>
-
- <programlisting role="XHTML"><![CDATA[<h:inputText value="#{shop.item}" converter="itemConverter" />]]></programlisting>
-
- <para>
- Registers the Seam component as a JSF converter. Shown here is a
- converter which is able to access the JPA EntityManager inside a
- JTA transaction, when converting the value back to it's object
- representation.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>
- <literal>@Validator</literal>
- </term>
- <listitem>
- <programlisting role="JAVA"><![CDATA[@Name("itemValidator")
+ at Converter
+public class ItemConverter implements Converter {
+ @Transactional
+ public Object getAsObject(FacesContext context, UIComponent cmp,
+ String value) {
+ EntityManager entityManager =
+ (EntityManager) Component.getInstance("entityManager");
+ entityManager.joinTransaction(); // Do the conversion
+ }
+ public String getAsString(FacesContext context, UIComponent cmp,
+ Object value) {
+ // Do the conversion
+ }
+}
+]]></programlisting>
+
+<programlisting role="XHTML"><![CDATA[<h:inputText value="#{shop.item}" converter="itemConverter" />]]>
+</programlisting>
+ <para>
+ Registers the Seam component as a JSF converter. Here, the converter accesses the JPA EntityManager inside a JTA transaction when converting the value back to its object representation.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term> <literal>@Validator</literal> </term>
+ <listitem>
+
+<programlisting role="JAVA"><![CDATA[@Name("itemValidator")
@BypassInterceptors
- at org.jboss.seam.annotations.faces.Validator
-public class ItemValidator implements javax.faces.validator.Validator {
-
- public void validate(FacesContext context, UIComponent cmp, Object value)
- throws ValidatorException {
- ItemController ItemController = (ItemController) Component.getInstance("itemController");
- boolean valid = itemController.validate(value);
- if (!valid) {
- throw ValidatorException("Invalid value " + value);
- }
- }
-}]]></programlisting>
-
- <programlisting role="XHTML"><![CDATA[<h:inputText value="#{shop.item}" validator="itemValidator" />]]></programlisting>
- <para>
- Registers the Seam component as a JSF validator. Shown here is a
- validator which injects another Seam component; the injected
- component is used to validate the value.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
-
-
+ at org.jboss.seam.annotations.faces.Validator
+public class ItemValidator implements javax.faces.validator.Validator {
+ public void validate(FacesContext context, UIComponent cmp,
+ Object value) throws ValidatorException {
+ ItemController ItemController =
+ (ItemController) Component.getInstance("itemController");
+ boolean valid = itemController.validate(value);
+ if (!valid) {
+ throw ValidatorException("Invalid value " + value);
+ }
+ }
+}
+]]></programlisting>
+
+<programlisting role="XHTML"><![CDATA[<h:inputText value="#{shop.item}" validator="itemValidator" />
+]]></programlisting>
+ <para>
+ Registers the Seam component as a JSF validator. Here, the validator injects another Seam component; the injected component is used to validate the value.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Conversations.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Conversations.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Conversations.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,1352 +1,976 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-
-
-<chapter id="conversations">
- <title>Conversations and workspace management</title>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<!-- This Chapter has been checked on 04 November 2009 that it reflects JBPAPP_5_0-CR5
+ sourced from:
+ https://svn.jboss.org/repos/seam/tags/JBPAPP_5_0-CR5/doc/Seam_Reference_Guide/en-US
+ The chapter was previously updated.
+-->
+<chapter id="conversations" >
+ <title>Conversations and workspace management</title>
+ <para>
+ Now we will take you through Seam's conversation model in finer detail.
+ </para>
+ <para>
+ The notion of a Seam <emphasis>conversation</emphasis> came about as a combination of three separate concepts:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ the concept of a <emphasis>workspace</emphasis>, and effective workspace management.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the concept of an <emphasis>application transaction</emphasis> with optimistic semantics. Existing frameworks, based around a stateless architecture, were unable to provide effective management of extended persistence contexts.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the concept of a workflow <emphasis>task</emphasis>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ By unifying these ideas and providing deep support in the framework, we have created a powerful construct that allows for richer and more efficient applications, using less verbose code.
+ </para>
+ <section>
+ <title>Seam's conversation model</title>
+ <para>
+ All examples so far operate under a simple conversation model with the following rules:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A conversation context is always active during the apply request values, process validation, update model values, invoke application and render response phases of the JSF request lifecycle.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ At the end of the restore view phase of the JSF request lifecycle, Seam attempts to restore any previous long-running conversation context. If none exists, Seam creates a new temporary conversation context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When a <literal>@Begin</literal> method is encountered, the temporary conversation context is promoted to a long-running conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When an <literal>@End</literal> method is encountered, any long-running conversation context is demoted to a temporary conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ At the end of the render response phase of the JSF request lifecycle, Seam either stores the contents of a long-running conversation context, or destroys the contents of a temporary conversation context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Any Faces request (a JSF postback) will propagate the conversation context. By default, non-Faces requests (GET requests, for example) do not propagate the conversation context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If the JSF request lifecycle is foreshortened by a redirect, Seam transparently stores and restores the current conversation context, unless the conversation was already ended via <literal>@End(beforeRedirect=true)</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Seam transparently propagates the conversation context (including the temporary conversation context) across JSF postbacks and redirects. Withou special additions, a <emphasis>non-Faces request</emphasis> (a GET request, for example) will not propagate the conversation context, and will be processed in a new temporary conversation. This is usually — but not always — the desired behavior.
+ </para>
+ <para>
+ To propagate a Seam conversation across a non-Faces request, the Seam <emphasis>conversation ID</emphasis> must be explicitly coded as a request parameter:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<a href="main.jsf?#{manager.conversationIdParameter}=#{conversation.id}">
+ Continue
+</a>]]>
+</programlisting>
+ <para>
+ Or, for JSF:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:outputLink value="main.jsf">
+ <f:param name="#{manager.conversationIdParameter}"
+ value="#{conversation.id}"/>
+ <h:outputText value="Continue"/>
+</h:outputLink>]]>
+</programlisting>
+ <para>
+ If you use the Seam tag library, this is equivalent:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:outputLink value="main.jsf">
+ <s:conversationId/>
+ <h:outputText value="Continue"/>
+</h:outputLink>]]>
+</programlisting>
+ <para>
+ The code to disable propagation of the conversation context for a postback is similar:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Exit">
+ <f:param name="conversationPropagation" value="none"/>
+</h:commandLink>]]>
+</programlisting>
+ <para>
+ The equivalent for the Seam tag library is:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Exit">
+ <s:conversationPropagation type="none"/>
+</h:commandLink>]]>
+</programlisting>
+ <note>
+ <para>
+ Disabling conversation context propagation is <emphasis>not</emphasis> the same as ending the conversation.
+ </para>
+ </note>
+ <para>
+ The <literal>conversationPropagation</literal> request parameter or <literal><![CDATA[<s:conversationPropagation>]]></literal> tag can also be used to begin and end conversations, or to begin a nested conversation.
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Exit">
+ <s:conversationPropagation type="end"/>
+</h:commandLink>]]>
+</programlisting>
+
+<programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Select Child">
+ <s:conversationPropagation type="nested"/>
+</h:commandLink>]]>
+</programlisting>
+
+<programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Select Hotel">
+ <s:conversationPropagation type="begin"/>
+</h:commandLink>]]>
+</programlisting>
+
+<programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Select Hotel">
+ <s:conversationPropagation type="join"/>
+</h:commandLink>]]>
+</programlisting>
+ <para>
+ This conversation model makes it easy to build applications which behave correctly with respect to multi-window operation. For many applications, this is all that is required. Some complex applications have one or both of the following additional requirements:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ A conversation spans many smaller units of user interaction, which execute serially or even concurrently. The smaller <emphasis>nested conversations</emphasis> have their own isolated set of conversation state, and have access to the state of the outer conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The user can switch between many conversations within the same browser window. This feature is called <emphasis>workspace management</emphasis>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Nested conversations</title>
+ <para>
+ A nested conversation is created by invoking a method marked <literal>@Begin(nested=true)</literal> within the scope of an existing conversation. A nested conversation has its own conversation context, but can read values from the outer conversation's context. The outer conversation's context is read-only within a nested conversation, but because objects are obtained by reference, changes to the objects themselves will be reflected in the outer context.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Nesting a conversation initializes a context that is stacked on the context of the original, or outer, conversation. The outer conversation is considered the parent.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Any values outjected or set directly into the nested conversation’s context do not affect the objects accessible in the parent conversation’s context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Injection, or a context lookup from the conversation context, will first look up the value in the current conversation context. If no value is found, lookup will continue down the conversation stack, if the conversation is nested. This behavior can be overridden.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ When an <literal>@End</literal> is subsequently encountered, the nested conversation will be destroyed, and the outer conversation will resume, <emphasis>popping</emphasis> the conversation stack. Conversations may be nested to any arbitrary depth.
+ </para>
+ <para>
+ Certain user activities (workspace management, or the back button) can cause the outer conversation to be resumed before the inner conversation ends. In this case, it is possible to have multiple concurrent nested conversations belonging to the same outer conversation. If the outer conversation ends before a nested conversation ends, Seam destroys all nested conversation contexts along with the outer context.
+ </para>
+ <para>
+ The conversation at the bottom of the conversation stack is the root conversation. Destroying this conversation will always destroy all descendent conversations. You can achieve this declaratively by specifying <literal>@End(root=true)</literal>.
+ </para>
+ <para>
+ A conversation can be thought of as a <emphasis>continuable state</emphasis>. Nested conversations allow the application to capture a consistent continuable state at various points in a user interaction, thus ensuring truly correct behavior in the face of backbuttoning and workspace management.
+ </para>
+ <para>
+ As mentioned previously, if a component exists in a parent conversation of the current nested conversation, the nested conversation will use the same instance. Occasionally, it is useful to have a different instance in each nested conversation, so that the component instance that of the parent conversation is invisible to its child conversations. You can achieve this behavior by annotating the component <literal>@PerNestedConversation</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Starting conversations with GET requests</title>
+ <para>
+ JSF does not define any action listener triggered when a page is accessed via a non-Faces request (a HTTP GET request, for example). This can occur when a user bookmarks the page, or navigates to the page via an <literal><![CDATA[<h:outputLink>]]></literal>.
+ </para>
+ <para>
+ Sometimes we want a conversation to begin immediately the page is accessed. Since there is no JSF action method, we cannot annotate the action with <literal>@Begin</literal>.
+ </para>
+ <para>
+ Further problems arise when the page requires state to be fetched into a context variable. We have already seen two methods of solving this problem. If the state is held in a Seam component, we can fetch the state in a <literal>@Create</literal> method. If not, we can define a <literal>@Factory</literal> method for the context variable.
+ </para>
+ <para>
+ If neither option works for you, Seam lets you define a <emphasis>page action</emphasis> in the <filename>pages.xml</filename> file.
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/messageList.jsp" action="#{messageManager.list}"/>
+ ...
+</pages>]]>
+</programlisting>
+ <para>
+ This action method is called at the beginning of the render response phase — that is, any time the page is about to be rendered. If a page action returns a non-null outcome, Seam will process any appropriate JSF and Seam navigation rules. This can result in a completely different page rendering.
+ </para>
+ <para>
+ If beginning a conversation is <emphasis>all</emphasis> you want to do before rendering the page, you can use a built-in action method:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/messageList.jsp" action="#{conversation.begin}"/>
+ ...
+</pages>]]>
+</programlisting>
+ <para>
+ You can also call this built-in action from a JSF control, and that <literal>#{conversation.end}</literal> similarly ends conversations.
+ </para>
+ <para>
+ The <literal><![CDATA[<begin-conversation>]]></literal> element can be used as follows for further control over joining existing conversations, or beginning a nested converstion, a pageflow, or an atomic conversation.
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/messageList.jsp">
+ <begin-conversation nested="true" pageflow="AddItem"/>
+ <page>
+ ...
+</pages>
+]]></programlisting>
+ <para>
+ There is also an <literal><![CDATA[<end-conversation>]]></literal> element.
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/home.jsp">
+ <end-conversation/>
+ <page>
+ ...
+</pages>]]>
+</programlisting>
+ <para>
+ We now have five options to begin a conversation immediately the page is accessed:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Annotate the <literal>@Create</literal> method with <literal>@Begin</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Annotate the <literal>@Factory</literal> method with <literal>@Begin</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Annotate the Seam page action method with <literal>@Begin</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Use <literal><![CDATA[<begin-conversation>]]></literal> in <filename>pages.xml</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Use <literal>#{conversation.begin}</literal> as the Seam page action method
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
- <para>
- It's time to understand Seam's conversation model in more detail.
- </para>
-
- <para>
- Historically, the notion of a Seam "conversation" came about as
- a merger of three different ideas:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- The idea of a <emphasis>workspace</emphasis>, which I
- encountered in a project for the Victorian government in
- 2002. In this project I was forced to implement workspace
- management on top of Struts, an experience I pray never
- to repeat.
- </para>
- </listitem>
- <listitem>
- <para>
- The idea of an <emphasis>application transaction</emphasis>
- with optimistic semantics, and the realization that existing
- frameworks based around a stateless architecture could not
- provide effective management of extended persistence contexts.
- (The Hibernate team is truly fed up with copping the blame for
- <literal>LazyInitializationException</literal>s, which are
- not really Hibernate's fault, but rather the fault of the
- extremely limiting persistence context model supported by
- stateless architectures such as the Spring framework or the
- traditional <emphasis>stateless session facade</emphasis>
- (anti)pattern in J2EE.)
- </para>
- </listitem>
- <listitem>
- <para>
- The idea of a workflow <emphasis>task</emphasis>.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- By unifying these ideas and providing deep support in the framework,
- we have a powerful construct that lets us build richer and more efficient
- applications with less code than before.
- </para>
-
- <section>
- <title>Seam's conversation model</title>
-
- <para>
- The examples we have seen so far make use of a very simple
- conversation model that follows these rules:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- There is always a conversation context active during the
- apply request values, process validations, update model values,
- invoke application and render response phases of the JSF request
- lifecycle.
- </para>
- </listitem>
- <listitem>
- <para>
- At the end of the restore view phase of the JSF request
- lifecycle, Seam attempts to restore any previous long-running
- conversation context. If none exists, Seam creates a new
- temporary conversation context.
- </para>
- </listitem>
- <listitem>
- <para>
- When an <literal>@Begin</literal> method is encountered,
- the temporary conversation context is promoted to a long
- running conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- When an <literal>@End</literal> method is encountered,
- any long-running conversation context is demoted to a
- temporary conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- At the end of the render response phase of the JSF request
- lifecycle, Seam stores the contents of a long running
- conversation context or destroys the contents of a temporary
- conversation context.
- </para>
- </listitem>
- <listitem>
- <para>
- Any faces request (a JSF postback) will propagate the
- conversation context. By default, non-faces requests (GET
- requests, for example) do not propagate the conversation
- context, but see below for more information on this.
- </para>
- </listitem>
- <listitem>
- <para>
- If the JSF request lifecycle is foreshortened by a redirect,
- Seam transparently stores and restores the current conversation
- context — unless the conversation was already ended via
- <literal>@End(beforeRedirect=true)</literal>.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Seam transparently propagates the conversation context (including
- the temporary conversation context) across JSF postbacks and
- redirects. If you don't do anything special, a <emphasis>non-faces request</emphasis>
- (a GET request for example) will not propagate the conversation context and
- will be processed in a new temporary conversation. This is usually - but not
- always - the desired behavior.
- </para>
-
- <para>
- If you want to propagate a Seam conversation across a non-faces request, you
- need to explicitly code the Seam <emphasis>conversation id</emphasis> as a
- request parameter:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<a href="main.jsf?#{manager.conversationIdParameter}=#{conversation.id}">Continue</a>]]></programlisting>
-
- <para>
- Or, the more JSF-ish:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:outputLink value="main.jsf">
- <f:param name="#{manager.conversationIdParameter}" value="#{conversation.id}"/>
- <h:outputText value="Continue"/>
-</h:outputLink>]]></programlisting>
-
- <para>
- If you use the Seam tag library, this is equivalent:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:outputLink value="main.jsf">
- <s:conversationId/>
- <h:outputText value="Continue"/>
-</h:outputLink>]]></programlisting>
-
- <para>
- If you wish to disable propagation of the conversation context for a
- postback, a similar trick is used:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Exit">
- <f:param name="conversationPropagation" value="none"/>
-</h:commandLink>]]></programlisting>
-
- <para>
- If you use the Seam tag library, this is equivalent:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Exit">
- <s:conversationPropagation type="none"/>
-</h:commandLink>]]></programlisting>
-
- <para>
- Note that disabling conversation context propagation is absolutely not the
- same thing as ending the conversation.
- </para>
-
- <para>
- The <literal>conversationPropagation</literal> request parameter, or
- the <literal><s:conversationPropagation></literal> tag may even
- be used to begin and end conversation, or begin a nested
- conversation.
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Exit">
- <s:conversationPropagation type="end"/>
-</h:commandLink>]]></programlisting>
-
- <programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Select Child">
- <s:conversationPropagation type="nested"/>
-</h:commandLink>]]></programlisting>
-
- <programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Select Hotel">
- <s:conversationPropagation type="begin"/>
-</h:commandLink>]]></programlisting>
-
- <programlisting role="XHTML"><![CDATA[<h:commandLink action="main" value="Select Hotel">
- <s:conversationPropagation type="join"/>
-</h:commandLink>]]></programlisting>
-
- <para>
- This conversation model makes it easy to build applications which
- behave correctly with respect to multi-window operation. For many
- applications, this is all that is needed. Some complex applications
- have either or both of the following additional requirements:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- A conversation spans many smaller units of user interaction,
- which execute serially or even concurrently. The smaller
- <emphasis>nested conversations</emphasis> have their own
- isolated set of conversation state, and also have access to
- the state of the outer conversation.
- </para>
- </listitem>
- <listitem>
- <para>
- The user is able to switch between many conversations
- within the same browser window. This feature is called
- <emphasis>workspace management</emphasis>.
- </para>
- </listitem>
- </itemizedlist>
-
- </section>
-
- <section>
- <title>Nested conversations</title>
-
- <para>
- A nested conversation is created by invoking a method marked
- <literal>@Begin(nested=true)</literal> inside the scope of an
- existing conversation. A nested conversation has its own
- conversation context, but can read values from the outer
- conversation's context. The outer conversation's context is
- read-only within a nested conversation, but because objects
- are obtained by reference, changes to the objects themselves
- will be reflected in the outer context.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Nesting a conversation through initializes a context that is
- stacked on the context of the original, or outer, conversation.
- The outer conversation is considered the parent.
- </para>
- </listitem>
- <listitem>
- <para>
- Any values outjected or directly set into the nested
- conversation’s context do not affect the objects accessible in
- the parent conversation’s context.
- </para>
- </listitem>
- <listitem>
- <para>
- Injection or a context lookup from the conversation context
- will first lookup the value in the current conversation context
- and, if no value is found, will proceed down the conversation
- stack if the conversation is nested. As you will see in moment,
- this behavior can be overriden.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- When an <literal>@End</literal> is subsequently encountered,
- the nested conversation will be destroyed, and the outer
- conversation will resume, by "popping" the conversation stack.
- Conversations may be nested to any arbitrary depth.
- </para>
-
- <para>
- Certain user activity (workspace management, or the back button)
- can cause the outer conversation to be resumed before the inner
- conversation is ended. In this case it is possible to have
- multiple concurrent nested conversations belonging to the
- same outer conversation. If the outer conversation ends before
- a nested conversation ends, Seam destroys all nested conversation
- contexts along with the outer context.
- </para>
-
- <para>
- The conversation at the bottom of the conversation stack is the root
- conversation. Destroying this conversation always destroy all of its
- descendents. You can achieve this declaratively by specifying
- <literal>@End(root=true)</literal>.
- </para>
-
- <para>
- A conversation may be thought of as a <emphasis>continuable state</emphasis>.
- Nested conversations allow the application to capture a consistent
- continuable state at various points in a user interaction, thus
- ensuring truly correct behavior in the face of backbuttoning and
- workspace management.
- </para>
-
- <para>
- As mentioned previously, if a component exists in a parent conversation of
- the current nested conversation, the nested conversation will use
- the same instance. Occasionally, it is useful to have a different
- instance in each nested conversation, so that the component
- instance that exists in the parent conversation is invisible to
- its child conversations. You can achieve this behavior by
- annotating the component <literal>@PerNestedConversation</literal>.
- </para>
-
- </section>
-
- <section>
- <title>Starting conversations with GET requests</title>
- <para>
- JSF does not define any kind of action listener that is triggered
- when a page is accessed via a non-faces request (for example, a
- HTTP GET request). This can occur if the user bookmarks the page,
- or if we navigate to the page via an <literal><h:outputLink></literal>.
- </para>
-
- <para>
- Sometimes we want to begin a conversation immediately the page is
- accessed. Since there is no JSF action method, we can't solve the problem
- in the usual way, by annotating the action with <literal>@Begin</literal>.
- </para>
-
- <para>
- A further problem arises if the page needs some state to be fetched
- into a context variable. We've already seen two ways to solve this
- problem. If that state is held in a Seam component, we can fetch the
- state in a <literal>@Create</literal> method. If not, we can define a
- <literal>@Factory</literal> method for the context variable.
- </para>
-
- <para>
- If none of these options works for you, Seam lets you define a
- <emphasis>page action</emphasis> in the <literal>pages.xml</literal>
- file.
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/messageList.jsp" action="#{messageManager.list}"/>
- ...
-</pages>]]></programlisting>
-
- <para>
- This action method is called at the beginning of the render response
- phase, any time the page is about to be rendered. If a page action
- returns a non-null outcome, Seam will process any appropriate JSF and
- Seam navigation rules, possibly resulting in a completely different page
- being rendered.
- </para>
-
- <para>
- If <emphasis>all</emphasis> you want to do before rendering the page
- is begin a conversation, you could use a built-in action method that
- does just that:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/messageList.jsp" action="#{conversation.begin}"/>
- ...
-</pages>]]></programlisting>
-
- <para>
- Note that you can also call this built-in action from a JSF
- control, and, similarly, you can use
- <literal>#{conversation.end}</literal> to end conversations.
- </para>
-
- <para>
- If you want more control, to join existing conversations or
- begin a nested conversion, to begin a pageflow or an atomic
- conversation, you should use the
- <literal><begin-conversation></literal> element.
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/messageList.jsp">
- <begin-conversation nested="true" pageflow="AddItem"/>
- <page>
- ...
-</pages>]]></programlisting>
-
- <para>
- There is also an <literal><end-conversation></literal>
- element.
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/home.jsp">
- <end-conversation/>
- <page>
- ...
-</pages>]]></programlisting>
-
- <para>
- To solve the first problem, we now have five options:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Annotate the <literal>@Create</literal> method with
- <literal>@Begin</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- Annotate the <literal>@Factory</literal> method with
- <literal>@Begin</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- Annotate the Seam page action method with
- <literal>@Begin</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- Use <literal><begin-conversation></literal> in
- <literal>pages.xml</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- Use <literal>#{conversation.begin}</literal> as
- the Seam page action method
- </para>
- </listitem>
- </itemizedlist>
-
- </section>
-
- <section id="conversations.required">
+ <section id="conversations.required">
<title>Requiring a long-running conversation</title>
<para>
- Certain pages are only relevant in the context of a long-running conversation. One way to "protect" such a
- page is to require a long-running conversation as a prerequisite to rendering the page. Fortunately, Seam
- has a built-in mechanism for enforcing this requirement.
+ Certain pages are only relevant in the context of a long-running conversation. One way to restrict access to such a page is to make the existence of a long-running conversation a prerequisite to the page being rendered.
</para>
<para>
- In the Seam page descriptor, you can indicate that the current conversation must be long-running (or nested)
- in order for a page to be rendered using the <literal>conversation-required</literal> attribute as follows:
+ Seam's page descriptor has a <literal>conversation-required</literal> attribute, which lets you indicate that the current conversation must be long-running (or nested) in order for a page to be rendered, like so:
</para>
- <programlisting role="XML"><![CDATA[<page view-id="/book.xhtml" conversation-required="true"/>]]></programlisting>
+<programlisting role="XML"><![CDATA[<page view-id="/book.xhtml" conversation-required="true"/>
+]]>
+</programlisting>
<note>
<para>
- The only downside is there's no built-in way to indicate <emphasis>which</emphasis> long-running
- conversation is required. You can build on this basic authorization by dually checking if a specific
- value is present in the conversation within a page action.
+ At present, you cannot indicate which long-running conversation is required. However, you can build on the basic authorization by checking whether a specific value is also present in the conversation within a page action.
</para>
</note>
<para>
- When Seam determines that this page is requested outside of a long-running conversation, the following
- actions are taken:
+ When Seam determines that the page has been requested while no long-running conversation is present, it performs the following actions:
</para>
<itemizedlist>
<listitem>
- <para>A contextual event named <literal>org.jboss.seam.noConversation</literal> is raised</para>
+ <para>raises a contextual event called <literal>org.jboss.seam.noConversation</literal></para>
</listitem>
<listitem>
- <para>A warning status message is registered using the bundle key <literal>org.jboss.seam.NoConversation</literal></para>
+ <para>registers a warning status message with the bundle key, <literal>org.jboss.seam.NoConversation</literal></para>
</listitem>
<listitem>
- <para>The user is redirected to an alternate page, if defined</para>
+ <para>redirects the user to an alternative page, if defined in the <literal>no-conversation-view-id</literal> attribute, like so:</para>
+<programlisting><![CDATA[<pages no-conversation-view-id="/main.xhtml"/>
+]]>
+</programlisting>
+ <para>This page will be used across the entire application; at present, multiple alternative pages cannot be defined.</para>
</listitem>
</itemizedlist>
-
- <para>
- The alternate page is defined in the <literal>no-conversation-view-id</literal> attribute on a
- <literal><pages></literal> element in the Seam page descriptor as follows:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages no-conversation-view-id="/main.xhtml"/>]]></programlisting>
-
- <para>
- At the moment, you can only define one such page for the entire application.
- </para>
-
</section>
<section>
- <title>Using <literal><s:link></literal> and <literal><s:button></literal></title>
-
- <para>
- JSF command links always perform a form submission via JavaScript,
- which breaks the web browser's "open in new window" or "open in new tab"
- feature. In plain JSF, you need to use an <literal><h:outputLink></literal>
- if you need this functionality. But there are two major limitations to
- <literal><h:outputLink></literal>.
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- JSF provides no way to attach an action listener to an
- <literal><h:outputLink></literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- JSF does not propagate the selected row of a <literal>DataModel</literal>
- since there is no actual form submission.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Seam provides the notion of a <emphasis>page action</emphasis> to help
- solve the first problem, but this does nothing to help us with the second
- problem. We <emphasis>could</emphasis> work around this by using the
- RESTful approach of passing a request parameter and requerying
- for the selected object on the server side. In some cases — such as the
- Seam blog example application — this is indeed the best approach. The
- RESTful style supports bookmarking, since it does not require server-side state.
- In other cases, where we don't care about bookmarks, the use of
- <literal>@DataModel</literal> and <literal>@DataModelSelection</literal> is
- just so convenient and transparent!
- </para>
-
- <para>
- To fill in this missing functionality, and to make conversation propagation
- even simpler to manage, Seam provides the <literal><s:link></literal>
- JSF tag.
- </para>
-
- <para>
- The link may specify just the JSF view id:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:link view="/login.xhtml" value="Login"/>]]></programlisting>
-
- <para>
- Or, it may specify an action method (in which case the action outcome determines
- the page that results):
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:link action="#{login.logout}" value="Logout"/>]]></programlisting>
-
- <para>
- If you specify <emphasis>both</emphasis> a JSF view id and an action method, the
- 'view' will be used <emphasis>unless</emphasis> the action method returns a
- non-null outcome:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:link view="/loggedOut.xhtml" action="#{login.logout}" value="Logout"/>]]></programlisting>
-
- <para>
- The link automatically propagates the selected row of a <literal>DataModel</literal>
- using inside <literal><h:dataTable></literal>:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:link view="/hotel.xhtml" action="#{hotelSearch.selectHotel}" value="#{hotel.name}"/>]]></programlisting>
-
- <para>
- You can leave the scope of an existing conversation:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:link view="/main.xhtml" propagation="none"/>]]></programlisting>
-
- <para>
- You can begin, end, or nest conversations:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:link action="#{issueEditor.viewComment}" propagation="nest"/>]]></programlisting>
-
- <para>
- If the link begins a conversation, you can even specify a pageflow to be used:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:link action="#{documentEditor.getDocument}" propagation="begin"
- pageflow="EditDocument"/>]]></programlisting>
-
- <para>
- The <literal>taskInstance</literal> attribute is for use in jBPM task lists:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:link action="#{documentApproval.approveOrReject}" taskInstance="#{task}"/>]]></programlisting>
-
- <para>
- (See the DVD Store demo application for examples of this.)
- </para>
-
- <para>
- Finally, if you need the "link" to be rendered as a button, use <literal><s:button></literal>:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:button action="#{login.logout}" value="Logout"/>]]></programlisting>
-
- </section>
-
- <section>
- <title>Success messages</title>
- <para>
- It is quite common to display a message to the user indicating
- success or failure of an action. It is convenient to use a JSF
- <literal>FacesMessage</literal> for this. Unfortunately, a
- successful action often requires a browser redirect, and JSF
- does not propagate faces messages across redirects. This makes
- it quite difficult to display success messages in plain JSF.
- </para>
-
- <para>
- The built in conversation-scoped Seam component named
- <literal>facesMessages</literal> solves this problem.
- (You must have the Seam redirect filter installed.)
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("editDocumentAction")
- at Stateless
-public class EditDocumentBean implements EditDocument {
- @In EntityManager em;
- @In Document document;
- @In FacesMessages facesMessages;
-
- public String update() {
- em.merge(document);
- facesMessages.add("Document updated");
- }
-}]]></programlisting>
-
- <para>
- Any message added to <literal>facesMessages</literal> is
- used in the very next render response phase for the current
- conversation. This even works when there is no long-running
- conversation since Seam preserves even temporary conversation
- contexts across redirects.
- </para>
-
- <para>
- You can even include JSF EL expressions in a faces message summary:
- </para>
-
- <programlisting role="JAVA"><![CDATA[facesMessages.add("Document #{document.title} was updated");]]></programlisting>
-
- <para>
- You may display the messages in the usual way, for example:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:messages globalOnly="true"/>]]></programlisting>
+ <title>Using <literal><![CDATA[<s:link>]]></literal> and <literal><![CDATA[<s:button>]]></literal></title>
+ <para>
+ JSF command links always perform a form submission with JavaScript, which causes problems with the web browser's "open in new window" or "open in new tab" feature. If you require this functionality in plain JSF, you need to use an <literal><![CDATA[<h:outputLink>]]></literal>, but there are two major limitations to this method:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ JSF provides no way to attach an action listener to an <literal><![CDATA[<h:outputLink>]]></literal>, and
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ JSF does not propagate the selected row of a <literal>DataModel</literal>, since there is no actual form submission.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ To solve the first problem, Seam implements the notion of a <emphasis>page action</emphasis>, but this does not solve the second. It is possible to work around this by passing a request parameter and requerying for the selected object on the server-side, and in some cases (like the Seam blog example application), this is the best approach. Since it is RESTful and does not require server-side state, bookmarking is supported. In other cases, where bookmarking is unnecessary, <literal>@DataModel</literal> and <literal>@DataModelSelection</literal> are transparent and convenient.
+ </para>
+ <para>
+ To replace this missing functionality, and to simplify conversation propagation further, Seam provides the <literal><![CDATA[<s:link>]]></literal> JSF tag.
+ </para>
+ <para>
+ The link can specify only the JSF ID:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:link view="/login.xhtml" value="Login"/>
+]]>
+</programlisting>
+ <para>
+ It can also specify an action method, in which case the action outcome determines the page that results:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:link action="#{login.logout}" value="Logout"/>
+]]>
+</programlisting>
+ <para>
+ If both a JSF view ID and an action method are specified, the view will be used unless the action method returns a non-null outcome:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:link view="/loggedOut.xhtml" action="#{login.logout}" value="Logout"/>
+]]>
+</programlisting>
+ <para>
+ The link automatically propagates the selected row of a <literal>DataModel</literal> inside <literal><![CDATA[<h:dataTable>]]></literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:link view="/hotel.xhtml" action="#{hotelSearch.selectHotel}"
+ value="#{hotel.name}"/>
+ ]]></programlisting>
+ <para>
+ You can leave the scope of an existing conversation:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:link view="/main.xhtml" propagation="none"/>
+]]>
+</programlisting>
+ <para>
+ You can begin, end, or nest conversations:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:link action="#{issueEditor.viewComment}" propagation="nest"/>
+]]>
+</programlisting>
+ <para>
+ If the link begins a conversation, you can specify the use of a particular pageflow:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:link action="#{documentEditor.getDocument}" propagation="begin"
+ pageflow="EditDocument"/>
+]]>
+</programlisting>
+ <para>
+ The <literal>taskInstance</literal> attribute is for use in jBPM task lists, as follows. (See the DVD Store demo application for examples of this.<!-- #modify: xref? -->)
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:link action="#{documentApproval.approveOrReject}"
+ taskInstance="#{task}"/>
+ ]]>
+</programlisting>
+ <para>
+ Finally, use <literal><![CDATA[<s:button>]]></literal> if you want the "link" rendered as a button:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:button action="#{login.logout}" value="Logout"/>
+]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Success messages</title>
+ <para>
+ Messages are commonly displayed to the user to indicate the success or failure of an action. A JSF <literal>FacesMessage</literal> is convenient for this function. However, a successful action often requires a browser redirect. Since JSF does not propagate Faces messages across redirects, it is difficult to display success messages in plain JSF.
+ </para>
+ <para>
+ The built-in conversation-scoped Seam component named <literal>facesMessages</literal> solves this problem. (This requires the Seam redirect filter.)
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("editDocumentAction")
+ at Stateless
+public class EditDocumentBean implements EditDocument {
+ @In EntityManager em;
+ @In Document document;
+ @In FacesMessages facesMessages;
- </section>
-
- <section>
- <title>Natural conversation ids</title>
- <para>
- When working with conversations that deal with persistent objects, it may be
- desirable to use the natural business key of the object instead of the standard,
- "surrogate" conversation id:
- </para>
-
- <para>
- <emphasis>Easy redirect to existing conversation</emphasis>
- </para>
- <para>
- It can be useful to redirect to an existing conversation if
- the user requests the same operation twice. Take this example:
-
- <quote>
- You are on ebay, half way through paying for an item you just
- won as a Christmas present for your parents. Lets say you're
- sending it straight to them - you enter your payment details
- but you can't remember their address. You accidentally reuse
- the same browser window finding out their address. Now you
- need to return to the payment for the item.
- </quote>
- </para>
- <para>
- With a natural conversation it's really easy to have the user
- rejoin the existing conversation, and pick up where they left
- off - just have them to rejoin the payForItem conversation
- with the itemId as the conversation id.
- </para>
-
- <para>
- <emphasis>User friendly URLs</emphasis>
- </para>
-
- <para>
- For me this consists of a navigable
- hierarchy (I can navigate by editing the url) and a meaningful
- URL (like this Wiki uses - so don't identify things by random
- ids). For some applications user friendly URLs are less
- important, of course.
- </para>
-
- <para>
- With a natural conversation, when you are building your hotel
- booking system (or, of course, whatever your app is) you can
- generate a URL like
- <literal>http://seam-hotels/book.seam?hotel=BestWesternAntwerpen</literal>
- (of course, whatever parameter <literal>hotel</literal> maps
- to on your domain model must be unique) and with URLRewrite
- easily transform this to
- http://seam-hotels/book/BestWesternAntwerpen.
- </para>
-
- <para>
- Much better!
- </para>
-
- </section>
- <section>
- <title>Creating a natural conversation</title>
- <para>
- Natural conversations are defined in <literal>pages.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[ <conversation name="PlaceBid"
- parameter-name="auctionId"
- parameter-value="#{auction.auctionId}"/>]]></programlisting>
-
- <para>
- The first thing to note from the above definition is that the conversation
- has a name, in this case <literal>PlaceBid</literal>. This name uniquely
- identifies this particular named conversation, and is used by the
- <literal>page</literal> definition to identify a named conversation to participate
- in.
- </para>
-
- <para>
- The next attribute, <literal>parameter-name</literal> defines the request parameter
- that will contain the natural conversation id, in place of the default conversation
- id parameter. In this example, the <literal>parameter-name</literal> is <literal>auctionId</literal>.
- This means that instead of a conversation parameter like <literal>cid=123</literal>
- appearing in the URL for your page, it will contain <literal>auctionId=765432</literal>
- instead.
- </para>
-
- <para>
- The last attribute in the above configuration, <literal>parameter-value</literal>,
- defines an EL expression used to evaluate the value of the natural business key to
- use as the conversation id. In this example, the conversation id will be the primary
- key value of the <literal>auction</literal> instance currently in scope.
- </para>
-
- <para>
- Next, we define which pages will participate in the named conversation.
- This is done by specifying the <literal>conversation</literal> attribute for a
- <literal>page</literal> definition:
- </para>
-
- <programlisting role="XML"><![CDATA[ <page view-id="/bid.xhtml" conversation="PlaceBid" login-required="true">
- <navigation from-action="#{bidAction.confirmBid}">
- <rule if-outcome="success">
- <redirect view-id="/auction.xhtml">
- <param name="id" value="#{bidAction.bid.auction.auctionId}"/>
- </redirect>
- </rule>
- </navigation>
- </page>]]></programlisting>
-
- </section>
-
- <section>
- <title>Redirecting to a natural conversation</title>
-
- <para>
- When starting, or redirecting to, a natural conversation there are a number
- of options for specifying the natural conversation name. Let's start by looking at
- the following page definition:
- </para>
-
- <programlisting role="XML"><![CDATA[ <page view-id="/auction.xhtml">
- <param name="id" value="#{auctionDetail.selectedAuctionId}"/>
-
- <navigation from-action="#{bidAction.placeBid}">
- <redirect view-id="/bid.xhtml"/>
- </navigation>
- </page>]]></programlisting>
-
- <para>
- From here, we can see that invoking the action <literal>#{bidAction.placeBid}</literal>
- from our auction view (by the way, all these examples are taken from the seamBay example in Seam),
- that we will be redirected to <literal>/bid.xhtml</literal>, which, as we saw previously,
- is configured with the natural conversation <literal>PlaceBid</literal>. The declaration for
- our action method looks like this:
- </para>
-
- <programlisting role="JAVA"><![CDATA[ @Begin(join = true)
- public void placeBid()]]></programlisting>
-
- <para>
- When named conversations are specified in the <literal><page/></literal> element,
- redirection to the named conversation occurs as part of navigation rules, after the
- action method has already been invoked. This is a problem when redirecting to an
- existing conversation, as redirection needs to be occur before the action method is
- invoked. Therefore it is necessary to specify the conversation name when
- the action is invoked. One way of doing this is by using the <literal>s:conversationName</literal>
- tag:
- </para>
-
- <programlisting role="XHTML"><![CDATA[ <h:commandButton id="placeBidWithAmount" styleClass="placeBid" action="#{bidAction.placeBid}">
- <s:conversationName value="PlaceBid"/>
- </h:commandButton>]]></programlisting>
+ public String update() {
+ em.merge(document);
+ facesMessages.add("Document updated");
+ }
+}]]>
+</programlisting>
+ <para>
+ When a message is added to <literal>facesMessages</literal>, it is used in the nextg render response phase for the current conversation. Since Seam preserves even temporary conversation contexts across redirects, this works even without a long-running conversation.
+ </para>
+ <para>
+ You can even include JSF EL expressions in a Faces message summary:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[facesMessages.add("Document #{document.title} was updated");
+]]>
+</programlisting>
+ <para>
+ Messages are displayed as usual:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:messages globalOnly="true"/>
+]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Natural conversation IDs</title>
+ <para>
+ When working with conversations that deal with persistent objects, there are several reasons to use the natural business key of the object instead of the standard, "surrogate" conversation ID.
+ </para>
+ <para>
+ <emphasis>Easy redirect to existing conversation</emphasis>
+ </para>
+ <para>
+ If the user requests the same operation twice, it can be useful to redirect to an existing conversation. Take the following situation, for example:
+ </para>
+ <para>
+ You are on Ebay, halfway through paying for an item you won as a Christmas present for your parents. You want to send it straight to them, but once you have entered your payment details, you cannot remember your parents' address. While you find the address, you accidentally reuse the same browser window, but now you need to return to payment for the item.
+ </para>
+ <para>
+ With a natural conversation, the user can easily rejoin the previous conversation and pick up where they left off. In this case, they can rejoin the payForItem conversation with the itemId as the conversation ID.
+ </para>
+ <para>
+ <emphasis>User-friendly URLs</emphasis>
+ </para>
+ <para>
+ A user-friendly URL is meaningful (refers to page contents plainly, without using ID numbers), and has a navigable heirarchy (that is, the user can navigate by editing the URL).
+ </para>
+ <para>
+ With a natural conversation, applications can generate long, complex URLs, but display simple, memorable URLs to users by using URLRewrite. In the case of our hotel booking example, <literal>http://seam-hotels/book.seam?hotel=BestWesternAntwerpen</literal> is rewritten as <literal>http://seam-hotels/book/BestWesternAntwerpen</literal> — much clearer. Note that URLRewrite relies upon parameters: <literal>hotel</literal> in the previous example must map to a unique parameter on the domain model.
+ </para>
+ </section>
+
+ <section>
+ <title>Creating a natural conversation</title>
+ <para>
+ Natural conversations are defined in <filename>pages.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<conversation name="PlaceBid" parameter-name="auctionId"
+ parameter-value="#{auction.auctionId}"/>
+]]>
+</programlisting>
+ <para>
+ The first thing to note in the above definition is the conversation name, in this case <literal>PlaceBid</literal>. The conversation name identifies this particular named conversation uniquely, and is used by the <literal>page</literal> definition to identify a named conversation in which to participate.
+ </para>
+ <para>
+ The <literal>parameter-name</literal> attribute defines the request parameter that will hold the natural conversation ID, and replace the default conversation ID parameter. In this case, <literal>parameter-name</literal> is <literal>auctionId</literal>. This means that the URL of your page will contain <literal>auctionId=765432</literal> instead of a conversation parameter like <literal>cid=123</literal>.
+ </para>
+ <para>
+ The final attribute, <literal>parameter-value</literal>, defines an EL expression to evaluate the value of the natural business key to use as the conversation ID. In this example, the conversation ID will be the primary key value of the <literal>auction</literal> instance currently in scope.
+ </para>
+ <para>
+ Next, we define the pages participating in the named conversation. This is done by specifying the <literal>conversation</literal> attribute for a <literal>page</literal> definition:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/bid.xhtml" conversation="PlaceBid" login-required="true">
+ <navigation from-action="#{bidAction.confirmBid}">
+ <rule if-outcome="success">
+ <redirect view-id="/auction.xhtml">
+ <param name="id" value="#{bidAction.bid.auction.auctionId}"/>
+ </redirect>
+ </rule>
+ </navigation>
+</page>
+]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Redirecting to a natural conversation</title>
+ <para>
+ When initiating or redirecting to a natural conversation, there are several ways to specify the natural conversation name. We will start with the following page definition:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/auction.xhtml">
+ <param name="id" value="#{auctionDetail.selectedAuctionId}"/>
+ <navigation from-action="#{bidAction.placeBid}">
+ <redirect view-id="/bid.xhtml"/>
+ </navigation>
+</page>]]>
+</programlisting>
+ <para>
+ Here we see that invoking <literal>#{bidAction.placeBid}</literal> redirects us to <filename>/bid.xhtml</filename>, which is configured with the natural conversation ID <literal>PlaceBid</literal>. Our action method declaration looks like this:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Begin(join = true)
+public void placeBid()
+]]>
+</programlisting>
+ <para>
+ When named conversations are specified in the <literal><![CDATA[<page/>]]></literal> element, redirection to the named conversation occurs as part of navigation rules following the invocation of the action method. This can cause problems when redirecting to an existing conversation, since redirection needs to occur before the action method is invoked. Therefore, the conversation name must be specified before the action is invoked. One method of doing this uses the <literal><![CDATA[<s:conversationName>]]></literal> tag:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton id="placeBidWithAmount" styleClass="placeBid"
+ action="#{bidAction.placeBid}">
+ <s:conversationName value="PlaceBid"/>
+</h:commandButton>]]>
+</programlisting>
+ <para>
+ You can also specify the <literal>conversationName</literal> attribute for either the <literal>s:link</literal> or <literal>s:button</literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:link value="Place Bid" action="#{bidAction.placeBid}"
+ conversationName="PlaceBid"/>
+]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Workspace management</title>
+ <para>
+ Workspace management is the ability to "switch" conversations in a single window. Seam workspace mangement is completely transparent at the Java level. To enable workspace management:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Provide <emphasis>description</emphasis> text for each view ID (when using JSF or Seam navigation rules) or page node (when using jPDL pageflows). Workspace switchers display this description text to the user.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Include one or more workspace switcher JSP or Facelets fragments in your page. Standard fragments support workspace management via a drop-down menu and a list of conversations, or "breadcrumbs".
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Workspace management and JSF navigation</title>
+ <para>
+ With JSF or Seam navigation rules in place, Seam switches to a conversation by restoring the current <literal>view-id</literal> for that conversation. The descriptive text for the workspace is defined in a file called <filename>pages.xml</filename>, which Seam expects to find in the <literal>WEB-INF</literal> directory alongside <filename>faces-config.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/main.xhtml">
+ <description>Search hotels: #{hotelBooking.searchString}</description>
+ </page>
+ <page view-id="/hotel.xhtml">
+ <description>View hotel: #{hotel.name}</description>
+ </page>
+ <page view-id="/book.xhtml">
+ <description>Book hotel: #{hotel.name}</description>
+ </page>
+ <page view-id="/confirm.xhtml">
+ <description>Confirm: #{booking.description}</description>
+ </page>
+</pages>
+]]>
+</programlisting>
+ <note>
+ <para>
+ The Seam application will still work if this file is not present. However, workplace switching will not be available.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>Workspace management and jPDL pageflow</title>
+ <para>
+ When a jPDL pageflow definition is in place, Seam switches to a particular conversation by restoring the current jBPM process state. This is a more flexible model, since it allows the same <literal>view-id</literal> to have different descriptions depending on the current <literal><![CDATA[<page>]]></literal> node. The description text is defined by the <literal><![CDATA[<page>]]></literal> node:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pageflow-definition name="shopping">
+ <start-state name="start">
+ <transition to="browse"/>
+ </start-state>
+ <page name="browse" view-id="/browse.xhtml">
+ <description>DVD Search: #{search.searchPattern}</description>
+ <transition to="browse"/>
+ <transition name="checkout" to="checkout"/>
+ </page>
+ <page name="checkout" view-id="/checkout.xhtml">
+ <description>Purchase: $#{cart.total}</description>
+ <transition to="checkout"/>
+ <transition name="complete" to="complete"/>
+ </page>
+ <page name="complete" view-id="/complete.xhtml">
+ <end-conversation />
+ </page>
+</pageflow-definition>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>The conversation switcher</title>
+ <para>
+ Including the following fragment in your JSP or Facelets page will include a drop-down menu that lets you switch to any current conversation, or any other page of the application:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{switcher.conversationIdOrOutcome}">
+ <f:selectItem itemLabel="Find Issues" itemValue="findIssue"/>
+ <f:selectItem itemLabel="Create Issue" itemValue="editIssue"/>
+ <f:selectItems value="#{switcher.selectItems}"/>
+</h:selectOneMenu>
+<h:commandButton action="#{switcher.select}" value="Switch"/>
+]]>
+</programlisting>
+ <para>
+ This example includes a menu that contains an item for each conversation, plus two additional items that let the user begin an additional conversation.
+ </para>
+ <para>
+ Only conversations with a description (specified in <filename>pages.xml</filename>) will be included in the drop-down menu.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/switcher.png" format="PNG" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/switcher.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ <section>
+ <title>The conversation list</title>
+ <para>
+ The conversation list is similar to the conversation switcher, except that it is displayed as a table:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:dataTable value="#{conversationList}" var="entry"
+ rendered="#{not empty conversationList}">
+ <h:column>
+ <f:facet name="header">Workspace</f:facet>
+ <h:commandLink action="#{entry.select}" value="#{entry.description}"/>
+ <h:outputText value="[current]" rendered="#{entry.current}"/>
+ </h:column>
+ <h:column>
+ <f:facet name="header">Activity</f:facet>
+ <h:outputText value="#{entry.startDatetime}">
+ <f:convertDateTime type="time" pattern="hh:mm a"/>
+ </h:outputText>
+ <h:outputText value=" - "/>
+ <h:outputText value="#{entry.lastDatetime}">
+ <f:convertDateTime type="time" pattern="hh:mm a"/>
+ </h:outputText>
+ </h:column>
+ <h:column>
+ <f:facet name="header">Action</f:facet>
+ <h:commandButton action="#{entry.select}" value="#{msg.Switch}"/>
+ <h:commandButton action="#{entry.destroy}" value="#{msg.Destroy}"/>
+ </h:column>
+</h:dataTable>
+]]>
+</programlisting>
+ <para>
+ This can be customized for your own applications.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/list.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/list.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ Only conversations with a description will be included in the list.
+ </para>
+ <para>
+ Note that the conversation list also lets the user destroy workspaces.
+ </para>
+ </section>
+
+ <section>
+ <title>Breadcrumbs</title>
+ <para>
+ Breadcrumbs are a list of links to conversations in the current conversation stack. They are useful for applications with a nested conversation model:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<ui:repeat value="#{conversationStack}" var="entry">
+ <h:outputText value=" | "/>
+ <h:commandLink value="#{entry.description}" action="#{entry.select}"/>
+</ui:repeat
+]]>
+</programlisting>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/breadcrumbs.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/breadcrumbs.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Conversational components and JSF component bindings</title>
+ <para>
+ Conversational components have one minor limitation: they cannot be used to hold bindings to JSF components. (Generally we recommend avoiding this feature of JSF unless absolutely necessary, since it creates a hard dependency from application logic to the view.) On a postback request, component bindings are updated during the Restore View phase, before the Seam conversation context has been restored.
+ </para>
+ <para>
+ You can work around this by storing component bindings with an event-scoped component, and injecting this into the requiring conversation-scoped component.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("grid")
+ at Scope(ScopeType.EVENT)
+public class Grid {
+ private HtmlPanelGrid htmlPanelGrid; // getters and setters
+ ...
+}
+]]>
+</programlisting>
+
+<programlisting role="JAVA"><![CDATA[@Name("gridEditor")
+ at Scope(ScopeType.CONVERSATION)
+public class GridEditor {
+ @In(required=false)
- <para>
- Another alternative is to specify the <literal>conversationName</literal> attribute when
- using either <literal>s:link</literal> or <literal>s:button</literal>:
- </para>
-
- <programlisting role="XHTML"><![CDATA[ <s:link value="Place Bid" action="#{bidAction.placeBid}" conversationName="PlaceBid"/>]]></programlisting>
-
- </section>
-
-
- <section>
- <title>Workspace management</title>
-
- <para>
- Workspace management is the ability to "switch" conversations in
- a single window. Seam makes workspace management completely
- transparent at the level of the Java code. To enable workspace
- management, all you need to do is:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Provide <emphasis>description</emphasis> text for each view id
- (when using JSF or Seam navigation rules) or page node (when using
- jPDL pageflows). This description text is displayed to the user
- by the workspace switchers.
- </para>
- </listitem>
- <listitem>
- <para>
- Include one or more of the standard workspace switcher JSP
- or facelets fragments in your pages. The standard fragments
- support workspace management via a drop down menu, a list
- of conversations, or breadcrumbs.
- </para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>Workspace management and JSF navigation</title>
- <para>
- When you use JSF or Seam navigation rules, Seam switches to a
- conversation by restoring the current <literal>view-id</literal>
- for that conversation. The descriptive text for the
- workspace is defined in a file called <literal>pages.xml</literal>
- that Seam expects to find in the <literal>WEB-INF</literal>
- directory, right next to <literal>faces-config.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/main.xhtml">
- <description>Search hotels: #{hotelBooking.searchString}</description>
- </page>
- <page view-id="/hotel.xhtml">
- <description>View hotel: #{hotel.name}</description>
- </page>
- <page view-id="/book.xhtml">
- <description>Book hotel: #{hotel.name}</description>
- </page>
- <page view-id="/confirm.xhtml">
- <description>Confirm: #{booking.description}</description>
- </page>
- </pages>]]></programlisting>
-
- <para>
- Note that if this file is missing, the Seam application will
- continue to work perfectly! The only missing functionality
- will be the ability to switch workspaces.
- </para>
-
- </section>
-
- <section>
- <title>Workspace management and jPDL pageflow</title>
- <para>
- When you use a jPDL pageflow definition, Seam switches
- to a conversation by restoring the current jBPM process
- state. This is a more flexible model since it allows the
- same <literal>view-id</literal> to have different
- descriptions depending upon the current
- <literal><page></literal> node. The description
- text is defined by the <literal><page></literal>
- node:
- </para>
-
-<programlisting role="XML"><![CDATA[<pageflow-definition name="shopping">
-
- <start-state name="start">
- <transition to="browse"/>
- </start-state>
-
- <page name="browse" view-id="/browse.xhtml">
- <description>DVD Search: #{search.searchPattern}</description>
- <transition to="browse"/>
- <transition name="checkout" to="checkout"/>
- </page>
-
- <page name="checkout" view-id="/checkout.xhtml">
- <description>Purchase: $#{cart.total}</description>
- <transition to="checkout"/>
- <transition name="complete" to="complete"/>
- </page>
-
- <page name="complete" view-id="/complete.xhtml">
- <end-conversation />
- </page>
-
-</pageflow-definition>]]></programlisting>
-
- </section>
-
- <section>
- <title>The conversation switcher</title>
-
- <para>
- Include the following fragment in your JSP or facelets page
- to get a drop-down menu that lets you switch to any
- current conversation, or to any other page of the application:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{switcher.conversationIdOrOutcome}">
- <f:selectItem itemLabel="Find Issues" itemValue="findIssue"/>
- <f:selectItem itemLabel="Create Issue" itemValue="editIssue"/>
- <f:selectItems value="#{switcher.selectItems}"/>
-</h:selectOneMenu>
-<h:commandButton action="#{switcher.select}" value="Switch"/>]]></programlisting>
-
- <para>
- In this example, we have a menu that includes an item for each
- conversation, together with two additional items that let the
- user begin a new conversation.
- </para>
-
- <para>
- Only conversations with a description (specified in
- <literal>pages.xml</literal>) will be included in the drop-down
- menu.
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/switcher.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/switcher.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- </section>
-
- <section>
- <title>The conversation list</title>
-
- <para>
- The conversation list is very similar to the conversation switcher,
- except that it is displayed as a table:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:dataTable value="#{conversationList}" var="entry"
- rendered="#{not empty conversationList}">
- <h:column>
- <f:facet name="header">Workspace</f:facet>
- <h:commandLink action="#{entry.select}" value="#{entry.description}"/>
- <h:outputText value="[current]" rendered="#{entry.current}"/>
- </h:column>
- <h:column>
- <f:facet name="header">Activity</f:facet>
- <h:outputText value="#{entry.startDatetime}">
- <f:convertDateTime type="time" pattern="hh:mm a"/>
- </h:outputText>
- <h:outputText value=" - "/>
- <h:outputText value="#{entry.lastDatetime}">
- <f:convertDateTime type="time" pattern="hh:mm a"/>
- </h:outputText>
- </h:column>
- <h:column>
- <f:facet name="header">Action</f:facet>
- <h:commandButton action="#{entry.select}" value="#{msg.Switch}"/>
- <h:commandButton action="#{entry.destroy}" value="#{msg.Destroy}"/>
- </h:column>
-</h:dataTable>]]></programlisting>
-
- <para>
- We imagine that you will want to customize this for your own application.
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/list.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/list.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>
- Only conversations with a description will be included in the
- list.
- </para>
-
- <para>
- Notice that the conversation list lets the user destroy workspaces.
- </para>
-
- </section>
-
- <section>
- <title>Breadcrumbs</title>
-
- <para>
- Breadcrumbs are useful in applications which use a nested conversation
- model. The breadcrumbs are a list of links to conversations in the
- current conversation stack:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<ui:repeat value="#{conversationStack}" var="entry">
- <h:outputText value=" | "/>
- <h:commandLink value="#{entry.description}" action="#{entry.select}"/>
-</ui:repeat]]></programlisting>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/breadcrumbs.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/breadcrumbs.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- </section>
- </section>
-
- <section>
- <title>Conversational components and JSF component bindings</title>
-
- <para>
- Conversational components have one minor limitation: they cannot be used to hold bindings
- to JSF components. (We generally prefer not to use this feature of JSF unless absolutely
- necessary, since it creates a hard dependency from application logic to the view.) On a
- postback request, component bindings are updated during the Restore View phase,
- before the Seam conversation context has been restored.
- </para>
-
- <para>
- To work around this use an event scoped component to store the component bindings and inject
- it into the conversation scoped component that requires it.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("grid")
- at Scope(ScopeType.EVENT)
-public class Grid
-{
- private HtmlPanelGrid htmlPanelGrid;
-
- // getters and setters
- ...
-}]]></programlisting>
-
-
- <programlisting role="JAVA"><![CDATA[@Name("gridEditor")
- at Scope(ScopeType.CONVERSATION)
-public class GridEditor
-{
- @In(required=false)
- private Grid grid;
-
- ...
-}]]></programlisting>
-
- <para>
- Also, you can't inject a conversation scoped component into an event
- scoped component which you bind a JSF control to. This includes Seam
- built in components like <literal>facesMessages</literal>.
- </para>
-
- <para>
- Alternatively, you can access the JSF component tree through the implicit <literal>uiComponent</literal>
- handle. The following example accesses <literal>getRowIndex()</literal> of the
- <literal>UIData</literal> component which backs the data table during iteration, it prints
- the current row number:
- </para>
-
- <programlisting role="XHTML"><![CDATA[
-<h:dataTable id="lineItemTable" var="lineItem" value="#{orderHome.lineItems}">
- <h:column>
- Row: #{uiComponent['lineItemTable'].rowIndex}
- </h:column>
- ...
-</h:dataTable>]]></programlisting>
-
- <para>
- JSF UI components are available with their client identifier in this map.
- </para>
-
- </section>
-
- <section>
- <title>Concurrent calls to conversational components</title>
-
- <para>
- A general discussion of concurrent calls to Seam components can be
- found in <xref linkend="concurrency" />. Here we will discuss
- the most common situation in which you will encounter concurrency
- — accessing conversational components from AJAX requests.
- We're going to discuss the options that a Ajax client library should
- provide to control events originating at the client — and we'll
- look at the options RichFaces gives you.
- </para>
-
- <para>
- Conversational components don't allow real concurrent access therefore
- Seam queues each request to process them serially. This allows each
- request to be executed in a deterministic fashion. However, a simple
- queue isn't that great — firstly, if a method is, for some
- reason, taking a very long time to complete, running it over and over
- again whenever the client generates a request is bad idea (potential
- for Denial of Service attacks), and, secondly, AJAX is often to used
- to provide a quick status update to the user, so continuing to run the
- action after a long time isn't useful.
- </para>
-
- <para>
- Therefore, when you are working inside a long running conversation,
- Seam queues the action event for a period of time (the concurrent
- request timeout); if it can't process the event in time, it creates a
- temporary conversation and prints out a message to the user to let them
- know what's going on. It's therefore very important not to flood the
- server with AJAX events!
- </para>
-
- <para>
- We can set a sensible default for the concurrent request timeout (in
- ms) in components.xml:
- </para>
-
- <programlisting role="XML"><![CDATA[<core:manager concurrent-request-timeout="500" />]]></programlisting>
-
- <para>
- We can also fine tune the concurrent request timeout on a page-by-page
- basis:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/book.xhtml"
- conversation-required="true"
- login-required="true"
- concurrent-request-timeout="2000" />]]></programlisting>
-
- <para>
- So far we've discussed AJAX requests which appear serial to the user -
- the client tells the server that an event has occur, and then rerenders
- part of the page based on the result. This approach is great when the
- AJAX request is lightweight (the methods called are simple e.g.
- calculating the sum of a column of numbers). But what if we need to do
- a complex computation thats going to take a minute?
- </para>
-
- <para>
- For heavy computation we should use a poll based approach — the
- client sends an AJAX request to the server, which causes action to be
- executed asynchronously on the server (the response to the client is
- immediate) and the client then polls the server for updates. This is
- good approach when you have a long-running action for which it is
- important that every action executes (you don't want some to timeout).
- </para>
-
- <section>
- <title>How should we design our conversational AJAX application?</title>
-
- <para>
- Well first, you need to decide whether you want to use the simpler
- "serial" request or whether you want to use a polling approach.
- </para>
-
- <para>
- If you go for a "serial" requests, then you need to estimate how long
- your request will take to complete - is it much shorter than the
- concurrent request timeout? If not, you probably want to alter the
- concurrent request timeout for this page (as discussed above). You
- probably want a queue on the client side to prevent flooding the
- server with requests. If the event occurs often (e.g. a keypress,
- onblur of input fields) and immediate update of the client is not a
- priority you should set a request delay on the client side. When
- working out your request delay, factor in that the event may also be
- queued on the server side.
- </para>
-
- <para>
- Finally, the client library may provide an option to abort unfinished
- duplicate requests in favor of the most recent.
- </para>
-
- <para>
- Using a poll-style design requires less fine-tuning. You just mark your
- action method <literal>@Asynchronous</literal> and decide on a polling
- interval:
- </para>
-
- <programlisting role="JAVA"><![CDATA[int total;
-
-// This method is called when an event occurs on the client
-// It takes a really long time to execute
- at Asynchronous
-public void calculateTotal() {
- total = someReallyComplicatedCalculation();
+ private Grid grid;
+ ...
}
+]]>
+</programlisting>
+ <para>
+ You are also limited in that a conversation-scoped component cannot be injected into an event-scoped component with a JSF control bound to it. This includes Seam built-in components like <literal>facesMessages</literal>.
+ </para>
+ <para>
+ You can also access the JSF component tree with the implicit <literal>uiComponent</literal> handle. The following example accesses the <literal>getRowIndex()</literal> of the <literal>UIData</literal> component that backs the data table during iteration, and prints the current row number:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:dataTable id="lineItemTable" var="lineItem"
+ value="#{orderHome.lineItems}">
+ <h:column>
+ Row: #{uiComponent['lineItemTable'].rowIndex}
+ </h:column>
+ ...
+</h:dataTable>]]>
+</programlisting>
+ <para>
+ In this map, JSF UI components are available with their client identifier.
+ </para>
+ </section>
+
+ <section>
+ <title>Concurrent calls to conversational components</title>
+ <para>
+ <xref linkend="concurrency" /> contains a general discussion of concurrent calls to Seam components. In this section, we discuss the most common situation in which you will encounter concurrency — when accessing conversational components from AJAX requests. We will also look at the options provided by an AJAX client library, and RichFaces, to control events originating from the client.
+ </para>
+ <para>
+ Conversational components do not allow true concurrent access, so Seam queues each request for serial processing. This allows each request to be executed in a deterministic fashion. However, there are some limitations to a simple queue. If a method, for whatever reason, takes a long time to complete, running it whenever the client generates a request can lead to Denial of Service attacks. AJAX is also often used to provide quick status updates to users, so continuing to run an action after a long time is not useful.
+ </para>
+ <para>
+ Therefore, when you work inside a long-running conversation, Seam queues the action even for a period of time (the concurrent request timeout). If Seam cannot process the event before timeout, it creates a temporary conversation and prints a message for the user, informing them of the timeout. It is therefore important not to flood the server with AJAX events.
+ </para>
+ <para>
+ We can set a sensible default for the concurrent request timeout (in milliseconds) in components.xml:
+ </para>
+
+<programlisting role="XML"><![CDATA[<core:manager concurrent-request-timeout="500" />
+]]>
+</programlisting>
+ <para>
+ The concurrent request timeout can also be adjusted on a page-by-page basis:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/book.xhtml" conversation-required="true"
+ login-required="true" concurrent-request-timeout="2000" />
+]]>
+</programlisting>
+ <para>
+ So far we have discussed AJAX requests that appear serial to the user, where the client tells the server than an event has occurred, and then rerenders part of the page based on the result. This approach is sufficient when the AJAX request is lightweight (the methods called are simple, for example, calculating the sum of a column of numbers), but complex computations require a different approach.
+ </para>
+ <para>
+ A poll-based approach is where the client sends an AJAX request to the server, causing actions to begin immediate asynchronous execution on the server. The client then polls the server for updates while the actions are executed. This is a sensible approach when it is important that no action in a long-running action sequence times out.
+ </para>
+ <section>
+ <title>How should we design our conversational AJAX application?</title>
+ <para>
+ The first question is whether to use the simpler "serial" request method, or a polling approach.
+ </para>
+ <para>
+ If you want to use <emphasis>serial</emphasis> requests, you must estimate the time required for your request to complete. You may need to alter the concurrent request timeout for this page, as discussed in the previous section. A queue on the server side is probably necessary, to prevent requests from flooding the server. If the event occurs often (for example, a keypress, or onblur of input fields) and immediate client update is not a priority, set a request delay on the client side. Remember to factor the possibility of server-side queueing into your request delay.
+ </para>
+ <para>
+ Finally, the client library may provide an option to abort unfinished duplicate requests in favor of the most recent.
+ </para>
+ <para>
+ A polling approach requires less fine-tuning — simply mark your action method <literal>@Asynchronous</literal> and decide on a polling interval:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[int total;
-// This method is called as the result of the poll
-// It's very quick to execute
-public int getTotal() {
- return total;
-}]]></programlisting>
- </section>
-
- <section>
- <title>Dealing with errors</title>
-
- <para>
- However carefully you design your application to queue concurrent
- requests to your conversational component, there is a risk that the
- server will become overloaded and be unable to process all the
- requests before the request will have to wait longer than the
- <literal>concurrent-request-timeout</literal>. In this case Seam will
- throw a <literal>ConcurrentRequestTimeoutException</literal> which can
- be handled in <literal>pages.xml</literal>. We recommend sending an
- HTTP 503 error:
- </para>
-
- <programlisting role="XML"><![CDATA[ <exception class="org.jboss.seam.ConcurrentRequestTimeoutException" log-level="trace">
- <http-error error-code="503" />
- </exception>]]></programlisting>
-
- <note>
- <title>503 Service Unavailable (HTTP/1.1 RFC)</title>
-
- <para>
- The server is currently unable to handle the request due to a
- temporary overloading or maintenance of the server. The implication
- is that this is a temporary condition which will be alleviated after
- some delay.
- </para>
- </note>
-
- <para>
- Alternatively you could redirect to an error page:
- </para>
-
- <programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.ConcurrentRequestTimeoutException" log-level="trace">
- <end-conversation/>
- <redirect view-id="/error.xhtml">
- <message>The server is too busy to process your request, please try again later</message>
- </redirect>
-</exception>]]></programlisting>
-
- <para>
- ICEfaces, RichFaces Ajax and Seam Remoting can all handle HTTP error
- codes. Seam Remoting will pop up a dialog box showing the HTTP
- error. ICEfaces will indicate the error in its connection status
- component. RichFaces provides the most complete support for handling
- HTTP errors by providing a user definable callback. For example, to
- show the error message to the user:
- </para>
-
- <programlisting><![CDATA[<script type="text/javascript">
- A4J.AJAX.onError = function(req,status,message) {
- alert("An error occurred");
- };
-</script>]]></programlisting>
+// This method is called when an event occurs on the client
+// It takes a really long time to execute
+ at Asynchronous
+public void calculateTotal() {
+ total = someReallyComplicatedCalculation();
+}
- <para>
- If instead of an error code, the server reports that the view has expired,
- perhaps because the session timed out, you use a separate callback function
- in RichFaces to handle this scenario.
- </para>
-
- <programlisting><![CDATA[<script type="text/javascript">
- A4J.AJAX.onExpired = function(loc,message) {
- alert("View expired");
- };
-</script>]]></programlisting>
-
- <para>
- Alternatively, you can allow RichFaces handle the error, in which
- case the user will be presented with a prompt that reads "View state
- could't be restored - reload page?" You can customize this message
- globally by setting the following message key in an application
- resource bundle.
- </para>
-
- <programlisting><![CDATA[AJAX_VIEW_EXPIRED=View expired. Please reload the page.]]></programlisting>
-
- </section>
-
- <section>
- <title>RichFaces (Ajax4jsf)</title>
-
- <para>
- RichFaces (Ajax4jsf) is the Ajax library most commonly used with Seam, and
- provides all the controls discussed above:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>eventsQueue</literal> — provides a queue in which
- events are placed. All events are queued and requests are sent to
- the server serially. This is useful if the request to the
- server can take some time to execute (e.g. heavy computation,
- retrieving information from a slow source) as the server isn't
- flooded.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>ignoreDupResponses</literal> — ignores the response
- produced by the request if a more recent 'similar' request is
- already in the queue. ignoreDupResponses="true" does <emphasis>not
- cancel</emphasis> the processing of the request on the server
- side — just prevents unnecessary updates on the client side.
- </para>
- <para>
- This option should be used with care with Seam's conversations as
- it allows multiple concurrent requests to be made.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>requestDelay</literal> — defines the time (in ms.)
- that the request will be remain on the queue. If the request has
- not been processed by after this time the request will be sent
- (regardless of whether a response has been received) or discarded
- (if there is a more recent similar event on the queue).
- </para>
- <para>
- This option should be used with care with Seam's conversations as
- it allows multiple concurrent requests to be made. You need to be
- sure that the delay you set (in combination with the concurrent
- request timeout) is longer than the action will take to execute.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><a:poll reRender="total" interval="1000" /></literal> —
- Polls the server, and rerenders an area as needed
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
+// This method is called as the result of the poll
+// It's very quick to execute
+public int getTotal() {
+ return total;
+}
+]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Dealing with errors</title>
+ <para>
+ However carefully your application is designed to queue concurrent requests to your conversational component, there is a risk that the server will overload. When overload occurs, not all requests will be processed before the <literal>concurrent-request-timeout</literal> period expires. In this case, Seam throws a <exceptionname>ConcurrentRequestTimeoutException</exceptionname>, which is handled in <filename>pages.xml</filename>. We recommend sending a HTTP 503 error:
+ </para>
+
+<programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.ConcurrentRequestTimeoutException"
+ log-level="trace">
+ <http-error error-code="503" />
+</exception>]]>
+</programlisting>
+ <note>
+ <title>503 Service Unavailable (HTTP/1.1 RFC)</title>
+ <para>
+ The server is currently unable to handle the request due to a temporary overloading or maintenance of the server. The implication is that this is a temporary condition which will be alleviated after some delay.
+ </para>
+ </note>
+ <para>
+ Alternatively you could redirect to an error page:
+ </para>
+
+<programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.ConcurrentRequestTimeoutException"
+ log-level="trace">
+ <end-conversation/>
+ <redirect view-id="/error.xhtml">
+ <message>
+ The server is too busy to process your request,
+ please try again later
+ </message>
+ </redirect>
+</exception>
+]]>
+</programlisting>
+ <para>
+ ICEfaces, RichFaces AJAX and Seam Remoting can all handle HTTP error codes. Seam Remoting will pop up a dialog box showing the HTTP error. ICEfaces will indicate the error in its connection status component. RichFaces provides the most complete support for handling HTTP errors by providing a user definable callback. For example, to show the error message to the user:
+ </para>
+
+<programlisting><![CDATA[<script type="text/javascript">
+ A4J.AJAX.onError = function(req,status,message) {
+ alert("An error occurred");
+ };
+</script>]]>
+</programlisting>
+ <para>
+ If, rather than an error code, the server reports that the view has expired, perhaps because a session timed out, use a separate callback function in RichFaces:
+ </para>
+
+<programlisting><![CDATA[<script type="text/javascript">
+ A4J.AJAX.onExpired = function(loc,message) {
+ alert("View expired");
+ };
+</script>
+]]>
+</programlisting>
+ <para>
+ Alternatively, you can allow RichFaces to handle the error. In this case, the user will receive a prompt reading, "View state could not be restored — reload page?" This message can be globally customized by setting the following message key in an application resource bundle:
+ </para>
+
+<programlisting><![CDATA[AJAX_VIEW_EXPIRED=View expired. Please reload the page.
+]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>RichFaces (Ajax4jsf)</title>
+ <para>
+ RichFaces (Ajax4jsf) is the most common AJAX library used with Seam, and provides all of the controls discussed in the previous section.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>eventsQueue</literal></term>
+ <listitem>
+ <para>
+ Provides a queue in which events are placed. All events are queued, and requests are sent to the server serially. This is useful if the request to the server can take some time to execute (for example, in heavy computation, retrieving information from a slow source) since it prevents server flooding.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>ignoreDupResponses</literal></term>
+ <listitem>
+ <para>
+ Ignores the response produced by a request if a more recent "similar" request is already queued. <literal>ignoreDupResponses="true"</literal> does <emphasis>not</emphasis> cancel the processing of the request on the server side; it only prevents unnecessary updates on the client side.
+ </para>
+ <para>
+ With Seam conversations, this option should be used with care, since it allows multiple concurrent requests.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>requestDelay</literal></term>
+ <listitem>
+ <para>
+ Defines the time in milliseconds that the request will remain on the queue. If, at this time, the request has not been processed, the request will either be sent (regardless of whether a response has been received), or discarded (if there is a more recent "similar" event queued).
+ </para>
+ <para>
+ With Seam conversations, this option should be used with care, as it allows multiple concurrent requests. The delay that you set (in combination with the concurrent request timeout) must be longer than the action will take to execute.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal><![CDATA[<a:poll reRender="total" interval="1000" />]]></literal></term>
+ <listitem>
+ <para>
+ Polls the server and rerenders an area, as required.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Dependencies.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Dependencies.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Dependencies.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,1084 +1,1557 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="dependencies">
- <title>Dependencies</title>
-
- <section id="jdk_dependencies">
- <title>JDK Dependencies</title>
-
- <para>
- Seam does not work with JDK 1.4 and requires JDK 5 or above as it uses
- annotations and other JDK 5.0 features. Seam has been thoroughly tested
- using Sun's JDKs. However there are no known issues specific to Seam with
- other JDKs.
- </para>
-
- <section id="jdk6_dependencies">
- <title>Sun's JDK 6 Considerations</title>
- <para>
- Earlier versions of Sun's JDK 6 contained an incompatible
- version of JAXB and required overriding it using the "endorsed"
- directory. Sun's JDK6 Update 4 release upgraded to JAXB 2.1 and
- removed this requirement. When building, testing, or executing be
- sure to use this version or higher.
- </para>
-
- <para>
- Seam used JBoss Embedded in its unit and integration testing. This
- has an additional requirement when using JDK 6. In order to run
- JBoss Embedded with JDK 6 you need to set the following JVM argument:
-
- <programlisting>-Dsun.lang.ClassLoader.allowArraySyntax=true</programlisting>
-
- Seam's internal build system is setting this by default when it
- executes Seam's test suite. However if you are also using JBoss
- Embedded for your testing you will need to set this value.
- </para>
- </section>
- </section>
-
- <section>
- <title>Project Dependencies</title>
+<!-- This Chapter has been updated on 04 November 2009 to reflect JBPAPP_5_0-CR5
+ sourced from:
+ https://svn.jboss.org/repos/seam/tags/JBPAPP_5_0-CR5/doc/Seam_Reference_Guide/en-US
+-->
- <para>
- This section both lists the compile-time and runtime dependencies for Seam.
- Where the type is listed as <literal>ear</literal>, the library should be
- included in the /lib directory of your application's ear file. Where the
- type is listed as <literal>war</literal>, the library should be placed in
- the <literal>/WEB-INF/lib</literal> directory of your application's war
- file. The scope of the dependency is either all, runtime or provided (by
- JBoss AS 4.2 or 5.0).
- </para>
-
- <para>
- Up to date version information and complete dependency information is not
- included in the docs, but is provided in the
- <literal>/dependency-report.txt</literal> which is generated from the
- Maven POMs stored in <literal>/build</literal>. You can generate this file
- by running <literal>ant dependencyReport</literal>.
- </para>
-
- <section>
- <title>Core</title>
-
- <para>
- <table><title></title>
- <tgroup cols="4">
- <colspec colnum="1" colwidth="4*" />
- <colspec colnum="2" colwidth="2*" />
- <colspec colnum="3" colwidth="3*" />
- <colspec colnum="4" colwidth="5*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Name</para>
- </entry>
- <entry align="center">
- <para>Scope</para>
- </entry>
- <entry align="center">
- <para>Type</para>
- </entry>
- <entry align="center">
- <para>Notes</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para><literal>jboss-seam.jar</literal></para>
- </entry>
- <entry align="center">
- <para>all</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para>The core Seam library, always required.</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jboss-seam-debug.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Include during development when enabling Seam's debug feature</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jboss-seam-ioc.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Required when using Seam with Spring</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jboss-seam-pdf.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Required when using Seam's PDF features</para>
- </entry>
- </row>
+<chapter id="dependencies" >
+ <title>Dependencies</title>
+ <section id="jdk_dependencies">
+ <title>Java Development Kit Dependencies</title>
+ <para>
+ Seam does not work with <trademark class="trade">JDK</trademark> (Java Development Kit) 1.4, and requires JDK 5 or higher to support annotations and other features. Seam has been thoroughly tested with other JDKs. There are no known issues that are specific to Seam.
+ </para>
+ <section id="jdk6_dependencies">
+ <title>Sun's JDK 6 Considerations</title>
+ <para>
+ The version of JAXB distributed with early versions of JDK 6 was incompatible with Seam, and had to be overridden. The upgrade to JAXB 2.1 (released in JDK 6 Update 4) resolved this issue. When building, testing, or executing, be sure to use this version or higher.
+ </para>
+ <para>
+ Seam uses Embedded JBoss in its unit and integration testing. When using Embedded JBoss with JDK 6, you must set the following JVM argument:
+ </para>
+
+<programlisting>-Dsun.lang.ClassLoader.allowArraySyntax=true
+</programlisting>
+ <para>
+ Seam's internal build system sets this by default when it executes Seam's test suite, but you must set this value manually when using Embedded JBoss.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Project Dependencies</title>
+ <para>
+ This section lists both compilation and runtime dependencies for Seam. For <filename>EAR</filename>-type dependencies, include the library in the <literal>/lib</literal> directory of your application's <filename>EAR</filename> file. For <filename>WAR</filename>-type dependencies, include the library in the <literal>/WEB-INF/lib</literal> directory of your application's <filename>WAR</filename> file. The scope of each dependency is either <emphasis>all</emphasis>, <emphasis>runtime</emphasis> or <emphasis>provided</emphasis> (by JBoss AS 4.2 or 5.0).
+ </para>
+ <para>
+ This documentation does not include up-to-date version information and complete dependency information —this information is provided in the <filename>/dependency-report.txt</filename> generated from the Maven POM stored in <literal>/build</literal>. You can generate this file by running <command>ant dependencyReport</command>.
+ </para>
+ <section>
+ <title>Core</title>
+ <para>
+ <table>
+ <title></title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="4*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <colspec colnum="4" colwidth="5*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Name
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Scope
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Notes
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <filename>jboss-seam.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ all
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The core Seam library. Always required.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jboss-seam-debug.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Include during development when enabling Seam's debug feature.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jboss-seam-ioc.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required when using Seam with Spring.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jboss-seam-pdf.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required when using Seam's PDF features.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jboss-seam-excel.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required when using Seam's <trademark class="registered">Microsoft</trademark> <trademark class="registered">Excel</trademark> features.
+ </para>
+ </entry>
+ </row>
+ <!--
+ <row>
+ <entry>
+ <para>
+ <filename>jboss-seam-rss.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required when using Seam's RSS generation features.
+ </para>
+ </entry>
+ </row>
+ -->
+ <row>
+ <entry>
+ <para>
+ <filename>jboss-seam-remoting.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required when using Seam Remoting.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jboss-seam-ui.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required to use the Seam JavaServer Faces (JSF) controls.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jsf-api.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ provided
+ </para>
+ </entry>
+ <entry align="center">
- <row>
- <entry>
- <para><literal>jboss-seam-excel.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Required when using Seam's <trademark class="registered">Microsoft</trademark> <trademark class="registered">Excel</trademark> features</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jboss-seam-remoting.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Required when using Seam Remoting</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jboss-seam-ui.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Required to use the Seam JSF controls</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jsf-api.jar</literal></para>
- </entry>
- <entry align="center">
- <para>provided</para>
- </entry>
- <entry align="center">
- <para></para>
- </entry>
- <entry>
- <para>JSF API</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jsf-impl.jar</literal></para>
- </entry>
- <entry align="center">
- <para>provided</para>
- </entry>
- <entry align="center">
- <para></para>
- </entry>
- <entry>
- <para>JSF Reference Implementation</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jsf-facelets.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Facelets</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>urlrewritefilter.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>URL Rewrite library</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>quartz.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para>Required when you wish to use Quartz with Seam's asynchronous features</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-</para>
+ </entry>
+ <entry>
+ <para>
+ JSF API.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jsf-impl.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ provided
+ </para>
+ </entry>
+ <entry align="center">
- </section>
-
- <section>
- <title>RichFaces</title>
-
- <table>
- <title>RichFaces dependencies</title>
-
- <tgroup cols="4">
- <colspec colnum="1" colwidth="4*" />
- <colspec colnum="2" colwidth="2*" />
- <colspec colnum="3" colwidth="3*" />
- <colspec colnum="4" colwidth="5*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Name</para>
- </entry>
- <entry align="center">
- <para>Scope</para>
- </entry>
- <entry align="center">
- <para>Type</para>
- </entry>
- <entry align="center">
- <para>Notes</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para><literal>richfaces-api.jar</literal></para>
- </entry>
- <entry align="center">
- <para>all</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para>
- Required to use RichFaces. Provides API classes that you may
- wish to use from your application e.g. to create a tree
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>richfaces-impl.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Required to use RichFaces.</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>richfaces-ui.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Required to use RichFaces. Provides all the UI components.</para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>Seam Mail</title>
-
- <table>
- <title>Seam Mail Dependencies</title>
-
- <tgroup cols="4">
- <colspec colnum="1" colwidth="4*" />
- <colspec colnum="2" colwidth="2*" />
- <colspec colnum="3" colwidth="3*" />
- <colspec colnum="4" colwidth="5*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Name</para>
- </entry>
- <entry align="center">
- <para>Scope</para>
- </entry>
- <entry align="center">
- <para>Type</para>
- </entry>
- <entry align="center">
- <para>Notes</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para><literal>activation.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para>Required for attachment support</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>mail.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para>Required for outgoing mail support</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>mail-ra.jar</literal></para>
- </entry>
- <entry align="center">
- <para>compile only</para>
- </entry>
- <entry align="center">
- <para></para>
- </entry>
- <entry>
- <para>Required for incoming mail support</para>
- <para>mail-ra.rar should be deployed to the application server
- at runtime</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jboss-seam-mail.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Seam Mail</para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>Seam PDF</title>
-
- <table>
- <title>Seam PDF Dependencies</title>
-
- <tgroup cols="4">
- <colspec colnum="1" colwidth="4*" />
- <colspec colnum="2" colwidth="2*" />
- <colspec colnum="3" colwidth="3*" />
- <colspec colnum="4" colwidth="5*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Name</para>
- </entry>
- <entry align="center">
- <para>Type</para>
- </entry>
- <entry align="center">
- <para>Scope</para>
- </entry>
- <entry align="center">
- <para>Notes</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para><literal>itext.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>PDF Library</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jfreechart.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Charting library</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jcommon.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Required by JFreeChart</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jboss-seam-pdf.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Seam PDF core library</para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </section>
+ </entry>
+ <entry>
+ <para>
+ JSF Reference Implementation.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jsf-facelets.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Facelets.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <!-- Edit to (JBPAPP_5_0-CR5) -->
+ <!-- <filename>urlrewrite.jar</filename> -->
+ <literal>urlrewritefilter.jar</literal>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ URL Rewrite library.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>quartz.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required when using Quartz with Seam's asynchronous features.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </para>
+ </section>
+
+ <section>
+ <title>RichFaces</title>
+ <table>
+ <title>RichFaces dependencies</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="4*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <colspec colnum="4" colwidth="5*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Name
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Scope
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Notes
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <filename>richfaces-api.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ all
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required to use RichFaces. Provides API classes that can be used from your application, for example, to create a tree.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>richfaces-impl.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required to use RichFaces.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>richfaces-ui.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required to use RichFaces. Provides all the UI components.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Seam Mail</title>
+ <table>
+ <title>Seam Mail Dependencies</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="4*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <colspec colnum="4" colwidth="5*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Name
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Scope
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Notes
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <filename>activation.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required for attachment support.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>mail.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required for outgoing mail support.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>mail-ra.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ compile only
+ </para>
+ </entry>
+ <entry align="center">
- <section>
- <title>Seam <trademark class="registered">Microsoft</trademark> <trademark class="registered">Excel</trademark></title>
-
- <table>
- <title>Seam <trademark class="registered">Microsoft</trademark> <trademark class="registered">Excel</trademark> Dependencies</title>
-
- <tgroup cols="4">
- <colspec colnum="1" colwidth="4*" />
- <colspec colnum="2" colwidth="2*" />
- <colspec colnum="3" colwidth="3*" />
- <colspec colnum="4" colwidth="5*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Name</para>
- </entry>
- <entry align="center">
- <para>Type</para>
- </entry>
- <entry align="center">
- <para>Scope</para>
- </entry>
- <entry align="center">
- <para>Notes</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para><literal>jxl.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>JExcelAPI library</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>jboss-seam-excel.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>Seam <trademark class="registered">Microsoft</trademark> <trademark class="registered">Excel</trademark> core library</para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </section>
+ </entry>
+ <entry>
+ <para>
+ Required for incoming mail support. <filename>mail-ra.rar</filename> should be deployed to the application server at runtime.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jboss-seam-mail.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Seam Mail.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Seam PDF</title>
+ <table>
+ <title>Seam PDF Dependencies</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="4*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <colspec colnum="4" colwidth="5*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Name
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Scope
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Notes
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <filename>itext.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ PDF Library
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jfreechart.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Charting library.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jcommon.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required by JFreeChart.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jboss-seam-pdf.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Seam PDF core library.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Seam <trademark class="registered">Microsoft</trademark> <trademark class="registered">Excel</trademark></title>
+ <table>
+ <title>Seam <trademark class="registered">Microsoft</trademark> <trademark class="registered">Excel</trademark> Dependencies</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="4*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <colspec colnum="4" colwidth="5*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Name
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Scope
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Notes
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <filename>jxl.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ JExcelAPI library.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>jboss-seam-excel.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Seam <trademark class="registered">Microsoft</trademark> <trademark class="registered">Excel</trademark> core library.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+<!-- <section id="dependencies.rss">
+ <title>Seam RSS support</title>
+ <table>
+ <title>Seam RSS Dependencies</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="4*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <colspec colnum="4" colwidth="5*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Name
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Scope
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Notes
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <filename>yarfraw.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ YARFRAW RSS library.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>JAXB</literal>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ JAXB XML parsing libraries.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>http-client.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Apache HTTP Client libraries.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>commons-io</literal>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Apache commons IO library.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>commons-lang</literal>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Apache commons language library.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>commons-codec</literal>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Apache commons codec library.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>commons-collections</literal>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Apache commons collections library.
+ </para>
+ </entry>
+ </row>
+ TODO: Should the above be labeled .jar (or whatever) for consistency? <row>
+ <entry>
+ <para>
+ <filename>jboss-seam-rss.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Seam RSS core library.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>-->
+ <!-- Section below partially updated to (JBPAPP_5_0-CR5) -->
+ <section>
+ <title>JBoss Rules</title>
+ <para>
+ The JBoss Rules (Drools) libraries can be found in the <literal>drools/lib</literal> directory in Seam.
+ </para>
+ <table>
+ <title>JBoss Rules Dependencies</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="4*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <colspec colnum="4" colwidth="5*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Name
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Scope
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Notes
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <filename>antlr-runtime.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ ANTLR Runtime Library.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>core.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Eclipse JDT.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para><literal>drools-api.jar</literal></para>
+ </entry>
+ <entry align="center">
+ <para>runtime</para>
+ </entry>
+ <entry align="center">
+ <para>EAR</para>
+ </entry>
+ <entry>
+ <para></para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>drools-compiler.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
- <section>
- <title>JBoss Rules</title>
-
- <para>
- The JBoss Rules libraries can be found in the <literal>drools/lib</literal> directory in Seam.
- </para>
-
- <table>
- <title>JBoss Rules Dependencies</title>
-
- <tgroup cols="4">
- <colspec colnum="1" colwidth="4*" />
- <colspec colnum="2" colwidth="2*" />
- <colspec colnum="3" colwidth="3*" />
- <colspec colnum="4" colwidth="5*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Name</para>
- </entry>
- <entry align="center">
- <para>Scope</para>
- </entry>
- <entry align="center">
- <para>Type</para>
- </entry>
- <entry align="center">
- <para>Notes</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para><literal>antlr-runtime.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para>ANTLR Runtime Library</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>core.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para>Eclipse JDT</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>drools-api.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para></para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>drools-compiler.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para></para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>drools-core.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para></para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>drools-decisiontables.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para></para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>drools-templates.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para></para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>janino.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para></para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para><literal>mvel2.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para></para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section>
- <title>JBPM</title>
-
- <table>
- <title>JBPM dependencies</title>
-
- <tgroup cols="4">
- <colspec colnum="1" colwidth="4*" />
- <colspec colnum="2" colwidth="2*" />
- <colspec colnum="3" colwidth="3*" />
- <colspec colnum="4" colwidth="5*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Name</para>
- </entry>
- <entry align="center">
- <para>Scope</para>
- </entry>
- <entry align="center">
- <para>Type</para>
- </entry>
- <entry align="center">
- <para>Notes</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para><literal>jbpm-jpdl.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para></para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section>
- <title>GWT</title>
-
- <para>
- These libraries are required if you with to use the Google Web Toolkit (GWT) with your Seam application.
- </para>
-
- <table>
- <title>GWT dependencies</title>
-
- <tgroup cols="4">
- <colspec colnum="1" colwidth="4*" />
- <colspec colnum="2" colwidth="2*" />
- <colspec colnum="3" colwidth="3*" />
- <colspec colnum="4" colwidth="5*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Name</para>
- </entry>
- <entry align="center">
- <para>Scope</para>
- </entry>
- <entry align="center">
- <para>Type</para>
- </entry>
- <entry align="center">
- <para>Notes</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <para><literal>gwt-servlet.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>war</para>
- </entry>
- <entry>
- <para>The GWT Servlet libs</para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section>
- <title>Spring</title>
-
- <para>
- These libraries are required if you with to use the Spring Framework with your Seam application.
- </para>
-
- <table>
- <title>Spring Framework dependencies</title>
-
- <tgroup cols="4">
- <colspec colnum="1" colwidth="4*" />
- <colspec colnum="2" colwidth="2*" />
- <colspec colnum="3" colwidth="3*" />
- <colspec colnum="4" colwidth="5*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Name</para>
- </entry>
- <entry align="center">
- <para>Scope</para>
- </entry>
- <entry align="center">
- <para>Type</para>
- </entry>
- <entry align="center">
- <para>Notes</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <para><literal>spring.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para>The Spring Framework library</para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section>
- <title>Groovy</title>
-
- <para>
- These libraries are required if you with to use Groovy with your Seam application.
- </para>
-
- <table>
- <title>Groovy dependencies</title>
-
- <tgroup cols="4">
- <colspec colnum="1" colwidth="4*" />
- <colspec colnum="2" colwidth="2*" />
- <colspec colnum="3" colwidth="3*" />
- <colspec colnum="4" colwidth="5*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Name</para>
- </entry>
- <entry align="center">
- <para>Scope</para>
- </entry>
- <entry align="center">
- <para>Type</para>
- </entry>
- <entry align="center">
- <para>Notes</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <para><literal>groovy-all.jar</literal></para>
- </entry>
- <entry align="center">
- <para>runtime</para>
- </entry>
- <entry align="center">
- <para>ear</para>
- </entry>
- <entry>
- <para>The Groovy libs</para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </section>
- </section>
-
- <section>
- <title>Dependency Management using Maven</title>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para>
+ <filename>drools-core.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
-
- <para>
- Maven offers support for transitive dependency management and can be used
- to manage the dependencies of your Seam project. You can use Maven Ant
- Tasks to integrate Maven into your Ant build, or can use Maven to build and
- deploy your project.
- </para>
-
- <para>
- We aren't actually going to discuss how to use Maven here, but just run
- over some basic POMs you could use.
- </para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><literal>drools-decisiontables.jar</literal></para>
+ </entry>
+ <entry align="center">
+ <para>runtime</para>
+ </entry>
+ <entry align="center">
+ <para>EAR</para>
+ </entry>
+ <entry>
+ <para></para>
+ </entry>
+ </row>
+
+ <row>
+ <entry>
+ <para><literal>drools-templates.jar</literal></para>
+ </entry>
+ <entry align="center">
+ <para>runtime</para>
+ </entry>
+ <entry align="center">
+ <para>EAR</para>
+ </entry>
+ <entry>
+ <para></para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>janino.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
- <para>
- Released versions of Seam are available in <ulink url="http://repository.jboss.org/maven2">
- http://repository.jboss.org/maven2</ulink>
- and nightly snapshots are available in <ulink url="http://snapshots.jboss.org/maven2">
- http://snapshots.jboss.org/maven2</ulink>.
- </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <filename>mvel2.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
- <para>
- All the Seam artifacts are available in Maven:
- </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>JBPM</title>
+ <table>
+ <title>JBPM dependencies</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="4*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <colspec colnum="4" colwidth="5*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Name
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Scope
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Notes
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <filename>jbpm-jpdl.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
- <programlisting role="XML"><![CDATA[<dependency>
- <groupId>org.jboss.seam</groupId>
- <artifactId>jboss-seam</artifactId>
-</dependency>]]></programlisting>
-
-<programlisting role="XML"><![CDATA[<dependency>
- <groupId>org.jboss.seam</groupId>
- <artifactId>jboss-seam-ui</artifactId>
-</dependency>]]></programlisting>
-
-<programlisting role="XML"><![CDATA[<dependency>
- <groupId>org.jboss.seam</groupId>
- <artifactId>jboss-seam-pdf</artifactId>
-</dependency>]]></programlisting>
-
-<programlisting role="XML"><![CDATA[<dependency>
- <groupId>org.jboss.seam</groupId>
- <artifactId>jboss-seam-remoting</artifactId>
-</dependency>]]></programlisting>
-
-<programlisting role="XML"><![CDATA[<dependency>
- <groupId>org.jboss.seam</groupId>
- <artifactId>jboss-seam-ioc</artifactId>
-</dependency>]]></programlisting>
-
-<programlisting role="XML"><![CDATA[<dependency>
- <groupId>org.jboss.seam</groupId>
- <artifactId>jboss-seam-ioc</artifactId>
-</dependency>]]></programlisting>
-
- <para>
- This sample POM will give you Seam, JPA (provided by Hibernate),
- Hibernate Validator and Hibernate Search:
- </para>
-
-<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>GWT</title>
+ <para>
+ These libraries are required to use the Google Web Toolkit (GWT) with your Seam application.
+ </para>
+ <table>
+ <title>GWT dependencies</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="4*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <colspec colnum="4" colwidth="5*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Name
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Scope
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Notes
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <filename>gwt-servlet.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>WAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The GWT Servlet libraries.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Spring</title>
+ <para>
+ These libraries are required to use the Spring Framework with your Seam application.
+ </para>
+ <table>
+ <title>Spring Framework dependencies</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="4*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <colspec colnum="4" colwidth="5*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Name
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Scope
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Notes
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <filename>spring.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The Spring Framework library.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Groovy</title>
+ <para>
+ These libraries are required to use Groovy with your Seam application.
+ </para>
+ <table>
+ <title>Groovy dependencies</title>
+ <tgroup cols="4">
+ <colspec colnum="1" colwidth="4*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <colspec colnum="4" colwidth="5*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Name
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Scope
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Notes
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <filename>groovy-all.jar</filename>
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ runtime
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ <filename>EAR</filename>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The Groovy libraries.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Dependency Management using Maven</title>
+ <para>
+ Maven supports transitive dependency management, and can be used to manage your project's dependencies. You can integrate Maven into your Ant build with Maven Ant Tasks, or use Maven to build and deploy your project.
+ </para>
+ <para>
+ This section will not tell you how to use Maven. Instead, we will show you some basic Project Object Models (POMs) you can use.
+ </para>
+ <para>
+ Released versions of Maven are available in <ulink url="http://repository.jboss.org/maven2">http://repository.jboss.org/maven2 </ulink>, and nightly snapshots are available in <ulink url="http://snapshots.jboss.org/maven2">http://snapshots.jboss.org/maven2</ulink>.
+ </para>
+ <para>
+ All Seam artifacts are available in Maven:
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<dependency>
+ <groupId>org.jboss.seam</groupId>
+ <artifactId>jboss-seam</artifactId>
+</dependency>]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[
+<dependency>
+ <groupId>org.jboss.seam</groupId>
+ <artifactId>jboss-seam-ui</artifactId>
+</dependency>]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[
+<dependency>
+ <groupId>org.jboss.seam</groupId>
+ <artifactId>jboss-seam-pdf</artifactId>
+</dependency>]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[
+<dependency>
+ <groupId>org.jboss.seam</groupId>
+ <artifactId>jboss-seam-remoting</artifactId>
+</dependency>]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[
+<dependency>
+ <groupId>org.jboss.seam</groupId>
+ <artifactId>jboss-seam-ioc</artifactId>
+</dependency>]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[
+<dependency>
+ <groupId>org.jboss.seam</groupId>
+ <artifactId>jboss-seam-ioc</artifactId>
+</dependency>]]>
+</programlisting>
+ <para>
+ The following sample POM will give you Seam, a JPA (provided by Hibernate), Hibernate Validator and Hibernate Search:
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<?xml version="1.0" encoding="UTF-8"?>
<project xmlns="http://maven.apache.org/POM/4.0.0"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/maven-v4_0_0.xsd">
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="http://maven.apache.org/POM/4.0.0
+ http://maven.apache.org/maven-v4_0_0.xsd">
<modelVersion>4.0.0</modelVersion>
<groupId>org.jboss.seam.example/groupId>
<artifactId>my-project</artifactId>
@@ -1091,16 +1564,16 @@
<name>JBoss Repository</name>
<url>http://repository.jboss.org/maven2</url>
</repository>
+
</repositories>
<dependencies>
-
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-validator</artifactId>
<version>3.1.0.GA</version>
</dependency>
-
+
<dependency>
<groupId>org.hibernate</groupId>
<artifactId>hibernate-annotations</artifactId>
@@ -1114,9 +1587,9 @@
</dependency>
<dependency>
- <groupId>org.hibernate</groupId>
- <artifactId>hibernate-search</artifactId>
- <version>3.1.1.GA</version>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-search</artifactId>
+ <version>3.1.1.GA</version>
</dependency>
<dependency>
@@ -1124,11 +1597,12 @@
<artifactId>jboss-seam</artifactId>
<version>2.2.0.GA</version>
</dependency>
-
+
</dependencies>
-</project>]]></programlisting>
+</project>]]>
+</programlisting>
+ </section>
+
+</chapter>
-</section>
-
-</chapter>
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Drools.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Drools.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Drools.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,274 +1,237 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="drools">
- <title>Seam and JBoss Rules</title>
-
- <para>
- Seam makes it easy to call JBoss Rules (Drools) rulebases from Seam
- components or jBPM process definitions.
- </para>
-
- <section>
- <title>Installing rules</title>
-
- <para>
- The first step is to make an instance of <literal>org.drools.RuleBase</literal>
- available in a Seam context variable. For testing purposes, Seam provides a built-in component
- that compiles a static set of rules from the classpath. You can install
- this component via <literal>components.xml</literal>:
- </para>
+<chapter id="drools" >
+ <title>Seam and JBoss Rules</title>
+ <para>
+ Seam makes it easy to call JBoss Rules (Drools) rulebases from Seam components or jBPM process definitions.
+ </para>
+ <section>
+ <title>Installing rules</title>
+ <para>
+ The first step is to make an instance of <literal>org.drools.RuleBase</literal> available in a Seam context variable. For testing purposes, Seam provides a built-in component that compiles a static set of rules from the classpath. You can install this component via <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<drools:rule-base name="policyPricingRules">
+ <drools:rule-files>
+ <value>policyPricingRules.drl</value>
+ </drools:rule-files>
+</drools:rule-base>]]>
+</programlisting>
+ <para>
+ This component compiles rules from a set of DRL (<literal>.drl</literal>) or decision table (<literal>.xls</literal>) files and caches an instance of <literal>org.drools.RuleBase</literal> in the Seam <literal>APPLICATION</literal> context. Note that you will likely need to install multiple rule bases in a rule-driven application.
+ </para>
+ <para>
+ If you want to use a Drools DSL, you must also specify the DSL definition:
+ </para>
+
+<programlisting role="XML"><![CDATA[<drools:rule-base name="policyPricingRules" dsl-file="policyPricing.dsl">
+ <drools:rule-files>
+ <value>policyPricingRules.drl</value>
+ </drools:rule-files>
+</drools:rule-base>]]>
+</programlisting>
- <programlisting role="XML"><![CDATA[<drools:rule-base name="policyPricingRules">
- <drools:rule-files>
- <value>policyPricingRules.drl</value>
- </drools:rule-files>
-</drools:rule-base>]]></programlisting>
-
- <para>
- This component compiles rules from a set of DRL (<literal>.drl</literal>) or decision table (<literal>.xls</literal>)
- files and caches an instance of <literal>org.drools.RuleBase</literal>
- in the Seam <literal>APPLICATION</literal> context. Note that it is
- quite likely that you will need to install multiple rule bases in a
- rule-driven application.
+ <para>
+ If you want to register a custom consequence exception handler through the RuleBaseConfiguration, you need to write the handler. This is demonstrated in the following example:
</para>
- <para>
- If you want to use a Drools DSL, you alse need to specify the DSL
- definition:
- </para>
-
- <programlisting role="XML"><![CDATA[<drools:rule-base name="policyPricingRules" dsl-file="policyPricing.dsl">
- <drools:rule-files>
- <value>policyPricingRules.drl</value>
- </drools:rule-files>
-</drools:rule-base>]]></programlisting>
-
- <para>
- If you want to register a custom consequence exception handler through the RuleBaseConfiguration, you need to
- write the handler, for example:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Scope(ScopeType.APPLICATION)
+<programlisting role="JAVA"><![CDATA[@Scope(ScopeType.APPLICATION)
@Startup
@Name("myConsequenceExceptionHandler")
-public class MyConsequenceExceptionHandler implements ConsequenceExceptionHandler, Externalizable {
+public class MyConsequenceExceptionHandler
+ implements ConsequenceExceptionHandler, Externalizable {
+ public void readExternal(ObjectInput in) throws IOException,
+ ClassNotFoundException { }
- public void readExternal(ObjectInput in) throws IOException, ClassNotFoundException {
- }
+ public void writeExternal(ObjectOutput out) throws IOException { }
- public void writeExternal(ObjectOutput out) throws IOException {
- }
+ public void handleException(Activation activation,
+ WorkingMemory workingMemory,
+ Exception exception) {
+ throw new ConsequenceException( exception, activation.getRule() );
+ }
- public void handleException(Activation activation,
- WorkingMemory workingMemory,
- Exception exception) {
- throw new ConsequenceException( exception,
- activation.getRule() );
- }
-
}]]></programlisting>
-
<para>
and register it:
</para>
- <programlisting role="XML"><![CDATA[<drools:rule-base name="policyPricingRules" dsl-file="policyPricing.dsl" consequence-exception-handler="#{myConsequenceExceptionHandler}">
- <drools:rule-files>
- <value>policyPricingRules.drl</value>
- </drools:rule-files>
+<programlisting role="XML"><![CDATA[<drools:rule-base name="policyPricingRules"
+ dsl-file="policyPricing.dsl"
+ consequence-exception-handler=
+ "#{myConsequenceExceptionHandler}">
+ <drools:rule-files>
+ <value>policyPricingRules.drl</value>
+ </drools:rule-files>
</drools:rule-base>]]></programlisting>
- <para>
- In most rules-driven applications,
- rules need to be dynamically deployable, so a production application will want to use a
- Drools RuleAgent to manage the RuleBase. The RuleAgent can connect to a Drools rule server (BRMS)
- or hot deploy rules packages from a local file repository. The RulesAgent-managed RuleBase is
- also configurable in <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<drools:rule-agent name="insuranceRules"
- configurationFile="/WEB-INF/deployedrules.properties" />]]></programlisting>
-
- <para>The properties file contains properties specific to the RulesAgent. Here is an example configuration file from the
- Drools example distribution.</para>
-
- <programlisting>newInstance=true
-url=http://localhost:8080/drools-jbrms/org.drools.brms.JBRMS/package/org.acme.insurance/fmeyer
-localCacheDir=/Users/fernandomeyer/projects/jbossrules/drools-examples/drools-examples-brms/cache
-poll=30
-name=insuranceconfig</programlisting>
-
-
- <para>It is also possible to configure the options on the component directly, bypassing the configuration file.</para>
-
- <programlisting role="XML"><![CDATA[<drools:rule-agent name="insuranceRules"
- url="http://localhost:8080/drools-jbrms/org.drools.brms.JBRMS/package/org.acme.insurance/fmeyer"
- local-cache-dir="/Users/fernandomeyer/projects/jbossrules/drools-examples/drools-examples-brms/cache"
- poll="30"
- configuration-name="insuranceconfig" />]]></programlisting>
-
- <para>
- Next, we need to make an instance of <literal>org.drools.WorkingMemory</literal>
- available to each conversation. (Each <literal>WorkingMemory</literal>
- accumulates facts relating to the current conversation.)
+ <para>
+ In most rules-driven applications, rules must be dynamically deployable. A Drools RuleAgent is useful to manage the RuleBase. The RuleAgent can connect to a Drools rule server (BRMS), or hot-deploy rules packages from a local file repository. The RulesAgent-managed RuleBase is also configurable via <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<drools:rule-agent name="insuranceRules"
+ configurationFile="/WEB-INF/deployedrules.properties" />]]>
+</programlisting>
+ <para>
+ The properties file contains properties specific to the RulesAgent. The following is an example configuration file from the Drools example distribution:
+ </para>
+
+<programlisting><![CDATA[newInstance=true
+url=http://localhost:8080/drools-jbrms/org.drools.brms.JBRMS/package/
+ org.acme.insurance/fmeyer
+localCacheDir=/Users/fernandomeyer/projects/jbossrules/drools-examples/
+ drools-examples-brms/cache
+poll=30
+name=insuranceconfig]]>
+</programlisting>
+ <para>
+ It is also possible to configure the options on the component directly, bypassing the configuration file.
+ </para>
+
+<programlisting role="XML"><![CDATA[<drools:rule-agent name="insuranceRules"
+ url="http://localhost:8080/drools-jbrms/org.drools.brms.JBRMS/
+ package/org.acme.insurance/fmeyer"
+ local-cache-dir="/Users/fernandomeyer/projects/jbossrules/
+ drools-examples/drools-examples-brms/cache"
+ poll="30"
+ configuration-name="insuranceconfig" />]]>
+</programlisting>
+ <para>
+ Next, make an instance of <literal>org.drools.WorkingMemory</literal> available to each conversation. (Each <literal>WorkingMemory</literal> accumulates facts relating to the current conversation.)
+ </para>
+
+<programlisting role="XML"><![CDATA[<drools:managed-working-memory name="policyPricingWorkingMemory"
+ auto-create="true" rule-base="#{policyPricingRules}"/>]]>
+</programlisting>
+ <para>
+ Notice that we referred the <literal>policyPricingWorkingMemory</literal> back to our rule base via the <literal>ruleBase</literal> configuration property.
+ </para>
+
+ <para>
+ We can also add means to be notified of rule engine events, including, for example, rules firing or objects being asserted by adding event listeners to WorkingMemory.
</para>
-
- <programlisting role="XML"><![CDATA[<drools:managed-working-memory name="policyPricingWorkingMemory" auto-create="true" rule-base="#{policyPricingRules}"/>]]></programlisting>
-
- <para>
- Notice that we gave the <literal>policyPricingWorkingMemory</literal> a
- reference back to our rule base via the <literal>ruleBase</literal>
- configuration property.
- </para>
-
- <para>
- We can also add means to be notified of rule engine events, including rules firing, objects being asserted, etc.
- by adding event listeners to WorkingMemory.
- </para>
-
- <programlisting role="XML"><![CDATA[<drools:managed-working-memory name="policyPricingWorkingMemory" auto-create="true" rule-base="#{policyPricingRules}">
- <drools:event-listeners>
- <value>org.drools.event.DebugWorkingMemoryEventListener</value>
- <value>org.drools.event.DebugAgendaEventListener</value>
- </drools:event-listeners>
+
+<programlisting role="XML"><![CDATA[
+<drools:managed-working-memory name="policyPricingWorkingMemory"
+ auto-create="true"
+ rule-base="#{policyPricingRules}">
+ <drools:event-listeners>
+ <value>org.drools.event.DebugWorkingMemoryEventListener</value>
+ <value>org.drools.event.DebugAgendaEventListener</value>
+ </drools:event-listeners>
</drools:managed-working-memory>]]></programlisting>
- </section>
-
- <section>
- <title>Using rules from a Seam component</title>
-
- <para>
- We can now inject our <literal>WorkingMemory</literal> into any Seam component,
- assert facts, and fire rules:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@In WorkingMemory policyPricingWorkingMemory;
+ </section>
+
+ <section>
+ <title>Using rules from a Seam component</title>
+ <para>
+ We can now inject our <literal>WorkingMemory</literal> into any Seam component, assert facts, and fire rules:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In WorkingMemory policyPricingWorkingMemory;
+ at In Policy policy;
+ at In Customer customer;
- at In Policy policy;
- at In Customer customer;
-
-public void pricePolicy() throws FactException
-{
- policyPricingWorkingMemory.insert(policy);
- policyPricingWorkingMemory.insert(customer);
- policyPricingWorkingMemory.fireAllRules();
-}]]></programlisting>
-
- </section>
-
- <section>
- <title>Using rules from a jBPM process definition</title>
-
- <para>
- You can even allow a rule base to act as a jBPM action handler, decision
- handler, or assignment handler — in either a pageflow or business
- process definition.
- </para>
-
- <programlisting role="XML"><![CDATA[<decision name="approval">
-
- <handler class="org.jboss.seam.drools.DroolsDecisionHandler">
- <workingMemoryName>orderApprovalRulesWorkingMemory</workingMemoryName>
- <assertObjects>
- <element>#{customer}</element>
- <element>#{order}</element>
- <element>#{order.lineItems}</element>
- </assertObjects>
- </handler>
+public void pricePolicy() throws FactException {
+ policyPricingWorkingMemory.insert(policy);
+ policyPricingWorkingMemory.insert(customer);
+ policyPricingWorkingMemory.fireAllRules();
+}]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Using rules from a jBPM process definition</title>
+ <para>
+ A rule base can act as a jBPM action, decision, or assignment handler in either a pageflow or a business process definition.
+ </para>
+
+<programlisting role="XML"><![CDATA[<decision name="approval">
+ <handler class="org.jboss.seam.drools.DroolsDecisionHandler">
+ <workingMemoryName>orderApprovalRulesWorkingMemory</workingMemoryName>
+ <assertObjects>
+ <element>#{customer}</element>
+ <element>#{order}</element>
+ <element>#{order.lineItems}</element>
+ </assertObjects>
+ </handler>
- <transition name="approved" to="ship">
- <action class="org.jboss.seam.drools.DroolsActionHandler">
- <workingMemoryName>shippingRulesWorkingMemory</workingMemoryName>
- <assertObjects>
- <element>#{customer}</element>
- <element>#{order}</element>
- <element>#{order.lineItems}</element>
- </assertObjects>
- </action>
- </transition>
-
- <transition name="rejected" to="cancelled"/>
-
-</decision>]]></programlisting>
-
- <para>
- The <literal><assertObjects></literal> element specifies EL expressions that
- return an object or collection of objects to be asserted as facts into the
- <literal>WorkingMemory</literal>.
- </para>
-
- <para>
- There is also support for using Drools for jBPM task assignments:
- </para>
-
- <programlisting role="XML"><![CDATA[<task-node name="review">
- <task name="review" description="Review Order">
- <assignment handler="org.jboss.seam.drools.DroolsAssignmentHandler">
- <workingMemoryName>orderApprovalRulesWorkingMemory</workingMemoryName>
- <assertObjects>
- <element>#{actor}</element>
- <element>#{customer}</element>
- <element>#{order}</element>
- <element>#{order.lineItems}</element>
- </assertObjects>
- </assignment>
- </task>
- <transition name="rejected" to="cancelled"/>
- <transition name="approved" to="approved"/>
-</task-node>]]></programlisting>
-
- <para>
- Certain objects are available to the rules as Drools globals, namely
- the jBPM <literal>Assignable</literal>, as <literal>assignable</literal>
- and a Seam <literal>Decision</literal> object, as <literal>decision</literal>.
- Rules which handle decisions should call <literal>decision.setOutcome("result")</literal>
- to determine the result of the decision. Rules which perform assignments should
- set the actor id using the <literal>Assignable</literal>.
- </para>
-
- <programlisting><![CDATA[package org.jboss.seam.examples.shop
-
-import org.jboss.seam.drools.Decision
-
-global Decision decision
-
-rule "Approve Order For Loyal Customer"
- when
- Customer( loyaltyStatus == "GOLD" )
- Order( totalAmount <= 10000 )
- then
- decision.setOutcome("approved");
-end]]></programlisting>
-
- <programlisting><![CDATA[package org.jboss.seam.examples.shop
-
-import org.jbpm.taskmgmt.exe.Assignable
-
-global Assignable assignable
-
-rule "Assign Review For Small Order"
- when
- Order( totalAmount <= 100 )
- then
- assignable.setPooledActors( new String[] {"reviewers"} );
-end]]></programlisting>
-
- <note>
- <para>
- You can find out more about Drools at
- <ulink url="http://www.drools.org" />
- </para>
- </note>
-
- <caution>
- <para>
- Seam comes with enough of Drools' dependencies to implement some
- simple rules. If you want to add extra capabilities to Drools
- you should download the full distribution and add in extra
- dependencies as needed.
- </para>
- </caution>
-
- </section>
-
+ <transition name="approved" to="ship">
+ <action class="org.jboss.seam.drools.DroolsActionHandler">
+ <workingMemoryName>shippingRulesWorkingMemory</workingMemoryName>
+ <assertObjects>
+ <element>#{customer}</element>
+ <element>#{order}</element>
+ <element>#{order.lineItems}</element>
+ </assertObjects>
+ </action>
+ </transition>
+ <transition name="rejected" to="cancelled"/>
+</decision>]]>
+</programlisting>
+ <para>
+ The <literal><![CDATA[<assertObjects>]]></literal> element specifies EL expressions that return an object or collection of objects to be asserted as facts into the <literal>WorkingMemory</literal>.
+ </para>
+ <para>
+ Using Drools for jBPM task assignments is also supported:
+ </para>
+
+<programlisting role="XML"><![CDATA[<task-node name="review">
+ <task name="review" description="Review Order">
+ <assignment handler="org.jboss.seam.drools.DroolsAssignmentHandler">
+ <workingMemoryName>
+ orderApprovalRulesWorkingMemory
+ </workingMemoryName>
+ <assertObjects>
+ <element>#{actor}</element>
+ <element>#{customer}</element>
+ <element>#{order}</element>
+ <element>#{order.lineItems}</element>
+ </assertObjects>
+ </assignment>
+ </task>
+ <transition name="rejected" to="cancelled"/>
+ <transition name="approved" to="approved"/>
+</task-node>]]>
+</programlisting>
+ <para>
+ Certain objects are available as Drools globals — the jBPM <literal>Assignable</literal> is available as <literal>assignable</literal>, and the Seam <literal>Decision</literal> object is available as <literal>decision</literal>. Rules that handle decisions should call <literal>decision.setOutcome("result")</literal> to determine the decision result. Rules that perform assignments should set the actor ID with <literal>Assignable</literal>.
+ </para>
+
+<programlisting><![CDATA[package org.jboss.seam.examples.shop
+import org.jboss.seam.drools.Decision
+global Decision decision
+rule "Approve Order For Loyal Customer"
+ when
+ Customer( loyaltyStatus == "GOLD" )
+ Order( totalAmount <= 10000 )
+ then
+ decision.setOutcome("approved");
+end]]>
+</programlisting>
+
+<programlisting><![CDATA[package org.jboss.seam.examples.shop
+import org.jbpm.taskmgmt.exe.Assignable
+global Assignable assignable
+rule "Assign Review For Small Order"
+ when
+ Order( totalAmount <= 100 )
+ then
+ assignable.setPooledActors( new String[] {"reviewers"} );
+end]]>
+</programlisting>
+ <note>
+ <para>
+ More information about Drools is available at <ulink url="http://www.drools.org"></ulink>.
+ </para>
+ </note>
+ <important>
+ <para>
+ Seam comes packaged with enough Drools dependencies to implement some simple rules. To add extra capabilities, download the full Drools distribution and add extra dependencies as required.
+ </para>
+ </important>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Elenhancements.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Elenhancements.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Elenhancements.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,274 +1,193 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="elenhancements">
- <title>JBoss EL</title>
-
- <para>
- Seam uses JBoss EL which provides an extension to the standard Unified
- Expression Language (EL). JBoss EL provides a number of enhancements that
- increase the expressiveness and power of EL expressions.
- </para>
-
- <section>
- <title>Parameterized Expressions</title>
-
- <para>
- Standard EL does not allow you to use a method with user defined
- parameters — of course, JSF listener methods (e.g. a
- <literal>valueChangeListener</literal>) take parameters provided by JSF.
- </para>
-
- <para>
- JBoss EL removes this restriction. For example:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandButton action="#{hotelBooking.bookHotel(hotel)}" value="Book Hotel"/>]]></programlisting>
-
- <programlisting role="JAVA"><![CDATA[@Name("hotelBooking")
-public class HotelBooking {
-
- public String bookHotel(Hotel hotel) {
- // Book the hotel
- }
-}]]></programlisting>
-
- <section>
- <title>Usage</title>
-
- <para>
- Just as in calls to method from Java, parameters are surrounded by
- parentheses, and separated by commas:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandButton action="#{hotelBooking.bookHotel(hotel, user)}" value="Book Hotel"/>]]></programlisting>
-
- <para>
- The parameters <literal>hotel</literal> and <literal>user</literal>
- will be evaluated as value expressions and passed to the
- <literal>bookHotel()</literal> method of the component.
- </para>
- <para>
- Any value expression may be used as a parameter:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandButton
- action="#{hotelBooking.bookHotel(hotel.id, user.username)}"
- value="Book Hotel"/>]]></programlisting>
-
- <para>
- It's important to fully understand how this extension to EL works.
- When the page is rendered, the parameter <emphasis>names</emphasis>
- are stored (for example, <literal>hotel.id</literal> and
- <literal>user.username</literal>), and evaluated (as value
- expressions) when the page is submitted. You can't pass objects as
- parameters!
- </para>
-
- <para>
- You must ensure that the parameters are available not only when the
- page is rendered, but also when it is submittedIf the arguments can
- not be resolved when the page is submitted the action method will be
- called with <literal>null</literal> arguments!
- </para>
-
- <para>
- You can also pass literal strings using single quotes:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandLink action="#{printer.println('Hello world!')}" value="Hello"/>]]></programlisting>
-
- <para>
- Unified EL also supports value expressions, used to bind a field to
- a backing bean. Value expressions use JavaBean naming conventions
- and expect a getter/setter pair. Often JSF expects a value
- expression where only retrieval (get) is needed (e.g. the
- <literal>rendered</literal> attribute). Many objects, however, don't
- have appropriately named property accessors or require parameters.
- </para>
-
- <para>
- JBoss EL removes this restriction by allowing values to be retrieved
- using the method syntax. For example:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:outputText value="#{person.name}" rendered="#{person.name.length() > 5}" />]]></programlisting>
-
- <para>
- You can access the size of a collection in a similar manner:
- </para>
-
- <programlisting>#{searchResults.size()}</programlisting>
-
- <para>
- In general any expression of the form #{obj.property} would be
- identical to the expression #{obj.getProperty()}.
- </para>
- <para>
- Parameters are also allowed. The following example calls the
- <literal>productsByColorMethod</literal> with a literal string
- argument:
- </para>
-
- <programlisting>#{controller.productsByColor('blue')}</programlisting>
-
- </section>
-
- <section>
- <title>Limitations and Hints</title>
-
- <para>
- When using JBoss EL you should keep the following points in mind:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <emphasis>Incompatibility with JSP 2.1</emphasis> —
- JBoss EL can't currently be used with JSP 2.1 as the compiler
- rejects expressions with parameters in. So, if you want to use
- this extension with JSF 1.2, you will need to use Facelets.
- The extension works correctly with JSP 2.0.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Use inside iterative components</emphasis> —
- Components like <literal><c:forEach /></literal> and
- <literal><ui:repeat /></literal>iterate over a List or
- array, exposing each item in the list to nested components.
- This works great if you are selecting a row using a
- <literal><h:commandButton /></literal> or
- <literal><h:commandLink /></literal>:
- </para>
- <programlisting role="JAVA"><![CDATA[@Factory("items")
-public List<Item> getItems() {
- return entityManager.createQuery("select ...").getResultList();
-}]]></programlisting>
- <programlisting role="XHTML"><![CDATA[<h:dataTable value="#{items}" var="item">
- <h:column>
- <h:commandLink value="Select #{item.name}" action="#{itemSelector.select(item})" />
- </h:column>
-</h:dataTable>]]></programlisting>
- <para>
- However if you want to use <literal><s:link /></literal>
- or <literal><s:button /></literal> you
- <emphasis>must</emphasis> expose the items as a
- <literal>DataModel</literal>, and use a
- <literal><dataTable /></literal> (or equivalent from a
- component set like <literal><rich:dataTable /></literal>
- ). Neither <literal><s:link /></literal> or
- <literal><s:button /></literal> submit the form (and
- therefore produce a bookmarkable link) so a "magic" parameter
- is needed to recreate the item when the action method is
- called. This magic parameter can only be added when a
- data table backed by a <literal>DataModel</literal> is used.
- </para>
- </listitem>
- <listitem>
- <para>
- <emphasis>Calling a <literal>MethodExpression</literal> from
- Java code</emphasis> — Normally, when a
- <literal>MethodExpression</literal> is created, the parameter
- types are passed in by JSF. In the case of a method binding,
- JSF assumes that there are no parameters to pass. With this
- extension, we can't know the parameter types until after the
- expression has been evaluated. This has two minor
- consequences:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- When you invoke a <literal>MethodExpression</literal> in
- Java code, parameters you pass may be ignored.
- Parameters defined in the expression will take
- precedence.
- </para>
- </listitem>
- <listitem>
- <para>
- Ordinarily, it is safe to call
- <literal>methodExpression.getMethodInfo().getParamTypes()</literal>
- at any time. For an expression with parameters, you must
- first invoke the <literal>MethodExpression</literal>
- before calling <literal>getParamTypes()</literal>.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Both of these cases are exceedingly rare and only apply when
- you want to invoke the <literal>MethodExpression</literal> by
- hand in Java code.
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
-
- <section>
- <title>Projection</title>
-
- <para>
- JBoss EL supports a limited projection syntax. A projection expression
- maps a sub-expression across a multi-valued (list, set, etc...)
- expression. For instance, the expression:
- </para>
-
- <programlisting>#{company.departments}</programlisting>
-
- <para>
- might return a list of departments. If you only need a list of
- department names, your only option is to iterate over the list to
- retrieve the values. JBoss EL allows this with a projection expression:
- </para>
-
- <programlisting>#{company.departments.{d|d.name}}</programlisting>
-
- <para>
- The subexpression is enclosed in braces. In this example, the
- expression <literal>d.name</literal> is evaluated for each department,
- using <literal>d</literal> as an alias to the department object. The
- result of this expression will be a list of String values.
- </para>
-
- <para>
- Any valid expression can be used in an expression, so it would be
- perfectly valid to write the following, assuming you had a use for the
- lengths of all the department names in a company:
- </para>
-
- <programlisting>#{company.departments.{d|d.size()}}</programlisting>
-
- <para>
- Projections can be nested. The following expression returns the last
- names of every employee in every department:
- </para>
-
- <programlisting>#{company.departments.{d|d.employees.{emp|emp.lastName}}}</programlisting>
-
- <para>
- Nested projections can be slightly tricky, however. The following
- expression looks like it returns a list of all the employees in all the
- departments:
- </para>
-
- <programlisting>#{company.departments.{d|d.employees}}</programlisting>
-
- <para>
- However, it actually returns a list containing a list of the employees
- for each individual department. To combine the values, it is necessary
- to use a slightly longer expression:
- </para>
-
- <programlisting>#{company.departments.{d|d.employees.{e|e}}}</programlisting>
-
- <para>
- It is important to note that this syntax cannot be parsed by Facelets
- or JSP and thus cannot be used in xhtml or JSP files. We anticipate
- that the projection syntax will change in future versions of JBoss EL.
- </para>
-
- </section>
+<chapter id="elenhancements" >
+ <title>JBoss EL</title>
+ <para>
+ Seam uses JBoss EL to provide an extension to the standard Unified Expression Language (EL). This provides several enhancements to the expressiveness and power of EL expressions.
+ </para>
+ <section>
+ <title>Parameterized Expressions</title>
+ <para>
+ Standard EL does not allow methods to be used with user-defined parameters, but JBoss EL removoes this restriction. For example:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton action="#{hotelBooking.bookHotel(hotel)}"
+ value="Book Hotel"/>]]>
+</programlisting>
+
+<programlisting role="JAVA"><![CDATA[@Name("hotelBooking")
+public class HotelBooking {
+ public String bookHotel(Hotel hotel) {
+ // Book the hotel
+ }
+}]]>
+</programlisting>
+ <section>
+ <title>Usage</title>
+ <para>
+ As in method calls from Java, parameters are surrounded by parentheses, and separated by commas:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton action="#{hotelBooking.bookHotel(hotel, user)}"
+ value="Book Hotel"/>]]>
+</programlisting>
+ <para>
+ Here, the parameters <literal>hotel</literal> and <literal>user</literal> will be evaluated as value expressions and passed to the <literal>bookHotel()</literal> method of the component.
+ </para>
+ <para>
+ Any value expression can be used as a parameter:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton action="#{hotelBooking.bookHotel(hotel.id,
+ user.username)}"
+ value="Book Hotel"/>]]>
+</programlisting>
+ <para>
+ When the page is rendered, the parameter names —<literal>hotel.id</literal> and <literal>user.username</literal> —are stored, and evaluated as value expressions when the page is submitted. Objects cannot be passed as parameters.
+ </para>
+ <para>
+ Parameters must be available both when the page is rendered and when it is submitted. If the arguments cannot be resolved at page submission time, the action method will be called with <literal>null</literal> arguments.
+ </para>
+ <para>
+ You can also pass literal strings using single quotes:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandLink action="#{printer.println('Hello world!')}"
+ value="Hello"/>]]>
+</programlisting>
+ <para>
+ Unified EL also supports value expressions, which are used to bind a field to a backing bean. Value expressions use JavaBean naming conventions and expect a getter/setter pair. JSF often expects a value expression where only retrieval (get) is required (for example, in the <literal>rendered</literal> attribute), but many objects do not have appropriately named property accessors, or do not require parameters.
+ </para>
+ <para>
+ JBoss EL removes this restriction by allowing values to be retrieved using the method syntax. For example:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:outputText value="#{person.name}"
+ rendered="#{person.name.length() > 5}" />]]>
+</programlisting>
+ <para>
+ You can access the size of a collection in a similar manner:
+ </para>
+
+<programlisting>
+#{searchResults.size()}
+</programlisting>
+ <para>
+ In general, any expression of the form <literal>#{obj.property}</literal> would be identical to the expression <literal>#{obj.getProperty()}</literal>.
+ </para>
+ <para>
+ Parameters are also allowed. The following example calls the <literal>productsByColorMethod</literal> with a literal string argument:
+ </para>
+
+<programlisting>#{controller.productsByColor('blue')}
+</programlisting>
+ </section>
+
+ <section>
+ <title>Limitations and Hints</title>
+ <para>
+ JBoss EL does have several limitations:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <emphasis>Incompatibility with JSP 2.1</emphasis> —JBoss EL cannot currently be used with JSP 2.1, because the compiler rejects expressions that include parameters. You will need Facelets if you want to use this extension with JSF 1.2. The extension works correctly with JSP 2.0.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Use inside iterative components</emphasis> —Components like <literal><![CDATA[<c:forEach />]]></literal> and <literal><![CDATA[<ui:repeat />]]></literal> iterate over a list or array, exposing each item in the list to nested components. This is effective if you are selecting a row with a <literal><![CDATA[<h:commandButton />]]></literal> or <literal><![CDATA[<h:commandLink />]]></literal> like so:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Factory("items")
+public List<Item> getItems() {
+ return entityManager.createQuery("select ...").getResultList();
+}]]>
+</programlisting>
+
+<programlisting role="XHTML"><![CDATA[<h:dataTable value="#{items}" var="item">
+ <h:column>
+ <h:commandLink value="Select #{item.name}"
+ action="#{itemSelector.select(item})" />
+ </h:column>
+</h:dataTable>]]>
+</programlisting>
+ <para>
+ However, if you want to use <literal><![CDATA[<s:link />]]></literal> or <literal><![CDATA[<s:button />]]></literal> you must expose the items as a <literal>DataModel</literal>, and use a <literal><![CDATA[<dataTable />]]></literal> (or equivalent from a component set like <literal><![CDATA[<rich:dataTable />]]></literal>). Neither <literal><![CDATA[<s:link />]]></literal> or <literal><![CDATA[<s:button />]]></literal> submit the form, so they do not produce a bookmarkable link. An additional parameter is required to recreate the item when the action method is called. This parameter can only be added when a data table backed by a <literal>DataModel</literal> is used. <!-- #modify: remind reader of required additional parameter? -->
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <emphasis>Calling a <literal>MethodExpression</literal> from Java code</emphasis> —Normally, when a <literal>MethodExpression</literal> is created, the parameter types are passed in by JSF. However, in a method binding, JSF assumes that there are no parameters to pass. With this extension, there is no way to know the parameter types prior to expression evaluation. This has two minor consequences:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ When you invoke a <literal>MethodExpression</literal> in Java code, parameters you pass may be ignored. Parameters defined in the expression will take precedence.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Ordinarily, it is safe to call <literal>methodExpression.getMethodInfo().getParamTypes()</literal> at any time. For an expression with parameters, you must first invoke the <literal>MethodExpression</literal> before calling <literal>getParamTypes()</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Both of these cases are exceedingly rare and only apply when you want to invoke the <literal>MethodExpression</literal> by hand in Java code.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Projection</title>
+ <para>
+ JBoss EL supports a limited projection syntax. A projection expression maps a sub-expression across a multi-valued (list, set, etc...) expression. For instance, the expression:
+ </para>
+
+<programlisting>#{company.departments}
+</programlisting>
+ <para>
+ might return a list of departments. If you only need a list of department names, you must iterate over the list to retrieve the values. JBoss EL allows this with a projection expression:
+ </para>
+
+<programlisting>#{company.departments.{d|d.name}}
+</programlisting>
+ <para>
+ The sub-expression is enclosed in braces. In this example, the expression <literal>d.name</literal> is evaluated for each department, using <literal>d</literal> as an alias to the department object. The result of this expression will be a list of String values.
+ </para>
+ <para>
+ Any valid expression can be used in an expression, so —assuming you would use department names of all lengths in a company —it would also be valid to write the following:
+ </para>
+
+<programlisting>#{company.departments.{d|d.size()}}
+</programlisting>
+ <para>
+ Projections can be nested. The following expression returns the last names of every employee in every department:
+ </para>
+
+<programlisting>#{company.departments.{d|d.employees.{emp|emp.lastName}}}
+</programlisting>
+ <para>
+ Nested projections can be slightly tricky, however. The following expression appears to return a list of all employees in all departments:
+ </para>
+
+<programlisting>#{company.departments.{d|d.employees}}
+</programlisting>
+ <para>
+ However, it actually returns a list containing a list of the employees for each individual department. To combine the values, it is necessary to use a slightly longer expression:
+ </para>
+
+<programlisting>#{company.departments.{d|d.employees.{e|e}}}
+</programlisting>
+ <para>
+ This syntax cannot be parsed by either Facelets or JSP, so it cannot be used in XHTML or JSP files. Future versions of JBoss EL may accommodate the projection syntax more easily.
+ </para>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Events.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Events.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Events.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,1218 +1,1111 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-
-<chapter id="events">
- <title>Events, interceptors and exception handling</title>
-
- <para>
- Complementing the contextual component model, there are two further basic concepts
- that facilitate the extreme loose-coupling that is the distinctive feature of Seam
- applications. The first is a strong event model where events may be mapped to event
- listeners via JSF-like method binding expressions. The second is the pervasive use
- of annotations and interceptors to apply cross-cutting concerns to components which
- implement business logic.
- </para>
-
- <section>
- <title>Seam events</title>
- <para>
- The Seam component model was developed for use with <emphasis>event-driven
- applications</emphasis>, specifically to enable the development of fine-grained,
- loosely-coupled components in a fine-grained eventing model. Events in Seam come
- in several types, most of which we have already seen:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>JSF events</para>
- </listitem>
- <listitem>
- <para>jBPM transition events</para>
- </listitem>
- <listitem>
- <para>Seam page actions</para>
- </listitem>
- <listitem>
- <para>Seam component-driven events</para>
- </listitem>
- <listitem>
- <para>Seam contextual events</para>
- </listitem>
- </itemizedlist>
-
- <para>
- All of these various kinds of events are mapped to Seam components via JSF EL
- method binding expressions. For a JSF event, this is defined in the JSF template:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandButton value="Click me!" action="#{helloWorld.sayHello}"/>]]></programlisting>
-
-
-
- <para>
- For a jBPM transition event, it is specified in the jBPM process definition or
- pageflow definition:
- </para>
-
- <programlisting role="XML"><![CDATA[<start-page name="hello" view-id="/hello.jsp">
- <transition to="hello">
- <action expression="#{helloWorld.sayHello}"/>
- </transition>
-</start-page>]]></programlisting>
-
- <para>
- You can find out more information about JSF events and jBPM events elsewhere.
- Let's concentrate for now upon the two additional kinds of events defined by Seam.
- </para>
-</section>
-
- <section>
- <title>Page actions</title>
-
- <para>
- A Seam page action is an event that occurs just before we render a page.
- We declare page actions in <literal>WEB-INF/pages.xml</literal>. We
- can define a page action for either a particular JSF view id:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/hello.jsp" action="#{helloWorld.sayHello}"/>
-</pages>]]></programlisting>
-
- <para>
- Or we can use a <literal>*</literal> wildcard as a suffix to the
- <literal>view-id</literal> to specify an action that applies to all
- view ids that match the pattern:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/hello/*" action="#{helloWorld.sayHello}"/>
-</pages>]]></programlisting>
-
- <para>
- Keep in mind that if the <literal><page></literal> element is defined in
- a fine-grained page descriptor, the <literal>view-id</literal> attribute
- can be left off since it is implied.
- </para>
-
- <para>
- If multiple wildcarded page actions match the current view-id, Seam
- will call all the actions, in order of least-specific to most-specific.
- </para>
-
- <para>
- The page action method can return a JSF outcome. If the outcome is
- non-null, Seam will use the defined navigation rules to navigate to a view.
- </para>
-
- <para>
- Furthermore, the view id mentioned in the <literal><page></literal>
- element need not correspond to a real JSP or Facelets page! So, we can
- reproduce the functionality of a traditional action-oriented framework
- like Struts or WebWork using page actions. This is quite useful if you want
- to do complex things in response to non-faces requests (for example, HTTP GET
- requests).
- </para>
-
- <para>
- Multiple or conditional page actions my be specified using the <literal><action></literal>
- tag:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/hello.jsp">
- <action execute="#{helloWorld.sayHello}" if="#{not validation.failed}"/>
- <action execute="#{hitCount.increment}"/>
- </page>
-</pages>]]></programlisting>
-
- <para>
- Page actions are executed on both an initial (non-faces) request and a postback (faces) request.
- If you are using the page action to load data, this operation may conflict with the standard JSF
- action(s) being executed on a postback. One way to disable the page action is to setup a condition
- that resolves to true only on an initial request.
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/dashboard.xhtml">
- <action execute="#{dashboard.loadData}"
- if="#{not facesContext.renderKit.responseStateManager.isPostback(facesContext)}"/>
- </page>
-</pages>]]></programlisting>
-
- <para>
- This condition consults the <literal>ResponseStateManager#isPostback(FacesContext)</literal> to
- determine if the request is a postback. The ResponseStateManager is accessed using
- <literal>FacesContext.getCurrentInstance().getRenderKit().getResponseStateManager()</literal>.
- </para>
-
- <para>
- To save you from the verbosity of JSF's API, Seam offers a built-in condition that allows you to
- accomplish the same result with a heck of a lot less typing. You can disable a page action on postback
- by simply setting the <literal>on-postback</literal> to <literal>false</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/dashboard.xhtml">
- <action execute="#{dashboard.loadData}" on-postback="false"/>
- </page>
-</pages>]]></programlisting>
-
- <para>
- For backwards compatibility reasons, the default value of the <literal>on-postback</literal> attribute
- is true, though likely you will end up using the opposite setting more often.
- </para>
-
-</section>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+<!-- This Chapter has been updated on 04 November 2009 to reflect JBPAPP_5_0-CR5
+ sourced from:
+ https://svn.jboss.org/repos/seam/tags/JBPAPP_5_0-CR5/doc/Seam_Reference_Guide/en-US
+-->
+<chapter id="events" >
+ <title>Events, interceptors and exception handling</title>
+ <para>
+ To complement the contextual component model, there are two further basic concepts that facilitate the extremely loose coupling distinctive of Seam applications. The first is a strong event model, where events are mapped to event listeners with method-binding expressions like those in JavaServer Faces (JSF). The second is the pervasive use of annotations and interceptors to apply cross-cutting concerns to components that implement business logic.
+ </para>
+ <section>
+ <title>Seam events</title>
+ <para>
+ The Seam component model was developed for use with <emphasis>event-driven applications</emphasis>, specifically to enable the development of fine-grained, loosely-coupled components in a fine-grained eventing model. There are several event types in Seam:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ JSF events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ jBPM transition events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Seam page actions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Seam component-driven events
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Seam contextual events
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Each of these events is mapped to Seam components with JSF EL method-binding expressions. For a JSF event, this is defined in the JSF template:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton value="Click me!" action="#{helloWorld.sayHello}"/>]]>
+</programlisting>
+ <para>
+ For a jBPM transition event, it is specified in the jBPM process definition or pageflow definition:
+ </para>
+
+<programlisting role="XML"><![CDATA[<start-page name="hello" view-id="/hello.jsp">
+ <transition to="hello">
+ <action expression="#{helloWorld.sayHello}"/>
+ </transition>
+</start-page>]]>
+</programlisting>
+ <para>
+ More information about JSF events and jBPM events is available<!-- #modify: at this specific xref'd location! --> elsewhere. For now, we will concentrate upon the two additional event types defined by Seam.
+ </para>
+ </section>
- <section>
- <title>Page parameters</title>
-
- <para>
- A JSF faces request (a form submission) encapsulates both an "action"
- (a method binding) and "parameters" (input value bindings). A page
- action might also needs parameters!
- </para>
-
- <para>
- Since GET requests are bookmarkable, page parameters are passed as
- human-readable request parameters. (Unlike JSF form inputs, which are
- anything but!)
- </para>
-
- <para>
- You can use page parameters with or without an action method.
- </para>
-
- <section>
- <title>Mapping request parameters to the model</title>
-
- <para>
- Seam lets us provide a value binding that maps a named request parameter
- to an attribute of a model object.
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/hello.jsp" action="#{helloWorld.sayHello}">
- <param name="firstName" value="#{person.firstName}"/>
- <param name="lastName" value="#{person.lastName}"/>
- </page>
- </pages>]]></programlisting>
-
- <para>
- The <literal><param></literal> declaration is bidirectional, just
- like a value binding for a JSF input:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- When a non-faces (GET) request for the view id occurs, Seam sets
- the value of the named request parameter onto the model object,
- after performing appropriate type conversions.
- </para>
- </listitem>
- <listitem>
- <para>
- Any <literal><s:link></literal> or <literal><s:button></literal>
- transparently includes the request parameter. The value of the parameter is
- determined by evaluating the value binding during the render phase (when the
- <literal><s:link></literal> is rendered).
- </para>
- </listitem>
- <listitem>
- <para>
- Any navigation rule with a <literal><redirect/></literal> to
- the view id transparently includes the request parameter. The value
- of the parameter is determined by evaluating the value binding at
- the end of the invoke application phase.
- </para>
- </listitem>
- <listitem>
- <para>
- The value is transparently propagated with any JSF form submission
- for the page with the given view id. This means that view parameters
- behave like <literal>PAGE</literal>-scoped context variables for
- faces requests.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- The essential idea behind all this is that <emphasis>however</emphasis>
- we get from any other page to <literal>/hello.jsp</literal> (or from
- <literal>/hello.jsp</literal> back to <literal>/hello.jsp</literal>),
- the value of the model attribute referred to in the value binding is
- "remembered", without the need for a conversation (or other server-side
- state).
- </para>
-
- </section>
- </section>
-
- <section>
- <title>Propagating request parameters</title>
-
- <para>
- If just the <literal>name</literal> attribute is specified then the
- request parameter is propagated using the <literal>PAGE</literal> context
- (it isn't mapped to model property).
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/hello.jsp" action="#{helloWorld.sayHello}">
- <param name="firstName" />
- <param name="lastName" />
- </page>
- </pages>]]></programlisting>
-
-
- <para>
- Propagation of page parameters is especially useful if you want to build multi-layer
- master-detail CRUD pages. You can use it to "remember" which view you were previously
- on (e.g. when pressing the Save button), and which entity you were editing.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Any <literal><s:link></literal> or <literal><s:button></literal>
- transparently propagates the request parameter if that parameter is listed
- as a page parameter for the view.
- </para>
- </listitem>
- <listitem>
- <para>
- The value is transparently propagated with any JSF form submission
- for the page with the given view id. (This means that view parameters
- behave like <literal>PAGE</literal>-scoped context variables for
- faces requests.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- This all sounds pretty complex, and you're probably wondering if such an
- exotic construct is really worth the effort. Actually, the idea is very
- natural once you "get it". It is definitely worth taking the time to
- understand this stuff. Page parameters are the most elegant way to
- propagate state across a non-faces request. They are especially cool for
- problems like search screens with bookmarkable results pages, where we
- would like to be able to write our application code to handle both POST
- and GET requests with the same code. Page parameters eliminate repetitive
- listing of request parameters in the view definition and make redirects
- much easier to code.
- </para>
-
- </section>
-
- <section>
- <title>URL rewriting with page parameters</title>
- <para>
- Rewriting occurs based on rewrite patterns found for views in <literal>pages.xml</literal>.
- Seam URL rewriting does both incoming and outgoing URL rewriting based on the same pattern.
- Here's a simple pattern:
- </para>
-
-
- <programlisting role="XML"><![CDATA[
-<page view-id="/home.xhtml">
- <rewrite pattern="/home" />
-</page>
-]]></programlisting>
-
- <para>
- In this case, any incoming request for <literal>/home</literal> will be sent to
- <literal>/home.xhtml</literal>. More interestingly,
- any link generated that would normally point to <literal>/home.seam</literal> will
- instead be rewritten as <literal>/home</literal>. Rewrite patterns only match the portion of the URL
- before the query parameters. So, <literal>/home.seam?conversationId=13</literal> and
- <literal>/home.seam?color=red</literal>
- will both be matched by this rewrite rule.
- </para>
-
- <para>
- Rewrite rules can take these query paramters into consideration, as shown with the following rules.
- </para>
- <programlisting role="XML"><![CDATA[
-<page view-id="/home.xhtml">
- <rewrite pattern="/home/{color}" />
- <rewrite pattern="/home" />
-</page>
-]]></programlisting>
-
- <para>
- In this case, an incoming request for <literal>/home/red</literal> will be served as
- if it were a request
- for <literal>/home.seam?color=red</literal>. Similarly, if color is a page parameter an outgoing
- URL that would normally show as <literal>/home.seam?color=blue</literal> would instead
- be output as
- <literal>/home/blue</literal>. Rules are processed in order, so it is important to list
- more specific rules before more general rules.
- </para>
-
- <para>Default Seam query parameters can also be mapped using URL rewriting, allowing for another
- option for hiding Seam's fingerprints.
- In the following example, <literal>/search.seam?conversationId=13</literal> would
- be written as <literal>/search-13</literal>.
- </para>
- <programlisting role="XML"><![CDATA[
-<page view-id="/search.xhtml">
- <rewrite pattern="/search-{conversationId}" />
- <rewrite pattern="/search" />
-</page>
-]]></programlisting>
-
- <para>
- Seam URL rewriting provides simple, bidirectional rewriting on a per-view basis. For more
- complex rewriting rules that cover non-seam components, Seam applications can continue to
- use the <literal>org.tuckey URLRewriteFilter </literal>or apply rewriting rules at the web server.
- </para>
-
- <para>
- URL rewriting requires the Seam rewrite filter to be enable. Rewrite filter
- configuration is discussed in <xref linkend="configuration.filters.rewrite"/>.
- </para>
-
- </section>
-
- <section>
- <title>Conversion and Validation</title>
-
- <para>
- You can specify a JSF converter for complex model propreties:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/calculator.jsp" action="#{calculator.calculate}">
- <param name="x" value="#{calculator.lhs}"/>
- <param name="y" value="#{calculator.rhs}"/>
- <param name="op" converterId="com.my.calculator.OperatorConverter" value="#{calculator.op}"/>
- </page>
-</pages>]]></programlisting>
-
- <para>
- Alternatively:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/calculator.jsp" action="#{calculator.calculate}">
- <param name="x" value="#{calculator.lhs}"/>
- <param name="y" value="#{calculator.rhs}"/>
- <param name="op" converter="#{operatorConverter}" value="#{calculator.op}"/>
- </page>
-</pages>]]></programlisting>
-
-
- <para>
- JSF validators, and <literal>required="true"</literal> may
- also be used:
- </para>
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/blog.xhtml">
- <param name="date"
- value="#{blog.date}"
- validatorId="com.my.blog.PastDate"
- required="true"/>
- </page>
-</pages>]]></programlisting>
-
- <para>
- Alternatively:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/blog.xhtml">
- <param name="date"
- value="#{blog.date}"
- validator="#{pastDateValidator}"
- required="true"/>
- </page>
-</pages>]]></programlisting>
-
- <para>
- Even better, model-based Hibernate validator annotations are automatically
- recognized and validated. Seam also provides a default date converter to
- convert a string parameter value to a date and back.
- </para>
-
- <para>
- When type conversion or validation fails, a global <literal>FacesMessage</literal>
- is added to the <literal>FacesContext</literal>.
- </para>
-
- </section>
-
- <section id="events.pageaction.navigation">
- <title>Navigation</title>
-
- <para>
- You can use standard JSF navigation rules defined in <literal>faces-config.xml</literal>
- in a Seam application. However, JSF navigation rules have a number of annoying
- limitations:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- It is not possible to specify request parameters to be used when redirecting.
- </para>
- </listitem>
- <listitem>
- <para>
- It is not possible to begin or end conversations from a rule.
- </para>
- </listitem>
- <listitem>
- <para>
- Rules work by evaluating the return value of the action method; it is not
- possible to evaluate an arbitrary EL expression.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- A further problem is that "orchestration" logic gets scattered between <literal>pages.xml</literal>
- and <literal>faces-config.xml</literal>. It's better to unify this logic into <literal>pages.xml</literal>.
- </para>
-
- <para>
- This JSF navigation rule:
- </para>
-
- <programlisting role="XML"><![CDATA[<navigation-rule>
- <from-view-id>/editDocument.xhtml</from-view-id>
-
- <navigation-case>
- <from-action>#{documentEditor.update}</from-action>
- <from-outcome>success</from-outcome>
- <to-view-id>/viewDocument.xhtml</to-view-id>
- <redirect/>
- </navigation-case>
-
-</navigation-rule>]]></programlisting>
-
- <para>
- Can be rewritten as follows:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
-
- <navigation from-action="#{documentEditor.update}">
- <rule if-outcome="success">
- <redirect view-id="/viewDocument.xhtml"/>
- </rule>
- </navigation>
-
-</page>]]></programlisting>
-
- <para>
- But it would be even nicer if we didn't have to pollute our <literal>DocumentEditor</literal>
- component with string-valued return values (the JSF outcomes). So Seam lets us write:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
-
- <navigation from-action="#{documentEditor.update}"
- evaluate="#{documentEditor.errors.size}">
- <rule if-outcome="0">
- <redirect view-id="/viewDocument.xhtml"/>
- </rule>
- </navigation>
-
-</page>]]></programlisting>
-
- <para>
- Or even:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
-
- <navigation from-action="#{documentEditor.update}">
- <rule if="#{documentEditor.errors.empty}">
- <redirect view-id="/viewDocument.xhtml"/>
- </rule>
- </navigation>
-
-</page>]]></programlisting>
-
- <para>
- The first form evaluates a value binding to determine the outcome value
- to be used by the subsequent rules.
- The second approach ignores the outcome and evaluates a value binding
- for each possible rule.
- </para>
-
- <para>
- Of course, when an update succeeds, we probably want to end the current
- conversation. We can do that like this:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
-
- <navigation from-action="#{documentEditor.update}">
- <rule if="#{documentEditor.errors.empty}">
- <end-conversation/>
- <redirect view-id="/viewDocument.xhtml"/>
- </rule>
- </navigation>
-
-</page>]]></programlisting>
-
- <para>
- As we've ended conversation any subsequent requests won't know
- which document we are interested in. We can pass the document
- id as a request parameter which also makes the view bookmarkable:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
-
- <navigation from-action="#{documentEditor.update}">
- <rule if="#{documentEditor.errors.empty}">
- <end-conversation/>
- <redirect view-id="/viewDocument.xhtml">
- <param name="documentId" value="#{documentEditor.documentId}"/>
- </redirect>
- </rule>
- </navigation>
-
-</page>]]></programlisting>
-
- <para>
- Null outcomes are a special case in JSF. The null outcome is interpreted to
- mean "redisplay the page". The following navigation rule matches any non-null
- outcome, but <emphasis>not</emphasis> the null outcome:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
-
- <navigation from-action="#{documentEditor.update}">
- <rule>
- <render view-id="/viewDocument.xhtml"/>
- </rule>
- </navigation>
-
-</page>]]></programlisting>
-
- <para>
- If you want to perform navigation when a null outcome occurs, use the
- following form instead:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
-
- <navigation from-action="#{documentEditor.update}">
- <render view-id="/viewDocument.xhtml"/>
- </navigation>
-
-</page>]]></programlisting>
-
- <para>
- The view-id may be given as a JSF EL expression:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
-
- <navigation>
- <rule if-outcome="success">
- <redirect view-id="/#{userAgent}/displayDocument.xhtml"/>
- </rule>
- </navigation>
-
-</page>]]></programlisting>
-
- </section>
-
- <section>
- <title>Fine-grained files for definition of navigation, page actions and parameters</title>
-
- <para>
- If you have a lot of different page actions and page parameters,
- or even just a lot of navigation rules,
- you will almost certainly want to split the declarations up over
- multiple files. You can define actions and parameters for a page
- with the view id <literal>/calc/calculator.jsp</literal> in a
- resource named <literal>calc/calculator.page.xml</literal>. The
- root element in this case is the <literal><page></literal>
- element, and the view id is implied:
- </para>
-
- <programlisting role="XML"><![CDATA[<page action="#{calculator.calculate}">
- <param name="x" value="#{calculator.lhs}"/>
- <param name="y" value="#{calculator.rhs}"/>
- <param name="op" converter="#{operatorConverter}" value="#{calculator.op}"/>
-</page>]]></programlisting>
-
- </section>
-
-
-
- <section>
- <title>Component-driven events</title>
-
- <para>
- Seam components can interact by simply calling each others methods.
- Stateful components may even implement the observer/observable pattern.
- But to enable components to interact in a more loosely-coupled fashion
- than is possible when the components call each others methods directly,
- Seam provides <emphasis>component-driven events</emphasis>.
- </para>
-
- <para>
- We specify event listeners (observers) in <literal>components.xml</literal>.
- </para>
-
- <programlisting role="XML"><![CDATA[<components>
- <event type="hello">
- <action execute="#{helloListener.sayHelloBack}"/>
- <action execute="#{logger.logHello}"/>
- </event>
-</components>]]></programlisting>
-
- <para>
- Where the <emphasis>event type</emphasis> is just an arbitrary string.
- </para>
-
- <para>
- When an event occurs, the actions registered for that event will be called
- in the order they appear in <literal>components.xml</literal>. How does a
- component raise an event? Seam provides a built-in component for this.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("helloWorld")
-public class HelloWorld {
- public void sayHello() {
- FacesMessages.instance().add("Hello World!");
- Events.instance().raiseEvent("hello");
- }
-}]]></programlisting>
-
- <para>
- Or you can use an annotation.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("helloWorld")
-public class HelloWorld {
- @RaiseEvent("hello")
- public void sayHello() {
- FacesMessages.instance().add("Hello World!");
- }
-}]]></programlisting>
-
- <para>
- Notice that this event producer has no dependency upon event consumers.
- The event listener may now be implemented with absolutely no dependency
- upon the producer:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("helloListener")
-public class HelloListener {
- public void sayHelloBack() {
- FacesMessages.instance().add("Hello to you too!");
- }
-}]]></programlisting>
-
- <para>
- The method binding defined in <literal>components.xml</literal> above
- takes care of mapping the event to the consumer.
- If you don't like futzing about in the <literal>components.xml</literal>
- file, you can use an annotation instead:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("helloListener")
-public class HelloListener {
- @Observer("hello")
- public void sayHelloBack() {
- FacesMessages.instance().add("Hello to you too!");
- }
-}]]></programlisting>
-
- <para>
- You might wonder why I've not mentioned anything about event objects in
- this discussion. In Seam, there is no need for an event object to propagate
- state between event producer and listener. State is held in the Seam
- contexts, and is shared between components. However, if you really want
- to pass an event object, you can:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("helloWorld")
-public class HelloWorld {
- private String name;
- public void sayHello() {
- FacesMessages.instance().add("Hello World, my name is #0.", name);
- Events.instance().raiseEvent("hello", name);
- }
-}]]></programlisting>
-
- <programlisting role="JAVA"><![CDATA[@Name("helloListener")
-public class HelloListener {
- @Observer("hello")
- public void sayHelloBack(String name) {
- FacesMessages.instance().add("Hello #0!", name);
- }
-}]]></programlisting>
-
- </section>
-
- <section>
- <title>Contextual events</title>
- <para>
- Seam defines a number of built-in events that the application can use to
- perform special kinds of framework integration. The events are:
- </para>
-
- <itemizedlist>
- <listitem><para><literal>org.jboss.seam.validationFailed</literal> — called when JSF validation fails</para></listitem>
- <listitem><para><literal>org.jboss.seam.noConversation</literal> — called when there is no long running conversation and a long running conversation is required</para></listitem>
- <listitem><para><literal>org.jboss.seam.preSetVariable.<name></literal> — called when the context variable <name> is set</para></listitem>
- <listitem><para><literal>org.jboss.seam.postSetVariable.<name></literal> — called when the context variable <name> is set</para></listitem>
- <listitem><para><literal>org.jboss.seam.preRemoveVariable.<name></literal> — called when the context variable <name> is unset</para></listitem>
- <listitem><para><literal>org.jboss.seam.postRemoveVariable.<name></literal> — called when the context variable <name> is unset</para></listitem>
- <listitem><para><literal>org.jboss.seam.preDestroyContext.<SCOPE></literal> — called before the <SCOPE> context is destroyed</para></listitem>
- <listitem><para><literal>org.jboss.seam.postDestroyContext.<SCOPE></literal> — called after the <SCOPE> context is destroyed</para></listitem>
- <listitem><para><literal>org.jboss.seam.beginConversation </literal> — called whenever a long-running conversation begins</para></listitem>
- <listitem><para><literal>org.jboss.seam.endConversation </literal> — called whenever a long-running conversation ends</para></listitem>
- <listitem><para><literal>org.jboss.seam.conversationTimeout</literal> — called when a conversation timeout occurs. The conversation id is passed as a parameter.</para></listitem>
- <listitem><para><literal>org.jboss.seam.beginPageflow </literal> — called when a pageflow begins</para></listitem>
- <listitem><para><literal>org.jboss.seam.beginPageflow.<name> </literal> — called when the pageflow <name> begins</para></listitem>
- <listitem><para><literal>org.jboss.seam.endPageflow </literal> — called when a pageflow ends</para></listitem>
- <listitem><para><literal>org.jboss.seam.endPageflow.<name> </literal> — called when the pageflow <name> ends</para></listitem>
- <listitem><para><literal>org.jboss.seam.createProcess.<name> </literal> — called when the process <name> is created</para></listitem>
- <listitem><para><literal>org.jboss.seam.endProcess.<name> </literal> — called when the process <name> ends</para></listitem>
- <listitem><para><literal>org.jboss.seam.initProcess.<name> </literal> — called when the process <name> is associated with the conversation</para></listitem>
- <listitem><para><literal>org.jboss.seam.initTask.<name> </literal> — called when the task <name> is associated with the conversation</para></listitem>
- <listitem><para><literal>org.jboss.seam.startTask.<name> </literal> — called when the task <name> is started</para></listitem>
- <listitem><para><literal>org.jboss.seam.endTask.<name> </literal> — called when the task <name> is ended</para></listitem>
- <listitem><para><literal>org.jboss.seam.postCreate.<name> </literal> — called when the component <name> is created</para></listitem>
- <listitem><para><literal>org.jboss.seam.preDestroy.<name> </literal> — called when the component <name> is destroyed</para></listitem>
- <listitem><para><literal>org.jboss.seam.beforePhase </literal> — called before the start of a JSF phase</para></listitem>
- <listitem><para><literal>org.jboss.seam.afterPhase </literal> — called after the end of a JSF phase</para></listitem>
- <listitem><para><literal>org.jboss.seam.postInitialization </literal> — called when Seam has initialized and started up all components</para></listitem>
- <listitem><para><literal>org.jboss.seam.postReInitialization </literal> — called when Seam has re-initialized and started up all components after a redeploy</para></listitem>
- <listitem><para><literal>org.jboss.seam.exceptionHandled.<type></literal> — called when an uncaught exception is handled by Seam</para></listitem>
- <listitem><para><literal>org.jboss.seam.exceptionHandled</literal> — called when an uncaught exception is handled by Seam</para></listitem>
- <listitem><para><literal>org.jboss.seam.exceptionNotHandled</literal> — called when there was no handler for an uncaught exception</para></listitem>
- <listitem><para><literal>org.jboss.seam.afterTransactionSuccess</literal> — called when a transaction succeeds in the Seam Application Framework</para></listitem>
- <listitem><para><literal>org.jboss.seam.afterTransactionSuccess.<name></literal> — called when a transaction succeeds in the Seam Application Framework which manages an entity called <literal><name></literal></para></listitem>
- <listitem><para><literal>org.jboss.seam.security.loggedOut</literal> — called when a user logs out</para></listitem>
- <listitem><para><literal>org.jboss.seam.security.loginFailed</literal> — called when a user authentication attempt fails</para></listitem>
- <listitem><para><literal>org.jboss.seam.security.loginSuccessful</literal> — called when a user is successfully authenticated</para></listitem>
- <listitem><para><literal>org.jboss.seam.security.notAuthorized</literal> — called when an authorization check fails</para></listitem>
- <listitem><para><literal>org.jboss.seam.security.notLoggedIn</literal> — called there is no authenticated user and authentication is required</para></listitem>
- <listitem><para><literal>org.jboss.seam.security.postAuthenticate.</literal> — called after a user is authenticated</para></listitem>
- <listitem><para><literal>org.jboss.seam.security.preAuthenticate</literal> — called before attempting to authenticate a user</para></listitem>
- </itemizedlist>
-
- <para>
- Seam components may observe any of these events in just the same way they
- observe any other component-driven events.
- </para>
- </section>
-
-
-
- <section>
- <title>Seam interceptors</title>
-
- <para>
- EJB 3.0 introduced a standard interceptor model for session bean components. To add an
- interceptor to a bean, you need to write a class with a method annotated
- <literal>@AroundInvoke</literal> and annotate the bean with an
- <literal>@Interceptors</literal> annotation that specifies the name of the interceptor
- class. For example, the following interceptor checks that the user is logged in before
- allowing invoking an action listener method:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public class LoggedInInterceptor {
-
- @AroundInvoke
- public Object checkLoggedIn(InvocationContext invocation) throws Exception {
-
- boolean isLoggedIn = Contexts.getSessionContext().get("loggedIn")!=null;
- if (isLoggedIn) {
- //the user is already logged in
- return invocation.proceed();
- }
- else {
- //the user is not logged in, fwd to login page
- return "login";
- }
- }
-
-}]]></programlisting>
-
- <para>
- To apply this interceptor to a session bean which acts as an action listener, we must
- annotate the session bean <literal>@Interceptors(LoggedInInterceptor.class)</literal>.
- This is a somewhat ugly annotation. Seam builds upon the interceptor framework in
- EJB3 by allowing you to use <literal>@Interceptors</literal> as a meta-annotation for class
- level interceptors (those annotated <literal>@Target(TYPE)</literal>). In
- our example, we would create an <literal>@LoggedIn</literal> annotation, as follows:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Target(TYPE)
- at Retention(RUNTIME)
- at Interceptors(LoggedInInterceptor.class)
-public @interface LoggedIn {}]]></programlisting>
-
- <para>
- We can now simply annotate our action listener bean with <literal>@LoggedIn</literal>
- to apply the interceptor.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Stateless
- at Name("changePasswordAction")
- at LoggedIn
- at Interceptors(SeamInterceptor.class)
+ <section>
+ <title>Page actions</title>
+ <para>
+ A Seam page action is an event occurring immediately before a page is rendered. Declare page actions in <filename>WEB-INF/pages.xml</filename>. We can define a page action for a particular JSF view ID:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/hello.jsp" action="#{helloWorld.sayHello}"/>
+</pages>]]>
+</programlisting>
+ <para>
+ Or we can use a <literal>*</literal> wildcard as a suffix to the <literal>view-id</literal> to specify an action that applies to all view IDs that match that pattern:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/hello/*" action="#{helloWorld.sayHello}"/>
+</pages>]]>
+</programlisting>
+ <note>
+ <para>
+ If the <literal><![CDATA[<page>]]></literal> element is defined in a fine-grained page descriptor, the <literal>view-id</literal> attribute can be omitted, as it is already implied.
+ </para>
+ </note>
+ <para>
+ If multiple wildcarded page actions match the current view-id, Seam will call all the actions, in order of least-specific to most-specific.
+ </para>
+ <para>
+ The page action method can return a JSF outcome. If the outcome is not null, Seam uses the defined navigation rules to navigate to a view.
+ </para>
+ <para>
+ The view ID mentioned in the <literal><![CDATA[<page>]]></literal> element need not correspond to a real JSP or Facelets page. This way, we can reproduce the functionality of a traditional action-oriented framework like Struts or WebWork using page actions. This is useful for performing complex actions in response to non-Faces requests like HTTP GET.
+ </para>
+ <para>
+ Multiple or conditional page actions can be specified with the <literal><![CDATA[<action>]]></literal> tag:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/hello.jsp">
+ <action execute="#{helloWorld.sayHello}"
+ if="#{not validation.failed}"/>
+ <action execute="#{hitCount.increment}"/>
+ </page>
+</pages>]]>
+</programlisting>
+ <para>
+ Page actions are executed on both an initial (non-Faces) request and a postback (Faces) request. If you use the page action to load data, it may conflict with the standard JSF actions being executed on a postback. One way to disable the page action is to set up a condition that resolves to <literal>true</literal> only upon an initial request.
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/dashboard.xhtml">
+ <action execute="#{dashboard.loadData}"
+ if="#{not FacesContext.renderKit.responseStateManager
+ .isPostback(FacesContext)}"/>
+ </page>
+</pages>]]>
+</programlisting>
+ <para>
+ This condition consults the <literal>ResponseStateManager#isPostback(FacesContext)</literal> to determine if the request is a postback. The ResponseStateManager is accessed using <literal>FacesContext.getCurrentInstance().getRenderKit(). getResponseStateManager()</literal>.
+ </para>
+ <para>
+ Seam offers a built-in condition that accomplishes this result less verbosely. You can disable a page action on a postback by setting the <literal>on-postback</literal> attribute to <literal>false</literal>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/dashboard.xhtml">
+ <action execute="#{dashboard.loadData}" on-postback="false"/>
+ </page>
+</pages>]]>
+</programlisting>
+ <para>
+ The <literal>on-postback</literal> attribute defaults to <literal>true</literal> to maintain backwards compatibility. However, you are more likely to use <literal>false</literal> more often.
+ </para>
+ </section>
+
+ <section>
+ <title>Page parameters</title>
+ <para>
+ A Faces request (a JSF form submission) encapsulates both an <emphasis>action</emphasis> (a method binding) and <emphasis>parameters</emphasis> (input value bindings). A page action can also require parameters.
+ </para>
+ <para>
+ Since non-Faces (GET) requests can be bookmarked, page parameters are passed as human-readable request parameters.
+ </para>
+ <para>
+ You can use page parameters with or without an action method.
+ </para>
+ <section>
+ <title>Mapping request parameters to the model</title>
+ <para>
+ Seam lets us provide a value binding that maps a named request parameter to an attribute of a model object.
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/hello.jsp" action="#{helloWorld.sayHello}">
+ <param name="firstName" value="#{person.firstName}"/>
+ <param name="lastName" value="#{person.lastName}"/>
+ </page>
+</pages>]]>
+</programlisting>
+ <para>
+ The <literal><![CDATA[<param>]]></literal> declaration is bidirectional, as with value bindings for JSF input:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ When a non-Faces (GET) request for the view ID occurs, Seam sets the value of the named request parameter to the model object, after performing appropriate type conversions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Any <literal><![CDATA[<s:link>]]></literal> or <literal><![CDATA[<s:button>]]></literal> includes the request parameter transparently. The parameter value is determined by evaluating the value binding during the render phase (when the <literal><![CDATA[<s:link>]]></literal> is rendered).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Any navigation rule with a <literal><![CDATA[<redirect/>]]></literal> to the view ID includes the request parameter transparently. The parameter value is determined by evaluating the value binding at the end of the invoke application phase.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The value is transparently propagated with any JSF form submission for the page with the given view ID. This means that view parameters behave like <literal>PAGE</literal>-scoped context variables for Faces requests.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ However we arrive at <filename>/hello.jsp</filename>, the value of the model attribute referenced in the value binding is held in memory, without the need for a conversation (or other server-side state).
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Propagating request parameters</title>
+ <para>
+ If only the <literal>name</literal> attribute is specified, the request parameter is propagated with the <literal>PAGE</literal> context (that is, it is not mapped to model property).
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/hello.jsp" action="#{helloWorld.sayHello}">
+ <param name="firstName" />
+ <param name="lastName" />
+ </page>
+</pages>]]>
+</programlisting>
+ <para>
+ Page parameter propagation is especially useful when building multi-layered master-detail CRUD pages. You can use it to "remember" your view (for example, when pressing the Save button), and which entity you were editing.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Any <literal><![CDATA[<s:link>]]></literal> or <literal><![CDATA[<s:button>]]></literal> transparently propagates the request parameter if that parameter is listed as a page parameter for the view.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The value is transparently propagated with any JSF form submission for the page with the given view ID. (This means that view parameters behave like <literal>PAGE</literal>-scoped context variables for Faces requests.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Although this is fairly complex, it is definitely worthwhile to dedicate time to an understanding of page parameters. They are the most elegant method of propagating state across non-Faces requests. They are particularly useful in certain situations. For example, if we have search screens with bookmarkable results pages, page parameters let us write handling for both POST and GET requests in the same code. Page parameters eliminate repetitive request parameter-listing in the view definition, and simplify redirect code.
+ </para>
+ </section>
+
+ <section>
+ <title>URL rewriting with page parameters</title>
+ <para>
+ Rewriting occurs based on patterns found for views in <filename>pages.xml</filename>. Seam URL rewriting performs both incoming and outgoing URL rewriting based on the same pattern. A simple pattern for this process is:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/home.xhtml">
+ <rewrite pattern="/home" />
+</page> ]]>
+</programlisting>
+ <para>
+ In this case, any incoming request for <literal>/home</literal> will be sent to <filename>/home.xhtml</filename>. Any link generated that would normally point to <literal>/home.seam</literal> will instead be rewritten as <literal>/home</literal>. Rewrite patterns only match the portion of the URL before the query parameters, so <literal>/home.seam?conversationId=13</literal> and <literal>/home.seam?color=red</literal> will both be matched by this rewrite rule.
+ </para>
+ <para>
+ Rewrite rules can take query paramters into consideration, as shown with the following rules.
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/home.xhtml">
+ <rewrite pattern="/home/{color}" />
+ <rewrite pattern="/home" />
+</page> ]]>
+</programlisting>
+ <para>
+ In this case, an incoming request for <literal>/home/red</literal> will be served as if it were a request for <literal>/home.seam?color=red</literal>. Similarly, if color is a page parameter, an outgoing URL that would normally show as <literal>/home.seam?color=blue</literal> would instead be output as <literal>/home/blue</literal>. Rules are processed in order, so it is important to list more specific rules before more general rules.
+ </para>
+ <para>
+ Default Seam query parameters can also be mapped with URL rewriting, further concealing Seam's fingerprints. In the following example, <literal>/search.seam?conversationId=13</literal> would be written as <literal>/search-13</literal>.
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/search.xhtml">
+ <rewrite pattern="/search-{conversationId}" />
+ <rewrite pattern="/search" />
+</page> ]]>
+</programlisting>
+ <para>
+ Seam URL rewriting provides simple, bidirectional rewriting on a per-view basis. For more complex rewriting rules that cover non-Seam components, Seam applications can continue to use the <literal>org.tuckey.URLRewriteFilter</literal>, or apply rewriting rules at the web server.
+ </para>
+ <para>
+ To use URL rewriting, the Seam <emphasis>rewrite filter</emphasis> must be enabled. Rewrite filter configuration is discussed in <xref linkend="configuration.filters.rewrite" />.
+ </para>
+ </section>
+
+ <section>
+ <title>Conversion and Validation</title>
+ <para>
+ You can specify a JSF converter for complex model properties:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/calculator.jsp" action="#{calculator.calculate}">
+ <param name="x" value="#{calculator.lhs}"/>
+ <param name="y" value="#{calculator.rhs}"/>
+ <param name="op" converterId="com.my.calculator.OperatorConverter"
+ value="#{calculator.op}"/>
+ </page>
+</pages>]]>
+</programlisting>
+ <para>
+ Alternatively:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/calculator.jsp" action="#{calculator.calculate}">
+ <param name="x" value="#{calculator.lhs}"/>
+ <param name="y" value="#{calculator.rhs}"/>
+ <param name="op" converter="#{operatorConverter}"
+ value="#{calculator.op}"/>
+ </page>
+</pages>]]>
+</programlisting>
+ <para>
+ JSF validators, and <literal>required="true"</literal> may also be used:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/blog.xhtml">
+ <param name="date" value="#{blog.date}"
+ validatorId="com.my.blog.PastDate" required="true"/>
+ </page>
+</pages>]]>
+</programlisting>
+ <para>
+ Alternatively:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/blog.xhtml">
+ <param name="date" value="#{blog.date}"
+ validator="#{pastDateValidator}" required="true"/>
+ </page>
+</pages>]]>
+</programlisting>
+ <para>
+ Model-based Hibernate validator annotations are automatically recognized and validated. Seam also provides a default date converter to convert a string parameter value to a date and back.
+ </para>
+ <para>
+ When type conversion or validation fails, a global <literal>FacesMessage</literal> is added to the <literal>FacesContext</literal>.
+ </para>
+ </section>
+
+ <section id="events.pageaction.navigation">
+ <title>Navigation</title>
+ <para>
+ You can use standard JSF navigation rules defined in <filename>faces-config.xml</filename> in a Seam application. However, these rules have several limitations:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ It is not possible to specify that request parameters are used when redirecting.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ It is not possible to begin or end conversations from a rule.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Rules work by evaluating the return value of the action method; it is not possible to evaluate an arbitrary EL expression.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Another problem is that "orchestration" logic is scattered between <filename>pages.xml</filename> and <filename>faces-config.xml</filename>. It is better to unify this logic under <filename>pages.xml</filename>.
+ </para>
+ <para>
+ This JSF navigation rule:
+ </para>
+
+<programlisting role="XML"><![CDATA[<navigation-rule>
+ <from-view-id>/editDocument.xhtml</from-view-id>
+ <navigation-case>
+ <from-action>#{documentEditor.update}</from-action>
+ <from-outcome>success</from-outcome>
+ <to-view-id>/viewDocument.xhtml</to-view-id>
+ <redirect/>
+ </navigation-case>
+</navigation-rule>]]>
+</programlisting>
+ <para>
+ Can be rewritten as follows:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+ <navigation from-action="#{documentEditor.update}">
+ <rule if-outcome="success">
+ <redirect view-id="/viewDocument.xhtml"/>
+ </rule>
+ </navigation>
+</page>]]>
+</programlisting>
+ <para>
+ However, this method pollutes <literal>DocumentEditor</literal> with string-valued return values (the JSF outcomes). Instead, Seam lets us write:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+ <navigation from-action="#{documentEditor.update}"
+ evaluate="#{documentEditor.errors.size}">
+ <rule if-outcome="0">
+ <redirect view-id="/viewDocument.xhtml"/>
+ </rule>
+ </navigation>
+</page>]]>
+</programlisting>
+ <para>
+ Or even:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+ <navigation from-action="#{documentEditor.update}">
+ <rule if="#{documentEditor.errors.empty}">
+ <redirect view-id="/viewDocument.xhtml"/>
+ </rule>
+ </navigation>
+</page>]]>
+</programlisting>
+ <para>
+ The first form evaluates a value binding to determine the outcome value used by the subsequent rules. The second approach ignores the outcome and evaluates a value binding for each possible rule.
+ </para>
+ <para>
+ When an update succeeds, we probably want to end the current conversation, like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+ <navigation from-action="#{documentEditor.update}">
+ <rule if="#{documentEditor.errors.empty}">
+ <end-conversation/>
+ <redirect view-id="/viewDocument.xhtml"/>
+ </rule>
+ </navigation>
+</page>]]>
+</programlisting>
+ <para>
+ Since the conversation has ended, any subsequent requests will not know which document we are interested in. We can pass the document ID as a request parameter, which also makes the view bookmarkable:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+ <navigation from-action="#{documentEditor.update}">
+ <rule if="#{documentEditor.errors.empty}">
+ <end-conversation/>
+ <redirect view-id="/viewDocument.xhtml">
+ <param name="documentId" value="#{documentEditor.documentId}"/>
+ </redirect>
+ </rule>
+ </navigation>
+</page>]]>
+</programlisting>
+ <para>
+ Null outcomes are a special case in JSF, and are interpreted as instructions to redisplay the page. The following navigation rule matches any non-null outcome, but <emphasis>not</emphasis> the null outcome:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+ <navigation from-action="#{documentEditor.update}">
+ <rule>
+ <render view-id="/viewDocument.xhtml"/>
+ </rule>
+ </navigation>
+</page>]]>
+</programlisting>
+ <para>
+ To perform navigation when a null outcome occurs, use the following:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+ <navigation from-action="#{documentEditor.update}">
+ <render view-id="/viewDocument.xhtml"/>
+ </navigation>
+</page>]]>
+</programlisting>
+ <para>
+ The view ID can be given as a JSF EL expression:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/editDocument.xhtml">
+ <navigation>
+ <rule if-outcome="success">
+ <redirect view-id="/#{userAgent}/displayDocument.xhtml"/>
+ </rule>
+ </navigation>
+</page>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Fine-grained files for defining navigation, page actions and parameters</title>
+ <para>
+ If you have a large number of different page actions and parameters — or even just a large number of navigation rules — it is sensible to split the declarations into several smaller files. You can define actions and parameters for a page with the view ID <literal>/calc/calculator.jsp</literal> in a resource named <literal>calc/calculator.page.xml</literal>. In this case, <literal><![CDATA[<page>]]></literal> is the root element, and the view ID is implied:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page action="#{calculator.calculate}">
+ <param name="x" value="#{calculator.lhs}"/>
+ <param name="y" value="#{calculator.rhs}"/>
+ <param name="op" converter="#{operatorConverter}" value="#{calculator.op}"/>
+</page>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Component-driven events</title>
+ <para>
+ Seam components interact by calling each other's methods. Stateful components can even implement the observer/observable pattern. However, to enable more loosely-coupled interaction, Seam provides <emphasis>component-driven events</emphasis>.
+ </para>
+ <para>
+ We specify event listeners (observers) in <filename>components.xml</filename>.
+ </para>
+
+<programlisting role="XML"><![CDATA[<components>
+ <event type="hello">
+ <action execute="#{helloListener.sayHelloBack}"/>
+ <action execute="#{logger.logHello}"/>
+ </event>
+</components>]]>
+</programlisting>
+ <para>
+ Here, the <emphasis>event type</emphasis> is an arbitrary string.
+ </para>
+ <para>
+ When an event occurs, the actions registered for that event will be called in the order they appear in <filename>components.xml</filename>. Seam provides a built-in component to raise events.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("helloWorld")
+public class HelloWorld {
+ public void sayHello() {
+ FacesMessages.instance().add("Hello World!");
+ Events.instance().raiseEvent("hello");
+ }
+}]]>
+</programlisting>
+ <para>
+ You can also use an annotation, like so:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("helloWorld")
+public class HelloWorld {
+ @RaiseEvent("hello")
+ public void sayHello() {
+ FacesMessages.instance().add("Hello World!");
+ }
+}]]>
+</programlisting>
+ <para>
+ This event producer is not dependent upon event consumers. The event listener can now be implemented with absolutely no dependency upon the producer:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("helloListener")
+public class HelloListener {
+ public void sayHelloBack() {
+ FacesMessages.instance().add("Hello to you too!");
+ }
+}]]>
+</programlisting>
+ <para>
+ The method binding defined above in <filename>components.xml</filename> maps the event to the consumer. If you prefer, you can also do this with annotations:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("helloListener")
+public class HelloListener {
+ @Observer("hello")
+ public void sayHelloBack() {
+ FacesMessages.instance().add("Hello to you too!");
+ }
+}]]>
+</programlisting>
+ <para>
+ If you are familiar with component-driven events, you may be wondering about event objects. In Seam, event objects do not need to propagate state between the event producer and listener. State is held in the Seam contexts, and shared between components. However, if you do want to pass an event object, you can do so:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("helloWorld")
+public class HelloWorld {
+ private String name;
+ public void sayHello() {
+ FacesMessages.instance().add("Hello World, my name is #0.", name);
+ Events.instance().raiseEvent("hello", name);
+ }
+}]]>
+</programlisting>
+
+<programlisting role="JAVA"><![CDATA[@Name("helloListener")
+public class HelloListener {
+ @Observer("hello")
+ public void sayHelloBack(String name) {
+ FacesMessages.instance().add("Hello #0!", name);
+ }
+}]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Contextual events</title>
+ <para>
+ Seam defines a number of built-in events that the application uses for certain kinds of framework integration. The events are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.validationFailed</literal> — Called when JSF validation fails.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.noConversation</literal> — Called when there is no long-running conversation and a long-running conversation is required.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.preSetVariable.<![CDATA[<name>]]></literal> — Called when the context variable <![CDATA[<name>]]> is set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.postSetVariable.<![CDATA[<name>]]></literal> — Called when the context variable <![CDATA[<name>]]> is set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.preRemoveVariable.<![CDATA[<name>]]></literal> — Called when the context variable <![CDATA[<name>]]> is unset.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.postRemoveVariable.<![CDATA[<name>]]></literal> — Called when the context variable <![CDATA[<name>]]> is unset.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.preDestroyContext.<![CDATA[<SCOPE>]]></literal> — Called before the <![CDATA[<SCOPE>]]> context is destroyed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.postDestroyContext.<![CDATA[<SCOPE>]]></literal> — Called after the <![CDATA[<SCOPE>]]> context is destroyed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.beginConversation </literal> — Called whenever a long-running conversation begins.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.endConversation </literal> — Called whenever a long-running conversation ends.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.conversationTimeout</literal> — Called when a conversation timeout occurs. The conversation ID is passed as a parameter.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.beginPageflow </literal> — Called when a pageflow begins.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.beginPageflow.<![CDATA[<name>]]> </literal> — Called when the pageflow <![CDATA[<name>]]> begins.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.endPageflow </literal> — Called when a pageflow ends.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.endPageflow.<![CDATA[<name>]]> </literal> — Called when the pageflow <![CDATA[<name>]]> ends.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.createProcess.<![CDATA[<name>]]> </literal> — Called when the process <![CDATA[<name>]]> is created.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.endProcess.<![CDATA[<name>]]> </literal> — Called when the process <![CDATA[<name>]]> ends.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.initProcess.<![CDATA[<name>]]> </literal> — Called when the process <![CDATA[<name>]]> is associated with the conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.initTask.<![CDATA[<name>]]> </literal> — Called when the task <![CDATA[<name>]]> is associated with the conversation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.startTask.<![CDATA[<name>]]> </literal> — Called when the task <![CDATA[<name>]]> is started.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.endTask.<![CDATA[<name>]]> </literal> — Called when the task <![CDATA[<name>]]> is ended.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.postCreate.<![CDATA[<name>]]> </literal> — Called when the component <![CDATA[<name>]]> is created.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.preDestroy.<![CDATA[<name>]]> </literal> — Called when the component <![CDATA[<name>]]> is destroyed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.beforePhase </literal> — Called before the start of a JSF phase.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.afterPhase </literal> — Called after the end of a JSF phase.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.postInitialization </literal> — Called when Seam has initialized and started up all components.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.postReInitialization </literal> — Called when Seam has re-initialized and started up all components after a redeploy.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.exceptionHandled.<![CDATA[<type>]]></literal> — Called when an uncaught exception is handled by Seam.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.exceptionHandled</literal> — Called when an uncaught exception is handled by Seam.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.exceptionNotHandled</literal> — Called when there was no handler for an uncaught exception.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.afterTransactionSuccess</literal> — Called when a transaction succeeds in the Seam Application Framework.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.afterTransactionSuccess.<![CDATA[<name>]]></literal> — Called when a transaction succeeds in the Seam Application Framework managing the entity <literal><![CDATA[<name>]]></literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.security.loggedOut</literal> — Called when a user logs out
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.security.loginFailed</literal> — Called when a user authentication attempt fails.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.security.loginSuccessful</literal> — Called when a user is successfully authenticated.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.security.notAuthorized</literal> — Called when an authorization check fails.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.security.notLoggedIn</literal> — Called when there is no authenticated user and authentication is required.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.security.postAuthenticate.</literal> — Called after a user is authenticated.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.security.preAuthenticate</literal> — Called before attempting to authenticate a user.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Seam components observe these events just as they observe any other component-driven event.
+ </para>
+ </section>
+
+ <section>
+ <title>Seam interceptors</title>
+ <para>
+ EJB3 introduced a standard interceptor model for session bean components. To add an interceptor to a bean, you need to write a class with a method annotated <literal>@AroundInvoke</literal> and annotate the bean with an <literal>@Interceptors</literal> annotation that specifies the name of the interceptor class. For example, the following interceptor checks that the user is logged in before allowing invoking an action listener method:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public class LoggedInInterceptor {
+ @AroundInvoke
+ public Object checkLoggedIn(InvocationContext invocation)
+ throws Exception {
+ boolean isLoggedIn = Contexts.getSessionContext()
+ .get("loggedIn")!=null;
+ if (isLoggedIn) {
+ //the user is already logged in return invocation.proceed();
+ } else {
+ //the user is not logged in, fwd to login page return "login";
+ }
+ }
+}]]>
+</programlisting>
+ <para>
+ To apply this interceptor to a session bean acting as an action listener, we must annotate the session bean <literal>@Interceptors(LoggedInInterceptor.class)</literal>. However, Seam builds upon the interceptor framework in EJB3 by allowing you to use <literal>@Interceptors</literal> as a meta-annotation for class level interceptors (those annotated <literal>@Target(TYPE)</literal>). In this example, we would create an <literal>@LoggedIn</literal> annotation, as follows:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Target(TYPE)
+ at Retention(RUNTIME)
+ at Interceptors(LoggedInInterceptor.class)
+public @interface LoggedIn {}]]>
+</programlisting>
+ <para>
+ We can now annotate our action listener bean with <literal>@LoggedIn</literal> to apply the interceptor.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateless
+ at Name("changePasswordAction")
+ at LoggedIn
+ at Interceptors(SeamInterceptor.class)
public class ChangePasswordAction implements ChangePassword {
-
- ...
-
- public String changePassword() { ... }
-
-}]]></programlisting>
+ ...
+ public String changePassword() {
+ ...
+ }
+}]]>
+</programlisting>
+ <para>
+ Where interceptor order is important, add <literal>@Interceptor</literal> annotations to your interceptor classes to specify a particular order of interceptors.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Interceptor(around={BijectionInterceptor.class,
+ ValidationInterceptor.class,
+ ConversationInterceptor.class},
+ within=RemoveInterceptor.class)
+
+public class LoggedInInterceptor {
+ ...
+}]]>
+</programlisting>
+ <para>
+ You can even have a client-side interceptor, for built-in EJB3 functions:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Interceptor(type=CLIENT)
+public class LoggedInInterceptor {
+ ...
+}]]>
+</programlisting>
+ <para>
+ EJB interceptors are stateful, and their lifecycles match that of the component they intercept. For interceptors that do not need to maintain state, Seam allows performance optimization where <literal>@Interceptor(stateless=true)</literal> is specified.
+ </para>
+ <para>
+ Much of Seam's functionality is implemented as a set of built-in Seam interceptors, including the interceptors named in the previous example. These interceptors exist for all interceptable Seam components; you need not specify them explicitly through annotation.
+ </para>
+ <para>
+ Seam interceptors can also be used with JavaBean components.
+ </para>
+ <para>
+ EJB defines interception not only for business methods (using <literal>@AroundInvoke</literal>), but also for the lifecycle methods <literal>@PostConstruct</literal>, <literal>@PreDestroy</literal>, <literal>@PrePassivate</literal> and <literal>@PostActive</literal>. Seam supports these lifecycle methods on both component and interceptor, not only for EJB3 beans, but also for JavaBean components (except <literal>@PreDestroy</literal>, which is not meaningful for JavaBean components).
+ </para>
+ </section>
+
+ <section>
+ <title>Managing exceptions</title>
+ <para>
+ JSF has a limited ability to handle exceptions. To work around this problem, Seam lets you define treatment of an exception class through annotation, or through declaration in an XML file. This combines with the EJB3-standard <literal>@ApplicationException</literal> annotation, which specifies whether the exception should cause a transaction rollback.
+ </para>
+ <section>
+ <title>Exceptions and transactions</title>
+ <para>
+ EJB specifies well-defined rules to control whether an exception immediately marks the current transaction for rollback, when thrown by a business method of the bean. <emphasis>System exceptions</emphasis> always cause a transaction rollback. <emphasis>Application exceptions</emphasis> do not cause a rollback by default, but they will cause a rollback if <literal>@ApplicationException(rollback=true)</literal> is specified. (An application exception is any checked exception, or any unchecked exception annotated <literal>@ApplicationException</literal>. A system exception is any unchecked exception without an <literal>@ApplicationException</literal> annotation.)
+ </para>
+ <note>
+ <para>
+ Marking a transaction for rollback is not the same as actually rolling back the transaction. The exception rules say that the transaction should be marked rollback only, but it may still be active after the exception is thrown.
+ </para>
+ </note>
+ <para>
+ Seam also applies the EJB3 exception rollback rules to Seam JavaBean components.
+ </para>
+ <para>
+ These rules apply only in the Seam component layer. When an exception occurs outside the Seam component layer, Seam rolls back any active transaction.
+ </para>
+ </section>
+
+ <section>
+ <title>Enabling Seam exception handling</title>
+ <para>
+ To enable Seam's exception handling, the master Servlet filter must be declared in <filename>web.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<filter>
+ <filter-name>Seam Filter</filter-name>
+ <filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
+</filter>
- <para>
- If interceptor ordering is important (it usually is), you can add
- <literal>@Interceptor</literal> annotations to your interceptor
- classes to specify a partial order of interceptors.
- </para>
-
-<programlisting role="JAVA"><![CDATA[@Interceptor(around={BijectionInterceptor.class,
- ValidationInterceptor.class,
- ConversationInterceptor.class},
- within=RemoveInterceptor.class)
-public class LoggedInInterceptor
-{
- ...
-}]]></programlisting>
-
- <para>
- You can even have a "client-side" interceptor, that runs around any of the built-in
- functionality of EJB3:
- </para>
-
-<programlisting role="JAVA"><![CDATA[@Interceptor(type=CLIENT)
-public class LoggedInInterceptor
-{
- ...
-}]]></programlisting>
-
- <para>
- EJB interceptors are stateful, with a lifecycle that is the same as the component
- they intercept. For interceptors which do not need to maintain state, Seam lets
- you get a performance optimization by specifying
- <literal>@Interceptor(stateless=true)</literal>.
- </para>
-
- <para>
- Much of the functionality of Seam is implemented as a set of built-in Seam interceptors,
- including the interceptors named in the previous example. You don't have to explicitly
- specify these interceptors by annotating your components; they exist for all interceptable
- Seam components.
- </para>
-
- <para>
- You can even use Seam interceptors with JavaBean components, not just EJB3 beans!
- </para>
-
- <para>
- EJB defines interception not only for business methods (using <literal>@AroundInvoke</literal>),
- but also for the lifecycle methods <literal>@PostConstruct</literal>, <literal>@PreDestroy</literal>,
- <literal>@PrePassivate</literal> and <literal>@PostActive</literal>. Seam supports all these
- lifecycle methods on both component and interceptor not only for EJB3 beans, but also for
- JavaBean components (except <literal>@PreDestroy</literal> which is not meaningful for JavaBean
- components).
- </para>
-
- </section>
-
- <section>
- <title>Managing exceptions</title>
-
- <para>
- JSF is surprisingly limited when it comes to exception handling. As a partial
- workaround for this problem, Seam lets you define how a particular class of
- exception is to be treated by annotating the exception class, or declaring
- the exception class in an XML file. This facility is meant to be combined with
- the EJB 3.0-standard <literal>@ApplicationException</literal> annotation which
- specifies whether the exception should cause a transaction rollback.
- </para>
-
- <section>
- <title>Exceptions and transactions</title>
-
- <para>
- EJB specifies well-defined rules that let us control whether an exception
- immediately marks the current transaction for rollback when it is thrown by
- a business method of the bean: <emphasis>system exceptions</emphasis> always
- cause a transaction rollback, <emphasis>application exceptions</emphasis> do
- not cause a rollback by default, but they do if
- <literal>@ApplicationException(rollback=true)</literal>
- is specified. (An application exception is any checked exception, or any
- unchecked exception annotated <literal>@ApplicationException</literal>.
- A system exception is any unchecked exception without an
- <literal>@ApplicationException</literal> annotation.)
- </para>
-
- <para>
- Note that there is a difference between marking a transaction for rollback,
- and actually rolling it back. The exception rules say that the transaction
- should be marked rollback only, but it may still be active after the
- exception is thrown.
- </para>
-
- <para>
- Seam applies the EJB 3.0 exception rollback rules also to Seam JavaBean
- components.
- </para>
-
- <para>
- But these rules only apply in the Seam component layer. What about an exception
- that is uncaught and propagates out of the Seam component layer, and out of the JSF
- layer? Well, it is always wrong to leave a dangling transaction open, so Seam
- rolls back any active transaction when an exception occurs and is uncaught
- in the Seam component layer.
- </para>
- </section>
-
- <section>
- <title>Enabling Seam exception handling</title>
-
- <para>
- To enable Seam's exception handling, we need to make sure we have the master servlet
- filter declared in <literal>web.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<filter>
- <filter-name>Seam Filter</filter-name>
- <filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
-</filter>
-
-<filter-mapping>
- <filter-name>Seam Filter</filter-name>
- <url-pattern>*.seam</url-pattern>
-</filter-mapping>]]></programlisting>
-
- <para>
- You need to disable Facelets development mode in <literal>web.xml</literal> and
- Seam debug mode in <literal>components.xml</literal> if you want your exception handlers
- to fire.
- </para>
-
- </section>
-
- <section>
- <title>Using annotations for exception handling</title>
-
- <para>
- The following exception results in a HTTP 404 error whenever it propagates out of the
- Seam component layer. It does not roll back the current transaction immediately when
- thrown, but the transaction will be rolled back if it the exception is not caught by
- another Seam component.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@HttpError(errorCode=404)
-public class ApplicationException extends Exception { ... }]]></programlisting>
-
- <para>
- This exception results in a browser redirect whenever it propagates out of the
- Seam component layer. It also ends the current conversation. It causes an immediate
- rollback of the current transaction.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Redirect(viewId="/failure.xhtml", end=true)
- at ApplicationException(rollback=true)
-public class UnrecoverableApplicationException extends RuntimeException { ... }]]></programlisting>
-
- <note>
- It is important to note that Seam cannot handle exceptions that occur during JSF's
- RENDER_RESPONSE phase, as it is not possible to perform a redirect once the response
- has started being written to.
- </note>
-
- <para>
- You can also use EL to specify the <literal>viewId</literal> to redirect to.
- </para>
-
- <para>
- This exception results in a redirect, along with a message to the user, when it
- propagates out of the Seam component layer. It also immediately rolls back the
- current transaction.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Redirect(viewId="/error.xhtml", message="Unexpected error")
-public class SystemException extends RuntimeException { ... }]]></programlisting>
-
- </section>
-
- <section>
- <title>Using XML for exception handling</title>
-
- <para>
- Since we can't add annotations to all the exception classes we are interested in,
- Seam also lets us specify this functionality in <literal>pages.xml</literal>.
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
-
+<filter-mapping>
+ <filter-name>Seam Filter</filter-name>
+ <url-pattern>*.seam</url-pattern>
+</filter-mapping>]]>
+</programlisting>
+ <para>
+ For the exception handlers to fire, you must disable Facelets development mode in <filename>web.xml</filename> and Seam debug mode in <filename>components.xml</filename>.
+ </para>
+ </section>
+
+ <section>
+ <title>Using annotations for exception handling</title>
+ <para>
+ The following exception results in a HTTP 404 error whenever it propagates outside the Seam component layer. It does not roll back the current transaction immediately when thrown, but the transaction will be rolled back if it the exception is not caught by another Seam component.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@HttpError(errorCode=404)
+public class ApplicationException extends Exception {
+ ...
+}]]>
+</programlisting>
+ <para>
+ This exception results in a browser redirect whenever it propagates outside the Seam component layer. It also ends the current conversation. It causes an immediate rollback of the current transaction.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Redirect(viewId="/failure.xhtml", end=true)
+ at ApplicationException(rollback=true)
+public class UnrecoverableApplicationException extends RuntimeException {
+ ...
+}]]>
+</programlisting>
+ <note>
+ <para>
+ Seam cannot handle exceptions that occur during JSF's <literal>RENDER_RESPONSE</literal> phase, as it is not possible to perform a redirect once writing to the response has begun.
+ </para>
+ </note>
+ <para>
+ You can also use EL to specify the <literal>viewId</literal> to redirect to.
+ </para>
+ <para>
+ When this exception propagates outside the Seam component layer, it results in a redirect and a message to the user. It also immediately rolls back the current transaction.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Redirect(viewId="/error.xhtml", message="Unexpected error")
+public class SystemException extends RuntimeException {
+ ...
+}]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Using XML for exception handling</title>
+ <para>
+ Since annotations cannot be added to all exception classes, Seam also lets us specify this functionality in <filename>pages.xml</filename>.
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
<exception class="javax.persistence.EntityNotFoundException">
- <http-error error-code="404"/>
+ <http-error error-code="404"/>
</exception>
<exception class="javax.persistence.PersistenceException">
- <end-conversation/>
- <redirect view-id="/error.xhtml">
- <message>Database access failed</message>
- </redirect>
+ <end-conversation/>
+ <redirect view-id="/error.xhtml">
+ <message>Database access failed</message>
+ </redirect>
</exception>
<exception>
- <end-conversation/>
- <redirect view-id="/error.xhtml">
- <message>Unexpected failure</message>
- </redirect>
- </exception>
-
-</pages>]]></programlisting>
-
- <para>
- The last <literal><exception></literal> declaration does not specify a class,
- and is a catch-all for any exception for which handling is not otherwise specified
- via annotations or in <literal>pages.xml</literal>.
- </para>
-
- <para>
- You can also use EL to specify the <literal>view-id</literal> to redirect to.
- </para>
-
- <para>
- You can also access the handled exception instance through EL, Seam places it in the
- conversation context, e.g. to access the message of the exception:
- </para>
-
- <programlisting role="XML"><![CDATA[...
+ <end-conversation/>
+ <redirect view-id="/error.xhtml">
+ <message>Unexpected failure</message>
+ </redirect>
+ </exception>
+</pages>]]>
+</programlisting>
+ <para>
+ The final <literal><![CDATA[<exception>]]></literal> declaration does not specify a class, and acts as catch-all for any exception without specified handling via annotations or in <filename>pages.xml</filename>.
+ </para>
+ <para>
+ You can also use EL to specify the <literal>view-id</literal> to redirect to.
+ </para>
+ <para>
+ You can also access the handled exception instance through EL. Seam places it in the conversation context. For example, to access the exception message:
+ </para>
+
+<programlisting role="XML"><![CDATA[...
throw new AuthorizationException("You are not allowed to do this!");
<pages>
-
- <exception class="org.jboss.seam.security.AuthorizationException">
- <end-conversation/>
- <redirect view-id="/error.xhtml">
- <message severity="WARN">#{org.jboss.seam.handledException.message}</message>
- </redirect>
- </exception>
-
-</pages>]]></programlisting>
-
- <para>
- <literal>org.jboss.seam.handledException</literal> holds the nested exception that
- was actually handled by an exception handler. The outermost (wrapper) exception is
- also available, as <literal>org.jboss.seam.caughtException</literal>.
- </para>
-
- <section>
- <title>Suppressing exception logging</title>
-
- <para>
- For the exception handlers defined in <literal>pages.xml</literal>, it is possible
- to declare the logging level at which the exception will be logged, or to even
- suppress the exception being logged altogether. The attributes <literal>log</literal>
- and <literal>log-level</literal> can be used to control exception logging. By setting
- <literal>log="false"</literal> as per the following example, then no log message will
- be generated when the specified exception occurs:
- </para>
-
- <programlisting role="XML"><![CDATA[ <exception class="org.jboss.seam.security.NotLoggedInException" log="false">
- <redirect view-id="/register.xhtml">
- <message severity="warn">You must be a member to use this feature</message>
- </redirect>
- </exception>]]></programlisting>
-
- <para>
- If the <literal>log</literal> attribute is not specified, then it defaults to <literal>true</literal>
- (i.e. the exception will be logged). Alternatively, you can specify the <literal>log-level</literal>
- to control at which log level the exception will be logged:
- </para>
-
- <programlisting role="XML"><![CDATA[ <exception class="org.jboss.seam.security.NotLoggedInException" log-level="info">
- <redirect view-id="/register.xhtml">
- <message severity="warn">You must be a member to use this feature</message>
- </redirect>
- </exception>]]></programlisting>
-
- <para>
- The acceptable values for <literal>log-level</literal> are: <literal>fatal, error, warn, info, debug</literal>
- or <literal>trace</literal>. If the <literal>log-level</literal> is not specified, or if an invalid value is
- configured, then it will default to <literal>error</literal>.
- </para>
-
- </section>
-
- </section>
-
- <section>
- <title>Some common exceptions</title>
-
- <para>
- If you are using JPA:
- </para>
-
- <programlisting role="XML"><![CDATA[<exception class="javax.persistence.EntityNotFoundException">
- <redirect view-id="/error.xhtml">
- <message>Not found</message>
- </redirect>
+ <exception class="org.jboss.seam.security.AuthorizationException">
+ <end-conversation/>
+ <redirect view-id="/error.xhtml">
+ <message severity="WARN">
+ #{org.jboss.seam.handledException.message}
+ </message>
+ </redirect>
+ </exception>
+</pages>]]>
+</programlisting>
+ <para>
+ <literal>org.jboss.seam.handledException</literal> holds the nested exception that was handled by an exception handler. The outermost (wrapper) exception is also available as <literal>org.jboss.seam.caughtException</literal>.
+ </para>
+ <section>
+ <title>Suppressing exception logging</title>
+ <para>
+ For the exception handlers defined in <filename>pages.xml</filename>, it is possible to declare the level at which the exception will be logged, or to suppress exception logging altogether. The <literal>log</literal> and <literal>log-level</literal> attributes are used to control exception logging. No log message will be generated when the specified exception occurs when <literal>log="false"</literal> is set, as shown here:
+ </para>
+
+<programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.security.NotLoggedInException"
+ log="false">
+ <redirect view-id="/register.xhtml">
+ <message severity="warn">
+ You must be a member to use this feature
+ </message>
+ </redirect>
+</exception>]]>
+</programlisting>
+ <para>
+ If the <literal>log</literal> attribute is not specified, then it defaults to <literal>true</literal> — that is, the exception will be logged. Alternatively, you can specify the <literal>log-level</literal> to control the level at which the exception will be logged:
+ </para>
+
+<programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.security.NotLoggedInException"
+ log-level="info">
+ <redirect view-id="/register.xhtml">
+ <message severity="warn">
+ You must be a member to use this feature
+ </message>
+ </redirect>
+</exception>]]>
+</programlisting>
+ <para>
+ The acceptable values for <literal>log-level</literal> are: <literal>fatal, error, warn, info, debug</literal>, and <literal>trace</literal>. If the <literal>log-level</literal> is not specified, or if an invalid value is configured, <literal>log-level</literal> will default to <literal>error</literal>.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Some common exceptions</title>
+ <para>
+ If you are using JPA:
+ </para>
+
+<programlisting role="XML"><![CDATA[<exception class="javax.persistence.EntityNotFoundException">
+ <redirect view-id="/error.xhtml">
+ <message>Not found</message>
+ </redirect>
</exception>
<exception class="javax.persistence.OptimisticLockException">
- <end-conversation/>
- <redirect view-id="/error.xhtml">
- <message>Another user changed the same data, please try again</message>
- </redirect>
-</exception>]]></programlisting>
-
- <para>
- If you are using the Seam Application Framework:
- </para>
-
- <programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.framework.EntityNotFoundException">
- <redirect view-id="/error.xhtml">
- <message>Not found</message>
- </redirect>
-</exception>]]></programlisting>
-
- <para>
- If you are using Seam Security:
- </para>
-
- <programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.security.AuthorizationException">
- <redirect>
- <message>You don't have permission to do this</message>
- </redirect>
+ <end-conversation/>
+ <redirect view-id="/error.xhtml">
+ <message>
+ Another user changed the same data, please try again
+ </message>
+ </redirect>
+</exception>]]>
+</programlisting>
+ <para>
+ If you are using the Seam Application Framework:
+ </para>
+
+<programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.framework.EntityNotFoundException">
+ <redirect view-id="/error.xhtml">
+ <message>Not found</message>
+ </redirect>
+</exception>]]>
+</programlisting>
+ <para>
+ If you are using Seam Security:
+ </para>
+
+<programlisting role="XML"><![CDATA[<exception class="org.jboss.seam.security.AuthorizationException">
+ <redirect>
+ <message>You don't have permission to do this</message>
+ </redirect>
</exception>
<exception class="org.jboss.seam.security.NotLoggedInException">
- <redirect view-id="/login.xhtml">
- <message>Please log in first</message>
- </redirect>
-</exception>]]></programlisting>
-
- <para>
- And, for JSF:
- </para>
-
- <programlisting role="XML"><![CDATA[<exception class="javax.faces.application.ViewExpiredException">
- <redirect view-id="/error.xhtml">
- <message>Your session has timed out, please try again</message>
- </redirect>
-</exception>]]></programlisting>
-
- <para>
- A <literal>ViewExpiredException</literal> occurs if the user posts back to a page once their session has
- expired. The <literal>conversation-required</literal> and <literal>no-conversation-view-id</literal>
- settings in the Seam page descriptor, discussed in <xref linkend="conversations.required"/>, give you
- finer-grained control over session expiration if you are accessing a page used within a conversation.
- </para>
- </section>
- </section>
-
+ <redirect view-id="/login.xhtml">
+ <message>Please log in first</message>
+ </redirect>
+</exception>]]>
+</programlisting>
+ <para>
+ And, for JSF:
+ </para>
+
+<programlisting role="XML"><![CDATA[<exception class="javax.Faces.application.ViewExpiredException">
+ <redirect view-id="/error.xhtml">
+ <message>Your session has timed out, please try again</message>
+ </redirect>
+</exception>]]>
+</programlisting>
+ <para>
+ A <literal>ViewExpiredException</literal> occurs when the user posts to a page after their session has expired. The <literal>conversation-required</literal> and <literal>no-conversation-view-id</literal> settings in the Seam page descriptor, discussed in <xref linkend="conversations.required"/>, allow finer-grained control over session expiration while accessing a page used within a conversation.
+ </para>
+ </section>
+
+ </section>
+<!-- Edit to JBPAPP_5_0-CR5 -->
+<!--
+ <section>
+ <title><literal>conversation-required</literal></title>
+ <para>
+ When specified as the attribute of a <literal>page</literal> element in <filename>pages.xml</filename>, <literal>conversation-required</literal> controls whether a page requires an active long-running or nested converstaion before rendering. If there is no active long-running or nested conversation when the page is accessed, a user will be redirected to the <literal>no-conversation-view-id</literal> view specified in the root <literal>pages</literal> element.
+ </para>
+
+<programlisting><![CDATA[<page view-id="/foo.xhtml" conversation-required="true"/>]]>
+</programlisting>
+ </section>
+-->
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Excel.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Excel.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Excel.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,3207 +1,2706 @@
-<?xml version="1.0" standalone="no"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [
-<!ENTITY excel 'the Microsoft® Excel® spreadsheet application'>
-<!ENTITY Excel 'The Microsoft® Excel® spreadsheet application'>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<chapter id="excel">
- <title>&Excel;</title>
- <para>
- Seam also supports generation of &excel; spreadsheets through the
- excellent <ulink url="http://jexcelapi.sourceforge.net/">JExcelAPI
- </ulink> library. The generated document is compatible with
- &excel; versions 95, 97, 2000, XP and 2003. Currently a limited
- subset of the library functionality is exposed but the ultimate
- goal is to be able to do everything the library allows for. Please
- refer to the JExcelAPI documentation for more information on
- capabilities and limitations.
- </para>
-
- <section id="excel.intro">
- <title>&Excel; support</title>
- <para>
- &Excel; <literal>jboss-seam-excel.jar</literal>. This JAR contains
- the &excel; JSF controls, which are used to construct views that can
- render the document, and the DocumentStore component, which serves
- the rendered document to the user. To include &excel; support in
- your application, include <literal>jboss-seam-excel.jar</literal>
- in your <literal>WEB-INF/lib</literal> directory along with the
- <literal>jxl.jar</literal> JAR file. Furthermore, you need to
- configure the DocumentStore servlet in your web.xml
- </para>
- <para>
- &Excel; Seam module requires the use of Facelets as the view
- technology. Additionally, it requires the use of the seam-ui package.
- </para>
- <para>
- The <literal>examples/excel</literal> project contains an example of
- &excel; support in action. It demonstrates proper deployment
- packaging, and it shows the exposed functionality.
- </para>
- <para>
- Customizing the module to support other kinds of &excel; spreadsheet
- API's has been made very easy. Implement the <literal>ExcelWorkbook
- </literal> interface, and register in components.xml.
- </para>
- <programlisting role="XML"><![CDATA[<excel:excelFactory>
- <property name="implementations">
- <key>myExcelExporter</key>
- <value>my.excel.exporter.ExcelExport</value>
- </property>
+<chapter id="excel" >
+ <title>The Microsoft® Excel® spreadsheet application</title>
+ <para>
+ Seam can generate <trademark class="registered">Microsoft</trademark> <trademark class="registered"><application>Excel</application></trademark> spreadsheets through the <ulink url="http://jexcelapi.sourceforge.net/">JExcelAPI</ulink> library. The document generated is compatible with <application>Microsoft Excel</application> versions 95, 97, 2000, XP, and 2003. At present, only a limited subset of the library functionality is available. Refer to the JExcelAPI documentation for more information about limitations and capabilities.
+ </para>
+ <section id="excel.intro">
+ <title>Microsoft Excel support</title>
+ <para>
+ To include <application>Microsoft Excel</application> support in your application, you must include <filename>jboss-seam-excel.jar</filename> and <filename>jxl.jar</filename> in your <literal>WEB-INF/lib</literal> directory. <filename>jboss-seam-excel.jar</filename> contains the <application>Microsoft Excel</application> JSF controls used to construct views for document rendering, and the DocumentStore component, which serves the rendered document to the user. You will also need to configure the DocumentStore Servlet in your <filename>web.xml</filename> file. The <application>Microsoft Excel</application> Seam module requires the <literal>seam-ui</literal> package, and that Facelets be used as the view technology.
+ </para>
+ <para>
+ You can see an example of <application>Microsoft Excel</application> support in action in the <literal>examples/excel</literal> project. This demonstrates the exposed functionality of the support, as well as correct deployment packaging.
+ </para>
+ <para>
+ You can easily customize the module to support other kinds of <application>Microsoft Excel</application> spreadsheet. Implement the <literal>ExcelWorkbook</literal> interface and register the following in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<excel:excelFactory>
+ <property name="implementations">
+ <key>myExcelExporter</key>
+ <value>my.excel.exporter.ExcelExport</value>
+ </property>
</excel:excelFactory>]]>
- </programlisting>
- <para>
- and register the excel namespace in the components tag with
- </para>
- <programlisting role="XML"><![CDATA[xmlns:excel="http://jboss.com/products/seam/excel"]]></programlisting>
- <para>
- Then set the UIWorkbook type to <literal>myExcelExporter</literal> and your
- own exporter will be used. Default is "jxl", but support for CSV has also been
- added, using the type "csv".
- </para>
- <para>
- See <xref linkend="itext.configuration" /> for information on how to configure
- the document servlet for serving the documents with an .xls extension.
- </para>
- <para>
- If you are having problems accessing the generated file under IE (especially
- with https), make sure you are not using too strict restrictions in the browser
- (see <ulink url="http://www.nwnetworks.com/iezones.htm/"/>), too strict security
- constraint in web.xml or a combination of both.
- </para>
- </section>
- <section id="excel.usage">
- <title>Creating a simple workbook</title>
- <para>
- Basic usage of the worksheet support is simple; it is used like a
- familiar <literal><h:dataTable></literal> and you can bind to a
- <literal>List</literal>, <literal>Set</literal>,
- <literal>Map</literal>, <literal>Array</literal> or
- <literal>DataModel</literal>.
- </para>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook xmlns:e="http://jboss.com/products/seam/excel">
- <e:worksheet>
- <e:cell column="0" row="0" value="Hello world!"/>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>
- That's not terribly useful, so lets have a look at a more common case:
- </para>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook xmlns:e="http://jboss.com/products/seam/excel">
- <e:worksheet value="#{data}" var="item">
- <e:column>
- <e:cell value="#{item.value}"/>
- </e:column>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>
- First we have the top-level workbook element which serves as the
- container and it doesn't have any attributes. The child-element
- worksheet has two attributes; value="#{data}" is the
- EL-binding to the data and var="item" is the name of the
- current item. Nested inside the worksheet is a single column and within
- it you see the cell which is the final bind to the data within the
- currently iterated item
- </para>
- <para>
- This is all you know to get started dumping your data to worksheets!
- </para>
-
- </section>
- <section id="excel.workbook">
- <title>Workbooks</title>
- <para>
- Workbooks are the top-level parents of worksheets and stylesheet links.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:workbook></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>type</literal>
- — Defines which export module to be used. The
- value is a string and can be either "jxl" or
- "csv". The default is "jxl".
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>templateURI</literal>
- — A template that should be used as a basis
- for the workbook. The value is a string (URI).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>arrayGrowSize</literal>
- — The amount of memory by which to increase
- the amount of memory allocated to storing the
- workbook data. For processes reading many small
- workbooks inside a WAS it might be necessary to
- reduce the default size. Default value is 1
- megabyte. The value is a number (bytes).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>autoFilterDisabled</literal>
- — Should autofiltering be disabled?. The
- value is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>cellValidationDisabled</literal>
- — Should cell validation be ignored? The
- value is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>characterSet</literal>
- — The character set. This is only used when
- the spreadsheet is read, and has no effect when
- the spreadsheet is written. The value is a string
- (character set encoding).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>drawingsDisabled</literal>
- — Should drawings be disabled? The value is a
- boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>excelDisplayLanguage</literal>
- — The language in which the generated file
- will display. The value is a string (two character
- ISO 3166 country code).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>excelRegionalSettings</literal>
- — The regional settings for the generated
- excel file. The value is a string (two character
- ISO 3166 country code).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>formulaAdjust</literal>
- — Should formulas be adjusted? The value is a
- boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>gcDisabled</literal>
- — Should garbage collection be disabled? The
- value is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>ignoreBlanks</literal>
- — Should blanks be ignored? The value is a
- boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>initialFileSize</literal>
- — The initial amount of memory allocated to
- store the workbook data when reading a worksheet.
- For processes reading many small workbooks
- inside a WAS it might be necessary to reduce the
- default size. Default value is 5 megabytes. The
- value is a number (bytes).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>locale</literal>
- — The locale used by JExcelApi to generate
- the spreadsheet. Setting this value has no effect
- on the language or region of the generated excel
- file. The value is a string.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>mergedCellCheckingDisabled</literal>
- — Should merged cell checking be disabled?
- The value is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>namesDisabled</literal>
- — Should handling of names be disabled? The
- value is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>propertySets</literal>
- — Should any property sets be enabled (such
- as macros) to be copied along with the workbook?
- Leaving this feature enabled will result in the
- JXL process using more memory. The value is a
- boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>rationalization</literal>
- — Should the cell formats be rationalized
- before writing out the sheet? The value is a
- boolean. Default is true.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>supressWarnings</literal>
- — Should warnings be suppressed?. Due to the
- change in logging in version 2.4, this will now
- set the warning behaviour across the JVM
- (depending on the type of logger used). The value
- is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>
- temporaryFileDuringWriteDirectory
- </literal>
- — Used in conjunction with the
- <literal>useTemporaryFileDuringWrite</literal>
- setting to set the target directory for the
- temporary files. This value can be NULL, in which
- case the normal system default temporary directory
- is used instead. The value is a string (the
- directory to which temporary files should be
- written).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>useTemporaryFileDuringWrite</literal>
- — Should a temporary file is used during the
- generation of the workbook. If not set, the
- workbook will take place entirely in memory.
- Setting this flag involves an assessment of the
- trade-offs between memory usage and performance.
- The value is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>workbookProtected</literal>
- — Should the workbook be protected? The value
- is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>filename</literal>
- — The filename to use for the download. The value
- is a string. Please note that if you map the DocumentServlet
- to some pattern, this file extension must also match.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>exportKey</literal>
- — A key under which to store the resulting data
- in a DocumentData object under the event scope. If used,
- there is no redirection.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elements</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal><e:link/></literal>
- — Zero or more stylesheet links (see
- <xref linkend="excel.fontsandlayout.link" />
- ).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><e:worksheet/></literal>
- — Zero or more worksheets (see
- <xref linkend="excel.worksheet" />
- ).
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:cell value="Hello World" row="0" column="0"/>
- </e:worksheet>
- <e:workbook>
- ]]>
- </programlisting>
- <para>defines a workbook with a worksheet and a greeting at A1</para>
-
- </section>
- <section id="excel.worksheet">
- <title>Worksheets</title>
- <para>
- Worksheets are the children of workbooks and the parent of columns and
- worksheet commands. They can also contain explicitly placed cells,
- formulas, images and hyperlinks. They are the pages that make up the
- workbook.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:worksheet></literal>
- </para>
- </entry>
- <entry valign="top">
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal>
- — An EL-expression to the backing data. The
- value is a string. The target of this expression is
- examined for an Iterable. Note that if the target is a Map,
- the iteration is done over the Map.Entry entrySet(), so you
- should use a .key or .value to target in your references.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>var</literal>
- — The current row iterator variable name that
- can later be referenced in cell value attributes.
- The value is a string.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>name</literal>
- — The name of the worksheet. The value is a
- string. Defaults to Sheet# where # is the
- worksheet index. If the given worksheet name
- exists, that sheet is selected. This can be used
- for merging several data sets into a single
- worksheet, just define the same name for them
- (using
- <literal>startRow</literal>
- and
- <literal>startCol</literal>
- to make sure that they don't occupy the same
- space).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>startRow</literal>
- — Defines the starting row for the data. The
- value is a number. Used for placing the data in
- other places than the upper-left corner
- (especially useful if having multiple data sets
- for a single worksheet). The defaults is 0.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>startColumn</literal>
- — Defines the starting column for the data.
- The value is a number. Used for placing the data
- in other places than the upper-left corner
- (especially useful if having multiple data sets
- for a single worksheet). The default is 0.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>automaticFormulaCalculation</literal>
- — Should formulas be automatically
- calculated? The value is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>bottomMargin</literal>
- — The bottom margin. The value is a number
- (inches).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>copies</literal>
- — The number of copies. The value is a
- number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>defaultColumnWidth</literal>
- — The default column width. The value is a
- number (characters * 256).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>defaultRowHeight</literal>
- — The default row height. The value is a
- number (1/20ths of a point).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>displayZeroValues</literal>
- — Should zero-values be displayed? The value
- is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fitHeight</literal>
- — The number of pages vertically that this
- sheet will be printed into. The value is a number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fitToPages</literal>
- — Should printing be fit to pages? The value
- is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>fitWidth</literal>
- — The number of pages widthwise which this
- sheet should be printed into. The value is a
- number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>footerMargin</literal>
- — The margin for any page footer. The value
- is a number (inches).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>headerMargin</literal>
- — The margin for any page headers. The value
- is a number (inches).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>hidden</literal>
- — Should the worksheet be hidden? The value
- is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>horizontalCentre</literal>
- — Should the worksheet be centered
- horizontally? The value is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>horizontalFreeze</literal>
- — The row at which the pane is frozen
- vertically. The value is a number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>horizontalPrintResolution</literal>
- — The horizontal print resolution. The value
- is a number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>leftMargin</literal>
- — The left margin. The value is a number
- (inches).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>normalMagnification</literal>
- — The normal magnification factor (not zoom or
- scale factor). The value is a number (percentage).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>orientation</literal>
- — The paper orientation for printing this
- sheet. The value is a string that can be either
- "landscape" or "portrait".
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pageBreakPreviewMagnification</literal>
- — The page break preview magnification factor
- (not zoom or scale factors). The value is a number
- (percentage).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pageBreakPreviewMode</literal>
- — Show page in preview mode? The value is a
- boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>pageStart</literal>
- — The page number at which to commence
- printing. The value is a number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>paperSize</literal>
- — The paper size to be used when printing
- this sheet. The value is a string that can be one
- of "a4", "a3", "letter", "legal" etc (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/PaperSize.html">
- jxl.format.PaperSize
- </ulink>
- ).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>password</literal>
- — The password for this sheet. The value is a
- string.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>passwordHash</literal>
- — The password hash - used only when copying
- sheets. The value is a string.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>printGridLines</literal>
- — Should grid lines be printed? The value is
- a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>printHeaders</literal>
- — Should headers be printed? The value is a
- boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>sheetProtected</literal>
- — Should the sheet be protected (read-only)?
- The value is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>recalculateFormulasBeforeSave</literal>
- — Should the formulas be re-calculated when
- the sheet is saved? The value is a boolean. Default value is false.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>rightMargin</literal>
- — The right margin. The value is a number
- (inches).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>scaleFactor</literal>
- — The scale factor for this sheet to be used
- when printing. The value is a number (percent).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>selected</literal>
- — Should the sheet be selected when the
- workbook opens? The value is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>showGridLines</literal>
- — Should gridlines be shown? The value is a
- boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>topMargin</literal>
- — The top margin. The value is a number
- (inches).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>verticalCentre</literal>
- — Center verically? The value is a boolean.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>verticalFreeze</literal>
- — The row at which the pane is frozen
- vertically. The value is a number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>verticalPrintResolution</literal>
- — The vertical print resolution. The value is
- a number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>zoomFactor</literal>
- — The zoom factor. Do not confuse zoom factor
- (which relates to the on screen view) with scale
- factor (which refers to the scale factor when
- printing). The value is a number (percentage).
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal><e:printArea/></literal>
- — Zero or more print area definitions (see
- <xref linkend="excel.printareatitles" />
- ).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><e:printTitle/></literal>
- — Zero or more print title definitions (see
- <xref linkend="excel.printareatitles" />
- ).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><e:headerFooter/></literal>
- — Zero or more header/footer definitions
- (see
- <xref linkend="excel.headersfooters" />
- ).
- </para>
- </listitem>
- <listitem>
- <para>
- Zero or more worksheet commands (see
- <xref linkend="excel.worksheetcommands" />
- ).
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>header</literal>— Contents that will
- be placed at the top of the data block, above the
- column headers (if any).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>footer</literal>— Contents that will
- be placed at the bottom of the data block, below the
- column footers (if any).
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet name="foo" startColumn="1" startRow="1">
- <e:column value="#{personList}" var="person">
- <f:facet name="header">
- <e:cell value="Last name"/>
- </f:facet>
- <e:cell value="#{person.lastName}"/>
- </e:column>
- </e:worksheet>
- <e:workbook>
- ]]>
- </programlisting>
- <para>defines a worksheet with the name "foo", starting at B2.</para>
- </section>
- <section id="excel.columns">
- <title>Columns</title>
- <para>
- Columns are the children of worksheets and the parents of cells,
- images, formulas and hyperlinks. They are the structure that control
- the iteration of the worksheet data. See <xref linkend="excel.fontsandlayout.columnsettings"/>
- for formatting.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:column></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal><e:cell/></literal>
- — Zero or more cells (see
- <xref linkend="excel.cells" />
- ).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><e:formula/></literal>
- — Zero or more formulas (see
- <xref linkend="excel.formulas" />
- ).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><e:image/></literal>
- — Zero or more images (see
- <xref linkend="excel.images" />
- ).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal><e:hyperLink/></literal>
- — Zero or more hyperlinks (see
- <xref linkend="excel.hyperlinks" />
- ).
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>header</literal>
- — This facet can/will contain one
- <literal><e:cell></literal>
- ,
- <literal><e:formula></literal>
- ,
- <literal><e:image></literal>
- or
- <literal><e:hyperLink></literal>
- that will be used as header for the column.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>footer</literal>
- — This facet can/will contain one
- <literal><e:cell></literal>
- ,
- <literal><e:formula></literal>
- ,
- <literal><e:image></literal>
- or
- <literal><e:hyperLink></literal>
- that will be used as footer for the column.
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:column value="#{personList}" var="person">
- <f:facet name="header">
- <e:cell value="Last name"/>
- </f:facet>
- <e:cell value="#{person.lastName}"/>
- </e:column>
- </e:worksheet>
- <e:workbook>
- ]]>
- </programlisting>
- <para>defines a column with a header and an iterated output</para>
-
- </section>
- <section id="excel.cells">
- <title>Cells</title>
- <para>
- Cells are nested within columns (for iteration) or inside worksheets
- (for direct placement using the <literal>column</literal> and
- <literal>row</literal> attributes) and are responsible for outputting
- the value (usually through an EL-expression involving the
- <literal>var</literal>-attribute of the datatable. See
- <xref linkend="excel.fontsandlayout.cells"/>
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:cell></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>column</literal>
- — The column where to place the cell. The
- default is the internal counter. The value is a
- number. Note that the value is 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>row</literal>
- — The row where to place the cell. The
- default is the internal counter. The value is
- number. Note that the value is 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>value</literal>
- — The value to display. Usually an
- EL-expression referencing the var-attribute of the
- containing datatable. The value is a string.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>comment</literal>
- — A comment to add to the cell. The value is
- a string.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>commentHeight</literal>
- — The height of the comment. The value is a
- number (in pixels).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>commentWidth</literal>
- — A width of the comment. The value is a
- number (in pixels).
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Zero or more validation conditions (see
- <xref linkend="excel.cells.validation" />
- ).
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:column value="#{personList}" var="person">
- <f:facet name="header">
- <e:cell value="Last name"/>
- </f:facet>
- <e:cell value="#{person.lastName}"/>
- </e:column>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>defines a column with a header and an iterated output</para>
- <section id="excel.cells.validation">
- <title>Validation</title>
- <para>
- Validations are nested inside cells or formulas.
- They add constrains for the cell data.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:numericValidation></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal>
- — The limit (or lower limit where
- applicable) of the validation. The value is a
- number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>value2</literal>
- — The upper limit (where applicable) of
- the validation. The value is a number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>condition</literal>
- — The validation condition. The value is a
- string.
- <itemizedlist>
- <listitem>
- <para>
- "equal" - requires the cell value to
- match the one defined in the
- value-attribute
- </para>
- </listitem>
- <listitem>
- <para>
- "greater_equal" - requires the cell
- value to be greater than or equal to
- the value defined in the
- value-attribute
- </para>
- </listitem>
- <listitem>
- <para>
- "less_equal" - requires the cell value
- to be less than or equal to the value
- defined in the value-attribute
- </para>
- </listitem>
- <listitem>
- <para>
- "less_than" - requires the cell value
- to be less than the value defined in
- the value-attribute
- </para>
- </listitem>
- <listitem>
- <para>
- "not_equal" - requires the cell value
- to not match the one defined in the
- value-attribute
- </para>
- </listitem>
- <listitem>
- <para>
- "between" - requires the cell value to
- be between the values defined in the
- value- and value2 attributes
- </para>
- </listitem>
- <listitem>
- <para>
- "not_between" - requires the cell
- value not to be between the values
- defined in the value- and value2
- attributes
- </para>
- </listitem>
- </itemizedlist>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:column value="#{personList}" var="person">
- <e:cell value="#{person.age">
- <e:numericValidation condition="between" value="4"
- value2="18"/>
- </e:cell>
- </e:column>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>
- adds numeric validation to a cell specifying that the value must be
- between 4 and 18.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:rangeValidation></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>startColumn</literal>
- — The starting column of the range of
- values to validate against. The value is a
- number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>startRow</literal>
- — The starting row of the range of values
- to validate against. The value is a number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>endColumn</literal>
- — The ending column of the range of values
- to validate against. The value is a number.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>endRow</literal>
- — The ending row of the range of values to
- validate against. The value is a number.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:column value="#{personList}" var="person">
- <e:cell value="#{person.position">
- <e:rangeValidation startColumn="0" startRow="0"
- endColumn="0" endRow="10"/>
- </e:cell>
- </e:column>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>
- adds validation to a cell specifying that the value must be in the
- values specified in range A1:A10.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:listValidation></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>
- Zero or more list validation items.
- </literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>
- e:listValidation is a just a container for holding multiple
- e:listValidationItem tags.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:listValidationItem></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal>
- — A values to validate against.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:column value="#{personList}" var="person">
- <e:cell value="#{person.position">
- <e:listValidation>
- <e:listValidationItem value="manager"/>
- <e:listValidationItem value="employee"/>
- </e:listValidation>
- </e:cell>
- </e:column>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>
- adds validation to a cell specifying that the value must be
- "manager" or "employee".
- </para>
- </section>
- <section id="excel.cells.formatmasks">
- <title>Format masks</title>
- <para>
- Format masks are defined in the mask attribute in
- cells or formulas. There are two
- types of format masks, one for numbers and one for dates
- </para>
- <section id="excel.formatmasks.numbers">
- <title>Number masks</title>
- <para>
- When encountering a format mask, first it is checked if it is in
- internal form, e.g "format1", "accounting_float" and so on (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/write/NumberFormats.html">
- jxl.write.NumberFormats
- </ulink>
- ).
- </para>
- <para>
- if the mask is not in the list, it is treated as a custom mask
- (see
- <ulink
- url="http://java.sun.com/javase/6/docs/api/java/text/DecimalFormat.html">
- java.text.DecimalFormat
- </ulink>
- ). e.g "0.00" and automatically converted to the closest match.
- </para>
- </section>
- <section id="excel.formatmasks.dates">
- <title>Date masks</title>
- <para>
- When encountering a format mask, first it is checked if it is in
- internal form, e.g "format1", "format2" and so on (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/write/DecimalFormats.html">
- jxl.write.DecimalFormats
- </ulink>
- ).
- </para>
- <para>
- if the mask is not in the list, it is treated as a custom mask
- (see
- <ulink
- url="http://java.sun.com/javase/6/docs/api/java/text/DateFormat.html">
- java.text.DateFormat
- </ulink>
- )., e.g "dd.MM.yyyy" and automatically converted to the closest
- match.
- </para>
- </section>
- </section>
- </section>
- <section id="excel.formulas">
- <title>Formulas</title>
- <para>
- Formulas are nested within columns (for iteration) or inside worksheets
- (for direct placement using the <literal>column</literal> and
- <literal>row</literal> attributes) and add calculations or functions to
- ranges of cells. They are essentially cells, see
- <xref linkend="excel.cells" /> for available attributes. Note that they
- can apply templates and have own font definitions etc just as normal
- cells.
- </para>
- <para>
- The formula of the cell is placed in the <literal>value</literal>
- -attribute as a normal &excel; notation. Note that when doing
- cross-sheet formulas, the worksheets must exist before referencing
- a formula against them. The value is a string.
- </para>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet name="fooSheet">
- <e:cell column="0" row="0" value="1"/>
- </e:worksheet>
- <e:worksheet name="barSheet">
- <e:cell column="0" row="0" value="2"/>
- <e:formula column="0" row="1"
- value="fooSheet!A1+barSheet1!A1">
- <e:font fontSize="12"/>
- </e:formula>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>
- defines an formula in B2 summing cells A1 in worksheets FooSheet and
- BarSheet
- </para>
- </section>
- <section id="excel.images">
- <title>Images</title>
- <para>
- Images are nested within columns (for iteration) or inside worksheets
- (for direct placement using the <literal>startColumn/startRow</literal>
- and <literal>rowSpan/columnSpan</literal> attributes). The spans are
- optional and if omitted, the image will be inserted without resizing.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:image></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>startColumn</literal>
- — The starting column of the image. The
- default is the internal counter. The value is a
- number. Note that the value is 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>startRow</literal>
- — The starting row of the image. The default
- is the internal counter. The value is a number.
- Note that the value is 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>columnSpan</literal>
- — The column span of the image. The default
- is one resulting in the default width of the
- image. The value is a float.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>rowSpan</literal>
- — The row span of the image. The default is
- the one resulting in the default height of the
- image. The value is a float.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>URI</literal>
- — The URI to the image. The value is a
- string.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:image startRow="0" startColumn="0" rowSpan="4"
- columnSpan="4" URI="http://foo.org/logo.jpg"/>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>defines an image in A1:E5 based on the given data</para>
-
- </section>
- <section id="excel.hyperlinks">
- <title>Hyperlinks</title>
- <para>
- Hyperlinks are nested within columns (for iteration) or inside
- worksheets (for direct placement using the
- <literal>startColumn/startRow</literal> and
- <literal>endColumn/endRow</literal> attributes). They add link
- navigation to URIs
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:hyperlink></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>startColumn</literal>
- — The starting column of the hyperlink. The
- default is the internal counter. The value is a
- number. Note that the value is 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>startRow</literal>
- — The starting row of the hyperlink. The
- default is the internal counter. The value is a
- number. Note that the value is 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>endColumn</literal>
- — The ending column of the hyperlink. The
- default is the internal counter. The value is a
- number. Note that the value is 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>endRow</literal>
- — The ending row of the hyperlink. The
- default is the internal counter. The value is a
- number. Note that the value is 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>URL</literal>
- — The URL to link. The value is a string.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>description</literal>
- — The description of the link. The value is a
- string.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:hyperLink startRow="0" startColumn="0" endRow="4"
- endColumn="4" URL="http://seamframework.org"
- description="The Seam Framework"/>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>
- defines a described hyperlink pointing to SFWK in the area A1:E5
- </para>
- </section>
- <section id="excel.headersfooters">
- <title>Headers and footers</title>
- <para>
- Headers and footers are childrens of worksheets and contain facets which
- in turn contains a string with commands that are parsed.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:header></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>left</literal>
- — The contents of the left header/footer
- part.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>center</literal>
- — The contents of the center header/footer
- part.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>right</literal>
- — The contents of the right header/footer
- part.
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:footer></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>left</literal>
- — The contents of the left header/footer
- part.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>center</literal>
- — The contents of the center header/footer
- part.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>right</literal>
- — The contents of the right header/footer
- part.
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <para>
- The content of the facets is a string that can contain various #-delimited
- commands as follows:
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>#date#</para>
- </entry>
- <entry valign="top">
- <para>Inserts the current date</para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#page_number#</para>
- </entry>
- <entry valign="top">
- <para>Inserts the current page number</para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#time#</para>
- </entry>
- <entry valign="top">
- <para>Inserts the current time</para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#total_pages#</para>
- </entry>
- <entry valign="top">
- <para>Inserts the total page count</para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#worksheet_name#</para>
- </entry>
- <entry valign="top">
- <para>Inserts the worksheet name</para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#workbook_name#</para>
- </entry>
- <entry valign="top">
- <para>Inserts the workbook name</para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#bold#</para>
- </entry>
- <entry valign="top">
- <para>
- Toggles bold font, use another #bold# to
- turn it off
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#italics#</para>
- </entry>
- <entry valign="top">
- <para>
- Toggles italic font, use another #italic# to
- turn it off
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#underline#</para>
- </entry>
- <entry valign="top">
- <para>
- Toggles underlining, use another #underline# to
- turn it off
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#double_underline#</para>
- </entry>
- <entry valign="top">
- <para>
- Toggles double underlining, use another #double_underline# to
- turn it off
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#outline#</para>
- </entry>
- <entry valign="top">
- <para>
- Toggles outlined font, use another #outline# to
- turn it off
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#shadow#</para>
- </entry>
- <entry valign="top">
- <para>
- Toggles shadowed font, use another #shadow# to
- turn it off
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#strikethrough#</para>
- </entry>
- <entry valign="top">
- <para>
- Toggles strikethrough font, use another #strikethrough# to
- turn it off
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#subscript#</para>
- </entry>
- <entry valign="top">
- <para>
- Toggles subscripted font, use another #subscript# to
- turn it off
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#superscript#</para>
- </entry>
- <entry valign="top">
- <para>
- Toggles superscript font, use another #superscript# to
- turn it off
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#font_name#</para>
- </entry>
- <entry valign="top">
- <para>
- Sets font name, used like #font_name=Verdana"
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>#font_size#</para>
- </entry>
- <entry valign="top">
- <para>
- Sets font size, use like #font_size=12#
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:header>
- <f:facet name="left">
- This document was made on #date# and has #total_pages# pages
- </f:facet>
- <f:facet name="right">
- #time#
- </f:facet>
- </e:header>
- <e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- </section>
- <section id="excel.printareatitles">
- <title>Print areas and titles</title>
- <para>
- Print areas and titles childrens of worksheets and worksheet templates
- and provide... print areas and titles.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:printArea></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>firstColumn</literal>
- — The column of the top-left corner of the
- area. The parameter is a number. Note that the
- value is 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>firstRow</literal>
- — The row of the top-left corner of the area.
- The parameter is a number. Note that the value is
- 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>lastColumn</literal>
- — The column of the bottom-right corner of
- the area. The parameter is a number. Note that the
- value is 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>lastRow</literal>
- — The row of the bottom-right corner of the
- area. The parameter is a number. Note that the
- value is 0-based.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:printTitles firstRow="0" firstColumn="0"
- lastRow="0" lastColumn="9"/>
- <e:printArea firstRow="1" firstColumn="0"
- lastRow="9" lastColumn="9"/>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>
- defines a print title between A1:A10 and a print area between B2:J10.
- </para>
- </section>
- <section id="excel.worksheetcommands">
- <title>Worksheet Commands</title>
- <para>
- Worksheet commands are children of workbooks and are usually executed
- only once.
- </para>
- <section id="excel.worksheetcommands.grouping">
- <title>Grouping</title>
- <para>Provides grouping of columns and rows.</para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:groupRows></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>startRow</literal>
- — The row to start the grouping at. The
- value is a number. Note that the value is
- 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>endRow</literal>
- — The row to end the grouping at. The
- value is a number. Note that the value is
- 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>collapse</literal>
- — Should the grouping be collapsed
- initially? The value is a boolean.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elements</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:groupColumns></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>startColumn</literal>
- — The column to start the grouping at. The
- value is a number. Note that the value is
- 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>endColumn</literal>
- — The column to end the grouping at. The
- value is a number. Note that the value is
- 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>collapse</literal>
- — Should the grouping be collapsed
- initially? The value is a boolean.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elements</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:groupRows startRow="4" endRow="9" collapse="true"/>
- <e:groupColumns startColumn="0" endColumn="9" collapse="false"/>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>
- groups rows 5 through 10 and columns 5 through 10 so that the rows
- are initially collapsed (but not the columns).
- </para>
-
- </section>
- <section id="excel.worksheetcommands.pagebreaks">
- <title>Page breaks</title>
- <para>Provides page breaks</para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:rowPageBreak></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>row</literal>
- — The row to break at. The value is a
- number. Note that the value is 0-based.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elements</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:rowPageBreak row="4"/>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>breaks page at row 5.</para>
- </section>
- <section id="excel.worksheetcommands.merging">
- <title>Merging</title>
- <para>Provides cell merging</para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:mergeCells></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>startRow</literal>
- — The row to start the merging from. The
- value is a number. Note that the value is
- 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>startColumn</literal>
- — The column to start the merging from.
- The value is a number. Note that the value is
- 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>endRow</literal>
- — The row to end the merging at. The value
- is a number. Note that the value is 0-based.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>endColumn</literal>
- — The column to end the merging at. The
- value is a number. Note that the value is
- 0-based.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elements</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:worksheet>
- <e:mergeCells startRow="0" startColumn="0" endRow="9" endColumn="9"/>
- </e:worksheet>
- </e:workbook>
- ]]>
- </programlisting>
- <para>merges the cells in the range A1:J10</para>
- </section>
- </section>
- <section id="excel.datatableexporter">
- <title>Datatable exporter</title>
- <para>
- If you prefer to export an existing JSF datatable instead of writing a
- dedicated XHTML document, this can also be achieved easily by executing
- the <literal>org.jboss.seam.excel.excelExporter.export</literal>
- component, passing in the id of the datatable as an Seam EL parameter.
- Consider you have a data table
- </para>
- <programlisting role="XML">
- <![CDATA[
- <h:form id="theForm">
- <h:dataTable id="theDataTable" value="#{personList.personList}"
- var="person">
- ...
- </h:dataTable>
- </h:form>
- ]]>
- </programlisting>
- <para>
- that you want to view as an
- <trademark class="registered">Microsoft</trademark>
- <trademark class="registered">Excel</trademark>
- spreadsheet. Place a
- </para>
- <programlisting role="XML">
- <![CDATA[
- <h:commandLink
- value="Export"
- action="#{excelExporter.export('theForm:theDataTable')}"
- />
- ]]>
- </programlisting>
- <para>
- in the form and you're done. You can of course execute the exporter
- with a button, s:link or other preferred method. There are also plans
- for a dedicated export tag that can be placed inside the datatable tag
- so you won't have to refer to the datatable by ID.
- </para>
- <para>
- See <xref linkend="excel.fontsandlayout"/> for formatting.
- </para>
- </section>
- <section id="excel.fontsandlayout">
- <title>Fonts and layout</title>
- <para>
- Controlling how the output look is done with a combination of CSSish
- style attributes and tag attributes. The most common ones (fonts, borders,
- backgrounds etc) are CSS and some more general settings are in tag attributes.
- </para>
- <para>
- The CSS attributes cascade down from parent to children and within one tag
- cascades over the CSS classes referenced in the <literal>styleClass</literal>
- attributes and finally over the CSS attributes defined in the
- <literal>style</literal> attribute. You can place them pretty much anywhere but
- e.g. placing a column width setting in a cell nested within that column makes
- little sense.
- </para>
- <para>
- If you have format masks or fonts that use special characters, such as spaces
- and semicolons, you can escape the css string with '' characters like xls-format-mask:'$;$'
- </para>
-
- <section id="excel.fontsandlayout.link">
- <title>Stylesheet links</title>
- <para>
- External stylesheets are references with the e:link tag. They are placed as
- children of the workbook.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><e:link></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Attributes</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>URL</literal>
- — The URL to the stylesheet
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Child elemenents</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Facets</emphasis>
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>none</literal>
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- <programlisting role="XML">
- <![CDATA[
- <e:workbook>
- <e:link URL="/css/excel.css"/>
- </e:workbook>
- ]]>
- </programlisting>
- <para>References a stylesheet that can be found at /css/excel.css</para>
- </section>
-
- <section id="excel.fontsandlayout.fonts">
- <title>Fonts</title>
- <para>
- This group of XLS-CSS attributes define a font and its attributes
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>xls-font-family</para>
- </entry>
- <entry valign="top">
- <para>
- The name of the font. Make sure that it's one that is
- supported by your system.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-font-size</para>
- </entry>
- <entry valign="top">
- <para>The font size. Use a plain number</para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-font-color</para>
- </entry>
- <entry valign="top">
- <para>
- The color of the font (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/Colour.html">
- jxl.format.Colour
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-font-bold</para>
- </entry>
- <entry valign="top">
- <para>
- Should the font be bold? Valid values are "true" and
- "false"
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-font-italic</para>
- </entry>
- <entry valign="top">
- <para>
- Should the font be italic? Valid values are "true"
- and "false"
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-font-script-style</para>
- </entry>
- <entry valign="top">
- <para>
- The script style of the font (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/ScriptStyle.html">
- jxl.format.ScriptStyle
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-font-underline-style</para>
- </entry>
- <entry valign="top">
- <para>
- The underline style of the font (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/UnderlineStyle.html">
- jxl.format.UnderlineStyle
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-font-struck-out</para>
- </entry>
- <entry valign="top">
- <para>
- Should the font be struck out? Valid values are
- "true" and "false"
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-font</para>
- </entry>
- <entry valign="top">
- <para>
- A shorthand notation for setting all the values. Place
- the font name last and use tick marks for fonts with
- spaces in them, e.g. 'Times New Roman'. Use "italic", "bold"
- and "struckout".
- </para>
- <para>
- Example style="xls-font: red bold italic 22 Verdana"
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
- <section id="excel.fontsandlayout.borders">
- <title>Borders</title>
- <para>
- This group of XLS-CSS attributes defines the borders of the cell
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>xls-border-left-color</para>
- </entry>
- <entry valign="top">
- <para>
- The border color of the left edge of the cell
- (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/Colour.html">
- jxl.format.Colour
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border-left-line-style</para>
- </entry>
- <entry valign="top">
- <para>
- The border line style of the left edge of the cell (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/LineStyle.html">
- jxl.format.LineStyle
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border-left</para>
- </entry>
- <entry valign="top">
- <para>
- A shorthand for setting line style and color of the left edge
- of the cell, e.g style="xls-border-left: thick red"
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border-top-color</para>
- </entry>
- <entry valign="top">
- <para>
- The border color of the top edge of the cell
- (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/Colour.html">
- jxl.format.Colour
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border-top-line-style</para>
- </entry>
- <entry valign="top">
- <para>
- The border line style of the top edge of the cell (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/LineStyle.html">
- jxl.format.LineStyle
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border-top</para>
- </entry>
- <entry valign="top">
- <para>
- A shorthand for setting line style and color of the top edge
- of the cell, e.g style="xls-border-top: red thick"
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border-right-color</para>
- </entry>
- <entry valign="top">
- <para>
- The border color of the right edge of the cell
- (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/Colour.html">
- jxl.format.Colour
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border-right-line-style</para>
- </entry>
- <entry valign="top">
- <para>
- The border line style of the right edge of the cell (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/LineStyle.html">
- jxl.format.LineStyle
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border-right</para>
- </entry>
- <entry valign="top">
- <para>
- A shorthand for setting line style and color of the right edge
- of the cell, e.g style="xls-border-right: thick red"
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border-bottom-color</para>
- </entry>
- <entry valign="top">
- <para>
- The border color of the bottom edge of the cell
- (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/Colour.html">
- jxl.format.Colour
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border-bottom-line-style</para>
- </entry>
- <entry valign="top">
- <para>
- The border line style of the bottom edge of the cell (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/LineStyle.html">
- jxl.format.LineStyle
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border-bottom</para>
- </entry>
- <entry valign="top">
- <para>
- A shorthand for setting line style and color of the bottom edge
- of the cell, e.g style="xls-border-bottom: thick red"
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-border</para>
- </entry>
- <entry valign="top">
- <para>
- A shorthand for setting line style and color for all edges
- of the cell, e.g style="xls-border: thick red"
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
- <section id="excel.fontsandlayout.background">
- <title>Background</title>
- <para>
- This group of XLS-CSS attributes defines the background of the cell
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>xls-background-color</para>
- </entry>
- <entry valign="top">
- <para>
- The color of the background (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/LineStyle.html">
- jxl.format.LineStyle
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-background-pattern</para>
- </entry>
- <entry valign="top">
- <para>
- The pattern of the background (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/Pattern.html">
- jxl.format.Pattern
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-background</para>
- </entry>
- <entry valign="top">
- <para>
- A shorthand for setting the background color and pattern. See above for rules.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
- <section id="excel.fontsandlayout.columnsettings">
- <title>Column settings</title>
- <para>
- This group of XLS-CSS attributes defines the column widths etc.
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>xls-column-width</para>
- </entry>
- <entry valign="top">
- <para>
- The width of the column. Use largeish values (~5000) to start with.
- Used by the e:column in xhtml mode.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-column-widths</para>
- </entry>
- <entry valign="top">
- <para>
- The width of the column. Use largeish values (~5000) to start with.
- Used by the excel exporter, placed in the datatable style attribute.
- Use numerical values or * to bypass a column.
- </para>
- <para>
- Example style="xls-column-widths: 5000, 5000, *, 10000"
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-column-autosize</para>
- </entry>
- <entry valign="top">
- <para>
- Should an attempt be made to autosize the column? Valid values
- are "true" and "false".
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-column-hidden</para>
- </entry>
- <entry valign="top">
- <para>
- Should the column be hidden? Valid values are "true" and "false".
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-column-export</para>
- </entry>
- <entry valign="top">
- <para>
- Should the column be shown in export? Valid values are "true" and "false". Default is "true".
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
- <section id="excel.fontsandlayout.cellsettings">
- <title>Cell settings</title>
- <para>
- This group of XLS-CSS attributes defines the cell properties
- </para>
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
- <tbody>
- <row>
- <entry valign="top">
- <para>xls-alignment</para>
- </entry>
- <entry valign="top">
- <para>
- The alignment of the cell value (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/Alignment.html">
- jxl.format.Alignment
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-force-type</para>
- </entry>
- <entry valign="top">
- <para>
- The forced type of the cell data. The value is a string that can be one
- of "general", "number", "text", "date", "formula" or "bool". The type
- is automatically detected so there is rarely any use for this attribute.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-format-mask</para>
- </entry>
- <entry valign="top">
- <para>
- The format mask of the cell, see <xref linkend="excel.cells.formatmasks" />
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-indentation</para>
- </entry>
- <entry valign="top">
- <para>
- The indentation of the cell value. The value is numeric.
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-locked</para>
- </entry>
- <entry valign="top">
- <para>
- Should the cell be locked. Use with workbook level locked.
- Valid values are "true" and "false".
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-orientation</para>
- </entry>
- <entry valign="top">
- <para>
- The orientation of the cell value (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/Orientation.html">
- jxl.format.Orientation
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-vertical-alignment</para>
- </entry>
- <entry valign="top">
- <para>
- The vertical alignment of the cell value (see
- <ulink
- url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/format/VerticalAlignment.html">
- jxl.format.VerticalAlignment
- </ulink>
- ).
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-shrink-to-fit</para>
- </entry>
- <entry valign="top">
- <para>
- Should the cell values shrink to fit?
- Valid values are "true" and "false".
- </para>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>xls-wrap</para>
- </entry>
- <entry valign="top">
- <para>
- Should the cell wrap with newlines?
- Valid values are "true" and "false".
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
- <section id="excel.fontsandlayout.datatableexporter">
- <title>The datatable exporter</title>
- <para>
- The datatable exporter uses the same xls-css attributes as the xhtml
- document with the exception that column widths are defined with the
- <literal>xls-column-widths</literal> attribute on the datatable (since
- the UIColumn doesn't support the style or styleClass attributes).
- </para>
- </section>
- <section id="excel.fontsandlayout.examples">
- <title>Layout examples</title>
- <para>
- TODO
- </para>
- </section>
- <section id="excel.fontsandlayout.limitations">
- <title>Limitations</title>
- <para>
- In the current version there are some known limitations regarding
- CSS support
- </para>
- <itemizedlist>
- <listitem>
- <para>
- When using .xhtml documents, stylesheets must be referenced
- through the <literal><e:link></literal> tag
- </para>
- </listitem>
- <listitem>
- <para>
- When using the datatable exporter, CSS must be entered through
- style-attributes, external stylesheets are not supported
- </para>
- </listitem>
- </itemizedlist>
- </section>
- </section>
- <section id="excel.i18n">
- <title>Internationalization</title>
- <para>
- There are only two resources bundle keys used, both for invalid data format and both take a
- parameter (the invalid value)
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>org.jboss.seam.excel.not_a_number</literal>
- — When a value thought to be a number could not be treated as such
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>org.jboss.seam.excel.not_a_date</literal>
- — When a value thought to be a date could not be treated as such
- </para>
- </listitem>
- </itemizedlist>
- </section>
- <section id="excel.links">
- <title>Links and further documentation</title>
- <para>
- The core of the &excel; functionality is based on the excellent
- JExcelAPI library which can be found on
- <ulink url="http://jexcelapi.sourceforge.net">http://jexcelapi.sourceforge.net/</ulink>
- and most features and possible limitations are inherited from here.
- </para>
- <para>
- If you use the forum or mailing list, please remember that they don't
- know anything about Seam and the usage of their library, any issues are
- best reported in the JBoss Seam JIRA under the "excel" module.
- </para>
- </section>
+</programlisting>
+ <para>
+ Register the <application>Microsoft Excel</application> namespace in the components tag like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[xmlns:excel="http://jboss.com/products/seam/excel"]]>
+</programlisting>
+ <para>
+ Then set the UIWorkbook type to <literal>myExcelExporter</literal> to use your own preferred exporter. The default here is <literal>jxl</literal>, but you can also use CSV with the <literal>csv</literal> type.
+ </para>
+ <para>
+ See <xref linkend="itext.configuration" /> for information about how to configure the document servlet for serving documents with an .xls extension.
+ </para>
+ <para>
+ If you have trouble accessing the generated file under <trademark class="registered">Microsoft</trademark> <trademark class="registered"><application>Internet Explorer</application></trademark>, especially with HTTPS, check that your <filename>web.xml</filename> or browser security constraints (see <ulink url="http://www.nwnetworks.com/iezones.htm/"></ulink>) are not too strict.
+ </para>
+ </section>
+
+ <section id="excel.usage">
+ <title>Creating a simple workbook</title>
+ <para>
+ The worksheet support is used like a <literal><![CDATA[<h:dataTable>]]></literal>, and can be bound to a <literal>List</literal>, <literal>Set</literal>, <literal>Map</literal>, <literal>Array</literal> or <literal>DataModel</literal>.
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook xmlns:e="http://jboss.com/products/seam/excel">
+ <e:worksheet>
+ <e:cell column="0" row="0" value="Hello world!"/>
+ </e:worksheet>
+</e:workbook> ]]>
+</programlisting>
+ <para>
+ The following is a more common use case:
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook xmlns:e="http://jboss.com/products/seam/excel">
+ <e:worksheet value="#{data}" var="item">
+ <e:column>
+ <e:cell value="#{item.value}"/>
+ </e:column>
+ </e:worksheet>
+</e:workbook> ]]>
+</programlisting>
+ <para>
+ The top-level <literal>workbook</literal> element serves as the container, and has no attributes. The child element, <literal>worksheet</literal>, has two attributes: <literal>value="#{data}"</literal> is the EL-binding to the data, and <literal>var="item"</literal> is the name of the current item. The worksheet contains a single <literal>column</literal>. Within this is the <literal>cell</literal>, which is the final bind to the data in the currently iterated item.
+ </para>
+ <para>
+ Now you can bind your data into spreadsheets.
+ </para>
+ </section>
+
+ <section id="excel.workbook">
+ <title>Workbooks</title>
+ <para>
+ Workbooks are the top-level parents of worksheets and stylesheet links.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:workbook>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>type</literal> — Defines the export model. The value is a string and can be either <literal>jxl</literal> or <literal>csv</literal>. The default is <literal>jxl</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>templateURI</literal> — A template that forms the basis of the workbook. The value is a string (URI).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>arrayGrowSize</literal> — The amount of memory (in bytes) by which the workbook data storage space should be increased. If your process reads many small workbooks inside a web application server, you may need to reduce the default size. The default value is 1 MB.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>autoFilterDisabled</literal> — A Boolean value determining whether autofiltering is disabled.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>cellValidationDisabled</literal> — A Boolean value determining whether cell validation is ignored.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>characterSet</literal> — The character set used to read the spreadsheet. Has no effect on the spreadsheet being written. The value is a string (character set encoding).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>drawingsDisabled</literal> — A Boolean value determining whether drawings are disabled.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>excelDisplayLanguage</literal> — The language that the generated file will display in. The value is a string (two character ISO 3166 country code).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>excelRegionalSettings</literal> — The regional settings for the generated file. The value is a string (two character ISO 3166 country code).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>formulaAdjust</literal> — A Boolean determining whether formulas are adjusted.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>gcDisabled</literal> — A Boolean determining whether garbage collection is disabled.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ignoreBlanks</literal> — A Boolean value determining whether blanks are ignored.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>initialFileSize</literal> — The initial amount of memory (in bytes) allocated to workbook data storage when reading a worksheet. If your process reads many small workbooks inside a web application server, you may need to reduce the default size. The default value is 5 MB.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>locale</literal> — The locale JExcelAPI uses to generate the spreadsheet. This value has no effect on the language or region of the generated file. The value is a string.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>mergedCellCheckingDisabled</literal> — A Boolean determining whether merged cell checking is disabled.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>namesDisabled</literal> — A Boolean determining whether name handling is disabled.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>propertySets</literal> — A Boolean determining whether property sets (such as macros) are copied with the workbook. If this feature is enabled, the JXL process will use more memory.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rationalization</literal> — A Boolean determining whether cell formats are rationalized before the sheet is written. Defaults to <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>supressWarnings</literal> — A Boolean determining whether warnings are suppressed. Depending on the type of logger used, this sets the warning behavior across the JVM.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>temporaryFileDuringWriteDirectory</literal> — A string value containing the target directory for temporary files. Used in conjuction with <literal>useTemporaryFileDuringWrite</literal>. If set to <literal>NULL</literal>, the default temporary directory is used instead.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>useTemporaryFileDuringWrite</literal> — A Boolean determining whether a temporary file is used during workbook generation. If not set, the workbook will be generated entirely in memory. Setting this flag involves an assessment of the trade-offs between memory usage and performance.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>workbookProtected</literal> — A Boolean determining whether the workbook is protected.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>filename</literal> — A string value to be used as the download's filename. If you map the DocumentServlet to some pattern, its file extension must match.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>exportKey</literal> — A key to store event-scoped data in a DocumentData object. If used, there is no redirection.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal><![CDATA[<e:link/>]]></literal> — Zero or more stylesheet links. (See <xref linkend="excel.fontsandlayout.link" />.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><![CDATA[<e:worksheet/>]]></literal> — Zero or more worksheets. (See <xref linkend="excel.worksheet" />.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[<e:workbook>
+ <e:worksheet>
+ <e:cell value="Hello World" row="0" column="0"/>
+ </e:worksheet>
+<e:workbook> ]]>
+</programlisting>
+ <para>
+ This defines a workbook with a worksheet and a greeting at cell A1.
+ </para>
+ </section>
+
+ <section id="excel.worksheet">
+ <title>Worksheets</title>
+ <para>
+ Worksheets are the children of workbooks and the parent of columns and worksheet commands. They can also contain explicitly placed cells, formulas, images and hyperlinks. They are the pages that make up the workbook.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:worksheet>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — An EL-expression string to the backing data. The target of this expression is examined for an Iterable. If the target is a Map, the iteration is done over the Map.Entry entrySet(), so use a .key or .value to target in your references.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>var</literal> — The current row iterator variable name to be referenced in cell value attributes. The value is a string.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>name</literal> — The name of the worksheet. The value is a string. Defaults to <literal>Sheet<![CDATA[<replaceable>#</replaceable>]]></literal> where # is the worksheet index. If the given worksheet name exists, that sheet is selected. This can be used to merge several data sets into a single worksheet by defining each worksheet with the same name — use <literal>startRow</literal> and <literal>startCol</literal> to make sure they do not occupy the same space.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>startRow</literal> — A number value that defines the starting row for the data. This is used to position data from places other than the upper-left corner. This is particularly useful when using multiple data sets for a single worksheet. The default value is <literal>0</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>startColumn</literal> — A number value that defines the starting column for the data. This is used to position data from places other than the upper-left corner. This is particularly useful when using multiple data sets for a single worksheet. The default value is <literal>0</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>automaticFormulaCalculation</literal> — A Boolean determining whether formulas are calculated automatically.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>bottomMargin</literal> — A number value determining the bottom margin in inches.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>copies</literal> — A number value determining the number of copies.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>defaultColumnWidth</literal> — A number value defining the default column width, in characters * 256.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>defaultRowHeight</literal> — A number value defining the default row height, in 1/20ths of a point.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>displayZeroValues</literal> — A Boolean determining whether zero values are displayed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fitHeight</literal> — A number value defining the number of pages vertically that this sheet will print into.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fitToPages</literal> — A Boolean determining whether printing fits to pages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fitWidth</literal> — A number value defining the number of pages across that this sheet will print into.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>footerMargin</literal> — A number value defining the margin for any page footer in inches.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>headerMargin</literal> — A number value defining the margin for any page header in inches.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>hidden</literal> — A Boolean determining whether the worksheet is hidden.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>horizontalCentre</literal> — A Boolean determining whether the worksheet is centred horizontally.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>horizontalFreeze</literal> — A number value defining the column at which the pane is frozen horizontally.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>horizontalPrintResolution</literal> — A number value defining the horizontal print resolution.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>leftMargin</literal> — A number value defining the left margin in inches.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>normalMagnification</literal> — A number value defining the normal magnification factor as a percentage. This is not the zoom or scale factor.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>orientation</literal> — A string value that determines the paper orientation when this sheet is printed. Can be either <literal>landscape</literal> or <literal>portrait</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pageBreakPreviewMagnification</literal> — A number value defining the page break preview magnification factor as a percentage.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pageBreakPreviewMode</literal> — A Boolean determining whether the page is shown in preview mode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>pageStart</literal> — A number value defining the page number at which to commence printing.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>paperSize</literal> — A string value determining the paper size to be used when printing. Possible values are <literal>a4</literal>, <literal>a3</literal>, <literal>letter</literal>, <literal>legal</literal>, etc. For a full list, see <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/PaperSize.html">jxl.format.PaperSize</ulink>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>password</literal> — A string value determining the password for this sheet.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>passwordHash</literal> — A string value determining the password hash. This is used only when copying sheets.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>printGridLines</literal> — A Boolean determining whether grid lines are printed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>printHeaders</literal> — A Boolean determining whether headers are printed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>sheetProtected</literal> — A Boolean determining whether the sheet is read-only.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>recalculateFormulasBeforeSave</literal> — A Boolean determining whether formulas are recalculated when the sheet is saved. The default value is <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rightMargin</literal> — A number value defining the right margin in inches.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>scaleFactor</literal> — A number value defining the scale factor (as a percentage) used when this sheet is printed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>selected</literal> — A Boolean value determining whether the sheet is selected automatically when the workbook opens.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>showGridLines</literal> — A Boolean determining whether grid lines are shown.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>topMargin</literal> — A number value defining the top margin in inches.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>verticalCentre</literal> — A Boolean determining whether the sheet is vertically centred.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>verticalFreeze</literal> — A number value determining the row at which the pane is frozen vertically.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>verticalPrintResolution</literal> — A number value determining the vertical print resolution.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>zoomFactor</literal> — A number value determining the zoom factor. This relates to on-screen view, and should not be confused with the scale factor.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal><![CDATA[<e:printArea/>]]></literal> — Zero or more print area definitions. (See <xref linkend="excel.printareatitles" />.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><![CDATA[<e:printTitle/>]]></literal> — Zero or more print title definitions. (See <xref linkend="excel.printareatitles" />.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><![CDATA[<e:headerFooter/>]]></literal> — Zero or more header/footer definitions. (See <xref linkend="excel.headersfooters" />.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Zero or more worksheet commands. (See <xref linkend="excel.worksheetcommands" />.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>header</literal>— Contents placed at the top of the data block, above the column headers (if any).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>footer</literal>— Contents placed at the bottom of the data block, below the column footers (if any).
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet name="foo" startColumn="1" startRow="1">
+ <e:column value="#{personList}" var="person">
+ <f:facet name="header">
+ <e:cell value="Last name"/>
+ </f:facet>
+ <e:cell value="#{person.lastName}"/>
+ </e:column>
+ </e:worksheet>
+<e:workbook> ]]>
+</programlisting>
+ <para>
+ This defines a worksheet with the name "foo", starting at B2.
+ </para>
+ </section>
+
+ <section id="excel.columns">
+ <title>Columns</title>
+ <para>
+ Columns are the children of worksheets and the parents of cells, images, formulas and hyperlinks. They control the iteration of the worksheet data. See <xref linkend="excel.fontsandlayout.columnsettings" /> for formatting.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:column>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal><![CDATA[<e:cell/>]]></literal> — Zero or more cells. (See <xref linkend="excel.cells" />.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><![CDATA[<e:formula/>]]></literal> — Zero or more formulas. (See <xref linkend="excel.formulas" />.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><![CDATA[<e:image/>]]></literal> — Zero or more images. (See <xref linkend="excel.images" />.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal><![CDATA[<e:hyperLink/>]]></literal> — Zero or more hyperlinks (see <xref linkend="excel.hyperlinks" /> ).
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>header</literal> — This facet can/will contain one <literal><![CDATA[<e:cell>]]></literal>, <literal><![CDATA[<e:formula>]]></literal>, <literal><![CDATA[<e:image>]]></literal> or <literal><![CDATA[<e:hyperLink>]]></literal>, which will be used as header for the column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>footer</literal> — This facet can/will contain one <literal><![CDATA[<e:cell>]]></literal>, <literal><![CDATA[<e:formula>]]></literal>, <literal><![CDATA[<e:image>]]></literal> or <literal><![CDATA[<e:hyperLink>]]></literal>, which will be used as footer for the column.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:column value="#{personList}" var="person">
+ <f:facet name="header">
+ <e:cell value="Last name"/>
+ </f:facet>
+ <e:cell value="#{person.lastName}"/>
+ </e:column>
+ </e:worksheet>
+<e:workbook> ]]>
+</programlisting>
+ <para>
+ This defines a column with a header and an iterated output.
+ </para>
+ </section>
+
+ <section id="excel.cells">
+ <title>Cells</title>
+ <para>
+ Cells are nested within columns (for iteration) or inside worksheets (for direct placement using the <literal>column</literal> and <literal>row</literal> attributes) and are responsible for outputting the value, usually through an EL-expression involving the <literal>var</literal> attribute of the datatable. See <xref linkend="excel.fontsandlayout.cellsettings" />.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:cell>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>column</literal> — A number value denoting the column that the cell belongs to. The default is the internal counter. Note that the value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>row</literal> — A number value denoting the row where to place the cell. The default is the internal counter. Note that the value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>value</literal> — A string defining the display value. Usually an EL-expression referencing the var-attribute of the containing datatable.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>comment</literal> — A string value defining a comment attached to the cell.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>commentHeight</literal> — The comment height in pixels.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>commentWidth</literal> — The comment width in pixels.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Zero or more validation conditions. (See <xref linkend="excel.cells.validation" />.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:column value="#{personList}" var="person">
+ <f:facet name="header">
+ <e:cell value="Last name"/>
+ </f:facet>
+ <e:cell value="#{person.lastName}"/>
+ </e:column>
+ </e:worksheet>
+</e:workbook> ]]>
+</programlisting>
+ <para>
+ This defines a column with a header and an iterated output.
+ </para>
+ <section id="excel.cells.validation">
+ <title>Validation</title>
+ <para>
+ Validations are nested inside cells or formulas. They add constraints to cell data.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:numericValidation>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — A number value denoting the limit (or lower limit where applicable) of the validation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>value2</literal> — A number value denoting the upper limit (where applicable) of the validation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>condition</literal> — A string value defining the validation condition.
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>equal</literal> — requires the cell value to match the one defined in the value-attribute.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>greater_equal</literal> — requires the cell value to be greater than or equal to the value defined in the value-attribute.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>less_equal</literal> — requires the cell value to be less than or equal to the value defined in the value-attribute.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>less_than</literal> — requires the cell value to be less than the value defined in the value-attribute.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>not_equal</literal> — requires the cell value to not match the one defined in the value-attribute.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>between</literal> — requires the cell value to be between the values defined in the value and value2 attributes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>not_between</literal> — requires the cell value not to be between the values defined in the value- and value2 attributes.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:column value="#{personList}" var="person">
+ <e:cell value="#{person.age">
+ <e:numericValidation condition="between" value="4" value2="18"/>
+ </e:cell>
+ </e:column>
+ </e:worksheet>
+</e:workbook>]]>
+</programlisting>
+ <para>
+ This adds numeric validation to a cell, specifying that the value must be between 4 and 18.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:rangeValidation>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>startColumn</literal> — A number value denoting the first column to validate against.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>startRow</literal> — A number value denoting the first row to validate against.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>endColumn</literal> — A number value denoting the last column to validate against.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>endRow</literal> — A number value denoting the last row to validate against.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:column value="#{personList}" var="person">
+ <e:cell value="#{person.position">
+ <e:rangeValidation startColumn="0" startRow="0" endColumn="0"
+ endRow="10"/>
+ </e:cell>
+ </e:column>
+ </e:worksheet>
+</e:workbook> ]]>
+</programlisting>
+ <para>
+ This adds validation to a cell, specifying that the value must exist within the values specified in range A1:A10.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:listValidation>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal> Zero or more list validation items. </literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ e:listValidation is a just a container for holding multiple e:listValidationItem tags.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:listValidationItem>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — A value to validate against.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:column value="#{personList}" var="person">
+ <e:cell value="#{person.position">
+ <e:listValidation>
+ <e:listValidationItem value="manager"/>
+ <e:listValidationItem value="employee"/>
+ </e:listValidation>
+ </e:cell>
+ </e:column>
+ </e:worksheet>
+</e:workbook>]]>
+</programlisting>
+ <para>
+ This adds validation to a cell, specifying that the value must be "manager" or "employee".
+ </para>
+ </section>
+
+ <section id="excel.cells.formatmasks">
+ <title>Format masks</title>
+ <para>
+ Format masks are defined in the <literal>mask</literal> attribute in a cell or formula. There are two types of format masks: one for numbers, and one for dates.
+ </para>
+ <section id="excel.formatmasks.numbers">
+ <title>Number masks</title>
+ <para>
+ When a format mask is encountered, a check is executed to see if the mask follows an internal form, for example, <literal>format1</literal>, <literal>accounting_float</literal>, etc. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ write/NumberFormats.html">jxl.write.NumberFormats</ulink>.)
+ </para>
+ <para>
+ If the mask is not part of the internal list, it is treated as a custom mask (for example, <literal>0.00</literal>), and automatically converted to the closest match. (See <ulink url="http://java.sun.com/javase/6/docs/api/java/text/DecimalFormat.html"> java.text.DecimalFormat</ulink>.)
+ </para>
+ </section>
+
+ <section id="excel.formatmasks.dates">
+ <title>Date masks</title>
+ <para>
+ When a format mask is encountered, a check is executed to see if the mask follows an internal form, for example, <literal>format1</literal>, <literal>format2</literal>, etc. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ write/DecimalFormats.html">jxl.write.DecimalFormats</ulink>.)
+ </para>
+ <para>
+ If the mask is not part of the internal list, it is treated as a custom mask (for example, <literal>dd.MM.yyyy</literal>), and automatically converted to the closest match. (See <ulink url="http://java.sun.com/javase/6/docs/api/java/text/DateFormat.html">java. text.DateFormat</ulink>.)
+ </para>
+ </section>
+
+ </section>
+
+ </section>
+
+ <section id="excel.formulas">
+ <title>Formulas</title>
+ <para>
+ Formulas are nested within columns (for iteration) or inside worksheets (for direct placement using the <literal>column</literal> and <literal>row</literal> attributes), and add calculations or functions to ranges of cells. They are essentially cells, see <xref linkend="excel.cells" /> for available attributes. They can apply templates and have their own font definitions, etc., just as normal cells can.
+ </para>
+ <para>
+ The formula of the cell is placed in the <literal>value</literal> attribute as a normal <application>Microsoft Excel</application> notation. When doing cross-sheet formulas, the worksheets must exist before referencing a formula against them. The value is a string.
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet name="fooSheet">
+ <e:cell column="0" row="0" value="1"/>
+ </e:worksheet>
+ <e:worksheet name="barSheet">
+ <e:cell column="0" row="0" value="2"/>
+ <e:formula column="0" row="1" value="fooSheet!A1+barSheet1!A1">
+ <e:font fontSize="12"/>
+ </e:formula>
+ </e:worksheet>
+</e:workbook>]]>
+</programlisting>
+ <para>
+ This defines a formula in B2 summing cells A1 in worksheets FooSheet and BarSheet.
+ </para>
+ </section>
+
+ <section id="excel.images">
+ <title>Images</title>
+ <para>
+ Images are nested within columns (for iteration) or inside worksheets (for direct placement using the <literal>startColumn/startRow</literal> and <literal>rowSpan/columnSpan</literal> attributes). Span tags are optional, and the image will be inserted without resizing if they are omitted.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:image>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>startColumn</literal> — A number value denoting the column in which the image starts. The default is the internal counter. The number value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>startRow</literal> — A number value denoting the row in which the image starts. The default is the internal counter. The number value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>columnSpan</literal> — A float value denoting the column span of the image. The default uses the default width of the image.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rowSpan</literal> — A float value denoting the row span of the image. The default uses the default height of the image.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>URI</literal> — A string value denoting the URI to the image.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:image startRow="0" startColumn="0" rowSpan="4" columnSpan="4"
+ URI="http://foo.org/logo.jpg"/>
+ </e:worksheet>
+</e:workbook>]]>
+</programlisting>
+ <para>
+ This defines an image in A1:E5 based on the given data.
+ </para>
+ </section>
+
+ <section id="excel.hyperlinks">
+ <title>Hyperlinks</title>
+ <para>
+ Hyperlinks are nested within columns (for iteration) or inside worksheets (for direct placement using the <literal>startColumn/startRow</literal> and <literal>endColumn/endRow</literal> attributes). They add link navigation to URIs.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:hyperlink>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>startColumn</literal> — A number value denoting the column in which the hyperlink starts. The default is the internal counter. The number value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>startRow</literal> — A number value denoting the row in which the hyperlink starts. The default is the internal counter. The number value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>endColumn</literal> — A number value denoting the column in which the hyperlink ends. The default is the internal counter. The number value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>endRow</literal> — A number value denoting the row in which the hyperlink ends. The default is the internal counter. The number value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>URL</literal> — A string value denoting the URL to link.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>description</literal> — A string value describing the link. string.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:hyperLink startRow="0" startColumn="0" endRow="4" endColumn="4"
+ URL="http://seamframework.org" description="The Seam Framework"/>
+ </e:worksheet>
+</e:workbook> ]]>
+</programlisting>
+ <para>
+ This defines a described hyperlink pointing to Seam Framework in the area A1:E5.
+ </para>
+ </section>
+
+ <section id="excel.headersfooters">
+ <title>Headers and footers</title>
+ <para>
+ Headers and footers are children of worksheets, and contain facets, which contain strings to be parsed as commands.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:header>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>left</literal> — The contents of the left header part.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>center</literal> — The contents of the central header part.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>right</literal> — The contents of the right header part.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:footer>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>left</literal> — The contents of the left footer part.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>center</literal> — The contents of the central footer part.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>right</literal> — The contents of the right footer part.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <para>
+ Because facets contain string values, they can contain various #-delimited commands, like the following:
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ #date#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Inserts the current date.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #page_number#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Inserts the current page number.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #time#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Inserts the current time.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #total_pages#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Inserts the total page count.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #worksheet_name#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Inserts the worksheet name.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #workbook_name#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Inserts the workbook name.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #bold#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Toggles bold font. One use turns bold text on; a second use turns bold text off.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #italics#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Toggles italic font. One use turns italic text on; a second use turns italic text off.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #underline#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Toggles underlined font. One use turns underlined text on; a second use turns underlined text off.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #double_underline#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Toggles double-underlined font. One use turns double-underlying text on; a second use turns double-underlined text off.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #outline#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Toggles outlined font. One use turns outlined text on; a second use turns outlined text off.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #shadow#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Toggles shadowed font. One use turns shadowed text on; a second use turns shadowed text off.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #strikethrough#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Toggles struck-through font. One use turns struck-through text on; a second use turns struck-through text off.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #subscript#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Toggles subscripted font. One use turns subscripted text on; a second use turns subscripted text off.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #superscript#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Toggles superscripted font. One use turns superscripted text on; a second use turns superscripted text off.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #font_name#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Sets font name. To set Verdana as the font, use <literal>#font_name=Verdana#</literal>. <!-- #modify: Please check this; there was a typo in the original. Does Verdana need ' ' or " " marks? would Times New Roman? -->
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ #font_size#
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Sets font size. To set 12 as the font size, use <literal>#font_size=12#</literal>.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:header>
+ <f:facet name="left">
+ This document was made on #date# and has #total_pages# pages.
+ </f:facet>
+ <f:facet name="right"> #time# </f:facet>
+ </e:header>
+ <e:worksheet>
+</e:workbook> ]]>
+</programlisting>
+ </section>
+
+ <section id="excel.printareatitles">
+ <title>Print areas and titles</title>
+ <para>
+ Print areas and titles are the children of worksheets and worksheet templates, and provide print areas and titles.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:printArea>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>firstColumn</literal> — A number value denoting column that holds the top-left corner of the area. The value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>firstRow</literal> — A number value denoting the row that holds the top left corner of the area.The value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>lastColumn</literal> — A number value denoting the column that holds the bottom-right corner of the area. The value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>lastRow</literal> — A number value denoting the row that holds the bottom-right corner of the area. The value is 0-based.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:printTitles firstRow="0" firstColumn="0" lastRow="0"
+ lastColumn="9"/>
+ <e:printArea firstRow="1" firstColumn="0" lastRow="9" lastColumn="9"/>
+ </e:worksheet>
+</e:workbook> ]]>
+</programlisting>
+ <para>
+ This defines a print title between A1:A10 and a print area between B2:J10.
+ </para>
+ </section>
+
+ <section id="excel.worksheetcommands">
+ <title>Worksheet Commands</title>
+ <para>
+ Worksheet commands are the children of workbooks and are usually executed only once.
+ </para>
+ <section id="excel.worksheetcommands.grouping">
+ <title>Grouping</title>
+ <para>
+ Provides grouping of columns and rows.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:groupRows>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>startRow</literal> — A number value denoting the row at which to begin the grouping. The value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>endRow</literal> — A number value denoting the row at which to end the grouping. The value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>collapse</literal> — A Boolean determining whether the grouping is initially collapsed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:groupColumns>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>startColumn</literal> — A number value denoting the column at which to begin the grouping. The value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>endColumn</literal> — A number value denoting the column at which to end the grouping. The value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>collapse</literal> — A Boolean determining whether the grouping is initially collapsed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:groupRows startRow="4" endRow="9" collapse="true"/>
+ <e:groupColumns startColumn="0" endColumn="9" collapse="false"/>
+ </e:worksheet>
+</e:workbook>]]>
+</programlisting>
+ <para>
+ This groups rows 5 through 10 and columns 5 through 10 so that the rows are initially collapsed (but not the columns).
+ </para>
+ </section>
+
+ <section id="excel.worksheetcommands.pagebreaks">
+ <title>Page breaks</title>
+ <para>
+ Provides page breaks
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:rowPageBreak>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>row</literal> — A number value denoting the row at which a page break should occur. The value is 0-based.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:rowPageBreak row="4"/>
+ </e:worksheet>
+</e:workbook>]]>
+</programlisting>
+ <para>
+ This causes a page break at row 5.
+ </para>
+ </section>
+
+ <section id="excel.worksheetcommands.merging">
+ <title>Merging</title>
+ <para>
+ Provides cell merging
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:mergeCells>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>startRow</literal> — A number value denoting the row at which to begin the merge. The value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>startColumn</literal> — A number value denoting the column at which to begin the merge. The value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>endRow</literal> — A number value denoting the row at which to end the merge. The value is 0-based.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>endColumn</literal> — A number value denoting the column at which to end the merge. The value is 0-based.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:worksheet>
+ <e:mergeCells startRow="0" startColumn="0" endRow="9" endColumn="9"/>
+ </e:worksheet>
+</e:workbook>]]>
+</programlisting>
+ <para>
+ This merges the cells in the range A1:J10.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="excel.datatableexporter">
+ <title>Datatable exporter</title>
+ <para>
+ If you prefer to export an existing JSF datatable instead of writing a dedicated XHTML document, you can execute the <literal>org.jboss.seam.excel.excelExporter.export</literal> component, passing in the ID of the datatable as an Seam EL parameter. For example, say you have the following datatable:
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<h:form id="theForm">
+ <h:dataTable id="theDataTable" value="#{personList.personList}"
+ var="person">
+ ...
+ </h:dataTable>
+</h:form> ]]>
+</programlisting>
+ <para>
+ If you want to view this as a <application>Microsoft Excel</application> spreadsheet, place the following in the form:
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<h:commandLink value="Export"
+ action="#{excelExporter.export('theForm:theDataTable')}" />]]>
+</programlisting>
+ <para>
+ You can also execute the exporter with a button, s:link, or other preferred method.
+ </para>
+ <para>
+ See <xref linkend="excel.fontsandlayout" /> for formatting.
+ </para>
+ </section>
+
+ <section id="excel.fontsandlayout">
+ <title>Fonts and layout</title>
+ <para>
+ Output appearance is controlled with a combination of CSS style and tag attributes. CSS style attributes flow from parent to child, and let you use one tag to apply all attributes defined for that tag in the <literal>styleClass</literal> and <literal>style</literal> sheets. <!-- #modify: These paragraphs made very little sense to me. Please review rewritten paragraphs for technical accuracy. "Controlling how the output look is done with a combination of CSSish style attributes and tag attributes. The most common ones (fonts, borders, backgrounds etc) are CSS and some more general settings are in tag attributes. The CSS attributes cascade down from parent to children and within one tag cascades over the CSS classes referenced in the <literal>styleClass</literal> attributes and finally over the CSS attributes defined in the <literal>style</literal> attribute. You can place them pretty much anywhere but e.g. placing a column width setting in a cell nested within that column!
makes little sense." -->
+ </para>
+ <para>
+ If you have format masks or fonts that use special characters, such as spaces and semicolons, you can escape the CSS string with <literal>''</literal> characters such as <literal>xls-format-mask:'$;$'</literal>.
+ </para>
+ <section id="excel.fontsandlayout.link">
+ <title>Stylesheet links</title>
+ <para>
+ External stylesheets are referenced with the <literal>e:link</literal> tag. They are placed within the document as if they are children of the <literal>workbook</literal> tag.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<e:link>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>URL</literal> — The URL of the stylesheet.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Child elements</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Facets</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>none</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"><![CDATA[
+<e:workbook>
+ <e:link URL="/css/excel.css"/>
+</e:workbook> ]]>
+</programlisting>
+ <para>
+ This references a stylesheet located at <filename>/css/excel.css</filename>.
+ </para>
+ </section>
+
+ <section id="excel.fontsandlayout.fonts">
+ <title>Fonts</title>
+ <para>
+ This group of XLS-CSS attributes define a font and its attributes.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-font-family
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The name of the font. Make sure the font you enter here is supported by your system.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-font-size
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A plain number value denoting the font size.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-font-color
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The colour of the font. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/Colour.html">jxl.format.Colour</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-font-bold
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A Boolean determining whether the font is bolded. Valid values are <literal>true</literal> and <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-font-italic
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A Boolean determining whether the font is italicized. Valid values are <literal>true</literal> and <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-font-script-style
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The script style of the font. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/ScriptStyle.html">jxl.format.ScriptStyle</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-font-underline-style
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The underline style of the font. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/UnderlineStyle.html">jxl.format.UnderlineStyle</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-font-struck-out
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A Boolean determining whether the font is struck-through. Valid values are <literal>true</literal> and <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-font
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A shorthand notation for setting all values associated with font. Place the font name last. (If you wish to use a font with spaces in its name, use tick marks to surround the font. For example, <literal>'Times New Roman'</literal>.) Here, defined italicized, bolded, or struck-through text with <literal>italic</literal>, <literal>bold</literal>, or <literal>struckout</literal>.
+ </para>
+ <para>
+ For example: <literal>style="xls-font: red bold italic 22 Verdana"</literal>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="excel.fontsandlayout.borders">
+ <title>Borders</title>
+ <para>
+ This group of XLS-CSS attributes defines the borders of the cell.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-left-color
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The border color of the left edge of the cell. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/Colour.html">jxl.format.Colour</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-left-line-style
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The border line style of the left edge of the cell. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/LineStyle.html">jxl.format.LineStyle</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-left
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A shorthand notation for setting the line style and color of the left edge of the cell. Use like so: <literal>style="xls-border-left: thick red"</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-top-color
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The border color of the top edge of the cell. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/Colour.html">jxl.format.Colour</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-top-line-style
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The border line style of the top edge of the cell. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/LineStyle.html">jxl.format.LineStyle</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-top
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A shorthand notation for setting the line style and color of the top edge of the cell. Use like so: <literal>style="xls-border-top: red thick"</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-right-color
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The border color of the right edge of the cell. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/Colour.html">jxl.format.Colour</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-right-line-style
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The border line style of the right edge of the cell. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/LineStyle.html">jxl.format.LineStyle</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-right
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A shorthand notation for setting the line style and color of the right edge of the cell. Use like so: <literal>style="xls-border-right: thick red"</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-bottom-color
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The border color of the bottom edge of the cell. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/Colour.html">jxl.format.Colour</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-bottom-line-style
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The border line style of the bottom edge of the cell. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/LineStyle.html">jxl.format.LineStyle</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border-bottom
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A shorthand notation for setting the line style and color of the bottom edge of the cell. Use like so: <literal>style="xls-border-bottom: thick red"</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-border
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A shorthand notation for setting the line style and color for all edges of the cell. Use like so: <literal>style="xls-border: thick red"</literal>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="excel.fontsandlayout.background">
+ <title>Background</title>
+ <para>
+ This group of XLS-CSS attributes defines the background of the cell.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-background-color
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The color of the background. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/LineStyle.html">jxl.format.LineStyle</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-background-pattern
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The pattern of the background. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/Pattern.html">jxl.format.Pattern</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-background
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A shorthand for setting the background color and pattern.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="excel.fontsandlayout.columnsettings">
+ <title>Column settings</title>
+ <para>
+ This group of XLS-CSS attributes defines column properties.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-column-width
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The width of a column. We recommend beginning with values of approximately 5000, and adjusting as required. Used by the <literal>e:column</literal> in XHTML mode.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-column-widths
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The width of each column, respectively. We recommend beginning with values of approximately 5000, and adjusting as required. Used by the excel exporter, and placed in the datatable <literal>style</literal> attribute. Use numerical values, or * to bypass a column.
+ </para>
+ <para>
+ For example: <literal>style="xls-column-widths: 5000, 5000, *, 10000"</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-column-autosize
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Determines whether the column should be autosized. Valid values are <literal>true</literal> and <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-column-hidden
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Determines whether the column is hidden. Valid values are <literal>true</literal> and <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-column-export
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Determines whether the column is shown in export. Valid values are <literal>true</literal> and <literal>false</literal>. Defaults to <literal>true</literal>.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="excel.fontsandlayout.cellsettings">
+ <title>Cell settings</title>
+ <para>
+ This group of XLS-CSS attributes defines the cell properties.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-alignment
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The alignment of the cell value. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/Alignment.html">jxl.format.Alignment</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-force-type
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A string value determining the forced type of data in the cell. Valid values are <literal>general</literal>, <literal>number</literal>, <literal>text</literal>, <literal>date</literal>, <literal>formula</literal>, and <literal>bool</literal>. The type is automatically detected so there is rarely any use for this attribute.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-format-mask
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The format mask of the cell. (See <xref linkend="excel.cells.formatmasks" />.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-indentation
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ A number value determining the indentation of the cell's contents.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-locked
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Determines whether a cell is locked. Used with workbook level <literal>locked</literal>. Valid values are <literal>true</literal> or <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-orientation
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The orientation of the cell value. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/Orientation.html">jxl.format.Orientation</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-vertical-alignment
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ The vertical alignment of the cell value. (See <ulink url="http://jexcelapi.sourceforge.net/resources/javadocs/current/docs/jxl/ format/VerticalAlignment.html">jxl.format.VerticalAlignment</ulink>.)
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-shrink-to-fit
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Determines whether cell values shrink to fit. Valid values are <literal>true</literal> and <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ xls-wrap
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ Determines whether the cell wraps new lines. Valid values are <literal>true</literal> and <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="excel.fontsandlayout.datatableexporter">
+ <title>The datatable exporter</title>
+ <para>
+ The datatable exporter uses the same XLS-CSS attributes as the XHTML document, with the exception that column widths are defined with the <literal>xls-column-widths</literal> attribute on the datatable (since the UIColumn doesn't support the <literal>style</literal> or <literal>styleClass</literal> attributes).
+ </para>
+ </section>
+
+ <!-- #modify: CONTENT REQUIRED. <section id="excel.fontsandlayout.examples"> <title>Layout examples</title> <para> TODO </para> </section> --> <section id="excel.fontsandlayout.limitations">
+ <title>Limitations</title>
+ <para>
+ There are some known limitations to CSS support in the current version of Seam.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ When using <filename>.xhtml</filename> documents, stylesheets must be referenced through the <literal><![CDATA[<e:link>]]></literal> tag.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When using the datatable exporter, CSS must be entered through style-attributes — external stylesheets are not supported.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ </section>
+
+ <section id="excel.i18n">
+ <title>Internationalization</title>
+ <para>
+ Only two resource bundle keys are used. Both are for invalid data formats, and both take a parameter that defines the invalid value.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.excel.not_a_number</literal> — When a value thought to be a number could not be treated as such.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>org.jboss.seam.excel.not_a_date</literal> — When a value thought to be a date could not be treated as such.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section id="excel.links">
+ <title>Links and further documentation</title>
+ <para>
+ The core of <application>Microsoft Excel</application> functionality in Seam is based on the JExcelAPI library, which can be found on <ulink url="http://jexcelapi.sourceforge.net">http://jexcelapi.sourceforge.net/</ulink>. Most features and limitations are inherited from the JExcelAPI.
+ </para>
+ <note>
+ <para>
+ JExcelAPI is not Seam. Any Seam-based issues are best reported in the JBoss Seam JIRA under the <emphasis>Excel</emphasis> module. <!-- #modify: linkme? -->
+ </para>
+ </note>
+ </section>
+
</chapter>
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Feedback.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Feedback.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Feedback.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,17 +1,12 @@
-<?xml version='1.0'?>
+<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE section PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
-<section id="Book-We_Need_Feedback">
- <title>Contribute to Seam</title>
- <para>
- Visit
- <ulink url="http://www.seamframework.org/Community/Contribute">
- SeamFramework.org
- </ulink>
- to find out how to contribute to Seam!
- </para>
-
+<section id="Book-We_Need_Feedback" >
+ <title>Contribute to Seam</title>
+ <para>
+ Visit <ulink url="http://www.seamframework.org/Community/Contribute"> SeamFramework.org </ulink> to find out how to contribute to Seam!
+ </para>
</section>
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Framework.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Framework.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Framework.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,600 +1,495 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-
-<chapter id="framework">
- <title>The Seam Application Framework</title>
-
- <para>
- Seam makes it really easy to create applications by writing
- plain Java classes with annotations, which don't need to extend
- any special interfaces or superclasses. But we can simplify
- some common programming tasks even further, by providing a set
- of pre-built components which can be re-used either by
- configuration in <literal>components.xml</literal> (for very
- simple cases) or extension.
- </para>
-
- <para>
- The <emphasis>Seam Application Framework</emphasis> can reduce
- the amount of code you need to write when doing basic database
- access in a web application, using either Hibernate or JPA.
- </para>
-
- <para>
- We should emphasize that the framework is extremely simple,
- just a handful of simple classes that are easy to understand
- and extend. The "magic" is in Seam itself — the same magic
- you use when creating any Seam application even without using
- this framework.
- </para>
-
- <section>
- <title>Introduction</title>
-
- <para>
- The components provided by the Seam application framework
- may be used in one of two different approaches. The first
- way is to install and configure an instance of the component
- in <literal>components.xml</literal>, just like we have
- done with other kinds of built-in Seam components. For
- example, the following fragment from
- <literal>components.xml</literal> installs a component
- which can perform basic CRUD operations for a
- <literal>Person</literal> entity:
- </para>
-
- <programlisting role="XML"><![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
- your taste, you can use extension instead:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {
-
- @In EntityManager personDatabase;
-
- public EntityManager getEntityManager() {
- return personDatabase;
- }
-
-}]]></programlisting>
-
- <para>
- The second approach has one huge advantage: you can easily add
- extra functionality, and override the built-in functionality
- (the framework classes were carefully designed for extension
- and customization).
- </para>
-
- <para>
- A second advantage is that your classes may be EJB stateful
- session beans, if you like. (They do not have to be, they
- can be plain JavaBean components if you prefer.)
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Stateful
- at Name("personHome")
-public class PersonHome extends EntityHome<Person> implements LocalPersonHome {
-
-}]]></programlisting>
-
- <para>
- You can also make your classes stateless session beans. In this case
- you <emphasis>must</emphasis> use injection to provide the
- persistence context, even if it is called
- <literal>entityManager</literal>:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Stateless
- at Name("personHome")
-public class PersonHome extends EntityHome<Person> implements LocalPersonHome {
-
- @In EntityManager entityManager;
-
- public EntityManager getPersistenceContext() {
- entityManager;
- }
-
-}]]></programlisting>
-
- <para>
- At this time, the Seam Application Framework provides four main
- built-in components: <literal>EntityHome</literal> and
- <literal>HibernateEntityHome</literal> for CRUD, along with
- <literal>EntityQuery</literal> and <literal>HibernateEntityQuery</literal>
- for queries.
- </para>
-
- <para>
- The Home and Query components are written so that they can function
- with a scope of session, event or conversation. Which scope you
- use depends upon the state model you wish to use in your application.
- </para>
-
- <para>
- The Seam Application Framework only works with Seam-managed
- persistence contexts. By default, the components will look
- for a persistence context named <literal>entityManager</literal>.
- </para>
-
- </section>
-
- <section>
- <title>Home objects</title>
-
- <para>
- A Home object provides persistence operations for a particular entity
- class. Suppose we have our trusty <literal>Person</literal> class:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Entity
-public class Person {
- @Id private Long id;
- private String firstName;
- private String lastName;
- private Country nationality;
-
- //getters and setters...
-}]]></programlisting>
-
- <para>
- We can define a <literal>personHome</literal> component either via
- configuration:
- </para>
-
- <programlisting role="XML"><![CDATA[<framework:entity-home name="personHome" entity-class="eg.Person" />]]></programlisting>
-
- <para>
- Or via extension:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {}]]></programlisting>
-
- <para>
- A Home object provides the following operations: <literal>persist()</literal>,
- <literal>remove()</literal>, <literal>update()</literal> and
- <literal>getInstance()</literal>. Before you can call the
- <literal>remove()</literal>, or <literal>update()</literal> operations, you
- must first set the identifier of the object you are interested in, using the
- <literal>setId()</literal> method.
- </para>
-
- <para>
- We can use a Home directly from a JSF page, for example:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h1>Create Person</h1>
-<h:form>
- <div>First name: <h:inputText value="#{personHome.instance.firstName}"/></div>
- <div>Last name: <h:inputText value="#{personHome.instance.lastName}"/></div>
- <div>
- <h:commandButton value="Create Person" action="#{personHome.persist}"/>
- </div>
-</h:form>]]></programlisting>
-
- <para>
- Usually, it is much nicer to be able to refer to the <literal>Person</literal>
- merely as <literal>person</literal>, so let's make that possible by adding a
- line to <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<factory name="person"
- value="#{personHome.instance}"/>
-
-<framework:entity-home name="personHome"
- entity-class="eg.Person" />]]></programlisting>
-
- <para>
- (If we are using configuration.)
- Or by adding a <literal>@Factory</literal> method to <literal>PersonHome</literal>:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {
-
- @Factory("person")
- public Person initPerson() { return getInstance(); }
-
-}]]></programlisting>
-
- <para>
- (If we are using extension.)
- This change simplifies our JSF page to the following:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h1>Create Person</h1>
-<h:form>
- <div>First name: <h:inputText value="#{person.firstName}"/></div>
- <div>Last name: <h:inputText value="#{person.lastName}"/></div>
- <div>
- <h:commandButton value="Create Person" action="#{personHome.persist}"/>
- </div>
-</h:form>]]></programlisting>
-
- <para>
- Well, that lets us create new <literal>Person</literal> entries. Yes,
- that is all the code that is required! Now, if we want to be able to
- display, update and delete pre-existing <literal>Person</literal>
- entries in the database, we need to be able to pass the entry
- identifier to the <literal>PersonHome</literal>. Page parameters
- are a great way to do that:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/editPerson.jsp">
- <param name="personId" value="#{personHome.id}"/>
- </page>
-</pages>]]></programlisting>
-
- <para>
- Now we can add the extra operations to our JSF page:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h1>
- <h:outputText rendered="#{!personHome.managed}" value="Create Person"/>
- <h:outputText rendered="#{personHome.managed}" value="Edit Person"/>
-</h1>
-<h:form>
- <div>First name: <h:inputText value="#{person.firstName}"/></div>
- <div>Last name: <h:inputText value="#{person.lastName}"/></div>
- <div>
- <h:commandButton value="Create Person" action="#{personHome.persist}" rendered="#{!personHome.managed}"/>
- <h:commandButton value="Update Person" action="#{personHome.update}" rendered="#{personHome.managed}"/>
- <h:commandButton value="Delete Person" action="#{personHome.remove}" rendered="#{personHome.managed}"/>
- </div>
-</h:form>]]></programlisting>
-
- <para>
- When we link to the page with no request parameters, the page will
- be displayed as a "Create Person" page. When we provide a value for
- the <literal>personId</literal> request parameter, it will be an
- "Edit Person" page.
- </para>
-
- <para>
- Suppose we need to create <literal>Person</literal> entries with their
- nationality initialized. We can do that easily, via configuration:
- </para>
-
- <programlisting role="XML"><![CDATA[<factory name="person"
- value="#{personHome.instance}"/>
-
-<framework:entity-home name="personHome"
- entity-class="eg.Person"
- new-instance="#{newPerson}"/>
-
-<component name="newPerson"
- class="eg.Person">
- <property name="nationality">#{country}</property>
-</component>]]></programlisting>
-
- <para>
- Or by extension:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {
-
- @In Country country;
-
- @Factory("person")
- public Person initPerson() { return getInstance(); }
-
- protected Person createInstance() {
- return new Person(country);
- }
-
-}]]></programlisting>
-
- <para>
- Of course, the <literal>Country</literal> could be an object managed by
- another Home object, for example, <literal>CountryHome</literal>.
- </para>
-
- <para>
- To add more sophisticated operations (association management, etc), we can
- just add methods to <literal>PersonHome</literal>.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {
-
- @In Country country;
-
- @Factory("person")
- public Person initPerson() { return getInstance(); }
-
- protected Person createInstance() {
- return new Person(country);
- }
-
- public void migrate()
- {
- getInstance().setCountry(country);
- update();
- }
-
-}]]></programlisting>
-
- <para>
- The Home object raises an <literal>org.jboss.seam.afterTransactionSuccess</literal>
- event when a transaction succeeds (a call to <literal>persist()</literal>,
- <literal>update()</literal> or <literal>remove()</literal> succeeds). By observing
- this event we can refresh our queries when the underlying entities are changed. If
- we only want to refresh certain queries when a particular entity is persisted,
- updated or removed we can observe the
- <literal>org.jboss.seam.afterTransactionSuccess.<name></literal>
- event (where <literal><name></literal> is the simple name of the entity, e.g. an entity called "org.foo.myEntity" has "myEntity" as simple name).
+<chapter id="framework" >
+ <title>The Seam Application Framework</title>
+ <para>
+ Seam makes it easy to create applications with annotated plain Java classes. We can make common programming tasks even easier by providing a set of pre-built components that are reusable with configuration or extension.
+ </para>
+ <para>
+ The Seam Application Framework can reduce the amount of code you need to write in a web application for basic database access with either Hibernate or JPA. The framework contains a handful of simple classes that are easy to understand and to extend where required.
+ </para>
+ <section>
+ <title>Introduction</title>
+ <para>
+ The components provided by the Seam Application Framework can be used in two separate approaches. The first approach is to install and configure an instance of the component in <filename>components.xml</filename>, as with other built-in Seam components. For example, the following fragment (from <filename>components.xml</filename>) installs a component that performs basic CRUD operations for a <literal>Person</literal> entity:
</para>
-
- <para>
- The Home object automatically displays faces messages when an operation is
- successful. To customize these messages we can, again, use configuration:
- </para>
-
- <programlisting role="XML"><![CDATA[<factory name="person"
- value="#{personHome.instance}"/>
-
-<framework:entity-home name="personHome"
- entity-class="eg.Person"
- new-instance="#{newPerson}">
- <framework:created-message>New person #{person.firstName} #{person.lastName} created</framework:created-message>
- <framework:deleted-message>Person #{person.firstName} #{person.lastName} deleted</framework:deleted-message>
- <framework:updated-message>Person #{person.firstName} #{person.lastName} updated</framework:updated-message>
-</framework:entity-home>
-
-<component name="newPerson"
- class="eg.Person">
- <property name="nationality">#{country}</property>
-</component>]]></programlisting>
-
- <para>
- Or extension:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("personHome")
-public class PersonHome extends EntityHome<Person> {
-
- @In Country country;
-
- @Factory("person")
- public Person initPerson() { return getInstance(); }
-
- protected Person createInstance() {
- return new Person(country);
- }
-
- protected String getCreatedMessage() { return createValueExpression("New person #{person.firstName} #{person.lastName} created"); }
- protected String getUpdatedMessage() { return createValueExpression("Person #{person.firstName} #{person.lastName} updated"); }
- protected String getDeletedMessage() { return createValueExpression("Person #{person.firstName} #{person.lastName} deleted"); }
-
-}]]></programlisting>
-
- <para>
- But the best way to specify the messages is to put them in a resource
- bundle known to Seam (the bundle named <literal>messages</literal>,
- by default).
- </para>
-
- <programlisting><![CDATA[Person_created=New person #{person.firstName} #{person.lastName} created
-Person_deleted=Person #{person.firstName} #{person.lastName} deleted
-Person_updated=Person #{person.firstName} #{person.lastName} updated]]></programlisting>
-
- <para>
- This enables internationalization, and keeps your code and configuration clean of
- presentation concerns.
- </para>
-
- <para>
- The final step is to add validation functionality to the page, using
- <literal><s:validateAll></literal> and <literal><s:decorate></literal>,
- but I'll leave that for you to figure out.
- </para>
-
- </section>
-
- <section>
- <title>Query objects</title>
-
- <para>
- If we need a list of all <literal>Person</literal> instance in the database, we
- can use a Query object. For example:
- </para>
-
- <programlisting role="XML"><![CDATA[<framework:entity-query name="people"
- ejbql="select p from Person p"/>]]></programlisting>
-
- <para>
- We can use it from a JSF page:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h1>List of people</h1>
-<h:dataTable value="#{people.resultList}" var="person">
- <h:column>
- <s:link view="/editPerson.jsp" value="#{person.firstName} #{person.lastName}">
- <f:param name="personId" value="#{person.id}"/>
- </s:link>
- </h:column>
-</h:dataTable>]]></programlisting>
-
- <para>
- We probably need to support pagination:
- </para>
-
- <programlisting role="XML"><![CDATA[<framework:entity-query name="people"
- ejbql="select p from Person p"
- order="lastName"
- max-results="20"/>]]></programlisting>
-
- <para>
- We'll use a page parameter to determine the page to display:
- </para>
-
-
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/searchPerson.jsp">
- <param name="firstResult" value="#{people.firstResult}"/>
- </page>
-</pages>]]></programlisting>
-
- <para>
- The JSF code for a pagination control is a bit verbose, but manageable:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h1>Search for people</h1>
-<h:dataTable value="#{people.resultList}" var="person">
- <h:column>
- <s:link view="/editPerson.jsp" value="#{person.firstName} #{person.lastName}">
- <f:param name="personId" value="#{person.id}"/>
- </s:link>
- </h:column>
+
+<programlisting role="XML"><![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 this approach seems too XML-heavy, you can approach this through extension:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("personHome")
+public class PersonHome extends EntityHome<Person> {
+ at In EntityManager personDatabase;
+ public EntityManager getEntityManager() {
+ return personDatabase;
+ }
+}]]>
+</programlisting>
+ <para>
+ The major advantage to the second approach is that the framework classes were designed for extension and customization, so it is easy to add extra functionality or override the built-in functionality.
+ </para>
+ <para>
+ Another advantage is that you have the option of using EJB stateful session beans (or plain JavaBean components) as your classes:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateful
+ at Name("personHome")
+public class PersonHome extends EntityHome<Person>
+ implements LocalPersonHome { }]]>
+</programlisting>
+ <para>
+ You can also make your classes stateless session beans. In this case you <emphasis>must</emphasis> use injection to provide the persistence context, even if it is called <literal>entityManager</literal>:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateless
+ at Name("personHome")
+public class PersonHome extends EntityHome<Person>
+ implements LocalPersonHome {
+ @In EntityManager entityManager;
+ public EntityManager getPersistenceContext() {
+ entityManager;
+ }
+}]]>
+</programlisting>
+ <para>
+ At present, the Seam Application Framework provides four main built-in components: <literal>EntityHome</literal> and <literal>HibernateEntityHome</literal> for CRUD, and <literal>EntityQuery</literal> and <literal>HibernateEntityQuery</literal> for queries.
+ </para>
+ <para>
+ The Home and Query components are written so that they can be session-, event- or conversation-scoped. The scope depends upon the state model you wish to use in your application.
+ </para>
+ <para>
+ The Seam Application Framework works only with Seam-managed persistence contexts. By default, components will expect a persistence context named <literal>entityManager</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Home objects</title>
+ <para>
+ A Home object provides persistence operations for a particular entity class. Suppose we have our <literal>Person</literal> class:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Entity
+public class Person {
+ @Id private Long id;
+ private String firstName;
+ private String lastName;
+ private Country nationality;
+ //getters and setters...
+}]]>
+</programlisting>
+ <para>
+ We can define a <literal>personHome</literal> component either through configuration:
+ </para>
+
+<programlisting role="XML"><![CDATA[<framework:entity-home name="personHome" entity-class="eg.Person" />]]>
+</programlisting>
+ <para>
+ Or through extension:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("personHome")
+public class PersonHome extends EntityHome<Person> {}]]>
+</programlisting>
+ <para>
+ A Home object provides operations like <literal>persist()</literal>, <literal>remove()</literal>, <literal>update()</literal> and <literal>getInstance()</literal>. Before you can call <literal>remove()</literal> or <literal>update()</literal>, you must set the identifier of the object you are interested in, using the <literal>setId()</literal> method.
+ </para>
+ <para>
+ For example, we can use a Home directly from a JSF page:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h1>Create Person</h1>
+<h:form>
+ <div>
+ First name: <h:inputText value="#{personHome.instance.firstName}"/>
+ </div>
+ <div>
+ Last name: <h:inputText value="#{personHome.instance.lastName}"/>
+ </div>
+ <div>
+ <h:commandButton value="Create Person"
+ action="#{personHome.persist}"/>
+ </div>
+</h:form>]]>
+</programlisting>
+ <para>
+ It is useful to be able to refer to <literal>Person</literal> as <literal>person</literal>, so we will add that line to <filename>components.xml</filename> (if we are using configuration):
+ </para>
+
+<programlisting role="XML"><![CDATA[<factory name="person" value="#{personHome.instance}"/>
+<framework:entity-home name="personHome" entity-class="eg.Person" />]]>
+</programlisting>
+ <para>
+ Or, if we are using extension, we can add a <literal>@Factory</literal> method to <literal>PersonHome</literal>:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("personHome")
+public class PersonHome extends EntityHome<Person> {
+ @Factory("person")
+ public Person initPerson() {
+ return getInstance();
+ }
+}]]>
+</programlisting>
+ <para>
+ This change simplifies our JSF page to the following:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h1>Create Person</h1>
+<h:form>
+ <div>
+ First name: <h:inputText value="#{person.firstName}"/>
+ </div>
+ <div>
+ Last name: <h:inputText value="#{person.lastName}"/>
+ </div>
+ <div>
+ <h:commandButton value="Create Person"
+ action="#{personHome.persist}"/>
+ </div>
+</h:form>]]>
+</programlisting>
+ <para>
+ This is all the code required to create new <literal>Person</literal> entries. If we want to be able to display, update, and delete pre-existing <literal>Person</literal> entries in the database, we need to be able to pass the entry identifier to the <literal>PersonHome</literal>. An excellent method is through page parameters:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/editPerson.jsp">
+ <param name="personId" value="#{personHome.id}"/>
+ </page>
+</pages>]]>
+</programlisting>
+ <para>
+ Now we can add the extra operations to our JSF page:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h1>
+ <h:outputText rendered="#{!personHome.managed}" value="Create Person"/>
+ <h:outputText rendered="#{personHome.managed}" value="Edit Person"/>
+</h1>
+<h:form>
+ <div>
+ First name: <h:inputText value="#{person.firstName}"/>
+ </div>
+ <div>
+ Last name: <h:inputText value="#{person.lastName}"/>
+ </div>
+ <div>
+ <h:commandButton value="Create Person" action="#{personHome.persist}"
+ rendered="#{!personHome.managed}"/>
+ <h:commandButton value="Update Person" action="#{personHome.update}"
+ rendered="#{personHome.managed}"/>
+ <h:commandButton value="Delete Person" action="#{personHome.remove}"
+ rendered="#{personHome.managed}"/>
+ </div>
+</h:form>]]>
+</programlisting>
+ <para>
+ When we link to the page with no request parameters, the page will be displayed as a <emphasis>Create Person</emphasis> page. When we provide a value for the <literal>personId</literal> request parameter, it will be an <emphasis>Edit Person</emphasis> page.
+ </para>
+ <para>
+ If we need to create <literal>Person</literal> entries with their nationality initialized, we can do so easily. Via configuration:
+ </para>
+
+<programlisting role="XML"><![CDATA[<factory name="person" value="#{personHome.instance}"/>
+<framework:entity-home name="personHome" entity-class="eg.Person"
+ new-instance="#{newPerson}"/>
+<component name="newPerson" class="eg.Person">
+ <property name="nationality">#{country}</property>
+</component>]]>
+</programlisting>
+ <para>
+ Or via extension:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("personHome")
+public class PersonHome extends EntityHome<Person> {
+ @In Country country;
+ @Factory("person")
+ public Person initPerson() {
+ return getInstance();
+ }
+ protected Person createInstance() {
+ return new Person(country);
+ }
+}]]>
+</programlisting>
+ <para>
+ The <literal>Country</literal> could be an object managed by another Home object, for example, <literal>CountryHome</literal>.
+ </para>
+ <para>
+ To add more sophisticated operations (association management, etc.), we simply add methods to <literal>PersonHome</literal>.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("personHome")
+public class PersonHome extends EntityHome<Person> {
+ @In Country country;
+ @Factory("person")
+ public Person initPerson() {
+ return getInstance();
+ }
+ protected Person createInstance() {
+ return new Person(country);
+ }
+ public void migrate() {
+ getInstance().setCountry(country);
+ update();
+ }
+}]]>
+</programlisting>
+ <para>
+ The Home object raises an <literal>org.jboss.seam.afterTransactionSuccess</literal> event when a transaction (a call to <literal>persist()</literal>, <literal>update()</literal> or <literal>remove()</literal>) succeeds. By observing this event, we can refresh our querues when the underlying entities change. If we only want to refresh certain queries when a particular entry is persisted, updated, or removed, we can observe the <literal>org.jboss.seam.afterTransactionSuccess.<![CDATA[<name>]]></literal> (where <literal><![CDATA[<name>]]></literal> is the name of the entity).
+ </para>
+ <para>
+ The Home object automatically displays Faces messages when an operation succeeds. To customize these messages we can, again, use configuration:
+ </para>
+
+<programlisting role="XML"><![CDATA[<factory name="person" value="#{personHome.instance}"/>
+<framework:entity-home name="personHome" entity-class="eg.Person"
+ new-instance="#{newPerson}">
+ <framework:created-message>
+ New person #{person.firstName} #{person.lastName} created
+ </framework:created-message>
+ <framework:deleted-message>
+ Person #{person.firstName} #{person.lastName} deleted
+ </framework:deleted-message>
+ <framework:updated-message>
+ Person #{person.firstName} #{person.lastName} updated
+ </framework:updated-message>
+</framework:entity-home>
+<component name="newPerson" class="eg.Person">
+ <property name="nationality">#{country}</property>
+</component>]]>
+</programlisting>
+ <para>
+ Or extension:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("personHome")
+public class PersonHome extends EntityHome<Person> {
+ @In Country country;
+ @Factory("person")
+ public Person initPerson() {
+ return getInstance();
+ }
+ protected Person createInstance() {
+ return new Person(country);
+ }
+ protected String getCreatedMessage() {
+ return createValueExpression("New person #{person.firstName}
+ #{person.lastName} created");
+ }
+ protected String getUpdatedMessage() {
+ return createValueExpression("Person #{person.firstName}
+ #{person.lastName} updated");
+ }
+ protected String getDeletedMessage() {
+ return createValueExpression("Person #{person.firstName}
+ #{person.lastName} deleted");
+ }
+}]]>
+</programlisting>
+ <para>
+ The best way to specify messages is to put them in a resource bundle known to Seam — by default, the bundle named <literal>messages</literal>.
+ </para>
+
+<programlisting><![CDATA[Person_created=New person #{person.firstName} #{person.lastName} created
+Person_deleted=Person #{person.firstName} #{person.lastName} deleted
+Person_updated=Person #{person.firstName} #{person.lastName} updated]]>
+</programlisting>
+ <para>
+ This enables internationalization, and keeps your code and configuration clean of presentation concerns.
+ </para>
+ <!-- #modify: DO NOT WANT: <para> The final step is to add validation functionality to the page with <literal><s:validateAll></literal> and <literal><s:decorate></literal>, but I'll leave that for you to figure out. </para> -->
+ </section>
+
+ <section>
+ <title>Query objects</title>
+ <para>
+ If we need a list of all <literal>Person</literal> instances in the database, we can use a Query object, like the following.
+ </para>
+
+<programlisting role="XML"><![CDATA[<framework:entity-query name="people" ejbql="select p from Person p"/>]]>
+</programlisting>
+ <para>
+ We can use it from a JSF page:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h1>List of people</h1>
+<h:dataTable value="#{people.resultList}" var="person">
+ <h:column>
+ <s:link view="/editPerson.jsp"
+ value="#{person.firstName} #{person.lastName}">
+ <f:param name="personId" value="#{person.id}"/>
+ </s:link>
+ </h:column>
+</h:dataTable>]]>
+</programlisting>
+ <para>
+ If you require pagination support:
+ </para>
+
+<programlisting role="XML"><![CDATA[<framework:entity-query name="people" ejbql="select p from Person p"
+ order="lastName" max-results="20"/>]]>
+</programlisting>
+ <para>
+ Use a page parameter to determine which page to display:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/searchPerson.jsp">
+ <param name="firstResult" value="#{people.firstResult}"/>
+ </page>
+</pages>]]>
+</programlisting>
+ <para>
+ The JSF code for pagination control is slightly verbose, but manageable:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h1>Search for people</h1>
+<h:dataTable value="#{people.resultList}" var="person">
+ <h:column>
+
+ <s:link view="/editPerson.jsp"
+ value="#{person.firstName} #{person.lastName}">
+ <f:param name="personId" value="#{person.id}"/>
+ </s:link>
+
+ </h:column>
+
</h:dataTable>
-
-<s:link view="/search.xhtml" rendered="#{people.previousExists}" value="First Page">
- <f:param name="firstResult" value="0"/>
+
+<s:link view="/search.xhtml" rendered="#{people.previousExists}"
+ value="First Page">
+ <f:param name="firstResult" value="0"/>
</s:link>
-
-<s:link view="/search.xhtml" rendered="#{people.previousExists}" value="Previous Page">
- <f:param name="firstResult" value="#{people.previousFirstResult}"/>
+
+<s:link view="/search.xhtml" rendered="#{people.previousExists}"
+ value="Previous Page">
+ <f:param name="firstResult" value="#{people.previousFirstResult}"/>
</s:link>
-
-<s:link view="/search.xhtml" rendered="#{people.nextExists}" value="Next Page">
- <f:param name="firstResult" value="#{people.nextFirstResult}"/>
+
+<s:link view="/search.xhtml" rendered="#{people.nextExists}"
+ value="Next Page">
+ <f:param name="firstResult" value="#{people.nextFirstResult}"/>
</s:link>
-
-<s:link view="/search.xhtml" rendered="#{people.nextExists}" value="Last Page">
- <f:param name="firstResult" value="#{people.lastFirstResult}"/>
-</s:link>]]></programlisting>
-
- <para>
- Real search screens let the user enter a bunch of optional search criteria
- to narrow the list of results returned. The Query object lets you specify
- optional "restrictions" to support this important usecase:
- </para>
-
- <programlisting role="XML"><![CDATA[<component name="examplePerson" class="Person"/>
-
-<framework:entity-query name="people"
- ejbql="select p from Person p"
- order="lastName"
- max-results="20">
- <framework:restrictions>
- <value>lower(firstName) like lower( concat(#{examplePerson.firstName},'%') )</value>
- <value>lower(lastName) like lower( concat(#{examplePerson.lastName},'%') )</value>
- </framework:restrictions>
-</framework:entity-query>]]></programlisting>
-
- <para>
- Notice the use of an "example" object.
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h1>Search for people</h1>
+
+<s:link view="/search.xhtml" rendered="#{people.nextExists}"
+ value="Last Page">
+ <f:param name="firstResult" value="#{people.lastFirstResult}"/>
+</s:link>]]>
+</programlisting>
+ <para>
+ Real search screens let the user enter optional search criteria to narrow the list of returned results. The Query object lets you specify optional restrictions to support this usecase:
+ </para>
+
+<programlisting role="XML"><![CDATA[<component name="examplePerson" class="Person"/>
+<framework:entity-query name="people" ejbql="select p from Person p"
+ order="lastName" max-results="20">
+ <framework:restrictions>
+
+ <value>
+ lower(firstName) like lower(concat(#{examplePerson.firstName},'%&'))
+ </value>
+
+ <value>
+ lower(lastName) like lower(concat(#{examplePerson.lastName},'%&'))
+ </value>
+
+ </framework:restrictions>
+</framework:entity-query>]]>
+</programlisting>
+ <para>
+ Notice the use of an "example" object.
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h1>Search for people</h1>
<h:form>
- <div>First name: <h:inputText value="#{examplePerson.firstName}"/></div>
- <div>Last name: <h:inputText value="#{examplePerson.lastName}"/></div>
- <div><h:commandButton value="Search" action="/search.jsp"/></div>
+
+ <div>
+ First name: <h:inputText value="#{examplePerson.firstName}"/>
+ </div>
+
+ <div>
+ Last name: <h:inputText value="#{examplePerson.lastName}"/>
+ </div>
+
+ <div>
+ <h:commandButton value="Search" action="/search.jsp"/>
+ </div>
+
</h:form>
-
-<h:dataTable value="#{people.resultList}" var="person">
- <h:column>
- <s:link view="/editPerson.jsp" value="#{person.firstName} #{person.lastName}">
- <f:param name="personId" value="#{person.id}"/>
- </s:link>
- </h:column>
-</h:dataTable>]]></programlisting>
-
- <para>
- To refresh the query when the underlying entities change we observe the
- <literal>org.jboss.seam.afterTransactionSuccess</literal> event:
+
+<h:dataTable value="#{people.resultList}" var="person">
+ <h:column>
+ <s:link view="/editPerson.jsp"
+ value="#{person.firstName} #{person.lastName}">
+ <f:param name="personId" value="#{person.id}"/>
+ </s:link>
+ </h:column>
+</h:dataTable>]]>
+</programlisting>
+ <para>
+ To refresh the query when the underlying entities change, we observe the <literal>org.jboss.seam.afterTransactionSuccess</literal> event:
</para>
-
- <programlisting role="XML"><![CDATA[<event type="org.jboss.seam.afterTransactionSuccess">
- <action execute="#{people.refresh}" />
-</event>]]></programlisting>
-
- <para>
- Or, to just refresh the query when the person entity is persisted, updated or
- removed through <literal>PersonHome</literal>:
+
+<programlisting role="XML"><![CDATA[<event type="org.jboss.seam.afterTransactionSuccess">
+ <action execute="#{people.refresh}" />
+</event>]]>
+</programlisting>
+ <para>
+ Or, to refresh the query when the person entity is persisted, updated or removed through <literal>PersonHome</literal>:
</para>
-
- <programlisting role="XML"><![CDATA[<event type="org.jboss.seam.afterTransactionSuccess.Person">
- <action execute="#{people.refresh}" />
- </event>]]></programlisting>
-
- <para>
- Unfortunately Query objects don't work well with
- <emphasis>join fetch</emphasis> queries - the use of pagination with
- these queries is not recommended, and you'll have to implement your own
- method of calculating the total number of results (by overriding
- <literal>getCountEjbql()</literal>.
- </para>
-
- <para>
- The examples in this section have all shown reuse by configuration. However,
- reuse by extension is equally possible for Query objects.
- </para>
-
- </section>
-
- <section>
- <title>Controller objects</title>
- <para>
- A totally optional part of the Seam Application Framework is the class
- <literal>Controller</literal> and its subclasses
- <literal>EntityController</literal>
- <literal>HibernateEntityController</literal> and
- <literal>BusinessProcessController</literal>. These classes provide
- nothing more than some convenience methods for access to commonly
- used built-in components and methods of built-in components. They help
- save a few keystrokes (characters can add up!) and provide a great
- launchpad for new users to explore the rich functionality built in
- to Seam.
- </para>
- <para>
- For example, here is what <literal>RegisterAction</literal> from the
- Seam registration example would look like:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Stateless
- at Name("register")
-public class RegisterAction extends EntityController implements Register
-{
-
- @In private User user;
-
- public String register()
- {
- List existing = createQuery("select u.username from User u where u.username=:username")
- .setParameter("username", user.getUsername())
- .getResultList();
-
- if ( existing.size()==0 )
- {
- persist(user);
- info("Registered new user #{user.username}");
- return "/registered.jspx";
- }
- else
- {
- addFacesMessage("User #{user.username} already exists");
- return null;
- }
- }
-
-}]]></programlisting>
-
- <para>
- As you can see, its not an earthshattering improvement...
- </para>
-
- </section>
-
+
+<programlisting role="XML"><![CDATA[<event type="org.jboss.seam.afterTransactionSuccess.Person">
+ <action execute="#{people.refresh}" />
+</event>]]>
+</programlisting>
+ <para>
+ Unfortunately, Query objects do not work well with <emphasis>join fetch</emphasis> queries. We do not recommend using pagination with these queries. You will need to implement your own method of total result number calculation by overriding <literal>getCountEjbql()</literal>.
+ </para>
+ <para>
+ All of the examples in this section have shown re-use via configuration. It is equally possibly to re-use via extension:
+ </para>
+ </section>
+
+ <section>
+ <title>Controller objects</title>
+ <para>
+ The class <literal>Controller</literal> and its subclasses (<literal>EntityController</literal>, <literal>HibernateEntityController</literal> and <literal>BusinessProcessController</literal>) are an optional part of the Seam Application Framework. These classes provide a convenient method to access frequently-used built-in components and component methods. They save keystrokes, and provide an excellent foothold for new users to explore the rich functionality built into Seam.
+ </para>
+ <para>
+ For example, <literal>RegisterAction</literal> (from the Seam registration example) looks like this:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateless
+ at Name("register")
+public class RegisterAction extends EntityController implements Register {
+ @In private User user;
+ public String register() {
+ List existing = createQuery("select u.username from
+ User u where u.username=:username").
+ setParameter("username",
+ user.getUsername()).getResultList();
+ if ( existing.size()==0 ) {
+ persist(user);
+ info("Registered new user #{user.username}");
+ return "/registered.jspx";
+ } else {
+ addFacesMessage("User #{user.username} already exists");
+ return null;
+ }
+ }
+}]]>
+</programlisting>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Gettingstarted.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Gettingstarted.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Gettingstarted.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,65 +1,52 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="gettingstarted">
- <title>Getting started with Seam, using seam-gen</title>
-
- <para>The Seam distribution includes a command line utility that makes it really easy to set up an Eclipse project,
- generate some simple Seam skeleton code, and reverse engineer an application from a preexisting database.</para>
-
- <para>This is the easy way to get your feet wet with Seam, and gives you some ammunition for next time you find
- yourself trapped in an elevator with one of those tedious Ruby guys ranting about how great and wonderful his
- new toy is for building totally trivial applications that put things in databases.</para>
-
- <para>In this release, seam-gen works best for people with JBoss EAP.</para>
-
- <para>You <emphasis>can</emphasis> use seam-gen without Eclipse, but in this tutorial, we want to show you how to
- use it in conjunction with Eclipse for debugging and integration testing. If you don't want to install Eclipse,
- you can still follow along with this tutorial—all steps can be performed from the command line.</para>
-
- <para>seam-gen is basically just an intricate Ant script wrapped around Hibernate Tools, together with some templates.
- That makes it easy to customize if you need to.</para>
-
- <section>
- <title>Before you start</title>
-
- <para>Make sure you have JDK 5 or JDK 6 (see <xref
- linkend="jdk_dependencies"/> for details), JBoss EAP 5 and Ant 1.7.0, along with recent versions of
- Eclipse, the JBoss IDE plugin for Eclipse and the TestNG plugin for Eclipse correctly installed before
- starting. Add your JBoss installation to the JBoss Server View in Eclipse. Start JBoss in debug mode.
- Finally, start a command prompt in the directory where you unzipped the Seam distribution.</para>
-
- <para>JBoss has sophisticated support for hot re-deployment of WARs and EARs. Unfortunately, due to bugs in the
- JVM, repeated redeployment of an EAR—which is common during development—eventually causes the JVM to run out
- of perm gen space. For this reason, we recommend running JBoss in a JVM with a large perm gen space at
- development time. If you're running JBoss from JBoss IDE, you can configure this in the server launch
- configuration, under "VM arguments". We suggest the following values:</para>
-
- <programlisting>-Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512m</programlisting>
-
- <para>If you don't have so much memory available, the following is our minimum recommendation:</para>
-
- <programlisting>-Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256m</programlisting>
-
- <para>If you're running JBoss from the command line, you can configure the JVM options in
- <literal>bin/run.conf</literal>.</para>
-
- <para>If you don't want to bother with this stuff now, you don't have to—come back to it later, when you get
- your first <literal>OutOfMemoryException</literal>.</para>
- </section>
-
- <section>
- <title>Setting up a new project</title>
-
- <para>The first thing we need to do is configure seam-gen for your environment: JBoss AS installation directory,
- project workspace, and database connection. It's easy, just type:</para>
-
- <programlisting>cd <seam_distribution_dir>
-seam setup</programlisting>
-
- <para>And you will be prompted for the needed information:</para>
-
- <programlisting><seam_distribution_dir>$ ./seam setup
+<chapter id="gettingstarted" >
+ <title>Getting started with Seam, using seam-gen</title>
+ <para>
+ Seam includes a command line utility that makes it easy to set up an Eclipse project, generate some simple Seam skeleton code, and reverse-engineer an application from a preexisting database. This is an easy way to familiarize yourself with Seam.
+ </para>
+ <para>
+ In this release, <application>seam-gen</application> works best in conjunction with JBoss Enterprise Application Platform.
+ </para>
+ <para>
+ seam-gen can be used without Eclipse, but this tutorial focuses on using seam-gen with Eclipse for debugging and integration testing. If you would prefer not to use Eclipse, you can still follow this tutorial — all steps can be performed from the command line.
+ </para>
+ <section>
+ <title>Before you start</title>
+ <para>
+ Make sure you have JDK 5 or JDK 6 (see <xref linkend="jdk_dependencies" /> for details), JBoss Enterprise Application Platform 5 and Ant 1.7.0, along with recent versions of Eclipse, the JBoss IDE plugin for Eclipse and the TestNG plugin for Eclipse correctly installed before you begin this tutorial. Add your JBoss installation to the JBoss Server View in Eclipse. Then, start JBoss in debug mode. Finally, start a command prompt in the directory where you unzipped the Seam distribution.
+ </para>
+ <para>
+ JBoss has sophisticated support for hot redeployment of <filename>WAR</filename>s and <filename>EAR</filename>s. Unfortunately, due to bugs in JVM, repeat redeployment of an EAR (common during development) uses all of the JVM's perm gen space. Therefore, we recommend running JBoss in a JVM with a large perm gen space during development. If you are running JBoss from JBoss IDE, you can configure this in the server launch configuration, under "VM arguments". We suggest the following values:
+ </para>
+
+<programlisting>-Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512m
+</programlisting>
+ <para>
+ The minimum recommended values are:
+ </para>
+
+<programlisting>-Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256m
+</programlisting>
+ <para>
+ If you are running JBoss from the command line, you can configure the JVM options in <filename>bin/run.conf</filename>.
+ </para>
+ </section>
+
+ <section>
+ <title>Setting up a new project</title>
+ <para>
+ First, configure seam-gen for your environment. Just type the following in your command line interface:
+ </para>
+
+<programlisting>cd <seam_distribution_dir> seam setup</programlisting>
+ <para>
+ You will receive the following prompt for the required information:
+ </para>
+
+<programlisting><seam_distribution_dir>$ ./seam setup
Buildfile: build.xml
init:
@@ -68,7 +55,7 @@
[echo] Welcome to seam-gen :-)
[input] Enter your project workspace (the directory that contains your Seam projects) [C:/Projects] [C:/Projects]
/Users/pmuir/workspace
- [input] Enter your JBoss home directory [C:/Program Files/jboss-4.2.3.GA] [C:/Program Files/jboss-4.2.3.GA]
+ [input] Enter your JBoss home directory [C:/Program Files/jboss-eap-5.0.1/jboss-as] [C:/Program Files/jboss-eap-5.0.1/jboss-as]
/var/lib/jbossas
[input] Enter the project name [myproject] [myproject]
helloworld
@@ -112,91 +99,70 @@
BUILD SUCCESSFUL
Total time: 1 minute 32 seconds
-~/workspace/jboss-seam $ </programlisting>
-
- <para>The tool provides sensible defaults, which you can accept by just pressing enter at the prompt.</para>
-
- <para>The most important choice you need to make is between EAR deployment and WAR deployment of your project.
- EAR projects support EJB 3.0 and require Java EE 5. WAR projects do not support EJB 3.0, but may be deployed
- to a J2EE environment. The packaging of a WAR is also simpler to understand. If you installed an EJB3-ready
- application server like JBoss, choose <literal>ear</literal>. Otherwise, choose <literal>war</literal>.
- We'll assume that you've chosen an EAR deployment for the rest of the tutorial, but you can follow exactly
- the same steps for a WAR deployment.</para>
-
- <para>If you are working with an existing data model, make sure you tell seam-gen that the tables already exist
- in the database.</para>
-
- <para>The settings are stored in <literal>seam-gen/build.properties</literal>, but you can also modify them
- simply by running <literal>seam setup</literal> a second time.</para>
-
- <para>Now we can create a new project in our Eclipse workspace directory, by typing:</para>
-
- <programlisting>seam new-project</programlisting>
-
- <programlisting><seam_distribution_dir> seam new-project
+~/workspace/jboss-seam $
+</programlisting>
+ <para>
+ The tool provides sensible defaults. To accept them, press <keycap>Enter</keycap> when prompted.
+ </para>
+ <para>
+ The most important choice here is whether to deploy your project as an <filename>EAR</filename> or <filename>WAR</filename> archive. <filename>EAR</filename> projects support Enterprise JavaBeans 3.0 (EJB3) and require Java EE 5. <filename>WAR</filename> projects do not suppport EJB3, but can be deployed to a J2EE environment, and their packaging is simpler. If you have an EJB3-ready application server like JBoss installed, choose <literal>ear</literal>. Otherwise, choose <literal>war</literal>. This tutorial assumes you are using an <filename>EAR</filename> deployment, but you can follow these steps even if your project is <filename>WAR</filename>-deployed.
+ </para>
+ <para>
+ If you are working with an existing data model, make sure to tell seam-gen that tables already exist in the database.
+ </para>
+ <para>
+ Create a new project in our Eclipse workspace directory by typing:
+ </para>
+
+<programlisting>seam new-project
+</programlisting>
+
+<programlisting><seam_distribution_dir> seam new-project
+Buildfile: build.xml
+...
+new-project:
+ [echo] A new Seam project named 'helloworld' was created in the C:\Projects directory
+ [echo] Type 'seam explode' and go to http://localhost:8080/helloworld
+ [echo] Eclipse Users: Add the project into Eclipse using File > New > Project and select General > Project (not Java Project)
+ [echo] NetBeans Users: Open the project in NetBeans
+BUILD SUCCESSFUL Total time: 7 seconds
+C:\Projects\jboss-seam>
+</programlisting>
+ <para>
+ This copies the Seam <filename>JAR</filename>s, dependent <filename>JAR</filename>s and the JDBC driver <filename>JAR</filename> to a new Eclipse project. It generates all required resources and configuration files, a Facelets template file and stylesheet, along with Eclipse metadata and an Ant build script. The Eclipse project will be automatically deployed to an exploded directory structure in JBoss as soon as you add the project. To add the project, go to <guimenu>New</guimenu> → <guimenu>Project...</guimenu> → <guimenu>General</guimenu> → <guimenu>Project</guimenu> → <guimenu>Next</guimenu>, type the <guilabel>Project name</guilabel> (in this case, <literal>helloworld</literal>), and then click <literal>Finish</literal>. Do not select <literal>Java Project</literal> from the New Project wizard.
+ </para>
+ <para>
+ If your default JDK in Eclipse is not a Java SE 5 or Java SE 6 JDK, you will need to select a Java SE 5 compliant JDK. Go to <guimenu>Project</guimenu> → <guimenu>Properties</guimenu> → <guimenu>Java Compiler</guimenu>.
+ </para>
+ <para>
+ Alternatively, you can deploy the project from outside Eclipse by typing <command>seam explode</command>.
+ </para>
+ <para>
+ The welcome page can be found at <literal>http://localhost:8080/helloworld</literal>. This is a Facelets page (<filename>view/home.xhtml</filename>) created using the template found at <filename>view/layout/template.xhtml</filename>. You can edit the welcome page or the template in Eclipse, and see the results immediately by refreshing your browser.
+ </para>
+ <para>
+ XML configuration documents will be generated in the project directory. These may appear complicated, but they are comprised primarily of standard Java EE, and require little alteration, even between Seam projects.
+ </para>
+ <para>
+ There are three database and persistence configurations in the generated project. <filename>persistence-test.xml</filename> and <filename>import-test.sql</filename> are used while running TestNG unit tests against HSQLDB. The database schema and test data in <filename>import-test.sql</filename> is always exported to the database before tests are run. <filename>myproject-dev-ds.xml</filename>, <filename>persistence-dev.xml</filename> and <filename>import-dev.sql</filename> are used during application deployment to your development database. If you told seam-gen that you were working with an existing database, the schema may be exported automatically upon deployment. <filename>myproject-prod-ds.xml</filename>, <filename>persistence-prod.xml</filename> and <filename>import-prod.sql</filename> are used during application deployment to your production database. The schema will not be exported automatically upon deployment.
+ </para>
+ </section>
+
+ <section>
+ <title>Creating a new action</title>
+ <para>
+ You can create a simple web page with a stateless action method by typing:
+ </para>
+
+<programlisting>seam new-action
+</programlisting>
+ <para>
+ Seam prompts for some information, and generates a new Facelets page and Seam component for your project.
+ </para>
+
+<programlisting>C:\Projects\jboss-seam>seam new-action
Buildfile: build.xml
-...
-
-new-project:
- [echo] A new Seam project named 'helloworld' was created in the C:\Projects directory
- [echo] Type 'seam explode' and go to http://localhost:8080/helloworld
- [echo] Eclipse Users: Add the project into Eclipse using File > New > Project and select General > Project (not Java Project)
- [echo] NetBeans Users: Open the project in NetBeans
-
-BUILD SUCCESSFUL
-Total time: 7 seconds
-C:\Projects\jboss-seam></programlisting>
-
- <para>This copies the Seam jars, dependent jars and the JDBC driver jar to a new Eclipse project, and generates
- all needed resources and configuration files, a facelets template file and stylesheet, along with Eclipse
- metadata and an Ant build script. The Eclipse project will be automatically deployed to an exploded
- directory structure in JBoss AS as soon as you add the project using <literal>New -> Project...
- -> General -> Project -> Next</literal>, typing the <literal>Project name</literal>
- (<literal>helloworld</literal> in this case), and then clicking <literal>Finish</literal>. Do not select
- <literal>Java Project</literal> from the New Project wizard.</para>
-
- <para>If your default JDK in Eclipse is not a Java SE 5 or Java SE 6 JDK, you will need to select a Java SE 5
- compliant JDK using <literal>Project -> Properties -> Java Compiler</literal>.</para>
-
- <para>Alternatively, you can deploy the project from outside Eclipse by typing <literal>seam explode</literal>.</para>
-
- <para>Go to <literal>http://localhost:8080/helloworld</literal> to see a welcome page. This is a facelets page,
- <literal>view/home.xhtml</literal>, using the template <literal>view/layout/template.xhtml</literal>.
- You can edit this page, or the template, in Eclipse, and see the results <emphasis>immediately</emphasis>,
- by clicking refresh in your browser.</para>
-
- <para>Don't get scared by the XML configuration documents that were generated into the project directory. They
- are mostly standard Java EE stuff, the stuff you need to create once and then never look at again, and they
- are 90% the same between all Seam projects. (They are so easy to write that even seam-gen can do it.)</para>
-
- <para>The generated project includes three database and persistence configurations. The
- <literal>persistence-test.xml</literal> and
- <literal>import-test.sql</literal> files are used when running the TestNG unit tests against HSQLDB. The
- database schema and the test data in <literal>import-test.sql</literal> is always exported to the database
- before running tests. The <literal>myproject-dev-ds.xml</literal>, <literal>persistence-dev.xml</literal>and
- <literal>import-dev.sql</literal> files are for use when deploying the application to your development
- database. The schema might be exported automatically at deployment, depending upon whether you told seam-gen
- that you are working with an existing database. The <literal>myproject-prod-ds.xml</literal>,
- <literal>persistence-prod.xml</literal>and <literal>import-prod.sql</literal> files are for use when
- deploying the application to your production database. The schema is not exported automatically at
- deployment.</para>
- </section>
-
- <section>
- <title>Creating a new action</title>
-
- <para>If you're used to traditional action-style web frameworks, you're probably wondering how you can create a
- simple web page with a stateless action method in Java. If you type:</para>
-
- <programlisting>seam new-action</programlisting>
-
- <para>Seam will prompt for some information, and generate a new facelets page and Seam component for your
- project.</para>
-
- <programlisting>C:\Projects\jboss-seam>seam new-action
-Buildfile: build.xml
-
validate-workspace:
validate-project:
@@ -226,31 +192,34 @@
BUILD SUCCESSFUL
Total time: 13 seconds
-C:\Projects\jboss-seam></programlisting>
-
- <para>Because we've added a new Seam component, we need to restart the exploded directory deployment. You can do
- this by typing <literal>seam restart</literal>, or by running the <literal>restart</literal> target in the
- generated project <literal>build.xml</literal> file from inside Eclipse. Another way to force a restart is
- to edit the file <literal>resources/META-INF/application.xml</literal> in Eclipse. <emphasis>Note that you
- do not need to restart JBoss each time you change the application.</emphasis></para>
-
- <para>Now go to <literal>http://localhost:8080/helloworld/ping.seam</literal> and click the button. You can see
- the code behind this action by looking in the project <literal>src</literal> directory. Put a breakpoint in
- the <literal>ping()</literal> method, and click the button again.</para>
-
- <para>Finally, locate the <literal>PingTest.xml</literal> file in the test package and run the integration tests
- using the TestNG plugin for Eclipse. Alternatively, run the tests using <literal>seam test</literal> or the
- <literal>test</literal> target of the generated build.</para>
- </section>
-
- <section>
- <title>Creating a form with an action</title>
-
- <para>The next step is to create a form. Type:</para>
-
- <programlisting>seam new-form</programlisting>
-
- <programlisting>C:\Projects\jboss-seam>seam new-form
+C:\Projects\jboss-seam>
+</programlisting>
+ <para>
+ Since we have added a new Seam component, it is necessary to restart the exploded directory deployment. You can do this by typing <literal>seam restart</literal>, or by running the <literal>restart</literal> target in the generated project's <literal>build.xml</literal> file from within Eclipse. Alternatively, you can edit the <literal>resources/META-INF/application.xml</literal> file in Eclipse.
+ </para>
+ <note>
+ <para>
+ You do not need to restart JBoss each time you change the application.
+ </para>
+ </note>
+ <para>
+ Now go to <literal>http://localhost:8080/helloworld/ping.seam</literal> and click the button. The code behind this action is in the project <filename>src</filename> directory. Add a breakpoint to the <literal>ping()</literal> method, and click the button again.
+ </para>
+ <para>
+ Finally, locate the <filename>PingTest.xml</filename> file in the test package, and run the integration tests with the TestNG plugin for Eclipse. You can also run the tests with <command>seam test</command> or the <literal>test</literal> target of the generated build.
+ </para>
+ </section>
+
+ <section>
+ <title>Creating a form with an action</title>
+ <para>
+ The next step is to create a form. Type:
+ </para>
+
+<programlisting>seam new-form
+</programlisting>
+
+<programlisting>C:\Projects\jboss-seam>seam new-form
Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml
validate-workspace:
@@ -282,128 +251,152 @@
BUILD SUCCESSFUL
Total time: 5 seconds
-C:\Projects\jboss-seam></programlisting>
-
- <para>Restart the application again, and go to <literal>http://localhost:8080/helloworld/hello.seam</literal>.
- Then take a look at the generated code. Run the test. Try adding some new fields to the form and Seam
- component (remember to restart the deployment each time you change the Java code).</para>
- </section>
-
- <section>
- <title>Generating an application from an existing database</title>
-
- <para>Manually create some tables in your database. (If you need to switch to a different database, just run
- <literal>seam setup</literal> again.) Now type:</para>
-
- <programlisting>seam generate-entities</programlisting>
-
- <para>Restart the deployment, and go to <literal>http://localhost:8080/helloworld</literal>. You can browse the
- database, edit existing objects, and create new objects. If you look at the generated code, you'll probably
- be amazed how simple it is! Seam was designed so that data access code is easy to write by hand, even for
- people who don't want to cheat by using seam-gen.</para>
- </section>
-
- <section>
- <title>Generating an application from existing JPA/EJB3 entities</title>
-
- <para>Place your existing, valid entity classes inside the <literal>src/main</literal>. Now type</para>
-
- <programlisting>seam generate-ui</programlisting>
-
- <para>Restart the deployment, and go to <literal>http://localhost:8080/helloworld</literal>.</para>
- </section>
-
- <section>
- <title>Deploying the application as an EAR</title>
-
- <para>Finally, we want to be able to deploy the application using standard Java EE 5 packaging. First, we need
- to remove the exploded directory by running <literal>seam unexplode</literal>. To deploy the EAR, we can
- type <literal>seam deploy</literal> at the command prompt, or run the <literal>deploy</literal> target of
- the generated project build script. You can undeploy using <literal>seam undeploy</literal> or the
- <literal>undeploy</literal> target.</para>
-
- <para>By default, the application will be deployed with the <emphasis>dev profile</emphasis>. The EAR will
- include the <literal>persistence-dev.xml</literal> and <literal>import-dev.sql</literal> files, and the
- <literal>myproject-dev-ds.xml</literal> file will be deployed. You can change the profile, and use the
- <emphasis>prod profile</emphasis>, by typing</para>
-
- <programlisting>seam -Dprofile=prod deploy</programlisting>
-
- <para>You can even define new deployment profiles for your application. Just add appropriately named files to
- your project—for example, <literal>persistence-staging.xml</literal>, <literal>import-staging.sql</literal>
- and <literal>myproject-staging-ds.xml</literal>—and select the name of the profile using
- <literal>-Dprofile=staging</literal>.</para>
- </section>
-
- <section id="gettingstarted-hotdeployment">
- <title>Seam and incremental hot deployment</title>
-
- <para>When you deploy your Seam application as an exploded directory, you'll get some support for incremental
- hot deployment at development time. You need to enable debug mode in both Seam and Facelets, by adding this
- line to <literal>components.xml</literal>:</para>
-
- <programlisting role="XML"><![CDATA[<core:init debug="true">]]></programlisting>
-
- <para>Now, the following files may be redeployed without requiring a full restart of the web application:</para>
-
- <itemizedlist>
- <listitem>
- <para>any facelets page</para>
- </listitem>
-
- <listitem>
- <para>any <literal>pages.xml</literal> file</para>
- </listitem>
- </itemizedlist>
-
- <para>But if we want to change any Java code, we still need to do a full restart of the application. (In JBoss
- this may be accomplished by touching the top level deployment descriptor: <literal>application.xml</literal>
- for an EAR deployment, or <literal>web.xml</literal> for a WAR deployment.)</para>
-
- <para>But if you really want a fast edit/compile/test cycle, Seam supports incremental redeployment of JavaBean
- components. To make use of this functionality, you must deploy the JavaBean components into the
- <literal>WEB-INF/dev</literal> directory, so that they will be loaded by a special Seam classloader,
- instead of by the WAR or EAR classloader.</para>
-
- <para>You need to be aware of the following limitations:</para>
-
- <itemizedlist>
- <listitem>
- <para>the components must be JavaBean components, they cannot be EJB3 beans (we are working on fixing
- this limitation)</para>
- </listitem>
-
- <listitem>
- <para>entities can never be hot-deployed</para>
- </listitem>
-
- <listitem>
- <para>components deployed via <literal>components.xml</literal> may not be hot-deployed</para>
- </listitem>
-
- <listitem>
- <para>the hot-deployable components will not be visible to any classes deployed outside of
- <literal>WEB-INF/dev</literal></para>
- </listitem>
-
- <listitem>
- <para>Seam debug mode must be enabled and <literal>jboss-seam-debug.jar</literal>
- must be in <literal>WEB-INF/lib</literal></para>
- </listitem>
-
- <listitem>
- <para>You must have the Seam filter installed in web.xml</para>
- </listitem>
-
- <listitem>
- <para>You may see errors if the system is placed under any load and debug is enabled.</para>
- </listitem>
-
- </itemizedlist>
-
- <para>If you create a WAR project using seam-gen, incremental hot deployment is available out of the box for
- classes in the <literal>src/hot</literal> source directory. However, seam-gen does not support
- incremental hot deployment for EAR projects.</para>
- </section>
-
+C:\Projects\jboss-seam>
+</programlisting>
+ <para>
+ Restart the application again, and go to <literal>http://localhost:8080/helloworld/hello.seam</literal>. Look at the generated code. Run the test. Experiment with adding new fields to the form and Seam component. (Remember to restart the deployment each time you alter the Java code.)
+ </para>
+ </section>
+
+ <section>
+ <title>Generating an application from an existing database</title>
+ <para>
+ Manually create tables in your database. (To switch to a different database, run <literal>seam setup</literal> again.) Now type:
+ </para>
+
+<programlisting>seam generate-entities
+</programlisting>
+ <para>
+ Restart the deployment, and go to <literal>http://localhost:8080/helloworld</literal>. You can browse the database, edit existing objects, and create new objects. The code generated here is very simple. Seam was designed so that data access code is easy to write by hand, even without the assistance of seam-gen.
+ </para>
+ </section>
+
+ <section>
+ <title>Generating an application from existing JPA/EJB3 entities</title>
+ <para>
+ Place your existing, valid entity classes inside the <literal>src/main</literal> directory. Now, type:
+ </para>
+
+<programlisting>seam generate-ui
+</programlisting>
+ <para>
+ Restart the deployment, and go to <literal>http://localhost:8080/helloworld</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Deploying the application as an <filename>EAR</filename></title>
+ <para>
+ Several changes are required before we can deploy the application with standard Java EE 5 packaging. First, remove the exploded directory by running <command>seam unexplode</command>. To deploy the EAR, either type <command>seam deploy</command> at the command prompt, or run the <literal>deploy</literal> target of the generated project build script. To undeploy, use <command>seam undeploy</command> or the <literal>undeploy</literal> target.
+ </para>
+ <para>
+ By default, the application deploys with the <emphasis>dev profile</emphasis>. The EAR includes the <filename>persistence-dev.xml</filename> and <filename>import-dev.sql</filename> files, and deploys <filename>myproject-dev-ds.xml</filename>. You can change the profile to <emphasis>prod profile</emphasis> by typing:
+ </para>
+
+<programlisting>seam -Dprofile=prod deploy
+</programlisting>
+ <para>
+ You can also define new deployment profiles for your application. Just add appropriately named files to your project — for example, <filename>persistence-staging.xml</filename>, <filename>import-staging.sql</filename> and <filename>myproject-staging-ds.xml</filename> — and select the name of the profile with <literal>-Dprofile=staging</literal>.
+ </para>
+ </section>
+
+ <section id="gettingstarted-hotdeployment">
+ <title>Seam and incremental hot deployment</title>
+ <para>
+ Some support for incremental hot deployment is included during development when you deploy your Seam application as an exploded directory. Add the following line to <filename>components.xml</filename> to enable debug mode in Seam and Facelets:
+ </para>
+
+<programlisting role="XML"><![CDATA[<core:init debug="true">]]>
+</programlisting>
+ <para>
+ The following files may now be redeployed without requiring a full restart of the web application:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ any Facelets page
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ any <filename>pages.xml</filename> file
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ If you want to change any Java code, you will still need to do a full restart of the application. In JBoss, this can be accomplished by touching the top-level deployment descriptor: <filename>application.xml</filename> for an EAR deployment, or <filename>web.xml</filename> for a WAR deployment.
+ </para>
+ <para>
+ Seam supports incremental redeployment of JavaBean components for a fast edit/compile/test cycle. To make use of this, the JavaBean components must be deployed into the <filename>WEB-INF/dev</filename> directory. Here, they wil be loaded by a special Seam classloader instead of the WAR or EAR classloader.
+ </para>
+ <para>
+ This function has some limitations:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The components must be JavaBean components — they cannot be EJB3 beans. (Seam is working to remove this limitation.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Entities can never be hot-deployed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Components deployed with <filename>components.xml</filename> cannot be hot-deployed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Hot-deployable components will not be visible to any classes deployed outside <filename>WEB-INF/dev</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Seam debug mode must be enabled and <filename>jboss-seam-debug.jar</filename> must be included in <filename>WEB-INF/lib</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Seam filter must be installed in <filename>web.xml</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ You may see errors if the system is placed under any load and debug is enabled.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ For WAR projects created with seam-gen, incremental hot deployment is available out of the box for classes in the <literal>src/hot</literal> source directory. However, seam-gen does not support incremental hot deployment for EAR projects.
+ </para>
+ </section>
+ <!--
+ <section>
+ <title>Using Seam with JBoss 4.0</title>
+ <para>
+ Seam 2.0 was developed for JavaServer Faces 1.2. When using JBoss AS, we recommend using JBoss 4.2 or JBoss 5.0, both of which bundle the JSF 1.2 reference implementation. However, Seam 2.0 can still operate on the JBoss 4.0 platform. There are two steps required to do this: install an EJB3-enabled version of JBoss 4.0, and replace MyFaces with the JSF 1.2 reference implementation. Once these steps have been completed, Seam 2.0 applications can be deployed to JBoss 4.0.
+ </para>
+ <section>
+ <title>Install JBoss 4.0</title>
+ <para>
+ JBoss 4.0 does not ship a default configuration compatible with Seam. To run Seam, install JBoss 4.0.5 using the JEMS 1.2 installer with the EJB3 profile selected. Seam will not run with an installation that doesn't include EJB3 support. The JEMS installer can be downloaded from <ulink url="http://labs.jboss.com/jemsinstaller/downloads">http://labs.jboss.com/ jemsinstaller/downloads</ulink>.
+ </para>
+ </section>
+
+ <section>
+ <title>Install the JSF 1.2 RI</title>
+ <para>
+ The web configuration for JBoss 4.0 can be found in the <filename>server/default/deploy/jbossweb-tomcat55.sar</filename>. You will need to delete <filename>myfaces-api.jar</filename> and any <filename>myfaces-impl.jar</filename> from the <filename>jsf-libs </filename>directory. Then, you will need to copy <filename>jsf-api.jar</filename>, <filename>jsf-impl.jar</filename>, <filename>el-api.jar</filename>, and <filename>el-ri.jar</filename> to that directory. The JSF JARs can be found in the Seam <filename>lib</filename> directory. The EL JARs can be obtained from the Seam 1.2 release.
+ </para>
+ <para>
+ You will also need to edit the <filename>conf/web.xml</filename>, replacing <filename>myfaces-impl.jar</filename> with <filename>jsf-impl.jar</filename>.
+ </para>
+ </section>
+
+ </section>-->
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Groovy.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Groovy.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Groovy.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,219 +1,181 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="groovy">
- <title>Groovy integration</title>
+<chapter id="groovy" >
+ <title>Groovy integration</title>
+ <para>
+ Seam has a great capability for Rapid Application Development (RAD). Seam allows you to utilize dynamic languages with your existing platform, while retaining compatibility with standard Java APIs. Static and dynamic languages are integrated, so there is no need for context-switching, and you can use the same annotations and APIs to write a dynamic Seam component as you would for a regular Seam component.
+ </para>
+ <section>
+ <title id="groovy-intro">Groovy introduction</title>
+ <para>
+ Groovy is an agile, Java-based dynamic language, with additional features inspired by Python, Ruby, and Smalltalk. Being Java-based, with Java objects and classes, Groovy is easy to learn and integrates seamlessly with existing Java libraries and frameworks.
+ </para>
+ <!-- #modify: "TODO: write a quick overview of the Groovy syntax add-on." Let me comment that out for you. -->
+ </section>
+
+ <section>
+ <title>Writing Seam applications in Groovy</title>
+ <para>
+ Since Groovy objects are Java objects, any Seam component can be written and deployed with Groovy. You can also combine Groovy and Java classes in the same application.
+ </para>
+ <section>
+ <title>Writing Groovy components</title>
+ <para>
+ You will need to use Groovy 1.1 or higher to support annotations. Groovy code can be used in a Seam application like so:
+ </para>
+ <section>
+ <title>Entity</title>
+
+<programlisting role="JAVA"><![CDATA[
+ at Entity
+ at Name("hotel")
+class Hotel implements Serializable {
+ @Id @GeneratedValue
+ Long id
+
+ @Length(max=50) @NotNull
+ String name
- <para>One aspect of JBoss Seam is its RAD (Rapid Application Development) capability. While not synonymous with RAD,
- one interesting tool in this space is dynamic languages. Until recently, choosing a dynamic language was
- required choosing a completely different development platform (a development platform with a set of APIs and a
- runtime so great that you would no longer want to use you old legacy Java [sic] APIs anymore, which would be
- lucky because you would be forced to use those proprietary APIs anyway). Dynamic languages built on top of the
- Java Virtual Machine, and <ulink url="http://groovy.codehaus.org">Groovy</ulink> in particular broke this
- approach in silos.</para>
+ @Length(max=100) @NotNull
+ String address
- <para>JBoss Seam now unites the dynamic language world with the Java EE world by seamlessly integrating both static
- and dynamic languages. JBoss Seam lets the application developer use the best tool for the task, without context
- switching. Writing dynamic Seam components is exactly like writing regular Seam components. You use the same
- annotations, the same APIs, the same everything.</para>
+ @Length(max=40) @NotNull
+ String city
- <section>
- <title id="groovy-intro">Groovy introduction</title>
+ @Length(min=2, max=10) @NotNull
+ String state
- <para>Groovy is an agile dynamic language based on the Java language but with additional features inspired by
- Python, Ruby and Smalltalk. The strengths of Groovy are twofold:</para>
+ @Length(min=4, max=6) @NotNull
+ String zip
- <itemizedlist>
- <listitem>
- <para>Java syntax is supported in Groovy: Java code is Groovy code, making the learning curve very
- smooth</para>
- </listitem>
+ @Length(min=2, max=40) @NotNull
+ String country
- <listitem>
- <para>Groovy objects are Java objects, and Groovy classes are Java classes: Groovy integrates smoothly
- with existing Java libraries and frameworks.</para>
- </listitem>
- </itemizedlist>
+ @Column(precision=6, scale=2)
+ BigDecimal price
- <para>TODO: write a quick overview of the Groovy syntax add-on</para>
- </section>
-
- <section>
- <title>Writing Seam applications in Groovy</title>
-
- <para>There is not much to say about it. Since a Groovy object is a Java object, you can virtually write any
- Seam component, or any class for what it worth, in Groovy and deploy it. You can also mix Groovy classes and
- Java classes in the same application.</para>
-
- <section>
- <title>Writing Groovy components</title>
-
- <para>As you should have noticed by now, Seam uses annotations heavily. Be sure to use Groovy 1.1 or
- above for annotation support. Here are some example of groovy code used in a Seam application.</para>
-
- <section>
- <title>Entity</title>
-
- <programlisting role="JAVA"> @Entity
- @Name("hotel")
- class Hotel implements Serializable
- {
- @Id @GeneratedValue
- Long id
-
- @Length(max=50) @NotNull
- String name
-
- @Length(max=100) @NotNull
- String address
-
- @Length(max=40) @NotNull
- String city
-
- @Length(min=2, max=10) @NotNull
- String state
-
- @Length(min=4, max=6) @NotNull
- String zip
-
- @Length(min=2, max=40) @NotNull
- String country
-
- @Column(precision=6, scale=2)
- BigDecimal price
-
- @Override
- String toString()
- {
- return "Hotel(${name},${address},${city},${zip})"
- }
- }</programlisting>
-
- <para>Groovy natively support the notion of properties (getter/setter), so there is no need to
- explicitly write verbose getters and setters: in the previous example, the hotel class can be
- accessed from Java as <code>hotel.getCity()</code>, the getters and setters being generated by the
- Groovy compiler. This type of syntactic sugar makes the entity code very concise.</para>
-
- </section>
-
- <section>
- <title>Seam component</title>
-
- <para>Writing Seam components in Groovy is in no way different than in Java: annotations are used to
- mark the class as a Seam component.</para>
-
- <programlisting role="JAVA">@Scope(ScopeType.SESSION)
+ @Override
+ String toString(){
+ return "Hotel(${name},${address},${city},${zip})"
+ }
+}]]>
+</programlisting>
+ <para>
+ Since Groovy supports properties, there is no need to explicitly write verbose getters and setters. In the previous example, the hotel class can be accessed from Java as <code>hotel.getCity()</code> — the getters and setters are generated by the Groovy compiler. This makes the entity code very concise.
+ </para>
+ </section>
+
+ <section>
+ <title>Seam component</title>
+ <para>
+ You can write Seam components in Groovy exactly as you would in Java: annotations mark classes as Seam components.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[
+ at Scope(ScopeType.SESSION)
@Name("bookingList")
-class BookingListAction implements Serializable
-{
- @In EntityManager em
- @In User user
- @DataModel List<Booking> bookings
- @DataModelSelection Booking booking
- @Logger Log log
+class BookingListAction implements Serializable {
+ @In EntityManager em
+ @In User user
+ @DataModel List<Booking> bookings
+ @DataModelSelection Booking booking
+ @Logger Log log
- @Factory public void getBookings()
- {
- bookings = em.createQuery('''
- select b from Booking b
+ @Factory
+ public void getBookings() {
+ bookings = em.createQuery('''
+ select b from Booking b
where b.user.username = :username
- order by b.checkinDate''')
- .setParameter("username", user.username)
- .getResultList()
- }
+ order by b.checkinDate''').
+ setParameter("username", user.username).
+ getResultList()
+ }
- public void cancel()
- {
- log.info("Cancel booking: #{bookingList.booking.id} for #{user.username}")
- Booking cancelled = em.find(Booking.class, booking.id)
- if (cancelled != null) em.remove( cancelled )
- getBookings()
- FacesMessages.instance().add("Booking cancelled for confirmation number #{bookingList.booking.id}", new Object[0])
+ public void cancel() {
+ log.info("Cancel booking: #{bookingList.booking.id}
+ for #{user.username}")
+ Booking cancelled = em.find(Booking.class, booking.id)
+ if (cancelled != null) em.remove( cancelled )
+ getBookings()
+ FacesMessages.instance().add("Booking cancelled for confirmation
+ number #{bookingList.booking.id}",
+ new Object[0])
}
-}</programlisting>
+}]]>
+</programlisting>
- <para/>
- </section>
- </section>
-
- <section>
- <title>seam-gen</title>
-
- <para>Seam gen has a transparent integration with Groovy. You can write Groovy code in seam-gen backed
- projects without any additional infrastructure requirement. When writing a Groovy entity, simply place
- your <filename>.groovy</filename> files in <filename>src/main</filename>. Unsurprisingly, when writing
- an action, simply place your <filename>.groovy</filename> files in
- <filename>src/hot</filename>.</para>
- </section>
- </section>
-
- <section>
- <title>Deployment</title>
-
- <para>Deploying Groovy classes is very much like deploying Java classes (surprisingly, no need to write nor
- comply with a 3-letter composite specification to support a multi-language component framework).</para>
-
- <para>Beyond standard deployments, JBoss Seam has the ability, at development time, to redeploy JavaBeans Seam
- component classes without having to restart the application, saving a lot of time in the development / test
- cycle. The same support is provided for GroovyBeans Seam components when the <filename>.groovy</filename>
- files are deployed.</para>
-
- <section>
- <title>Deploying Groovy code</title>
-
- <para>A Groovy class <emphasis>is</emphasis> a Java class, with a bytecode representation just like a Java
- class. To deploy, a Groovy entity, a Groovy Session bean or a Groovy Seam component, a compilation step
- is necessary. A common approach is to use the <literal>groovyc</literal> ant task. Once compiles, a
- Groovy class is in no way different than a Java class and the application server will treat them
- equally. Note that this allow a seamless mix of Groovy and Java code.</para>
- </section>
-
- <section>
- <title>Native .groovy file deployment at development time</title>
-
- <para>JBoss Seam natively supports the deployment of <literal>.groovy</literal> files (ie without
- compilation) in incremental hotdeployment mode (development only). This enables a very fast edit/test
- cycle. To set up .groovy deployments, follow the configuration at <xref
- linkend="gettingstarted-hotdeployment"/> and deploy your Groovy code (<filename>.groovy</filename>
- files) into the <filename>WEB-INF/dev</filename> directory. The GroovyBean components will be picked up
- incrementally with no need to restart the application (and obviously not the application server either).</para>
-
- <para>Be aware that the native .groovy file deployment suffers the same limitations as the regular Seam
- hotdeployment:</para>
-
- <itemizedlist>
- <listitem>
- <para>The components must be JavaBeans or GroovyBeans. They cannot be EJB3 bean</para>
- </listitem>
-
- <listitem>
- <para>Entities cannot be hotdeployed</para>
- </listitem>
-
- <listitem>
- <para>The hot-deployable components will not be visible to any classes deployed outside of
- <literal>WEB-INF/dev</literal></para>
- </listitem>
-
- <listitem>
- <para>Seam debug mode must be enabled</para>
- </listitem>
- </itemizedlist>
-
- <para/>
- </section>
-
- <section>
- <title>seam-gen</title>
-
- <para>Seam-gen transparently supports Groovy files deployment and compilation. This includes the native
- <filename>.groovy</filename> file deployment in development mode (compilation-less). If you create a
- seam-gen project of type WAR, Java and Groovy classes in <filename>src/hot</filename> will
- automatically be candidate for the incremental hot deployment. If you are in production mode, the Groovy
- files will simply be compiled before deployment.</para>
-
- <para>You will find a live example of the Booking demo written completely in Groovy and supporting
- incremental hot deployment in <filename>examples/groovybooking</filename>.</para>
- </section>
- </section>
+ </section>
+
+ </section>
+
+ <section>
+ <title>seam-gen</title>
+ <para>
+ Seam-gen interacts transparently with Groovy. No additional infrastructure is required to include Groovy code in seam-gen-backed projects — when writing an entity, just place your <filename>.groovy</filename> files in <filename>src/main</filename>. When writing an action, place your <filename>.groovy</filename> files in <filename>src/hot</filename>.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Deployment</title>
+ <para>
+ Deploying Groovy classes works like deploying Java classes. As with JavaBeans component classes, Seam can redeploy GroovyBeans component classes without restarting the application.
+ </para>
+ <section>
+ <title>Deploying Groovy code</title>
+ <para>
+ Groovy entities, session beans, and components all require compilation to deploy — use the <literal>groovyc</literal> ant task. Once compiled, a Groovy class is identical to a Java class, and the application server will treat them equally. This allows a seamless mix of Groovy and Java code.
+ </para>
+ </section>
+
+ <section>
+ <title>Native .groovy file deployment at development time</title>
+ <para>
+ Seam supports <filename>.groovy</filename> file hot deployment (deployment without compilation) in incremental hot deployment mode. This mode is development-only, and enables a fast edit/test cycle. Follow the configuration instructions at <xref linkend="gettingstarted-hotdeployment" /> to set up <filename>.groovy</filename> hot deployment. Deploy your Groovy code (<filename>.groovy</filename> files) into the <filename>WEB-INF/dev</filename> directory. The GroovyBean components will deploy incrementally, without needing to restart either application or application server.
+ </para>
+ <note>
+ <para>
+ The native <filename>.groovy</filename> file deployment has the same limitations as the regular Seam hot deployment:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ components must be either JavaBeans or GroovyBeans — they cannot be EJB3 beans.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ entities cannot be hot deployed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ hot-deployable components are not visible to any classes deployed outside <literal>WEB-INF/dev</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Seam debug mode must be enabled.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </note>
+ </section>
+
+ <section>
+ <title>seam-gen</title>
+ <para>
+ Seam-gen transparently supports Groovy file deployment and compilation. This includes the native <filename>.groovy</filename> file hot deployment available during development. In WAR-type projects, Java and Groovy classes in <filename>src/hot</filename> are automatic candidates for incremental hot deployment. In production mode, Groovy files will be compiled prior to deployment.
+ </para>
+ <para>
+ There is a Booking demonstration, written completely in Groovy and supporting incremental hot deployment, in <filename>examples/groovybooking</filename>.
+ </para>
+ </section>
+
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Gwt.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Gwt.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Gwt.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,239 +1,208 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="gwt">
- <title>Seam and the Google Web Toolkit</title>
+<chapter id="gwt" >
+ <title>Seam and the Google Web Toolkit</title>
+ <warning>
+ <title>Google Web Toolkit integration is a Technology Preview</title>
+ <para>Technology Preview features are not fully supported under Red Hat subscription level agreements (SLAs), may not be functionally complete, and are not intended for production use. However, these features provide early access to upcoming product innovations, enabling customers to test functionality and provide feedback during the development process. As Red Hat considers making future iterations of Technology Preview features generally available, we will provide commercially reasonable efforts to resolve any reported issues that customers experience when using these features.</para>
+ </warning>
- <para>
- For those that prefer to use the Google Web Toolkit (GWT) to develop dynamic AJAX applications, Seam provides
- an integration layer that allows GWT widgets to interact directly with Seam components.
- </para>
-
- <para>
- To use GWT, we assume that you are already familiar with the GWT tools - more information can be found at
- <ulink url="http://code.google.com/webtoolkit/">http://code.google.com/webtoolkit/</ulink>. This chapter
- does not attempt to explain how GWT works or how to use it.
- </para>
-
- <note>
- <title>Technology preview </title>
- <para>GWT integration in Seam is marked as technology preview, so standard support is not guaranteed.</para>
- </note>
-
- <section>
- <title>Configuration</title>
-
- <para>
- There is no special configuration required to use GWT in a Seam application, however the Seam resource servlet
- must be installed. See <xref linkend="configuration"/> for details.
- </para>
-
- </section>
-
- <section>
- <title>Preparing your component</title>
-
- <para>
- The first step in preparing a Seam component to be called via GWT, is to create both synchronous and
- asynchronous service interfaces for the methods you wish to call. Both of these interfaces should extend the
- GWT interface <literal>com.google.gwt.user.client.rpc.RemoteService</literal>:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public interface MyService extends RemoteService {
- public String askIt(String question);
- }]]></programlisting>
-
- <para>
- The asynchronous interface should be identical, except that it also contains an additional
- <literal>AsyncCallback</literal> parameter for each of the methods it declares:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public interface MyServiceAsync extends RemoteService {
- public void askIt(String question, AsyncCallback callback);
-}]]></programlisting>
-
- <para>
- The asynchronous interface, in this example <literal>MyServiceAsync</literal>, will be implemented by GWT and
- should never be implemented directly.
- </para>
-
- <para>
- The next step, is to create a Seam component that implements the synchronous interface:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("org.jboss.seam.example.remoting.gwt.client.MyService")
+ <para>
+ If you prefer to develop dynamic AJAX (Asynchronous Java and XML) applications with the Google Web Toolkit (GWT), Seam provides an integration layer that allows GWT widgets to interact directly with Seam components.
+ </para>
+ <para>
+ In this section, we assume you are already familiar with GWT Tools, and focus only on the Seam integration. You can find more information at <ulink url="http://code.google.com/webtoolkit/">http://code.google.com/webtoolkit/ </ulink>.
+ </para>
+
+ <section>
+ <title>Configuration</title>
+ <para>
+ You do not need to make any configuration changes to use GWT in a Seam application — all you need to do is install the Seam Resource Servlet. See <xref linkend="configuration" /> for details.
+ </para>
+ </section>
+
+ <section>
+ <title>Preparing your component</title>
+ <para>
+ To prepare a Seam component to be called with GWT, you must first create both synchronous and asynchronous service interfaces for the methods you wish to call. Both interfaces should extend the GWT interface <literal>com.google.gwt.user.client.rpc.RemoteService</literal>:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public interface MyService extends RemoteService {
+ public String askIt(String question);
+}]]>
+</programlisting>
+ <para>
+ The asynchronous interface should be identical, except for an additional <literal>AsyncCallback</literal> parameter for each of the methods it declares:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public interface MyServiceAsync extends RemoteService {
+ public void askIt(String question, AsyncCallback callback);
+}]]>
+</programlisting>
+ <para>
+ The asynchronous interface (in this case, <literal>MyServiceAsync</literal>) is implemented by GWT, and should never be implemented directly.
+ </para>
+ <para>
+ The next step is to create a Seam component that implements the synchronous interface:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("org.jboss.seam.example.remoting.gwt.client.MyService")
public class ServiceImpl implements MyService {
- @WebRemote
- public String askIt(String question) {
+ @WebRemote
+ public String askIt(String question) {
- if (!validate(question)) {
- throw new IllegalStateException("Hey, this shouldn't happen, I checked on the client, " +
- "but its always good to double check.");
- }
- return "42. Its the real question that you seek now.";
- }
+ if (!validate(question)) {
+ throw new IllegalStateException("Hey, this shouldn't happen, " +
+ "I checked on the client, but " +
+ "it's always good to double check.");
+ }
+ return "42. Its the real question that you seek now.";
+ }
- public boolean validate(String q) {
- ValidationUtility util = new ValidationUtility();
- return util.isValid(q);
- }
-}]]></programlisting>
-
- <para>
- The name of the seam component <emphasis>must</emphasis> match the fully
- qualified name of the GWT client interface (as shown), or the seam
- resource servlet will not be able to find it when a client makes a GWT
- call. The methods that are to be made accessible via GWT also need to be
- annotated with the <literal>@WebRemote</literal> annotation.
- </para>
- </section>
-
- <section>
- <title>Hooking up a GWT widget to the Seam component</title>
-
- <para>
- The next step, is to write a method that returns the asynchronous interface to the component. This method
- can be located inside the widget class, and will be used by the widget to obtain a reference to the
- asynchronous client stub:
- </para>
-
- <programlisting role="JAVA"><![CDATA[private MyServiceAsync getService() {
- String endpointURL = GWT.getModuleBaseURL() + "seam/resource/gwt";
+ public boolean validate(String q) {
+ ValidationUtility util = new ValidationUtility();
+ return util.isValid(q);
+ }
+}]]>
+</programlisting>
+ <para>
+ The Seam component's name must match the fully-qualified name of the GWT client interface (as shown), or the Seam Resource Servlet will not be able to find it when a client makes a GWT call. Methods that GWT will make accessible must be annotated with <literal>@WebRemote</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Hooking up a GWT widget to the Seam component</title>
+ <para>
+ Next, write a method that returns the asynchronous interface to the component. This method can be located inside the widget class, and will be used by the widget to obtain a reference to the asynchronous client stub:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[private MyServiceAsync getService() {
+ String endpointURL = GWT.getModuleBaseURL() + "seam/resource/gwt";
- MyServiceAsync svc = (MyServiceAsync) GWT.create(MyService.class);
- ((ServiceDefTarget) svc).setServiceEntryPoint(endpointURL);
- return svc;
-}]]></programlisting>
+ MyServiceAsync svc = (MyServiceAsync) GWT.create(MyService.class);
+ ((ServiceDefTarget) svc).setServiceEntryPoint(endpointURL);
+ return svc;
+}]]>
+</programlisting>
+ <para>
+ Finally, write the widget code that invokes the method on the client stub. The following example creates a simple user interface with a label, text input, and a button:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public class AskQuestionWidget extends Composite {
+ private AbsolutePanel panel = new AbsolutePanel();
- <para>
- The final step is to write the widget code that invokes the method on the client stub. The following example
- creates a simple user interface with a label, text input and a button:
- </para>
+ public AskQuestionWidget() {
+ Label lbl = new Label("OK, what do you want to know?");
+ panel.add(lbl);
+ final TextBox box = new TextBox();
+ box.setText("What is the meaning of life?");
+ panel.add(box);
+ Button ok = new Button("Ask");
- <programlisting role="JAVA"><![CDATA[
-public class AskQuestionWidget extends Composite {
- private AbsolutePanel panel = new AbsolutePanel();
-
- public AskQuestionWidget() {
- Label lbl = new Label("OK, what do you want to know?");
- panel.add(lbl);
- final TextBox box = new TextBox();
- box.setText("What is the meaning of life?");
- panel.add(box);
- Button ok = new Button("Ask");
- ok.addClickListener(new ClickListener() {
- public void onClick(Widget w) {
- ValidationUtility valid = new ValidationUtility();
- if (!valid.isValid(box.getText())) {
- Window.alert("A question has to end with a '?'");
- } else {
- askServer(box.getText());
- }
- }
- });
- panel.add(ok);
+ ok.addClickListener(new ClickListener() {
+
+ public void onClick(Widget w) {
+ ValidationUtility valid = new ValidationUtility();
+ if (!valid.isValid(box.getText())) {
+ Window.alert("A question has to end with a '?'");
+ } else {
+ askServer(box.getText());
+ }
+ }
+ });
+ panel.add(ok);
- initWidget(panel);
- }
+ initWidget(panel);
+ }
- private void askServer(String text) {
- getService().askIt(text, new AsyncCallback() {
- public void onFailure(Throwable t) {
- Window.alert(t.getMessage());
- }
+ private void askServer(String text) {
+ getService().askIt(text, new AsyncCallback() {
+ public void onFailure(Throwable t) {
+ Window.alert(t.getMessage());
+ }
- public void onSuccess(Object data) {
- Window.alert((String) data);
- }
- });
- }
+ public void onSuccess(Object data) {
+ Window.alert((String) data);
+ }
+ });
+}
- ...]]></programlisting>
-
-
- <para>
- When clicked, the button invokes the <literal>askServer()</literal> method passing the contents of the input text (in this
- example, validation is also performed to ensure that the input is a valid question). The <literal>askServer()</literal>
- method acquires a reference to the asynchronous client stub (returned by the <literal>getService()</literal> method)
- and invokes the <literal>askIt()</literal> method. The result (or error message if the call fails) is shown in an alert window.
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/gwt-helloworld.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/gwt-helloworld.png" align="center"/>
- </imageobject>
- </mediaobject>
-
-
- <para>
- The complete code for this example can be found in the Seam distribution in the <literal>examples/remoting/gwt</literal>
- directory.
- </para>
- </section>
-
- <section>
- <title>GWT Ant Targets</title>
-
- <para>
- For deployment of GWT apps, there is a compile-to-Javascript step (which compacts and obfuscates the code). There is an
- ant utility which can be used instead of the command line or GUI utility that GWT provides. To use this, you will need
- to have the ant task jar in your ant classpath, as well as GWT downloaded (which you will need for hosted mode anyway).
- </para>
-
- <para>
- Then, in your ant file, place (near the top of your ant file):
- </para>
-
- <programlisting role="XML"><![CDATA[<taskdef uri="antlib:de.samaflost.gwttasks"
- resource="de/samaflost/gwttasks/antlib.xml"
- classpath="./lib/gwttasks.jar"/>
-
- <property file="build.properties"/>]]></programlisting>
-
- <para>
- Create a <literal>build.properties</literal> file, which has the contents:
- </para>
-
- <programlisting><![CDATA[gwt.home=/gwt_home_dir]]></programlisting>
-
- <para>
- This of course should point to the directory where GWT is installed. Then to use it, create a target:
- </para>
-
- <programlisting role="XML"><![CDATA[<!-- the following are are handy utilities for doing GWT development.
- To use GWT, you will of course need to download GWT seperately -->
- <target name="gwt-compile">
- <!-- in this case, we are "re homing" the gwt generated stuff, so in this case
- we can only have one GWT module - we are doing this deliberately to keep the URL short -->
- <delete>
- <fileset dir="view"/>
- </delete>
- <gwt:compile outDir="build/gwt"
- gwtHome="${gwt.home}"
- classBase="${gwt.module.name}"
- sourceclasspath="src"/>
- <copy todir="view">
- <fileset dir="build/gwt/${gwt.module.name}"/>
- </copy>
- </target>]]></programlisting>
-
- <para>
- This target when called will compile the GWT application, and copy it to the specified directory (which would be
- in the <literal>webapp</literal> part of your war - remember GWT generates HTML and Javascript artifacts). You
- never edit the resulting code that <literal>gwt-compile</literal> generates - you always edit in the GWT source
- directory.
- </para>
-
- <para>
- Remember that GWT comes with a hosted mode browser - you should be using that if you are developing with GWT. If you
- aren't using that, and are just compiling it each time, you aren't getting the most out of the toolkit (in fact, if
- you can't or won't use the hosted mode browser, I would go far as to say you should NOT be using GWT at all - it's
- that valuable!).
- </para>
-
- </section>
+...]]>
+</programlisting>
+ <para>
+ When clicked, this button invokes the <literal>askServer()</literal> method, passing the contents of the input text. In this example, it also validates that the input is a valid question. The <literal>askServer()</literal> method acquires a reference to the asynchronous client stub (returned by the <literal>getService()</literal> method) and invokes the <literal>askIt()</literal> method. The result (or error message, if the call fails) is shown in an alert window.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/gwt-helloworld.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/gwt-helloworld.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ The complete code for this example can be found in the Seam distribution in the <literal>examples/remoting/gwt</literal> directory.
+ </para>
+ </section>
+
+ <section>
+ <title>GWT Ant Targets</title>
+ <para>
+ To deploy GWT applications, you must also perform compilation to JavaScript. This compacts and obfuscates the code. You can use an Ant utility instead of the command line or GUI utility provided by GWT. To do so, you must have GWT downloaded, and the Ant task <filename>JAR</filename> in your Ant classpath.
+ </para>
+ <para>
+ Place the following near the top of your Ant file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<taskdef uri="antlib:de.samaflost.gwttasks"
+ resource="de/samaflost/gwttasks/antlib.xml"
+ classpath="./lib/gwttasks.jar"/>
+<property file="build.properties"/>]]>
+</programlisting>
+ <para>
+ Create a <filename>build.properties</filename> file containing:
+ </para>
+
+<programlisting><![CDATA[gwt.home=/gwt_home_dir]]>
+</programlisting>
+ <para>
+ This must point to the directory in which GWT is installed. Next, create a target:
+ </para>
+
+<programlisting role="XML"><![CDATA[<!-- the following are are handy utilities for doing GWT development.
+ To use GWT, you will of course need to download GWT seperately -->
+
+<target name="gwt-compile">
+ <!-- in this case, we are "re homing" the gwt generated stuff, so
+ in this case we can only have one GWT module - we are doing this
+ deliberately to keep the URL short -->
+ <delete>
+ <fileset dir="view"/>
+ </delete>
+ <gwt:compile outDir="build/gwt"
+ gwtHome="${gwt.home}"
+ classBase="${gwt.module.name}"
+ sourceclasspath="src"/>
+ <copy todir="view">
+ <fileset dir="build/gwt/${gwt.module.name}"/>
+ </copy>
+</target>]]>
+</programlisting>
+ <para>
+ When called, this target compiles the GWT application and copies it to the specified directory (likely in the <literal>webapp</literal> section of your WAR).
+ </para>
+ <note>
+ <para>
+ Never edit the code generated by <literal>gwt-compile</literal> — if you need to edit, do so in the GWT source directory.
+ </para>
+ </note>
+ <para>
+ We highly recommend using the hosted mode browser included in the GWT if you plan to develop applications with the GWT.
+ </para>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Hsearch.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Hsearch.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Hsearch.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,191 +1,189 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="search">
- <title>Hibernate Search</title>
-
- <section>
- <title>Introduction</title>
-
- <para>Full text search engines like Apache Lucene™ are a very powerful
- technology that bring full text and efficient queries to applications.
- Hibernate Search, which uses Apache Lucene under the covers, indexes your
- domain model with the addition of a few annotations, takes care of the
- database / index synchronization and returns regular managed objects that
- are matched by full text queries. Keep in mind, thought, that there are
- mismatches that arise when dealing with an object domain model over a text
- index (keeping the index up to date, mismatch between the index structure
- and the domain model, and querying mismatch). But the benefits of speed
- and efficiency far outweigh these limitations.</para>
-
- <para>Hibernate Search has been designed to integrate nicely and as
- naturally as possible with JPA and Hibernate. As a natural extension,
- JBoss Seam provides an Hibernate Search integration.</para>
-
- <para>Please refer to the <ulink
- url="http://www.hibernate.org/hib_docs/search/reference/en/html_single/">Hibernate
- Search documentation</ulink> for information specific to the Hibernate
- Search project.</para>
-
- </section>
-
- <section>
- <title>Configuration</title>
-
- <para>Hibernate Search is configured either in the
- <filename>META-INF/persistence.xml</filename> or
- <filename>hibernate.cfg.xml</filename> file.</para>
-
- <para>Hibernate Search configuration has sensible defaults for most
- configuration parameters. Here is a minimal persistence unit configuration
- to get started.</para>
-
- <programlisting role="XML"><![CDATA[<persistence-unit name="sample">
- <jta-data-source>java:/DefaultDS</jta-data-source>
- <properties>
- [...]
- <!-- use a file system based index -->
- <property name="hibernate.search.default.directory_provider"
- value="org.hibernate.search.store.FSDirectoryProvider"/>
- <!-- directory where the indexes will be stored -->
- <property name="hibernate.search.default.indexBase"
- value="/Users/prod/apps/dvdstore/dvdindexes"/>
- </properties>
-</persistence-unit>]]></programlisting>
-
- <note>
- <para>
- When using Hibernate Search 3.1.x more eventlisteners are needed, but
- these are registered automatically by Hibernate Annotations; refer
- to the Hibernate Search reference for configuring it without
- EntityManager and Annotations.</para>
- </note>
-
- <para>In addition to the configuration file, the following jars have to be
- deployed:</para>
-
- <itemizedlist>
- <listitem>
- <para>hibernate-search.jar</para>
- </listitem>
-
- <listitem>
- <para>hibernate-commons-annotations.jar</para>
- </listitem>
-
- <listitem>
- <para>lucene-core.jar</para>
- </listitem>
- </itemizedlist>
-
- <note>
- <para>If you deploy those in a EAR, don't forget to update
- <filename>application.xml</filename></para>
- </note>
- </section>
-
- <section>
- <title>Usage</title>
-
- <para>Hibernate Search uses annotations to map entities to a Lucene index,
- check the <ulink
- url="http://www.hibernate.org/hib_docs/search/reference/en/html_single/">reference
- documentation</ulink> for more informations.</para>
-
- <para>Hibernate Search is fully integrated with the API and semantic of
- JPA / Hibernate. Switching from a HQL or Criteria based query requires
- just a few lines of code. The main API the application interacts with is
- the <classname>FullTextSession</classname> API (subclass of Hibernate's
- <classname>Session</classname>).</para>
-
- <para>When Hibernate Search is present, JBoss Seam injects a
- <classname>FullTextSession</classname>.</para>
-
- <programlisting role="JAVA"><![CDATA[@Stateful
+<chapter id="search" >
+ <title>Hibernate Search</title>
+ <section>
+ <title>Introduction</title>
+ <para>
+ Full text search engines like <trademark>Apache</trademark> <trademark>Lucene</trademark> bring full text and efficient queries to applications. Hibernate Search, which makes use of Apache Lucene, can index your domain model with a few added annotations, handle database or index synchronization, and return regular managed objects that are matched by full text queries. There are some limitations to dealing with an object domain model over a text index — such as maintaining index accuracy, consistency between index structure and the domain model, and avoiding query mismatches — but these limitations are far outweighed by the advantages of speed and efficiency.
+ </para>
+ <para>
+ Hibernate Seach has been designed to integrate as naturally as possible with the Java Persistence API (JPA) and Hibernate. As a natural extension, JBoss Seam provides Hibernate Search integration.
+ </para>
+ <para>
+ Refer to the <ulink url="http://www.hibernate.org/hib_docs/search/reference/en/html_single/"> Hibernate Search documentation</ulink> for information specific to the Hibernate Search project.
+ </para>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+ <para>
+ Hibernate Search is configured either in the <filename>META-INF/persistence.xml</filename> or <filename>hibernate.cfg.xml</filename> file.
+ </para>
+ <para>
+ Hibernate Search configuration has sensible defaults for most configuration parameters. The following is an example of a minimal persistence unit configuration:
+ </para>
+
+<programlisting role="XML"><![CDATA[<persistence-unit name="sample">
+ <jta-data-source>java:/DefaultDS</jta-data-source>
+ <properties>
+ [...]
+ <!-- use a file system based index -->
+ <property name="hibernate.search.default.directory_provider"
+ value="org.hibernate.search.store.FSDirectoryProvider"/>
+ <!-- directory where the indexes will be stored -->
+ <property name="hibernate.search.default.indexBase"
+ value="/Users/prod/apps/dvdstore/dvdindexes"/>
+ </properties>
+</persistence-unit>]]>
+</programlisting>
+ <!--<para>
+ To target Hibernate Annotations or EntityManager 3.2.x (embedded into JBoss AS 4.2.x and later), you must also configure the appropriate event listeners.
+ </para>
+
+<programlisting role="XML"><![CDATA[<persistence-unit name="sample">
+ <jta-data-source>java:/DefaultDS</jta-data-source>
+ <properties>
+ [...]
+ # use a file system based index
+ <property name="hibernate.search.default.directory_provider"
+ value="org.hibernate.search.store.FSDirectoryProvider"/>
+ # directory where the indexes will be stored
+ <property name="hibernate.search.default.indexBase"
+ value="/Users/prod/apps/dvdstore/dvdindexes"/>
+ <property name="hibernate.ejb.event.post-insert"
+ value="org.hibernate.search.event.FullTextIndexEventListener"/>
+ <property name="hibernate.ejb.event.post-update"
+ value="org.hibernate.search.event.FullTextIndexEventListener"/>
+ <property name="hibernate.ejb.event.post-delete"
+ value="org.hibernate.search.event.FullTextIndexEventListener"/>
+ </properties>
+</persistence-unit>]]>
+</programlisting>-->
+ <note>
+<!-- <para>
+ This step is no longer necessary if Hibernate Annotation or EntityManager 3.3.x are used.
+ </para>--> <para>When using Hibernate Search 3.1.x, more event listeners are required, but these are registered automatically by Hibernate Annotations. Refer to the <citetitle>Hibernate Search Reference Guide</citetitle> to learn to configure event listeners without using Hibernate EntityManager and Hibernate Annotations.</para>
+ </note>
+ <para>
+ The following <filename>JAR</filename>s must be deployed alongside the configuration file:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <filename>hibernate-search.jar</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>hibernate-commons-annotations.jar</filename>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <filename>lucene-core.jar</filename>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+ If you deploy these in an <filename>EAR</filename>, remember to update <filename>application.xml</filename>.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>Usage</title>
+ <para>
+ Hibernate Search uses annotations to map entities to a Lucene index. Check the <ulink url="http://www.hibernate.org/hib_docs/search/reference/en/html_single/"> reference documentation</ulink> for more information.
+ </para>
+ <para>
+ Hibernate Search is completely integrated with the API, and semantic of JPA and Hibernate. Switching from a HQL- or Criteria-based query requires little code. The application interacts primarily with the <classname>FullTextSession</classname> API, which is a subclass of Hibernate's <classname>Session</classname>.
+ </para>
+ <para>
+ When Hibernate Search is present, JBoss Seam injects a <classname>FullTextSession</classname>:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateful
@Name("search")
public class FullTextSearchAction implements FullTextSearch, Serializable {
- @In FullTextSession session;
+ @In FullTextSession session;
- public void search(String searchString) {
- org.apache.lucene.search.Query luceneQuery = getLuceneQuery();
- org.hibernate.Query query session.createFullTextQuery(luceneQuery, Product.class);
- searchResults = query
- .setMaxResults(pageSize + 1)
- .setFirstResult(pageSize * currentPage)
- .list();
- }
- [...]
-}]]></programlisting>
-
- <note>
- <para><classname>FullTextSession</classname> extends
- <classname>org.hibernate.Session</classname> so that it can be used as a
- regular Hibernate Session</para>
- </note>
-
- <para>If the Java Persistence API is used, a smoother integration is
- proposed.</para>
-
- <programlisting role="JAVA"><![CDATA[@Stateful
+ public void search(String searchString) {
+ org.apache.lucene.search.Query luceneQuery = getLuceneQuery();
+ org.hibernate.Query query session.createFullTextQuery(luceneQuery,
+ Product.class);
+ searchResults = query
+ .setMaxResults(pageSize + 1)
+ .setFirstResult(pageSize * currentPage)
+ .list();
+ }
+ [...]
+}]]>
+</programlisting>
+ <note>
+ <para>
+ Here, <classname>FullTextSession</classname> extends <classname>org.hibernate.Session</classname> so that it can be used as a regular Hibernate Session.
+ </para>
+ </note>
+ <para>
+ A smoother integration is proposed if the JPA is used:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateful
+ at Name("search")
+public class FullTextSearchAction implements FullTextSearch, Serializable {
+ @In FullTextEntityManager em;
+ public void search(String searchString) {
+ org.apache.lucene.search.Query luceneQuery = getLuceneQuery();
+ javax.persistence.Query query = em.createFullTextQuery(luceneQuery,
+ Product.class);
+ searchResults = query
+ .setMaxResults(pageSize + 1)
+ .setFirstResult(pageSize * currentPage)
+ .getResultList();
+ }
+ [...]
+}]]>
+</programlisting>
+ <para>
+ Here, a <classname>FulltextEntityManager</classname> is injected where Hibernate Search is present. <classname>FullTextEntityManager</classname> extends <classname>EntityManager</classname> with search specific methods, the same way <classname>FullTextSession</classname> extends <classname>Session</classname>.
+ </para>
+ <para>
+ When an EJB 3.0 Session or Message Driven Bean injection is used (that is, where injection uses the <literal>@PersistenceContext</literal> annotation), the <classname>EntityManager</classname> interface cannot be replaced by using the <classname>FullTextEntityManager</classname> interface in the declaration statement. However, the implementation injected will be a <classname>FullTextEntityManager</classname> implementation, which allows downcasting.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateful
@Name("search")
public class FullTextSearchAction implements FullTextSearch, Serializable {
-
- @In FullTextEntityManager em;
-
- public void search(String searchString) {
- org.apache.lucene.search.Query luceneQuery = getLuceneQuery();
- javax.persistence.Query query = em.createFullTextQuery(luceneQuery, Product.class);
- searchResults = query
- .setMaxResults(pageSize + 1)
- .setFirstResult(pageSize * currentPage)
- .getResultList();
- }
- [...]
-}]]></programlisting>
-
- <para>When Hibernate Search is present, a
- <classname>FulltextEntityManager</classname> is injected.
- <classname>FullTextEntityManager</classname> extends
- <classname>EntityManager</classname> with search specific methods, the
- same way <classname>FullTextSession</classname> extends
- <classname>Session</classname>.</para>
-
- <para>When an EJB 3.0 Session or Message Driven Bean injection is used (i.e.
- via the @PersistenceContext annotation), it is not possible to replace the
- <classname>EntityManager</classname> interface by the
- <classname>FullTextEntityManager</classname> interface in the declaration
- statement. However, the implementation injected will be a
- <classname>FullTextEntityManager</classname> implementation: downcasting
- is then possible.</para>
-
- <programlisting role="JAVA"><![CDATA[@Stateful
- at Name("search")
-public class FullTextSearchAction implements FullTextSearch, Serializable {
- @PersistenceContext EntityManager em;
+ @PersistenceContext EntityManager em;
- public void search(String searchString) {
- org.apache.lucene.search.Query luceneQuery = getLuceneQuery();
- FullTextEntityManager ftEm = (FullTextEntityManager) em;
- javax.persistence.Query query = ftEm.createFullTextQuery(luceneQuery, Product.class);
- searchResults = query
- .setMaxResults(pageSize + 1)
- .setFirstResult(pageSize * currentPage)
- .getResultList();
- }
- [...]
-}]]></programlisting>
-
- <para></para>
-
- <caution>
- <para>For people accustomed to Hibernate Search out of Seam, note that
- using <methodname>Search.getFullTextSession</methodname> is not
- necessary.</para>
- </caution>
-
- <para>Check the DVDStore or the blog examples of the JBoss Seam
- distribution for a concrete use of Hibernate Search.</para>
- </section>
+ public void search(String searchString) {
+ org.apache.lucene.search.Query luceneQuery = getLuceneQuery();
+ FullTextEntityManager ftEm = (FullTextEntityManager) em;
+ javax.persistence.Query query =
+ ftEm.createFullTextQuery(luceneQuery, Product.class);
+ searchResults = query
+ .setMaxResults(pageSize + 1)
+ .setFirstResult(pageSize * currentPage)
+ .getResultList();
+ }
+ [...]
+}]]>
+</programlisting>
+ <note>
+ <para>
+ If you are accustomed to using Hibernate Search outside Seam, remember that you do not need to use <methodname>Search.createFullTextSession</methodname> when Hibernate Search is integrated with Seam.
+ </para>
+ </note>
+ <para>
+ For a working example of Hibernate Search, check the DVDStore or Blog examples in the JBoss Seam distribution.
+ </para>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/I18n.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/I18n.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/I18n.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,427 +1,337 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
-"http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<chapter id="i18n">
- <title>Internationalization, localization and themes</title>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- <para>
- Seam makes it easy to build internationalized applications. First, let's
- walk through all the stages needed to internationalize and localize your
- app. Then we'll take a look at the components Seam bundles.
- </para>
-
- <section>
- <title>Internationalizing your app</title>
-
- <para>
- A JEE application consists of many components and all of them must be
- configured properly for your application to be localized.
- </para>
-
- <note>
- <para> Note that all i18n features in Seam work only in JSF context.</para>
- </note>
-
- <para>
- Starting at the bottom, the first step is to ensure that your database
- server and client is using the correct character encoding for your
- locale. Normally you'll want to use UTF-8. How to do this is outside
- the scope of this tutorial.
- </para>
-
- <section>
- <title>Application server configuration</title>
-
- <para>
- To ensure that the application server receives the request
- parameters in the correct encoding from client requests you have to
- configure the tomcat connector. Add
- the <literal>URIEncoding="UTF-8"</literal> attribute to the
- connector configuration in
- <literal>${JBOSS_HOME}/server/(default)/deploy/jboss-web.deployer/server.xml</literal>:
- </para>
-
- <programlisting role="XML"><Connector port="8080" URIEncoding="UTF-8"/></programlisting>
-
- <para>
- There is alternative which is probably better. You can tell JBoss AS
- that the encoding for the request parameters will be taken from the
- request:
- </para>
-
- <programlisting role="XML"><Connector port="8080" useBodyEncodingForURI="true"/></programlisting>
- </section>
-
- <section>
- <title>Translated application strings</title>
-
- <para>
- You'll also need localized strings for all the <emphasis>messages</emphasis>
- in your application (for example field labels on your views). First
- you need to ensure that your resource bundle is encoded using the
- desired character encoding. By default ASCII is used. Although ASCII
- is enough for many languages, it doesn't provide characters for all
- languages.
- </para>
-
- <para>
- Resource bundles must be created in ASCII, or use Unicode escape
- codes to represent Unicode characters. Since you don't compile a
- property file to byte code, there is no way to tell the JVM which
- character set to use. So you must use either ASCII characters or
- escape characters not in the ASCII character set.
- You can represent a Unicode character in any Java file using \uXXXX,
- where XXXX is the hexidecimal representation of the character.
- </para>
-
- <para>
- You can write your translation of labels
- (<xref linkend="labels"/>) to your messages resource
- bundle in the native encoding and then convert the content of the
- file into the escaped format through the tool <literal>native2ascii</literal>
- provided in the JDK. This tool will convert a file written in your
- native encoding to one that represents non-ASCII characters as
- Unicode escape sequences.
- </para>
-
- <para>
- Usage of this tool is described
- <ulink url="http://java.sun.com/j2se/1.5.0/docs/tooldocs/index.html#intl">here for Java 5</ulink>
- or
- <ulink url="http://java.sun.com/javase/6/docs/technotes/tools/#intl">here for Java 6</ulink>.
- For example, to convert a file from UTF-8:
- </para>
-
- <programlisting><prompt>$ native2ascii -encoding UTF-8 messages_cs.properties > messages_cs_escaped.properties</prompt></programlisting>
-
- </section>
-
- <section>
- <title>Other encoding settings</title>
-
- <para>
- We need to make sure that the view displays your localized data and
- messages using the correct character set and also any data submitted
- uses the correct encoding.
- </para>
-
- <para>
- To set the display character encoding, you need to use the
- <literal><f:view locale="cs_CZ"/></literal> tag (here we tell
- JSF to use the Czech locale). You may want to change the encoding of
- the xml document itself if you want to embed localized strings in the
- xml. To do this alter the encoding attribute in xml declaration
- <literal><?xml version="1.0" encoding="UTF-8"?></literal> as
- required.
- </para>
-
- <para>
- Also JSF/Facelets should submit any requests using the specified
- character encoding, but to make sure any requests that don't specify
- an encoding you can force the request encoding using a servlet
- filter. Configure this in <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<web:character-encoding-filter encoding="UTF-8"
- override-client="true"
- url-pattern="*.seam" />]]></programlisting>
- </section>
- </section>
-
- <section id="locales">
- <title>Locales</title>
-
- <para>Each user login session has an associated instance of
- <literal>java.util.Locale</literal> (available to the application as a
- component named <literal>locale</literal>). Under normal circumstances,
- you won't need to do any special configuration to set the locale. Seam
- just delegates to JSF to determine the active locale:</para>
-
- <itemizedlist>
- <listitem>
- <para>If there is a locale associated with the HTTP request (the
- browser locale), and that locale is in the list of supported locales
- from <literal>faces-config.xml</literal>, use that locale for the rest
- of the session.</para>
- </listitem>
-
- <listitem>
- <para>Otherwise, if a default locale was specified in the
- <literal>faces-config.xml</literal>, use that locale for the rest of
- the session.</para>
- </listitem>
-
- <listitem>
- <para>Otherwise, use the default locale of the server.</para>
- </listitem>
- </itemizedlist>
-
- <para>It is <emphasis>possible</emphasis> to set the locale manually via
- the Seam configuration properties <literal>
- org.jboss.seam.international.localeSelector.language</literal>, <literal>
- org.jboss.seam.international.localeSelector.country</literal> and
- <literal> org.jboss.seam.international.localeSelector.variant</literal>,
- but we can't think of any good reason to ever do this.</para>
-
- <para>It is, however, useful to allow the user to set the locale manually
- via the application user interface. Seam provides built-in functionality
- for overriding the locale determined by the algorithm above. All you have
- to do is add the following fragment to a form in your JSP or Facelets
- page:</para>
-
- <programlisting role="XHTML"><h:selectOneMenu value="#{localeSelector.language}">
- <f:selectItem itemLabel="English" itemValue="en"/>
- <f:selectItem itemLabel="Deutsch" itemValue="de"/>
- <f:selectItem itemLabel="Francais" itemValue="fr"/>
-</h:selectOneMenu>
-<h:commandButton action="#{localeSelector.select}"
- value="#{messages['ChangeLanguage']}"/></programlisting>
-
- <para>Or, if you want a list of all supported locales from <literal>
- faces-config.xml</literal>, just use:</para>
-
- <programlisting role="XHTML"><h:selectOneMenu value="#{localeSelector.localeString}">
- <f:selectItems value="#{localeSelector.supportedLocales}"/>
-</h:selectOneMenu>
-<h:commandButton action="#{localeSelector.select}"
- value="#{messages['ChangeLanguage']}"/></programlisting>
-
- <para>When the user selects an item from the drop-down, then clicks the
- command button, the Seam and JSF locales will be overridden for the rest of the
- session.</para>
-
- <para>The brings us to the question of where the supported locales are
- defined. Typically, you provide a list of locales for which you have
- matching resource bundles in the <literal><locale-config></literal>
- element of the JSF configuration file (/META-INF/faces-config.xml). However,
- you have learned to appreciate that Seam's component configuration
- mechanism is more powerful than what is provided in Java EE. For that
- reason, you can configure the supported locales, and the default locale of
- the server, using the built-in component named
- <literal>org.jboss.seam.international.localeConfig</literal>. To use it,
- you first declare an XML namespace for Seam's international package in the
- Seam component descriptor. You then define the default locale and supported
- locales as follows:</para>
-
- <programlisting role="XML"><international:locale-config default-locale="fr_CA" supported-locales="en fr_CA fr_FR"/></programlisting>
-
- <para>Naturally, if you pronounce that you support a locale, you better
- provide a resource bundle to match it! Up next, you'll learn how to define
- the language-specific labels.</para>
- </section>
-
- <section id="labels" />
- <title>Labels</title>
-
- <para>JSF supports internationalization of user interface labels and
- descriptive text via the use of <literal><f:loadBundle /></literal>.
- You can use this approach in Seam applications. Alternatively, you can
- take advantage of the Seam <literal> messages</literal> component to
- display templated labels with embedded EL expressions.</para>
-
- <section>
- <title>Defining labels</title>
-
- <para>Seam provides a <literal>java.util.ResourceBundle</literal>
- (available to the application as a <literal>
- org.jboss.seam.core.resourceBundle</literal>). You'll need to make your
- internationalized labels available via this special resource bundle. By
- default, the resource bundle used by Seam is named
- <literal>messages</literal> and so you'll need to define your labels in
- files named <literal> messages.properties</literal>, <literal>
- messages_en.properties</literal>, <literal>
- messages_en_AU.properties</literal>, etc. These files usually belong in
- the <literal>WEB-INF/classes</literal> directory.</para>
-
- <para>So, in <literal>messages_en.properties</literal>:</para>
-
- <programlisting>Hello=Hello</programlisting>
-
- <para>And in <literal>messages_en_AU.properties</literal>:</para>
-
- <programlisting>Hello=G'day</programlisting>
-
- <para>You can select a different name for the resource bundle by setting
- the Seam configuration property named <literal>
- org.jboss.seam.core.resourceLoader.bundleNames</literal>. You can even
- specify a list of resource bundle names to be searched (depth first) for
- messages.</para>
-
- <programlisting role="XML"><core:resource-loader>
- <core:bundle-names>
- <value>mycompany_messages</value>
- <value>standard_messages</value>
- </core:bundle-names>
-</core:resource-loader></programlisting>
-
- <para>If you want to define a message just for a particular page, you
- can specify it in a resource bundle with the same name as the JSF view
- id, with the leading <literal>/</literal> and trailing file extension
- removed. So we could put our message in <literal>
- welcome/hello_en.properties</literal> if we only needed to display the
- message on <literal> /welcome/hello.jsp</literal>.</para>
-
- <para>You can even specify an explicit bundle name in <literal>
- pages.xml</literal>:</para>
-
- <programlisting role="XML"><page view-id="/welcome/hello.jsp" bundle="HelloMessages"/></programlisting>
-
- <para>Then we could use messages defined in <literal>
- HelloMessages.properties</literal> on <literal>
- /welcome/hello.jsp</literal>.</para>
- </section>
-
- <section>
- <title>Displaying labels</title>
-
- <para>If you define your labels using the Seam resource bundle, you'll
- be able to use them without having to type <literal> <f:loadBundle
- ... /></literal> on every page. Instead, you can simply type:</para>
-
- <programlisting role="XHTML"><h:outputText value="#{messages['Hello']}"/></programlisting>
-
- <para>or:</para>
-
- <programlisting role="XHTML"><h:outputText value="#{messages.Hello}"/></programlisting>
-
- <para>Even better, the messages themselves may contain EL
- expressions:</para>
-
- <programlisting>Hello=Hello, #{user.firstName} #{user.lastName}</programlisting>
-
- <programlisting>Hello=G'day, #{user.firstName}</programlisting>
-
- <para>You can even use the messages in your code:</para>
-
- <programlisting role="JAVA">@In private Map<String, String> messages;</programlisting>
-
- <programlisting role="JAVA">@In("#{messages['Hello']}") private String helloMessage;</programlisting>
- </section>
-
- <section>
- <title>Faces messages</title>
-
- <para>The <literal>facesMessages</literal> component is a
- super-convenient way to display success or failure messages to the user.
- The functionality we just described also works for faces
- messages:</para>
-
- <programlisting role="JAVA">@Name("hello")
- at Stateless
-public class HelloBean implements Hello {
- @In FacesMessages facesMessages;
-
- public String sayIt() {
- facesMessages.addFromResourceBundle("Hello");
- }
-}</programlisting>
-
- <para>This will display <literal>Hello, Gavin King</literal> or
- <literal>G'day, Gavin</literal>, depending upon the user's
- locale.</para>
- </section>
-
- <section>
- <title>Timezones</title>
-
- <para>There is also a session-scoped instance of <literal>
- java.util.Timezone</literal>, named <literal>
- org.jboss.seam.international.timezone</literal>, and a Seam component for
- changing the timezone named <literal>
- org.jboss.seam.international.timezoneSelector</literal>. By default, the
- timezone is the default timezone of the server. Unfortunately, the JSF
- specification says that all dates and times should be assumed to be UTC,
- and displayed as UTC, unless a timezone is explicitly specified using
- <literal> <f:convertDateTime></literal>. This is an extremely
- inconvenient default behavior.</para>
-
- <para>Seam overrides this behavior, and defaults all dates and times to
- the Seam timezone. In addition, Seam provides the <literal>
- <s:convertDateTime></literal> tag which always performs conversions
- in the Seam timezone.</para>
-
- <para>Seam also provides a default date converter to convert a string value
- to a date. This saves you from having to specify a converter on input fields
- that are simply capturing a date. The pattern is selected according the
- the user's locale and the time zone is selected as described above.</para>
- </section>
-
- <section>
- <title>Themes</title>
-
- <para>Seam applications are also very easily skinnable. The theme API is
- very similar to the localization API, but of course these two concerns are
- orthogonal, and some applications support both localization and
- themes.</para>
-
- <para>First, configure the set of supported themes:</para>
-
- <programlisting role="XML"><theme:theme-selector cookie-enabled="true">
- <theme:available-themes>
- <value>default</value>
- <value>accessible</value>
- <value>printable</value>
- </theme:available-themes>
-</theme:theme-selector></programlisting>
-
- <para>Note that the first theme listed is the default theme.</para>
-
- <para>Themes are defined in a properties file with the same name as the
- theme. For example, the <literal>default</literal> theme is defined as a
- set of entries in <literal> default.properties</literal>. For example,
- <literal> default.properties</literal> might define:</para>
-
- <programlisting>css ../screen.css
-template /template.xhtml</programlisting>
-
- <para>Usually the entries in a theme resource bundle will be paths to CSS
- styles or images and names of facelets templates (unlike localization
- resource bundles which are usually text).</para>
-
- <para>Now we can use these entries in our JSP or facelets pages. For
- example, to theme the stylesheet in a facelets page:</para>
-
- <programlisting role="XHTML"><link href="#{theme.css}" rel="stylesheet" type="text/css" /></programlisting>
-
- <para>Or, when the page definition resides in a subdirectory:</para>
-
- <programlisting role="XHTML"><link href="#{facesContext.externalContext.requestContextPath}#{theme.css}"
- rel="stylesheet" type="text/css" /></programlisting>
-
- <para>Most powerfully, facelets lets us theme the template used by a
- <literal><ui:composition></literal>:</para>
-
- <programlisting role="XHTML"><ui:composition xmlns="http://www.w3.org/1999/xhtml"
+<chapter id="i18n" >
+ <title>Internationalization, localization and themes</title>
+ <para>
+ There are several stages required to internationalize and localize your application.
+ </para>
+ <note>
+ <para>Internationalization features are available only in the JSF context.</para>
+ </note>
+ <section>
+ <title>Internationalizing your application</title>
+ <para>
+ A Java EE 5 application involves many components, all of which must be configured properly to localize your application.
+ </para>
+ <para>
+ Before you begin, ensure that your database server and client use the correct character encoding for your locale. Normally, you will want UTF-8 encoding. (Setting the correct encoding falls outside the scope of this tutorial.)
+ </para>
+ <section>
+ <title>Application server configuration</title>
+ <para>
+ You will need to configure the Tomcat connector to ensure that the application server receives the request parameters from client requests in the correct encoding. Add the <literal>URIEncoding="UTF-8"</literal> attribute to the connector configuration in <filename>$JBOSS_HOME/server/$PROFILE/deploy/jboss-web.deployer/server.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<Connector port="8080" URIEncoding="UTF-8"/>]]>
+</programlisting>
+ <para>
+ Alternatively, you can tell JBoss AS that the correct encoding for the request parameters will be taken from the request:
+ </para>
+
+<programlisting role="XML"><![CDATA[<Connector port="8080" useBodyEncodingForURI="true"/>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Translated application strings</title>
+ <para>
+ You will also need localized strings for all of the <emphasis>messages</emphasis> in your application (for example, field labels on your views). First, ensure that your resource bundle is encoded with the desired character encoding. ASCII is used by default. Although ASCII is enough for many languages, it does not provide characters for all languages.
+ </para>
+ <para>
+ Resource bundles must either be created in ASCII, or use Unicode escape codes to represent Unicode characters. Since you do not compile a property file to byte code, there is no way to tell JVM which character set to use. Therefore, you must use either ASCII characters or escape characters not in the ASCII character set. You can represent a Unicode character in any Java file with <literal>\uXXXX</literal>, where <replaceable>XXXX</replaceable> is the hexadecimal representation of the character.
+ </para>
+ <para>
+ You can write your translation of labels (<xref linkend="labels" />) to your message resource bundle in the native coding. The <literal>native2ascii</literal> tool provided in the JDK lets you convert the contents of a file written in your native encoding into one that represents non-ASCII characters as Unicode escape sequences.
+ </para>
+ <para>
+ Usage of this tool is described <ulink url="http://java.sun.com/j2se/1.5.0/docs/tooldocs/index.html#intl">here for Java 5</ulink> or <ulink url="http://java.sun.com/javase/6/docs/technotes/tools/#intl">here for Java 6</ulink>. For example, to convert a file from UTF-8:
+ </para>
+
+<programlisting><prompt>
+$ native2ascii -encoding UTF-8 messages_cs.properties > messages_cs_escaped.properties</prompt>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Other encoding settings</title>
+ <para>
+ We need to make sure that the view displays your localized data and messages in the correct character set, and that any data submitted uses the correct encoding.
+ </para>
+ <para>
+ Use the <literal><![CDATA[<f:view locale="cs_CZ"/>]]></literal> tag to set the display character encoding. (Note that this <literal>locale</literal> value sets JSF to use the Czech locale.) If you want to embed localized strings in the XML, you may want to change the XML document's encoding. To do so, alter the <literal>encoding</literal> attribute value in the XML declaration <literal><![CDATA[<?xml version="1.0" encoding="UTF-8"?>]]></literal>.
+ </para>
+ <para>
+ JSF/Facelets should submit any requests with the specified character encoding, but to ensure that requests that do not specify an encoding are submitted, you can force the request encoding using a servlet filter. Configure this in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<web:character-encoding-filter encoding="UTF-8" override-client="true"
+ url-pattern="*.seam" />]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section id="locales">
+ <title>Locales</title>
+ <para>
+ Each user login session has an associated instance of <literal>java.util.Locale</literal>, which is available to the application as a component named <literal>locale</literal>. Under normal circumstances, setting the locale requires no special configuration. Seam delegates to JSF to determine the active locale as follows:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ If a locale is associated with the HTTP request (the browser locale), and that locale is in the list of supported locales from <filename>faces-config.xml</filename>, use that locale for the rest of the session.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Otherwise, if a default locale was specified in the <filename>faces-config.xml</filename>, use that locale for the rest of the session.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Otherwise, use the default locale of the server.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ You <emphasis>can</emphasis> set the locale manually through the Seam configuration properties <literal>org.jboss.seam.international.localeSelector.language</literal>, <literal>org.jboss.seam.international.localeSelector.country</literal> and <literal>org.jboss.seam.international.localeSelector.variant</literal>, but there is no good reason to use this method over those described above.
+ </para>
+ <para>
+ It is useful to allow the user to set the locale manually via the application user interface. Seam provides built-in functionality to override the locale determined by the default algorithm. Do this by adding the following fragment to a form in your JSP or Facelets page:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{localeSelector.language}">
+ <f:selectItem itemLabel="English" itemValue="en"/>
+ <f:selectItem itemLabel="Deutsch" itemValue="de"/>
+ <f:selectItem itemLabel="Francais" itemValue="fr"/>
+</h:selectOneMenu>
+<h:commandButton action="#{localeSelector.select}"
+ value="#{messages['ChangeLanguage']}"/>]]>
+</programlisting>
+ <para>
+ Or, if you want a list of all supported locales from <filename>faces-config.xml</filename>, use:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{localeSelector.localeString}">
+ <f:selectItems value="#{localeSelector.supportedLocales}"/>
+</h:selectOneMenu>
+<h:commandButton action="#{localeSelector.select}"
+ value="#{messages['ChangeLanguage']}"/>]]>
+</programlisting>
+ <para>
+ When the user selects an item from the drop-down, then clicks the command button, the Seam and JSF locales will be overridden for the rest of the session.
+ </para>
+ <para>
+ You can configure the supported locales and the default locale of the server with the built-in <literal>org.jboss.seam.international.localeConfig</literal> component. First, declare an XML namespace for Seam's international package in the Seam component descriptor. Then, define the default locale and supported locales as follows:
+ </para>
+
+<programlisting role="XML"><![CDATA[<international:locale-config default-locale="fr_CA"
+ supported-locales="en fr_CA fr_FR"/>]]>
+</programlisting>
+ <para>
+ Remember that supported locales must have matching resource bundles. Next, define your language-specific labels.
+ </para>
+ </section>
+
+ <section id="labels">
+ <title>Labels</title>
+ <para>
+ JSF supports the internationalization of user interface labels and descriptive text with the <literal><![CDATA[<f:loadBundle />]]></literal>. In Seam applications, you can either take this approach, or use the Seam <literal> messages</literal> component to display templated labels with embedded EL expressions.
+ </para>
+ <section>
+ <title>Defining labels</title>
+ <para>
+ Make your internationalized labels available with Seam's <literal>java.util.ResourceBundle</literal>, available to the application as a <literal>org.jboss.seam.core.resourceBundle</literal>. By default, Seam uses a resource bundle named <literal>messages</literal>, so you will need to define your labels in files named <filename> messages.properties</filename>, <filename>messages_en.properties</filename>, <filename>messages_en_AU.properties</filename>, etc. These files usually belong in the <literal>WEB-INF/classes</literal> directory.
+ </para>
+ <para>
+ So, in <filename>messages_en.properties</filename>:
+ </para>
+
+<programlisting>Hello=Hello
+</programlisting>
+ <para>
+ And in <filename>messages_en_AU.properties</filename>:
+ </para>
+
+<programlisting>Hello=G'day
+</programlisting>
+ <para>
+ You can select a different name for the resource bundle by setting the Seam configuration property named <literal>org.jboss.seam.core.resourceLoader.bundleNames</literal>. You can even specify a list of resource bundle names to be searched (depth first) for messages.
+ </para>
+
+<programlisting role="XML"><![CDATA[<core:resource-loader>
+ <core:bundle-names>
+ <value>mycompany_messages</value>
+ <value>standard_messages</value>
+ </core:bundle-names>
+</core:resource-loader>]]>
+</programlisting>
+ <para>
+ To define a message for one particular page, specify it in a resource bundle with the same name as the JSF view ID, with the leading <literal>/</literal> and trailing file extension removed. So, we could put our message in <filename>welcome/hello_en.properties</filename> if we only needed to display the message on <filename> /welcome/hello.jsp</filename>.
+ </para>
+ <para>
+ You can even specify an explicit bundle name in <filename> pages.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/welcome/hello.jsp" bundle="HelloMessages"/>]]>
+</programlisting>
+ <para>
+ Then we could use messages defined in <filename>HelloMessages.properties</filename> on <filename>/welcome/hello.jsp</filename>.
+ </para>
+ </section>
+
+ <section>
+ <title>Displaying labels</title>
+ <para>
+ If you define your labels with the Seam resource bundle, you can use them without having to type <literal><![CDATA[<f:loadBundle... />]]></literal> on each page. Instead, you can type:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:outputText value="#{messages['Hello']}"/>]]>
+</programlisting>
+ <para>
+ or:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:outputText value="#{messages.Hello}"/>]]>
+</programlisting>
+ <para>
+ Even better, the messages themselves may contain EL expressions:
+ </para>
+
+<programlisting>Hello=Hello, #{user.firstName} #{user.lastName}
+</programlisting>
+
+<programlisting>Hello=G'day, #{user.firstName}
+</programlisting>
+ <para>
+ You can even use the messages in your code:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In private Map<String, String> messages;]]>
+</programlisting>
+
+<programlisting role="JAVA"><![CDATA[@In("#{messages['Hello']}") private String helloMessage;]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Faces messages</title>
+ <para>
+ The <literal>facesMessages</literal> component is a convenient way to display success or failure messages to the user. The functionality we just described also works for Faces messages:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("hello")
+ at Stateless
+public class HelloBean implements Hello {
+ @In FacesMessages facesMessages;
+ public String sayIt() {
+ facesMessages.addFromResourceBundle("Hello");
+ }
+}]]>
+</programlisting>
+ <para>
+ This will display <literal>Hello, Gavin King</literal> or <literal>G'day, Gavin</literal>, depending upon the user's locale.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Timezones</title>
+ <para>
+ There is also a session-scoped instance of <literal>java.util.Timezone</literal>, named <literal>org.jboss.seam.international.timezone</literal>, and a Seam component for changing the timezone named <literal>org.jboss.seam.international.timezoneSelector</literal>. By default, the timezone is the default timezone of the server. Unfortunately, the JSF specification assumes all dates and times are UTC, and displayed as UTC, unless a different timezone is explicitly specified with <literal><![CDATA[<f:convertDateTime>]]></literal>.
+ </para>
+ <para>
+ Seam overrides this behavior, and defaults all dates and times to the Seam timezone. In addition, Seam provides the <literal><![CDATA[<s:convertDateTime>]]></literal> tag, which always performs conversions in the Seam timezone.
+ </para>
+ <para>
+ Seam also provides a default date converter to convert a string value to a date. This saves you from having to specify a converter on input fields that capture dates. The pattern is selected according to the user's locale and the time zone is selected as described above.
+ </para>
+ </section>
+
+ <section>
+ <title>Themes</title>
+ <para>
+ Seam applications are also very easily skinnable. The theme API is very similar to the localization API, but of course these two concerns are orthogonal, and some applications support both localization and themes.
+ </para>
+ <para>
+ First, configure the set of supported themes:
+ </para>
+
+<programlisting role="XML"><![CDATA[<theme:theme-selector cookie-enabled="true">
+ <theme:available-themes>
+ <value>default</value>
+ <value>accessible</value>
+ <value>printable</value>
+ </theme:available-themes>
+</theme:theme-selector>]]>
+</programlisting>
+ <para>
+ The first theme listed is the default theme.
+ </para>
+ <para>
+ Themes are defined in a properties file with the same name as the theme. For example, the <literal>default</literal> theme is defined as a set of entries in <filename> default.properties</filename>, which might define:
+ </para>
+
+<programlisting>
+css ../screen.css template /template.xhtml
+</programlisting>
+ <para>
+ The entries in a theme resource bundle are usually paths to CSS styles or images and names of Facelets templates (unlike localization resource bundles which are usually text).
+ </para>
+ <para>
+ Now we can use these entries in our JSP or Facelets pages. For example, to theme the stylesheet in a Facelets page:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<link href="#{theme.css}" rel="stylesheet" type="text/css" />]]>
+</programlisting>
+ <para>
+ Or, where the page definition resides in a subdirectory:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<link href="#{facesContext.externalContext.requestContextPath}#{theme.css}"
+ rel="stylesheet" type="text/css" />]]>
+</programlisting>
+ <para>
+ Most powerfully, Facelets lets us theme the template used by a <literal><![CDATA[<ui:composition>]]></literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<ui:composition xmlns="http://www.w3.org/1999/xhtml"
xmlns:ui="http://java.sun.com/jsf/facelets"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core"
- template="#{theme.template}"></programlisting>
+ template="#{theme.template}">]]>
+</programlisting>
+ <para>
+ Just like the locale selector, there is a built-in theme selector to allow the user to freely switch themes:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:selectOneMenu value="#{themeSelector.theme}">
+ <f:selectItems value="#{themeSelector.themes}"/>
+</h:selectOneMenu>
+<h:commandButton action="#{themeSelector.select}" value="Select Theme"/>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Persisting locale and theme preferences via cookies</title>
+ <para>
+ The locale selector, theme selector and timezone selector all support persistence of locale and theme preference to a cookie. Simply set the <literal>cookie-enabled</literal> property in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<theme:theme-selector cookie-enabled="true">
+ <theme:available-themes>
+ <value>default</value>
+ <value>accessible</value>
+ <value>printable</value>
+ </theme:available-themes>
+</theme:theme-selector>
- <para>Just like the locale selector, there is a built-in theme selector to
- allow the user to freely switch themes:</para>
-
- <programlisting role="XHTML"><h:selectOneMenu value="#{themeSelector.theme}">
- <f:selectItems value="#{themeSelector.themes}"/>
-</h:selectOneMenu>
-<h:commandButton action="#{themeSelector.select}" value="Select Theme"/></programlisting>
- </section>
-
- <section>
- <title>Persisting locale and theme preferences via cookies</title>
-
- <para>The locale selector, theme selector and timezone selector all
- support persistence of locale and theme preference to a cookie. Simply set
- the <literal>cookie-enabled</literal> property in
- <literal>components.xml</literal>:</para>
-
- <programlisting role="XML"><theme:theme-selector cookie-enabled="true">
- <theme:available-themes>
- <value>default</value>
- <value>accessible</value>
- <value>printable</value>
- </theme:available-themes>
-</theme:theme-selector>
-
-<international:locale-selector cookie-enabled="true"/></programlisting>
- </section>
+<international:locale-selector cookie-enabled="true"/>]]>
+</programlisting>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Itext.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Itext.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Itext.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,1185 +1,1011 @@
-<chapter id="itext">
- <title>iText PDF generation</title>
- <para>Seam now includes a component set for generating documents using iText. The primary focus of Seam's iText
- document support is for the generation of PDF documents, but Seam also offers basic support for RTF document
- generation.</para>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- <section id="itext.intro">
- <title>Using PDF Support</title>
- <para>iText support is provided by <literal>jboss-seam-pdf.jar</literal>. This JAR contains the iText JSF
- controls, which are used to construct views that can render to PDF, and the DocumentStore component, which
- serves the rendered documents to the user. To include PDF support in your application, put
- <literal>jboss-seam-pdf.jar</literal> in your <literal>WEB-INF/lib</literal> directory along with the
- iText JAR file. There is no further configuration needed to use Seam's iText support. </para>
- <para> The Seam iText module requires the use of Facelets as the view technology. Future versions of the library
- may also support the use of JSP. Additionally, it requires the use of the seam-ui package.</para>
+<chapter id="itext" >
+ <title>iText PDF generation</title>
+ <para>
+ Seam now includes a component set for generating documents with iText. The primary focus of Seam's iText document support is for the generation of PDF documents, but Seam also offers basic support for RTF document generation.
+ </para>
+ <section id="itext.intro">
+ <title>Using PDF Support</title>
+ <para>
+ iText support is provided by <filename>jboss-seam-pdf.jar</filename>. This <filename>JAR</filename> contains the iText JSF controls (which construct views that can render to PDF) and the DocumentStore component (which serves the rendered documents to the user). To include PDF support in your application, place <filename>jboss-seam-pdf.jar</filename> in your <literal>WEB-INF/lib</literal> directory along with the iText <filename>JAR</filename> file. No further configuration is required to use Seam's iText support.
+ </para>
+ <para>
+ The Seam iText module requires that Facelets be used as the view technology. Future versions of the library may also support the use of JSP. It also requires the use of the <literal>seam-ui</literal> package.
+ </para>
+ <para>
+ The <literal>examples/itext</literal> project contains an example of the PDF support in action. It demonstrates proper deployment packaging, and contains several examples demonstrating the key PDF-generation features currently supported.
+ </para>
+ <section id="itext.document">
+ <title>Creating a document</title>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:document>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Documents are generated by Facelet XHTML files using tags in the <literal>http://jboss.com/products/seam/pdf</literal> namespace. Documents should always have the <literal>document</literal> tag at the root of the document. The <literal>document</literal> tag prepares Seam to generate a document into the DocumentStore and renders an HTML redirect to that stored content.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><literal>type</literal></term>
+ <listitem>
+ <para>
+ The type of the document to be produced. Valid values are <literal>PDF</literal>, <literal>RTF</literal> and <literal>HTML</literal>. Seam defaults to PDF generation, and many features only work correctly when generating PDF documents.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>pageSize</literal></term>
+ <listitem>
+ <para>
+ The size of the page to be generated. The most commonly used values are <literal>LETTER</literal> and <literal>A4</literal>. A full list of supported pages sizes can be found in the <literal>com.lowagie.text.PageSize</literal> class. Alternatively, pageSize can provide the width and height of the page directly. The value "612 792", for example, is equivalent to the LETTER page size.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>orientation</literal></term>
+ <listitem>
+ <para>
+ The orientation of the page. Valid values are <literal>portrait</literal> and <literal>landscape</literal>. Landscape mode swaps the height and width page values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>margins</literal></term>
+ <listitem>
+ <para>
+ The left, right, top and bottom margin values.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>marginMirroring</literal></term>
+ <listitem>
+ <para>
+ Indicates that margin settings should be reversed on alternating pages.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>disposition</literal></term>
+ <listitem>
+ <para>
+ When generating PDFs in a web browser, this determines the HTTP <literal>Content-Disposition</literal> of the document. Valid values are <literal>inline</literal>, which indicates the document should be displayed in the browser window if possible, and <literal>attachment</literal>, which indicates that the document should be treated as a download. The default value is <literal>inline</literal>.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><literal>fileName</literal></term>
+ <listitem>
+ <para>
+ For attachments, this value overrides the downloaded file name.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ <para>
+ <emphasis>Metadata Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>title</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>subject</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>keywords</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>author</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>creator</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:document xmlns:p="http://jboss.com/products/seam/pdf">
+ The document goes here.
+</p:document>]]>
+</programlisting>
- <para> The <literal>examples/itext</literal> project contains an example of the PDF support in action. It
- demonstrates proper deployment packaging, and it contains a number examples that demonstrate the key PDF
- generation features current supported. </para>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="itext.text">
+ <title>Basic Text Elements</title>
+ <para>
+ Seam provides special UI components for generating content suitable to PDF. <literal><![CDATA[<p:image>]]></literal> and <literal><![CDATA[<p:paragraph>]]></literal> tags form the foundations of simple documents. Tags like <literal><![CDATA[<p:font>]]></literal> provide style information.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:paragraph>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ For most purposes, text should be sectioned into paragraphs so that text fragments can be assigned a logical flow, format and style.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>firstLineIndent</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>extraParagraphSpace</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>leading</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>multipliedLeading</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>spacingBefore</literal> — The blank space to be inserted before the element.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>spacingAfter</literal> — The blank space to be inserted after the element.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>indentationLeft</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>indentationRight</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>keepTogether</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
- <section id="itext.document">
- <title>Creating a document</title>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*"/>
- <colspec colnum="2" colwidth="3*"/>
-
- <tbody>
-
- <row>
- <entry valign="top">
- <para>
- <literal><p:document></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para> Documents are generated by facelet XHTML files using tags in the
- <literal>http://jboss.com/products/seam/pdf</literal> namespace. Documents
- should always have the <literal>document</literal> tag at the root of the document.
- The <literal>document</literal> tag prepares Seam to generate a document into the
- DocumentStore and renders an HTML redirect to that stored content.</para>
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>type</literal> — The type of the document to be produced.
- Valid values are <literal>PDF</literal>, <literal>RTF</literal> and
- <literal>HTML</literal> modes. Seam defaults to PDF generation, and many
- of the features only work correctly when generating PDF documents.</para>
- </listitem>
-
-
- <listitem>
- <para>
- <literal>pageSize</literal> — The size of the page to be generate.
- The most commonly used values would be <literal>LETTER</literal> and
- <literal>A4</literal>. A full list of supported pages sizes can be found
- in <literal>com.lowagie.text.PageSize</literal> class. Alternatively,
- pageSize can provide the width and height of the page directly. The value
- "612 792", for example, is equivalent to the LETTER page size. </para>
- </listitem>
- <listitem>
- <para>
- <literal>orientation</literal> — The orientation of the page.
- Valid values are <literal>portrait</literal> and
- <literal>landscape</literal>. In landscape mode, the height and width page
- size values are reversed. </para>
- </listitem>
-
-
- <listitem>
- <para>
- <literal>margins</literal> — The left, right, top and bottom
- margin values. </para>
- </listitem>
- <listitem>
- <para>
- <literal>marginMirroring</literal> — Indicates that margin
- settings should be reversed an alternating pages.</para>
- </listitem>
-
- <listitem>
- <para>
- <literal>disposition</literal> — When generating PDFs in a web browser, this determines the HTTP
- <literal>Content-Disposition</literal> of the document. Valid values are <literal>inline</literal>, which
- indicates the document should be displayed in the browser window if possible,
- and <literal>attachment</literal>, which indicates that the document should be treated as a download.
- The default value is <literal>inline</literal>.</para>
- </listitem>
- <listitem>
- <para>
- <literal>fileName</literal> — For attachments, this value
- overrides the downloaded file name.
- </para>
- </listitem>
- </itemizedlist>
-
-
- <para>
- <emphasis>Metadata Attributes</emphasis>
- </para>
-
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>title</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>subject</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>keywords</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>author</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>creator</literal>
- </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:document xmlns:p="http://jboss.com/products/seam/pdf">
- The document goes here.
-</p:document>]]></programlisting>
-
-
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- </section>
-
-
- <section id="itext.text">
- <title>Basic Text Elements</title>
-
- <para> Useful documents will need to contain more than just text; however, the standard UI components are
- geared towards HTML generation and are not useful for generating PDF content. Instead, Seam provides a
- special UI components for generating suitable PDF content. Tags like
- <literal><p:image></literal> and <literal><p:paragraph></literal> are the
- basic foundations of simple documents. Tags like <literal><p:font></literal> provide style
- information to all the content surrounding them. </para>
-
-
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*"/>
- <colspec colnum="2" colwidth="3*"/>
-
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><p:paragraph></literal>
- </para>
- </entry>
-
-
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para> Most uses of text should be sectioned into paragraphs so that text fragments can
- be flowed, formatted and styled in logical groups.</para>
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>firstLineIndent</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>extraParagraphSpace</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>leading</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>multipliedLeading</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>spacingBefore</literal> — The blank space to be inserted
- before the element. </para>
- </listitem>
- <listitem>
- <para>
- <literal>spacingAfter</literal> — The blank space to be inserted
- after the element.</para>
- </listitem>
- <listitem>
- <para>
- <literal>indentationLeft</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>indentationRight</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>keepTogether</literal>
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:paragraph alignment="justify">
- This is a simple document. It isn't very fancy.
-</p:paragraph>]]></programlisting>
-
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:text></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
-
- <para> The <literal>text</literal> tag allows text fragments to be produced from
- application data using normal JSF converter mechanisms. It is very similar to the
- <literal>outputText</literal> tag used when rendering HTML documents. </para>
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
-
- <itemizedlist>
- <listitem>
- <para><literal>value</literal> — The value to be displayed. This will
- typically be a value binding expression.</para>
- </listitem>
- </itemizedlist>
-
- <para>
- <emphasis>Usage</emphasis>
- </para>
-
- <programlisting role="XHTML"><![CDATA[<p:paragraph>
- The item costs <p:text value="#{product.price}">
- <f:convertNumber type="currency" currencySymbol="$"/>
- </p:text>
-</p:paragraph>]]></programlisting>
-
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:html></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
-
- <para> The <literal>html</literal> tag renders HTML content into the PDF.
- </para>
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
-
- <itemizedlist>
- <listitem>
- <para><literal>value</literal> — The text to be displayed.</para>
- </listitem>
- </itemizedlist>
-
- <para>
- <emphasis>Usage</emphasis>
- </para>
-
- <programlisting role="XHTML"><![CDATA[
-<p:html value="This is HTML with <b>some markup</b>." />
+ </entry>
+
+<programlisting role="XHTML"><![CDATA[<p:paragraph alignment="justify">
+ This is a simple document. It isn't very fancy.
+</p:paragraph>]]>
+</programlisting>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:text>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ The <literal>text</literal> tag lets application data produce text fragments using normal JSF converter mechanisms. It is very similar to the <literal>outputText</literal> tag used when rendering HTML documents.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — The value to be displayed. This is typically a value binding expression.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+
+<programlisting role="XHTML"><![CDATA[<p:paragraph>
+ The item costs <p:text value="#{product.price}">
+ <f:convertNumber type="currency"
+ currencySymbol="$"/>
+ </p:text>
+</p:paragraph>]]>
+</programlisting>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:html>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ The <literal>html</literal> tag renders HTML content into the PDF.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — The text to be displayed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:html value="This is HTML with <b>some markup</b>" />
<p:html>
- <h1>This is more complex HTML</h1>
- <ul>
- <li>one</li>
- <li>two</li>
- <li>three</li>
- </ul>
+ <h1>This is more complex HTML</h1>
+ <ul>
+ <li>one</li>
+ <li>two</li>
+ <li>three</li>
+ </ul>
</p:html>
<p:html>
- <s:formattedText value="*This* is |Seam Text| as HTML. It's very^cool^." />
+ <s:formattedText value="*This* is |Seam Text| as
+ HTML.
+ It's very^cool^." />
</p:html>
]]></programlisting>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:font></literal>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:font>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ The <literal>font</literal> tag defines the default font to be used for all text inside of it.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>name</literal> — The font name, for example: <literal>COURIER</literal>, <literal>HELVETICA</literal>, <literal>TIMES-ROMAN</literal>, <literal>SYMBOL</literal> or <literal>ZAPFDINGBATS</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>size</literal> — The point size of the font.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>style</literal> — The font styles. Any combination of : <literal>NORMAL</literal>, <literal>BOLD</literal>, <literal>ITALIC</literal>, <literal>OBLIQUE</literal>, <literal>UNDERLINE</literal>, <literal>LINE-THROUGH</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>encoding</literal> — The character set encoding.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+
+<programlisting role="XHTML"><![CDATA[<p:font name="courier" style="bold" size="24">
+ <p:paragraph>My Title</p:paragraph>
+</p:font>]]>
+</programlisting>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><p:textcolumn></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para><literal>p:textcolumn</literal> inserts a text column that can
+ be used to control the flow of text. The most common case is to
+ support right to left direction fonts.</para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ <itemizedlist>
+ <listitem>
+ <para><literal>left</literal> — The left bounds of
+ the text column</para>
+ </listitem>
+ <listitem>
+ <para><literal>right</literal> — The right bounds
+ of the text column</para>
+ </listitem>
+ <listitem>
+ <para><literal>direction</literal> — The run direction
+ of the text in the column: <literal>RTL</literal>,
+ <literal>LTR</literal>, <literal
+ >NO-BIDI</literal>, <literal>DEFAULT</literal>
</para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
-
- <para> The font tag defines the default font to be used for all text inside of it. </para>
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
-
- <itemizedlist>
- <listitem>
- <para><literal>name</literal> — The font name, for example:
- <literal>COURIER</literal>, <literal>HELVETICA</literal>,
- <literal>TIMES-ROMAN</literal>, <literal>SYMBOL</literal> or
- <literal>ZAPFDINGBATS</literal>.</para>
- </listitem>
-
- <listitem>
- <para><literal>size</literal> — The point size of the font.</para>
- </listitem>
-
- <listitem>
- <para><literal>style</literal> — The font styles. Any combination of :
- <literal>NORMAL</literal>, <literal>BOLD</literal>,
- <literal>ITALIC</literal>, <literal>OBLIQUE</literal>,
- <literal>UNDERLINE</literal>, <literal>LINE-THROUGH</literal></para>
-
- </listitem>
-
- <listitem>
- <para><literal>color</literal> — The font color. (see <xref linkend="itext.colors"/> for color values)</para>
- </listitem>
-
- <listitem>
- <para><literal>encoding</literal> — The character set encoding.</para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
-
- <programlisting role="XHTML"><![CDATA[<p:font name="courier" style="bold" size="24">
- <p:paragraph>My Title</p:paragraph>
-</p:font>]]></programlisting>
-
- </entry>
- </row>
-<row>
- <entry valign="top">
- <para>
- <literal><p:textcolumn></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para><literal>p:textcolumn</literal> inserts a text column that can
- be used to control the flow of text. The most common case is to
- support right to left direction fonts.</para>
- <para>
- <emphasis>Attributes</emphasis>
- <itemizedlist>
- <listitem>
- <para><literal>left</literal> — The left bounds of
- the text column</para>
- </listitem>
- <listitem>
- <para><literal>right</literal> — The right bounds
- of the text column</para>
- </listitem>
- <listitem>
- <para><literal>direction</literal> — The run direction
- of the text in the column: <literal>RTL</literal>,
- <literal>LTR</literal>, <literal
- >NO-BIDI</literal>, <literal>DEFAULT</literal>
- </para>
- </listitem>
- </itemizedlist>
- </para>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[
+ </listitem>
+ </itemizedlist>
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+ <programlisting role="XHTML"><![CDATA[
<p:textcolumn left="400" right="600" direction="rtl">
- <p:font name="/Library/Fonts/Arial Unicode.ttf"
- encoding="Identity-H"
- embedded="true">#{phrases.arabic}</p:font>
+<p:font name="/Library/Fonts/Arial Unicode.ttf"
+encoding="Identity-H"
+embedded="true">#{phrases.arabic}</p:font>
</p:textcolumn>]]></programlisting>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:newPage></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
+ </row>
-
- <para><literal>p:newPage</literal> inserts a page break. </para>
-
-
- <para>
- <emphasis>Usage</emphasis>
- </para>
-
- <programlisting role="XHTML"><![CDATA[<p:newPage />]]></programlisting>
-
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:image></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
-
-
- <para><literal>p:image</literal> inserts an image into the document. Images can be
- loaded from the classpath or from the web application context using the
- <literal>value</literal> attribute. </para>
-
-
-
- <para>Resources can also be dynamically generated by application code. The
- <literal>imageData</literal> attribute can specify a value binding expression
- whose value is a <literal>java.awt.Image</literal> object. </para>
-
-
-
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>value</literal> — A resource name or a method
- expression binding to an application-generated image. </para>
- </listitem>
-
-
- <listitem>
- <para><literal>rotation</literal> — The rotation of the image in
- degrees. </para>
- </listitem>
-
-
- <listitem>
- <para><literal>height</literal> — The height of the image. </para>
- </listitem>
-
- <listitem>
- <para><literal>width</literal> — The width of the image. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>alignment</literal>— The alignment of the image. (see
- <xref linkend="itext.alignment"/> for possible values) </para>
-
- </listitem>
- <listitem>
-
- <para>
- <literal>alt</literal> — Alternative text representation for the
- image.</para>
- </listitem>
- <listitem>
- <para>
- <literal>indentationLeft</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>indentationRight</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>spacingBefore</literal> — The blank space to be inserted
- before the element.</para>
- </listitem>
- <listitem>
- <para>
- <literal>spacingAfter</literal> — The blank space to be inserted
- after the element.</para>
-
- </listitem>
- <listitem>
-
- <para>
- <literal>widthPercentage</literal>
- </para>
-
- </listitem>
- <listitem>
- <para>
- <literal>initialRotation</literal>
- </para>
- </listitem>
- <listitem>
-
- <para>
- <literal>dpi</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>scalePercent</literal> — The scaling factor (as a
- percentage) to use for the image. This can be expressed as a single
- percentage value or as two percentage values representing separate x and y
- scaling percentages.</para>
- </listitem>
- <listitem>
- <para>
- <literal>scaleToFit</literal> — Specifies the X any Y
- size to scale the image to. The image will be scale to fit those dimensions
- as closely as possible while preserving the XY ratio of the image.</para>
- </listitem>
- <listitem>
- <para>
- <literal>wrap</literal>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>underlying</literal>
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- <emphasis>Usage</emphasis>
- </para>
-
-
- <programlisting role="XHTML"><![CDATA[<p:image value="/jboss.jpg" />]]></programlisting>
- <programlisting role="XHTML"><![CDATA[<p:image value="#{images.chart}" />]]></programlisting>
-
-
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:anchor></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para><literal>p:anchor</literal> defines clickable links from a document. It supports
- the following attributes:</para>
-
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
-
- <itemizedlist>
- <listitem>
- <para><literal>name</literal> — The name of an in-document anchor
- destination.</para>
-
- </listitem>
-
- <listitem>
-
- <para><literal>reference</literal> — The destination the link refers
- to. Links to other points in the document should begin with a "#". For
- example, "#link1" to refer to an anchor position with a
- <literal>name</literal> of <literal>link1</literal>. Links may also be a
- full URL to point to a resource outside of the document.</para>
- </listitem>
- </itemizedlist>
-
-
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:listItem><p:anchor reference="#reason1">Reason 1</p:anchor></p:listItem>
-...
-<p:paragraph>
- <p:anchor name="reason1">It's the quickest way to get "rich"</p:anchor>
- ...
-</p:paragraph>]]></programlisting>
-
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- </section>
-
- <section id="itext.header">
- <title>Headers and Footers</title>
-
-
-
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*"/>
- <colspec colnum="2" colwidth="3*"/>
-
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><p:header></literal>
- </para>
- <para>
- <literal><p:footer></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>The <literal>p:header</literal> and <literal>p:footer</literal> components provide
- the ability to place header and footer text on each page of a generated document. Header and footer declarations should appear at the beginning of a document. </para>
-
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
-
- <itemizedlist>
-
-
- <listitem>
- <para>
- <literal>alignment</literal> — The alignment of the header/footer
- box section. (see <xref linkend="itext.alignment"/> for alignment values)</para>
-
- </listitem>
-
- <listitem>
- <para><literal>backgroundColor</literal> — The background color of the
- header/footer box. (see <xref linkend="itext.colors"/> for color values)
- </para>
- </listitem>
-
-
-
-
- <listitem>
- <para><literal>borderColor</literal> — The border color of the
- header/footer box. Individual border sides can be set using
- <literal>borderColorLeft</literal>, <literal>borderColorRight</literal>,
- <literal>borderColorTop</literal> and
- <literal>borderColorBottom</literal>.(see <xref linkend="itext.colors"/> for
- color values) </para>
- </listitem>
- <listitem>
- <para>
- <literal>borderWidth</literal> — The width of the border.
- Individual border sides can be specified using
- <literal>borderWidthLeft</literal>, <literal>borderWidthRight</literal>,
- <literal>borderWidthTop</literal> and
- <literal>borderWidthBottom</literal>.</para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<f:facet name="header">
- <p:font size="12">
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:newPage>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ <literal>p:newPage</literal> inserts a page break.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+
+<programlisting role="XHTML"><![CDATA[<p:newPage />]]>
+</programlisting>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:image>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ <literal>p:image</literal> inserts an image into the document. Images can be loaded from the classpath or from the web application context using the <literal>value</literal> attribute.
+ </para>
+ <para>
+ Resources can also be dynamically generated by application code. The <literal>imageData</literal> attribute can specify a value binding expression whose value is a <literal>java.awt.Image</literal> object.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — A resource name or a method expression that binds to an application-generated image.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rotation</literal> — The rotation of the image in degrees.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>height</literal> — The height of the image.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>width</literal> — The width of the image.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>alignment</literal> — The alignment of the image. (See <xref linkend="itext.alignment" /> for possible values.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>alt</literal> — Alternative text representation for the image.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>indentationLeft</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>indentationRight</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>spacingBefore</literal> — The blank space to be inserted before the element.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>spacingAfter</literal> — The blank space to be inserted after the element.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>widthPercentage</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>initialRotation</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>dpi</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>scalePercent</literal> — The scaling factor (as a percentage) to use for the image. This can be expressed as a single percentage value or as two percentage values representing separate x and y scaling percentages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>wrap</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>underlying</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting><![CDATA[<p:image value="/jboss.jpg" />]]>
+</programlisting>
+
+<programlisting><![CDATA[<p:image value="#{images.chart}" />]]>
+</programlisting>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:anchor>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ <literal>p:anchor</literal> defines clickable links from a document. It supports the following attributes:
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>name</literal> — The name of an in-document anchor destination.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>reference</literal> — The destination the link refers to. Links to other points in the document should begin with a "#". For example, "#link1" to refer to an anchor position with a <literal>name</literal> of <literal>link1</literal>. To point to a resource outside the document, links must be a complete URL.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:listItem>
+ <p:anchor reference="#reason1">Reason 1</p:anchor>
+</p:listItem>
+...
+<p:paragraph>
+ <p:anchor name="reason1">
+ It's the quickest way to get "rich"
+ </p:anchor>
+ ...
+</p:paragraph>]]>
+</programlisting>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="itext.header">
+ <title>Headers and Footers</title>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:header>]]></literal>
+ </para>
+ <para>
+ <literal><![CDATA[<p:footer>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ The <literal>p:header</literal> and <literal>p:footer</literal> components let you place header and footer text on each page of a generated document. Header and footer declarations should appear at the beginning of a document.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>alignment</literal> — The alignment of the header/footer box section. (See <xref linkend="itext.alignment" /> for alignment values.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>backgroundColor</literal> — The background color of the header/footer box. (See <xref linkend="itext.colors" /> for color values.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>borderColor</literal> — The border color of the header/footer box. Individual border sides can be set using <literal>borderColorLeft</literal>, <literal>borderColorRight</literal>, <literal>borderColorTop</literal> and <literal>borderColorBottom</literal>. (See <xref linkend="itext.colors" /> for color values.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>borderWidth</literal> — The width of the border. Individual border sides can be specified using <literal>borderWidthLeft</literal>, <literal>borderWidthRight</literal>, <literal>borderWidthTop</literal> and <literal>borderWidthBottom</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:facet name="header">
+ <p:font size="12">
<p:footer borderWidthTop="1" borderColorTop="blue"
- borderWidthBottom="0" alignment="center">
- Why Seam? [<p:pageNumber />]
- </p:footer>
- </p:font>
-</f:facet>]]></programlisting>
+ borderWidthBottom="0" alignment="center">
+ Why Seam? [<p:pageNumber />]
+ </p:footer>
+ </p:font>
+</f:facet>]]>
+</programlisting>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:pageNumber></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>The current page number can be placed inside of a header or footer using the
- <literal>p:pageNumber</literal> tag. The page number tag can only be used in the
- context of a header or footer and can only be used once.</para>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><p:footer borderWidthTop="1" borderColorTop="blue"
- borderWidthBottom="0" alignment="center">
- Why Seam? [<p:pageNumber />]
-</p:footer></programlisting>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:pageNumber>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ The current page number can be placed inside a header or footer with the <literal>p:pageNumber</literal> tag. The page number tag can only be used in the context of a header or footer and can only be used once.
+ </para>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:footer borderWidthTop="1" borderColorTop="blue"
+ borderWidthBottom="0" alignment="center">
+ Why Seam? [<p:pageNumber />]
+</p:footer>]]>
+</programlisting>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="itext.chapters">
+ <title>Chapters and Sections</title>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:chapter>]]></literal>
+ </para>
+ <para>
+ <literal><![CDATA[<p:section>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ If the generated document follows a book/article structure, the <literal>p:chapter</literal> and <literal>p:section</literal> tags can be used to provide structure. Sections can only be used inside chapters, but they may be nested to any depth required. Most PDF viewers provide easy navigation between chapters and sections in a document.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>alignment</literal> — The alignment of the header/footer box section. (See <xref linkend="itext.alignment" /> for alignment values.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>number</literal> — The chapter number. Every chapter should be assigned a chapter number.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>numberDepth</literal> — The depth of numbering for section. All sections are numbered relative to their surrounding chapters/sections. The fourth section of the first section of chapter three would be section 3.1.4, if displayed at the default number depth of <literal>3</literal>. To omit the chapter number, a number depth of <literal>2</literal> should be used — this would display the section number as 1.4.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:document xmlns:p="http://jboss.com/products/seam/pdf" title="Hello">
+ <p:chapter number="1">
+ <p:title><p:paragraph>Hello</p:paragraph></p:title>
+ <p:paragraph>Hello #{user.name}!</p:paragraph>
+ </p:chapter>
+ <p:chapter number="2">
+ <p:title>
+ <p:paragraph>
+ Goodbye
+ </p:paragraph>
+ </p:title>
+ <p:paragraph>Goodbye #{user.name}.</p:paragraph>
+ </p:chapter>
+</p:document> ]]>
+</programlisting>
-
- <section id="itext.chapters">
- <title>Chapters and Sections</title>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*"/>
- <colspec colnum="2" colwidth="3*"/>
-
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><p:chapter></literal>
- </para>
- <para>
- <literal><p:section></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
-
- <para>If the generated document follows a book/article structure, the
- <literal>p:chapter</literal> and <literal>p:section</literal> tags can be used to
- provide the necessary structure. Sections can only be used inside of chapters, but
- they may be nested arbitrarily deep. Most PDF viewers provide easy navigation
- between chapters and sections in a document. </para>
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
-
- <itemizedlist>
-
-
- <listitem>
- <para>
- <literal>alignment</literal> — The alignment of the header/footer
- box section. (see <xref linkend="itext.alignment"/> for alignment values)</para>
-
- </listitem>
-
- <listitem>
- <para><literal>number</literal> — The chapter number. Every chapter
- should be assigned a chapter number.</para>
- </listitem>
-
- <listitem>
- <para><literal>numberDepth</literal> — The depth of numbering for
- section. All sections are numbered relative to their surrounding
- chapter/sections. The fourth section of the first section of chapter
- three would be section 3.1.4, if displayed at the default number depth of
- three. To omit the chapter number, a number depth of 2 should be used. In
- that case, the section number would be displayed as 1.4.</para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
-
- <programlisting role="XHTML"><![CDATA[<p:document xmlns:p="http://jboss.com/products/seam/pdf"
- title="Hello">
-
- <p:chapter number="1">
- <p:title><p:paragraph>Hello</p:paragraph></p:title>
- <p:paragraph>Hello #{user.name}!</p:paragraph>
- </p:chapter>
-
- <p:chapter number="2">
- <p:title><p:paragraph>Goodbye</p:paragraph></p:title>
- <p:paragraph>Goodbye #{user.name}.</p:paragraph>
- </p:chapter>
-
-</p:document> ]]></programlisting>
-
-
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:header></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
-
- <para>Any chapter or section can contain a <literal>p:title</literal>. The title will be
- displayed next to the chapter/section number. The body of the title may contain raw
- text or may be a <literal>p:paragraph</literal>. </para>
-
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
-
-
- <section id="itext.list">
- <title>Lists</title>
-
- <para>List structures can be displayed using the <literal>p:list</literal> and <literal>p:listItem</literal>
- tags. Lists may contain arbitrarily-nested sublists. List items may not be used outside of a list. The
- following document uses the <literal>ui:repeat</literal> tag to to display a list of values retrieved
- from a Seam component. </para>
-
- <programlisting role="XHTML"><![CDATA[<p:document xmlns:p="http://jboss.com/products/seam/pdf"
- xmlns:ui="http://java.sun.com/jsf/facelets"
- title="Hello">
- <p:list style="numbered">
- <ui:repeat value="#{documents}" var="doc">
- <p:listItem>#{doc.name}</p:listItem>
- </ui:repeat>
- </p:list>
-</p:document>]]></programlisting>
-
-
-
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*"/>
- <colspec colnum="2" colwidth="3*"/>
-
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><p:list></literal>
- </para>
- </entry>
- <entry valign="top">
- <!--
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>...</para>
- -->
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para><literal>style</literal> — The ordering/bulleting style of list.
- One of: <literal>NUMBERED</literal>, <literal>LETTERED</literal>,
- <literal>GREEK</literal>, <literal>ROMAN</literal>,
- <literal>ZAPFDINGBATS</literal>, <literal>ZAPFDINGBATS_NUMBER</literal>.
- If no style is given, the list items are bulleted.</para>
- </listitem>
- <listitem>
- <para><literal>listSymbol</literal> — For bulleted lists, specifies
- the bullet symbol. </para>
- </listitem>
-
- <listitem>
- <para><literal>indent</literal> — The indentation level of the
- list.</para>
- </listitem>
-
-
- <listitem>
- <para><literal>lowerCase</literal> — For list styles using letters,
- indicates whether the letters should be lower case.</para>
- </listitem>
-
-
- <listitem>
- <para><literal>charNumber</literal> — For ZAPFDINGBATS, indicates the
- character code of the bullet character.</para>
- </listitem>
-
-
- <listitem>
- <para><literal>numberType</literal> — For ZAPFDINGBATS_NUMBER,
- indicates the numbering style.</para>
- </listitem>
-
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:list style="numbered">
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:header>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Any chapter or section can contain a <literal>p:title</literal>. The title will be displayed next to the chapter or section number. The body of the title may contain raw text or may be a <literal>p:paragraph</literal>.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="itext.list">
+ <title>Lists</title>
+ <para>
+ List structures can be displayed with the <literal>p:list</literal> and <literal>p:listItem</literal> tags. Lists may contain arbitrarily-nested sublists. List items may not be used outside of a list. The following document uses the <literal>ui:repeat</literal> tag to to display a list of values retrieved from a Seam component.
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<p:document xmlns:p="http://jboss.com/products/seam/pdf"
+ xmlns:ui="http://java.sun.com/jsf/facelets" title="Hello">
+
+ <p:list style="numbered">
+ <ui:repeat value="#{documents}" var="doc">
+ <p:listItem>#{doc.name}</p:listItem>
+ </ui:repeat>
+ </p:list>
+
+</p:document>]]>
+</programlisting>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:list>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <!-- #modify: ??? description required? <para> <emphasis>Description</emphasis> </para> <para>...</para> --> <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>style</literal> — The ordering/bulleting style of the list. One of: <literal>NUMBERED</literal>, <literal>LETTERED</literal>, <literal>GREEK</literal>, <literal>ROMAN</literal>, <literal>ZAPFDINGBATS</literal>, <literal>ZAPFDINGBATS_NUMBER</literal>. If no style is given, the list items are bulleted by default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>listSymbol</literal> — For bulleted lists, specifies the bullet symbol.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>indent</literal> — The indentation level of the list.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>lowerCase</literal> — For list styles using letters, indicates whether the letters should be lower case.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>charNumber</literal> — For <literal>ZAPFDINGBATS</literal>, indicates the character code of the bullet character.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>numberType</literal> — For <literal>ZAPFDINGBATS_NUMBER</literal>, indicates the numbering style.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:list style="numbered">
<ui:repeat value="#{documents}" var="doc">
- <p:listItem>#{doc.name}</p:listItem>
- </ui:repeat>
-</p:list>]]></programlisting>
+ <p:listItem>#{doc.name}</p:listItem>
+ </ui:repeat>
+</p:list>]]>
+</programlisting>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:listItem></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para><literal>p:listItem</literal> supports the following attributes:</para>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:listItem>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ <literal>p:listItem</literal> supports the following attributes:
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>alignment</literal> — The alignment of the header/footer box section. (See <xref linkend="itext.alignment" /> for alignment values.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>alignment</literal> — The alignment of the list item. (See <xref linkend="itext.alignment" /> for possible values.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>indentationLeft</literal> — The left indentation amount.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>indentationRight</literal> — The right indentation amount.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>listSymbol</literal> — Overrides the default list symbol for this list item.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML">...
+</programlisting>
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
-
- <itemizedlist>
-
-
- <listitem>
- <para>
- <literal>alignment</literal> — The alignment of the header/footer
- box section. (see <xref linkend="itext.alignment"/> for alignment values)</para>
-
- </listitem>
-
- <listitem>
- <para><literal>alignment</literal> — The alignment of the list item.
- (See <xref linkend="itext.alignment"/> for possible values)</para>
- </listitem>
-
-
- <listitem>
- <para><literal>indentationLeft</literal> — The left indentation
- amount.</para>
- </listitem>
-
-
-
- <listitem>
- <para><literal>indentationRight</literal> — The right indentation
- amount.</para>
- </listitem>
-
-
-
- <listitem>
- <para><literal>listSymbol</literal> — Overrides the default list
- symbol for this list item.</para>
- </listitem>
-
-
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML">...</programlisting>
-
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
-
-
-
- </section>
-
- <section id="itext.tables">
- <title>Tables</title>
-
- <para>Table structures can be created using the <literal>p:table</literal> and <literal>p:cell</literal>
- tags. Unlike many table structures, there is no explicit row declaration. If a table has 3 columns, then
- every 3 cells will automatically form a row. Header and footer rows can be declared, and the headers and
- footers will be repeated in the event a table structure spans multiple pages.</para>
-
-
-
-
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*"/>
- <colspec colnum="2" colwidth="3*"/>
-
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><p:table></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para><literal>p:table</literal> supports the following attributes.</para>
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
-
-
- <listitem>
- <para><literal>columns</literal> — The number of columns (cells) that
- make up a table row.</para>
- </listitem>
-
-
-
- <listitem>
- <para><literal>widths</literal> — The relative widths of each column.
- There should be one value for each column. For example: widths="2 1 1" would
- indicate that there are 3 columns and the first column should be twice the
- size of the second and third column.</para>
- </listitem>
-
-
-
- <listitem>
- <para><literal>headerRows</literal> — The initial number of rows which
- are considered to be headers or footer rows and should be repeated if the
- table spans multiple pages. </para>
- </listitem>
-
-
-
- <listitem>
- <para><literal>footerRows</literal> — The number of rows that are
- considered to be footer rows. This value is subtracted from the
- <literal>headerRows</literal> value. If document has 2 rows which make
- up the header and one row that makes up the footer,
- <literal>headerRows</literal> should be set to 3 and
- <literal>footerRows</literal> should be set to 1</para>
- </listitem>
-
-
-
- <listitem>
- <para><literal>widthPercentage</literal> — The percentage of the page
- width that the table spans.</para>
- </listitem>
-
- <listitem>
- <para><literal>horizontalAlignment</literal> — The horizontal
- alignment of the table. (See <xref linkend="itext.alignment"/> for possible
- values)</para>
- </listitem>
-
- <listitem>
- <para>
- <literal>skipFirstHeader</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>runDirection</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>lockedWidth</literal>
- </para>
- </listitem>
-
-
-
- <listitem>
- <para>
- <literal>splitRows</literal>
- </para>
- </listitem>
-
-
-
- <listitem>
- <para><literal>spacingBefore</literal> — The blank space to be
- inserted before the element.</para>
- </listitem>
-
-
- <listitem>
- <para><literal>spacingAfter</literal> — The blank space to be inserted
- after the element.</para>
- </listitem>
- <listitem>
- <para>
- <literal>extendLastRow</literal>
- </para>
- </listitem>
-
-
-
- <listitem>
- <para>
- <literal>headersInEvent</literal>
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- <literal>splitLate</literal>
- </para>
- </listitem>
-
-
-
- <listitem>
- <para>
- <literal>keepTogether</literal>
- </para>
- </listitem>
-
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:table columns="3" headerRows="1">
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="itext.tables">
+ <title>Tables</title>
+ <para>
+ Table structures can be created using the <literal>p:table</literal> and <literal>p:cell</literal> tags. Unlike many table structures, there is no explicit row declaration. If a table has three columns, then every three cells will automatically form a row. Header and footer rows can be declared, and the headers and footers will be repeated in the event a table structure spans multiple pages.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:table>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ <literal>p:table</literal> supports the following attributes.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>columns</literal> — The number of columns (cells) that make up a table row.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>widths</literal> — The relative widths of each column. There should be one value for each column. For example: <literal>widths="2 1 1"</literal> would indicate that there are three columns and the first column should be twice the size of the second and third column.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>headerRows</literal> — The initial number of rows considered to be header and footer rows, which should be repeated if the table spans multiple pages.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>footerRows</literal> — The number of rows considered to be footer rows. This value is subtracted from the <literal>headerRows</literal> value. If document has two rows which make up the header and one row that makes up the footer, <literal>headerRows</literal> should be set to <literal>3</literal> and <literal>footerRows</literal> should be set to <literal>1</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>widthPercentage</literal> — The percentage of the page width spanned by the table.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>horizontalAlignment</literal> — The horizontal alignment of the table. (See <xref linkend="itext.alignment" /> for possible values.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>skipFirstHeader</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>runDirection</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>lockedWidth</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>splitRows</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>spacingBefore</literal> — The blank space to be inserted before the element.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>spacingAfter</literal> — The blank space to be inserted after the element.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>extendLastRow</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>headersInEvent</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>splitLate</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>keepTogether</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:table columns="3" headerRows="1">
<p:cell>name</p:cell>
<p:cell>owner</p:cell>
<p:cell>size</p:cell>
@@ -1188,1523 +1014,1325 @@
<p:cell>#{doc.user.name}</p:cell>
<p:cell>#{doc.size}</p:cell>
</ui:repeat>
-</p:table>]]></programlisting>
+</p:table>]]>
+</programlisting>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:cell>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ <literal>p:cell</literal> supports the following attributes:
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>colspan</literal> — Cells can span more than one column by declaring a <literal>colspan</literal> greater than one. Cells cannot span multiple rows.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>horizontalAlignment</literal> — The horizontal alignment of the cell. (See <xref linkend="itext.alignment" /> for possible values.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>verticalAlignment</literal> — The vertical alignment of the cell. (See <xref linkend="itext.alignment" /> for possible values.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>padding</literal> — Specify padding on a particular side using <literal>paddingLeft</literal>, <literal>paddingRight</literal>, <literal>paddingTop</literal> and <literal>paddingBottom</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>useBorderPadding</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>leading</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>multipliedLeading</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>indent</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>verticalAlignment</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>extraParagraphSpace</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fixedHeight</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>noWrap</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>minimumHeight</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>followingIndent</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rightIndent</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>spaceCharRatio</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>runDirection</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>arabicOptions</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>useAscender</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>grayFill</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rotation</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:cell>...</p:cell>]]>
+</programlisting>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:cell></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para><literal>p:cell</literal> supports the following attributes.</para>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="itext.constant">
+ <title>Document Constants</title>
+ <para>
+ This section documents some of the constants shared by attributes on multiple tags.
+ </para>
+ <section id="itext.colors">
+ <title>Color Values</title>
+ <para>
+ Seam documents do not yet support a full color specification. Currently, only named colors are supported. They are: <literal>white</literal>, <literal>gray</literal>, <literal>lightgray</literal>, <literal>darkgray</literal>, <literal>black</literal>, <literal>red</literal>, <literal>pink</literal>, <literal>yellow</literal>, <literal>green</literal>, <literal>magenta</literal>, <literal>cyan</literal> and <literal>blue</literal>.
+ </para>
+ </section>
+
+ <section id="itext.alignment">
+ <title>Alignment Values</title>
+ <para>
+ Seam PDF supports the following horizontal alignment values: <literal>left</literal>, <literal>right</literal>, <literal>center</literal>, <literal>justify</literal> and <literal>justifyall</literal>. The vertical alignment values are <literal>top</literal>, <literal>middle</literal>, <literal>bottom</literal>, and <literal>baseline</literal>.
+ </para>
+ </section>
+
+ </section>
+
+ </section>
+
+ <section id="itext.charting">
+ <title>Charting</title>
+ <para>
+ Charting support is also provided with <filename>jboss-seam-pdf.jar</filename>. Charts can be used in PDF documents, or as images in an HTML page. To use charting, you will need to add the JFreeChart library (<filename>jfreechart.jar</filename> and <filename>jcommon.jar</filename>) to the <literal>WEB-INF/lib</literal> directory. Three types of charts are currently supported: pie charts, bar charts and line charts.
+ </para>
+ <informaltable id="itext.barchart">
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3.5*"></colspec>
+ <tbody>
- <para>
- <emphasis>Attributes</emphasis>
- </para>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:chart>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Displays a chart created in Java by a Seam component.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>chart</literal>
+ — The chart object to display.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>height</literal>
+ — The height of the chart.
+ </para>
+ </listitem>
+
+ <listitem>
+ <para>
+ <literal>width</literal>
+ — The width of the chart.
+ </para>
+ </listitem>
+
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ <programlisting role="XHTML"><![CDATA[<p:chart chart="#{mycomponent.chart}" width="500" height="500" />]]></programlisting>
+ </entry>
+ </row>
+
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:barchart>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Displays a bar chart.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>borderVisible</literal> — Controls whether or not a border is displayed around the entire chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>borderPaint</literal> — The color of the border, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>borderBackgroundPaint</literal> — The default background color of the chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>borderStroke</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainAxisLabel</literal> — The text label for the domain axis.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainLabelPosition</literal> — The angle of the domain axis category labels. Valid values are <literal>STANDARD</literal>, <literal>UP_45</literal>, <literal>UP_90</literal>, <literal>DOWN_45</literal> and <literal>DOWN_90</literal>. The value can also be a positive or negative angle in radians.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainAxisPaint</literal> — The color of the domain axis label.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainGridlinesVisible</literal>— Controls whether or not gridlines for the domain axis are shown on the chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainGridlinePaint</literal>— The color of the domain gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainGridlineStroke</literal> — The stroke style of the domain gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>height</literal> — The height of the chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>width</literal> — The width of the chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>is3D</literal> — A Boolean value indicating that the chart should be rendered in 3D instead of 2D.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>legend</literal> — A Boolean value indicating whether or not the chart should include a legend.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>legendItemPaint</literal>— The default color of the text labels in the legend.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>legendItemBackgoundPaint</literal>— The background color for the legend, if different from the chart background color.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>legendOutlinePaint</literal>— The color of the border around the legend.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>orientation</literal> — The orientation of the plot, either <literal>vertical</literal> (the default) or <literal>horizontal</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>plotBackgroundPaint</literal> — The color of the plot background.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>plotBackgroundAlpha</literal> — The alpha (transparency) level of the plot background. This should be a number between 0 (completely transparent) and 1 (completely opaque).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>plotForegroundAlpha</literal> — The alpha (transparency) level of the plot. This should be a number between 0 (completely transparent) and 1 (completely opaque).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>plotOutlinePaint</literal> — The color of the range gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>plotOutlineStroke</literal> — The stroke style of the range gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rangeAxisLabel</literal> — The text label for the range axis.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rangeAxisPaint</literal> — The color of the range axis label.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rangeGridlinesVisible</literal> — Controls whether or not gridlines for the range axis are shown on the chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rangeGridlinePaint</literal> — The color of the range gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rangeGridlineStroke</literal> — The stroke style of the range gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>title</literal> — The chart title text.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>titlePaint</literal> — The color of the chart title text.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>titleBackgroundPaint</literal> — The background color around the chart title.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>width</literal> — The width of the chart.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:barchart title="Bar Chart" legend="true" width="500" height="500">
+ <p:series key="Last Year">
+ <p:data columnKey="Joe" value="100" />
+ <p:data columnKey="Bob" value="120" />
+ </p:series>
+ <p:series key="This Year">
+ <p:data columnKey="Joe" value="125" />
+ <p:data columnKey="Bob" value="115" />
+ </p:series>
+</p:barchart>]]>
+</programlisting>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:linechart>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Displays a line chart.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>borderVisible</literal> — Controls whether or not a border is displayed around the entire chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>borderPaint</literal> — The color of the border, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>borderBackgroundPaint</literal> — The default background color of the chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>borderStroke</literal> —
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainAxisLabel</literal> — The text label for the domain axis.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainLabelPosition</literal> — The angle of the domain axis category labels. Valid values are <literal>STANDARD</literal>, <literal>UP_45</literal>, <literal>UP_90</literal>, <literal>DOWN_45</literal> and <literal>DOWN_90</literal>. The value can also be a positive or negative angle in radians.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainAxisPaint</literal> — The color of the domain axis label.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainGridlinesVisible</literal>— Controls whether or not gridlines for the domain axis are shown on the chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainGridlinePaint</literal>— The color of the domain gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>domainGridlineStroke</literal> — The stroke style of the domain gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>height</literal> — The height of the chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>width</literal> — The width of the chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>is3D</literal> — A Boolean value indicating that the chart should be rendered in 3D instead of 2D.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>legend</literal> — A Boolean value indicating whether or not the chart should include a legend.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>legendItemPaint</literal> — The default color of the text labels in the legend.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>legendItemBackgoundPaint</literal> — The background color for the legend, if different from the chart background color.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>legendOutlinePaint</literal> — The color of the border around the legend.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>orientation</literal> — The orientation of the plot, either <literal>vertical</literal> (the default) or <literal>horizontal</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>plotBackgroundPaint</literal> — The color of the plot background.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>plotBackgroundAlpha</literal> — The alpha (transparency) level of the plot background. It should be a number between 0 (completely transparent) and 1 (completely opaque).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>plotForegroundAlpha</literal> — The alpha (transparency) level of the plot. It should be a number between 0 (completely transparent) and 1 (completely opaque).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>plotOutlinePaint</literal> — The color of the range gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>plotOutlineStroke</literal> — The stroke style of the range gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rangeAxisLabel</literal> — The text label for the range axis.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rangeAxisPaint</literal> — The color of the range axis label.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rangeGridlinesVisible</literal> — Controls whether or not gridlines for the range axis are shown on the chart.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rangeGridlinePaint</literal> — The color of the range gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rangeGridlineStroke</literal> — The stroke style of the range gridlines, if visible.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>title</literal> — The chart title text.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>titlePaint</literal> — The color of the chart title text.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>titleBackgroundPaint</literal> — The background color around the chart title.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>width</literal> — The width of the chart.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:linechart title="Line Chart" width="500" height="500">
+ <p:series key="Prices">
+ <p:data columnKey="2003" value="7.36" />
+ <p:data columnKey="2004" value="11.50" />
+ <p:data columnKey="2005" value="34.625" />
+ <p:data columnKey="2006" value="76.30" />
+ <p:data columnKey="2007" value="85.05" />
+ </p:series>
+</p:linechart>]]>
+</programlisting>
- <itemizedlist>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:piechart>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Displays a pie chart.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>title</literal> — The chart title text.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>label</literal> — The default label text for pie sections.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>legend</literal> — A Boolean value indicating whether or not the chart should include a legend. Default value is <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>is3D</literal> — A Boolean value indicating that the chart should be rendered in 3D instead of 2D.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>labelLinkMargin</literal> — The link margin for labels.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>labelLinkPaint</literal> — The paint used for the label linking lines.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>labelLinkStroke</literal> — The stroke used for the label linking lines.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>labelLinksVisible</literal> — A flag that controls whether or not the label links are drawn.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>labelOutlinePaint</literal> — The paint used to draw the outline of the section labels.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>labelOutlineStroke</literal> — The stroke used to draw the outline of the section labels.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>labelShadowPaint</literal> — The paint used to draw the shadow for the section labels.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>labelPaint</literal> — The color used to draw the section labels.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>labelGap</literal> — The gap between the labels and the plot, as a percentage of the plot width.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>labelBackgroundPaint</literal> — The color used to draw the background of the section labels. If this is null, the background is not filled.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>startAngle</literal> — The starting angle of the first section.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>circular</literal> — A Boolean value indicating that the chart should be drawn as a circle. If <literal>false</literal>, the chart is drawn as an ellipse. The default is <literal>true</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>direction</literal> — The direction in which the pie sections are drawn. One of: <literal>clockwise</literal> or <literal>anticlockwise</literal>. The default is <literal>clockwise</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>sectionOutlinePaint</literal> — The outline paint for all sections.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>sectionOutlineStroke</literal> — The outline stroke for all sections.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>sectionOutlinesVisible</literal> — Indicates whether an outline is drawn for each section in the plot.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>baseSectionOutlinePaint</literal> — The base section outline paint.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>baseSectionPaint</literal> — The base section paint.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>baseSectionOutlineStroke</literal> — The base section outline stroke.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[
+<p:piechart title="Pie Chart" circular="false"
+ direction="anticlockwise" startAngle="30"
+ labelGap="0.1" labelLinkPaint="red">
+ <p:series key="Prices">
+ <p:data key="2003" columnKey="2003" value="7.36" />
+ <p:data key="2004" columnKey="2004" value="11.50" />
+ <p:data key="2005" columnKey="2005" value="34.625" />
+ <p:data key="2006" columnKey="2006" value="76.30" />
+ <p:data key="2007" columnKey="2007" value="85.05" />
+ </p:series>
+</p:piechart>]]>
+</programlisting>
- <listitem>
- <para>
- <literal>colspan</literal> — Cells can span more than one column
- by declaring a <literal>colspan</literal> greater than 1. Tables do not have
- the ability to span across multiple rows. </para>
- </listitem>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:series>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Category data can be broken down into series. The series tag is used to categorize a data set with a series and apply styling to the entire series.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>key</literal> — The series name.
+ </para>
+ </listitem>
+ <!-- <listitem> <para> <literal>seriesFillPaint</literal> — </para> </listitem> --> <listitem>
+ <para>
+ <literal>seriesPaint</literal> — The color of each item in the series.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>seriesOutlinePaint</literal> — The outline color for each item in the series.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>seriesOutlineStroke</literal> — The stroke used to draw each item in the series.
+ </para>
+ </listitem>
+ <!-- <listitem> <para> <literal>seriesStroke</literal> </para> </listitem> --> <listitem>
+ <para>
+ <literal>seriesVisible</literal> — A Boolean indicating if the series should be displayed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>seriesVisibleInLegend</literal> — A Boolean indicating whether the series should be listed in the legend.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:series key="data1">
+ <ui:repeat value="#{data.pieData1}" var="item">
+ <p:data columnKey="#{item.name}"
+ value="#{item.value}" />
+ </ui:repeat>
+</p:series>]]>
+</programlisting>
-
-
- <listitem>
- <para><literal>horizontalAlignment</literal> — The horizontal
- alignment of the cell. (see <xref linkend="itext.alignment"/> for possible
- values)</para>
- </listitem>
-
-
-
- <listitem>
- <para><literal>verticalAlignment</literal> — The vertical alignment of
- the cell. (see <xref linkend="itext.alignment"/> for possible values)</para>
- </listitem>
-
-
-
- <listitem>
- <para>
- <literal>padding</literal> — Padding on a given side can also be
- specified using <literal>paddingLeft</literal>,
- <literal>paddingRight</literal>, <literal>paddingTop</literal> and
- <literal>paddingBottom</literal>.</para>
- </listitem>
-
-
- <listitem>
- <para>
- <literal>useBorderPadding</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>leading</literal>
- </para>
- </listitem>
-
-
-
- <listitem>
- <para>
- <literal>multipliedLeading</literal>
- </para>
- </listitem>
-
-
-
- <listitem>
- <para>
- <literal>indent</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>verticalAlignment</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>extraParagraphSpace</literal>
- </para>
- </listitem>
-
-
-
- <listitem>
- <para>
- <literal>fixedHeight</literal>
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- <literal>noWrap</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>minimumHeight</literal>
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- <literal>followingIndent</literal>
- </para>
- </listitem>
-
-
-
- <listitem>
- <para>
- <literal>rightIndent</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>spaceCharRatio</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>runDirection</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>arabicOptions</literal>
- </para>
- </listitem>
-
-
- <listitem>
- <para>
- <literal>useAscender</literal>
- </para>
- </listitem>
-
-
-
- <listitem>
- <para>
- <literal>grayFill</literal>
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>rotation</literal>
- </para>
- </listitem>
-
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:cell>...</p:cell>]]></programlisting>
-
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
-
- </section>
-
- <section id="itext.constant">
- <title>Document Constants</title>
-
- <para>This section documents some of the constants shared by attributes on multiple tags. </para>
-
- <section id="itext.colors">
- <title>Color Values</title>
- <para>Several ways of specifying colors are provided. A limited number of colors are
- supported by name. They are: <literal>white</literal>, <literal>gray</literal>,
- <literal>lightgray</literal>, <literal>darkgray</literal>, <literal>black</literal>,
- <literal>red</literal>, <literal>pink</literal>, <literal>yellow</literal>,
- <literal>green</literal>, <literal>magenta</literal>, <literal>cyan</literal> and
- <literal>blue</literal>. Colors can be specified as an integer value, as
- definied by <literal>java.awt.Color</literal>. Finally a color value may be specified
- as <literal>rgb(r,g,b)</literal> or <literal>rgb(r,g,b,a)</literal> with the red, green, blue
- alpha values specified as an integer between 0 and 255 or as a floating point percentages
- followed by a '%' sign.
- </para>
-
- </section>
-
- <section id="itext.alignment">
- <title>Alignment Values</title>
- <para> Where alignment values are used, the Seam PDF supports the following horizontal alignment values:
- <literal>left</literal>, <literal>right</literal>, <literal>center</literal>,
- <literal>justify</literal> and <literal>justifyall</literal>. The vertical alignment values are
- <literal>top</literal>, <literal>middle</literal>, <literal>bottom</literal>, and
- <literal>baseline</literal>.</para>
- </section>
-
- </section>
-
-
- </section>
-
-
- <section id="itext.charting">
- <title>Charting</title>
-
- <para> Charting support is also provided with <literal>jboss-seam-pdf.jar</literal>. Charts can be used in PDF
- documents or can be used as images in an HTML page. Charting requires the JFreeChart library
- (<literal>jfreechart.jar</literal> and <literal>jcommon.jar</literal>) to be added to the
- <literal>WEB-INF/lib</literal> directory.
- Four types of charts are currently supported: pie charts, bar
- charts and line charts. Where greater variety or control is needed, it is possible to construct charts
- using Java code.</para>
-
-
-
- <informaltable id="itext.charttags">
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*"/>
- <colspec colnum="2" colwidth="3*"/>
-
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><p:chart></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>Displays a chart created in Java by a Seam component.</para>
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>chart</literal> — The chart object to display. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>height</literal> — The height of the chart. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>width</literal> — The width of the chart. </para>
- </listitem>
-
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:chart chart="#{mycomponent.chart}" width="500" height="500" />
- ]]></programlisting>
-
- </entry>
- </row>
-
-
- <row>
- <entry valign="top">
- <para>
- <literal><p:barchart></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>Displays a bar chart.</para>
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>chart</literal> — The chart object to display, if programmatic
- chart creation is being used.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>dataset</literal> — The dataset to be displayed, if programmatic
- dataset is being used.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>borderVisible</literal> — Controls whether or not a border is
- displayed around the entire chart. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>borderPaint</literal> — The color of the border, if visible;
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>borderBackgroundPaint</literal> — The default background
- color of the chart. </para>
- </listitem>
- <listitem>
- <para>
- <literal>borderStroke</literal> — </para>
- </listitem>
-
-
- <listitem>
- <para>
- <literal>domainAxisLabel</literal> — The text label for the domain
- axis. </para>
- </listitem>
-
-
- <listitem>
- <para>
- <literal>domainLabelPosition</literal> — The angle of the domain axis category labels.
- Valid values are <literal>STANDARD</literal>, <literal>UP_45</literal>, <literal>UP_90</literal>,
- <literal>DOWN_45</literal> and <literal>DOWN_90</literal>. Alternatively, the value
- can the positive or negative angle in radians.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>domainAxisPaint</literal> — The color of the domain axis
- label. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>domainGridlinesVisible</literal>— Controls whether or not
- gridlines for the domain axis are shown on the chart. </para>
- </listitem>
- <listitem>
- <para>
- <literal>domainGridlinePaint</literal>— The color of the domain
- gridlines, if visible. </para>
- </listitem>
- <listitem>
- <para>
- <literal>domainGridlineStroke</literal> — The stroke style of the
- domain gridlines, if visible. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>height</literal> — The height of the chart. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>width</literal> — The width of the chart. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>is3D</literal> — A boolean value indicating that the chart
- should be rendered in 3D instead of 2D. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>legend</literal> — A boolean value indicating whether or not
- the chart should include a legend. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>legendItemPaint</literal>— The default color of the text
- labels in the legend. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>legendItemBackgoundPaint</literal>— The background color for
- the legend, if different from the chart background color.</para>
- </listitem>
-
- <listitem>
- <para>
- <literal>legendOutlinePaint</literal>— The color of the border around
- the legend.</para>
- </listitem>
-
- <listitem>
- <para>
- <literal>orientation</literal> — The orientation of the plot, either
- <code>vertical</code> (the default) or <code>horizontal</code>. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>plotBackgroundPaint</literal>— The color of the plot
- background.</para>
- </listitem>
-
- <listitem>
- <para>
- <literal>plotBackgroundAlpha</literal>— The alpha (transparency) level
- of the plot background. It should be a number between 0 (completely transparent)
- and 1 (completely opaque). </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>plotForegroundAlpha</literal>— The alpha (transparency) level
- of the plot. It should be a number between 0 (completely transparent) and 1
- (completely opaque). </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>plotOutlinePaint</literal>— The color of the range gridlines,
- if visible. </para>
- </listitem>
- <listitem>
- <para>
- <literal>plotOutlineStroke</literal> — The stroke style of the range
- gridlines, if visible. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>rangeAxisLabel</literal> — The text label for the range axis.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>rangeAxisPaint</literal> — The color of the range axis label.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>rangeGridlinesVisible</literal>— Controls whether or not
- gridlines for the range axis are shown on the chart. </para>
- </listitem>
- <listitem>
- <para>
- <literal>rangeGridlinePaint</literal>— The color of the range
- gridlines, if visible. </para>
- </listitem>
- <listitem>
- <para>
- <literal>rangeGridlineStroke</literal> — The stroke style of the range
- gridlines, if visible. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>title</literal> — The chart title text. </para>
- </listitem>
- <listitem>
- <para>
- <literal>titlePaint</literal>— The color of the chart title text.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>titleBackgroundPaint</literal>— The background color around
- the chart title.</para>
- </listitem>
- <listitem>
- <para>
- <literal>width</literal> — The width of the chart. </para>
- </listitem>
-
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:barchart title="Bar Chart" legend="true"
- width="500" height="500">
- <p:series key="Last Year">
- <p:data columnKey="Joe" value="100" />
- <p:data columnKey="Bob" value="120" />
- </p:series> <p:series key="This Year">
- <p:data columnKey="Joe" value="125" />
- <p:data columnKey="Bob" value="115" />
- </p:series>
-</p:barchart>]]></programlisting>
-
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:linechart></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>Displays a line chart.</para>
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>chart</literal> — The chart object to display, if programmatic
- chart creation is being used.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>dataset</literal> — The dataset to be displayed, if programmatic
- dataset is being used.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>borderVisible</literal> — Controls whether or not a border is
- displayed around the entire chart. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>borderPaint</literal> — The color of the border, if visible;
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>borderBackgroundPaint</literal> — The default background
- color of the chart. </para>
- </listitem>
- <listitem>
- <para>
- <literal>borderStroke</literal> — </para>
- </listitem>
-
-
- <listitem>
- <para>
- <literal>domainAxisLabel</literal> — The text label for the domain
- axis. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>domainLabelPosition</literal> — The angle of the domain axis category labels.
- Valid values are <literal>STANDARD</literal>, <literal>UP_45</literal>, <literal>UP_90</literal>,
- <literal>DOWN_45</literal> and <literal>DOWN_90</literal>. Alternatively, the value
- can the positive or negative angle in radians.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>domainAxisPaint</literal> — The color of the domain axis
- label. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>domainGridlinesVisible</literal>— Controls whether or not
- gridlines for the domain axis are shown on the chart. </para>
- </listitem>
- <listitem>
- <para>
- <literal>domainGridlinePaint</literal>— The color of the domain
- gridlines, if visible. </para>
- </listitem>
- <listitem>
- <para>
- <literal>domainGridlineStroke</literal> — The stroke style of the
- domain gridlines, if visible. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>height</literal> — The height of the chart. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>width</literal> — The width of the chart. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>is3D</literal> — A boolean value indicating that the chart
- should be rendered in 3D instead of 2D. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>legend</literal> — A boolean value indicating whether or not
- the chart should include a legend. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>legendItemPaint</literal> — The default color of the text
- labels in the legend. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>legendItemBackgoundPaint</literal> — The background color for
- the legend, if different from the chart background color.</para>
- </listitem>
-
- <listitem>
- <para>
- <literal>legendOutlinePaint</literal> — The color of the border around
- the legend.</para>
- </listitem>
-
- <listitem>
- <para>
- <literal>orientation</literal> — The orientation of the plot, either
- <code>vertical</code> (the default) or <code>horizontal</code>. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>plotBackgroundPaint</literal> — The color of the plot
- background.</para>
- </listitem>
-
- <listitem>
- <para>
- <literal>plotBackgroundAlpha</literal> — The alpha (transparency) level
- of the plot background. It should be a number between 0 (completely transparent)
- and 1 (completely opaque). </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>plotForegroundAlpha</literal> — The alpha (transparency) level
- of the plot. It should be a number between 0 (completely transparent) and 1
- (completely opaque). </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>plotOutlinePaint</literal> — The color of the range gridlines,
- if visible. </para>
- </listitem>
- <listitem>
- <para>
- <literal>plotOutlineStroke</literal> — The stroke style of the range
- gridlines, if visible. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>rangeAxisLabel</literal> — The text label for the range axis.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>rangeAxisPaint</literal> — The color of the range axis label.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>rangeGridlinesVisible</literal> — Controls whether or not
- gridlines for the range axis are shown on the chart. </para>
- </listitem>
- <listitem>
- <para>
- <literal>rangeGridlinePaint</literal> — The color of the range
- gridlines, if visible. </para>
- </listitem>
- <listitem>
- <para>
- <literal>rangeGridlineStroke</literal> — The stroke style of the range
- gridlines, if visible. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>title</literal> — The chart title text. </para>
- </listitem>
- <listitem>
- <para>
- <literal>titlePaint</literal> — The color of the chart title text.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>titleBackgroundPaint</literal> — The background color around
- the chart title.</para>
- </listitem>
- <listitem>
- <para>
- <literal>width</literal> — The width of the chart. </para>
- </listitem>
-
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:linechart title="Line Chart"
- width="500" height="500">
- <p:series key="Prices">
- <p:data columnKey="2003" value="7.36" />
- <p:data columnKey="2004" value="11.50" />
- <p:data columnKey="2005" value="34.625" />
- <p:data columnKey="2006" value="76.30" />
- <p:data columnKey="2007" value="85.05" />
- </p:series>
-</p:linechart>]]></programlisting>
-
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:piechart></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>Displays a pie chart.</para>
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- <literal>title</literal> — The chart title text. </para>
- </listitem>
- <listitem>
- <para>
- <literal>chart</literal> — The chart object to display, if programmatic
- chart creation is being used.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>dataset</literal> — The dataset to be displayed, if programmatic
- dataset is being used.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>label</literal> — The default label text for pie sections.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>legend</literal> — A boolean value indicating whether or not
- the chart should include a legend. Default value is true </para>
- </listitem>
- <listitem>
- <para>
- <literal>is3D</literal> —A boolean value indicating that the chart
- should be rendered in 3D instead of 2D. </para>
- </listitem>
- <listitem>
- <para>
- <literal>labelLinkMargin</literal> — The link margin for labels.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>labelLinkPaint</literal> — The paint used for the label
- linking lines. </para>
- </listitem>
- <listitem>
- <para>
- <literal>labelLinkStroke</literal> — he stroke used for the label
- linking lines. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>labelLinksVisible</literal> — A flag that controls whether or
- not the label links are drawn. </para>
- </listitem>
- <listitem>
- <para>
- <literal>labelOutlinePaint</literal> — The paint used to draw the
- outline of the section labels. </para>
- </listitem>
- <listitem>
- <para>
- <literal>labelOutlineStroke</literal> — The stroke used to draw the
- outline of the section labels. </para>
- </listitem>
- <listitem>
- <para>
- <literal>labelShadowPaint</literal> — The paint used to draw the shadow
- for the section labels. </para>
- </listitem>
- <listitem>
- <para>
- <literal>labelPaint</literal> — The color used to draw the section
- labels </para>
- </listitem>
- <listitem>
- <para>
- <literal>labelGap</literal> — The gap between the labels and the plot
- as a percentage of the plot width. </para>
- </listitem>
- <listitem>
- <para>
- <literal>labelBackgroundPaint</literal> — The color used to draw the
- background of the section labels. If this is null, the background is not filled.
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>startAngle</literal> — The starting angle of the first
- section. </para>
- </listitem>
- <listitem>
- <para>
- <literal>circular</literal> — A boolean value indicating that the chart
- should be drawn as a circle. If false, the chart is drawn as an ellipse. The
- default is true. </para>
- </listitem>
- <listitem>
- <para>
- <literal>direction</literal> — The direction the pie section are drawn.
- One of: <literal>clockwise</literal> or <literal>anticlockwise</literal>. The
- default is <literal>clockwise</literal>. </para>
- </listitem>
- <listitem>
- <para>
- <literal>sectionOutlinePaint</literal> — The outline paint for all
- sections. </para>
- </listitem>
- <listitem>
- <para>
- <literal>sectionOutlineStroke</literal> — The outline stroke for all
- sections </para>
- </listitem>
- <listitem>
- <para>
- <literal>sectionOutlinesVisible</literal> — Indicates whether an
- outline is drawn for each section in the plot. </para>
- </listitem>
- <listitem>
- <para>
- <literal>baseSectionOutlinePaint</literal> — The base section outline
- paint. </para>
- </listitem>
- <listitem>
- <para>
- <literal>baseSectionPaint</literal> — The base section paint. </para>
- </listitem>
- <listitem>
- <para>
- <literal>baseSectionOutlineStroke</literal> — The base section outline
- stroke. </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:piechart title="Pie Chart" circular="false" direction="anticlockwise"
- startAngle="30" labelGap="0.1" labelLinkPaint="red">
- <p:series key="Prices">
- <p:data key="2003" columnKey="2003" value="7.36" />
- <p:data key="2004" columnKey="2004" value="11.50" />
- <p:data key="2005" columnKey="2005" value="34.625" />
- <p:data key="2006" columnKey="2006" value="76.30" />
- <p:data key="2007" columnKey="2007" value="85.05" />
- </p:series>
-</p:piechart>]]></programlisting>
-
- </entry>
- </row>
-
-
-
- <row>
- <entry valign="top">
- <para>
- <literal><p:series></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>Category data can be broken down into series. The series tag is used to categorize a
- set of data with a series and apply styling to the entire series. </para>
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- <literal>key</literal> — The series name. </para>
- </listitem>
- <!--
- <listitem>
- <para>
- <literal>seriesFillPaint</literal> —
- </para>
- </listitem>
- -->
- <listitem>
- <para>
- <literal>seriesPaint</literal> — The color of each item in the series
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>seriesOutlinePaint</literal> — The outline color for each
- item in the series. </para>
- </listitem>
- <listitem>
- <para>
- <literal>seriesOutlineStroke</literal> — The stroke used to draw each
- item in the series. </para>
- </listitem>
- <!--
- <listitem>
- <para>
- <literal>seriesStroke</literal>
- </para>
- </listitem>
- -->
- <listitem>
- <para>
- <literal>seriesVisible</literal> — A boolean indicating if the series
- should be displayed. </para>
- </listitem>
- <listitem>
- <para>
- <literal>seriesVisibleInLegend</literal> — A boolean indicating if
- the series should be listed in the legend. </para>
- </listitem>
-
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:series key="data1">
- <ui:repeat value="#{data.pieData1}" var="item">
- <p:data columnKey="#{item.name}" value="#{item.value}" />
- </ui:repeat>
-</p:series>]]></programlisting>
-
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:data></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>The data tag describes each data point to be displayed in the graph.</para>
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>key</literal> — The name of the data item. </para>
- </listitem>
- <listitem>
- <para>
- <literal>series</literal> — The series name, when not embedded inside
- a <code><p:series></code>. </para>
- </listitem>
- <listitem>
- <para>
- <literal>value</literal> — The numeric data value. </para>
- </listitem>
- <listitem>
- <para>
- <literal>explodedPercent</literal> — For pie charts, indicates how
- exploded a from the pie a piece is. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>sectionOutlinePaint</literal> — For bar charts, the color of
- the section outline.</para>
- </listitem>
- <listitem>
- <para>
- <literal>sectionOutlineStroke</literal> — For bar charts, the stroke
- type for the section outline.</para>
- </listitem>
- <listitem>
- <para>
- <literal>sectionPaint</literal> — For bar charts, the color of the
- section.</para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
-
-
-
- <programlisting role="XHTML"><![CDATA[<p:data key="foo" value="20" sectionPaint="#111111"
- explodedPercent=".2" />
-<p:data key="bar" value="30" sectionPaint="#333333" />
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:data>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ The data tag describes each data point to be displayed in the graph.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>key</literal> — The name of the data item.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>series</literal> — The series name, when not embedded inside a <code><![CDATA[<p:series>]]></code>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>value</literal> — The numeric data value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>explodedPercent</literal> — For pie charts, indicates how exploded from the pie a piece is.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>sectionOutlinePaint</literal> — For bar charts, the color of the section outline.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>sectionOutlineStroke</literal> — For bar charts, the stroke type for the section outline.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>sectionPaint</literal> — For bar charts, the color of the section.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:data key="foo" value="20" sectionPaint="#111111" explodedPercent=".2" />
+<p:data key="bar" value="30" sectionPaint="#333333" />
<p:data key="baz" value="40" sectionPaint="#555555"
- sectionOutlineStroke="my-dot-style" />]]></programlisting>
+ sectionOutlineStroke="my-dot-style" />]]>
+</programlisting>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:color></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>The color component declares a color or gradient than can be referenced when drawing
- filled shapes. </para>
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- <literal>color</literal> — The color value. For gradient colors, this
- the starting color. <xref linkend="itext.colors"/>
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>color2</literal> — For gradient colors, this is the color
- that ends the gradient. </para>
- </listitem>
- <listitem>
- <para>
- <literal>point</literal> — The co-ordinates where the gradient color
- begins. </para>
- </listitem>
- <listitem>
- <para>
- <literal>point2</literal> — The co-ordinates where the gradient color
- ends. </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:color id="foo" color="#0ff00f"/>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:color>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ The color component declares a color or gradient for filled shapes.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>color</literal> — The color value. For gradient colors, this indicates the starting color. See <xref linkend="itext.colors" /> for color values.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>color2</literal> — For gradient colors, this is the color that ends the gradient.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>point</literal> — The coordinates that mark the beginning of the gradient color.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>point2</literal> — The coordinates that mark the end of the gradient color.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:color id="foo" color="#0ff00f"/>
<p:color id="bar" color="#ff00ff" color2="#00ff00"
- point="50 50" point2="300 300"/>]]></programlisting>
+ point="50 50" point2="300 300"/>]]>
+</programlisting>
- </entry>
- </row>
- <row>
- <entry valign="top">
- <para>
- <literal><p:stroke></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>Describes a stroke used to draw lines in a chart.</para>
- <para>
- <emphasis>Attributes</emphasis>
- </para>
+ </row>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:stroke>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Describes a stroke used to draw lines in a chart.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>width</literal> — The width of the stroke.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>cap</literal> — The line cap type. Valid values are <literal>butt</literal>, <literal>round</literal> and <literal>square</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>join</literal> — The line join type. Valid values are <literal>miter</literal>, <literal>round</literal> and <literal>bevel</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>miterLimit</literal> — For miter joins, this value is the limit of the size of the join.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>dash</literal> — The dash value sets the dash pattern used to draw the line. Use space-separated integers to indicate the length of each alternating drawn and undrawn segment.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>dashPhase</literal> — The dash phase indicates the point in the dash pattern that corresponds to the beginning of the stroke.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:stroke id="dot2" width="2" cap="round" join="bevel" dash="2 3" />]]>
+</programlisting>
- <itemizedlist>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="itext.barcodes">
+ <title>Bar codes</title>
+ <para>
+ Seam can use iText to generate barcodes in a wide variety of formats. These barcodes can be embedded in a PDF document or displayed as an image on a web page. However, barcodes cannot currently display barcode text when used with HTML images.
+ </para>
+ <informaltable id="itext.barcode">
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:barCode>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Displays a barcode image.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>type</literal> — A barcode type supported by iText. Valid values include: <literal>EAN13</literal>, <literal>EAN8</literal>, <literal>UPCA</literal>, <literal>UPCE</literal>, <literal>SUPP2</literal>, <literal>SUPP5</literal>, <literal>POSTNET</literal>, <literal>PLANET</literal>, <literal>CODE128</literal>, <literal>CODE128_UCC</literal>, <literal>CODE128_RAW</literal> and <literal>CODABAR</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>code</literal> — The value to be encoded by the barcode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>xpos</literal> — For PDFs, the absolute <literal>x</literal> position of the barcode on the page.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ypos</literal> — For PDFs, the absolute <literal>y</literal> position of the barcode on the page.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>rotDegrees</literal> — For PDFs, the rotation factor of the barcode in degrees.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>barHeight</literal> — The height of the bars in the barcode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>minBarWidth</literal> — The minimum bar width.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>barMultiplier</literal> — The bar multiplier for wide bars or the distance between bars for <literal>POSTNET</literal> and <literal>PLANET</literal> code.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>barColor</literal> — The color the bars should be drawn in.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>textColor</literal> — The color of any text on the barcode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>textSize</literal> — The size of any text on the barcode.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>altText</literal> — The <literal>alt</literal> text for HTML image links.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:barCode type="code128" barHeight="80" textSize="20"
+ code="(10)45566(17)040301" codeType="code128_ucc"
+ altText="My BarCode" />]]>
+</programlisting>
- <listitem>
- <para>
- <literal>width</literal> — The width of the stroke. </para>
- </listitem>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="itext.fillinforms">
+ <title>Fill-in-forms</title>
+ <para>
+ If you have a complex, pre-generated PDF with named fields, you can easily populate it with values from your application and present it to the user.
+ </para>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:form>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Defines a form template to populate.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>URL</literal> — A URL that points to the PDF file to use as a template. If the value contains no protocol (<literal>://</literal>), the file is read locally.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>filename</literal> — The filename to use for the generated PDF file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>exportKey</literal> — If set, no redirect will occur when the generated PDF file is placed in a DocumentData object under the specified key in the event context.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ <informaltable>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:field>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Connects a field name to its value.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>name</literal> — The name of the field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>value</literal> — The value of the field.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>readOnly</literal> — Whether the field is read-only. The default is <literal>true</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+
+<programlisting role="XML"> <![CDATA[
+<p:form
+ xmlns:p="http://jboss.com/products/seam/pdf"
+ URL="http://localhost/Concept/form.pdf">
+ <p:field name="person.name" value="Me, myself and I"/>
+</p:form>]]>
+</programlisting>
+ </section>
+
+ <section id="itext.swingcomponents">
+ <title>Rendering Swing/AWT components</title>
+ <para>
+ Seam now provides experimental support to render Swing components into PDF images. Some Swing look and feel supports, specifically those that use native widgets, will not render correctly.
+ </para>
+ <informaltable id="itext.swing">
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <tbody>
+ <row>
+ <entry valign="top">
+ <para>
+ <literal><![CDATA[<p:swing>]]></literal>
+ </para>
+ </entry>
+ <entry valign="top">
+ <para>
+ <emphasis>Description</emphasis>
+ </para>
+ <para>
+ Renders a Swing component into a PDF document.
+ </para>
+ <para>
+ <emphasis>Attributes</emphasis>
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>width</literal> — The width of the component to be rendered.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>height</literal> — The height of the component to be rendered.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>component</literal> — An expression whose value is a Swing or AWT component.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ <emphasis>Usage</emphasis>
+ </para>
+ </entry>
+<programlisting role="XHTML"><![CDATA[<p:swing width="310" height="120" component="#{aButton}" />]]>
+</programlisting>
- <listitem>
- <para><literal>cap</literal> — The line cap type. Valid values are
- <literal>butt</literal>, <literal>round</literal> and
- <literal>square</literal></para>
- </listitem>
-
- <listitem>
- <para><literal>join</literal> — The line join type. Valid values are
- <literal>miter</literal>, <literal>round</literal> and
- <literal>bevel</literal></para>
- </listitem>
-
- <listitem>
- <para>
- <literal>miterLimit</literal> — For miter joins, this value is the
- limit of the size of the join. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>dash</literal> — The dash value sets the dash pattern to be
- used to draw the line. The space separated integers indicate the length of each
- alternating drawn and undrawn segments. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>dashPhase</literal> — The dash phase indicates the offset
- into the dash pattern that the line should be drawn with. </para>
- </listitem>
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:stroke id="dot2" width="2" cap="round" join="bevel" dash="2 3" />]]></programlisting>
-
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
-
-
-
-
-
- <section id="itext.barcodes">
- <title>Bar codes</title>
- <para>Seam can use iText to generate barcodes in a wide variety of formats. These barcodes can
- be embedded in a PDF document or displayed as an image on a web page. Note that
- when used with HTML images, barcodes can not currently display barcode text in the barcode.
- </para>
-
- <informaltable id="itext.barcode">
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*"/>
- <colspec colnum="2" colwidth="3*"/>
-
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><p:barCode></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>Displays a barcode image.</para>
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- <literal>type</literal> — A barcode type supported by iText. Valid
- values include: <literal>EAN13</literal>, <literal>EAN8</literal>,
- <literal>UPCA</literal>, <literal>UPCE</literal>, <literal>SUPP2</literal>,
- <literal>SUPP5</literal>, <literal>POSTNET</literal>,
- <literal>PLANET</literal>, <literal>CODE128</literal>,
- <literal>CODE128_UCC</literal>, <literal>CODE128_RAW</literal> and
- <literal>CODABAR</literal>. </para>
- </listitem>
- <listitem>
- <para>
- <literal>code</literal> — The value to be encoded by the barcode.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>xpos</literal> — For PDFs, the absolute y position of the
- barcode on the page. </para>
- </listitem>
- <listitem>
- <para>
- <literal>ypos</literal> — For PDFs, the absolute y position of the
- barcode on the page. </para>
- </listitem>
- <listitem>
- <para>
- <literal>rotDegrees</literal> — For PDFs, the rotation factor of the
- barcode in degrees. </para>
- </listitem>
- <listitem>
- <para>
- <literal>barHeight</literal> — The height of the bars in the barCode
- </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>minBarWidth</literal> — The minimum bar width. </para>
- </listitem>
- <listitem>
- <para>
- <literal>barMultiplier</literal> — The bar multiplier for wide bars or
- the distance between bars for <literal>POSTNET</literal> and
- <literal>PLANET</literal> code. </para>
- </listitem>
- <listitem>
- <para>
- <literal>barColor</literal> — The color to draw the bars. </para>
- </listitem>
-
- <listitem>
- <para>
- <literal>textColor</literal> — The color of any text on the barcode.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>textSize</literal> — The size of the barcode text, if any.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>altText</literal> — The <literal>alt</literal> text for HTML image links.
- </para>
- </listitem>
-
-
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:barCode type="code128"
- barHeight="80"
- textSize="20"
- code="(10)45566(17)040301"
- codeType="code128_ucc"
- altText="My BarCode" />]]></programlisting>
-
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
-
- <section id="itext.fillinforms">
- <title>Fill-in-forms</title>
- <para>
- If you have a complex, pre-generated PDF with named fields, you can easily
- fill in the values from your application and present it to the user.
- </para>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*"/>
- <colspec colnum="2" colwidth="3*"/>
-
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><p:form></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>Defines a form template to populate</para>
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>URL</literal> — An URL pointing
- to the PDF file to use as a template. If the value
- has no protocol part (://), the file is read locally.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>filename</literal> — The filename
- to use for the generated PDF file.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>exportKey</literal> — Place the generated
- PDF file in a DocumentData object under the specified key
- in the event context. If set, no redirect will occur.
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <informaltable>
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*"/>
- <colspec colnum="2" colwidth="3*"/>
-
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><p:field></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
- <para>Connects a field name to its value</para>
-
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- <literal>name</literal> — The name
- of the field
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>value</literal> — The value
- of the field
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>readOnly</literal> — Should the field
- be read-only? Defaults to true.
- </para>
- </listitem>
- </itemizedlist>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
-
- <programlisting role="XML">
- <![CDATA[
- <p:form
- xmlns:p="http://jboss.com/products/seam/pdf"
- URL="http://localhost/Concept/form.pdf">
- <p:field name="person.name" value="Me, myself and I"/>
- </p:form>
- ]]>
- </programlisting>
- </section>
-
-
- <section id="itext.swingcomponents">
- <title>Rendering Swing/AWT components</title>
- <para>Seam now provides experimental support for rendering Swing components to into a PDF
- image. Some Swing look and feels supports, notably ones that use native widgets, will not
- render correctly.
- </para>
-
- <informaltable id="itext.swing">
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*"/>
- <colspec colnum="2" colwidth="3*"/>
-
- <tbody>
- <row>
- <entry valign="top">
- <para>
- <literal><p:swing></literal>
- </para>
- </entry>
- <entry valign="top">
- <para>
- <emphasis>Description</emphasis>
- </para>
-
- <para>Renders a Swing component into a PDF document.</para>
- <para>
- <emphasis>Attributes</emphasis>
- </para>
-
- <itemizedlist>
-
- <listitem>
- <para>
- <literal>width</literal> — The width of the component to be rendered. </para>
- </listitem>
- <listitem>
- <para>
- <literal>height</literal> — The height of the component to be rendered. </para>
- </listitem>
- <listitem>
- <para>
- <literal>component</literal> — An expression whose value is a Swing or AWT component. </para>
- </listitem>
-
- </itemizedlist>
- <para>
- <emphasis>Usage</emphasis>
- </para>
- <programlisting role="XHTML"><![CDATA[<p:swing width="310" height="120" component="#{aButton}" />]]></programlisting>
-
- </entry>
- </row>
- </tbody>
- </tgroup>
- </informaltable>
- </section>
-
-
- <section id="itext.configuration">
- <title>Configuring iText</title>
-
- <para>Document generation works out of the box with no additional configuration needed. However, there are a
- few points of configuration that are needed for more serious applications. </para>
-
- <para> The default implementation serves PDF documents from a generic URL,
- <literal>/seam-doc.seam</literal>. Many browsers (and users) would prefer to see URLs that contain the
- actual PDF name like <literal>/myDocument.pdf</literal>. This capability requires some configuration. To
- serve PDF files, all <literal>*.pdf</literal> resources should be mapped to the DocumentStoreServlet:</para>
-
- <programlisting role="XML"><![CDATA[<servlet>
- <servlet-name>Document Store Servlet</servlet-name>
- <servlet-class>org.jboss.seam.document.DocumentStoreServlet</servlet-class>
-</servlet>
-
-<servlet-mapping>
- <servlet-name>Document Store Servlet</servlet-name>
- <url-pattern>*.pdf</url-pattern>
-</servlet-mapping>]]></programlisting>
-
- <para> The <literal>use-extensions</literal> option on the document store component completes the
- functionality by instructing the document store to generate URLs with the correct filename extension for
- the document type being generated. </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:document="http://jboss.com/products/seam/document"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://jboss.com/products/seam/document http://jboss.com/products/seam/document-2.2.xsd
- http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.2.xsd">
- <document:document-store use-extensions="true"/>
-</components>]]></programlisting>
-
- <para> The document store stores documents in conversation scope, and documents will expire when the conversation ends. At
- that point, references to the document will be invalid. You can specify a default view to be shown
- when a document does not exist using the <literal>error-page</literal> property of the <literal>documentStore</literal>. </para>
- <programlisting role="XML"><![CDATA[<document:document-store use-extensions="true" error-page="/documentMissing.seam" />]]></programlisting>
- </section>
-
- <section id="itext.links">
- <title>Further documentation</title>
-
- <para>For further information on iText, see:</para>
- <para>
- <itemizedlist>
- <listitem>
- <para>
- <ulink url="http://www.lowagie.com/iText/">iText Home Page</ulink>
- </para>
- </listitem>
- <listitem>
- <para>
- <ulink url="http://www.manning.com/lowagie/">iText in Action</ulink>
- </para>
- </listitem>
- </itemizedlist>
-
- </para>
- </section>
+ </row>
+ </tbody>
+ </tgroup>
+ </informaltable>
+ </section>
+
+ <section id="itext.configuration">
+ <title>Configuring iText</title>
+ <para>
+ Document generation itself requires no additional configuration, but some minor configuration can make your application more user-friendly.
+ </para>
+ <para>
+ The default implementation serves PDF documents from a generic URL, <literal>/seam-doc.seam</literal>. Many users would prefer to see a URL that contains the actual PDF name — <filename>/myDocument.pdf</filename>, for example — which requires some configuration. To serve PDF files, all <filename>*.pdf</filename> resources must be mapped to the <literal>DocumentStoreServlet</literal>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<servlet>
+ <servlet-name>Document Store Servlet</servlet-name>
+ <servlet-class>
+ org.jboss.seam.document.DocumentStoreServlet
+ </servlet-class>
+</servlet>
+<servlet-mapping>
+ <servlet-name>Document Store Servlet</servlet-name>
+ <url-pattern>*.pdf</url-pattern>
+</servlet-mapping>]]>
+</programlisting>
+ <para>
+ The <literal>use-extensions</literal> option instructs the DocumentStore component to generate URLs with the correct filename extension for the generated document type.
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:document="http://jboss.com/products/seam/document"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://jboss.com/products/seam/document
+ http://jboss.com/products/seam/document-2.2.xsd
+ http://jboss.com/products/seam/components
+ http://jboss.com/products/seam/components-2.2.xsd">
+ <document:document-store use-extensions="true"/>
+</components>]]>
+</programlisting>
+ <para>
+ The DocumentStore holds documents in conversation scope, so documents will expire when the conversation ends. At that point, references to the document will be invalid. Specify a default view to show when a document does not exist by editing the <literal>error-page</literal> property of <literal>documentStore</literal>.
+ </para>
+
+<programlisting role="XML"><![CDATA[<document:document-store use-extensions="true"
+ error-page="/documentMissing.seam" />]]>
+</programlisting>
+ </section>
+
+ <section id="itext.links">
+ <title>Further documentation</title>
+ <para>
+ For further information on iText, see:
+ </para>
+ <para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <ulink url="http://www.lowagie.com/iText/">iText Home Page</ulink>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <ulink url="http://www.manning.com/lowagie/">iText in Action</ulink>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </para>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Jbpm.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Jbpm.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Jbpm.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,865 +1,629 @@
-<chapter id="jbpm">
- <title>Pageflows and business processes</title>
-
- <para>
- JBoss jBPM is a business process management engine for any Java SE or EE
- environment. jBPM lets you represent a business process or user
- interaction as a graph of nodes representing wait states, decisions,
- tasks, web pages, etc. The graph is defined using a simple, very readable,
- XML dialect called jPDL, and may be edited and visualised graphically using
- an eclipse plugin. jPDL is an extensible language, and is suitable for
- a range of problems, from defining web application page flow, to traditional
- workflow management, all the way up to orchestration of services in a SOA
- environment.
- </para>
-
- <para>
- Seam applications use jBPM for two different problems:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Defining the pageflow involved in complex user interactions. A jPDL
- process definition defines the page flow for a single conversation.
- A Seam conversation is considered to be a relatively short-running
- interaction with a single user.
- </para>
- </listitem>
- <listitem>
- <para>
- Defining the overarching business process. The business process may span
- multiple conversations with multiple users. Its state is persistent in
- the jBPM database, so it is considered long-running. Coordination of
- the activities of multiple users is a much more complex problem than
- scripting an interaction with a single user, so jBPM offers sophisticated
- facilities for task management and dealing with multiple concurrent paths
- of execution.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Don't get these two things confused! They operate at very different levels
- or granularity. <emphasis>Pageflow</emphasis>, <emphasis>conversation</emphasis>
- and <emphasis>task</emphasis> all refer to a single
- interaction with a single user. A business process spans many tasks.
- Futhermore, the two applications of jBPM are totally orthogonal. You can
- use them together or independently or not at all.
- </para>
-
- <para>
- You don't have to know jDPL to use Seam. If you're perfectly happy defining
- pageflow using JSF or Seam navigation rules, and if your application is more
- data-driven that process-driven, you probably don't need jBPM. But we're
- finding that thinking of user interaction in terms of a well-defined graphical
- representation is helping us build more robust applications.
- </para>
-
- <section>
- <title>Pageflow in Seam</title>
- <para>
- There are two ways to define pageflow in Seam:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Using JSF or Seam navigation rules - the <emphasis>stateless navigation
- model</emphasis>
- </para>
- </listitem>
- <listitem>
- <para>
- Using jPDL - the <emphasis>stateful navigation model</emphasis>
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Very simple applications will only need the stateless navigation
- model. Very complex applications will use both models in different
- places. Each model has its strengths and weaknesses!
- </para>
-
- <section>
- <title>The two navigation models</title>
-
- <para>
- The stateless model defines a mapping from a set of named, logical
- outcomes of an event directly to the resulting page of the view.
- The navigation rules are entirely oblivious to any state held by
- the application other than what page was the source of the event.
- This means that your action listener methods must sometimes make
- decisions about the page flow, since only they have access to the
- current state of the application.
- </para>
-
- <para>
- Here is an example page flow definition using JSF navigation
- rules:
- </para>
-
- <programlisting role="XML"><![CDATA[<navigation-rule>
- <from-view-id>/numberGuess.jsp</from-view-id>
-
- <navigation-case>
- <from-outcome>guess</from-outcome>
- <to-view-id>/numberGuess.jsp</to-view-id>
- <redirect/>
- </navigation-case>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- <navigation-case>
- <from-outcome>win</from-outcome>
- <to-view-id>/win.jsp</to-view-id>
- <redirect/>
- </navigation-case>
+<chapter id="jbpm" >
+ <title>Pageflows and business processes</title>
+ <para>
+ JBoss jBPM is a business process management engine for any Java SE or EE environment. jBPM represents a business process or user interaction as a graph of nodes representing wait states, decisions, tasks, web pages, etc. The graph is defined with a simple, very readable XML dialect called jPDL, and can be edited and represented graphically using an Eclipse plugin. jPDL is an extensible language, suitable for a range of problems, from defining web application pageflow, to managing traditional workflow, all the way up to orchestrating services in a SOA environment.
+ </para>
+ <para>
+ Seam applications use jBPM for two different problems: defining pageflow in complex user interactions, and defining the overarching business process.
+ </para>
+ <para>
+ For the former, a jPDL process definition defines the pageflow for a single conversation, whereas a Seam conversation is considered to be a relatively short-running interaction with a single user.
+ </para>
+ <para>
+ For the latter, the business process may span multiple conversations with multiple users. Its state is persistent in the jBPM database, so it is considered long-running. Coordinating the activities of multiple users is more complex than scripting interaction with a single user, so jBPM offers sophisticated facilities for managing tasks and multiple concurrent execution paths.
+ </para>
+ <note>
+ <para>
+ Do not confuse pageflow with the overarching business process. They operate at different levels of granularity. Pageflows, conversations, and tasks are all single interactions with a single user. A business process spans many tasks. Furthermore, the two applications of jBPM are not dependent upon each other — you can use them together, independently, or not at all.
+ </para>
+ </note>
+ <note>
+ <para>
+ It is not necessary to know jPDL to use Seam. If you prefer to define pageflow with JSF or Seam navigation rules, and your application is more data-driven than process-driven, jBPM is probably unnecessary. However, we find that thinking of user interaction in terms of a well-defined graphical representation helps us create more robust applications.
+ </para>
+ </note>
+ <section>
+ <title>Pageflow in Seam</title>
+ <para>
+ There are two ways to define pageflow in Seam:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Using JavaServer Faces (JSF) or Seam navigation rules — the <emphasis>stateless navigation model</emphasis>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Using jPDL — the <emphasis>stateful navigation model</emphasis>
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Simple applications will only require the stateless navigation model. Complex applications will use a combination of the two. Each model has its strengths and weaknesses, and should be implemented accordingly.
+ </para>
+ <section>
+ <title>The two navigation models</title>
+ <para>
+ The stateless model defines a mapping from a set of named, logical event outcomes directly to the resulting view page. The navigation rules ignore any state held by the application, other than the page from which the event originates. Therefore, action listener methods must sometimes make decisions about the pageflow, since only they have access to the current state of the application.
+ </para>
+ <para>
+ Here is an example pageflow definition using JSF navigation rules:
+ </para>
+
+<programlisting role="XML"><![CDATA[<navigation-rule>
+ <from-view-id>/numberGuess.jsp</from-view-id>
- <navigation-case>
- <from-outcome>lose</from-outcome>
- <to-view-id>/lose.jsp</to-view-id>
- <redirect/>
- </navigation-case>
+ <navigation-case>
+ <from-outcome>guess</from-outcome>
+ <to-view-id>/numberGuess.jsp</to-view-id>
+ <redirect/>
+ </navigation-case>
-</navigation-rule>]]></programlisting>
-
- <para>
- Here is the same example page flow definition using Seam navigation
- rules:
- </para>
+ <navigation-case>
+ <from-outcome>win</from-outcome>
+ <to-view-id>/win.jsp</to-view-id>
+ <redirect/>
+ </navigation-case>
- <programlisting role="XML"><![CDATA[<page view-id="/numberGuess.jsp">
-
- <navigation>
- <rule if-outcome="guess">
- <redirect view-id="/numberGuess.jsp"/>
- </rule>
- <rule if-outcome="win">
- <redirect view-id="/win.jsp"/>
- </rule>
- <rule if-outcome="lose">
- <redirect view-id="/lose.jsp"/>
- </rule>
- </navigation>
-
-</page>]]></programlisting>
-
- <para>
- If you find navigation rules overly verbose, you can return view ids
- directly from your action listener methods:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public String guess() {
- if (guess==randomNumber) return "/win.jsp";
- if (++guessCount==maxGuesses) return "/lose.jsp";
- return null;
-}]]></programlisting>
-
- <para>
- Note that this results in a redirect. You can even specify parameters
- to be used in the redirect:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public String search() {
- return "/searchResults.jsp?searchPattern=#{searchAction.searchPattern}";
-}]]></programlisting>
-
- <para>
- The stateful model defines a set of transitions between a set of
- named, logical application states. In this model, it is possible
- to express the flow of any user interaction entirely in the jPDL
- pageflow definition, and write action listener methods that are
- completely unaware of the flow of the interaction.
- </para>
-
- <para>
- Here is an example page flow definition using jPDL:
- </para>
-
- <programlisting role="XML"><![CDATA[<pageflow-definition name="numberGuess">
+ <navigation-case>
+ <from-outcome>lose</from-outcome>
+ <to-view-id>/lose.jsp</to-view-id>
+ <redirect/>
+ </navigation-case>
+
+</navigation-rule>]]>
+</programlisting>
+ <para>
+ Here is the same example pageflow definition using Seam navigation rules:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/numberGuess.jsp">
+ <navigation>
+
+ <rule if-outcome="guess">
+ <redirect view-id="/numberGuess.jsp"/>
+ </rule>
- <start-page name="displayGuess" view-id="/numberGuess.jsp">
- <redirect/>
- <transition name="guess" to="evaluateGuess">
- <action expression="#{numberGuess.guess}" />
- </transition>
- </start-page>
+ <rule if-outcome="win">
+ <redirect view-id="/win.jsp"/>
+ </rule>
+
+ <rule if-outcome="lose">
+ <redirect view-id="/lose.jsp"/>
+ </rule>
+
+ </navigation>
+</page>]]>
+</programlisting>
+ <para>
+ If you find navigation rules too verbose, you can return view IDs directly from your action listener methods:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public String guess() {
+ if (guess==randomNumber) return "/win.jsp";
+ if (++guessCount==maxGuesses) return "/lose.jsp";
+ return null;
+}]]>
+</programlisting>
+ <para>
+ Note that this results in a redirect. You can also specify parameters to be used in the redirect:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public String search() {
+ return "/searchResults.jsp?searchPattern=#{searchAction.searchPattern}";
+}]]>
+</programlisting>
+ <para>
+ The stateful model defines a set of transitions between a set of named, logical application states. With this model, you can express the flow of any user interaction entirely in the jPDL pageflow definition, and write action listener methods that are completely unaware of the flow of the interaction.
+ </para>
+ <para>
+ Here is an example page flow definition using jPDL:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pageflow-definition name="numberGuess">
+ <start-page name="displayGuess" view-id="/numberGuess.jsp">
+ <redirect/>
+ <transition name="guess" to="evaluateGuess">
+ <action expression="#{numberGuess.guess}" />
+ </transition>
+ </start-page>
- <decision name="evaluateGuess" expression="#{numberGuess.correctGuess}">
- <transition name="true" to="win"/>
- <transition name="false" to="evaluateRemainingGuesses"/>
- </decision>
+ <decision name="evaluateGuess" expression="#{numberGuess.correctGuess}">
+ <transition name="true" to="win"/>
+ <transition name="false" to="evaluateRemainingGuesses"/>
+ </decision>
- <decision name="evaluateRemainingGuesses" expression="#{numberGuess.lastGuess}">
- <transition name="true" to="lose"/>
- <transition name="false" to="displayGuess"/>
- </decision>
+ <decision name="evaluateRemainingGuesses"
+ expression="#{numberGuess.lastGuess}">
+ <transition name="true" to="lose"/>
+ <transition name="false" to="displayGuess"/>
+ </decision>
- <page name="win" view-id="/win.jsp">
- <redirect/>
- <end-conversation />
- </page>
+ <page name="win" view-id="/win.jsp">
+ <redirect/>
+ <end-conversation />
+ </page>
- <page name="lose" view-id="/lose.jsp">
- <redirect/>
- <end-conversation />
- </page>
-
-</pageflow-definition>]]></programlisting>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/plugin-jbpm-numguess.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/plugin-jbpm-numguess.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>
- There are two things we notice immediately here:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- The JSF/Seam navigation rules are <emphasis>much</emphasis> simpler.
- (However, this obscures the fact that the underlying Java code
- is more complex.)
- </para>
- </listitem>
- <listitem>
- <para>
- The jPDL makes the user interaction immediately understandable,
- without us needing to even look at the JSP or Java code.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- In addition, the stateful model is more <emphasis>constrained</emphasis>.
- For each logical state (each step in the page flow), there are a
- constrained set of possible transitions to other states. The stateless
- model is an <emphasis>ad hoc</emphasis> model which is suitable to
- relatively unconstrained, freeform navigation where the user decides
- where he/she wants to go next, not the application.
- </para>
-
- <para>
- The stateful/stateless navigation distinction is quite similar to
- the traditional view of modal/modeless interaction. Now, Seam
- applications are not usually modal in the simple sense of the
- word - indeed, avoiding application modal behavior is one of the
- main reasons for having conversations! However, Seam applications
- can be, and often are, modal at the level of a particular
- conversation. It is well-known that modal behavior is something
- to avoid as much as possible; it is very difficult to predict the
- order in which your users are going to want to do things! However,
- there is no doubt that the stateful model has its place.
- </para>
-
- <para>
- The biggest contrast between the two models is the back-button
- behavior.
- </para>
-
- </section>
-
- <section>
- <title>Seam and the back button</title>
-
- <para>
- When JSF or Seam navigation rules are used, Seam lets the user freely
- navigate via the back, forward and refresh buttons. It is the
- responsibility of the application to ensure that conversational
- state remains internally consistent when this occurs. Experience
- with the combination of web application frameworks like Struts
- or WebWork - that do not support a conversational model - and
- stateless component models like EJB stateless session beans
- or the Spring framework has taught many developers that this is
- close to impossible to do! However, our experience is that in
- the context of Seam, where there is a well-defined conversational
- model, backed by stateful session beans, it is actually quite
- straightforward. Usually it is as simple as combining the use
- of <literal>no-conversation-view-id</literal> with null
- checks at the beginning of action listener methods. We consider
- support for freeform navigation to be almost always desirable.
- </para>
-
- <para>
- In this case, the <literal>no-conversation-view-id</literal>
- declaration goes in <literal>pages.xml</literal>. It tells
- Seam to redirect to a different page if a request originates
- from a page rendered during a conversation, and that conversation
- no longer exists:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/checkout.xhtml"
- no-conversation-view-id="/main.xhtml"/>]]></programlisting>
-
- <para>
- On the other hand, in the stateful model, using the back button is
- interpreted as an undefined transition back to a previous state.
- Since the stateful model enforces a defined set of transitions
- from the current state, the back button is not permitted by default
- in the stateful model! Seam transparently detects the use of the
- back button, and blocks any attempt to perform an action from
- a previous, "stale" page, and simply redirects the user to
- the "current" page (and displays a faces message). Whether you
- consider this a feature or a limitation of the stateful model
- depends upon your point of view: as an application developer,
- it is a feature; as a user, it might be frustrating! You can
- enable backbutton navigation from a particular page node by
- setting <literal>back="enabled"</literal>.
- </para>
-
- <programlisting role="XML"><![CDATA[<page name="checkout"
- view-id="/checkout.xhtml"
- back="enabled">
+ <page name="lose" view-id="/lose.jsp">
<redirect/>
- <transition to="checkout"/>
- <transition name="complete" to="complete"/>
-</page>]]></programlisting>
-
- <para>
- This allows navigation via the back button <emphasis>from</emphasis>
- the <literal>checkout</literal> state to <emphasis>any previous
- state!</emphasis>
- </para>
-
- <note>
- If a page is set to redirect after a transition, it is not possible
- to use the back button to return to that page even when back is
- enabled on a page later in the flow. The reason is because Seam
- stores information about the pageflow in the page scope and the back
- button must result in a POST for that information to be restored
- (i.e., a Faces request). A redirect severs this linkage.
- </note>
-
- <para>
- Of course, we still need to define what happens if a request
- originates from a page rendered during a pageflow, and the
- conversation with the pageflow no longer exists. In this case,
- the <literal>no-conversation-view-id</literal> declaration
- goes into the pageflow definition:
- </para>
-
- <programlisting role="XML"><![CDATA[<page name="checkout"
- view-id="/checkout.xhtml"
- back="enabled"
- no-conversation-view-id="/main.xhtml">
- <redirect/>
- <transition to="checkout"/>
- <transition name="complete" to="complete"/>
-</page>]]></programlisting>
-
-
- <para>
- In practice, both navigation models have their place, and you'll
- quickly learn to recognize when to prefer one model over the other.
- </para>
-
- </section>
- </section>
-
- <section>
- <title>Using jPDL pageflows</title>
-
- <section>
- <title>Installing pageflows</title>
-
- <para>
- We need to install the Seam jBPM-related components, and place the
- pageflow definitions (using the standard <literal>.jpdl.xml</literal>
- extension) inside a Seam archive (an archive which
- contains a <literal>seam.properties</literal> file):
- </para>
-
- <programlisting role="XML"><![CDATA[<bpm:jbpm />]]></programlisting>
-
- <para>
- We can also explicitly tell Seam where to find our pageflow
- definition. We specify this in <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<bpm:jbpm>
- <bpm:pageflow-definitions>
- <value>pageflow.jpdl.xml</value>
- </bpm:pageflow-definitions>
-</bpm:jbpm>]]></programlisting>
-
- </section>
-
- <section>
- <title>Starting pageflows</title>
-
- <para>
- We "start" a jPDL-based pageflow by specifying the name of the
- process definition using a <literal>@Begin</literal>,
- <literal>@BeginTask</literal> or <literal>@StartTask</literal>
- annotation:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Begin(pageflow="numberguess")
-public void begin() { ... }]]></programlisting>
-
- <para>Alternatively we can start a pageflow using pages.xml:</para>
+ <end-conversation />
+ </page>
+
+</pageflow-definition>]]>
+</programlisting>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/plugin-jbpm-numguess.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/plugin-jbpm-numguess.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ Here, we notice two things immediately:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The JSF and Seam navigation rules are much simpler. (However, this obscures the fact that the underlying Java code is more complex.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The jPDL makes the user interaction immediately comprehensible, and removes the need to look at JSP or Java code.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ In addition, the stateful model is more constrained. For each logical state (each step in the pageflow), there are a constrained set of possible transitions to other states. The stateless model is an <emphasis>ad hoc</emphasis> model, suitable to relatively unconstrained, freeform navigation where the user decides where he/she wants to go next, not the application.
+ </para>
+ <para>
+ The distinction between stateful and stateless navigation is similar to that between modal and modeless interaction. Seam applications are not usually modal in the simple sense of the word — we use conversations to avoid modal behavior. However, Seam applications can be, and often are, modal at the level of a particular conversation. Because user movements are not perfectly predictable, modal behavior is best avoided, but it has its place in the stateful model.
+ </para>
+ <para>
+ The biggest contrast between the two models is the back-button behavior.
+ </para>
+ </section>
- <programlisting role="XML"><![CDATA[<page>
- <begin-conversation pageflow="numberguess"/>
- </page>]]></programlisting>
-
- <para>
- If we are beginning the pageflow during the <literal>RENDER_RESPONSE</literal>
- phase — during a <literal>@Factory</literal> or <literal>@Create</literal>
- method, for example — we consider ourselves to be already at the page being
- rendered, and use a <literal><start-page></literal> node as the first node
- in the pageflow, as in the example above.
- </para>
-
- <para>
- But if the pageflow is begun as the result of an action listener invocation,
- the outcome of the action listener determines which is the first page to be
- rendered. In this case, we use a <literal><start-state></literal> as
- the first node in the pageflow, and declare a transition for each possible
- outcome:
- </para>
-
- <programlisting role="XML"><![CDATA[<pageflow-definition name="viewEditDocument">
-
- <start-state name="start">
- <transition name="documentFound" to="displayDocument"/>
- <transition name="documentNotFound" to="notFound"/>
- </start-state>
+ <section>
+ <title>Seam and the back button</title>
+ <para>
+ With JSF or Seam navigation rules, the user can navigate freely with the back, forward and refresh buttons. The application is responsible for ensuring that conversational state remains internally consistent. Experience with web application frameworks and stateless component models has taught developers how difficult this is. It becomes far more straightforward in Seam, where it sits in a well-defined conversational model backed by stateful session beans. Usually, you need only combine a <literal>no-conversation-view-id</literal> with null checks at the beginning of action listener methods. Freeform navigation support is almost always desirable.
+ </para>
+ <para>
+ In this case, the <literal>no-conversation-view-id</literal> declaration goes in <filename>pages.xml</filename>. This tells Seam to redirect to a different page if a request originates from a page that was rendered during a conversation that no longer exists:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/checkout.xhtml" no-conversation-view-id="/main.xhtml"/>]]>
+</programlisting>
+ <para>
+ On the other hand, in the stateful model, the back button is interpreted as an undefined transition back to a previous state. Since the stateful model enforces a defined set of transitions from the current state, the back button is, by default, not permitted in the stateful model. Seam transparently detects the use of the back button, and blocks any attempt to perform an action from a previous, "stale" page, redirecting the user to the "current" page (and displaying a Faces message). Although developers view this as a feature, it can be frustrating from the user's perspective. You can enable back button navigation from a particular page node by setting <literal>back="enabled"</literal>.
+ </para>
+
+<programlisting role="XML"><![CDATA[<page name="checkout" view-id="/checkout.xhtml" back="enabled">
+ <redirect/>
+ <transition to="checkout"/>
+ <transition name="complete" to="complete"/>
+</page>]]>
+</programlisting>
+ <para>
+ This allows navigation via the back button from the <literal>checkout</literal> state to any previous state.
+ </para>
+ <note>
+ <para>
+ If a page is set to redirect after a transition, the back button cannot return a user to that page even when back is enabled on a page later in the flow. This is because Seam stores information about the pageflow in the page scope and the back button must result in a POST for that information to be restored (for example, through a Faces request). A redirect severs this link.
+ </para>
+ </note>
+ <para>
+ We must still define what happens if a request originates from a page rendered during a pageflow, and the conversation with the pageflow no longer exists. In this case, the <literal>no-conversation-view-id</literal> declaration goes into the pageflow definition:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page name="checkout" view-id="/checkout.xhtml" back="enabled"
+ no-conversation-view-id="/main.xhtml">
+ <redirect/>
+ <transition to="checkout"/>
+ <transition name="complete" to="complete"/>
+</page>]]>
+</programlisting>
+ <para>
+ In practice, both navigation models have their place, and you will quickly learn to recognize where one model is better-suited to a task.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Using jPDL pageflows</title>
+ <section>
+ <title>Installing pageflows</title>
+ <para>
+ We need to install the Seam jBPM-related components, and place the pageflow definitions (using the standard <filename>.jpdl.xml</filename> extension) inside a Seam archive (an archive containing a <filename>seam.properties</filename> file):
+ </para>
+
+<programlisting role="XML"><![CDATA[<bpm:jbpm />]]>
+</programlisting>
+ <para>
+ We can also explicitly tell Seam where to find our pageflow definition. We specify this in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<bpm:jbpm>
+ <bpm:pageflow-definitions>
+ <value>pageflow.jpdl.xml</value>
+ </bpm:pageflow-definitions>
+</bpm:jbpm>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Starting pageflows</title>
+ <para>
+ We "start" a jPDL-based pageflow by specifying the name of the process definition with a <literal>@Begin</literal>, <literal>@BeginTask</literal> or <literal>@StartTask</literal> annotation:
+ </para>
+
+<programlisting role="JAVA">@Begin(pageflow="numberguess") public void begin() { ... }
+</programlisting>
+ <para>
+ Alternatively, we can start a pageflow using <filename>pages.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page>
+ <begin-conversation pageflow="numberguess"/>
+</page>]]>
+</programlisting>
+ <para>
+ If we are beginning the pageflow during the <literal>RENDER_RESPONSE</literal> phase — during a <literal>@Factory</literal> or <literal>@Create</literal> method, for example — we consider ourselves already at the rendered page, and use a <literal><![CDATA[<start-page>]]></literal> node as the first node in the pageflow, as in the example above.
+ </para>
+ <para>
+ But if the pageflow is begun as the result of an action listener invocation, the outcome of the action listener determines the first page to be rendered. In this case, we use a <literal><![CDATA[<start-state>]]></literal> as the first node in the pageflow, and declare a transition for each possible outcome:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pageflow-definition name="viewEditDocument">
+ <start-state name="start">
+ <transition name="documentFound" to="displayDocument"/>
+ <transition name="documentNotFound" to="notFound"/>
+ </start-state>
- <page name="displayDocument" view-id="/document.jsp">
- <transition name="edit" to="editDocument"/>
- <transition name="done" to="main"/>
- </page>
+ <page name="displayDocument" view-id="/document.jsp">
+ <transition name="edit" to="editDocument"/>
+ <transition name="done" to="main"/>
+ </page>
- ...
+ ...
- <page name="notFound" view-id="/404.jsp">
- <end-conversation/>
- </page>
+ <page name="notFound" view-id="/404.jsp">
+ <end-conversation/>
+ </page>
-</pageflow-definition>]]></programlisting>
-
- </section>
-
- <section>
- <title>Page nodes and transitions</title>
-
- <para>
- Each <literal><page></literal> node represents a state where
- the system is waiting for user input:
- </para>
-
- <programlisting role="XML"><![CDATA[<page name="displayGuess" view-id="/numberGuess.jsp">
- <redirect/>
- <transition name="guess" to="evaluateGuess">
- <action expression="#{numberGuess.guess}" />
- </transition>
-</page>]]></programlisting>
-
- <para>
- The <literal>view-id</literal> is the JSF view id. The <literal><redirect/></literal>
- element has the same effect as <literal><redirect/></literal> in a
- JSF navigation rule: namely, a post-then-redirect behavior, to overcome problems
- with the browser's refresh button. (Note that Seam propagates conversation contexts
- over these browser redirects. So there is no need for a Ruby on Rails style "flash"
- construct in Seam!)
- </para>
-
- <para>
- The transition name is the name of a JSF outcome triggered by clicking
- a command button or command link in <literal>numberGuess.jsp</literal>.
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandButton type="submit" value="Guess" action="guess"/>]]></programlisting>
-
- <para>
- When the transition is triggered by clicking this button, jBPM will activate the
- transition action by calling the <literal>guess()</literal> method of the
- <literal>numberGuess</literal> component. Notice that the syntax used for
- specifying actions in the jPDL is just a familiar JSF EL expression, and that
- the transition action handler is just a method of a Seam component in the
- current Seam contexts. So we have exactly the same event model for jBPM events
- that we already have for JSF events! (The <emphasis>One Kind of Stuff</emphasis>
- principle.)
- </para>
-
- <para>
- In the case of a null outcome (for example, a command button with no
- <literal>action</literal> defined), Seam will signal the transition with no
- name if one exists, or else simply redisplay the page if all transitions
- have names. So we could slightly simplify our example pageflow and this button:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandButton type="submit" value="Guess"/>]]></programlisting>
-
- <para>
- Would fire the following un-named transition:
- </para>
-
- <programlisting role="XML"><![CDATA[<page name="displayGuess" view-id="/numberGuess.jsp">
- <redirect/>
- <transition to="evaluateGuess">
- <action expression="#{numberGuess.guess}" />
- </transition>
-</page>]]></programlisting>
-
- <para>
- It is even possible to have the button call an action method, in which case the
- action outcome will determine the transition to be taken:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandButton type="submit" value="Guess" action="#{numberGuess.guess}"/>]]></programlisting>
-
+</pageflow-definition>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Page nodes and transitions</title>
+ <para>
+ Each <literal><![CDATA[<page>]]></literal> node represents a state where the system is waiting for user input:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page name="displayGuess" view-id="/numberGuess.jsp">
+ <redirect/>
+ <transition name="guess" to="evaluateGuess">
+ <action expression="#{numberGuess.guess}" />
+ </transition>
+</page>]]>
+</programlisting>
+ <para>
+ The <literal>view-id</literal> is the JSF view ID. The <literal><![CDATA[<redirect/>]]></literal> element has the same effect as <literal><![CDATA[<redirect/>]]></literal> in a JSF navigation rule — that is, a post-then-redirect behavior, to overcome problems with the browser's refresh button. (Note that Seam propagates conversation contexts across these browser redirects, so Seam does not require a Ruby on Rails-style <emphasis>flash</emphasis> construct.)
+ </para>
+ <para>
+ The transition name is the name of a JSF outcome triggered by clicking a command button or command link in <filename>numberGuess.jsp</filename>.
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton type="submit" value="Guess" action="guess"/>
+]]>
+</programlisting>
+ <para>
+ When clicking this button triggers the transition, jBPM activates the transition action by calling the <literal>guess()</literal> method of the <literal>numberGuess</literal> component. The syntax used for specifying actions in the jPDL is a familiar JSF EL expression, and the transition handler is a method of a Seam component in the current Seam contexts. Thus, we have the same event model for jBPM events as we have for JSF events. This is one of the guiding principles of Seam.
+ </para>
+ <para>
+ In the case of a null outcome (for example, a command button with no <literal>action</literal> defined), Seam signals the transition with no name (if one exists), or simply redisplay the page if all transitions are named. Therefore we could simplify this button and our pageflow like so:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton type="submit" value="Guess"/>]]>
+</programlisting>
+ <para>
+ This would fire the following un-named transition:
+ </para>
+
<programlisting role="XML"><![CDATA[<page name="displayGuess" view-id="/numberGuess.jsp">
- <transition name="correctGuess" to="win"/>
- <transition name="incorrectGuess" to="evaluateGuess"/>
-</page>]]></programlisting>
-
- <para>
- However, this is considered an inferior style, since it moves responsibility for
- controlling the flow out of the pageflow definition and back into the other
- components. It is much better to centralize this concern in the pageflow itself.
- </para>
-
- </section>
-
- <section>
- <title>Controlling the flow</title>
-
- <para>
- Usually, we don't need the more powerful features of jPDL when defining pageflows.
- We do need the <literal><decision></literal> node, however:
- </para>
-
+ <redirect/>
+ <transition to="evaluateGuess">
+ <action expression="#{numberGuess.guess}" />
+ </transition>
+</page>]]>
+</programlisting>
+ <para>
+ The button could also call an action method, in which case the action outcome determines the transition to be made:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton type="submit" value="Guess"
+ action="#{numberGuess.guess}"/>]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[<page name="displayGuess" view-id="/numberGuess.jsp">
+ <transition name="correctGuess" to="win"/>
+ <transition name="incorrectGuess" to="evaluateGuess"/>
+</page>]]>
+</programlisting>
+ <para>
+ However, this style is considered inferior, since it shifts responsibility for flow control out of the pageflow definition and back into other components. It is much better to centralize this concern in the pageflow itself.
+ </para>
+ </section>
+
+ <section>
+ <title>Controlling the flow</title>
+ <para>
+ Usually, the more powerful features of jPDL are not required when defining pageflows. However, we do require the <literal><![CDATA[<decision>]]></literal> node:
+ </para>
+
<programlisting role="XML"><![CDATA[<decision name="evaluateGuess" expression="#{numberGuess.correctGuess}">
- <transition name="true" to="win"/>
- <transition name="false" to="evaluateRemainingGuesses"/>
-</decision>]]></programlisting>
-
- <para>
- A decision is made by evaluating a JSF EL expression in the Seam contexts.
- </para>
-
- </section>
-
- <section>
- <title>Ending the flow</title>
-
- <para>
- We end the conversation using <literal><end-conversation></literal>
- or <literal>@End</literal>. (In fact, for readability, use of
- <emphasis>both</emphasis> is encouraged.)
- </para>
-
+ <transition name="true" to="win"/>
+ <transition name="false" to="evaluateRemainingGuesses"/>
+</decision>]]>
+</programlisting>
+ <para>
+ A decision is made by evaluating a JSF EL expression within the Seam context.
+ </para>
+ </section>
+
+ <section>
+ <title>Ending the flow</title>
+ <para>
+ We end the conversation with <literal><![CDATA[<end-conversation>]]></literal> or <literal>@End</literal>. For the sake of readability, we encourage you to use both.
+ </para>
+
<programlisting role="XML"><![CDATA[<page name="win" view-id="/win.jsp">
- <redirect/>
- <end-conversation/>
-</page>]]></programlisting>
-
- <para>
- Optionally, we can end a task, specify a jBPM <literal>transition</literal>
- name. In this case, Seam will signal the end of the current task in the
- overarching business process.
- </para>
-
+ <redirect/>
+ <end-conversation/>
+</page>]]>
+</programlisting>
+ <para>
+ Optionally, we can end a task, or specify a jBPM <literal>transition</literal> name. In this case, Seam signals the end of the current task in the overarching business process.
+ </para>
+
<programlisting role="XML"><![CDATA[<page name="win" view-id="/win.jsp">
- <redirect/>
- <end-task transition="success"/>
-</page>]]></programlisting>
-
- </section>
-
- <section>
- <title>Pageflow composition</title>
- <para>
- It is possible to compose pageflows and have one pageflow pause
- pause while another pageflow executes. The <literal><process-state></literal>
- node pauses the outer pageflow, and begins execution of a named
- pageflow:
- </para>
-
+ <redirect/>
+ <end-task transition="success"/>
+</page>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Pageflow composition</title>
+ <para>
+ It is possible to compose pageflows so that one pageflow pauses while another pageflow executes. The <literal><![CDATA[<process-state>]]></literal> node pauses the outer pageflow, and begins execution of a named pageflow:
+ </para>
+
<programlisting role="XML"><![CDATA[<process-state name="cheat">
- <sub-process name="cheat"/>
- <transition to="displayGuess"/>
-</process-state>]]></programlisting>
-
- <para>
- The inner flow begins executing at a <literal><start-state></literal>
- node. When it reaches an <literal><end-state></literal> node,
- execution of the inner flow ends, and execution of the outer flow
- resumes with the transition defined by the <literal><process-state></literal>
- element.
- </para>
-
- </section>
-
- </section>
-
- <section>
- <title>Business process management in Seam</title>
- <para>
- A business process is a well-defined set of tasks that must
- be performed by users or software systems according to
- well-defined rules about <emphasis>who</emphasis> can perform
- a task, and <emphasis>when</emphasis> it should be performed.
- Seam's jBPM integration makes it easy to display lists of
- tasks to users and let them manage their tasks. Seam also
- lets the application store state associated with the business
- process in the <literal>BUSINESS_PROCESS</literal> context,
- and have that state made persistent via jBPM variables.
- </para>
-
- <para>
- A simple business process definition looks much the same as a
- page flow definition (<emphasis>One Kind of Stuff</emphasis>),
- except that instead of <literal><page></literal> nodes,
- we have <literal><task-node></literal> nodes. In a
- long-running business process, the wait states are where the
- system is waiting for some user to log in and perform a task.
- </para>
-
- <programlisting role="XML"><![CDATA[<process-definition name="todo">
+ <sub-process name="cheat"/>
+ <transition to="displayGuess"/>
+</process-state>]]>
+</programlisting>
+ <para>
+ The inner flow begins executing at a <literal><![CDATA[<start-state>]]></literal> node. When it reaches an <literal><![CDATA[<end-state>]]></literal> node, execution of the inner flow ends, and execution of the outer flow resumes with the transition defined by the <literal><![CDATA[<process-state>]]></literal> element.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Business process management in Seam</title>
+ <para>
+ A business process is a set of tasks that must be performed by users or software systems according to well-defined rules regarding who can perform a certain task, and when that task should be performed. Seam's jBPM integration makes it easy to let users view and manage their task lists. Seam also lets the application store state associated with the business process in the <literal>BUSINESS_PROCESS</literal> context, and makes that state persistent through jBPM variables.
+ </para>
+ <para>
+ A simple business process definition resembles a pageflow definition, except that instead of <literal><![CDATA[<page>]]></literal> nodes, we use <literal><![CDATA[<task-node>]]></literal> nodes. In a long-running business process, the wait state occurs where the system is waiting for some user to log in and perform a task.
+ </para>
+
+<programlisting role="XML"><![CDATA[<process-definition name="todo">
+ <start-state name="start">
+ <transition to="todo"/>
+ </start-state>
- <start-state name="start">
- <transition to="todo"/>
- </start-state>
+ <task-node name="todo">
+ <task name="todo" description="#{todoList.description}">
+ <assignment actor-id="#{actor.id}"/>
+ </task>
+ <transition to="done"/>
+ </task-node>
- <task-node name="todo">
- <task name="todo" description="#{todoList.description}">
- <assignment actor-id="#{actor.id}"/>
- </task>
- <transition to="done"/>
- </task-node>
+ <end-state name="done"/>
- <end-state name="done"/>
-
-</process-definition>]]></programlisting>
+</process-definition>]]>
+</programlisting>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/plugin-jbpm-todo.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/plugin-jbpm-todo.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ jPDL business process definitions and jPDL pageflow definitions can be used in the same project. When this occurs, a single <literal><![CDATA[<task>]]></literal> in a business process corresponds to a whole pageflow <literal><![CDATA[<pageflow-definition>]]></literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Using jPDL business process definitions</title>
+ <section>
+ <title>Installing process definitions</title>
+ <para>
+ First, we must install jBPM and tell it where to find the business process definitions:
+ </para>
+
+<programlisting role="XML"><![CDATA[<bpm:jbpm>
+ <bpm:process-definitions>
+ <value>todo.jpdl.xml</value>
+ </bpm:process-definitions>
+</bpm:jbpm>]]>
+</programlisting>
+ <para>
+ Since jBPM processes persist across application restarts, when using Seam in a production environment, it is unnecessary to install the process definition each time the application starts. Therefore, the process must be deployed to jBPM outside Seam. It is only necessary to install process definitions from <filename>components.xml</filename> during application development.
+ </para>
+ </section>
+
+ <section>
+ <title>Initializing actor IDs</title>
+ <para>
+ We always need to know which user is currently logged in. jBPM recognizes users with their <emphasis>actor ID</emphasis> and <emphasis>group actor ID</emphasis>. We specify the current actor IDs with the built-in Seam component, <literal>actor</literal>:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In Actor actor;
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/plugin-jbpm-todo.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/plugin-jbpm-todo.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>
- It is perfectly possible that we might have both jPDL business
- process definitions and jPDL pageflow definitions in the
- same project. If so, the relationship between the two is that
- a single <literal><task></literal> in a business process
- corresponds to a whole pageflow
- <literal><pageflow-definition></literal>
- </para>
- </section>
-
- <section>
- <title>Using jPDL business process definitions</title>
-
- <section>
- <title>Installing process definitions</title>
-
- <para>
- We need to install jBPM, and tell it where to find the
- business process definitions:
- </para>
-
- <programlisting role="XML"><![CDATA[<bpm:jbpm>
- <bpm:process-definitions>
- <value>todo.jpdl.xml</value>
- </bpm:process-definitions>
-</bpm:jbpm>]]></programlisting>
-
- <para>
- As jBPM processes are persistent across application restarts,
- when using Seam in a production environment you won't want to
- install the process definition every time the application starts.
- Therefore, in a production environment, you'll need to deploy
- the process to jBPM outside of Seam. In other words, only install
- process definitions from <literal>components.xml</literal> when
- developing your application.
- </para>
-
- </section>
-
- <section>
- <title>Initializing actor ids</title>
-
- <para>
- We always need to know what user is currently logged in.
- jBPM "knows" users by their <emphasis>actor id</emphasis>
- and <emphasis>group actor ids</emphasis>. We specify the
- current actor ids using the built in Seam component named
- <literal>actor</literal>:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@In Actor actor;
-
public String login() {
- ...
- actor.setId( user.getUserName() );
- actor.getGroupActorIds().addAll( user.getGroupNames() );
- ...
-}]]></programlisting>
-
- </section>
-
- <section>
- <title>Initiating a business process</title>
-
- <para>
- To initiate a business process instance, we use the
- <literal>@CreateProcess</literal> annotation:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@CreateProcess(definition="todo")
-public void createTodo() { ... }]]></programlisting>
-
- <para>Alternatively we can initiate a business process using pages.xml:</para>
-
- <programlisting role="XML"><![CDATA[<page>
- <create-process definition="todo" />
-</page>]]></programlisting>
-
- </section>
-
- <section>
- <title>Task assignment</title>
-
- <para>
- When a process reaches a task node, task instances are created. These must be
- assigned to users or user groups. We can either hardcode our actor ids, or
- delegate to a Seam component:
- </para>
-
- <programlisting role="XML"><![CDATA[<task name="todo" description="#{todoList.description}">
- <assignment actor-id="#{actor.id}"/>
-</task>]]></programlisting>
-
- <para>
- In this case, we have simply assigned the task to the current user.
- We can also assign tasks to a pool:
- </para>
-
- <programlisting role="XML"><![CDATA[<task name="todo" description="#{todoList.description}">
- <assignment pooled-actors="employees"/>
-</task>]]></programlisting>
-
- </section>
-
- <section>
- <title>Task lists</title>
-
- <para>
- Several built-in Seam components make it easy to display task lists.
- The <literal>pooledTaskInstanceList</literal> is a list of pooled tasks
- that users may assign to themselves:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:dataTable value="#{pooledTaskInstanceList}" var="task">
- <h:column>
- <f:facet name="header">Description</f:facet>
- <h:outputText value="#{task.description}"/>
- </h:column>
- <h:column>
- <s:link action="#{pooledTask.assignToCurrentActor}" value="Assign" taskInstance="#{task}"/>
- </h:column>
-</h:dataTable>]]></programlisting>
-
- <para>
- Note that instead of <literal><s:link></literal> we could have used
- a plain JSF <literal><h:commandLink></literal>:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandLink action="#{pooledTask.assignToCurrentActor}">
- <f:param name="taskId" value="#{task.id}"/>
-</h:commandLink>]]></programlisting>
-
- <para>
- The <literal>pooledTask</literal> component is a built-in component that
- simply assigns the task to the current user.
- </para>
-
- <para>
- The <literal>taskInstanceListForType</literal> component includes tasks of
- a particular type that are assigned to the current user:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:dataTable value="#{taskInstanceListForType['todo']}" var="task">
- <h:column>
- <f:facet name="header">Description</f:facet>
- <h:outputText value="#{task.description}"/>
- </h:column>
- <h:column>
- <s:link action="#{todoList.start}" value="Start Work" taskInstance="#{task}"/>
- </h:column>
-</h:dataTable>]]></programlisting>
-
- </section>
-
- <section>
- <title>Performing a task</title>
-
- <para>
- To begin work on a task, we use either <literal>@StartTask</literal>
- or <literal>@BeginTask</literal> on the listener method:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@StartTask
-public String start() { ... }]]></programlisting>
-
- <para>Alternatively we can begin work on a task using pages.xml:</para>
-
- <programlisting role="XML"><![CDATA[<page>
- <start-task />
-</page>]]></programlisting>
-
- <para>
- These annotations begin a special kind of conversation that has
- significance in terms of the overarching business process. Work done
- by this conversation has access to state held in the business
- process context.
- </para>
-
- <para>
- If we end the conversation using <literal>@EndTask</literal>, Seam
- will signal the completion of the task:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@EndTask(transition="completed")
-public String completed() { ... }]]></programlisting>
-
- <para>Alternatively we can use pages.xml:</para>
-
- <programlisting role="XML"><![CDATA[<page>
- <end-task transition="completed" />
-</page>]]></programlisting>
-
- <para>
- You can also use EL to specify the transition in pages.xml.
- </para>
-
- <para>
- At this point, jBPM takes over and continues executing the business process
- definition. (In more complex processes, several tasks might need to be
- completed before process execution can resume.)
- </para>
-
- <para>
- Please refer to the jBPM documentation for a more thorough overview of
- the sophisticated features that jBPM provides for managing complex
- business processes.
- </para>
-
- </section>
- </section>
-
+ ...
+ actor.setId( user.getUserName() );
+ actor.getGroupActorIds().addAll( user.getGroupNames() );
+ ...
+}]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Initiating a business process</title>
+ <para>
+ To initiate a business process instance, we use the <literal>@CreateProcess</literal> annotation:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@CreateProcess(definition="todo")
+public void createTodo() { ... }]]>
+</programlisting>
+ <para>
+ Alternatively we can initiate a business process using <filename>pages.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page>
+ <create-process definition="todo" />
+</page>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Task assignment</title>
+ <para>
+ When a process reaches a task node, task instances are created. These must be assigned to users or user groups. We can either hardcode our actor IDs, or delegate to a Seam component:
+ </para>
+
+<programlisting role="XML"><![CDATA[<task name="todo" description="#{todoList.description}">
+ <assignment actor-id="#{actor.id}"/>
+</task>]]>
+</programlisting>
+ <para>
+ In this case, we have simply assigned the task to the current user. We can also assign tasks to a pool:
+ </para>
+
+<programlisting role="XML"><![CDATA[<task name="todo" description="#{todoList.description}">
+ <assignment pooled-actors="employees"/>
+</task>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Task lists</title>
+ <para>
+ Several built-in Seam components make it easy to display task lists. The <literal>pooledTaskInstanceList</literal> is a list of pooled tasks that users may assign to themselves:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:dataTable value="#{pooledTaskInstanceList}" var="task">
+ <h:column>
+ <f:facet name="header">Description</f:facet>
+ <h:outputText value="#{task.description}"/>
+ </h:column>
+ <h:column>
+ <s:link action="#{pooledTask.assignToCurrentActor}"
+ value="Assign" taskInstance="#{task}"/>
+ </h:column>
+</h:dataTable>]]>
+</programlisting>
+ <para>
+ Note that instead of <literal><![CDATA[<s:link>]]></literal>, we can use a plain JSF <literal><![CDATA[<h:commandLink>]]></literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandLink action="#{pooledTask.assignToCurrentActor}">
+ <f:param name="taskId" value="#{task.id}"/>
+</h:commandLink>]]>
+</programlisting>
+ <para>
+ The <literal>pooledTask</literal> component is a built-in component that simply assigns the task to the current user.
+ </para>
+ <para>
+ The <literal>taskInstanceListForType</literal> component includes tasks of a particular type that are assigned to the current user:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:dataTable value="#{taskInstanceListForType['todo']}" var="task">
+ <h:column>
+ <f:facet name="header">Description</f:facet>
+ <h:outputText value="#{task.description}"/>
+ </h:column>
+ <h:column>
+ <s:link action="#{todoList.start}"
+ value="Start Work" taskInstance="#{task}"/>
+ </h:column>
+</h:dataTable>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Performing a task</title>
+ <para>
+ To begin work on a task, we use either <literal>@StartTask</literal> or <literal>@BeginTask</literal> on the listener method:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@StartTask public String start() { ... }]]>
+</programlisting>
+ <para>
+ Alternatively, we can begin work on a task with <filename>pages.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page>
+ <start-task />
+</page>]]>
+</programlisting>
+ <para>
+ These annotations begin a special kind of conversation that is significant in terms of the overarching business process. Work done by this conversation has access to state held in the business process context.
+ </para>
+ <para>
+ If we end the conversation with <literal>@EndTask</literal>, Seam signals the completion of the task:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@EndTask(transition="completed")
+public String completed() { ... }]]>
+</programlisting>
+ <para>
+ Alternatively, we can use <filename>pages.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page>
+ <end-task transition="completed" />
+</page>]]>
+</programlisting>
+ <para>
+ You can also use EL to specify the transition in <filename>pages.xml</filename>.
+ </para>
+ <para>
+ At this point, jBPM will continue to execute the business process definition. (In more complex processes, several tasks may need to be completed before process execution can resume.)
+ </para>
+ <para>
+ Please refer to the jBPM documentation for a more thorough overview of the sophisticated features that jBPM provides for managing complex business processes.
+ </para>
+ </section>
+
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Jms.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Jms.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Jms.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,607 +1,474 @@
-<chapter id="jms">
- <title>Asynchronicity and messaging</title>
- <para>
- Seam makes it very easy to perform work asynchronously from a web request. When most people
- think of asynchronicity in Java EE, they think of using JMS. This is certainly one way to
- approach the problem in Seam, and is the right way when you have strict and well-defined
- quality of service requirements. Seam makes it easy to send and receive JMS messages using
- Seam components.
- </para>
-
- <para>
- But for cases when you are simply want to use a worker thread, JMS is overkill. Seam layers a simple
- asynchronous method and event facility over your choice of <emphasis>dispatchers</emphasis>:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>java.util.concurrent.ScheduledThreadPoolExecutor</literal> (by default)
- </para>
- </listitem>
- <listitem>
- <para>
- the EJB timer service (for EJB 3.0 environments)
- </para>
- </listitem>
- <listitem>
- <para>
- Quartz
- </para>
- </listitem>
- </itemizedlist>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- <para>
- This chapter first covers how to leverage Seam to simplify JMS and then explains how to use the
- simpler asynchronous method and event facility.
- </para>
+<chapter id="jms" >
+ <title>Asynchronicity and messaging</title>
+ <para>
+ Seam makes it easy to perform work asynchronously from a web request. Asynchronicity in Java EE is usually linked with JMS, and where your quality of service requirements are strict and well-defined, this is logical. It is easy to send JMS messages through Seam components.
+ </para>
+ <para>
+ However, for many use cases, JMS is more powerful than necessary. Seam layers a simple, asynchronous method and event facility over your choice of <emphasis>dispatchers</emphasis>:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>java.util.concurrent.ScheduledThreadPoolExecutor</literal> (by default)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the EJB timer service (for EJB 3.0 environments)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Quartz
+ </para>
+ </listitem>
+ </itemizedlist>
- <sect1>
- <title>Messaging in Seam</title>
-
- <para>
- Seam makes it easy to send and receive JMS messages to and from
- Seam components. Both the message publisher and the message receiver
- can be Seam components.
- </para>
-
- <para>
- You'll first learn to setup a queue and topic message publisher and then
- look at an example that illustrates how to perform the message exchange.
- </para>
-
- <sect2>
- <title>Configuration</title>
- <para>
- To configure Seam's infrastructure for sending JMS messages,
- you need to tell Seam about any topics and queues you want to
- send messages to, and also tell Seam where to find the
- <literal>QueueConnectionFactory</literal> and/or
- <literal>TopicConnectionFactory</literal>.
- </para>
-
- <para>
- Seam defaults to using <literal>UIL2ConnectionFactory</literal>
- which is the usual connection factory for use with JBossMQ. If
- you are using some other JMS provider, you need to set one or
- both of <literal>queueConnection.queueConnectionFactoryJndiName</literal>
- and <literal>topicConnection.topicConnectionFactoryJndiName</literal>
- in <literal>seam.properties</literal>, <literal>web.xml</literal>
- or <literal>components.xml</literal>.
- </para>
-
- <para>
- You also need to list topics and queues in <literal>components.xml</literal>
- to install Seam managed <literal>TopicPublisher</literal>s and
- <literal>QueueSender</literal>s:
- </para>
-
- <programlisting role="XML"><![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>
-
- <sect2>
- <title>Sending messages</title>
- <para>
- Now, you can inject a JMS <literal>TopicPublisher</literal> and
- <literal>TopicSession</literal> into any Seam component to publish
- an object to a topic:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("stockPriceChangeNotifier")
-public class StockPriceChangeNotifier
-{
- @In private TopicPublisher stockTickerPublisher;
-
- @In private TopicSession topicSession;
-
- public void publish(StockPrice price)
- {
- try
- {
- stockTickerPublisher.publish(topicSession.createObjectMessage(price));
- }
- catch (Exception ex)
- {
- throw new RuntimeException(ex);
- }
- }
-}]]></programlisting>
-
- <para>or to a queue:</para>
-
- <programlisting role="JAVA"><![CDATA[@Name("paymentDispatcher")
-public class PaymentDispatcher
-{
- @In private QueueSender paymentQueueSender;
-
- @In private QueueSession queueSession;
-
- public void publish(Payment payment)
- {
- try
- {
- paymentQueueSender.send(queueSession.createObjectMessage(payment));
- }
- catch (Exception ex)
- {
- throw new RuntimeException(ex);
- }
- }
-}]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Receiving messages using a message-driven bean</title>
- <para>
- You can process messages using any EJB 3 message-driven bean. The MDB
- can even be a Seam component, in which case it's possible to inject
- other event- and application- scoped Seam components. Here's an example
- of the payment receiver, which delegates to a payment processor.
- </para>
- <note>
- <para>
- You'll likely need to set the create attribute on the <literal>@In</literal> annotation to true (i.e.
- create = true) to have Seam create an instance of the component being injected. This isn't necessary if
- the component supports auto-creation (e.g., it's annotated with <literal>@Autocreate</literal>).
- </para>
- </note>
-
- <para>
- First, create an MDB to receive the message.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@MessageDriven(activationConfig = {
- @ActivationConfigProperty(
- propertyName = "destinationType",
- propertyValue = "javax.jms.Queue"
- ),
- @ActivationConfigProperty(
- propertyName = "destination",
- propertyValue = "queue/paymentQueue"
- )
-})
- at Name("paymentReceiver")
-public class PaymentReceiver implements MessageListener
-{
- @Logger private Log log;
-
- @In(create = true) private PaymentProcessor paymentProcessor;
-
- @Override
- public void onMessage(Message message)
- {
- try
- {
- paymentProcessor.processPayment((Payment) ((ObjectMessage) message).getObject());
- }
- catch (JMSException ex)
- {
- log.error("Message payload did not contain a Payment object", ex);
- }
- }
-}]]></programlisting>
-
- <para>
- Then, implement the Seam component to which the receiver delegates processing of the payment.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("paymentProcessor")
-public class PaymentProcessor
-{
- @In private EntityManager entityManager;
-
- public void processPayment(Payment payment)
- {
- // perhaps do something more fancy
- entityManager.persist(payment);
- }
-}]]></programlisting>
-
- <para>
- If you are going to be performing transaction operations in your MDB, you should ensure that you
- are working with an XA datasource. Otherwise, it won't be possible to rollback database changes
- if the database transaction commits and a subsequent operation being performed by the message
- fails.
- </para>
- </sect2>
-
- <sect2>
- <title>Receiving messages in the client</title>
- <para>
- Seam Remoting lets you subscribe to a JMS topic from client-side JavaScript. This is
- described in <xref linkend="remoting"/>.
- </para>
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>Asynchronicity</title>
-
- <para>
- Asynchronous events and method calls have the same quality of service expectations as
- the underlying dispatcher mechanism. The default dispatcher, based upon a
- <literal>ScheduledThreadPoolExecutor</literal> performs efficiently but provides no
- support for persistent asynchronous tasks, and hence no guarantee that a task
- will ever actually be executed. If you're working in an environment that supports
- EJB 3.0, and add the following line to <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<async:timer-service-dispatcher/>]]></programlisting>
-
- <para>
- then your asynchronous tasks will be processed by the container's EJB timer service. If
- you're not familiar with the Timer service, don't worry, you don't need to interact with
- it directly if you want to use asynchronous methods in Seam. The important thing to know
- is that any good EJB 3.0 implementation will have the option of using persistent timers,
- which gives some guarantee that the tasks will eventually be processed.
- </para>
-
- <para>
- Another alternative is to use the open source Quartz library to manage asynchronous method.
- You need to bundle the Quartz library JAR (found in the <literal>lib</literal> directory)
- in your EAR and declare it as a Java module in <literal>application.xml</literal>.
- The Quartz dispatcher may be configured by adding a Quartz property file to the classpath.
- It must be named <literal>seam.quartz.properties</literal>. In addition,
- you need to add the following line to <literal>components.xml</literal> to install the
- Quartz dispatcher.
- </para>
-
- <programlisting role="XML"><![CDATA[<async:quartz-dispatcher/>]]></programlisting>
-
- <para>
- The Seam API for the default <literal>ScheduledThreadPoolExecutor</literal>, the EJB3
- <literal>Timer</literal>, and the Quartz <literal>Scheduler</literal> are largely the
- same. They can just "plug and play" by adding a line to <literal>components.xml</literal>.
- </para>
-
- <sect2>
- <title>Asynchronous methods</title>
-
- <para>
- In simplest form, an asynchronous call just lets a method call be processed asynchronously
- (in a different thread) from the caller. We usually use an asynchronous call when we want
- to return an immediate response to the client, and let some expensive work be processed in
- the background. This pattern works very well in applications which use AJAX, where the
- client can automatically poll the server for the result of the work.
- </para>
-
- <para>
- For EJB components, we annotate the local interface to specify that a method is processed
- asynchronously.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Local
-public interface PaymentHandler
-{
- @Asynchronous
- public void processPayment(Payment payment);
-}]]></programlisting>
-
- <para>
- (For JavaBean components we can annotate the component implementation class if we like.)
- </para>
-
- <para>
- The use of asynchronicity is transparent to the bean class:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Stateless
+ <section>
+ <title>Asynchronicity</title>
+ <para>
+ Asynchronous events and method calls have the same quality of service expectations as the underlying dispatcher mechanism. The default dispatcher, based upon a <literal>ScheduledThreadPoolExecutor</literal> performs efficiently but provides no support for persistent asynchronous tasks, and hence no guarantee that a task will ever actually be executed. If you are working in an environment that supports EJB 3.0, add the following line to <filename>components.xml</filename> to ensure that your asynchronous tasks are processed by the container's EJB timer service:
+ </para>
+
+<programlisting role="XML"><![CDATA[<async:timer-service-dispatcher/>]]>
+</programlisting>
+ <para>
+ If you want to use asynchronous methods in Seam, you do not need to interact directly with the Timer service. However, it is important that your EJB3 implementation has the option of using persistent timers, which give some guarantee that the task will eventually be processed.
+ </para>
+ <para>
+ Alternatively, you can use the open source Quartz library to manage asynchronous method. To do so, bundle the Quartz library <filename>JAR</filename> (found in the <literal>lib</literal> directory) in your <filename>EAR</filename>, and declare it as a Java module in <filename>application.xml</filename>. You can configure the Quartz dispatcher by adding a Quartz property file to the classpath —this file must be named <filename>seam.quartz.properties</filename>. To install the Quartz dispatcher, you will also need to add the following line to <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<async:quartz-dispatcher/>]]>
+</programlisting>
+ <para>
+ Since the Seam API for the default <literal>ScheduledThreadPoolExecutor</literal>, the EJB3 <literal>Timer</literal>, and the Quartz <literal>Scheduler</literal> are very similar, you can "plug and play" by adding a line to <filename>components.xml</filename>. <!-- #modify: What line can you add? -->
+ </para>
+ <section>
+ <title>Asynchronous methods</title>
+ <para>
+ An asynchronous call allows a method call to be processed asynchronously (in a different thread) to the caller. Usually, asynchronous calls are used when we want to send an immediate response to the client, and simultaneously process expensive work in the background. This pattern works well in AJAX applications, where the client can automatically poll the server for the result of the work.
+ </para>
+ <para>
+ For EJB components, annotate the implementation of the bean to specify that a method be processed asynchronously. For JavaBean components, annotate the component implementation class:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateless
@Name("paymentHandler")
public class PaymentHandlerBean implements PaymentHandler
{
- public void processPayment(Payment payment)
- {
- //do some work!
- }
-}]]></programlisting>
-
- <para>
- And also transparent to the client:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Stateful
+ @Asynchronous
+ public void processPayment(Payment payment) {
+ //do some work!
+ }
+}]]>
+</programlisting>
+ <para>
+ Asynchronicity is transparent to the bean class. It is also transparent to the client:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateful
@Name("paymentAction")
public class CreatePaymentAction
{
- @In(create=true) PaymentHandler paymentHandler;
- @In Bill bill;
+ @In(create=true) PaymentHandler paymentHandler;
+ @In Bill bill;
- public String pay()
- {
- paymentHandler.processPayment( new Payment(bill) );
- return "success";
- }
-}]]></programlisting>
+ public String pay() {
+ paymentHandler.processPayment( new Payment(bill) );
+ return "success";
+ }
+}]]>
+</programlisting>
+ <para>
+ The asynchronous method is processed in a fresh event context, and has no access to the session or conversation context state of the caller. However, the business process context <emphasis>is</emphasis> propagated.
+ </para>
+ <para>
+ You can schedule asynchronous method calls for delayed execution with the <literal>@Duration</literal>, <literal>@Expiration</literal> and <literal>@IntervalDuration</literal> annotations.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Local
+public interface PaymentHandler {
+ @Asynchronous
+ public void processScheduledPayment(Payment payment,
+ @Expiration Date date);
- <para>
- The asynchronous method is processed in a completely new event context and does
- not have access to the session or conversation context state of the caller. However,
- the business process context <emphasis>is</emphasis> propagated.
- </para>
-
- <para>
- Asynchronous method calls may be scheduled for later execution using the
- <literal>@Duration</literal>, <literal>@Expiration</literal> and
- <literal>@IntervalDuration</literal> annotations.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Local
-public interface PaymentHandler
-{
- @Asynchronous
- public void processScheduledPayment(Payment payment, @Expiration Date date);
-
- @Asynchronous
- public void processRecurringPayment(Payment payment,
- @Expiration Date date,
- @IntervalDuration Long interval)'
-}]]></programlisting>
-
- <programlisting role="JAVA"><![CDATA[@Stateful
+ @Asynchronous
+ public void processRecurringPayment(Payment payment,
+ @Expiration Date date,
+ @IntervalDuration Long interval);
+}]]>
+</programlisting>
+
+<programlisting role="JAVA"><![CDATA[@Stateful
@Name("paymentAction")
public class CreatePaymentAction
{
- @In(create=true) PaymentHandler paymentHandler;
- @In Bill bill;
+ @In(create=true) PaymentHandler paymentHandler;
+ @In Bill bill;
- public String schedulePayment()
- {
- paymentHandler.processScheduledPayment( new Payment(bill), bill.getDueDate() );
- return "success";
- }
+ public String schedulePayment() {
+ paymentHandler.processScheduledPayment(new Payment(bill),
+ bill.getDueDate() );
+ return "success";
+ }
- public String scheduleRecurringPayment()
- {
- paymentHandler.processRecurringPayment( new Payment(bill), bill.getDueDate(),
- ONE_MONTH );
- return "success";
- }
-}]]></programlisting>
-
- <para>
- Both client and server may access the <literal>Timer</literal> object associated with
- the invocation. The <literal>Timer</literal> object shown below is the EJB3 timer when you use the EJB3 dispatcher. For the default <literal>ScheduledThreadPoolExecutor</literal>, the returned object is <literal>Future</literal> from the JDK. For the Quartz dispatcher, it returns <literal>QuartzTriggerHandle</literal>, which we will discuss in the next section.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Local
+ public String scheduleRecurringPayment() {
+ paymentHandler.processRecurringPayment(new Payment(bill),
+ bill.getDueDate(), ONE_MONTH );
+ return "success";
+ }
+}]]>
+</programlisting>
+ <para>
+ Both client and server can access the <literal>Timer</literal> object associated with the invocation. The <literal>Timer</literal> shown below is the EJB3 timer used with the EJB3 dispatcher. For the default <literal>ScheduledThreadPoolExecutor</literal>, the timer returns <literal>Future</literal> from the JDK. For the Quartz dispatcher, it returns <literal>QuartzTriggerHandle</literal>, which will be discussed in the next section.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Local
public interface PaymentHandler
{
- @Asynchronous
- public Timer processScheduledPayment(Payment payment, @Expiration Date date);
-}]]></programlisting>
-
- <programlisting role="JAVA"><![CDATA[@Stateless
+ @Asynchronous
+ public Timer processScheduledPayment(Payment payment,
+ @Expiration Date date);
+}]]>
+</programlisting>
+
+<programlisting role="JAVA"><![CDATA[@Stateless
@Name("paymentHandler")
-public class PaymentHandlerBean implements PaymentHandler
-{
- @In Timer timer;
+public class PaymentHandlerBean implements PaymentHandler {
+ @In Timer timer;
- public Timer processScheduledPayment(Payment payment, @Expiration Date date)
- {
- //do some work!
-
- return timer; //note that return value is completely ignored
- }
-
-}]]></programlisting>
-
- <programlisting role="JAVA"><![CDATA[@Stateful
+ public Timer processScheduledPayment(Payment payment,
+ @Expiration Date date) {
+ //do some work!
+ return timer; //note that return value is completely ignored
+ }
+}]]>
+</programlisting>
+
+<programlisting role="JAVA"><![CDATA[@Stateful
@Name("paymentAction")
public class CreatePaymentAction
{
- @In(create=true) PaymentHandler paymentHandler;
- @In Bill bill;
+ @In(create=true) PaymentHandler paymentHandler;
+ @In Bill bill;
- public String schedulePayment()
- {
- Timer timer = paymentHandler.processScheduledPayment( new Payment(bill),
- bill.getDueDate() );
- return "success";
- }
-}]]></programlisting>
-
- <para>
- Asynchronous methods cannot return any other value to the caller.
- </para>
-
- </sect2>
+ public String schedulePayment() {
+ Timer timer =
+ paymentHandler.processScheduledPayment(new Payment(bill),
+ bill.getDueDate());
+ return "success";
+ }
+}]]>
+</programlisting>
+ <para>
+ Asynchronous methods cannot return any other value to the caller.
+ </para>
+ </section>
+
+ <section>
+ <title>Asynchronous methods with the Quartz Dispatcher</title>
+ <para>
+ The Quartz dispatcher lets you use the <literal>@Asynchronous</literal>, <literal>@Duration</literal>, <literal>@Expiration</literal>, and <literal>@IntervalDuration</literal> annotations, as above, but it also supports several additional annotations.
+ </para>
+ <para>
+ The <literal>@FinalExpiration</literal> annotation specifies an end date for a recurring task. Note that you can inject the <code>QuartzTriggerHandle</code>.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In QuartzTriggerHandle timer;
- <sect2>
- <title>Asynchronous methods with the Quartz Dispatcher</title>
-
- <para>
- The Quartz dispatcher (see earlier on how to install it) allows you to use the <literal>@Asynchronous</literal>, <literal>@Duration</literal>, <literal>@Expiration</literal>, and <literal>@IntervalDuration</literal> annotations as above. But it has some powerful additional features. The Quartz dispatcher supports three new annotations.
- </para>
-
- <para>The <literal>@FinalExpiration</literal> annotation specifies an end date for the recurring task. Note that you can inject the <code>QuartzTriggerHandle</code>.</para>
-
- <programlisting role="JAVA"><![CDATA[
- @In QuartzTriggerHandle timer;
-
- // Defines the method in the "processor" component
- @Asynchronous
- public QuartzTriggerHandle schedulePayment(@Expiration Date when,
- @IntervalDuration Long interval,
- @FinalExpiration Date endDate,
- Payment payment)
- {
- // do the repeating or long running task until endDate
- }
+// Defines the method in the "processor" component
+ at Asynchronous
+public QuartzTriggerHandle schedulePayment(@Expiration Date when,
+ @IntervalDuration Long interval,
+ @FinalExpiration Date endDate,
+ Payment payment) {
+ // do the repeating or long running task until endDate
+}
- ... ...
+... ...
- // Schedule the task in the business logic processing code
- // Starts now, repeats every hour, and ends on May 10th, 2010
- Calendar cal = Calendar.getInstance ();
- cal.set (2010, Calendar.MAY, 10);
- processor.schedulePayment(new Date(), 60*60*1000, cal.getTime(), payment);
-]]></programlisting>
-
- <para>Note that the method returns the <literal>QuartzTriggerHandle</literal> object, which you can use later to stop, pause, and resume the scheduler. The <literal>QuartzTriggerHandle</literal> object is serializable, so you can save it into the database if you need to keep it around for extended period of time.</para>
+// Schedule the task in the business logic processing code
+// Starts now, repeats every hour, and ends on May 10th, 2010
+Calendar cal = Calendar.getInstance ();
+cal.set (2010, Calendar.MAY, 10);
+processor.schedulePayment(new Date(), 60*60*1000, cal.getTime(), payment);]]>
+</programlisting>
+ <para>
+ Note that this method returns the <literal>QuartzTriggerHandle</literal> object, which can be used to stop, pause, and resume the scheduler. The <literal>QuartzTriggerHandle</literal> object is serializable, so it can be saved into the database if required for an extended period of time.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[QuartzTriggerHandle handle=
+ processor.schedulePayment(payment.getPaymentDate(),
+ payment.getPaymentCron(),
+ payment);
+payment.setQuartzTriggerHandle( handle );
+// Save payment to DB
- <programlisting role="JAVA"><![CDATA[QuartzTriggerHandle handle =
- processor.schedulePayment(payment.getPaymentDate(),
- payment.getPaymentCron(),
- payment);
- payment.setQuartzTriggerHandle( handle );
- // Save payment to DB
+// later ...
- // later ...
-
- // Retrieve payment from DB
- // Cancel the remaining scheduled tasks
- payment.getQuartzTriggerHandle().cancel();
-]]></programlisting>
-
- <para>The <literal>@IntervalCron</literal> annotation supports Unix cron job syntax for task scheduling. For instance, the following asynchronous method runs at 2:10pm and at 2:44pm every Wednesday in the month of March.
- </para>
-
- <programlisting role="JAVA"><![CDATA[
- // Define the method
- @Asynchronous
- public QuartzTriggerHandle schedulePayment(@Expiration Date when,
- @IntervalCron String cron,
- Payment payment)
- {
- // do the repeating or long running task
- }
+// Retrieve payment from DB
+// Cancel the remaining scheduled tasks
+payment.getQuartzTriggerHandle().cancel();]]>
+</programlisting>
+ <para>
+ The <literal>@IntervalCron</literal> annotation supports Unix cron job syntax for task scheduling. For example, the following asynchronous method runs at 2:10pm and at 2:44pm every Wednesday in the month of March.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[// Define the method
+ at Asynchronous
+public QuartzTriggerHandle schedulePayment(@Expiration Date when,
+ @IntervalCron String cron,
+ Payment payment) {
+ // do the repeating or long running task
+}
- ... ...
+... ...
- // Schedule the task in the business logic processing code
- QuartzTriggerHandle handle =
- processor.schedulePayment(new Date(), "0 10,44 14 ? 3 WED", payment);
-]]></programlisting>
-
- <para>The <literal>@IntervalBusinessDay</literal> annotation supports invocation on the "nth Business Day" scenario. For instance, the following asynchronous method runs at 14:00 on the 2nd business day of each month. By default, it excludes all weekends and US federal holidays until 2010 from the business days.
- </para>
-
- <programlisting role="JAVA"><![CDATA[
- // Define the method
- @Asynchronous
- public QuartzTriggerHandle schedulePayment(@Expiration Date when,
+// Schedule the task in the business logic processing code
+QuartzTriggerHandle handle =
+ processor.schedulePayment(new Date(), "0 10,44 14 ? 3 WED", payment);
+]]>
+</programlisting>
+ <para>
+ The <literal>@IntervalBusinessDay</literal> annotation supports invocation in the "nth Business Day" scenario. For instance, the following asynchronous method runs at 14:00 on the 2nd business day of each month. All weekends and US Federal holidays are excluded from the business days by default.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[// Define the method
+ at Asynchronous
+public QuartzTriggerHandle schedulePayment(@Expiration Date when,
@IntervalBusinessDay NthBusinessDay nth,
- Payment payment)
- {
- // do the repeating or long running task
- }
+ Payment payment) {
+ // do the repeating or long running task
+}
- ... ...
+... ...
- // Schedule the task in the business logic processing code
- QuartzTriggerHandle handle =
- processor.schedulePayment(new Date(),
- new NthBusinessDay(2, "14:00", WEEKLY), payment);
-]]></programlisting>
+// Schedule the task in the business logic processing code
+QuartzTriggerHandle handle =
+ processor.schedulePayment(new Date(),
+ new NthBusinessDay(2, "14:00", WEEKLY),
+ payment);
+]]>
+</programlisting>
+ <para>
+ The <literal>NthBusinessDay</literal> object contains the configuration of the invocation trigger. You can specify more holidays (company holidays and non-US holidays, for example) in the <literal>additionalHolidays</literal> property.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public class NthBusinessDay implements Serializable {
+ int n;
+ String fireAtTime;
+ List<Date> additionalHolidays;
+ BusinessDayIntervalType interval;
+ boolean excludeWeekends;
+ boolean excludeUsFederalHolidays;
- <para>The <literal>NthBusinessDay</literal> object contains the configuration of the invocation trigger. You can specify more holidays (e.g., company holidays, non-US holidays etc.) via the <literal>additionalHolidays</literal> property.</para>
-
- <programlisting role="JAVA"><![CDATA[
-public class NthBusinessDay implements Serializable
-{
- int n;
- String fireAtTime;
- List <Date> additionalHolidays;
- BusinessDayIntervalType interval;
- boolean excludeWeekends;
- boolean excludeUsFederalHolidays;
+ public enum BusinessDayIntervalType { WEEKLY, MONTHLY, YEARLY }
- public enum BusinessDayIntervalType { WEEKLY, MONTHLY, YEARLY }
-
- public NthBusinessDay ()
- {
- n = 1;
- fireAtTime = "12:00";
- additionalHolidays = new ArrayList <Date> ();
- interval = BusinessDayIntervalType.WEEKLY;
- excludeWeekends = true;
- excludeUsFederalHolidays = true;
- }
+ public NthBusinessDay () {
+ n = 1;
+ fireAtTime = "12:00";
+ additionalHolidays = new ArrayList<Date> ();
+ interval = BusinessDayIntervalType.WEEKLY;
+ excludeWeekends = true;
+ excludeUsFederalHolidays = true;
+ }
... ...
}
-]]></programlisting>
-
- <para>The <literal>@IntervalDuration</literal>, <literal>@IntervalCron</literal>, and <literal>@IntervalNthBusinessDay</literal> annotations are mutually exclusive. If they are used in the same method, a <literal>RuntimeException</literal> will be thrown.</para>
-
- </sect2>
-
- <sect2>
- <title>Asynchronous events</title>
- <para>
- Component-driven events may also be asynchronous. To raise an event for asynchronous
- processing, simply call the <literal>raiseAsynchronousEvent()</literal> method of
- the <literal>Events</literal> class. To schedule a timed event, call the
- <literal>raiseTimedEvent()</literal> method, passing a <emphasis>schedule</emphasis>
- object (for the default dispatcher or timer service dispatcher, use <literal>TimerSchedule</literal>).
- Components may observe asynchronous events in the usual way, but remember that only the
- business process context is propagated to the asynchronous thread.
- </para>
- </sect2>
-
- <sect2>
- <title>Handling exceptions from asynchronous calls</title>
-
- <para>
- Each asynchronous dispatcher behaves differently when an
- exception propagates through it. For example, the
- <literal>java.util.concurrent</literal> dispatcher will suspend
- further executions of a call which repeats, and the EJB3 timer
- service will swallow the exception. Seam therefore catches any
- exception which propagates out of the asynchronous call before
- it reaches the dispatcher.
- </para>
-
- <para>
- By default, any exception which propagates out from an
- asynchronous execution will be caught and logged at error level.
- You can customize this behavior globally by overriding the
- <literal>org.jboss.seam.async.asynchronousExceptionHandler</literal>
- component:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Scope(ScopeType.STATELESS)
+]]>
+</programlisting>
+ <para>
+ The <literal>@IntervalDuration</literal>, <literal>@IntervalCron</literal>, and <literal>@IntervalNthBusinessDay</literal> annotations are mutually exclusive. Attempting to use them in the same method will cause a <exceptionname>RuntimeException</exceptionname> error.
+ </para>
+ </section>
+
+ <section>
+ <title>Asynchronous events</title>
+ <para>
+ Component-driven events can also be asynchronous. To raise an event for ansynchronous processing, call the <literal>raiseAsynchronousEvent()</literal> method of the <literal>Events</literal> class. To schedule a timed event, call the <literal>raisedTimedEvent()</literal> method and pass a schedule object. (For the default dispatcher or timer service dispatcher, use <literal>TimerSchedule</literal>.) Components can observe asynchronous events as usual, but only business process context is propagated to the asynchronous thread.
+ </para>
+ </section>
+
+ <section>
+ <title>Handling exceptions from asynchronous calls</title>
+ <para>
+ Each asynchronous dispatcher behaves differently when an exception propagates through it. For example, the <literal>java.util.concurrent</literal> suspends further executions of a repeating call, and the EJB3 timer service swallows the exception, so Seam catches any exception that propagates from the asynchronous call before it reaches the dispatcher.
+ </para>
+ <para>
+ By default, any exception that propagates from an asynchronous execution will be caught and logged at error level. You can customize this behavior globally by overriding the <literal>org.jboss.seam.async.asynchronousExceptionHandler</literal> component:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Scope(ScopeType.STATELESS)
@Name("org.jboss.seam.async.asynchronousExceptionHandler")
-public class MyAsynchronousExceptionHandler extends AsynchronousExceptionHandler {
-
- @Logger Log log;
+public class MyAsynchronousExceptionHandler
+ extends AsynchronousExceptionHandler {
+ @Logger Log log;
- @In Future timer;
+ @In Future timer;
- @Override
- public void handleException(Exception exception) {
- log.debug(exception);
- timer.cancel(false);
- }
+ @Override
+ public void handleException(Exception exception) {
+ log.debug(exception);
+ timer.cancel(false);
+ }
-}]]></programlisting>
+}]]>
+</programlisting>
+ <para>
+ Here, with <literal>java.util.concurrent</literal> dispatcher, we inject its control object and cancel all future invocations when an exception is encountered.
+ </para>
+ <para>
+ You can alter this behavior for an individual component by implementing the <literal>public void handleAsynchronousException(Exception exception);</literal> method on that component, like so:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[
+public void handleAsynchronousException(Exception exception) {
+ log.fatal(exception);
+}]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Messaging in Seam</title>
+ <para>
+ It is easy to send and receive JMS messages to and from Seam components.
+ </para>
+ <section>
+ <title>Configuration</title>
+ <para>
+ To configure Seam infrastructure to send JMS messages, you must first tell Seam about the topics and queues you want to send messages to, and where to find the <literal>QueueConnectionFactory</literal> and <literal>TopicConnectionFactory</literal>, depending on your requirements.
+ </para>
+ <para>
+ By default, Seam uses <literal>UIL2ConnectionFactory</literal>, the default connection factory with JBossMQ. If you use another JMS provider, you must set one or both of <literal>queueConnection.queueConnectionFactoryJndiName</literal> and <literal>topicConnection.topicConnectionFactoryJndiName</literal>, in either <filename>seam.properties</filename>, <filename>web.xml</filename>, or <filename>components.xml</filename>.
+ </para>
+ <para>
+ To install Seam-managed <literal>TopicPublisher</literal>s and <literal>QueueSender</literal>s, you must also list topics and queues in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![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>
+ </section>
+
+ <section>
+ <title>Sending messages</title>
+ <para>
+ Once configuration is complete, you can inject a JMS <literal>TopicPublisher</literal> and <literal>TopicSession</literal> into any component:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("stockPriceChangeNotifier")
+public class StockPriceChangeNotifier {
+ @In private TopicPublisher stockTickerPublisher;
+ @In private TopicSession topicSession;
+
+ public void publish(StockPrice price) {
+ try {
+ stockTickerPublisher.publish(topicSession
+ .createObjectMessage(price));
+ } catch (Exception ex) {
+ throw new RuntimeException(ex);
+ }
+ }
+}]]>
+</programlisting>
+ <para>
+ Or, to work with a queue:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("paymentDispatcher")
+public class PaymentDispatcher {
+ @In private QueueSender paymentQueueSender;
+
+ @In private QueueSession queueSession;
+
+ public void publish(Payment payment) {
+ try {
+ paymentQueueSender.send(queueSession.createObjectMessage(payment));
+ } catch (Exception ex) {
+ throw new RuntimeException(ex);
+ }
+ }
+}]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Receiving messages using a message-driven bean</title>
+ <para>
+ You can process messages with any EJB3 message-driven bean. Message-driven beans can sometimes be Seam components, in which case, you can inject other event- and application-scoped Seam components. The following is an example of the payment receiver, which delegates to the payment processor.
+ </para>
+ <note>
+ <para>
+ You may need to set the <varname>create</varname> attribute on the <literal>@In</literal> annotation to <literal>true</literal> so that Seam can create an instance of the component to be injected. (This is necessary only if the component does not support auto-creation — that is, it is not annotated with <literal>@Autocreate</literal>.)
+ </para>
+ </note>
<para>
- Here, for example, using <literal>java.util.concurrent</literal>
- dispatcher, we inject its control object and cancel all future
- invocations when an exception is encountered
+ First, create a message-driven bean to receive the message:
</para>
-
- <para>
- You can also alter this behavior for an individual component by
- implementing the method
- <literal>public void handleAsynchronousException(Exception exception);</literal>
- on the component. For example:
- </para>
-
- <programlisting role="JAVA"><![CDATA[ public void handleAsynchronousException(Exception exception) {
- log.fatal(exception);
- }]]></programlisting>
- </sect2>
+ <programlisting role="JAVA"><![CDATA[@MessageDriven(activationConfig =
+ {@ActivationConfigProperty(propertyName = "destinationType",
+ propertyValue = "javax.jms.Queue"),
+ @ActivationConfigProperty(propertyName = "destination",
+ propertyValue = "queue/paymentQueue")
+})
- </sect1>
+ at Name("paymentReceiver")
+public class PaymentReceiver implements MessageListener
+{
+ @Logger private Log log;
+
+ @In(create = true) private PaymentProcessor paymentProcessor;
+
+ @Override
+ public void onMessage(Message message)
+ {
+ try {
+ paymentProcessor.processPayment((Payment) ((ObjectMessage)
+ message).getObject());
+ } catch (JMSException ex) {
+ log.error("Message payload did not contain a Payment object", ex);
+ }
+ }
+}]]></programlisting>
+
+ <para>
+ Next, implement the Seam component to which the receiver will delegate payment processing:
+ </para>
+
+ <programlisting role="JAVA"><![CDATA[@Name("paymentProcessor")
+public class PaymentProcessor {
+ @In private EntityManager entityManager;
+
+ public void processPayment(Payment payment) {
+ // perhaps do something more fancy
+ entityManager.persist(payment);
+ }
+}]]></programlisting>
+
+ <para>
+ If you want to perform transaction operations in your message-driven bean, ensure that you are working with an XA datasource, or you will not be able to roll back database changes in the event that a database transaction commits, but a subsequent message operation fails.
+ </para>
+ </section>
+
+ <section>
+ <title>Receiving messages in the client</title>
+ <para>
+ Seam Remoting lets you subscribe to a JMS topic from client-side JavaScript. You can find more information in <xref linkend="remoting" />.
+ </para>
+ </section>
+
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Mail.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Mail.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Mail.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,773 +1,650 @@
-<chapter id="mail">
- <title>Email</title>
- <para>
- Seam now includes an optional components for templating and sending emails.
- </para>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- <para>
- Email support is provided by <literal>jboss-seam-mail.jar</literal>. This
- JAR contains the mail JSF controls, which are used to construct emails,
- and the <literal>mailSession</literal> manager component.
- </para>
-
- <para>
- The examples/mail project contains an example of the email support in
- action. It demonstrates proper packaging, and it contains a number of
- example that demonstrate the key features currently supported.
- </para>
+<chapter id="mail" >
+ <title>Email</title>
+ <para>
+ Seam now includes an optional component for templating and sending email.
+ </para>
+ <para>
+ Email support is provided by <filename>jboss-seam-mail.jar</filename>. This <filename>JAR</filename> contains the mail JSF controls, used to construct emails, and the <literal>mailSession</literal> manager component.
+ </para>
+ <para>
+ For a demonstration of the email support available in Seam, see the <literal>examples/mail</literal> project. This demonstrates proper packaging, and contains a number of currently-supported key features.
+ </para>
+ <para>
+ You can test your mail system with Seam's integration testing environment. See <xref linkend="testing.mail" /> for details.
+ </para>
+ <section>
+ <title>Creating a message</title>
+ <para>
+ Seam uses Facelets to template emails.
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:message xmlns="http://www.w3.org/1999/xhtml"
+ xmlns:m="http://jboss.com/products/seam/mail"
+ xmlns:h="http://java.sun.com/jsf/html">
- <para>
- You can also test your mail's using Seam's integration testing environment.
- See <xref linkend="testing.mail" />.
- </para>
+ <m:from name="Peter" address="peter at example.com" />
+ <m:to name="#{person.firstname} #{person.lastname}">
+ #{person.address}
+ </m:to>
+ <m:subject>Try out Seam!</m:subject>
- <section>
- <title>Creating a message</title>
-
- <para>
- You don't need to learn a whole new templating language to use Seam Mail
- — an email is just facelet!
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:message xmlns="http://www.w3.org/1999/xhtml"
- xmlns:m="http://jboss.com/products/seam/mail"
- xmlns:h="http://java.sun.com/jsf/html">
-
- <m:from name="Peter" address="peter at example.com" />
- <m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>
- <m:subject>Try out Seam!</m:subject>
+ <m:body>
+ <p><h:outputText value="Dear #{person.firstname}" />,</p>
+ <p>You can try out Seam by visiting
+ <a href="http://labs.jboss.com/jbossseam">
+ http://labs.jboss.com/jbossseam
+ </a>.
+ </p>
+ <p>Regards,</p>
+ <p>Pete</p>
+ </m:body>
- <m:body>
- <p><h:outputText value="Dear #{person.firstname}" />,</p>
- <p>You can try out Seam by visiting
- <a href="http://labs.jboss.com/jbossseam">http://labs.jboss.com/jbossseam</a>.</p>
- <p>Regards,</p>
- <p>Pete</p>
- </m:body>
-
-</m:message>]]></programlisting>
-
- <para>
- The <literal><m:message></literal> tag wraps the whole message,
- and tells Seam to start rendering an email. Inside the <literal><m:message></literal>
- tag we use an <literal><m:from></literal> tag to set who the
- message is from, a <literal><m:to></literal> tag to specify a
- sender (notice how we use EL as we would in a normal facelet), and a
- <literal><m:subject></literal> tag.
- </para>
-
- <para>
- The <literal><m:body></literal> tag wraps the body of the email.
- You can use regular HTML tags inside the body as well as JSF components.
- </para>
-
- <para>
- So, now you have your email template, how do you go about sending it?
- Well, at the end of rendering the <literal>m:message</literal> the
- <literal>mailSession</literal> is called to send the email, so all you
- have to do is ask Seam to render the view:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@In(create=true)
+</m:message>]]>
+</programlisting>
+ <para>
+ The <literal><![CDATA[<m:message>]]></literal> tag wraps the whole message, and tells Seam to start rendering an email. Inside the <literal><![CDATA[<m:message>]]></literal> tag, we use an <literal><![CDATA[<m:from>]]></literal> tag to specify the sender, a <literal><![CDATA[<m:to>]]></literal> tag to specify a recipient, and a <literal><![CDATA[<m:subject>]]></literal> tag. (Note that EL is used as it would be in a normal Facelet.)
+ </para>
+ <para>
+ The <literal><![CDATA[<m:body>]]></literal> tag wraps the body of the email. You can use regular HTML tags inside the body, as well as JSF components.
+ </para>
+ <para>
+ Once the <literal>m:message</literal> is rendered, the <literal>mailSession</literal> is called to send the email. To send your email, have Seam render the view:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In(create=true)
private Renderer renderer;
public void send() {
- try {
- renderer.render("/simple.xhtml");
- facesMessages.add("Email sent successfully");
- }
- catch (Exception e) {
- facesMessages.add("Email sending failed: " + e.getMessage());
- }
-}]]></programlisting>
-
- <para>
- If, for example, you entered an invalid email address, then an exception
- would be thrown, which is caught and then displayed to the user.
- </para>
-
- <section>
- <title>Attachments</title>
- <para>
- Seam makes it easy to attach files to an email. It supports most of
- the standard java types used when working with files.
- </para>
-
- <para>
- If you wanted to email the <literal>jboss-seam-mail.jar</literal>:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar"/>]]></programlisting>
-
- <para>
- Seam will load the file from the classpath, and attach it to the email.
- By default it would be attached as <literal>jboss-seam-mail.jar</literal>;
- if you wanted it to have another name you would just add the <literal>fileName</literal> attribute:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar" fileName="this-is-so-cool.jar"/>]]></programlisting>
-
- <para>
- You could also attach a <literal>java.io.File</literal>, a <literal>java.net.URL</literal>:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:attachment value="#{numbers}"/>]]></programlisting>
-
- <para>
- Or a <literal>byte[]</literal> or a <literal>java.io.InputStream</literal>:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:attachment value="#{person.photo}" contentType="image/png"/>]]></programlisting>
-
- <para>
- You'll notice that for a <literal>byte[]</literal> and a <literal>java.io.InputStream</literal>
- you need to specify the MIME type of the attachment (as that
- information is not carried as part of the file).
- </para>
-
- <para>
- And it gets even better, you can attach a Seam generated PDF, or any
- standard JSF view, just by wrapping a <literal><m:attachment></literal>
- around the normal tags you would use:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:attachment fileName="tiny.pdf">
- <p:document>
- A very tiny PDF
- </p:document>
-</m:attachment>]]></programlisting>
-
- <para>
- If you had a set of files you wanted to attach (for example a set of
- pictures loaded from a database) you can just use a <literal><ui:repeat></literal>:
- </para>
+ try {
+ renderer.render("/simple.xhtml");
+ facesMessages.add("Email sent successfully");
+ } catch (Exception e) {
+ facesMessages.add("Email sending failed: " + e.getMessage());
+ }
+}]]>
+</programlisting>
+ <para>
+ If, for example, you entered an invalid email address, then an exception is thrown, caught and then displayed to the user.
+ </para>
+ <section>
+ <title>Attachments</title>
+ <para>
+ Seam supports most standard Java types when working with files, so it is easy to attach files to an email.
+ </para>
+ <para>
+ For example, to email the <filename>jboss-seam-mail.jar</filename>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar"/>]]>
+</programlisting>
+ <para>
+ Seam loads the file from the classpath and attaches it to the email. By default, this file is attached as <filename>jboss-seam-mail.jar</filename>, but you can change the attachment name by adding and editing the <literal>fileName</literal> attribute:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar"
+ fileName="this-is-so-cool.jar"/>]]>
+</programlisting>
+ <para>
+ You can also attach a <literal>java.io.File</literal>, a <literal>java.net.URL</literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:attachment value="#{numbers}"/>]]>
+</programlisting>
+ <para>
+ Or a <literal>byte[]</literal> or a <literal>java.io.InputStream</literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:attachment value="#{person.photo}" contentType="image/png"/>]]>
+</programlisting>
+ <para>
+ For <literal>byte[]</literal> and <literal>java.io.InputStream</literal>, you will need to specify the MIME type of the attachment, since this information is not carried as part of the file.
+ </para>
+ <para>
+ You can attach a Seam-generated PDF, or any standard JSF view, by wrapping a <literal><![CDATA[<m:attachment>]]></literal> tag around your normal tags:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:attachment fileName="tiny.pdf">
+ <p:document>
+ A very tiny PDF
+ </p:document>
+</m:attachment>]]>
+</programlisting>
+ <para>
+ To attach a set of files — for example, a set of pictures loaded from a database — you can use a <literal><![CDATA[<ui:repeat>]]></literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<ui:repeat value="#{people}" var="person">
+ <m:attachment value="#{person.photo}" contentType="image/jpeg"
+ fileName="#{person.firstname}_#{person.lastname}.jpg"/>
+</ui:repeat>]]>
+</programlisting>
+ <para>
+ To display an attached image inline:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:attachment value="#{person.photo}" contentType="image/jpeg"
+ fileName="#{person.firstname}_#{person.lastname}.jpg"
+ status="personPhoto" disposition="inline" />
+<img src="cid:#{personPhoto.contentId}" />]]>
+</programlisting>
+ <para>
+ The <literal>cid:#{...}</literal> tag specifies that the attachments will be examined when attempting to locate the image. The <literal>cid</literal> — <literal>Content-ID</literal> — must match.
+ </para>
+ <para>
+ You must declare the attachment before trying to access the status object.
+ </para>
+ </section>
- <programlisting role="XHTML"><![CDATA[<ui:repeat value="#{people}" var="person">
- <m:attachment value="#{person.photo}" contentType="image/jpeg" fileName="#{person.firstname}_#{person.lastname}.jpg"/>
-</ui:repeat>]]></programlisting>
-
- <para>
- And if you want to display an attached image inline:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:attachment
- value="#{person.photo}"
- contentType="image/jpeg"
- fileName="#{person.firstname}_#{person.lastname}.jpg"
- status="personPhoto"
- disposition="inline" />
-<img src="cid:#{personPhoto.contentId}" />]]></programlisting>
-
- <para>
- You may be wondering what <literal>cid:#{...}</literal> does. Well, the
- IETF specified that by putting this as the src for your image, the
- attachments will be looked at when trying to locate the image (the
- <literal>Content-ID</literal>'s must match) — magic!
- </para>
-
- <para>
- You must declare the attachment before trying to access the status object.
- </para>
-
- </section>
-
- <section>
- <title>HTML/Text alternative part</title>
-
- <para>
- Whilst most mail readers nowadays support HTML, some don't, so you can
- add a plain text alternative to your email body:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:body>
- <f:facet name="alternative">Sorry, your email reader can't show our fancy email,
-please go to http://labs.jboss.com/jbossseam to explore Seam.</f:facet>
-</m:body>]]></programlisting>
-
+ <section>
+ <title>HTML/Text alternative part</title>
+ <para>
+ Although most mail readers support HTML, some do not. You can add a plain text alternative to your email body:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:body>
+ <f:facet name="alternative">
+ Sorry, your email reader can't show our fancy email. Please go to
+ http://labs.jboss.com/jbossseam to explore Seam.
+ </f:facet>
+</m:body>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Multiple recipients</title>
+ <para>
+ Often you will want to send an email to a group of recipients, such as your users. All recipient mail tags can be placed inside a <literal><![CDATA[<ui:repeat>]]></literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<ui:repeat value="#{allUsers} var="user">
+ <m:to name="#{user.firstname} #{user.lastname}"
+ address="#{user.emailAddress}"/>
+</ui:repeat>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Multiple messages</title>
+ <para>
+ Sometimes — for example, during a password reset — you will need to send a slightly different message to each recipient. The best way to do this is to place the whole message inside a <literal><![CDATA[<ui:repeat>]]></literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<ui:repeat value="#{people}" var="p">
+ <m:message>
+ <m:from name="#{person.firstname} #{person.lastname}">
+ #{person.address}
+ </m:from>
+ <m:to name="#{p.firstname}">#{p.address}</m:to>
+ ...
+ </m:message>
+ </ui:repeat>
+]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Templating</title>
+ <para>
+ The mail templating example shows that Facelets templating works with the Seam mail tags.
+ </para>
+ <para>
+ Our <filename>template.xhtml</filename> contains:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:message>
+ <m:from name="Seam" address="do-not-reply at jboss.com" />
+ <m:to name="#{person.firstname} #{person.lastname}">
+ #{person.address}
+ </m:to>
+ <m:subject>#{subject}</m:subject>
+ <m:body>
+ <html>
+ <body>
+ <ui:insert name="body">
+ This is the default body, specified by the template.
+ </ui:insert>
+ </body>
+ </html>
+ </m:body>
+</m:message>]]>
+</programlisting>
+ <para>
+ Our <literal>templating.xhtml</literal> contains:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<ui:param name="subject" value="Templating with Seam Mail"/>
+ <ui:define name="body">
+ <p>
+ This example demonstrates that you can easily use
+ <i>facelets templating</i> in email!
+ </p>
+ </ui:define>
+]]>
+</programlisting>
+ <para>
+ You can also use Facelets source tags in your email. These must be placed in a JAR in <literal>WEB-INF/lib</literal> because referencing the <filename>.taglib.xml</filename> from <filename>web.xml</filename> isn't reliable when using Seam Mail. (When mail is sent asynchronously, Seam Mail cannot access the full JSF or Servlet context, so it does not acknowledge <filename>web.xml</filename> configuration parameters.)
+ </para>
+ <para>
+ To configure Facelets or JSF further when sending mail, you will need to override the Renderer component and perform the configuration programmatically. This should only be done by advanced users.
+ </para>
+ </section>
+
+ <section>
+ <title>Internationalization</title>
+ <para>
+ Seam supports sending internationalized messages. By default, Seam uses encoding provided by JSF, but this can be overridden on the template:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:message charset="UTF-8">
+ ...
+</m:message>]]>
+</programlisting>
+ <para>
+ The body, subject, and recipient and sender names are encoded. You will need to make sure that Facelets parses your page with the correct character set by setting the encoding of the template:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Other Headers</title>
+ <para>
+ Seam also provides support for some additional email headers. (See <xref linkend="mail.tags" />.) You can set the importance of the email, and ask for a read receipt:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:message xmlns:m="http://jboss.com/products/seam/mail"
+ importance="low" requestReadReceipt="true"/>]]>
+</programlisting>
+ <para>
+ Otherwise, you can add any header to the message by using the <literal><![CDATA[<m:header>]]></literal> tag:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<m:header name="X-Sent-From" value="JBoss Seam"/>]]>
+</programlisting>
+ </section>
+
</section>
-
- <section>
- <title>Multiple recipients</title>
-
- <para>
- Often you'll want to send an email to a group of recipients (for
- example your users). All of the recipient mail tags can be placed
- inside a <literal><ui:repeat></literal>:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<ui:repeat value="#{allUsers} var="user">
- <m:to name="#{user.firstname} #{user.lastname}" address="#{user.emailAddress}" />
-</ui:repeat>]]></programlisting>
-
- </section>
-
- <section>
- <title>Multiple messages</title>
-
- <para>
- Sometimes, however, you need to send a slightly different message to
- each recipient (e.g. a password reset). The best way to do this is to
- place the whole message inside a <literal><ui:repeat></literal>:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<ui:repeat value="#{people}" var="p">
- <m:message>
- <m:from name="#{person.firstname} #{person.lastname}">#{person.address}</m:from>
- <m:to name="#{p.firstname}">#{p.address}</m:to>
- ...
- </m:message>
-</ui:repeat>]]></programlisting>
-
- </section>
-
- <section>
- <title>Templating</title>
-
- <para>
- The mail templating example shows that facelets templating just works
- with the Seam mail tags.
- </para>
-
- <para>
- Our <literal>template.xhtml</literal> contains:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:message>
- <m:from name="Seam" address="do-not-reply at jboss.com" />
- <m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>
- <m:subject>#{subject}</m:subject>
- <m:body>
- <html>
- <body>
- <ui:insert name="body">This is the default body, specified by the template.</ui:insert>
- </body>
- </html>
- </m:body>
-</m:message>]]></programlisting>
-
- <para>
- Our <literal>templating.xhtml</literal> contains:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<ui:param name="subject" value="Templating with Seam Mail"/>
-<ui:define name="body">
- <p>This example demonstrates that you can easily use <i>facelets templating</i> in email!</p>
-</ui:define>]]></programlisting>
-
- <para>
- You can also use facelets source tags in your email, but you must place
- them in a jar in <literal>WEB-INF/lib</literal> - referencing the
- <literal>.taglib.xml</literal> from <literal>web.xml</literal> isn't
- reliable when using Seam Mail (if you send your mail asynchrounously
- Seam Mail doesn't have access to the full JSF or Servlet context, and
- so doesn't know about <literal>web.xml</literal> configuration
- parameters).
- </para>
-
- <para>
- If you do need more configure Facelets or JSF when sending mail, you'll
- need to override the Renderer component and do the configuration
- programmatically - only for advanced users!
- </para>
-
-
- </section>
-
- <section>
- <title>Internationalisation</title>
-
- <para>
- Seam supports sending internationalised messages. By default, the
- encoding provided by JSF is used, but this can be overridden on the
- template:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:message charset="UTF-8">
- ...
-</m:message>]]></programlisting>
-
- <para>
- The body, subject and recipient (and from) name will be encoded.
- You'll need to make sure facelets uses the correct charset for parsing
- your pages by setting encoding of the template:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>]]></programlisting>
- </section>
-
- <section>
- <title>Other Headers</title>
-
- <para>
- Sometimes you'll want to add other headers to your email. Seam
- provides support for some (see <xref linkend="mail.tags" />). For
- example, we can set the importance of the email, and ask for a read
- receipt:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:message xmlns:m="http://jboss.com/products/seam/mail"
- importance="low"
- requestReadReceipt="true"/>]]></programlisting>
-
- <para>
- Otherwise you can add any header to the message using the
- <literal><m:header></literal> tag:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<m:header name="X-Sent-From" value="JBoss Seam"/>]]></programlisting>
-
- </section>
-
- </section>
- <section>
- <title>Receiving emails</title>
-
- <para>
- If you are using EJB then you can use a MDB (Message Driven Bean) to
- receive email. JBoss provides a JCA adaptor —
- <literal>mail-ra.rar</literal> — but the version distributed with
- JBoss AS has a number of limitations (and isn't bundled in some versions)
- therefore we recommend using the <literal>mail-ra.rar</literal>
- distributed with Seam (it's in the <literal>extras/</literal>
- directory in the Seam bundle). <literal>mail-ra.rar</literal> should
- be placed in <literal>$JBOSS_HOME/server/default/deploy</literal>; if the
- version of JBoss AS you use already has this file, replace it.
- </para>
-
- <note>
- <title>Technology preview </title>
- <para>Distributed mail-ra.rar in Seam is marked as technology preview, so standard support is not guaranteed.</para>
- </note>
-
- <para>
- You can configure it like this:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@MessageDriven(activationConfig={
- @ActivationConfigProperty(propertyName="mailServer", propertyValue="localhost"),
- @ActivationConfigProperty(propertyName="mailFolder", propertyValue="INBOX"),
- @ActivationConfigProperty(propertyName="storeProtocol", propertyValue="pop3"),
- @ActivationConfigProperty(propertyName="userName", propertyValue="seam"),
- @ActivationConfigProperty(propertyName="password", propertyValue="seam")
+
+ <section>
+ <title>Receiving emails</title>
+ <para>
+ If you use Enterprise JavaBeans (EJB), you can use a MDB (Message Driven Bean) to receive email. JBoss provides a JCA adaptor (<filename>mail-ra.rar</filename>), but the version distributed with the JBoss AS has a number of limitations, and is not bundled with all versions. Therefore, we recommend using the <filename>mail-ra.rar</filename> distributed with Seam. (You can find this in the <literal>extras/</literal> directory in the Seam bundle.)
+ </para>
+ <para>
+ Place <filename>mail-ra.rar</filename> in <literal>$JBOSS_HOME/server/default/deploy</literal>. If your JBoss AS already contains this file, replace it with the version in the Seam bundle.
+ </para>
+
+ <para>
+ You can configure <filename>mail-ra.rar</filename> like so:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@MessageDriven(activationConfig={
+ @ActivationConfigProperty(propertyName="mailServer",
+ propertyValue="localhost"),
+ @ActivationConfigProperty(propertyName="mailFolder",
+ propertyValue="INBOX"),
+ @ActivationConfigProperty(propertyName="storeProtocol",
+ propertyValue="pop3"),
+ @ActivationConfigProperty(propertyName="userName",
+ propertyValue="seam"),
+ @ActivationConfigProperty(propertyName="password",
+ propertyValue="seam")
})
@ResourceAdapter("mail-ra.rar")
@Name("mailListener")
public class MailListenerMDB implements MailListener {
- @In(create=true)
- private OrderProcessor orderProcessor;
+ @In(create=true)
+ private OrderProcessor orderProcessor;
- public void onMessage(Message message) {
- // Process the message
- orderProcessor.process(message.getSubject());
- }
+ public void onMessage(Message message) {
+ // Process the message
+ orderProcessor.process(message.getSubject());
+ }
-}]]></programlisting>
-
- <para>
- Each message received will cause <literal>onMessage(Message message)</literal>
- to be called. Most Seam annotations will work inside a MDB but you
- musn't access the persistence context.
- </para>
-
- <para>
- You can find more information on <literal>mail-ra.rar</literal>
- at <ulink url="http://www.jboss.org/community/wiki/InboundJavaMail">http://www.jboss.org/community/wiki/InboundJavaMail</ulink>.
- </para>
+}]]>
+</programlisting>
+ <para>
+ Each message received calls <literal>onMessage(Message message)</literal>. Most Seam annotations work inside a MDB, but you must not access the persistence context.
+ </para>
+ <para>
+ You can find more information on <filename>mail-ra.rar</filename> at <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=InboundJavaMail">http://wiki. jboss.org/wiki/Wiki.jsp?page=InboundJavaMail</ulink>.
+ </para>
+ <para>
+ You can still use <literal>mail-ra.rar</literal> if you are not using JBoss AS, but your application server may include a similar adapter file.
+ </para>
- <para>
- If you aren't using JBoss AS you can still use <literal>mail-ra.rar</literal>
- or you may find your application server includes a similar adapter.
- </para>
+ <warning>
+ <title>Distributed <filename>mail-ra.rar</filename> is a Technology Preview</title>
+ <para>Technology Preview features are not fully supported under Red Hat subscription level agreements (SLAs), may not be functionally complete, and are not intended for production use. However, these features provide early access to upcoming product innovations, enabling customers to test functionality and provide feedback during the development process. As Red Hat considers making future iterations of Technology Preview features generally available, we will provide commercially reasonable efforts to resolve any reported issues that customers experience when using these features.</para>
+ </warning>
+
+ </section>
- </section>
-
- <section>
- <title>Configuration</title>
+ <section>
+ <title>Configuration</title>
+ <para>
+ Include <filename>jboss-seam-mail.jar</filename> in your <literal>WEB-INF/lib</literal> directory to include email support in your application. If you use JBoss AS, no further configuration is required. If you do not use JBoss AS, make sure you have the JavaMail API and a copy of the Java Active Framework. The versions distributed with Seam are <filename>lib/mail.jar</filename> and <filename> lib/activation.jar</filename> respectively.)
+ </para>
+ <note>
+ <para>
+ The Seam Mail module requires both the use of the <literal>seam-ui</literal> package, and that Facelets be used as the view technology. Future versions of the library may also support the use of JSP.
+ </para>
+ </note>
+ <para>
+ The <literal>mailSession</literal> component uses JavaMail to talk to a 'real' SMTP server.
+ </para>
+ <section>
+ <title><literal>mailSession</literal></title>
+ <para>
+ If you are working in a Java EE 5 environment, a JavaMail session may be available through a JNDI lookup. Otherwise, you can use a Seam-configured session.
+ </para>
+ <para>
+ The <literal>mailSession</literal> component's properties are described in more detail in <xref linkend="components.mail" />.
+ </para>
+ <section>
+ <title>JNDI lookup in JBoss AS</title>
+ <para>
+ The JBossAS <filename>deploy/mail-service.xml</filename> configures a JavaMail session binding into JNDI. The default service configuration must be altered for your network. <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=JavaMail">http://wiki.jboss. org/wiki/Wiki.jsp?page=JavaMail</ulink> describes the service in more detail.
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:core="http://jboss.com/products/seam/core"
+ xmlns:mail="http://jboss.com/products/seam/mail">
+ <mail:mail-session session-jndi-name="java:/Mail"/>
+</components>]]>
+</programlisting>
+ <para>
+ Here, we tell Seam to retrieve the mail session bound to <literal>java:/Mail</literal> from JNDI.
+ </para>
+ </section>
+
+ <section>
+ <title>Seam-configured Session</title>
+ <para>
+ A mail session can be configured via <filename>components.xml</filename>. Here we tell Seam to use <literal>smtp.example.com</literal> as the SMTP server:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:core="http://jboss.com/products/seam/core"
+ xmlns:mail="http://jboss.com/products/seam/mail">
+ <mail:mail-session host="smtp.example.com"/>
+</components>]]>
+</programlisting>
+ </section>
+
+ </section>
- <para>
- To include Email support in your application, include <literal>jboss-seam-mail.jar</literal>
- in your <literal>WEB-INF/lib</literal> directory. If you are using JBoss
- AS there is no further configuration needed to use Seam's email support.
- Otherwise you need to make sure you have the JavaMail API, an
- implementation of the JavaMail API present (the API and impl used in
- JBoss AS are distributed with seam as <literal>lib/mail.jar</literal>),
- and a copy of the Java Activation Framework (distributed with Seam as
- <literal>lib/activation.jar</literal>.
- </para>
-
- <note>
- <para>
- The Seam Mail module requires the use of Facelets as the view
- technology. Future versions of the library may also support the use of
- JSP. Additionally, it requires the use of the seam-ui package.
- </para>
- </note>
-
- <para>
- The <literal>mailSession</literal> component uses JavaMail to talk to a
- 'real' SMTP server.
- </para>
-
- <section>
- <title><literal>mailSession</literal></title>
-
- <para>
- A JavaMail Session may be available via a JNDI lookup if you are
- working in an JEE environment or you can use a Seam configured Session.
- </para>
-
- <para>
- The mailSession component's properties are described in more detail in
- <xref linkend="components.mail"/>.
- </para>
-
- <section>
- <title>JNDI lookup in JBoss AS</title>
-
- <para>
- The JBossAS <literal>deploy/mail-service.xml</literal> configures a
- JavaMail session binding into JNDI. The default service
- configuration will need altering for your network.
- <ulink url="http://www.jboss.org/community/wiki/JavaMail">http://www.jboss.org/community/wiki/JavaMail</ulink>
- describes the service in more detail.
- </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:core="http://jboss.com/products/seam/core"
- xmlns:mail="http://jboss.com/products/seam/mail">
-
- <mail:mail-session session-jndi-name="java:/Mail"/>
-
-</components>]]></programlisting>
-
- <para>
- Here we tell Seam to get the mail session bound to
- <literal>java:/Mail</literal> from JNDI.
- </para>
-
- </section>
-
- <section>
- <title>Seam configured Session</title>
-
- <para>
- A mail session can be configured via <literal>components.xml</literal>.
- Here we tell Seam to use <literal>smtp.example.com</literal> as the
- smtp server:
- </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:core="http://jboss.com/products/seam/core"
- xmlns:mail="http://jboss.com/products/seam/mail">
-
- <mail:mail-session host="smtp.example.com"/>
-
-</components>]]></programlisting>
-
- </section>
- </section>
- </section>
+ </section>
- <section id="mail.tags">
- <title>Tags</title>
-
- <para>
- Emails are generated using tags in the <literal>http://jboss.com/products/seam/mail</literal>
- namespace. Documents should always have the <literal>message</literal>
- tag at the root of the message. The message tag prepares Seam to generate
- an email.
- </para>
-
- <para>
- The standard templating tags of facelets can be used as normal. Inside
- the body you can use any JSF tag; if it requires access to external
- resources (stylesheets, javascript) then be sure to set the
- <literal>urlBase</literal>.
- </para>
-
- <variablelist>
- <varlistentry>
- <term><m:message></term>
- <listitem>
- <para>
- Root tag of a mail message
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>importance</literal> — low, normal or high. By
- default normal, this sets the importance of the mail message.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>precedence</literal> — sets the precedence of
- the message (e.g. bulk).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>requestReadReceipt</literal> — by default false,
- if set, a read receipt request will be will be added, with the
- read receipt being sent to the <literal>From:</literal>
- address.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>urlBase</literal> — If set, the value is
- prepended to the <literal>requestContextPath</literal> allowing
- you to use components such as
- <literal><h:graphicImage></literal> in your emails.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>messageId</literal> — Sets the Message-ID explicitly
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><m:from></term>
- <listitem>
- <para>
- Set's the From: address for the email. You can only have one of
- these per email.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>name</literal> — the name the email should come
- from.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>address</literal> — the email address the email
- should come from.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><m:replyTo></term>
- <listitem>
- <para>
- Set's the Reply-to: address for the email. You can only have one
- of these per email.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>address</literal> — the email address the email
- should come from.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><m:to></term>
- <listitem>
- <para>
- Add a recipient to the email. Use multiple <m:to> tags for
- multiple recipients. This tag can be safely placed inside a repeat
- tag such as <ui:repeat>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>name</literal> — the name of the recipient.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>address</literal> — the email address of the recipient.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><m:cc></term>
- <listitem>
- <para>
- Add a cc recipient to the email. Use multiple <m:cc> tags
- for multiple ccs. This tag can be safely placed inside a iterator
- tag such as <ui:repeat>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>name</literal> — the name of the recipient.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>address</literal> — the email address of the
- recipient.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><m:bcc></term>
- <listitem>
- <para>
- Add a bcc recipient to the email. Use multiple <m:bcc>
- tags for multiple bccs. This tag can be safely placed inside a
- repeat tag such as <ui:repeat>.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>name</literal> — the name of the recipient.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>address</literal> — the email address of the
- recipient.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><m:header></term>
- <listitem>
- <para>
- Add a header to the email (e.g. <literal>X-Sent-From: JBoss Seam</literal>)
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>name</literal> — The name of the header to
- add (e.g. <literal>X-Sent-From</literal>).
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>value</literal> — The value of the header to
- add (e.g. <literal>JBoss Seam</literal>).
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><m:attachment></term>
- <listitem>
- <para>
- Add an attachment to the email.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>value</literal> — The file to attach:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>String</literal> — A <literal>String</literal>
- is interpreted as a path to file within the classpath
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>java.io.File</literal> — An EL expression
- can reference a <literal>File</literal> object
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>java.net.URL</literal> — An EL expression
- can reference a <literal>URL</literal> object
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>java.io.InputStream</literal> — An EL
- expression can reference an <literal>InputStream</literal>.
- In this case both a <literal>fileName</literal> and a
- <literal>contentType</literal> must be specified.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>byte[]</literal> — An EL expression can
- reference an <literal>byte[]</literal>. In this case both
- a <literal>fileName</literal> and a
- <literal>contentType</literal> must be specified.
- </para>
- </listitem>
- </itemizedlist>
- <para>If the value attribute is ommitted:</para>
- <itemizedlist>
- <listitem>
- <para>
- If this tag contains a <literal><p:document></literal>
- tag, the document described will be generated and
- attached to the email. A <literal>fileName</literal>
- should be specified.
- </para>
- </listitem>
- <listitem>
- <para>
- If this tag contains other JSF tags a HTML document will
- be generated from them and attached to the email. A
- <literal>fileName</literal> should be specified.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- <listitem>
- <para>
- <literal>fileName</literal> — Specify the file name to
- use for the attached file.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>contentType</literal> — Specify the MIME type
- of the attached file
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><m:subject></term>
- <listitem>
- <para>
- Set's the subject for the email.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term><m:body></term>
- <listitem>
- <para>
- Set's the body for the email. Supports an <literal>alternative</literal>
- facet which, if an HTML email is generated can contain
- alternative text for a mail reader which doesn't support html.
- </para>
- <itemizedlist>
- <listitem>
- <para>
- <literal>type</literal> — If set to <literal>plain</literal>
- then a plain text email will be generated otherwise an HTML
- email is generated.
- </para>
- </listitem>
- </itemizedlist>
- </listitem>
- </varlistentry>
- </variablelist>
- </section>
+ <!--<section>
+ <title>Meldware</title>
+ <para>
+ Meldware (from <ulink url="http://buni.org">buni.org</ulink>) is used as a mail server in Seam's mail examples. Meldware is a groupware package that provides <literal>SMTP</literal>, <literal>POP3</literal>, <literal>IMAP</literal>, webmail, a shared calendar and an graphical administration tool. It is written as a Java EE application, so it can be deployed onto JBoss AS alongside your Seam application.
+ </para>
+ <warning>
+ <para>
+ The version of Meldware distributed with Seam (downloaded on demand) is tailored for development — mailboxes, users and aliases (email addresses) are created every time the application deploys. To use Meldware in production, install the latest release from <ulink url="http://buni.org">buni.org</ulink>.
+ </para>
+ </warning>
+ </section>-->
+
+ <section id="mail.tags">
+ <title>Tags</title>
+ <para>
+ Emails are generated using tags in the <literal>http://jboss.com/products/seam/mail</literal> namespace. Documents should always have the <literal>message</literal> tag at the root of the message. The message tag prepares Seam to generate an email.
+ </para>
+ <para>
+ Facelets standard templating tags can be used as normal. Inside the <literal>body</literal>, you can use any JSF tag. If the tag requires access to external resources such as stylesheets or JavaScript, be sure to set the <literal>urlBase</literal>.
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><![CDATA[<m:message>]]></term>
+ <listitem>
+ <para>
+ Root tag of a mail message.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>importance</literal> — Sets the importance of the mail message. Valid values are <literal>low</literal>, <literal>normal</literal>, or <literal>high</literal>. Defaults to <literal>normal</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>precedence</literal> — Sets the precedence of the message, for example, <literal>bulk</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>requestReadReceipt</literal> — If set, a read receipt request will be added, and the read receipt will be sent to the <literal>From:</literal> address. Defaults to <literal>false</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>urlBase</literal> — If set, the value is prepended to the <literal>requestContextPath</literal>, allowing you to use components such as <literal><![CDATA[<h:graphicImage>]]></literal> in your emails.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>messageId</literal> — Explicitly sets the Message-ID.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><![CDATA[<m:from>]]></term>
+ <listitem>
+ <para>
+ Sets the <literal>From:</literal> address for the email. Only one exists per email.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>name</literal> — The name that the email comes from.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>address</literal> — The email address that the email comes from.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><![CDATA[<m:replyTo>]]></term>
+ <listitem>
+ <para>
+ Sets the <literal>Reply-to:</literal> address for the email. Only one exists per email.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>address</literal> — the email address the email comes from.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><![CDATA[<m:to>]]></term>
+ <listitem>
+ <para>
+ Adds a recipient to the email. Use multiple <literal><![CDATA[<m:to>]]></literal> tags for multiple recipients. This tag can be safely placed inside a repeat tag such as <literal><![CDATA[<ui:repeat>]]></literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>name</literal> — The name of the recipient.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>address</literal> — The email address of the recipient.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><![CDATA[<m:cc>]]></term>
+ <listitem>
+ <para>
+ Adds a CC recipient to the email. Use multiple <literal><![CDATA[<m:cc>]]></literal> tags for multiple CCs. This tag can be safely placed inside a iterator tag such as <![CDATA[<ui:repeat>]]>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>name</literal> — The name of the recipient.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>address</literal> — The email address of the recipient.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><![CDATA[<m:bcc>]]></term>
+ <listitem>
+ <para>
+ Adds a BCC recipient to the email. Use multiple <literal><![CDATA[<m:bcc>]]></literal> tags for multiple bccs. This tag can be safely placed inside a repeat tag such as <literal><![CDATA[<ui:repeat>]]></literal>.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>name</literal> — The name of the recipient.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>address</literal> — The email address of the recipient.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><![CDATA[<m:header>]]></term>
+ <listitem>
+ <para>
+ Adds a header to the email. (For example, <literal>X-Sent-From: JBoss Seam</literal>.)
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>name</literal> — The name of the header to add. (For example, <literal>X-Sent-From</literal>.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>value</literal> — The value of the header to add. (For example, <literal>JBoss Seam</literal>.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><![CDATA[<m:attachment>]]></term>
+ <listitem>
+ <para>
+ Adds an attachment to the email.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>value</literal> — The file to attach:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>String</literal> — A <literal>String</literal> is interpreted as a path to file within the classpath.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>java.io.File</literal> — An EL expression can reference a <literal>File</literal> object.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>java.net.URL</literal> — An EL expression can reference a <literal>URL</literal> object.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>java.io.InputStream</literal> — An EL expression can reference an <literal>InputStream</literal>. In this case both a <literal>fileName</literal> and a <literal>contentType</literal> must be specified.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>byte[]</literal> — An EL expression can reference a <literal>byte[]</literal>. In this case both a <literal>fileName</literal> and a <literal>contentType</literal> must be specified.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ If the value attribute is ommitted:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ If this tag contains a <literal><![CDATA[<p:document>]]></literal> tag, the document described will be generated and attached to the email. A <literal>fileName</literal> should be specified.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ If this tag contains other JSF tags, a HTML document will be generated from them and attached to the email. A <literal>fileName</literal> should be specified.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>fileName</literal> — Specifies the file name to use for the attached file.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>contentType</literal> — Specifies the MIME type of the attached file.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><![CDATA[<m:subject>]]></term>
+ <listitem>
+ <para>
+ Sets the subject for the email.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><![CDATA[<m:body>]]></term>
+ <listitem>
+ <para>
+ Sets the body for the email. Supports an <literal>alternative</literal> facet which, if a HTML email is generated, can contain alternative text for a mail reader which doesn't support HTML.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>type</literal> — If set to <literal>plain</literal>, a plain text email will be generated. Otherwise, a HTML email is generated.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </section>
+
</chapter>
+
Added: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Migration.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Migration.xml (rev 0)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Migration.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -0,0 +1,550 @@
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter id="Migration">
+ <title>Migration</title>
+ <para>
+ If you already have a previous version of Seam installed, you will need to follow the instructions in this chapter to migrate to latest version (2.2.0), which is available with the JBoss Enterprise Application Platform.
+ </para>
+ <para>
+ If you are already using Seam 2.0, you can skip directly to <xref linkend="MigrationFrom20" />. If you are currently using Seam 1.2.x, you will need to follow the instructions in both <xref linkend="MigrationFrom12" /> and <xref linkend="MigrationFrom20" />.
+ </para>
+ <section id="MigrationFrom12">
+ <title>Migrating from Seam 1.2.x to Seam 2.0</title>
+ <para>
+ In this section, we show you how to migrate from Seam 1.2.x to Seam 2.0. We also list the changes to Seam components between versions.
+ </para>
+
+ <section id="Migration12.JSF12">
+ <title>Migrating to JavaServer Faces 1.2</title>
+ <para>
+ Seam 2.0 requires JSF 1.2 to work correctly. We recommend Sun's JSF Reference Implementation (RI), which ships with most Java EE 5 application servers, including JBoss 4.2. To switch to the JSF RI, you will need to make the following changes to your <filename>web.xml</filename>:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Remove the MyFaces <literal>StartupServletContextListener</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Remove the AJAX4JSF filter, mappings, and <literal>org.ajax4jsf.VIEW_HANDLERS</literal> context parameter.</para>
+ </listitem>
+ <listitem>
+ <para>Rename <literal>org.jboss.seam.web.SeamFilter</literal> as <literal>org.jboss.seam.servlet.SeamFilter</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Rename <literal>org.jboss.seam.servlet.ResourceServlet</literal> as <literal>org.jboss.seam.servlet.SeamResourceServlet</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Change the <varname>web-app</varname> version from <literal>2.4</literal> to <literal>2.5</literal>. In the namespace URL, change <literal>j2ee</literal> to <literal>javaee</literal>. For example:</para>
+<programlisting role="XML"><![CDATA[<web-app xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd" version="2.5">
+ ...
+ </web-app>]]>
+</programlisting>
+ </listitem>
+ </itemizedlist>
+ <para>
+ As of Seam 1.2, you can declare <literal>SeamFilter</literal> in <filename>web.xml</filename> instead of explicitly declaring <literal>SeamExceptionFilter</literal> and <literal>SeamRedirectFilter</literal> in <filename>web.xml</filename>.
+ </para>
+ <para>
+ Client-side state saving is not required with the JSF RI, and can be removed. (Client-side state saving is defined by the <literal>javax.faces.STATE_SAVING_METHOD</literal> context parameter.
+ </para>
+ <para>
+ You will also need to make the following changes to <filename>faces-config.xml</filename>:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Remove the <literal>TransactionalSeamPhaseListener</literal> or <literal>SeamPhaseListener</literal> declaration, if in use.</para>
+ </listitem>
+ <listitem>
+ <para>Remove the <literal>SeamELResolver</literal> declaration, if in use.</para>
+ </listitem>
+ <listitem>
+ <para>Change the <literal>SeamFaceletViewHandler</literal> declaration to the standard <literal>com.sun.facelets.FaceletViewHandler</literal>, and ensure it is enabled.</para>
+ </listitem>
+ <listitem>
+ <para>Remove the Document Type Declaration (DTD) from the document and add the XML Schema declarations to the <literal><![CDATA[<faces-config>]]></literal> root tag, like so:</para>
+<programlisting role="XML"><![CDATA[<faces-config version="1.2"
+ xmlns="http://java.sun.com/xml/ns/javaee"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd">
+ ...
+</faces-config>]]>
+</programlisting>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="Migration12.Code">
+ <title>Code Migration</title>
+ <para>
+ Seam's built-in components have been reorganized to make them easier to learn and to isolate particular technology dependencies into specific packages.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Persistence-related components have been moved to <literal>org.jboss.seam.persistence</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>jBPM-related components have been moved to <literal>org.jboss.seam.bpm</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>JSF-related components, most notably <literal>org.jboss.seam.faces.FacesMessages</literal>, have been moved to <literal>org.jboss.seam.faces</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Servlet-related components have been moved to <literal>org.jboss.seam.web</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Components related to asynchronicity have been moved to <literal>org.jboss.seam.async</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Internationalization-related components have been moved to <literal>org.jboss.seam.international</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>The Pageflow component has been moved to <literal>org.jboss.seam.pageflow</literal>.</para>
+ </listitem>
+ <listitem>
+ <para>The Pages component has been moved to <literal>org.jboss.seam.navigation</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Any code that depends upon these APIs will need to be altered to reflect the new Java package names.
+ </para>
+ <para>
+ Annotations have also been reorganized:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>BPM-related annotations are now included in the <literal>org.jboss.seam.annotations.bpm</literal> package.</para>
+ </listitem>
+ <listitem>
+ <para>JSF-related annotations are now included in the <literal>org.jboss.seam.annotations.faces</literal> package.</para>
+ </listitem>
+ <listitem>
+ <para>Interceptor annotations are now included in the <literal>org.jboss.seam.annotations.intercept</literal> package.</para>
+ </listitem>
+ <listitem>
+ <para>Annotations related to asynchronicity are now included in the <literal>org.jboss.seam.annotations.async</literal> package.</para>
+ </listitem>
+ <listitem>
+ <para><literal>@RequestParameter</literal> is now included inthe <literal>org.jboss.seam.annotations.web</literal> package.</para>
+ </listitem>
+ <listitem>
+ <para><literal>@WebRemote</literal> is now included in the <literal>org.jboss.seam.annotations.remoting</literal> package.</para>
+ </listitem>
+ <listitem>
+ <para><literal>@Restrict</literal> is now included in the <literal>org.jboss.seam.annotations.security</literal> package.</para>
+ </listitem>
+ <listitem>
+ <para>Exception handling annotations are now included in the <literal>org.jboss.seam.annotations.exception</literal> package.</para>
+ </listitem>
+ <listitem>
+ <para>Use <literal>@BypassInterceptors</literal> instead of <literal>@Intercept(NEVER)</literal>.</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+ <section id="Migration12.Components">
+ <title>Migrating <filename>components.xml</filename></title>
+ <para>The new packaging system outlined in the previous section means that you must update <filename>components.xml</filename> with the new schemas and namespaces.</para>
+ <para>
+ Namespaces originally took the form <literal>org.jboss.seam.foobar</literal>. The new namespace format is <literal>http://jboss.com/products/seam/foobar</literal>, and the schema is of the form <literal>http://jboss.com/products/seam/foobar-2.0.xsd</literal>. You will need to update the format of the namespaces and schemas in your <filename>components.xml</filename> file so that the URLs correspond to the version of Seam that you wish to migrate to (2.0 or 2.1).
+ </para>
+ <para>
+ The following declarations must have their locations corrected, or be removed entirely:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>Replace <literal><![CDATA[<core:managed-persistence-context>]]></literal> with <literal><![CDATA[<persistence:managed-persistence-context>]]></literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Replace <literal><![CDATA[<core:entity-manager-factory>]]></literal> with <literal><![CDATA[<persistence:entity-manager-factory>]]></literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Remove <varname>conversation-is-long-running</varname> parameter from <literal><![CDATA[<core:manager/>]]></literal> element.</para>
+ </listitem>
+ <listitem>
+ <para>Remove <literal><![CDATA[<core:ejb/>]]></literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Remove <literal><![CDATA[<core:microcontainer/>]]></literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Replace <literal><![CDATA[<core:transaction-listener/>]]></literal> with <literal><![CDATA[<transaction:ejb-transaction/>]]></literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Replace <literal><![CDATA[<core:resource-bundle/>]]></literal> with <literal><![CDATA[<core:resource-loader/>]]></literal>.</para>
+ </listitem>
+ </itemizedlist>
+ <note>
+ <para>
+ Seam transaction management is now enabled by default. It is now controlled by <filename>components.xml</filename> instead of a JSF phase listener declaration in <filename>faces-config.xml</filename>. To disable Seam-managed transactions, use the following:
+ </para>
+<programlisting role="XML"><![CDATA[<core:init transaction-management-enabled="false"/>]]></programlisting>
+ </note>
+ <note>
+ <para>
+ The <varname>expression</varname> attribute on <literal>event</literal> <literal>action</literal>s has been deprecated in favour of <literal>execute</literal>. For example:
+ </para>
+<programlisting role="XML"><![CDATA[<event type="org.jboss.seam.security.notLoggedIn">
+ <action execute="#{redirect.captureCurrentView}"/>
+</event>
+<event type="org.jboss.seam.loginSuccessful">
+ <action execute="#{redirect.returnToCapturedView}"/>
+</event>]]></programlisting>
+ </note>
+ <para>
+ In Seam 2.1, security events use the <literal>org.jboss.seam.security></literal> prefix instead of <literal>org.jboss.seam</literal>. (For example, <literal>org.jboss.seam.security.notLoggedIn</literal>.)
+ </para>
+ <note>
+ <para>
+ Instead of the <literal> org.jboss.seam.postAuthenticate</literal> event, use the <literal>org.jboss.seam.security.loginSuccessful</literal> event to return to the captured view.
+ </para>
+ </note>
+ </section>
+ <section id="Migration12.Embedded">
+ <title>Migrating to Embedded JBoss</title>
+ <para>
+ Embedded JBoss no longer supports the use of JBoss Embeddable EJB3 or JBoss Microcontainer. Instead, the new Embedded JBoss distribution provides a complete set of Java EE-compatible APIs with simplified deployment.
+ </para>
+ <para>
+ For testing, you will need to include the following in your classpath:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>the <filename>jar</filename>s in Seam's <filename>lib/</filename> directory</para>
+ </listitem>
+ <listitem>
+ <para>the <filename>bootstrap/</filename> directory</para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Remove any references or artifacts relating to JBoss Embeddable EJB3, such as the <filename>embeddded-ejb</filename> directory and <filename>jboss-beans.xml</filename>. (You can use the Seam examples as reference.)
+ </para>
+ <para>
+ There are no longer any special configuration or packaging requirements for Tomcat deployment. To deploy with Tomcat, follow the instructions in the User Guide.<!--#modify: The Tomcat UG, or the Seam UG?-->
+ </para>
+ <note>
+ <para>
+ Embedded JBoss can bootstrap a datasource from a <filename>-ds.xml</filename> file, so the <filename>jboss-beans.xml</filename> file is no longer required.
+ </para>
+ </note>
+ </section>
+ <section id="Migration12.BPM">
+ <title>Migrating to jBPM 3.2</title>
+ <para>
+ If you use jBPM for business processes as well as pageflows, you must add the <literal>tx</literal> service to <filename>jbpm.cfg.xml</filename>:
+ </para>
+<programlisting role="XML"><![CDATA[<service name="tx" factory="org.jbpm.tx.TxServiceFactory" />]]>
+</programlisting>
+ </section>
+ <section id="Migration12.RFC">
+ <title>Migrating to RichFaces 3.1</title>
+ <para>
+ There has been a major reorganization of the codebase for both RichFaces and AJAX4JSF. The <filename>ajax4jsf.jar</filename> and <filename>richfaces.jar</filename> <filename>jar</filename>s have been replaced with the <filename>richfaces-api.jar</filename> (to be placed in the EAR <filename>lib/</filename> directory) and the <filename>richfaces-impl.jar</filename> and <filename>richfaces-ui.jar</filename> (to be placed in <filename>WEB-INF/lib</filename>).
+ </para>
+ <para>
+ <literal><![CDATA[<s:selectDate>]]></literal> has been deprecated in favour of <literal><![CDATA[<rich:calendar>]]></literal>. There will be no further development of <literal><![CDATA[<s:selectDate>]]></literal>. The styles associated with the data picker should be removed from your style sheet to reduce bandwidth use.
+ </para>
+ <para>
+ Check the RichFaces documentation for more information about changes to namespace and parameter names.
+ </para>
+ </section>
+ <section id="Migration12.Changes">
+ <title>Changes to Components</title>
+ <formalpara id="Migration12.Changes.Packaging">
+ <title>Packaging Changes</title>
+ <para>
+ All dependencies that were previously declared as modules in <filename>application.xml</filename> should now be placed in the <filename>lib/</filename> directory of your EAR, <emphasis>except</emphasis> <filename>jboss-seam.jar</filename>, which should be declared as an EJB module in <filename>application.xml</filename>.
+ </para>
+ </formalpara>
+ <formalpara id="Migration12.Changes.UI">
+ <title>Changes to the Seam User Interface</title>
+ <para>
+ <literal><![CDATA[<s:decorate>]]></literal> has become a naming container. Client IDs have therefore changed from <literal>fooForm:fooInput</literal> to <literal>fooForm:foo:fooInput</literal>, assuming that the following has been declared:
+ </para>
+ </formalpara>
+<programlisting role="XML"><![CDATA[<h:form id="fooForm">
+ <s:decorate id="foo">
+ <h:inputText id="fooInput" value="#{bean.property}"/>
+ </s:decorate>
+</h:form>]]>
+</programlisting>
+ <para>
+ If you do not provide an ID for <literal><![CDATA[<s:decorate>]]></literal>, JSF will generate an ID automatically.
+ </para>
+ <formalpara id="Migration12.Changes.SeamGen">
+ <title>Changes to <application>seam-gen</application></title>
+ <para>
+ Since Seam 2.0.0.CR2, there have been changes to the organization of generated classes in <application>seam-gen</application> when <literal>generate-entities</literal> is executed.
+ </para>
+ </formalpara>
+ <para>
+ Originally, classes were generated as follows:
+ </para>
+ <screen>
+ src/model/com/domain/projectname/model/EntityName.java
+ src/action/com/domain/projectname/model/EntityNameHome.java
+ src/action/com/domain/projectname/model/EntityNameList.java
+ </screen>
+ <para>
+ Now, they are generated like this:
+ </para>
+ <screen>
+ src/model/com/domain/projectname/model/EntityName.java
+ src/action/com/domain/projectname/action/EntityNameHome.java
+ src/action/com/domain/projectname/action/EntityNameList.java
+ </screen>
+ <para>
+ Home and Query objects are <emphasis>action</emphasis> components, not <emphasis>model</emphasis> components, and are therefore placed in the <literal>action</literal> package. This makes <literal>generate-entities</literal> conventions consistent with those of the <literal>new-entity</literal> command.
+ </para>
+ <para>
+ Model classes are listed separately because they cannot be hot-reloaded.
+ </para>
+ <para>
+ Since the testing system has changed from JBoss Embeddable EJB3 to Embedded JBoss, we recommend that you generate a project with <application>seam-gen</application> in Seam 2.x, and use its <filename>build.xml</filename> file as a base for new projects. If you have made extensive changes to the <filename>build.xml</filename>, you can focus on migrating only test-related targets.
+ </para>
+ <para>
+ For tests to work under Embedded JBoss, you need to change the value of the <literal><![CDATA[<datasource>]]></literal> element in <filename>resources/META-INF/persistence-test.xml</filename> (or <filename>persistence-test-war.xml</filename>) to <literal>java:/DefaultDS</literal>. Alternatively, you can deploy a <filename>-ds.xml</filename> file to the <filename>bootstrap/deploy</filename> folder and use the JNDI name defined in that file.
+ </para>
+ <para>
+ If you use the Seam 2.x <filename>build.xml</filename> as described, you will also require the <filename>deployed-*.list</filename> files, which define the <filename>jar</filename> files that are packaged in the EAR or WAR archive. These were introduced to remove the <filename>jar</filename> set from the <filename>build.xml</filename> file.
+ </para>
+ <para>
+ Add the following CSS to your style sheet to allow your style to accomodate a change in the RichFaces panel. Failing to add this code will mean that, in any page created by <literal>generate-entities</literal>, the <emphasis>search criteria</emphasis> block will bleed into the <emphasis>results table</emphasis>.
+ </para>
+<programlisting>
+.rich-stglpanel-body {
+ overflow: auto;
+}
+</programlisting>
+ </section>
+ </section>
+ <section id="MigrationFrom20">
+ <title>Migrating from Seam 2.0 to Seam 2.1 or 2.2</title>
+ <para>
+ This section describes the changes between Seam 2.0 and Seam 2.1 or 2.2. If you are trying to migrate from Seam 1.2.x, you will need to read the previous section, <xref linkend="MigrationFrom12"/>, before following any steps outlined in this section.
+ </para>
+ <section id="Migration20.Changes">
+ <title>Changes to Components</title>
+ <formalpara id="Migration20.Changes.Testing">
+ <title>Testing</title>
+ <para>
+ <literal>SeamTest</literal> now boots Seam at the start of each suite, instead of the start of each class. This improves speed. Check the reference guide if you wish to alter the default.
+ </para>
+ </formalpara>
+ <formalpara id="Migration20.Changes.DTD">
+ <title>Changes to DTD and Schema Format</title>
+ <para>
+ Document Type Declarations (DTDs) for Seam XML files are no longer supported. XML Schema Declarations (XSDs) should be used for validation instead. Any file that uses Seam 2.0 XSDs should be updated to refer to the Seam 2.1 XSDs instead.
+ </para>
+ </formalpara>
+ <formalpara id="Migration20.Changes.Exceptions">
+ <title>Changes to Exception Handling</title>
+ <para>
+ Caught exceptions are now available in EL as <literal>#{org.jboss.seam.caughtException}</literal>. They are no longer available in <literal>#{org.jboss.seam.exception}</literal> form.
+ </para>
+ </formalpara>
+ <formalpara id="Migration20.Changes.EntityConverter">
+ <title>Changes to EntityConverter Configuration</title>
+ <para>
+ You can now configure the entity manager used from the <literal>entity-loader</literal> component. For further details, see the documentation.
+ </para>
+ </formalpara>
+ <formalpara id="Migration20.Changes.HibernateSessions">
+ <title>Changes in Managed Hibernate Sessions</title>
+ <para>
+ Several aspects of Seam, including the Seam Application Framework, rely upon the existence of a common naming convention between the Seam-managed Persistence Context (JPA) and the Hibernate Session. In versions earlier than Seam 2.1, the name of the managed Hibernate Session was assumed to be <literal>session</literal>. Since <literal>session</literal> is an overloaded term in Seam and the Java Servlet API, the default has been changed to <literal>hibernateSession</literal> to reduce ambiguity. This means that, when you inject or resolve the Hibernate Session, it is much easier to identify the appropriate session.
+ </para>
+ </formalpara>
+ <para>
+ You can use either of these approaches to inject the Hibernate Session:
+ </para>
+<programlisting role="JAVA">
+ at In private Session hibernateSession;
+</programlisting>
+<programlisting role="JAVA">
+ at In(name = "hibernateSession") private Session session;
+</programlisting>
+ <para>
+ If your Seam-managed Hibernate Session is still named <literal>session</literal>, you can inject the reference explicitly with the <varname>session</varname> property:
+ </para>
+<programlisting role="XML"><![CDATA[<framework:hibernate-entity-home session="#{session}".../>
+<transaction:entity-transaction session="#{session}".../>]]>
+</programlisting>
+ <para>
+ Alternatively, you can override the <literal>getPersistenceContextName()</literal> method on any persistence controller in the Seam Application Framework with the following:
+ </para>
+<programlisting role="JAVA">
+public String getPersistenceContextName() {
+ "session";
+}
+</programlisting>
+ <formalpara id="Migration20.Changes.Security">
+ <title>Changes to Security</title>
+ <para>
+ The configuration for security rules in <filename>components.xml</filename> has changed for projects that use rule-based security. Previously, rules were configured as a property of the <literal>identity</literal> component:
+ </para>
+ </formalpara>
+<programlisting role="XML"><![CDATA[<security:identity security-rules="#{securityRules}"
+ authenticate-method="#{authenticator.authenticate}"/>]]>
+</programlisting>
+ <para>
+ Seam 2.1 uses the <literal>ruleBasedPermissionResolver</literal> component for its rule-based permission checks. You must activate this component and register the security rules with it instead of with the <literal>identity</literal> component:
+ </para>
+<programlisting><![CDATA[<security:rule-based-permission-resolver
+ security-rules="#{securityRules}"/>]]>
+</programlisting>
+ <important>
+ <para>
+ The definition of a <emphasis>permission</emphasis> has changed. Prior to Seam 2.1, a permission consisted of three elements:
+ </para>
+ <itemizedlist>
+ <listitem><para>name</para></listitem>
+ <listitem><para>action</para></listitem>
+ <listitem><para>contextual object (optional)</para></listitem>
+ </itemizedlist>
+ <para>
+ The <emphasis>name</emphasis> would typically be the Seam component's name, entity class, or view ID. The <emphasis>action</emphasis> would be the method name, the JSF phase (restore or render), or an assigned term representing the intent of the activity. Optionally, one or more contextual objects can be inserted directly into the working memory to assist in decision-making. Typically, this would be the target of the activity. For example:
+ </para>
+<programlisting role="JAVA">s:hasPermission('userManager', 'edit', user)</programlisting>
+ <para>
+ In Seam 2.1, permissions have been simplified so that they contain two elements:
+ </para>
+ <itemizedlist>
+ <listitem><para>target</para></listitem>
+ <listitem><para>action</para></listitem>
+ </itemizedlist>
+ <para>
+ The <emphasis>target</emphasis> replaces the <emphasis>name</emphasis> element, becoming the focus of the permission. The <emphasis>action</emphasis> still communicates the intent of the activity to be secured. Within the rules file, most checking now revolves around the <emphasis>target</emphasis> object. For example:
+ </para>
+<programlisting role="JAVA">s:hasPermission(user, 'edit')</programlisting>
+ <para>
+ This change means that the rules can be applied more broadly, and lets Seam consult a persistent permission resolver (ACL) as well as the rule-based resolver.
+ </para>
+ <para>
+ Additionally, keep in mind that existing rules may behave oddly. This is because, given the following permission check format:
+ </para>
+ <programlisting>s:hasPermission('userManager', 'edit', user)</programlisting>
+ <para>
+ Seam transposes the following to apply the new permission format:
+ </para>
+ <programlisting>s:hasPemrission(user, 'edit')</programlisting>
+ <para>
+ Read the Security chapter for a complete overview of the new design.
+ </para>
+ </important>
+ <formalpara id="Migration20.Changes.Identity">
+ <title>Changes to Identity.isLoggedIn()</title>
+ <para>
+ This method will no longer attempt to perform an authentication check if credentials have been set. Instead, it will return <literal>true</literal> if the user is currently unauthenticated. To make use of the previous behaviour, use <literal>Identity.tryLogin()</literal> instead.
+ </para>
+ </formalpara>
+ <para>
+ If you use Seam's token-based <emphasis>Remember-Me</emphasis> feature, you must add the following section to <filename>components.xml</filename> to ensure that the user is logged in automatically when the application is first accessed:
+ </para>
+<programlisting role="XML"><![CDATA[<event type="org.jboss.seam.security.notLoggedIn">
+ <action execute="#{redirect.captureCurrentView}"/>
+ <action execute="#{identity.tryLogin}"/>
+</event>
+<event type="org.jboss.seam.security.loginSuccessful">
+ <action execute="#{redirect.returnToCapturedView}"/>
+</event>]]>
+</programlisting>
+ <formalpara id="Migration20.Changes.iText">
+ <title>Changes to iText (PDF)</title>
+ <para>
+ The <literal>documentStore</literal> component has been moved from the external <literal>pdf/itext</literal> module into Seam itself. Any references to <literal>pdf:document-store</literal> in <filename>components.xml</filename> should therefore be replaced with <literal>document:document-store</literal>. Similarly, if your <filename>web.xml</filename> references <literal>org.jboss.seam.pdf.DocumentStoreServlet</literal>, you should change the reference to <literal>org.jboss.seam.document.DocumentStoreServlet</literal>.
+ </para>
+ </formalpara>
+ <formalpara id="Migration20.Changes.Clustering">
+ <title>Changes to Clustering</title>
+ <para>
+ Seam's <literal>ManagedEntityInterceptor</literal> (previously <literal>ManagedEntityIdentityInterceptor</literal>) is now disabled by default. If you need the <literal>ManagedEntityInterceptor</literal> for clustered conversation failover, you can enable it in <filename>components.xml</filename> with the following:
+ </para>
+ </formalpara>
+<programlisting role="XML"><![CDATA[<core:init>
+ <core:interceptors>
+ <value>org.jboss.seam.core.SynchronizationInterceptor</value>
+ <value>org.jboss.seam.async.AsynchronousInterceptor</value>
+ <value>org.jboss.seam.ejb.RemoveInterceptor</value>
+ <value>org.jboss.seam.persistence.HibernateSessionProxyInterceptor</value>
+ <value>org.jboss.seam.persistence.EntityManagerProxyInterceptor</value>
+ <value>org.jboss.seam.core.MethodContextInterceptor</value>
+ <value>org.jboss.seam.core.EventInterceptor</value>
+ <value>org.jboss.seam.core.ConversationalInterceptor</value>
+ <value>org.jboss.seam.bpm.BusinessProcessInterceptor</value>
+ <value>org.jboss.seam.core.ConversationInterceptor</value>
+ <value>org.jboss.seam.core.BijectionInterceptor</value>
+ <value>org.jboss.seam.transaction.RollbackInterceptor</value>
+ <value>org.jboss.seam.transaction.TransactionInterceptor</value>
+ <value>org.jboss.seam.webservice.WSSecurityInterceptor</value>
+ <value>org.jboss.seam.security.SecurityInterceptor</value>
+ <value>org.jboss.seam.persistence.ManagedEntityInterceptor</value>
+ </core:interceptors>
+</core:init>]]>
+</programlisting>
+ <formalpara id="Migration20.Changes.Async">
+ <title>Changes to Asynchronous Exception Handling</title>
+ <para>
+ All asynchronous invocations are now wrapped by exception handling. By default, any exceptions that propagate out of an asynchronous call are caught and logged at the error level. You will find further information in <xref linkend="jms"/>.
+ </para>
+ </formalpara>
+ <formalpara id="Migration20.Changes.Redeploy">
+ <title>Changes to Redeploy Events</title>
+ <para>
+ The <literal>org.jboss.seam.postInitialization</literal> event is no longer called upon redeployment. <literal>org.jboss.seam.postReInitialization</literal> is called instead.
+ </para>
+ </formalpara>
+ <formalpara id="Migration20.Changes.Cache">
+ <title>Changes to Cache Support</title>
+ <para>
+ Cache support in Seam has been rewritten to support JBoss Cache, JBoss POJO Cache, JBoss
+Cache 2 and EHCache. If you use JBoss AS 4.2.x, JBoss Cache 1.x will be used. If you use JBoss 5.x, then JBoss Cache 2 will be installed. Further information is available in <xref linkend="cache"/>.
+ </para>
+ </formalpara>
+ <para>
+ The <literal><![CDATA[<s:cache />]]></literal> has not changed, but the <literal>pojoCache</literal> component can no longer be injected. Instead, configure JBoss POJO Cache as your cache provider in <filename>components.xml</filename>, like so:
+ </para>
+<programlisting role="XML"><![CDATA[<cache:jboss-pojo-cache-provider />]]>
+</programlisting>
+ <para>
+ Then, inject it:
+ </para>
+<programlisting><![CDATA[@In CacheProvider<PojoCache> cacheProvider;]]>
+</programlisting>
+ <para>
+ The <literal>CacheProvider</literal> provides a Map-like interface. The <literal>getDelegate()</literal> method can then be used to retrieve the underlying cache.
+ </para>
+ <formalpara>
+ <title>Changes to Maven Dependencies</title>
+ <para>
+ The provided platform is now JBoss AS 5.1.0, so <literal>javaassist:javaassist</literal> and <literal>dom4j:dom4j</literal> are now marked as <emphasis>provided</emphasis>.
+ </para>
+ </formalpara>
+ <formalpara>
+ <title>Changes to the Seam Application Framework</title>
+ <para>
+ A number of properties now expect value expressions:
+ </para>
+ </formalpara>
+ <itemizedlist>
+ <listitem><para><literal>entityHome.createdMessage</literal></para></listitem>
+ <listitem><para><literal>entityHome.updatedMessage</literal></para></listitem>
+ <listitem><para><literal>entityHome.deletedMessage</literal></para></listitem>
+ <listitem><para><literal>entityQuery.restrictions</literal></para></listitem>
+ </itemizedlist>
+ <para>
+ If you configure these objects with <filename>components.xml</filename>, no changes are necessary. If you configure the objects with JavaScript, you must create a value expression as follows:
+ </para>
+<programlisting role="JAVA">
+public ValueExpression getCreatedMessage() {
+ return createValueExpression("New person #{person.firstName}
+ #{person.lastName} created");
+}
+</programlisting>
+ </section>
+ </section>
+</chapter>
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Performance.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Performance.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Performance.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,63 +1,46 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="performance">
- <title>Performance Tuning</title>
-
- <para>
- This chapter is an attempt to document in one place all the tips for getting the best performance from
- your Seam application.
- </para>
-
- <section>
- <title>Bypassing Interceptors</title>
-
- <para>
- For repetitive value bindings such as those found in a JSF dataTable or other iterative control
- (like <literal>ui:repeat</literal>), the full interceptor stack will be invoked for every invocation of
- the referenced Seam component. The effect of this can result in a substantial performance hit, especially
- if the component is accessed many times. A significant performance gain can be achieved by disabling the
- interceptor stack for the Seam component being invoked. To disable interceptors for the component, add the
- <literal>@BypassInterceptors</literal> annotation to the component class.
- </para>
-
- <warning>
- <para>
- It is very important to be aware of the implications of disabling interceptors for a Seam component.
- Features such as bijection, annotated security restrictions, synchronization and others are
- unavailable for a component marked with <literal>@BypassInterceptors</literal>. While in most cases
- it is possible to compensate for the loss of these features (e.g. instead of injecting a component
- using <literal>@In</literal>, you can use <literal>Component.getInstance()</literal> instead) it is
- important to be aware of the consequences.
- </para>
- </warning>
-
- <para>
- The following code listing demonstrates a Seam component with its interceptors disabled:
- </para>
-
- <programlisting><![CDATA[@Name("foo")
+<chapter id="performance" >
+ <title>Performance Tuning</title>
+ <para>
+ This chapter contains tips for getting the best performance from your Seam application.
+ </para>
+ <section>
+ <title>Bypassing Interceptors</title>
+ <para>
+ For repetitive value bindings such as those found in JavaServer Faces (JSF) dataTables, or in iterative controls such as <literal>ui:repeat</literal>, the full interceptor stack is invoked upon each invocation of the referenced Seam component. This can substantially decrease performance, particularly if the component is accessed many times. You can improve performance by disabling the interceptor stack for the invoked Seam component —annotate the component class with <literal>@BypassInterceptors</literal>.
+ </para>
+ <warning>
+ <para>
+ Before you disable the interceptors, note that any component marked with <literal>@BypassInterceptors</literal> cannot use features such as bijection, annotated security restrictions, or synchronization. However, you can usually compensate for the loss of these features —for example, instead of injecting a component with <literal>@In</literal>, you can use <literal>Component.getInstance()</literal> instead.
+ </para>
+ </warning>
+ <para>
+ The following code listing demonstrates a Seam component with its interceptors disabled:
+ </para>
+
+<programlisting><![CDATA[
+ at Name("foo")
@Scope(EVENT)
@BypassInterceptors
-public class Foo
-{
- public String getRowActions()
- {
- // Role-based security check performed inline instead of using @Restrict or other security annotation
- Identity.instance().checkRole("user");
+public class Foo {
+ public String getRowActions() {
+ // Role-based security check performed inline instead of using
+ // @Restrict or other security annotation
+ Identity.instance().checkRole("user");
- // Inline code to lookup component instead of using @In
- Bar bar = (Bar) Component.getInstance("bar");
+ // Inline code to lookup component instead of using @In
+ Bar bar = (Bar) Component.getInstance("bar");
- String actions;
- // some code here that does something
- return actions;
- }
-}]]></programlisting>
-
-
-
- </section>
-
-
-</chapter>
\ No newline at end of file
+ String actions;
+ // some code here that does something
+ return actions;
+ }
+}]]>
+</programlisting>
+ </section>
+
+</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Persistence.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Persistence.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Persistence.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,615 +1,407 @@
-<chapter id="persistence">
- <title>Seam and Object/Relational Mapping</title>
-
- <para>
- Seam provides extensive support for the two most popular persistence
- architectures for Java: Hibernate3, and the Java Persistence API
- introduced with EJB 3.0. Seam's unique state-management architecture
- allows the most sophisticated ORM integration of any web application
- framework.
- </para>
-
- <section>
- <title>Introduction</title>
-
- <para>
- Seam grew out of the frustration of the Hibernate team with the
- statelessness typical of the previous generation of Java application
- architectures. The state management architecture of Seam was originally
- designed to solve problems relating to persistence — in particular
- problems associated with <emphasis>optimistic transaction processing</emphasis>.
- Scalable online applications always use optimistic transactions. An atomic
- (database/JTA) level transaction should not span a user interaction unless
- the application is designed to support only a very small number of concurrent
- clients. But almost all interesting work involves first displaying data
- to a user, and then, slightly later, updating the same data. So Hibernate was
- designed to support the idea of a persistence context which spanned an
- optimistic transaction.
- </para>
-
- <para>
- Unfortunately, the so-called "stateless" architectures that preceded Seam and
- EJB 3.0 had no construct for representing an optimistic transaction. So, instead,
- these architectures provided persistence contexts scoped to the atomic
- transaction. Of course, this resulted in many problems for users, and is the
- cause of the number one user complaint about Hibernate: the dreaded
- <literal>LazyInitializationException</literal>. What we need is a construct
- for representing an optimistic transaction in the application tier.
- </para>
-
- <para>
- EJB 3.0 recognizes this problem, and introduces the idea of a stateful
- component (a stateful session bean) with an <emphasis>extended persistence
- context</emphasis> scoped to the lifetime of the component. This is a
- partial solution to the problem (and is a useful construct in and of
- itself) however there are two problems:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- The lifecycle of the stateful session bean must be managed manually
- via code in the web tier (it turns out that this is a subtle problem
- and much more difficult in practice than it sounds).
- </para>
- </listitem>
- <listitem>
- <para>
- Propagation of the persistence context between stateful components
- in the same optimistic transaction is possible, but tricky.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Seam solves the first problem by providing conversations, and stateful
- session bean components scoped to the conversation. (Most conversations
- actually represent optimistic transactions in the data layer.) This is
- sufficient for many simple applications (such as the Seam booking
- demo) where persistence context propagation is not needed. For more
- complex applications, with many loosly-interacting components in each
- conversation, propagation of the persistence context across components
- becomes an important issue. So Seam extends the persistence context
- management model of EJB 3.0, to provide conversation-scoped extended
- persistence contexts.
- </para>
-
- </section>
-
- <section id="persistence.seam-managed-transactions">
- <title>Seam managed transactions</title>
- <para>
- EJB session beans feature declarative transaction management. The EJB container is able
- to start a transaction transparently when the bean is invoked, and end it when the
- invocation ends. If we write a session bean method that acts as a JSF action listener,
- we can do all the work associated with that action in one transaction, and be sure that
- it is committed or rolled back when we finish processing the action. This is a great feature,
- and all that is needed by some Seam applications.
- </para>
+<?xml version='1.0' encoding='UTF-8'?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- <para>
- However, there is a problem with this approach. A Seam application may not perform all data
- access for a request from a single method call to a session bean.
- </para>
+<chapter id="persistence" >
+ <title>Seam and Object/Relational Mapping</title>
+ <para>
+ Seam provides extensive support for the two most popular persistence architectures for Java: Hibernate, and the Java Persistence API introduced with Enterprise JavaBeans 3.0 (EJB3). Seam's unique state-management architecture allows the most sophisticated ORM integration of any web application framework.
+ </para>
+ <section>
+ <title>Introduction</title>
+ <para>
+ Seam was created because of frustration with the statelessness typical of the previous generation of Java application architectures. Seam's state management architecture was originally designed to solve problems relating to persistence, particularly problems associated with <emphasis>optimistic transaction processing</emphasis>. Scalable online applications always use optimistic transactions. An atomic (database/JTA) level transaction should not span a user interaction unless the application is designed to support only a very small number of concurrent clients. But almost all work involves first displaying data to a user, and then updating that data. Hibernate was designed to support a persistence context that spanned an optimistic transaction.
+ </para>
+ <para>
+ Unfortunately, the "stateless" architectures that preceded Seam and EJB3 had no construct to represent an optimistic transaction. Instead, these architectures provided persistence contexts scoped to the atomic transaction. This resulted in many problems for users, and causes the number one user complaint: Hibernate's <exceptionname>LazyInitializationException</exceptionname>. A construct was required to represent an optimistic transaction in the application tier.
+ </para>
+ <para>
+ EJB3 recognizes this problem, and introduces the idea of a stateful component (a stateful session bean) with an <emphasis>extended persistence context</emphasis> scoped to the lifetime of the component. This is a partial solution to the problem (and is a useful construct in and of itself), but there are still two issues with this approach:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The lifecycle of the stateful session bean must be managed manually with code in the web tier.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Propagation of the persistence context between stateful components in the same optimistic transaction is possible, but very complex.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Seam solves the first problem by providing conversations, and scoping stateful session bean components to the conversation. (Most conversations actually represent optimistic transactions in the data layer.) This is sufficient for many simple applications where persistence context propagation is not required, such as the Seam booking example application. For more complex applications, with many loosely-interacting components in each conversation, propagation of the persistence context across components becomes an important issue. Therefore, Seam extends the persistence context management model of EJB3, to provide conversation-scoped extended persistence contexts.
+ </para>
+ </section>
+
+ <section id="persistence.seam-managed-transactions">
+ <title>Seam managed transactions</title>
+ <para>
+ EJB session beans feature declarative transaction management. The EJB container can start a transaction transparently when the bean is invoked, and end it when the invocation ends. If we write a session bean method that acts as a JSF action listener, all work associated with that action can be performed as one transaction, and committed or rolled back when the action is completely processed. This is a useful feature, and for some Seam applications, this is all that is required.
+ </para>
+ <para>
+ However, there is a problem with this approach: in a request from a single method call to a session bean, a Seam application may not perform all data access.
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ when the request requires processing by several loosely-coupled components, with each component being called independently from the web layer. It is common to see multiple calls per request from the web layer to EJB components in Seam.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ when view rendering requires lazily-fetched associations.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The more transactions that exist per request, the more likely we are to encounter atomicity and isolation problems while our application processes many concurrent requests. All write operations should occur in the same transaction.
+ </para>
+ <para>
+ To work around this problem, Hibernate users developed the <emphasis>open session in view</emphasis> pattern. This is also important because some frameworks (Spring, for example) use transaction-scoped persistence contexts, which caused <exceptionname>LazyInitializationException</exceptionname>s when unfetched associations were accessed.
+ </para>
+ <para>
+ <emphasis>Open session in view</emphasis> is usually implemented as a single transaction that spans the entire request. The most serious problem with this implementation is that we cannot be certain that a transaction is successful until we commit it — but when the transaction commits, the view is fully rendered, and the rendered response may already be synchronized the client, so there is no way to notify the user that their transaction did not succeed.
+ </para>
+ <para>
+ Seam solves the problems with transaction isolation and association fetching, while working around the major flaw in <emphasis>open session in view</emphasis>, with two changes:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Seam uses an extended persistence context that is scoped to the conversation instead of the transaction.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Seam uses two transactions per request. The first spans from the beginning of the restore view phase until the end of the invoke application phase; the second spans the length of the render response phase. (In some applications, the first phase will begin later, at the beginning of the apply request values phase.)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The next section takes you through the setup of a conversation-scoped persistence context. Before this, we will enable Seam transaction management. You can use conversation-scoped persistence contexts without Seam transaction management, and Seam transaction management is useful even without Seam-managed persistence contexts, but they work most effectively together.
+ </para>
+ <section>
+ <title>Disabling Seam-managed transactions</title>
+ <para>
+ Seam transaction management is enabled by default for all JSF requests, but can be disabled in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<core:init transaction-management-enabled="false"/>
- <itemizedlist>
- <listitem>
- <para>
- The request might require processing by several loosely-coupled components, each
- of which is called independently from the web layer. It is common to see several
- or even many calls per request from the web layer to EJB components in Seam.
- </para>
- </listitem>
- <listitem>
- <para>
- Rendering of the view might require lazy fetching of associations.
- </para>
- </listitem>
- </itemizedlist>
+<transaction:no-transaction />]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Configuring a Seam transaction manager</title>
+ <para>
+ Seam provides a transaction management abstraction for beginning, committing, rolling back, and synchronizing with transactions. By default, Seam uses a JTA transaction component to integrate with container-managed and programmatic EJB transactions. If you work in a Java EE 5 environment, install the EJB synchronization component in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<transaction:ejb-transaction />]]>
+</programlisting>
+ <para>
+ However, if you work in a non-EE 5 container, Seam attempts to auto-detect the correct transaction synchronization mechanism. If Seam is unable to detect the correct mechanism, you may need to configure one of the following:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ configure JPA RESOURCE_LOCAL managed transactions with the <literal>javax.persistence.EntityTransaction</literal> interface. <literal>EntityTransaction</literal> starts the transaction at the beginning of the apply request values phase.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ configure Hibernate managed transactions with the <literal>org.hibernate.Transaction</literal> interface. <literal>HibernateTransaction</literal> starts the transaction at the beginning of the apply request values phase.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ configure Spring managed transactions with the <literal>org.springframework.transaction.PlatformTransactionManager</literal> interface. The Spring <literal>PlatformTransactionManagement</literal> manager may begin the transaction at the beginning of the apply request values phase if the <literal>userConversationContext</literal> attribute is set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Explicitly disable Seam managed transactions
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ To configure JPA RESOURCE_LOCAL transaction management, add the following to your <filename>components.xml</filename>, where <literal>#{em}</literal> is the name of the <literal>persistence:managed-persistence-context</literal> component. If your managed persistence context is named <literal>entityManager</literal>, you may leave out the <literal>entity-manager</literal> attribute. (For further information, see <xref linkend="persistence.seam-managed-persistence-contexts" />.)
+ </para>
+
+<programlisting role="XML"><![CDATA[<transaction:entity-transaction entity-manager="#{em}"/>]]>
+</programlisting>
+ <para>
+ To configure Hibernate managed transactions, declare the following in your <filename>components.xml</filename>, where <literal>#{hibernateSession}</literal> is the name of the project's <literal>persistence:managed-hibernate-session</literal> component. If your managed hibernate session is named <literal>session</literal>, you can opt to leave out the <literal>session</literal> attribute. (For further information, see <xref linkend="persistence.seam-managed-persistence-contexts"/>.)
+ </para>
+
+<programlisting role="XML"><![CDATA[<transaction:hibernate-transaction session="#{hibernateSession}"/>]]>
+</programlisting>
+ <para>
+ To explicitly disable Seam managed transactions, declare the following in your <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<transaction:no-transaction />]]>
+</programlisting>
+ <para>
+ For information about configuring Spring-managed transactions see <xref linkend="spring-transactions" />.
+ </para>
+ </section>
+
+ <section>
+ <title>Transaction synchronization</title>
+ <para>
+ Transaction synchronization provides callbacks for transaction-related events such as <literal>beforeCompletion()</literal> and <literal>afterCompletion()</literal>. By default, Seam uses its own transaction synchronization component, which requires explicit use of the Seam transaction component when committing transactions so that synchronization callbacks are correctly executed. If you work in a Java EE 5 environment, declare <literal><![CDATA[<transaction:ejb-transaction/>]]></literal> in <filename>components.xml</filename> to ensure that Seam synchronization callbacks are called correctly if the container commits a transaction outside Seam.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="persistence.seam-managed-persistence-contexts">
+ <title>Seam-managed persistence contexts</title>
+ <para>
+ If you use Seam outside a Java EE 5 environment, you cannot rely upon the container to manage the persistence context lifestyle. Even within EE 5 environments, propagating the persistence context between loosely-coupled components in a complex application can be difficult and error-prone.
+ </para>
+ <para>
+ In this case, you will need to use a <emphasis>managed persistence context</emphasis> (for JPA) or a <emphasis>managed session</emphasis> (for Hibernate) in your components. A Seam-managed persistence context is just a built-in Seam component that manages an instance of <literal>EntityManager</literal> or <literal>Session</literal> in the conversation context. You can inject it with <literal>@In</literal>.
+ </para>
+ <para>
+ Seam-managed persistence contexts are extremely efficient in a clustered environment. Seam can perform optimizations for container-managed persistence contexts that the EJB3 specification does not allow. Seam supports transparent failover of extended persistence contexts, without replicating any persistence context state between nodes. (We hope to add this support to the next revision of the EJB specification.)
+ </para>
+ <section>
+ <title>Using a Seam-managed persistence context with JPA</title>
+ <para>
+ Configuring a managed persistence context is easy. In <filename>components.xml</filename>, write:
+ </para>
+
+<programlisting role="XML"><![CDATA[<persistence: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 <literal>bookingDatabase</literal>, which manages the lifecycle of <literal>EntityManager</literal> instances for the persistence unit (<literal>EntityManagerFactory</literal> instance) with JNDI name <literal>java:/EntityManagerFactories/bookingData</literal>.
+ </para>
+ <para>
+ You must bind the <literal>EntityManagerFactory</literal> into JNDI. In JBoss, you can do this by adding the following property setting to <filename>persistence.xml</filename>.
+ </para>
+
+<programlisting role="XML"><![CDATA[<property name="jboss.entity.manager.factory.jndi.name"
+ value="java:/EntityManagerFactories/bookingData"/>]]>
+</programlisting>
+ <para>
+ Now we can inject our <literal>EntityManager</literal> with:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In EntityManager bookingDatabase;]]>
+</programlisting>
+ <para>
+ If you use EJB3, and mark your class or method <literal>@TransactionAttribute(REQUIRES_NEW)</literal>, then the transaction and persistence context should not propagate to method calls on this object. However, since the Seam-managed persistence context propagates to any component within the conversation, it propagates to methods marked <literal>REQUIRES_NEW</literal>. Therefore, if you mark a method <literal>REQUIRES_NEW</literal>, you should access the entity manager with <literal>@PersistenceContext</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Using a Seam-managed Hibernate session</title>
+ <para>
+ Seam-managed Hibernate sessions work in a similar fashion. In <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<persistence:hibernate-session-factory name="hibernateSessionFactory"/>
- <para>
- The more transactions per request, the more likely we are to encounter atomicity
- and isolation problems when our application is processing many concurrent requests.
- Certainly, all write operations should occur in the same transaction!
- </para>
-
- <para>
- Hibernate users developed the <emphasis>"open session in view"</emphasis> pattern to work
- around this problem. In the Hibernate community, "open session in view" was historically
- even more important because frameworks like Spring use transaction-scoped persistence contexts.
- So rendering the view would cause <literal>LazyInitializationException</literal>s when
- unfetched associations were accessed.
- </para>
-
- <para>
- This pattern is usually implemented as a single transaction which spans the entire request.
- There are several problems with this implementation, the most serious being that we
- can never be sure that a transaction is successful until we commit it — but by the
- time the "open session in view" transaction is committed, the view is fully rendered, and
- the rendered response may already have been flushed to the client. How can we notify the
- user that their transaction was unsuccessful?
- </para>
-
- <para>
- Seam solves both the transaction isolation problem and the association fetching problem,
- while working around the problems with "open session in view". The solution comes in two
- parts:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- use an extended persistence context that is scoped to the conversation,
- instead of to the transaction
- </para>
- </listitem>
- <listitem>
- <para>
- use two transactions per request; the first spans the beginning of the restore view
- phase (some transaction managers begin the transaction later at the beginning of the
- apply request vaues phase) until the end of the invoke application phase; the second spans the
- render response phase
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- In the next section, we'll tell you how to set up a conversation-scope persistence
- context. But first we need to tell you how to enable Seam transaction management.
- Note that you can use conversation-scoped persistence contexts without Seam
- transaction management, and there are good reasons to use Seam transaction management
- even when you're not using Seam-managed persistence contexts. However, the two
- facilities were designed to work together, and work best when used together.
- </para>
-
- <para>
- Seam transaction management is useful even if you're using EJB 3.0
- container-managed persistence contexts. But it is especially useful
- if you use Seam outside a Java EE 5 environment, or in any other
- case where you would use a Seam-managed persistence context.
- </para>
-
- <section>
- <title>Disabling Seam-managed transactions</title>
-
- <para>
- Seam transaction management is enabled by default for all JSF requests.
- If you want to <emphasis>disable</emphasis> this feature, you can do it
- in <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<core:init transaction-management-enabled="false"/>
-
-<transaction:no-transaction />]]></programlisting>
-
- </section>
-
- <section>
- <title>Configuring a Seam transaction manager</title>
-
- <para>
- Seam provides a transaction management abstraction for beginning, committing, rolling back, and
- synchronizing with a transaction. By default Seam uses a JTA transaction component that integrates with
- Container Managed and programmatic EJB transactions. If you are working in a Java EE 5 environment, you
- should install the EJB synchronization component in <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<transaction:ejb-transaction />]]></programlisting>
-
- <para>
- However, if you are working in a non EE 5 container, Seam will try auto detect the transaction
- synchronization mechanism to use. However, if Seam is unable to detect the correct transaction
- synchronization to use, you may find you need configure one of the following:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- JPA RESOURCE_LOCAL transactions with the
- <literal>javax.persistence.EntityTransaction</literal>
- interface. <literal>EntityTransaction</literal> begins the transaction at the beginning
- of the apply request values phase.
- </para>
- </listitem>
- <listitem>
- <para>
- Hibernate managed transactions with the
- <literal>org.hibernate.Transaction</literal>
- interface. <literal>HibernateTransaction</literal> begins the transaction at the beginning
- of the apply request values phase.
- </para>
- </listitem>
- <listitem>
- <para>
- Spring managed transactions with the
- <literal>org.springframework.transaction.PlatformTransactionManager</literal>
- interface. The Spring <literal>PlatformTransactionManagement</literal> manager may begin the
- transaction at the beginning of the apply request values phase if the
- <literal>userConversationContext</literal> attribute is set.
- </para>
- </listitem>
- <listitem>
- <para>
- Explicitly disable Seam managed transactions
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Configure JPA RESOURCE_LOCAL transaction management by adding the following to your components.xml where
- <literal>#{em}</literal>
- is the name of the
- <literal>persistence:managed-persistence-context</literal>
- component. If your managed persistence context is named <literal>entityManager</literal>, you can
- opt to leave out the <literal>entity-manager</literal> attribute. (see
- <link linkend="persistence.seam-managed-persistence-contexts">Seam-managed persistence contexts</link>
- )
- </para>
- <programlisting role="XML"><![CDATA[<transaction:entity-transaction entity-manager="#{em}"/>]]></programlisting>
- <para>
- To configure Hibernate managed transactions declare the following in your components.xml where
- <literal>#{hibernateSession}</literal>
- is the name of the project's
- <literal>persistence:managed-hibernate-session</literal>
- component. If your managed hibernate session is named <literal>session</literal>, you can
- opt to leave out the <literal>session</literal> attribute. (see
- <link linkend="persistence.seam-managed-persistence-contexts">Seam-managed persistence contexts</link>
- )
- </para>
- <programlisting role="XML"><![CDATA[<transaction:hibernate-transaction session="#{hibernateSession}"/>]]></programlisting>
- <para>
- To explicitly disable Seam managed transactions declare the following in your components.xml:
- </para>
- <programlisting role="XML"><![CDATA[<transaction:no-transaction />]]></programlisting>
- <para>
- For configuring Spring managed transactions see
- <link linkend="spring-transactions">using Spring PlatformTransactionManagement</link>
- .
- </para>
- </section>
- <section>
- <title>Transaction synchronization</title>
-
- <para>
- Transaction synchronization provides callbacks for transaction related events
- such as <literal>beforeCompletion()</literal> and <literal>afterCompletion()</literal>.
- By default, Seam uses it's own transaction synchronization component which requires explicit use of the
- Seam transaction component when committing a transaction to ensure synchronization callbacks are
- correctly executed. If in a Java EE 5 environment the
- <literal><transaction:ejb-transaction/></literal>
- component should be be declared in <literal>components.xml</literal> to ensure that Seam synchronization callbacks are
- correctly called if the container commits a transaction outside of Seam's knowledge.
- </para>
- </section>
- </section>
-
- <section id="persistence.seam-managed-persistence-contexts">
- <title>Seam-managed persistence contexts</title>
-
- <para>
- If you're using Seam outside of a Java EE 5 environment, you can't rely upon the
- container to manage the persistence context lifecycle for you. Even if you are
- in an EE 5 environment, you might have a complex application with many loosly
- coupled components that collaborate together in the scope of a single conversation,
- and in this case you might find that propagation of the persistence context between
- component is tricky and error-prone.
- </para>
-
- <para>
- In either case, you'll need to use a <emphasis>managed persistence context</emphasis>
- (for JPA) or a <emphasis>managed session</emphasis> (for Hibernate) in your components.
- A Seam-managed persistence context is just a built-in Seam component that manages an
- instance of <literal>EntityManager</literal> or <literal>Session</literal> in the
- conversation context. You can inject it with <literal>@In</literal>.
- </para>
-
- <para>
- Seam-managed persistence contexts are extremely efficient in a clustered environment.
- Seam is able to perform an optimization that EJB 3.0 specification does not allow
- containers to use for container-managed extended persistence contexts. Seam supports
- transparent failover of extended persisence contexts, without the need to replicate
- any persistence context state between nodes. (We hope to fix this oversight in the
- next revision of the EJB spec.)
- </para>
-
- <section>
- <title>Using a Seam-managed persistence context with JPA</title>
-
- <para>
- Configuring a managed persistence context is easy. In <literal>components.xml</literal>,
- we can write:
- </para>
-
- <programlisting role="XML"><![CDATA[<persistence: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
- <literal>bookingDatabase</literal> that manages the lifecycle of <literal>EntityManager</literal>
- instances for the persistence unit (<literal>EntityManagerFactory</literal> instance)
- with JNDI name <literal>java:/EntityManagerFactories/bookingData</literal>.
- </para>
-
- <para>
- Of course, you need to make sure that you have bound the <literal>EntityManagerFactory</literal>
- into JNDI. In JBoss, you can do this by adding the following property setting to
- <literal>persistence.xml</literal>.
- </para>
-
- <programlisting role="XML"><![CDATA[<property name="jboss.entity.manager.factory.jndi.name"
- value="java:/EntityManagerFactories/bookingData"/>]]></programlisting>
-
- <para>
- Now we can have our <literal>EntityManager</literal> injected using:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@In EntityManager bookingDatabase;]]></programlisting>
-
- <para>
- If you are using EJB3 and mark your class or method
- <literal>@TransactionAttribute(REQUIRES_NEW)</literal> then the
- transaction and persistence context shouldn't be propagated to method
- calls on this object. However as the Seam-managed persistence
- context is propagated to any component within the conversation, it
- will be propagated to methods marked <literal>REQUIRES_NEW</literal>.
- Therefore, if you mark a method <literal>REQUIRES_NEW</literal> then
- you should access the entity manager using @PersistenceContext.
- </para>
-
- </section>
-
- <section>
- <title>Using a Seam-managed Hibernate session</title>
-
- <para>
- Seam-managed Hibernate sessions are similar. In <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<persistence:hibernate-session-factory name="hibernateSessionFactory"/>
-
<persistence: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
- specified in <literal>hibernate.cfg.xml</literal>.
- </para>
-
- <programlisting role="XML"><![CDATA[<session-factory name="java:/bookingSessionFactory">
- <property name="transaction.flush_before_completion">true</property>
- <property name="connection.release_mode">after_statement</property>
- <property name="transaction.manager_lookup_class">org.hibernate.transaction.JBossTransactionManagerLookup</property>
- <property name="transaction.factory_class">org.hibernate.transaction.JTATransactionFactory</property>
- <property name="connection.datasource">java:/bookingDatasource</property>
- ...
-</session-factory>]]></programlisting>
-
- <para>
- Note that Seam does not flush the session, so you should always enable
- <literal>hibernate.transaction.flush_before_completion</literal> to
- ensure that the session is automatically flushed before the JTA transaction
- commits.
- </para>
-
- <para>
- We can now have a managed Hibernate <literal>Session</literal> injected into our
- JavaBean components using the following code:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@In Session bookingDatabase;]]></programlisting>
-
- </section>
-
- <section>
- <title>Seam-managed persistence contexts and atomic conversations</title>
- <para>
- Persistence contexts scoped to the conversation allows you to program optimistic
- transactions that span multiple requests to the server without the need to use the
- <literal>merge()</literal> operation , without the need to re-load
- data at the beginning of each request, and without the need to wrestle with the
- <literal>LazyInitializationException</literal> or
- <literal>NonUniqueObjectException</literal>.
- </para>
-
- <para>
- As with any optimistic transaction management, transaction isolation and consistency
- can be achieved via use of optimistic locking. Fortunately, both Hibernate and EJB
- 3.0 make it very easy to use optimistic locking, by providing the
- <literal>@Version</literal> annotation.
- </para>
-
- <para>
- By default, the persistence context is flushed (synchronized with the database)
- at the end of each transaction. This is sometimes the desired behavior. But very
- often, we would prefer that all changes are held in memory and only written to
- the database when the conversation ends successfully. This allows for truly
- atomic conversations. As the result of a truly stupid and shortsighted decision
- by certain non-JBoss, non-Sun and non-Sybase members of the EJB 3.0 expert group,
- there is currently no simple, usable and portable way to implement atomic
- conversations using EJB 3.0 persistence. However, Hibernate provides this feature
- as a vendor extension to the <literal>FlushModeType</literal>s defined by the
- specification, and it is our expectation that other vendors will soon provide
- a similar extension.
- </para>
-
- <para>
- Seam lets you specify <literal>FlushModeType.MANUAL</literal> when beginning a
- conversation. Currently, this works only when Hibernate is the underlying
- persistence provider, but we plan to support other equivalent vendor extensions.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@In EntityManager em; //a Seam-managed persistence context
-
+ auto-create="true"
+ session-factory-jndi-name="java:/bookingSessionFactory"/>]]>
+</programlisting>
+ <para>
+ Here, <literal>java:/bookingSessionFactory</literal> is the name of the session factory specified in <filename>hibernate.cfg.xml</filename>.
+ </para>
+
+<programlisting role="XML"><![CDATA[<session-factory name="java:/bookingSessionFactory">
+ <property name="transaction.flush_before_completion">true</property>
+ <property name="connection.release_mode">after_statement</property>
+ <property name="transaction.manager_lookup_class">
+ org.hibernate.transaction.JBossTransactionManagerLookup
+ </property>
+ <property name="transaction.factory_class">
+ org.hibernate.transaction.JTATransactionFactory
+ </property>
+ <property name="connection.datasource">
+ java:/bookingDatasource
+ </property>
+ ...
+</session-factory>]]>
+</programlisting>
+ <note>
+ <para>
+ Seam does not synchronize the session with the database, so always enable <literal>hibernate.transaction.flush_before_completion</literal> to ensure that the session is automatically synchronized before the JTA transaction commits.
+ </para>
+ </note>
+ <para>
+ We can now inject a managed Hibernate <literal>Session</literal> into our JavaBean components with the following code:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In Session bookingDatabase;]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Seam-managed persistence contexts and atomic conversations</title>
+ <para>
+ Conversation-scoped persistence contexts let you program optimistic transactions spanning multiple server requests, without using <literal>merge()</literal>, reloading data at the beginning of each request, or wrestling with exceptions (<exceptionname>LazyInitializationException</exceptionname> or <exceptionname>NonUniqueObjectException</exceptionname>).
+ </para>
+ <para>
+ You can achieve transaction isolation and consistency by using optimistic locking. Both Hibernate and EJB3 make optimistic locking easy with the <literal>@Version</literal> annotation.
+ </para>
+ <para>
+ By default, the persistence context is synchronized with the database (flushed) at the end of each transaction. Sometimes this is desirable, but often we prefer all changes to be held in memory, and only written to the database when the conversation ends successfully. This allows for truly atomic conversations with EJB3 persistence. However, Hibernate provides this feature as a vendor extension to the <literal>FlushModeType</literal>s defined by the specification. We expect other vendors will soon provide a similar extension.
+ </para>
+ <para>
+ Seam lets you specify <literal>FlushModeType.MANUAL</literal> when beginning a conversation. Currently, this works only when Hibernate is the underlying persistence provider, but we plan to support other equivalent vendor extensions.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In EntityManager em; //a Seam-managed persistence context
@Begin(flushMode=MANUAL)
+
public void beginClaimWizard() {
- claim = em.find(Claim.class, claimId);
-}]]></programlisting>
-
- <para>
- Now, the <literal>claim</literal> object remains managed by the persistence context
- for the rest ot the conversation. We can make changes to the claim:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public void addPartyToClaim() {
- Party party = ....;
- claim.addParty(party);
-}]]></programlisting>
+ claim = em.find(Claim.class, claimId);
+}]]>
+</programlisting>
+ <para>
+ Now, the <literal>claim</literal> object remains managed by the persistence context for the entire conversation. We can make changes to the claim:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public void addPartyToClaim() {
+ Party party = ....;
+ claim.addParty(party);
+}]]>
+</programlisting>
+ <para>
+ But these changes will not be flushed to the database until we explicitly force synchronization to occur:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@End public void commitClaim() {
+ em.flush();
+}]]>
+</programlisting>
+ <para>
+ You can also set the <literal>flushMode</literal> to <literal>MANUAL</literal> from pages.xml, for example in a navigation rule:
+ </para>
+
+<programlisting role="XML"><![CDATA[<begin-conversation flush-mode="MANUAL" />]]>
+</programlisting>
+ <para>
+ You can set any Seam-managed persistence context to use manual flush mode:
+ </para>
+
+<programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:core="http://jboss.com/products/seam/core">
+ <core:manager conversation-timeout="120000"
+ default-flush-mode="manual" />
+</components>]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Using the JPA "delegate"</title>
+ <para>
+ The <literal>EntityManager</literal> interface lets you access a vendor-specific API with the <literal>getDelegate()</literal> method. We recommend using Hibernate as your vendor, and <literal>org.hibernate.Session</literal> as your delegate interface, but if you require a different JPA provider, see <xref linkend="alt-jpa-providers" /> for further information.
+ </para>
+ <para>
+ Regardless of your vendor, there are several approaches to using the delegate in your Seam components. One approach is:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In EntityManager entityManager;
+ at Create public void init() {
+ ((Session)entityManager.getDelegate() ).enableFilter("currentVersions");
+}]]>
+</programlisting>
+ <para>
+ If you, like most Java users, would rather avoid using typecasts, you can also access the delegate by adding the following line to <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<factory name="session" scope="STATELESS" auto-create="true"
+ value="#{entityManager.delegate}"/>]]>
+</programlisting>
+ <para>
+ The session can now be injected directly:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In Session session;
- <para>
- But these changes will not be flushed to the database until we explicitly force
- the flush to occur:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@End
-public void commitClaim() {
- em.flush();
-}]]></programlisting>
-
- <para>
- Of course, you could set the <literal>flushMode</literal> to <literal>MANUAL</literal>
- from pages.xml, for example in a navigation rule:
- </para>
-
- <programlisting role="XML"><![CDATA[<begin-conversation flush-mode="MANUAL" />]]></programlisting>
-
- <para>
- You can set any Seam Managed Persistence Context to use manual flush
- mode:
- </para>
-
- <programlisting><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:core="http://jboss.com/products/seam/core">
- <core:manager conversation-timeout="120000" default-flush-mode="manual" />
-</components>]]></programlisting>
-
- </section>
-
- </section>
-
- <section>
- <title>Using the JPA "delegate"</title>
-
- <para>
- The <literal>EntityManager</literal> interface lets you access a vendor-specific
- API via the <literal>getDelegate()</literal> method. Naturally, the most interesting
- vendor is Hibernate, and the most powerful delegate interface is
- <literal>org.hibernate.Session</literal>. You'd be nuts to use anything else. Trust
- me, I'm not biased at all. If you must use a different JPA provider see
- <link linkend="alt-jpa-providers">Using Alternate JPA Providers</link>.
- </para>
-
- <para>
- But regardless of whether you're using Hibernate (genius!) or something else
- (masochist, or just not very bright), you'll almost certainly want to use the
- delegate in your Seam components from time to time. One approach would be the
- following:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@In EntityManager entityManager;
-
@Create
public void init() {
- ( (Session) entityManager.getDelegate() ).enableFilter("currentVersions");
-}]]></programlisting>
-
- <para>
- But typecasts are unquestionably the ugliest syntax in the Java language, so most
- people avoid them whenever possible. Here's a different way to get at the
- delegate. First, add the following line to <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<factory name="session"
- scope="STATELESS"
- auto-create="true"
- value="#{entityManager.delegate}"/>]]></programlisting>
-
- <para>
- Now we can inject the session directly:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@In Session session;
-
- at Create
-public void init() {
- session.enableFilter("currentVersions");
-}]]></programlisting>
-
- </section>
-
- <section>
- <title>Using EL in EJB-QL/HQL</title>
- <para>
- Seam proxies the <literal>EntityManager</literal> or <literal>Session</literal>
- object whenever you use a Seam-managed persistence context or inject a container
- managed persistence context using <literal>@PersistenceContext</literal>. This
- lets you use EL expressions in your query strings, safely and efficiently. For
- example, this:
- </para>
-
- <programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=#{user.username}")
- .getSingleResult();]]></programlisting>
-
- <para>is equivalent to:</para>
-
- <programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=:username")
- .setParameter("username", user.getUsername())
- .getSingleResult();]]></programlisting>
-
- <para>
- Of course, you should never, ever write it like this:
- </para>
-
- <programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=" + user.getUsername()) //BAD!
- .getSingleResult();]]></programlisting>
-
- <para>
- (It is inefficient and vulnerable to SQL injection attacks.)
- </para>
-
- </section>
-
- <section>
- <title>Using Hibernate filters</title>
-
- <para>
- The coolest, and most unique, feature of Hibernate is <emphasis>filters</emphasis>.
- Filters let you provide a restricted view of the data in the database. You can find
- out more about filters in the Hibernate documentation. But we thought we'd mention
- an easy way to incorporate filters into a Seam application, one that works especially
- well with the Seam Application Framework.
- </para>
-
- <para>
- Seam-managed persistence contexts may have a list of filters defined, which will be
- enabled whenever an <literal>EntityManager</literal> or Hibernate <literal>Session</literal>
- is first created. (Of course, they may only be used when Hibernate is the underlying
- persistence provider.)
- </para>
-
- <programlisting role="XML"><![CDATA[<persistence:filter name="regionFilter">
- <persistence:name>region</persistence:name>
- <persistence:parameters>
- <key>regionCode</key>
- <value>#{region.code}</value>
- </persistence:parameters>
+ session.enableFilter("currentVersions");
+}]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Using EL in EJB-QL/HQL</title>
+ <para>
+ Seam proxies the <literal>EntityManager</literal> or <literal>Session</literal> object whenever you use a Seam-managed persistence context or inject a container-managed persistence context with <literal>@PersistenceContext</literal>. This lets you safely and efficiently use EL expressions in your query strings. For example, this:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=#{user.username}")
+ .getSingleResult();]]>
+</programlisting>
+ <para>
+ is equivalent to:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username=:username")
+ .setParameter("username", user.getUsername())
+ .getSingleResult();]]>
+</programlisting>
+ <warning>
+ <para>
+ This should <emphasis>never</emphasis> be written as:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[User user = em.createQuery("from User where username="
+ + user.getUsername()).getSingleResult(); //BAD!]]>
+</programlisting>
+ <para>
+ This is inefficient, but more importantly, it is vulnerable to SQL injection attacks.
+ </para>
+ </warning>
+ </section>
+
+ <section>
+ <title>Using Hibernate filters</title>
+ <para>
+ Hibernate's most unique, useful feature is the <emphasis>filter</emphasis>. Filters provide a restricted view of the data in the database. You can find more information in the Hibernate documentation, but this section takes you through one easy, effective method of incorporating filters into Seam.
+ </para>
+ <para>
+ Seam-managed persistence contexts can have a list of filters defined, which will be enabled whenever an <literal>EntityManager</literal> or Hibernate <literal>Session</literal> is first created. (These can only be used when Hibernate is the underlying persistence provider.)
+ </para>
+
+<programlisting role="XML"><![CDATA[<persistence:filter name="regionFilter">
+ <persistence:name>region</persistence:name>
+ <persistence:parameters>
+ <key>regionCode</key>
+ <value>#{region.code}</value>
+ </persistence:parameters>
</persistence:filter>
<persistence:filter name="currentFilter">
- <persistence:name>current</persistence:name>
- <persistence:parameters>
- <key>date</key>
- <value>#{currentDate}</value>
- </persistence:parameters>
+ <persistence:name>current</persistence:name>
+ <persistence:parameters>
+ <key>date</key>
+ <value>#{currentDate}</value>
+ </persistence:parameters>
</persistence:filter>
<persistence:managed-persistence-context name="personDatabase"
- persistence-unit-jndi-name="java:/EntityManagerFactories/personDatabase">
- <persistence:filters>
- <value>#{regionFilter}</value>
- <value>#{currentFilter}</value>
- </persistence:filters>
-</persistence:managed-persistence-context>]]></programlisting>
-
- </section>
-
+ persistence-unit-jndi-name="java:/EntityManagerFactories/personDatabase">
+ <persistence:filters>
+ <value>#{regionFilter}</value>
+ <value>#{currentFilter}</value>
+ </persistence:filters>
+</persistence:managed-persistence-context>]]>
+</programlisting>
+ </section>
+
</chapter>
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Preface.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Preface.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Preface.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,282 +1,152 @@
-<?xml version='1.0'?>
+<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
+<preface id="Book-Preface" >
+ <title>Introduction to the JBoss Seam Framework</title>
+ <para>
+ The JBoss Seam Framework is an application framework for Enterprise Java. It is inspired by the following principles:
+ </para>
+ <variablelist>
+ <varlistentry>
+ <term><emphasis>One kind of "stuff"</emphasis></term>
+ <listitem>
+ <para>
+ The Seam Framework (hereafter 'Seam') defines a uniform component model for all of the business logic in your application. Components can hold application state, which can be associated with any one of several well-defined contexts, including the long-running, persistent <emphasis>business process context</emphasis> and the <emphasis>conversation context</emphasis>, which is preserved across multiple web requests in a user interaction.
+ </para>
+ <para>
+ Unlike plain Java EE or J2EE components, Seam components can access both state associated with web requests and state held in transactional resources simultaneously, without propagating web request state manually through method parameters. There is no distinction between presentation tier components and business logic components in Seam, so layering your applications is much more flexible. The Seam framework allows you to design architecture that suits your business model, rather than being constrained to a set layering scheme.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Integrate JSF with EJB 3.0</emphasis></term>
+ <listitem>
+ <para>
+ JavaServer Faces (JSF) is an excellent component model for the presentation tier, while Enterprise JavaBeans 3.0 (EJB3) is a new component model for server-side business and persistence logic. Java EE 5 provided no standard way to integrate these component models, relying instead upon extension points provided by JSF and EJB3 — Seam eliminates this glue code and unifies the two component models to enable improved performance.
+ </para>
+ <para>
+ EJB3 transformed the Enterprise JavaBean (EJB) from a coarse-grained "heavyweight" object into a fine-grained object. You can write a Seam application with EJBs alone, but virtually any Java class can be a Seam component, and Seam provides lightweight container functionality to match.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Integrated AJAX</emphasis></term>
+ <listitem>
+ <para>
+ JBoss RichFaces and ICEfaces are two of the top JSF-based AJAX solutions. Seam supports both, which lets you add AJAX capabilities to your user interface without needing to write any JavaScript code.
+ </para>
+ <para>
+ Alternatively, Seam provides a built-in JavaScript remoting layer that lets you call components asynchronously from client-side JavaScript without using an intermediate action layer. You can even subscribe to server-side JMS topics and receive messages via AJAX Push.
+ </para>
+ <para>
+ Seam's built-in concurrency and state management ensures that multiple concurrent fine-grained, asynchronous AJAX requests are handled safely and efficiently on the server side.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Business process as a first class construct</emphasis></term>
+ <listitem>
+ <para>
+ Seam provides the option of transparent business process management through jBPM, allowing you to easily implement complex workflows, collaboration, and task management. You can also define presentation tier pageflow with the same language used for business process definition (jPDL).
+ </para>
+ <para>
+ JSF provides a rich event model for the presentation tier. Seam enhances this by using the same event-handling mechanism to expose jBPM's business process-related events, providing a uniform event model for Seam's uniform component model.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Declarative state management</emphasis></term>
+ <listitem>
+ <para>
+ EJB3 introduced declarative persistence context management, while retaining concepts of declarative security and transaction management from earlier versions of EJB. These concepts help solve the problem of managing state associated with a particular <emphasis>context</emphasis> while ensuring that all necessary cleanup occurs when the context ends.
+ </para>
+ <para>
+ Seam applies the concept of declarative state management to <emphasis>application state</emphasis>. Traditionally, J2EE applications implement state management manually by getting and setting servlet session and request attributes. This causes many bugs and memory leaks when applications fail to clean up session attributes, or when multi-window applications fail to separate session data associated with different workflows. By managing application state, Seam can eliminate this class of bug.
+ </para>
+ <para>
+ Seam manages declarative application state by including two new contexts to the model defined by the servlet specifications. The <emphasis>conversation</emphasis> and <emphasis>business process</emphasis> contexts are more meaningful in terms of business logic, and solve many of the problems caused by older state management architecture.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Bijection</emphasis></term>
+ <listitem>
+ <para>
+ The notion of Inversion of Control (IoC) or <emphasis>dependency injection</emphasis> exists in many lightweight containers, including JSF and EJB3. Most of these containers emphasize the injection of stateless components. Where stateful component injection is supported, application state is not handled well because component scope cannot be flexibly defined, and wider-scoped components may not be injected into components with narrower scopes.
+ </para>
+ <para>
+ <emphasis>Bijection</emphasis> differs from IoC in that it is dynamic, contextual, and bidirectional. You can think of it as a mechanism for aliasing contextual variables (names in the various contexts bound to the current thread) to attributes of the component. Bijection lets the container assemble stateful components automatically, and lets components safely and easily manipulate context variable values by assigning them to component attributes.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Workspace management and multi-window browsing</emphasis></term>
+ <listitem>
+ <para>
+ Seam applications let the user freely switch between multiple browser tabs, each associated with a different, safely isolated conversation. Applications can even take advantage of <emphasis>workspace management</emphasis>, allowing the user to switch between conversations (workspaces) in a single browser tab.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Annotations over XML</emphasis></term>
+ <listitem>
+ <para>
+ Where JSF still depends heavily on verbose XML configuration files, EJB3 combines annotations with configuration "by exception". Seam includes a set of annotations for declarative state management and context demarcation, eliminating the need for JSF-managed bean declarations and reducing the amount of XML to that required in JSF navigation rules.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Easy integration testing</emphasis></term>
+ <listitem>
+ <para>
+ Seam components are unit-testable by nature, but for complex applications (above plain Java class), unit testing alone is insufficient. One of Seam's core features is the removal of all mess and difficulty traditionally associated with integration testing. It is easy to write JUnit or TestNG tests that reproduce whole user interactions and exercise all system components outside the view (the JSP or Facelets page). These tests can be run directly inside your IDE, where Seam will automatically deploy EJB components using Embedded JBoss.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Improving Specifications</emphasis></term>
+ <listitem>
+ <para>
+ Seam patches holes that exist within Java EE specifications (for example, limitations in the JSF lifecycle for GET requests), and Seam authors work with JCP expert groups to ensure that any fixes are included in future standard revisions.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><emphasis>Web applications can do more than serve HTML pages</emphasis></term>
+ <listitem>
+ <para>
+ We believe a complete web application framework should address persistence, concurrency, asynchronicity, state management, security, email, messaging, PDF and chart generation, workflow, wikitext rendering, webservices, caching and more.
+ </para>
+ <para>
+ Seam integrates the Java Persistence API and Hibernate 3 for persistence; the EJB Timer Service and Quartz for lightweight asychronicity; jBPM for workflow; JBoss Rules for business rules; <!-- Meldware Mail for email;--> Hibernate Search and Lucene for full text search; Java Message Service for messaging; and JBoss Cache for page fragment caching. Seam layers an innovative rule-based security framework over the Java Authentication and Authorization Service and JBoss Rules. It also includes JSF tag libraries for rendering PDF, outgoing email, charts and wikitext. Seam components can be called synchronously as a Web Service, asynchronously from client-side JavaScript or Google Web Toolkit, or directly from JSF.
+ </para>
+ </listitem>
+ </varlistentry>
+<!-- <varlistentry>
+ <term><emphasis>Get started now!</emphasis></term>
+ <listitem>
+ <para>
+ Seam works in any Java EE application server. Even if your environment does not support EJB3, you can use Seam's inbuilt transaction management with JPA or Hibernate3 for persistence, or deploy Embedded JBoss in Tomcat for full EJB3 support.
+ </para>
+ </listitem>
+ </varlistentry>-->
+ </variablelist>
+ <mediaobject>
+ <imageobject>
+ <imagedata fileref="images/architecture.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ Combining Seam, JSF and EJB3 is the simplest way to write a complex web application in Java.
+ </para>
+ <xi:include href="Common_Content/Conventions.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <!--FOR JDOCBOOK:-->
+ <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ </xi:include>
+ <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude">
+ <!--FOR JDOCBOOK:-->
+ <xi:fallback xmlns:xi="http://www.w3.org/2001/XInclude"/>
+ </xi:include>
+</preface>
-<preface id="Book-Preface">
- <title>Introduction to JBoss Seam</title>
-
- <para>
- Seam is an application framework for Enterprise Java. It is inspired by the following principles:
- </para>
-
- <variablelist>
-
- <varlistentry>
- <term><emphasis>One kind of "stuff"</emphasis></term>
- <listitem>
- <para>
- Seam defines a uniform component model for all business logic in your application.
- A Seam component may be stateful, with the state associated with any one of several
- well-defined contexts, including the long-running, persistent, <emphasis>business process
- context</emphasis> and the <emphasis>conversation context</emphasis>, which is
- preserved across multiple web requests in a user interaction.
- </para>
- <para>
- There is no distinction between presentation tier components and business logic
- components in Seam. You can layer your application according to whatever architecture
- you devise, rather than being forced to shoehorn your application logic into an
- unnatural layering scheme forced upon you by whatever combination of stovepipe
- frameworks you're using today.
- </para>
- <para>
- Unlike plain Java EE or J2EE components, Seam components may <emphasis>simultaneously</emphasis>
- access state associated with the web request and state held in transactional resources (without
- the need to propagate web request state manually via method parameters). You might object
- that the application layering imposed upon you by the old J2EE platform was a Good Thing.
- Well, nothing stops you creating an equivalent layered architecture using Seam — the difference
- is that <emphasis>you</emphasis> get to architect your own application and decide what the
- layers are and how they work together.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>Integrate JSF with EJB 3.0</emphasis></term>
- <listitem>
- <para>
- JSF and EJB 3.0 are two of the best new features of Java EE 5. EJB3 is a brand new
- component model for server side business and persistence logic. Meanwhile, JSF is a
- great component model for the presentation tier. Unfortunately, neither component
- model is able to solve all problems in computing by itself. Indeed, JSF and EJB3
- work best used together. But the Java EE 5 specification provides no standard way
- to integrate the two component models. Fortunately, the creators of both models
- foresaw this situation and provided standard extension points to allow extension
- and integration with other frameworks.
- </para>
- <para>
- Seam unifies the component models of JSF and EJB3, eliminating glue code, and letting
- the developer think about the business problem.
- </para>
- <para>
- It is possible to write Seam applications where "everything" is an EJB. This may come
- as a surprise if you're used to thinking of EJBs as coarse-grained, so-called
- "heavyweight" objects. However, version 3.0 has completely changed the nature of EJB
- from the point of view of the developer. An EJB is a fine-grained object — nothing
- more complex than an annotated JavaBean. Seam even encourages you to use session beans
- as JSF action listeners!
- </para>
- <para>
- On the other hand, if you prefer not to adopt EJB 3.0 at this time, you don't have to.
- Virtually any Java class may be a Seam component, and Seam provides all the functionality
- that you expect from a "lightweight" container, and more, for any component, EJB or
- otherwise.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>Integrated AJAX</emphasis></term>
- <listitem>
- <para>
- Seam supports the best open source JSF-based AJAX solution - JBoss
- RichFaces. These solutions let you add AJAX capability to your user
- interface without the need to write any JavaScript code.
- </para>
- <para>
- Alternatively, Seam provides a built-in JavaScript remoting layer that lets you call
- components asynchronously from client-side JavaScript without the need for an intermediate
- action layer. You can even subscribe to server-side JMS topics and receive messages via AJAX
- push.
- </para>
- <para>
- Neither of these approaches would work well, were it not for Seam's built-in concurrency
- and state management, which ensures that many concurrent fine-grained, asynchronous AJAX
- requests are handled safely and efficiently on the server side.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>Business process as a first class construct</emphasis></term>
- <listitem>
- <para>
- Optionally, Seam provides transparent business process management via jBPM. You won't
- believe how easy it is to implement complex workflows, collaboration and and task management
- using jBPM and Seam.
- </para>
- <para>
- Seam even allows you to define presentation tier pageflow using the same language (jPDL)
- that jBPM uses for business process definition.
- </para>
- <para>
- JSF provides an incredibly rich event model for the presentation tier. Seam enhances this
- model by exposing jBPM's business process related events via exactly the same event handling
- mechanism, providing a uniform event model for Seam's uniform component model.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>Declarative state management</emphasis></term>
- <listitem>
- <para>
- We're all used to the concept of declarative transaction management and declarative
- security from the early days of EJB. EJB 3.0 even introduces declarative persistence context
- management. These are three examples of a broader problem of managing state that is
- associated with a particular <emphasis>context</emphasis>, while ensuring that all needed
- cleanup occurs when the context ends. Seam takes the concept of declarative state
- management much further and applies it to <emphasis>application state</emphasis>.
- Traditionally, J2EE applications implement state management manually, by getting
- and setting servlet session and request attributes. This approach to state management is the
- source of many bugs and memory leaks when applications fail to clean up session attributes,
- or when session data associated with different workflows collides in a multi-window
- application. Seam has the potential to almost entirely eliminate this class of bugs.
- </para>
- <para>
- Declarative application state management is made possible by the richness of the
- <emphasis>context model</emphasis> defined by Seam. Seam extends the context model defined
- by the servlet spec — request, session, application — with two new
- contexts — conversation and business process — that are more meaningful from the
- point of view of the business logic.
- </para>
- <para>
- You'll be amazed at how many things become easier once you start using conversations.
- Have you ever suffered pain dealing with lazy association fetching in an ORM solution
- like Hibernate or JPA? Seam's conversation-scoped persistence contexts mean you'll
- rarely have to see a <literal>LazyInitializationException</literal>. Have you ever
- had problems with the refresh button? The back button? With duplicate form submission?
- With propagating messages across a post-then-redirect? Seam's conversation management
- solves these problems without you even needing to really think about them. They're all
- symptoms of the broken state management architecture that has been prevalent since the
- earliest days of the web.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>Bijection</emphasis></term>
- <listitem>
- <para>
- The notion of <emphasis>Inversion of Control</emphasis> or <emphasis>dependency injection</emphasis>
- exists in both JSF and EJB3, as well as in numerous so-called "lightweight containers". Most of
- these containers emphasize injection of components that implement <emphasis>stateless services</emphasis>.
- Even when injection of stateful components is supported (such as in JSF), it is virtually useless
- for handling application state because the scope of the stateful component cannot be defined with
- sufficient flexibility, and because components belonging to wider scopes may not be injected into
- components belonging to narrower scopes.
- </para>
- <para>
- <emphasis>Bijection</emphasis> differs from IoC in that it is <emphasis>dynamic</emphasis>,
- <emphasis>contextual</emphasis>, and <emphasis>bidirectional</emphasis>.
- You can think of it as a mechanism for aliasing contextual variables (names in the various contexts
- bound to the current thread) to attributes of the component. Bijection allows auto-assembly of stateful
- components by the container. It even allows a component to safely and easily manipulate the
- value of a context variable, just by assigning it to an attribute of the component.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>Workspace management and multi-window browsing</emphasis></term>
- <listitem>
- <para>
- Seam applications let the user freely switch between multiple browser tabs, each associated with a
- different, safely isolated, conversation. Applications may even take advantage of <emphasis>workspace
- management</emphasis>, allowing the user to switch between conversations (workspaces) in a single
- browser tab. Seam provides not only correct multi-window operation, but also multi-window-like
- operation in a single window!
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>Prefer annotations to XML</emphasis></term>
- <listitem>
- <para>
- Traditionally, the Java community has been in a state of deep confusion about precisely
- what kinds of meta-information counts as configuration. J2EE and popular "lightweight"
- containers have provided XML-based deployment descriptors both for things which are
- truly configurable between different deployments of the system, and for any other kinds
- or declaration which can not easily be expressed in Java. Java 5 annotations changed
- all this.
- </para>
- <para>
- EJB 3.0 embraces annotations and "configuration by exception" as the easiest way to provide
- information to the container in a declarative form. Unfortunately, JSF is still heavily
- dependent on verbose XML configuration files. Seam extends the annotations provided by
- EJB 3.0 with a set of annotations for declarative state management and declarative
- context demarcation. This lets you eliminate the noisy JSF managed bean declarations
- and reduce the required XML to just that information which truly belongs in XML
- (the JSF navigation rules).
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>Integration testing is easy</emphasis></term>
- <listitem>
- <para>
- Seam components, being plain Java classes, are by nature unit testable. But for complex applications,
- unit testing alone is insufficient. Integration testing has traditionally been a messy and
- difficult task for Java web applications. Therefore, Seam provides for testability of Seam
- applications as a core feature of the framework. You can easily write JUnit or TestNG tests
- that reproduce a whole interaction with a user, exercising all components of the system
- apart from the view (the JSP or Facelets page). You can run these tests directly inside your
- IDE, where Seam will automatically deploy EJB components using JBoss Embedded.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>The specs ain't perfect</emphasis></term>
- <listitem>
- <para>
- We think the latest incarnation of Java EE is great. But we know it's never going to be
- perfect. Where there are holes in the specifications (for example, limitations in the
- JSF lifecycle for GET requests), Seam fixes them. And the authors of Seam are working
- with the JCP expert groups to make sure those fixes make their way back into the next
- revision of the standards.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term><emphasis>There's more to a web application than serving HTML pages</emphasis></term>
- <listitem>
- <para>
- Today's web frameworks think too small. They let you get user input off a form and
- into your Java objects. And then they leave you hanging. A truly complete web application
- framework should address problems like persistence, concurrency, asynchronicity, state
- management, security, email, messaging, PDF and chart generation, workflow, wikitext
- rendering, webservices, caching and more. Once you scratch the surface of Seam, you'll
- be amazed at how many problems become simpler...
- </para>
- <para>
- Seam integrates JPA and Hibernate3 for persistence, the EJB Timer Service and Quartz
- for lightweight asychronicity, jBPM for workflow, JBoss Rules for business rules, Meldware
- Mail for email, Hibernate Search and Lucene for full text search, JMS for messaging and JBoss
- Cache for page fragment caching. Seam layers an innovative rule-based security framework over
- JAAS and JBoss Rules. There's even JSF tag libraries for rendering PDF, outgoing email, charts
- and wikitext. Seam components may be called synchronously as a Web Service, asynchronously
- from client-side JavaScript or Google Web Toolkit or, of course, directly from JSF.
- </para>
- </listitem>
- </varlistentry>
-
- </variablelist>
-
- <mediaobject>
- <imageobject>
- <imagedata fileref="images/architecture.png"/>
- </imageobject>
- </mediaobject>
-
- <para>
- It turns out that the combination of Seam, JSF and EJB3 is <emphasis>the</emphasis> simplest way
- to write a complex web application in Java. You won't believe how little code is required!
- </para>
-
- <xi:include href="Feedback.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-
- </preface>
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Remoting.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Remoting.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Remoting.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,117 +1,109 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<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>
-
- <section>
- <title>Configuration</title>
- <para> To use remoting, the Seam Resource servlet must first be configured in your <literal>web.xml</literal> file: </para>
-
- <programlisting role="XML"><![CDATA[<servlet>
- <servlet-name>Seam Resource Servlet</servlet-name>
- <servlet-class>org.jboss.seam.servlet.SeamResourceServlet</servlet-class>
+<chapter id="remoting" >
+ <title>Remoting</title>
+ <para>
+ Seam uses Asynchronous JavaScript and XML (AJAX) to remotely access components from a web page. The framework for this functionality requires very little development effort — you can make your components AJAX-accessible with simple annotations. This chapter describes the steps required to build an AJAX-enabled web page, and explains the Seam Remoting framework in further detail.
+ </para>
+ <section>
+ <title>Configuration</title>
+ <para>
+ To use remoting, you must first configure your Seam Resource Servlet in your <filename>web.xml</filename> file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<servlet>
+ <servlet-name>Seam Resource Servlet</servlet-name>
+ <servlet-class>
+ org.jboss.seam.servlet.SeamResourceServlet
+ </servlet-class>
</servlet>
<servlet-mapping>
<servlet-name>Seam Resource Servlet</servlet-name>
<url-pattern>/seam/resource/*</url-pattern>
-</servlet-mapping>]]></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>
-
- <programlisting role="XHTML"><![CDATA[<script type="text/javascript" src="seam/resource/remoting/resource/remote.js"></script>]]></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>
-
- <programlisting role="XHTML"><![CDATA[<script type="text/javascript"
- src="seam/resource/remoting/interface.js?customerAction"></script>]]></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>
-
- <programlisting role="XHTML"><![CDATA[<script type="text/javascript"
- src="seam/resource/remoting/interface.js?customerAction&accountAction"></script>]]></programlisting>
-
-
- <para>
- Alternatively, you may use the <literal>s:remote</literal> tag to import the required Javascript. Separate each
- component or class name you wish to import with a comma:
- </para>
-
- <programlisting role="XHTML"><![CDATA[
- <s:remote include="customerAction,accountAction"/>
- ]]></programlisting>
-
- </section>
-
- <section>
- <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>
-
- <section>
- <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>
-
- <programlisting role="JAVA"><![CDATA[@Stateless
- at Name("helloAction")
-public class HelloAction implements HelloLocal {
- public String sayHello(String name) {
- return "Hello, " + name;
- }
-}]]></programlisting>
-
- <para>You also need to create a local interface for our new component - take special note of the
- <literal>@WebRemote</literal> annotation, as it's required to make our method accessible via remoting:</para>
-
- <programlisting role="JAVA"><![CDATA[@Local
-public interface HelloLocal {
- @WebRemote
- public String sayHello(String name);
-}]]></programlisting>
-
- <para> That's all the server-side code we need to write.</para>
-
- <note>
- <para>If you are performing a persistence operation in the method marked <literal>@WebRemote</literal> you will
- also need to add a <literal>@Transactional</literal> annotation to the method. Otherwise, your method would
- execute outside of a transaction without this extra hint.That's because unlike a JSF request, Seam does not
- wrap the remoting request in a transaction automatically.</para>
- </note>
-
- <para>Now for our web page - create a new page and import the
- <literal>helloAction</literal> component: </para>
-
- <programlisting role="XHTML"><![CDATA[<s:remote include="helloAction"/>]]></programlisting>
-
- <para> To make this a fully interactive user experience, let's add a button to our page: </para>
-
- <programlisting role="XHTML"><![CDATA[<button onclick="javascript:sayHello()">Say Hello</button>]]></programlisting>
-
- <para> We'll also need to add some more script to make our button actually do something when it's clicked: </para>
-
- <programlisting role="XHTML">
-<![CDATA[<script type="text/javascript">
-<![CDATA[
- function sayHello() {
+</servlet-mapping>]]>
+</programlisting>
+ <para>
+ Next, import the necessary JavaScript into your web page. A minimum of two scripts must be imported. The first contains all client-side framework code, which enables remoting functionality:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<script type="text/javascript"
+ src="seam/resource/remoting/resource/remote.js">
+</script>]]>
+</programlisting>
+ <para>
+ The second contains the stubs and type definitions for the components you wish to call. This is generated dynamically, based on the local interface of your components, and includes type definitions for all classes that can be used to call the remotable methods of the interface. The script name reflects your component name. For example, if you annotate a stateless session bean with <literal>@Name("customerAction")</literal>, your script tag should look like this:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<script type="text/javascript"
+ src="seam/resource/remoting/interface.js?customerAction">
+</script>]]>
+</programlisting>
+ <para>
+ If you want to access more than one component from the same page, include them all as parameters of your script tag:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<script type="text/javascript"
+ src="seam/resource/remoting/interface.js?customerAction&accountAction">
+</script>]]>
+</programlisting>
+ <para>
+ You can also use the <literal>s:remote</literal> tag to import the required JavaScript. Separate each component or class name that you want to import with a comma:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:remote include="customerAction,accountAction"/>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>The "Seam" object</title>
+ <para>
+ Client-side component interaction is performed with the <literal>Seam</literal> JavaScript object defined in <literal>remote.js</literal>. This is used 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>
+ <section>
+ <title>A Hello World example</title>
+ <para>
+ To show you how the <literal>Seam</literal> object works, we will first create a new Seam component called <literal>helloAction</literal>:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateless
+ at Name("helloAction")
+public class HelloAction implements HelloLocal {
+ public String sayHello(String name) {
+ return "Hello, " + name;
+ }
+}]]>
+</programlisting>
+ <para>
+ We will also need to create a local interface for our new component. In particular, note the <literal>@WebRemote</literal> annotation, as this is required to make our method accessible via remoting:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Local
+public interface HelloLocal {
+ @WebRemote
+ public String sayHello(String name);
+}]]>
+</programlisting>
+ <para>
+ This is all the server-side code we require. Next, create a new web page and import the <literal>helloAction</literal> component:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:remote include="helloAction"/>]]>
+</programlisting>
+ <para>
+ Add a button to the page to make this an interactive user experience:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<button onclick="javascript:sayHello()">Say Hello</button>]]>
+</programlisting>
+ <para>
+ You will also need script that performs an action when the button is clicked:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<script type="text/javascript">
+ //<<![CDATA[ function sayHello() {
var name = prompt("What is your name?");
Seam.Component.getInstance("helloAction").sayHello(name, sayHelloCallback);
}
@@ -119,56 +111,43 @@
function sayHelloCallback(result) {
alert(result);
}
-]]]]><![CDATA[>
+ //]]>
</script>]]>
- </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> 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>
-
- <programlisting role="XHTML">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> 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>
-
- <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>
-
- </section>
-
- <section>
- <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>
-
- <section>
- <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>
-
- <programlisting role="JAVA">@Name("customer")
+</programlisting>
+ <para>
+ Now 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 the call's success. (You can find the full source code for this Hello World example in Seam's <literal>/examples/remoting/helloworld</literal> directory.)
+ </para>
+ <para>
+ You can see from the JavaScript code listing that we have implemented two methods. The first method prompts the user for their name, and makes a remote request. Look at the following line:
+ </para>
+
+<programlisting role="XHTML">
+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 <emphasis>stub</emphasis>, for our <literal>helloAction</literal> component. The remainder of the line (<literal>sayHello(name,sayHelloCallback);</literal>) invokes our component methods against the stub.
+ </para>
+ <para>
+ The whole line invokes the <literal>sayHello</literal> method of our component, passing in <literal>name</literal> as a parameter. The second parameter, <literal>sayHelloCallback</literal>, is not a parameter of our component's <literal>sayHello</literal> method — it tells the Seam Remoting framework that, once a response to the request is received, the response should be passed to the <literal>sayHelloCallback</literal> JavaScript method. (This callback parameter is optional; you can leave it out if you are calling a method with a <literal>void</literal> return type, or if the result of the request is not important.)
+ </para>
+ <para>
+ When the <literal>sayHelloCallback</literal> method receives the response to our remote request, it displays an alert message with the result of our method call.
+ </para>
+ </section>
+
+ <section>
+ <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 more thoroughly in the sections following. The main difference between them 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>
+ <section>
+ <title>Seam.Component.newInstance()</title>
+ <para>
+ Use this method to create a new instance of an entity or JavaBean component. The object returned will have the same getter/setter methods as its server-side counterpart. You can also access its fields directly. For example:
+ </para>
+
+<programlisting role="JAVA">
+ at Name("customer")
@Entity
public class Customer implements Serializable
{
@@ -199,613 +178,576 @@
public void setLastName(String lastName) {
this.lastName = lastName;
}
-}</programlisting>
-
- <para> To create a client-side Customer you would write the following code: </para>
-
- <programlisting role="XHTML">var customer = Seam.Component.newInstance("customer");</programlisting>
-
- <para> Then from here you can set the fields of the customer object: </para>
-
- <programlisting role="XHTML">customer.setFirstName("John");
-// Or you can set the fields directly
-customer.lastName = "Smith";</programlisting>
-
- </section>
-
- <section>
- <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>
-
- <programlisting role="XHTML">Seam.Component.getInstance("customerAction").saveCustomer(customer);</programlisting>
- </section>
-
- <section>
- <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>
-
- <programlisting role="XHTML">if (Seam.Component.getComponentName(instance) == "customer")
+}
+</programlisting>
+ <para>
+ To create a client-side Customer you would write the following code:
+ </para>
+
+<programlisting role="XHTML">
+var customer = Seam.Component.newInstance("customer");
+</programlisting>
+ <para>
+ From here, you can set the fields of the customer object.
+ </para>
+
+<programlisting role="XHTML">
+customer.setFirstName("John"); // Or you can set the fields directly
+ // customer.lastName = "Smith";
+</programlisting>
+ </section>
+
+ <section>
+ <title>Seam.Component.getInstance()</title>
+ <para>
+ The <literal>getInstance()</literal> method is used to refer 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 the previous example, if we have created a new <literal>customer</literal> and we want to save it, we pass it to the <literal>saveCustomer()</literal> method of our <literal>customerAction</literal> component:
+ </para>
+
+<programlisting role="XHTML">
+Seam.Component.getInstance("customerAction").saveCustomer( customer);
+</programlisting>
+ </section>
+
+ <section>
+ <title>Seam.Component.getComponentName()</title>
+ <para>
+ Passing an object into this method returns the component name, if it is a component, or <literal>null</literal> if it is not.
+ </para>
+
+<programlisting role="XHTML">
+if (Seam.Component.getComponentName(instance) == "customer")
alert("Customer");
else if (Seam.Component.getComponentName(instance) == "staff")
- alert("Staff member");</programlisting>
- </section>
-
- </section>
-
- <section>
- <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>
-
- <section>
- <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>
-
- <programlisting role="XHTML">var widget = Seam.Remoting.createType("com.acme.widgets.MyWidget");</programlisting>
- </section>
-
- <section>
- <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>
- </section>
- </section>
- </section>
-
- <section>
- <title>Evaluating EL Expressions</title>
-
- <para>
- Seam Remoting also supports the evaluation of EL expressions, which provides another convenient method for retrieving
- data from the server. Using the <literal>Seam.Remoting.eval()</literal> function, an EL expression can be remotely
- evaluated on the server and the resulting value returned to a client-side callback method. This function accepts two
- parameters, the first being the EL expression to evaluate, and the second being the callback method to invoke with the
- value of the expression. Here's an example:
- </para>
-
- <programlisting role="XHTML"><![CDATA[ function customersCallback(customers) {
- for (var i = 0; i < customers.length; i++) {
- alert("Got customer: " + customers[i].getName());
- }
- }
-
- Seam.Remoting.eval("#{customers}", customersCallback);
- ]]></programlisting>
-
- <para>
- In this example, the expression <literal>#{customers}</literal> is evaluated by Seam, and the value of the expression
- (in this case a list of Customer objects) is returned to the <literal>customersCallback()</literal> method. It is
- important to remember that the objects returned this way must have their types imported (via <literal>s:remote</literal>)
- to be able to work with them in Javascript. So to work with a list of <literal>customer</literal> objects,
- it is required to import the <literal>customer</literal> type:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:remote include="customer"/>]]></programlisting>
- </section>
-
- <section>
- <title>Client Interfaces</title>
-
- <para> In the configuration section above, the interface, or "stub" for our component is imported into our page
- either via <literal>seam/resource/remoting/interface.js</literal>: or using the <literal>s:remote</literal>
- tag:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<script type="text/javascript"
- src="seam/resource/remoting/interface.js?customerAction"></script>]]></programlisting>
-
- <programlisting role="XHTML"><![CDATA[<s:remote include="customerAction"/>]]></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>
-
- </section>
-
- <section>
- <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>
-
- <section>
- <title>Setting and reading the Conversation ID</title>
-
-
- <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>
-
- <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>
- </section>
- <section>
- <title>Remote calls within the current conversation scope</title>
-
- <para> In some circumstances it may be required to make a remote call within the scope of the
- current view's conversation. To do this, you must explicitly set the conversation ID to that
- of the view before making the remote call. This small snippet of JavaScript will set the
- conversation ID that is used for remoting calls to the current view's conversation ID: </para>
-
- <programlisting role="XHTML"><![CDATA[Seam.Remoting.getContext().setConversationId( #{conversation.id} );]]></programlisting>
- </section>
- </section>
-
- <section>
- <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> 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>
-
- <para> To see an example of a batch being used, take a look at <literal>/examples/remoting/chatroom</literal>.
- </para>
- </section>
-
- <section>
- <title>Working with Data types</title>
-
- <section>
- <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>
-
- <section>
- <title>String</title>
-
- <para> Simply use Javascript String objects when setting String parameter values. </para>
- </section>
-
- <section>
- <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>
- </section>
-
- <section>
- <title>Boolean</title>
-
- <para> Booleans are represented client side by Javascript Boolean values, and server side by a Java boolean.
- </para>
- </section>
- </section>
-
- <section>
- <title>JavaBeans</title>
-
- <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>
-
- <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 role="JAVA">@Name("myAction")
-public class MyAction implements MyActionLocal {
- public void doSomethingWithObject(Object obj) {
- // code
- }
-}</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>
-
- <programlisting role="XHTML"><![CDATA[<s:remote include="myAction,myWidget"/>]]></programlisting>
-
- <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>
-
- </section>
-
- <section>
- <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>
- </section>
-
- <section>
- <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>
-
- <programlisting role="JAVA">@Name("paintAction")
-public class paintAction implements paintLocal {
- public enum Color {red, green, blue, yellow, orange, purple};
-
- public void paint(Color color) {
- // code
+ alert("Staff member");
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Seam.Remoting</title>
+ <para>
+ Most of the client side functionality for Seam Remoting is held within the <literal>Seam.Remoting</literal> object. You should not need to directly call many of its methods, but there are several that are useful:
+ </para>
+ <section>
+ <title>Seam.Remoting.createType()</title>
+ <para>
+ If your application contains or uses JavaBean classes that are not 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 role="XHTML">
+var widget = Seam.Remoting.createType("com.acme.widgets.MyWidget");
+</programlisting>
+ </section>
+
+ <section>
+ <title>Seam.Remoting.getTypeName()</title>
+ <para>
+ This method is the non-component equivalent of <literal>Seam.Component.getComponentName()</literal>. It returns 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>
+ </section>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Evaluating EL Expressions</title>
+ <para>
+ Seam Remoting also supports EL expression evaluation, which is another convenient method of retrieving data from the server. The <literal>Seam.Remoting.eval()</literal> function lets the EL expression be remotely evaluated on the server, and returns the resulting value to a client-side callback method. This function accepts two parameters: the EL expression to evaluate, and the callback method to invoke with the expression value. For example:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[function customersCallback(customers) {
+ for (var i = 0; i < customers.length; i++) {
+ alert("Got customer: " + customers[i].getName());
}
-} </programlisting>
-
- <para> To call the <literal>paint()</literal> method with the color <literal>red</literal>, pass the parameter
- value as a String literal: </para>
-
- <programlisting role="XHTML">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>
- </section>
-
- <section>
- <title>Collections</title>
-
- <section>
- <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>
- </section>
-
- <section>
- <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>
-
- <programlisting role="XHTML">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>
- </section>
- </section>
- </section>
-
- <section>
- <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>
-
- <programlisting role="XHTML">Seam.Remoting.setDebug(true);</programlisting>
-
- <para> Or configure it via components.xml: </para>
-
- <programlisting role="XML"><![CDATA[<remoting:remoting 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>
- </section>
-
- <section>
- <title>Handling Exceptions</title>
+}
- <para>
- When invoking a remote component method, it is possible to specify an exception handler which will process
- the response in the event of an exception during component invocation. To specify an exception handler function,
- include a reference to it after the callback parameter in your JavaScript:
- </para>
-
- <programlisting><![CDATA[var callback = function(result) { alert(result); };
-var exceptionHandler = function(ex) { alert("An exception occurred: " + ex.getMessage()); };
-Seam.Component.getInstance("helloAction").sayHello(name, callback, exceptionHandler);]]></programlisting>
-
- <para>
- If you do not have a callback handler defined, you must specify <literal>null</literal> in its place:
- </para>
-
- <programlisting><![CDATA[var exceptionHandler = function(ex) { alert("An exception occurred: " + ex.getMessage()); };
-Seam.Component.getInstance("helloAction").sayHello(name, null, exceptionHandler);]]></programlisting>
-
- <para>
- The exception object that is passed to the exception handler exposes one method, <literal>getMessage()</literal>
- that returns the exception message which is produced by the exception thrown by the <literal>@WebRemote</literal>
- method.
- </para>
-
- </section>
-
- <section>
- <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>
-
- <section>
- <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>
-
- <programlisting role="XHTML">Seam.Remoting.loadingMessage = "Loading..."; </programlisting>
- </section>
-
- <section>
- <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>
-
- <programlisting role="XHTML">// don't display the loading indicator
-Seam.Remoting.displayLoadingMessage = function() {};
-Seam.Remoting.hideLoadingMessage = function() {};</programlisting>
- </section>
-
- <section>
- <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>
-
- <programlisting role="XHTML"> Seam.Remoting.displayLoadingMessage = function() {
- // Write code here to display the indicator
- };
-
- Seam.Remoting.hideLoadingMessage = function() {
- // Write code here to hide the indicator
- };</programlisting>
- </section>
- </section>
-
- <section>
- <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> 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>
-
- <programlisting role="JAVA">@Name("widget")
-public class Widget
-{
+Seam.Remoting.eval("#{customers}", customersCallback);
+ ]]>
+</programlisting>
+ <para>
+ Here, Seam evaluates the <literal>#{customers}</literal> expression, and the value of the expression (in this case, a list of <literal>Customer</literal> objects) is returned to the <literal>customersCallback()</literal> method. Remember, objects returned this way must have their types imported with <literal>s:remote</literal> for you to work with them in JavaScript. To work with a list of <literal>customer</literal> objects, you must be able to import the <literal>customer</literal> type:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:remote include="customer"/>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Client Interfaces</title>
+ <para>
+ In the previous configuration section, the stub for our component is imported into our page with either <literal>seam/resource/remoting/interface.js</literal>, or with the <literal>s:remote</literal> tag:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<script type="text/javascript"
+ src="seam/resource/remoting/interface.js?customerAction">
+</script> ]]>
+</programlisting>
+
+<programlisting role="XHTML"><![CDATA[<s:remote include="customerAction"/>]]>
+</programlisting>
+ <para>
+ Including this script generates the interface definitions for our component, plus any other components or types required to execute the methods of our component, and makes them available for the remoting framework's use.
+ </para>
+ <para>
+ Two types of stub can be generated: <emphasis>executable</emphasis> stubs, and <emphasis>type</emphasis> stubs. Executable stubs are behavioral, and execute methods against your session bean components. Type stubs contain state, and represent the types that can be passed in as parameters or returned as results.
+ </para>
+ <para>
+ The type of stub that is generated depends upon the type of your Seam component. If the component is a session bean, an executable stub will be generated. If it is an entity or JavaBean, a type stub will be generated. However, if your component is a JavaBean and any of its methods are annotated with <literal>@WebRemote</literal>, an executable stub will be generated. This lets you call your JavaBean component's methods in a non-EJB environment, where you do not have access to session beans.
+ </para>
+ </section>
+
+ <section>
+ <title>The Context</title>
+ <para>
+ The Seam Remoting Context contains additional information that is sent and received as part of a remoting request or response cycle. At this point, it contains only the conversation ID, but may be expanded in future.
+ </para>
+ <section>
+ <title>Setting and reading the Conversation ID</title>
+ <para>
+ If you intend to use remote calls within a conversation's scope, then you must 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>
+ <para>
+ If the conversation ID has not been explicitly set with <literal>Seam.Remoting.getContext().setConversationId()</literal>, then the first valid conversation ID returned by any remoting call is assigned automatically. If you are working with multiple conversations within your page, you may need to set your conversation ID explicitly before each call. Single conversations do not require explicit ID setting.
+ </para>
+ </section>
+
+ <section>
+ <title>Remote calls within the current conversation scope</title>
+ <para>
+ Under some circumstances, you may need to make a remote call within the scope of the current view's conversation. To do so, you must explicitly set the conversation ID to that of the view before making the remote call. The following JavaScript will set the conversation ID being used for remote calls to the current view's conversation ID:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[Seam.Remoting.getContext().setConversationId( #{conversation.id} );]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Batch Requests</title>
+ <para>
+ Seam Remoting lets you execute multiple component calls with a single request. We recommend using this feature when you need to reduce network traffic.
+ </para>
+ <para>
+ The <literal>Seam.Remoting.startBatch()</literal> method starts a new batch. 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 sends 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 containing all return values is returned to the client, and the callback functions are triggered in their execution order.
+ </para>
+ <para>
+ If you begin a batch, and then decide you do not want to send it, the <literal>Seam.Remoting.cancelBatch()</literal> method discards any queued calls and exits the batch mode.
+ </para>
+ <para>
+ For an example of batch use, see <literal>/examples/remoting/chatroom</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Working with Data types</title>
+ <section>
+ <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>
+ <section>
+ <title>String</title>
+ <para>
+ Use JavaScript String objects to set String parameter values.
+ </para>
+ </section>
+
+ <section>
+ <title>Number</title>
+ <para>
+ Seam supports all Java-supported number types. On the client side, number values are always serialized as their String representation. They are converted to the correct destination type on the server side. 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>
+ </section>
+
+ <section>
+ <title>Boolean</title>
+ <para>
+ Booleans are represented client-side by JavaScript Boolean values, and server-side by a Java Boolean.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>JavaBeans</title>
+ <para>
+ In general, these are either Seam entity or JavaBean components, or some other non-component class. Use the appropriate method to create a new instance of the object — <literal>Seam.Component.newInstance()</literal> for Seam components, or <literal>Seam.Remoting.createType()</literal> for anything else.
+ </para>
+ <para>
+ Only objects created by either of these two methods should be used as parameter values, where the parameter is not one of the preexisting valid types. You may encounter component methods where the exact parameter type cannot be determined, such as:
+ </para>
+
+<programlisting role="JAVA">
+ at Name("myAction")
+public class MyAction implements MyActionLocal {
+ public void doSomethingWithObject(Object obj) {
+ // code
+ }
+}
+</programlisting>
+ <para>
+ In this case, the interface for <literal>myAction</literal> will not include <literal>myWidget</literal>, because it is not directly referenced by any of its methods. Therefore, you cannot pass in an instance of your <literal>myWidget</literal> component unless you import it explicitly:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:remote include="myAction,myWidget"/>]]>
+</programlisting>
+ <para>
+ This allows 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>
+ </section>
+
+ <section>
+ <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> class (or a descendant class, such as <literal>java.sql.Date</literal> or <literal>java.sql.Timestamp</literal>.)
+ </para>
+ </section>
+
+ <section>
+ <title>Enums</title>
+ <para>
+ On the client side, enums are treated similarly to Strings. When setting the value for an enum parameter, use the String representation of the enum. Take the following component as an example:
+ </para>
+
+<programlisting role="JAVA">
+ at Name("paintAction")
+public class paintAction implements paintLocal {
+ public enum Color {red, green, blue, yellow, orange, purple};
+ public void paint(Color color) {
+ // code
+ }
+}
+</programlisting>
+ <para>
+ To call the <literal>paint()</literal> method with the color <literal>red</literal>, pass the parameter value as a String literal:
+ </para>
+
+<programlisting role="XHTML">
+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>
+ </section>
+
+ <section>
+ <title>Collections</title>
+ <section>
+ <title>Bags</title>
+ <para>
+ Bags cover all collection types, including arrays, collections, lists, and sets, but excluding maps — see the section following. They are implemented client-side as a JavaScript array, both when called and returned. The remoting framework on the server side can convert the bag to an appropriate type for the component method call.
+ </para>
+ </section>
+
+ <section>
+ <title>Maps</title>
+ <para>
+ The Seam Remoting framework provides simple map support where no native support is available in JavaScript. To create a map that can be used as a parameter to a remote call, create a new <literal>Seam.Remoting.Map</literal> object:
+ </para>
+
+<programlisting role="XHTML">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 is equivalent to the Java method of the same name. Where the method returns a collection, as in <literal>keySet()</literal> and <literal>values()</literal>, a JavaScript array object will be returned that contains the key or value objects (respectively).
+ </para>
+ </section>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Debugging</title>
+ <para>
+ To help you track down bugs, you can enable a debug mode, which displays the contents of all packets sent between client and server in a pop-up window. To enable debug mode, either execute the <literal>setDebug()</literal> method in JavaScript, like so:
+ </para>
+
+<programlisting role="XHTML">
+Seam.Remoting.setDebug(true);
+</programlisting>
+ <para>
+ Or configure it in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<remoting:remoting debug="true"/>]]>
+</programlisting>
+ <para>
+ To turn off debug mode, 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>
+ </section>
+
+ <section>
+ <title>Handling Exceptions</title>
+ <para>
+ When invoking a remote component method, you can specify an exception handler to process the response in the event of an exception during component invocation. To specify an exception handler function, include a reference to it after the callback parameter in your JavaScript:
+ </para>
+
+<programlisting><![CDATA[var callback = function(result) {
+ alert(result);
+};
+var exceptionHandler = function(ex) {
+ alert("An exception occurred: " + ex.getMessage());
+};
+Seam.Component.getInstance("helloAction")
+ .sayHello(name, callback, exceptionHandler);]]>
+</programlisting>
+ <para>
+ If you do not have a callback handler defined, you must specify <literal>null</literal> in its place:
+ </para>
+
+<programlisting><![CDATA[var exceptionHandler = function(ex) {
+ alert("An exception occurred: " + ex.getMessage());
+};
+Seam.Component.getInstance("helloAction")
+ .sayHello(name, null, exceptionHandler);]]>
+</programlisting>
+ <para>
+ The exception object that is passed to the exception handler exposes one method, <literal>getMessage()</literal>, which returns the exception message belonging to the exception thrown by the <literal>@WebRemote</literal> method.
+ </para>
+ </section>
+
+ <section>
+ <title>The Loading Message</title>
+ <para>
+ You can modify, define custom rendering for, or even remove the default loading message that appears in the top right corner of the screen.
+ </para>
+ <section>
+ <title>Changing the message</title>
+ <para>
+ To change the message from the default "Please Wait...", set the value of <literal>Seam.Remoting.loadingMessage</literal>:
+ </para>
+
+<programlisting role="XHTML">
+Seam.Remoting.loadingMessage = "Loading...";
+</programlisting>
+ </section>
+
+ <section>
+ <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 actionless functions:
+ </para>
+
+<programlisting role="XHTML">
+// don't display the loading indicator
+Seam.Remoting.displayLoadingMessage = function() {};
+Seam.Remoting.hideLoadingMessage = function() {};
+</programlisting>
+ </section>
+
+ <section>
+ <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 so, override the <literal>displayLoadingMessage()</literal> and <literal>hideLoadingMessage()</literal> messages with your own implementations:
+ </para>
+
+<programlisting role="XHTML">
+Seam.Remoting.displayLoadingMessage = function() {
+ // Write code here to display the indicator
+};
+Seam.Remoting.hideLoadingMessage = function() {
+ // Write code here to hide the indicator
+};
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Controlling what data is returned</title>
+ <para>
+ When a remote method is executed, the result is serialized into an XML response, which is returned to the client. This response is then unmarshaled by the client into a JavaScript object. For complex types (such as JavaBeans) that include references to other objects, all referenced objects are also serialized as part of the response. These objects can reference other objects, which can reference other objects, and so on — so, if left unchecked, this object "graph" can be enormous.
+ </para>
+ <para>
+ For this reason, and to prevent sensitive information being exposed to the client, Seam Remoting lets you 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 with 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>
+ The examples that follow are all based on this <literal>Widget</literal> class:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("widget")
+public class Widget {
private String value;
private String secret;
private Widget child;
- private Map<String,Widget> widgetMap;
- private List<Widget> widgetList;
+ private Map<String,Widget> widgetMap;
+ private List<Widget> widgetList;
- // getters and setters for all fields
-}</programlisting>
-
- <section>
- <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>
-
- <programlisting role="JAVA">@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>
-
- <programlisting role="JAVA">@WebRemote(exclude = {"child.secret"})
-public Widget getWidget();</programlisting>
-
- </section>
-
- <section>
- <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>
-
- <programlisting role="JAVA">@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
- <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>
-
- <programlisting role="JAVA">@WebRemote(exclude = {"widgetMap[value].secret"})
-public Widget getWidget(); </programlisting>
- </section>
-
- <section>
- <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>
-
- <programlisting role="JAVA">@WebRemote(exclude = {"[widget].secret"})
-public Widget getWidget(); </programlisting>
-
- </section>
-
- <section>
- <title>Combining Constraints</title>
-
- <para> Constraints can also be combined, to filter objects from multiple paths within the object graph: </para>
-
- <programlisting role="JAVA">@WebRemote(exclude = {"widgetList.secret", "widgetMap[value].secret"})
-public Widget getWidget();</programlisting>
- </section>
-
- </section>
-
- <section>
- <title>Transactional Requests</title>
-
- <para>
- By default there is no active transaction during a remoting request, so if you wish to perform database updates
- during a remoting request, you need to annotate the <literal>@WebRemote</literal> method with
- <literal>@Transactional</literal>, like so:
- </para>
-
- <programlisting><![CDATA[ @WebRemote @Transactional(TransactionPropagationType.REQUIRED)
- public void updateOrder(Order order) {
- entityManager.merge(order);
- }]]></programlisting>
- </section>
-
- <section>
- <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>
-
- <section>
- <title>Configuration</title>
-
- <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>
-
- <programlisting role="XML"><![CDATA[<remoting:remoting poll-timeout="5" poll-interval="1"/>]]></programlisting>
-
- </section>
-
- <section>
- <title>Subscribing to a JMS Topic</title>
-
- <para> The following example demonstrates how to subscribe to a JMS Topic: </para>
-
- <programlisting role="XHTML">function subscriptionCallback(message)
-{
- if (message instanceof Seam.Remoting.TextMessage)
- alert("Received message: " + message.getText());
+ // getters and setters for all fields]]>
+</programlisting>
+ <section>
+ <title>Constraining normal fields</title>
+ <para>
+ If your remote method returns an instance of <literal>Widget</literal>, but you do not want to expose the <literal>secret</literal> field because it contains sensitive information, you would constrain it like so:
+ </para>
+
+<programlisting role="JAVA">
+ at WebRemote(exclude = {"secret"})
+public Widget getWidget();
+</programlisting>
+ <para>
+ The value "secret" refers to the <literal>secret</literal> field of the returned object.
+ </para>
+ <para>
+ Now, note that the returned <literal>Widget</literal> value has a field <literal>child</literal> that is also a <literal>Widget</literal>. If we want to hide the <literal>child</literal>'s <literal>secret</literal> value, rather than the field itself, we can use dot notation to specify this field's path within the result object's graph:
+ </para>
+
+<programlisting role="JAVA">
+ at WebRemote(exclude = {"child.secret"})
+public Widget getWidget();
+</programlisting>
+ </section>
+
+ <section>
+ <title>Constraining Maps and Collections</title>
+ <para>
+ Objects within an object graph can also exist in a <literal>Map</literal> or a Collection (that is, a <literal>List</literal>, a <literal>Set</literal>, an <literal>Array</literal>, etc.). Collections 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, we would constrain the <literal>secret</literal> field of the <literal>Widget</literal>s in this list with the following notation:
+ </para>
+
+<programlisting role="JAVA">
+ at 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 <literal>[key]</literal> after the <literal>Map</literal>'s field name constrains the <literal>Map</literal>'s key object values, while <literal>[value]</literal> constrains 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 role="JAVA">
+ at WebRemote(exclude = {"widgetMap[value].secret"})
+public Widget getWidget();
+</programlisting>
+ </section>
+
+ <section>
+ <title>Constraining objects of a specific type</title>
+ <para>
+ You can use square brackets to constrain the fields of an object type regardless of its location in the object graph. If the object is a Seam component, use the name of the component; if not, use the fully-qualified class name, like so:
+ </para>
+
+<programlisting role="JAVA">
+ at WebRemote(exclude = {"[widget].secret"})
+public Widget getWidget();
+</programlisting>
+ </section>
+
+ <section>
+ <title>Combining Constraints</title>
+ <para>
+ Constraints can also be combined to filter objects from multiple paths within the object graph:
+ </para>
+
+<programlisting role="JAVA">
+ at WebRemote(exclude = {"widgetList.secret", "widgetMap[value].secret"})
+public Widget getWidget();
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Transactional Requests</title>
+ <para>
+ By default, no transaction is active during a remoting request. If you wish to update the database during a remoting request, you must annotate the <literal>@WebRemote</literal> method with <literal>@Transactional</literal>, like so:
+ </para>
+
+<programlisting><![CDATA[@WebRemote
+ at Transactional(TransactionPropagationType.REQUIRED)
+public void updateOrder(Order order) {
+ entityManager.merge(order);
+}]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>JMS Messaging</title>
+ <para>
+ Seam Remoting provides experimental support for JMS Messaging. This section describes currently-implemented JMS support. Note that this may change in the future. At present, we do not recommend using this feature within a production environment.
+ </para>
+ <section>
+ <title>Configuration</title>
+ <para>
+ Before you can subscribe to a JMS topic, you must first configure a list of the topics that Seam Remoting can subscribe to. List the topics under <literal>org.jboss.seam.remoting.messaging.subscriptionRegistry. allowedTopics</literal> in <filename>seam.properties</filename>, <filename>web.xml</filename> or <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<remoting:remoting poll-timeout="5" poll-interval="1"/>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Subscribing to a JMS Topic</title>
+ <para>
+ The following example demonstrates how to subscribe to a JMS Topic:
+ </para>
+
+<programlisting role="XHTML">
+function subscriptionCallback(message) {
+ if (message instanceof Seam.Remoting.TextMessage)
+ alert("Received message: " + message.getText());
}
-
-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> 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>value</literal> field (or call its
- <literal>getValue()</literal> method). </para>
- </section>
-
- <section>
- <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>
-
- <programlisting role="XHTML">Seam.Remoting.unsubscribe("topicName");</programlisting>
- </section>
-
- <section>
- <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> 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>
-
- <programlisting role="XML"><![CDATA[<remoting:remoting poll-timeout="5" poll-interval="1"/>]]></programlisting>
-
- <para> Via JavaScript: </para>
-
- <programlisting role="XHTML">// Only wait 1 second between receiving a poll response and sending the next poll request.
-Seam.Remoting.pollInterval = 1;
-
-// Wait up to 5 seconds on the server for new messages
-Seam.Remoting.pollTimeout = 5; </programlisting>
-
- </section>
-
- </section>
-
+Seam.Remoting.subscribe("topicName", subscriptionCallback);
+</programlisting>
+ <para>
+ The <literal>Seam.Remoting.subscribe()</literal> method accepts two parameters: the name of the JMS topic to subscribe to, and the callback function to invoke when a message is received.
+ </para>
+ <para>
+ Two message types are supported: Text messages, and Object messages. To test for the message type that is passed to your callback function, use the <literal>instanceof</literal> operator. This tests 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. (You can also fetch this value by calling the object's <literal>getText()</literal> method.) An <literal>ObjectMessage</literal> contains its object value in its <literal>value</literal> field. (You can also fetch this value by calling the object's <literal>getValue()</literal> method.)
+ </para>
+ </section>
+
+ <section>
+ <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>
+
+<programlisting role="XHTML">
+Seam.Remoting.unsubscribe("topicName");
+</programlisting>
+ </section>
+
+ <section>
+ <title>Tuning the Polling Process</title>
+ <para>
+ Polling can be controlled and modified with two parameters.
+ </para>
+ <para>
+ <literal>Seam.Remoting.pollInterval</literal> controls how long to wait between subsequent polls for new messages. This parameter is expressed in seconds, and its default setting is <literal>10</literal>.
+ </para>
+ <para>
+ <literal>Seam.Remoting.pollTimeout</literal> is also expressed in 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 <literal>0</literal> seconds, which means that when the server is polled, if there are no messages ready for delivery, an empty response will be immediately returned.
+ </para>
+ <para>
+ Use caution when setting a high <literal>pollTimeout</literal> value. Each request that has to wait for a message uses a server thread until either the message is received, or the request times out. If many such requests are served simultaneously, a large number of server threads will be used.
+ </para>
+ <para>
+ We recommend setting these options in <filename>components.xml</filename>, but they can be overridden with JavaScript if desired. The following example demonstrates a more aggressive polling method. Set these parameters to values that suit your application:
+ </para>
+ <para>
+ In <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<remoting:remoting poll-timeout="5" poll-interval="1"/>]]>
+</programlisting>
+ <para>
+ With JavaScript:
+ </para>
+
+<programlisting role="XHTML">
+// Only wait 1 second between receiving a poll response and sending
+// the next poll request.
+Seam.Remoting.pollInterval = 1;
+// Wait up to 5 seconds on the server for new messages
+Seam.Remoting.pollTimeout = 5;
+</programlisting>
+ </section>
+
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Revision_History.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Revision_History.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Revision_History.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,21 +1,19 @@
-<?xml version='1.0'?>
+<?xml version='1.0' encoding='utf-8' ?>
<!DOCTYPE revhistory PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
]>
<revhistory>
-
-<revision>
- <revnumber>5.0.0</revnumber>
- <date>Feb 07 2008</date>
+ <revision>
+ <revnumber>1.2</revnumber>
+ <date>Wed Feb 17 2010</date>
<author>
- <firstname>Samson</firstname>
- <surname>Kittoli</surname>
- <email></email>
+ <firstname>Laura</firstname>
+ <surname>Bailey</surname>
+ <email>lbailey at redhat.com</email>
</author>
<revdescription>
<simplelist>
- <member>content reformat</member>
-
+ <member>Updated RESTEasy section.</member>
</simplelist>
</revdescription>
</revision>
Added: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide.ent
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide.ent (rev 0)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide.ent 2010-05-25 14:38:51 UTC (rev 12794)
@@ -0,0 +1,4 @@
+<!ENTITY JBEAP "JBoss Enterprise Application Platform">
+<!ENTITY VERSION "5.0.1">
+<!ENTITY HOLDER "Red Hat, Inc">
+<!ENTITY YEAR "2010">
Added: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide.xml (rev 0)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -0,0 +1,50 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
+
+<book>
+ <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Tutorial.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Migration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Gettingstarted.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Getting_Started_With_JBoss_Tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Xml.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Events.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Conversations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Jbpm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Persistence.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Validation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Groovy.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!-- <xi:include href="Wicket.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
+ <xi:include href="Framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Drools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="I18n.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Text.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Itext.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Excel.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!-- <xi:include href="Rss.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
+ <xi:include href="Mail.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Jms.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Cache.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Webservices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Remoting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Gwt.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Spring.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Hsearch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Annotations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Components.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Controls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Elenhancements.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Clustering_EJBPassivation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Performance.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <xi:include href="Tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+ <!-- <xi:include href="Weblogic.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
+ <!-- <xi:include href="Websphere.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
+ <!-- <xi:include href="Glassfish.xml" xmlns:xi="http://www.w3.org/2001/XInclude" /> -->
+ <xi:include href="Dependencies.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
+</book>
+
Property changes on: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Seam_Reference_Guide.xml
___________________________________________________________________
Name: svn:executable
+ *
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Security.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Security.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Security.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,1033 +1,820 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<chapter id="security">
- <title>Security</title>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- <sect1>
- <title>Overview</title>
-
- <para>
- The Seam Security API provides a multitude of security-related features for your Seam-based application, covering
- such areas as:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Authentication - an extensible, JAAS-based authentication layer that allows users to authenticate
- against any security provider.
- </para>
- </listitem>
- <listitem>
- <para>
- Identity Management - an API for managing a Seam application's users and roles at runtime.
- </para>
- </listitem>
- <listitem>
- <para>
- Authorization - an extremely comprehensive authorization framework, supporting user roles, persistent and
- rule-based permissions, and a pluggable permission resolver for easily implementing customised security logic.
- </para>
- </listitem>
- <listitem>
- <para>
- Permission Management - a set of built-in Seam components to allow easy management of an application's
- security policy.
- </para>
- </listitem>
- <listitem>
- <para>
- CAPTCHA support - to assist in the prevention of automated software/scripts abusing your Seam-based site.
- </para>
- </listitem>
- <listitem>
- <para>
- And much more
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- This chapter will cover each of these features in detail.
- </para>
+<chapter id="security" >
+ <title>Security</title>
+ <section>
+ <title>Overview</title>
+ <para>
+ The Seam Security API provides a multitude of security-related features for your Seam-based application, including:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Authentication — an extensible, Java Authentication and Authorization Service (JAAS) based authentication layer that allows users to authenticate against any security provider.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Identity Management — an API for managing the users and roles of a Seam application at runtime.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Authorization — an extremely comprehensive authorization framework, supporting user roles, persistent and rule-based permissions, and a pluggable permission-resolver that makes it easy to implement customized security logic.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Permission Management — a set of built-in Seam components that make it easy to manage an application's security policy.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ CAPTCHA support — to assist in the prevention of automated software/scripts abusing your Seam-based site.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ This chapter covers each of these features in detail.
+ </para>
+ </section>
+
+ <section>
+ <title>Disabling Security</title>
+ <para>
+ In some situations, you may need to disable Seam Security (during unit tests, for instance, or to use a different security approach, like native JAAS). To disable the security infrastructure, call the static method <literal>Identity.setSecurityEnabled(false)</literal>. However, when you want to configure the application, a more convenient alternative is to control the following settings in <filename>components.xml</filename>:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Entity Security
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Hibernate Security Interceptor
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Seam Security Interceptor
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Page restrictions
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Servlet API security integration
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ This chapter documents the vast number of options available when establishing the user's identity (authentication) and establishing access constraints (authorization). We will begin with the foundation of the security model: authentication.
+ </para>
+ </section>
+
+ <section>
+ <title>Authentication</title>
+ <para>
+ Seam Security provides Java Authentication and Authorization Service (JAAS) based authorization features, providing a robust and highly configurable API for handling user authentication. If your authentication needs are not this complex, Seam also offers a simplified authentication method.
+ </para>
+ <section>
+ <title>Configuring an Authenticator component</title>
+ <note>
+ <para>
+ If you use Seam's Identity Management features, you can skip this section — it is not necessary to create an authenticator component.
+ </para>
+ </note>
+ <para>
+ Seam's simplified authentication method uses a built-in JAAS login module (<literal>SeamLoginModule</literal>) to delegate authentication to one of your own Seam components. (This module requires no additional configuration files, and comes pre-configured within Seam.) With this, you can write an authentication method with the entity classes provided by your own application, or authenticate through another third-party provider. Configuring this simplified authentication requires the <literal>identity</literal> component to be configured in <filename>components.xml</filename>
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:core="http://jboss.com/products/seam/core"
+ xmlns:security="http://jboss.com/products/seam/security"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation=
+ "http://jboss.com/products/seam/components
+ http://jboss.com/products/seam/components-2.2.xsd
+ http://jboss.com/products/seam/security
+ http://jboss.com/products/seam/security-2.2.xsd">
- </sect1>
+<security:identity authenticate-method="#{authenticator.authenticate}"/>
- <sect1>
- <title>Disabling Security</title>
-
- <para>
- In some situations it may be necessary to disable Seam Security, for instances during unit tests or because you
- are using a different approach to security, such as native JAAS. Simply call the static method
- <literal>Identity.setSecurityEnabled(false)</literal> to disable the security infrastructure. Of course, it's not
- very convenient to have to call a static method when you want to configure the application, so as an alternative
- you can control this setting in components.xml:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>Entity Security</para>
- </listitem>
- <listitem>
- <para>Hibernate Security Interceptor</para>
- </listitem>
- <listitem>
- <para>Seam Security Interceptor</para>
- </listitem>
- <listitem>
- <para>Page restrictions</para>
- </listitem>
- <listitem>
- <para>Servlet API security integration</para>
- </listitem>
- </itemizedlist>
-
- <para>
- Assuming you are planning to take advantage of what Seam Security has to offer, the rest of this chapter documents
- the plethora of options you have for giving your user an identity in the eyes of the security model
- (authentication) and locking down the application by establishing constraints (authorization). Let's begin with
- the task of authentication since that's the foundation of any security model.
- </para>
-
- </sect1>
-
- <sect1>
- <title>Authentication</title>
-
- <para>
- The authentication features provided by Seam Security are built upon JAAS (Java Authentication and Authorization Service),
- and as such provide a robust and highly configurable API for handling user authentication. However, for less complex
- authentication requirements Seam offers a much more simplified method of authentication that hides the complexity of JAAS.
- </para>
-
- <sect2>
- <title>Configuring an Authenticator component</title>
-
- <note>
- <para>
- If you use Seam's Identity Management features (discussed later in this chapter) then it is not necessary to create
- an authenticator component (and you can skip this section).
- </para>
- </note>
-
- <para>
- The simplified authentication method provided by Seam uses a built-in JAAS login module, <literal>SeamLoginModule</literal>, which
- delegates authentication to one of your own Seam components. This login module is already configured inside Seam as
- part of a default application policy and as such does not require any additional configuration files. It allows you to
- write an authentication method using the entity classes that are provided by your own application, or alternatively to
- authenticate with some other third party provider. Configuring this simplified form of authentication requires the
- <literal>identity</literal> component to be configured in <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:core="http://jboss.com/products/seam/core"
- xmlns:security="http://jboss.com/products/seam/security"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation=
- "http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.2.xsd
- http://jboss.com/products/seam/security http://jboss.com/products/seam/security-2.2.xsd">
-
- <security:identity authenticate-method="#{authenticator.authenticate}"/>
-
-</components>]]></programlisting>
-
- <para>
- The EL expression <literal>#{authenticator.authenticate}</literal> is a method binding that indicates
- the <literal>authenticate</literal> method of the <literal>authenticator</literal> component will be used
- to authenticate the user.
- </para>
-
- </sect2>
-
- <sect2>
- <title>Writing an authentication method</title>
-
- <para>
- The <literal>authenticate-method</literal> property specified for <literal>identity</literal> in
- <literal>components.xml</literal> specifies which method will be used by <literal>SeamLoginModule</literal>
- to authenticate users. This method takes no parameters, and is expected to return a boolean, which indicates
- whether authentication is successful or not. The user's username and password can be obtained from
- <literal>Credentials.getUsername()</literal> and <literal>Credentials.getPassword()</literal>,
- respectively (you can get a reference to the <literal>credentials</literal> component via
- <literal>Identity.instance().getCredentials()</literal>). Any roles that the user is a member of
- should be assigned using <literal>Identity.addRole()</literal>. Here's a complete example of an
- authentication method inside a POJO component:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("authenticator")
+</components>]]>
+</programlisting>
+ <para>
+ <literal>#{authenticator.authenticate}</literal> is a method binding that indicates the <literal>authenticate</literal> method of the <literal>authenticator</literal> component will be used to authenticate the user.
+ </para>
+ </section>
+
+ <section>
+ <title>Writing an authentication method</title>
+ <para>
+ The <literal>authenticate-method</literal> property specified for <literal>identity</literal> in <filename>components.xml</filename> specifies the method used by <literal>SeamLoginModule</literal> to authenticate users. This method takes no parameters, and is expected to return a Boolean indicating authentication success or failure. Username and password are obtained from <literal>Credentials.getUsername()</literal> and <literal>Credentials.getPassword()</literal> respectively. (A reference to the <literal>credentials</literal> component can be obtained via <literal>Identity.instance().getCredentials()</literal>.) Any role that the user is a member of should be assigned with <literal>Identity.addRole()</literal>. The following is a complete example of an authentication method inside a POJO component:
+ </para>
+
+<programlisting role="JAVA"> <![CDATA[@Name("authenticator")
public class Authenticator {
- @In EntityManager entityManager;
- @In Credentials credentials;
- @In Identity identity;
+ @In EntityManager entityManager;
+ @In Credentials credentials;
+ @In Identity identity;
- public boolean authenticate() {
- try {
- User user = (User) entityManager.createQuery(
- "from User where username = :username and password = :password")
- .setParameter("username", credentials.getUsername())
- .setParameter("password", credentials.getPassword())
- .getSingleResult();
+ public boolean authenticate() {
+ try {
+ User user = (User) entityManager.createQuery(
+ "from User where username = :username and password = :password")
+ .setParameter("username", credentials.getUsername())
+ .setParameter("password", credentials.getPassword())
+ .getSingleResult();
- if (user.getRoles() != null) {
- for (UserRole mr : user.getRoles())
- identity.addRole(mr.getName());
- }
+ if (user.getRoles() != null) {
+ for (UserRole mr : user.getRoles())
+ identity.addRole(mr.getName());
+ }
- return true;
+ return true;
+ } catch (NoResultException ex) {
+ return false;
}
- catch (NoResultException ex) {
- return false;
- }
}
-}]]></programlisting>
+}]]>
+</programlisting>
+ <para>
+ In the example, both <literal>User</literal> and <literal>UserRole</literal> are application-specific entity beans. The <literal>roles</literal> parameter is populated with roles that the user is a member of. This is added to the <literal>Set</literal> as literal string values — for example, "admin", "user", etc. If the user record is not found, and a <literal>NoResultException</literal> is thrown, the authentication method returns <literal>false</literal> to indicate authentication failure.
+ </para>
+ <note>
+ <para>
+ It is important to keep authenticator methods minimal and free from any side-effects — they can be invoked multiple times during a single request, so any special code that should execute when authentication succeeds or fails should implement an event observer. See <xref linkend="security-security_events" /> later in this chapter for more information about events raised by Seam Security.
+ </para>
+ </note>
+ <section>
+ <title>Identity.addRole()</title>
+ <para>
+ The <literal>Identity.addRole()</literal> method's behavior depends upon current session authentication. If the session is not authenticated, <literal>addRole()</literal> should only be called during the authentication process. When called here, the role name is placed in a temporary list of pre-authenticated roles. Once authentication succeeds, the pre-authenticated roles then become "real" roles, and calling <literal>Identity.hasRole()</literal> for those roles returns <literal>true</literal>. The following sequence diagram represents the list of pre-authenticated roles as a first class object to clarify its position in the authentication process.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/security-addrole.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/security-addrole.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ If the current session is already authenticated, then calling <literal>Identity.addRole()</literal> grants the specified role to the current user immediately.
+ </para>
+ </section>
+
+ <section>
+ <title>Writing an event observer for security-related events</title>
+ <para>
+ If, upon successful login, some user statistics require updates, you can write an event observer for the <literal>org.jboss.seam.security.loginSuccessful</literal> event, like this:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[
+ at In UserStats userStats;
- <para>
- In the above example, both <literal>User</literal> and <literal>UserRole</literal> are application-specific
- entity beans. The <literal>roles</literal> parameter is populated with the roles that the user is a member
- of, which should be added to the <literal>Set</literal> as literal string values, e.g. "admin", "user".
- In this case, if the user record is not found and a <literal>NoResultException</literal> thrown, the
- authentication method returns <literal>false</literal> to indicate the authentication failed.
- </para>
-
- <tip>
- <para>
- When writing an authenticator method, it is important that it is kept minimal and free from
- any side-effects. This is because there is no guarantee as to how many times the authenticator
- method will be called by the security API, and as such it may be invoked multiple times during
- a single request. Because of this, any special code that should execute upon a successful or
- failed authentication should be written by implementing an event observer. See the section on
- Security Events further down in this chapter for more information about which events are
- raised by Seam Security.
- </para>
- </tip>
-
- <sect3>
- <title>Identity.addRole()</title>
-
- <para>
- The <literal>Identity.addRole()</literal> method behaves differently depending on whether the current
- session is authenticated or not. If the session is not authenticated, then <literal>addRole()</literal>
- should <emphasis>only</emphasis> be called during the authentication process. When called here, the
- role name is placed into a temporary list of pre-authenticated roles. Once authentication is successful,
- the pre-authenticated roles then become "real" roles, and calling <literal>Identity.hasRole()</literal>
- for those roles will then return true. The following sequence diagram represents the list of pre-authenticated
- roles as a first class object to show more clearly how it fits in to the authentication process.
-
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-addrole.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-addrole.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>
- If the current session is already authenticated, then calling <literal>Identity.addRole()</literal> will
- have the expected effect of immediately granting the specified role to the current user.
- </para>
-
- </sect3>
-
- <sect3>
- <title>Writing an event observer for security-related events</title>
-
- <para>
- Say for example, that upon a successful login that some user statistics must be
- updated. This would be done by writing an event observer for the
- <literal>org.jboss.seam.security.loginSuccessful</literal> event, like this:
- </para>
-
- <programlisting role="JAVA"><![CDATA[ @In UserStats userStats;
-
- @Observer("org.jboss.seam.security.loginSuccessful")
- public void updateUserStats()
- {
- userStats.setLastLoginDate(new Date());
- userStats.incrementLoginCount();
- }]]></programlisting>
-
- <para>
- This observer method can be placed anywhere, even in the Authenticator component itself.
- You can find more information about security-related events later in this chapter.
- </para>
- </sect3>
-
- </sect2>
-
- <sect2>
- <title>Writing a login form</title>
-
- <para>
- The <literal>credentials</literal> component provides both <literal>username</literal> and <literal>password</literal>
- properties, catering for the most common authentication scenario. These properties can be bound directly to the
- username and password fields on a login form. Once these properties are set, calling
- <literal>identity.login()</literal> will authenticate the user using the provided credentials.
- Here's an example of a simple login form:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<div>
- <h:outputLabel for="name" value="Username"/>
- <h:inputText id="name" value="#{credentials.username}"/>
+ at Observer("org.jboss.seam.security.loginSuccessful")
+public void updateUserStats() {
+ userStats.setLastLoginDate(new Date());
+ userStats.incrementLoginCount();
+}]]>
+</programlisting>
+ <para>
+ This observer method can be placed anywhere, even in the Authenticator component itself. More information about other security-related events appears later in the chapter.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Writing a login form</title>
+ <para>
+ The <literal>credentials</literal> component provides both <literal>username</literal> and <literal>password</literal> properties, catering for the most common authentication scenario. These properties can be bound directly to the username and password fields on a login form. Once these properties are set, calling <literal>identity.login()</literal> authenticates the user with the credentials provided. An example of a simple login form is as follows:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<div>
+ <h:outputLabel for="name" value="Username"/>
+ <h:inputText id="name" value="#{credentials.username}"/>
</div>
<div>
- <h:outputLabel for="password" value="Password"/>
- <h:inputSecret id="password" value="#{credentials.password}"/>
+ <h:outputLabel for="password" value="Password"/>
+ <h:inputSecret id="password" value="#{credentials.password}"/>
</div>
<div>
- <h:commandButton value="Login" action="#{identity.login}"/>
-</div>]]></programlisting>
-
- <para>
- Similarly, logging out the user is done by calling <literal>#{identity.logout}</literal>. Calling this
- action will clear the security state of the currently authenticated user, and invalidate the user's session.
- </para>
-
- </sect2>
-
- <sect2>
- <title>Configuration Summary</title>
- <para>
- So to sum up, there are the three easy steps to configure authentication:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Configure an authentication method in <literal>components.xml</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- Write an authentication method.
- </para>
- </listitem>
- <listitem>
- <para>
- Write a login form so that the user can authenticate.
- </para>
- </listitem>
- </itemizedlist>
-
- </sect2>
-
- <sect2>
- <title>Remember Me</title>
-
- <para>
- Seam Security supports the same kind of "Remember Me" functionality that is commonly encountered in many
- online web-based applications. It is actually supported in two different "flavours", or modes - the first
- mode allows the username to be stored in the user's browser as a cookie, and leaves the entering of the
- password up to the browser (many modern browsers are capable of remembering passwords).
- </para>
-
- <para>
- The second mode supports the storing of a unique token in a cookie, and allows a user to authenticate
- automatically upon returning to the site, without having to provide a password.
- </para>
-
- <warning>
- <para>
- Automatic client authentication with a persistent cookie stored on the client machine is dangerous.
- While convenient for users, any cross-site scripting security hole in your website would have dramatically more
- serious effects than usual. Without the authentication cookie, the only cookie to steal for an attacker with XSS
- is the cookie of the current session of a user. This means the attack only works when the user has an open session -
- which should be a short timespan. However, it is much more attractive and dangerous if an attacker has the possibility
- to steal a persistent Remember Me cookie that allows him to login without authentication, at any time. Note that this
- all depends on how well you protect your website against XSS attacks - it's up to you to make sure that your website
- is 100% XSS safe - a non-trival achievement for any website that allows user input to be rendered on a page.
- </para>
-
- <para>
- Browser vendors recognized this issue and introduced a "Remember Passwords" feature - today almost all browsers support
- this. Here, the browser remembers the login username and password for a particular website and domain, and fills out the
- login form automatically when you don't have an active session with the website. If you as a website designer then offer
- a convenient login keyboard shortcut, this approach is almost as convenient as a "Remember Me" cookie and much safer.
- Some browsers (e.g. Safari on OS X) even store the login form data in the encrypted global operation system keychain.
- Or, in a networked environment, the keychain can be transported with the user (between laptop and desktop for example),
- while browser cookies are usually not synchronized.
- </para>
-
- <para>
- To summarize: While everyone is doing it, persistent "Remember Me" cookies with automatic authentication are a bad
- practice and should not be used. Cookies that "remember" only the users login name, and fill out the login form with
- that username as a convenience, are not an issue.
- </para>
- </warning>
-
- <para>
- To enable the remember me feature for the default (safe, username only) mode, no special configuration is required.
- In your login form, simply bind the remember me checkbox to <literal>rememberMe.enabled</literal>, like in the following
- example:
- </para>
-
- <programlisting role="XHTML"><![CDATA[ <div>
- <h:outputLabel for="name" value="User name"/>
- <h:inputText id="name" value="#{credentials.username}"/>
- </div>
+ <h:commandButton value="Login" action="#{identity.login}"/>
+</div>]]>
+</programlisting>
+ <para>
+ Similarly, the user is logged out by calling <literal>#{identity.logout}</literal>. This action clears the security state of the currently authenticated user and invalidate the user's session.
+ </para>
+ </section>
+
+ <section>
+ <title>Configuration Summary</title>
+ <para>
+ There are three easy steps to configure authentication:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Configure an authentication method in <filename>components.xml</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Write an authentication method.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Write a login form so that the user can authenticate.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Remember Me</title>
+ <para>
+ Seam Security supports two different modes of the <emphasis>Remember Me</emphasis> functionality common to many web-based applications. The first mode allows the username to be stored in the user's browser as a cookie, and leaves the browser to remember the password. The second mode stores a unique token in a cookie, and lets a user authenticate automatically when they return to the site, without having to provide a password.
+ </para>
+ <warning>
+ <para>
+ Although it is convenient for users, automatic client authentication through a persistent cookie on the client machine is dangerous because the effects of any cross-site scripting (XSS) security hole are magnified. Without the authentication cookie, the only cookie an attacker can steal with XSS is the user's <emphasis>current session cookie</emphasis> — so an attack can only occur while a user has a session open. If a persistent <emphasis>Remember Me</emphasis> cookie is stolen, an attacker can log in without authentication at any time. If you wish to use automatic client authentication, it is vital to protect your website against XSS attacks.
+ </para>
+ <para>
+ Browser vendors introduced the <emphasis>Remember Passwords</emphasis> feature to combat this issue. Here, the browser remembers the username and password used to log in to a particular website and domain, and automatically fills in the login form when there is no session active. A login keyboard shortcut on your website can make the login process almost as convenient as the "Remember Me" cookie, and much safer. Some browsers (for example, Safari on OS X) store the login form data in the encrypted global operation system keychain. In a networked environment, the keychain can be transported with the user between laptop and desktop — cookies are not usually synchronised.
+ </para>
+ <para>
+ Although persistent <emphasis>Remember Me</emphasis> cookies with automatic authentication are widely used, they are bad security practice. Cookies that recall only the user's login name, and fill out the login form with that username as a convenience, are much more secure.
+ </para>
+ </warning>
+ <para>
+ No special configuration is required to enable the <emphasis>Remember Me</emphasis> feature for the default (safe, username-only) mode. In your login form, simply bind the <emphasis>Remember Me</emphasis> checkbox to <literal>rememberMe.enabled</literal>, as seen in the following example:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<div>
+ <h:outputLabel for="name" value="User name"/>
+ <h:inputText id="name" value="#{credentials.username}"/>
+</div>
- <div>
- <h:outputLabel for="password" value="Password"/>
- <h:inputSecret id="password" value="#{credentials.password}" redisplay="true"/>
- </div>
+<div>
+ <h:outputLabel for="password" value="Password"/>
+ <h:inputSecret id="password" value="#{credentials.password}" redisplay="true"/>
+</div>
- <div class="loginRow">
- <h:outputLabel for="rememberMe" value="Remember me"/>
- <h:selectBooleanCheckbox id="rememberMe" value="#{rememberMe.enabled}"/>
- </div>]]></programlisting>
-
- <sect3>
- <title>Token-based Remember-me Authentication</title>
-
- <para>
- To use the automatic, token-based mode of the remember me feature, you must first configure a token store. The
- most common scenario is to store these authentication tokens within a database (which Seam supports), however it
- is possible to implement your own token store by implementing the <literal>org.jboss.seam.security.TokenStore</literal>
- interface. This section will assume you will be using the provided <literal>JpaTokenStore</literal> implementation
- to store authentication tokens inside a database table.
- </para>
-
- <para>
- The first step is to create a new Entity which will contain the tokens. The following example shows a possible
- structure that you may use:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Entity
+<div class="loginRow">
+ <h:outputLabel for="rememberMe" value="Remember me"/>
+ <h:selectBooleanCheckbox id="rememberMe" value="#{rememberMe.enabled}"/>
+</div>]]>
+</programlisting>
+ <section>
+ <title>Token-based <emphasis>Remember Me</emphasis> Authentication</title>
+ <para>
+ To use the automatic, token-based mode of the <emphasis>Remember Me</emphasis> feature, you must first configure a token store. These authentication tokens are commonly stored within a database. Seam supports this method, but you can also implement your own token store by using the <literal>org.jboss.seam.security.TokenStore</literal> interface. This section assumes that you will be using the provided <literal>JpaTokenStore</literal> implementation to store authentication tokens inside a database table.
+ </para>
+ <para>
+ First, create a new Entity to hold the tokens. The following is one possible structure:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Entity
public class AuthenticationToken implements Serializable {
- private Integer tokenId;
- private String username;
- private String value;
+ private Integer tokenId;
+ private String username;
+ private String value;
- @Id @GeneratedValue
- public Integer getTokenId() {
- return tokenId;
- }
+ @Id @GeneratedValue
+ public Integer getTokenId() {
+ return tokenId;
+ }
- public void setTokenId(Integer tokenId) {
- this.tokenId = tokenId;
- }
+ public void setTokenId(Integer tokenId) {
+ this.tokenId = tokenId;
+ }
- @TokenUsername
- public String getUsername() {
- return username;
- }
+ @TokenUsername
+ public String getUsername() {
+ return username;
+ }
- public void setUsername(String username) {
- this.username = username;
- }
+ public void setUsername(String username) {
+ this.username = username;
+ }
- @TokenValue
- public String getValue() {
- return value;
- }
+ @TokenValue
+ public String getValue() {
+ return value;
+ }
- public void setValue(String value) {
- this.value = value;
- }
-}]]></programlisting>
+ public void setValue(String value) {
+ this.value = value;
+ }
+}]]>
+</programlisting>
+ <para>
+ Several special annotations, <literal>@TokenUsername</literal> and <literal>@TokenValue</literal>, are used to configure the username and token properties of the entity. These annotations are required for the entity that holds the authentication tokens.
+ </para>
+ <para>
+ The next step is to configure <literal>JpaTokenStore</literal> to store and retrieve authentication tokens with this entity bean. Do this by specifying the <literal>token-class</literal> attribute in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<security:jpa-token-store
+ token-class="org.jboss.seam.example.seamspace.AuthenticationToken"/>]]>
+</programlisting>
+ <para>
+ The final step is to configure the <literal>RememberMe</literal> component in <filename>components.xml</filename>. Its <literal>mode</literal> should be set to <literal>autoLogin</literal>:
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<security:remember-me mode="autoLogin"/>]]>
+</programlisting>
+ <para>
+ Users who check the <emphasis>Remember Me</emphasis> checkbox will now be authenticated automatically.
+ </para>
+ <para>
+ To ensure that users are automatically authenticated when returning to the site, the following section should be placed in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<event type="org.jboss.seam.security.notLoggedIn">
+ <action execute="#{redirect.captureCurrentView}"/>
+ <action execute="#{identity.tryLogin()}"/>
+</event>
+<event type="org.jboss.seam.security.loginSuccessful">
+ <action execute="#{redirect.returnToCapturedView}"/>
+</event>]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Handling Security Exceptions</title>
+ <para>
+ So that users do not receive a basic default error page when a security error occurs, you should edit <filename>pages.xml</filename> to redirect users to a more attractive page. The two main exceptions thrown by the security API are:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <exceptionname>NotLoggedInException</exceptionname> — This exception is thrown when the user attempts to access a restricted action or page when they are not logged in.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <exceptionname>AuthorizationException</exceptionname> — This exception is only thrown if the user is already logged in, and they have attempted to access a restricted action or page for which they do not have the necessary privileges.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ In the case of a <exceptionname>NotLoggedInException</exceptionname>, we recommend the user be redirected to a login or registration page so that they can log in. For an <exceptionname>AuthorizationException</exceptionname>, it may be useful to redirect the user to an error page. Here's an example of a <filename>pages.xml</filename> file that redirects both of these security exceptions:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
- <para>
- As you can see from this listing, a couple of special annotations, <literal>@TokenUsername</literal> and
- <literal>@TokenValue</literal> are used to configure the username and token properties of the entity. These
- annotations are required for the entity that will contain the authentication tokens.
- </para>
-
- <para>
- The next step is to configure <literal>JpaTokenStore</literal> to use this entity bean to store and retrieve
- authentication tokens. This is done in <literal>components.xml</literal> by specifying the <literal>token-class</literal>
- attribute:
- </para>
-
- <programlisting role="XML"><![CDATA[
- <security:jpa-token-store token-class="org.jboss.seam.example.seamspace.AuthenticationToken"/>
- ]]></programlisting>
-
- <para>
- Once this is done, the last thing to do is to configure the <literal>RememberMe</literal> component in
- <literal>components.xml</literal> also. Its <literal>mode</literal> should be set to <literal>autoLogin</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[ <security:remember-me mode="autoLogin"/>
- ]]></programlisting>
-
- <para>
- That is all that is required - automatic authentication will now occur for users revisiting your site (as long as they
- check the "remember me" checkbox).
- </para>
-
- <para>
- To ensure that users are automatically authenticated when returning to the site, the following section
- should be placed in components.xml:
- </para>
+ ...
- <programlisting role="XML"><![CDATA[ <event type="org.jboss.seam.security.notLoggedIn">
- <action execute="#{redirect.captureCurrentView}"/>
- <action execute="#{identity.tryLogin()}"/>
- </event>
- <event type="org.jboss.seam.security.loginSuccessful">
- <action execute="#{redirect.returnToCapturedView}"/>
- </event>]]></programlisting>
-
- </sect3>
-
- </sect2>
+ <exception class="org.jboss.seam.security.NotLoggedInException">
+ <redirect view-id="/login.xhtml">
+ <message>You must be logged in to perform this action</message>
+ </redirect>
+ </exception>
- <sect2>
- <title>Handling Security Exceptions</title>
+ <exception class="org.jboss.seam.security.AuthorizationException">
+ <end-conversation/>
+ <redirect view-id="/security_error.xhtml">
+ <message>
+ You do not have the necessary security privileges to perform this action.
+ </message>
+ </redirect>
+ </exception>
- <para>
- To prevent users from receiving the default error page in response to a security error, it's recommended that
- <literal>pages.xml</literal> is configured to redirect security errors to a more "pretty" page. The two
- main types of exceptions thrown by the security API are:
- </para>
+</pages>]]>
+</programlisting>
+ <para>
+ Most web applications require more sophisticated handling of login redirection. Seam includes some special functionality, outlined in the following section.
+ </para>
+ </section>
+
+ <section>
+ <title>Login Redirection</title>
+ <para>
+ When an unauthenticated user tries to access a particular view or wildcarded view ID, you can have Seam redirect the user to a login screen as follows:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages login-view-id="/login.xhtml">
- <itemizedlist>
- <listitem>
- <para>
- <literal>NotLoggedInException</literal> - This exception is thrown if the user attempts to access a
- restricted action or page when they are not logged in.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>AuthorizationException</literal> - This exception is only thrown if the user is already logged in,
- and they have attempted to access a restricted action or page for which they do not have the necessary
- privileges.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- In the case of a <literal>NotLoggedInException</literal>, it is recommended that the user is redirected to
- either a login or registration page so that they can log in. For an <literal>AuthorizationException</literal>,
- it may be useful to redirect the user to an error page. Here's an example of a <literal>pages.xml</literal>
- file that redirects both of these security exceptions:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages>
-
- ...
-
- <exception class="org.jboss.seam.security.NotLoggedInException">
- <redirect view-id="/login.xhtml">
- <message>You must be logged in to perform this action</message>
- </redirect>
- </exception>
-
- <exception class="org.jboss.seam.security.AuthorizationException">
- <end-conversation/>
- <redirect view-id="/security_error.xhtml">
- <message>You do not have the necessary security privileges to perform this action.</message>
- </redirect>
- </exception>
-
-</pages>]]></programlisting>
-
- <para>
- Most web applications require even more sophisticated handling of login redirection, so
- Seam includes some special functionality for handling this problem.
- </para>
-
- </sect2>
-
- <sect2>
- <title>Login Redirection</title>
-
- <para>
- You can ask Seam to redirect the user to a login screen when an unauthenticated user tries
- to access a particular view (or wildcarded view id) as follows:
- </para>
-
- <programlisting role="XML"><![CDATA[<pages login-view-id="/login.xhtml">
-
- <page view-id="/members/*" login-required="true"/>
-
- ...
-
-</pages>]]></programlisting>
-
- <tip>
- <para>
- This is less of a blunt instrument than the exception handler shown above, but should
- probably be used in conjunction with it.
- </para>
- </tip>
-
- <para>
- After the user logs in, we want to automatically send them back where they came from, so
- they can retry the action that required logging in. If you add the following event listeners
- to <literal>components.xml</literal>, attempts to access a restricted view while not logged
- in will be remembered, so that upon the user successfully logging in they will be redirected
- to the originally requested view, with any page parameters that existed in the original
- request.
- </para>
-
- <programlisting role="XML"><![CDATA[<event type="org.jboss.seam.security.notLoggedIn">
- <action execute="#{redirect.captureCurrentView}"/>
+ <page view-id="/members/*" login-required="true"/>
+...
+</pages>]]>
+</programlisting>
+ <note>
+ <para>
+ This is more refined than the exception handler shown above, but should probably be used in conjunction with it.
+ </para>
+ </note>
+ <para>
+ After the user logs in, we want to automatically redirect them to the action that required login. If you add the following event listeners to <filename>components.xml</filename>, attempts to access a restricted view while not logged in are remembered. Upon a successful login, the user is redirected to the originally requested view, with any page parameters that existed in the original request.
+ </para>
+
+<programlisting role="XML"><![CDATA[<event type="org.jboss.seam.security.notLoggedIn">
+ <action execute="#{redirect.captureCurrentView}"/>
</event>
<event type="org.jboss.seam.security.postAuthenticate">
- <action execute="#{redirect.returnToCapturedView}"/>
-</event>]]></programlisting>
+ <action execute="#{redirect.returnToCapturedView}"/>
+</event>]]>
+</programlisting>
+ <note>
+ <para>
+ Login redirection is implemented as a conversation-scoped mechanism, so do not end the conversation in your <literal>authenticate()</literal> method.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>HTTP Authentication</title>
+ <para>
+ Although we do not recommend it unless absolutely necessary, Seam provides the means to authenticate with either HTTP Basic or HTTP Digest (RFC 2617) methods. For either form, you must first enable the <literal>authentication-filter</literal> component in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<web:authentication-filter url-pattern="*.seam" auth-type="basic"/> ]]>
+</programlisting>
+ <para>
+ To enable basic authentication, set <literal>auth-type</literal> to <literal>basic</literal>. For digest authentication, set it to <literal>digest</literal>. If you want to use digest authentication, you must also set the <literal>key</literal> and <literal>realm</literal>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<web:authentication-filter url-pattern="*.seam" auth-type="digest"
+ key="AA3JK34aSDlkj" realm="My App"/> ]]>
+</programlisting>
+ <para>
+ The <literal>key</literal> can be any String value. The <literal>realm</literal> is the name of the authentication realm that is presented to the user when they authenticate.
+ </para>
+ <section>
+ <title>Writing a Digest Authenticator</title>
+ <para>
+ If using digest authentication, your authenticator class should extend the abstract class <literal>org.jboss.seam.security.digest.DigestAuthenticator</literal>, and use the <literal>validatePassword()</literal> method to validate the user's plain text password against the digest request. Here is an example:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public boolean authenticate() {
+ try {
+ User user = (User) entityManager.createQuery(
+ "from User where username = "username")
+ .setParameter("username", identity.getUsername())
+ .getSingleResult();
- <para>
- Note that login redirection is implemented as a conversation-scoped mechanism, so don't end
- the conversation in your <literal>authenticate()</literal> method.
- </para>
-
- </sect2>
-
- <sect2>
- <title>HTTP Authentication</title>
-
- <para>
- Although not recommended for use unless absolutely necessary, Seam provides means for authenticating
- using either HTTP Basic or HTTP Digest (RFC 2617) methods. To use either form of authentication,
- the <literal>authentication-filter</literal> component must be enabled in components.xml:
- </para>
-
- <programlisting role="XML"><![CDATA[
- <web:authentication-filter url-pattern="*.seam" auth-type="basic"/>
- ]]></programlisting>
-
- <para>
- To enable the filter for basic authentication, set <literal>auth-type</literal> to <literal>basic</literal>,
- or for digest authentication, set it to <literal>digest</literal>. If using digest authentication, the
- <literal>key</literal> and <literal>realm</literal> must also be set:
- </para>
-
- <programlisting role="XML"><![CDATA[
- <web:authentication-filter url-pattern="*.seam" auth-type="digest" key="AA3JK34aSDlkj" realm="My App"/>
- ]]></programlisting>
-
- <para>
- The <literal>key</literal> can be any String value. The <literal>realm</literal> is the name of the
- authentication realm that is presented to the user when they authenticate.
- </para>
-
- <sect3>
- <title>Writing a Digest Authenticator</title>
-
- <para>
- If using digest authentication, your authenticator class should extend the abstract class
- <literal>org.jboss.seam.security.digest.DigestAuthenticator</literal>, and use the
- <literal>validatePassword()</literal> method to validate the user's plain text password
- against the digest request. Here is an example:
- </para>
-
- <programlisting role="JAVA"><![CDATA[
- public boolean authenticate()
- {
- try
- {
- User user = (User) entityManager.createQuery(
- "from User where username = :username")
- .setParameter("username", identity.getUsername())
- .getSingleResult();
-
- return validatePassword(user.getPassword());
- }
- catch (NoResultException ex)
- {
- return false;
- }
- }
- ]]></programlisting>
- </sect3>
-
- </sect2>
-
- <sect2>
- <title>Advanced Authentication Features</title>
-
- <para>
- This section explores some of the advanced features provided by the security API for addressing more complex
- security requirements.
- </para>
-
- <sect3>
- <title>Using your container's JAAS configuration</title>
-
- <para>
- If you would rather not use the simplified JAAS configuration provided by the Seam Security API, you may
- instead delegate to the default system JAAS configuration by providing a <literal>jaas-config-name</literal>
- property in <literal>components.xml</literal>. For example, if you are using JBoss AS and wish to use
- the <literal>other</literal> policy (which uses the <literal>UsersRolesLoginModule</literal> login module
- provided by JBoss AS), then the entry in <literal>components.xml</literal> would look like this:
- </para>
-
- <programlisting role="XML"><![CDATA[<security:identity jaas-config-name="other"/>]]></programlisting>
-
- <para>
- Please keep in mind that doing this does not mean that your user will be authenticated in whichever
- container your Seam application is deployed in. It merely instructs Seam Security to authenticate
- itself using the configured JAAS security policy.
- </para>
- </sect3>
- </sect2>
- </sect1>
-
- <sect1>
- <title>Identity Management</title>
-
- <para>
- Identity Management provides a standard API for the management of a Seam application's users and roles,
- regardless of which identity store (database, LDAP, etc) is used on the backend. At the center
- of the Identity Management API is the <literal>identityManager</literal> component, which provides
- all the methods for creating, modifying and deleting users, granting and revoking roles, changing passwords,
- enabling and disabling user accounts, authenticating users and listing users and roles.
- </para>
-
- <para>
- Before it may be used, the <literal>identityManager</literal> must first be configured with one or more
- <literal>IdentityStore</literal>s. These components do the actual work of interacting with the backend
- security provider, whether it be a database, LDAP server, or something else.
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-identitymanager.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-identitymanager.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <sect2>
- <title>Configuring IdentityManager</title>
-
- <para>
- The <literal>identityManager</literal> component allows for separate identity stores to be configured
- for authentication and authorization operations. This means that it is possible for users to
- be authenticated against one identity store, for example an LDAP directory, yet have their roles
- loaded from another identity store, such as a relational database.
- </para>
-
- <para>
- Seam provides two <literal>IdentityStore</literal> implementations out of the box;
- <literal>JpaIdentityStore</literal> uses a relational database to store user and role information,
- and is the default identity store that is used if nothing is explicitly configured in the
- <literal>identityManager</literal> component. The other implementation that is provided is
- <literal>LdapIdentityStore</literal>, which uses an LDAP directory to store users and roles.
- </para>
-
- <para>
- There are two configurable properties for the <literal>identityManager</literal> component -
- <literal>identityStore</literal> and <literal>roleIdentityStore</literal>. The value for these
- properties must be an EL expression referring to a Seam component implementing the
- <literal>IdentityStore</literal> interface. As already mentioned,
- if left unconfigured then <literal>JpaIdentityStore</literal> will be assumed by default. If
- only the <literal>identityStore</literal> property is configured, then the same value will be used for
- <literal>roleIdentityStore</literal> also. For example, the following entry in
- <literal>components.xml</literal> will configure <literal>identityManager</literal> to use
- an <literal>LdapIdentityStore</literal> for both user-related and role-related operations:
- </para>
-
- <programlisting role="XML"><![CDATA[
- <security:identity-manager identity-store="#{ldapIdentityStore}"/>
- ]]></programlisting>
-
- <para>
- The following example configures <literal>identityManager</literal> to use an <literal>LdapIdentityStore</literal>
- for user-related operations, and <literal>JpaIdentityStore</literal> for role-related operations:
- </para>
-
- <programlisting role="XML"><![CDATA[
- <security:identity-manager
- identity-store="#{ldapIdentityStore}"
- role-identity-store="#{jpaIdentityStore}"/>
- ]]></programlisting>
-
- <para>
- The following sections explain both of these identity store implementations in greater detail.
- </para>
-
- </sect2>
-
- <sect2>
- <title>JpaIdentityStore</title>
-
- <para>
- This identity store allows for users and roles to be stored inside a relational database. It is designed
- to be as unrestrictive as possible in regards to database schema design, allowing a great deal of
- flexibility in the underlying table structure. This is achieved through the use of a set of special
- annotations, allowing entity beans to be configured to store user and role records.
- </para>
-
- <sect3>
- <title>Configuring JpaIdentityStore</title>
-
- <para>
- <literal>JpaIdentityStore</literal> requires that both the <literal>user-class</literal> and
- <literal>role-class</literal> properties are configured. These properties should refer to the
- entity classes that are to be used to store both user and role records, respectively. The following
- example shows the configuration from <literal>components.xml</literal> in the SeamSpace example:
- </para>
-
- <programlisting role="XML"><![CDATA[
- <security:jpa-identity-store
- user-class="org.jboss.seam.example.seamspace.MemberAccount"
- role-class="org.jboss.seam.example.seamspace.MemberRole"/>
- ]]></programlisting>
-
- </sect3>
-
- <sect3>
- <title>Configuring the Entities</title>
-
- <para>
- As already mentioned, a set of special annotations are used to configure entity beans for storing
- users and roles. The following table lists each of the annotations, and their descriptions.
- </para>
-
- <table>
- <title>User Entity Annotations</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="2*" />
- <colspec colnum="2" colwidth="1*" />
- <colspec colnum="3" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Annotation</para>
- </entry>
- <entry align="center">
- <para>Status</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <para>
- <literal>@UserPrincipal</literal>
- </para>
- </entry>
- <entry>
- <para>Required</para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the user's username.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@UserPassword</literal>
- </para>
- </entry>
- <entry>
- <para>Required</para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the user's password. It allows a <literal>hash</literal>
- algorithm to be specified for password hashing. Possible values for <literal>hash</literal> are
- <literal>md5</literal>, <literal>sha</literal> and <literal>none</literal>. E.g:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@UserPassword(hash = "md5")
+ return validatePassword(user.getPassword());
+ } catch (NoResultException ex) {
+ return false;
+ }
+}]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Advanced Authentication Features</title>
+ <para>
+ This section explores some of the advanced features provided by the security API for addressing more complex security requirements.
+ </para>
+ <section>
+ <title>Using your container's JAAS configuration</title>
+ <para>
+ If you prefer not to use the simplified JAAS configuration provided by the Seam Security API, you can use the default system JAAS configuration by adding a <literal>jaas-config-name</literal> property to <literal>components.xml</literal>. For example, if you use JBoss AS and want to use the <literal>other</literal> policy (which uses the <literal>UsersRolesLoginModule</literal> login module provided by JBoss AS), then the entry in <filename>components.xml</filename> would look like this:
+ </para>
+
+<programlisting role="XML"><![CDATA[<security:identity jaas-config-name="other"/>]]>
+</programlisting>
+ <para>
+ Keep in mind that doing this does not mean that your user will be authenticated in your Seam application container — it instructs Seam Security to authenticate itself with the configured JAAS security policy.
+ </para>
+ </section>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Identity Management</title>
+ <para>
+ Identity Management provides a standard API for managing a Seam application's users and roles, regardless of the identity store (database, LDAP, etc.) used in back-end operations. The <literal>identityManager</literal> component is at the core of the Identity Management API, and provides all methods for creating, modifying, and deleting users, granting and revoking roles, changing passwords, enabling and disabling user accounts, authenticating users, and listing users and roles.
+ </para>
+ <para>
+ Before use, the <literal>identityManager</literal> must be configured with at least one <literal>IdentityStore</literal>. These components interact with the back-end security provider.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/security-identitymanager.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/security-identitymanager.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <section>
+ <title>Configuring IdentityManager</title>
+ <para>
+ The <literal>identityManager</literal> component allows you to configure separate identity stores for authentication and authorization. This means that users can be authenticated against one identity store (for example, an LDAP directory), but have their roles loaded from another identity store (such as a relational database).
+ </para>
+ <para>
+ Seam provides two <literal>IdentityStore</literal> implementations out of the box. The default, <literal>JpaIdentityStore</literal>, uses a relational database to store user and role information. The other implementation is <literal>LdapIdentityStore</literal>, which uses an LDAP directory to store users and roles.
+ </para>
+ <para>
+ The <literal>identityManager</literal> component has two configurable properties: <literal>identityStore</literal> and <literal>roleIndentityStore</literal>. The value for these properties must be an EL expression that refers to a Seam component with the <literal>IdentityStore</literal> interface. If left unconfigured, the default (<literal>JpaIdentityStore</literal>) will be used. If only the <literal>identityStore</literal> property is configured, the same value will be used for <literal>roleIdentityStore</literal>. For example, the following entry in <filename>components.xml</filename> will configure <literal>identityManager</literal> to use an <literal>LdapIdentityStore</literal> for both user-related and role-related operations:
+ </para>
+
+<programlisting role="XML"><![CDATA[<security:identity-manager identity-store="#{ldapIdentityStore}"/>
+]]>
+</programlisting>
+ <para>
+ The following example configures <literal>identityManager</literal> to use an <literal>LdapIdentityStore</literal> for user-related operations, and <literal>JpaIdentityStore</literal> for role-related operations:
+ </para>
+
+<programlisting role="XML"><![CDATA[<security:identity-manager identity-store="#{ldapIdentityStore}"
+ role-identity-store="#{jpaIdentityStore}"/>
+]]>
+</programlisting>
+ <para>
+ The following sections explain each identity storage method in greater detail.
+ </para>
+ </section>
+
+ <section>
+ <title>JpaIdentityStore</title>
+ <para>
+ This method stores users and roles in a relational database. It is designed to allow flexible database design and table structure. A set of special annotations lets entity beans store user and role records.
+ </para>
+ <section>
+ <title>Configuring JpaIdentityStore</title>
+ <para>
+ Both <literal>user-class</literal> and <literal>role-class</literal> must be configured before <literal>JpaIdentityStore</literal> can be used. These properties refer to the entity classes used to store user and role records, respectively. The following example shows the <filename>components.xml</filename> file from the SeamSpace example:
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<security:jpa-identity-store
+ user-class="org.jboss.seam.example.seamspace.MemberAccount"
+ role-class="org.jboss.seam.example.seamspace.MemberRole"/>
+]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Configuring the Entities</title>
+ <para>
+ The following table describes the special annotations used to configure entity beans for user and role storage.
+ </para>
+ <table>
+ <title>User Entity Annotations</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="2*"></colspec>
+ <colspec colnum="2" colwidth="1*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Annotation
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Status
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Description
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>@UserPrincipal</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation marks the field or method containing the user's username.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@UserPassword</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation marks the field or method containing the user's password. It allows a <literal>hash</literal> algorithm to be specified for password hashing. Possible values for <literal>hash</literal> are <literal>md5</literal>, <literal>sha</literal> and <literal>none</literal>. For example:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@UserPassword(hash = "md5")
public String getPasswordHash() {
return passwordHash;
-}]]></programlisting>
-
- <para>
- If an application requires a hash algorithm that isn't supported natively by Seam, it
- is possible to extend the <literal>PasswordHash</literal> component to implement other
- hashing algorithms.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@UserFirstName</literal>
- </para>
- </entry>
- <entry>
- <para>Optional</para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the user's first name.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@UserLastName</literal>
- </para>
- </entry>
- <entry>
- <para>Optional</para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the user's last name.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@UserEnabled</literal>
- </para>
- </entry>
- <entry>
- <para>Optional</para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the enabled status of the user. This should be a boolean
- property, and if not present then all user accounts are assumed to be enabled.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@UserRoles</literal>
- </para>
- </entry>
- <entry>
- <para>Required</para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the roles of the user. This property will be described in
- more detail further down.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <table>
- <title>Role Entity Annotations</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="2*" />
- <colspec colnum="2" colwidth="1*" />
- <colspec colnum="3" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Annotation</para>
- </entry>
- <entry align="center">
- <para>Status</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <para>
- <literal>@RoleName</literal>
- </para>
- </entry>
- <entry>
- <para>Required</para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the name of the role.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@RoleGroups</literal>
- </para>
- </entry>
- <entry>
- <para>Optional</para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method containing the group memberships of the role.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@RoleConditional</literal>
- </para>
- </entry>
- <entry>
- <para>Optional</para>
- </entry>
- <entry>
- <para>
- This annotation marks the field or method indicating whether the role is conditional or not.
- Conditional roles are explained later in this chapter.
- </para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </sect3>
-
- <sect3>
- <title>Entity Bean Examples</title>
-
- <para>
- As mentioned previously, <literal>JpaIdentityStore</literal> is designed to be as flexible as possible when
- it comes to the database schema design of your user and role tables. This section looks at a number of
- possible database schemas that can be used to store user and role records.
- </para>
-
- <sect4>
- <title>Minimal schema example</title>
-
- <para>
- In this bare minimal example, a simple user and role table are linked via a
- many-to-many relationship using a cross-reference table named <literal>UserRoles</literal>.
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-entities-1.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-entities-1.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <programlisting role="JAVA"><![CDATA[@Entity
+}]]>
+</programlisting>
+ <para>
+ It is possible to extend the <literal>PasswordHash</literal> component to implement other hashing algorithms, if required.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@UserFirstName</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Optional
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation marks the field or method containing the user's first name.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@UserLastName</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Optional
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation marks the field or method containing the user's last name.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@UserEnabled</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Optional
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation marks the field or method containing the enabled user status. This should be a Boolean property. If not present, all user accounts are assumed to be enabled.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@UserRoles</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation marks the field or method containing the roles of the user. This property will be described in more detail in a later section. <!-- #modify: xref if possible -->
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <table>
+ <title>Role Entity Annotations</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="2*"></colspec>
+ <colspec colnum="2" colwidth="1*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Annotation
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Status
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Description
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>@RoleName</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Required
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation marks the field or method containing the name of the role.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@RoleGroups</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Optional
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation marks the field or method containing the group memberships of the role.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@RoleConditional</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Optional
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation marks the field or method that indicates whether a role is conditional. Conditional roles are explained later in this chapter.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Entity Bean Examples</title>
+ <para>
+ As mentioned previously, <literal>JpaIdentityStore</literal> is designed to be as flexible as possible when it comes to the database schema design of your user and role tables. This section looks at a number of possible database schemas that can be used to store user and role records.
+ </para>
+ <section>
+ <title>Minimal schema example</title>
+ <para>
+ Here, a simple user and role table are linked via a many-to-many relationship using a cross-reference table named <literal>UserRoles</literal>.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/security-entities-1.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/security-entities-1.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+
+<programlisting role="JAVA"><![CDATA[@Entity
public class User {
private Integer userId;
private String username;
@@ -1044,16 +831,20 @@
@UserPassword(hash = "md5")
public String getPasswordHash() { return passwordHash; }
- public void setPasswordHash(String passwordHash) { this.passwordHash = passwordHash; }
+ public void setPasswordHash(String passwordHash) {
+ this.passwordHash = passwordHash;
+ }
@UserRoles
@ManyToMany(targetEntity = Role.class)
@JoinTable(name = "UserRoles",
- joinColumns = @JoinColumn(name = "UserId"),
- inverseJoinColumns = @JoinColumn(name = "RoleId"))
+ joinColumns = @JoinColumn(name = "UserId"),
+ inverseJoinColumns = @JoinColumn(name = "RoleId"))
public Set<Role> getRoles() { return roles; }
public void setRoles(Set<Role> roles) { this.roles = roles; }
-}]]></programlisting>
+}]]>
+</programlisting>
+
<programlisting><![CDATA[@Entity
public class Role {
private Integer roleId;
@@ -1066,28 +857,25 @@
@RoleName
public String getRolename() { return rolename; }
public void setRolename(String rolename) { this.rolename = rolename; }
-}]]></programlisting>
-
- </sect4>
-
- <sect4>
- <title>Complex Schema Example</title>
-
- <para>
- This example builds on the above minimal example by including all of the optional fields, and allowing
- group memberships for roles.
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-entities-2.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-entities-2.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <programlisting role="JAVA"><![CDATA[@Entity
+}]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Complex Schema Example</title>
+ <para>
+ This example builds on the previous minimal example by including all optional fields, and allowing group memberships for roles.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/security-entities-2.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/security-entities-2.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+
+<programlisting role="JAVA"><![CDATA[@Entity
public class User {
private Integer userId;
private String username;
@@ -1107,11 +895,15 @@
@UserPassword(hash = "md5")
public String getPasswordHash() { return passwordHash; }
- public void setPasswordHash(String passwordHash) { this.passwordHash = passwordHash; }
+ public void setPasswordHash(String passwordHash) {
+ this.passwordHash = passwordHash;
+ }
@UserFirstName
public String getFirstname() { return firstname; }
- public void setFirstname(String firstname) { this.firstname = firstname; }
+ public void setFirstname(String firstname) {
+ this.firstname = firstname;
+ }
@UserLastName
public String getLastname() { return lastname; }
@@ -1128,7 +920,9 @@
inverseJoinColumns = @JoinColumn(name = "RoleId"))
public Set<Role> getRoles() { return roles; }
public void setRoles(Set<Role> roles) { this.roles = roles; }
-}]]></programlisting>
+}]]>
+</programlisting>
+
<programlisting><![CDATA[@Entity
public class Role {
private Integer roleId;
@@ -1145,1270 +939,1200 @@
@RoleConditional
public boolean isConditional() { return conditional; }
- public void setConditional(boolean conditional) { this.conditional = conditional; }
+ public void setConditional(boolean conditional) {
+ this.conditional = conditional;
+ }
@RoleGroups
@ManyToMany(targetEntity = Role.class)
@JoinTable(name = "RoleGroups",
- joinColumns = @JoinColumn(name = "RoleId"),
- inverseJoinColumns = @JoinColumn(name = "GroupId"))
+ joinColumns = @JoinColumn(name = "RoleId"),
+ inverseJoinColumns = @JoinColumn(name = "GroupId"))
public Set<Role> getGroups() { return groups; }
public void setGroups(Set<Role> groups) { this.groups = groups; }
-}]]></programlisting>
- </sect4>
-
- </sect3>
-
- <sect3>
- <title>JpaIdentityStore Events</title>
-
- <para>
- When using <literal>JpaIdentityStore</literal> as the identity store implementation with <literal>IdentityManager</literal>,
- a few events are raised as a result of invoking certain <literal>IdentityManager</literal> methods.
- </para>
-
- <sect4>
- <title>JpaIdentityStore.EVENT_PRE_PERSIST_USER</title>
-
- <para>
- This event is raised in response to calling <literal>IdentityManager.createUser()</literal>. Just before the user
- entity is persisted to the database, this event will be raised passing the entity instance as an event parameter.
- The entity will be an instance of the <literal>user-class</literal> configured for <literal>JpaIdentityStore</literal>.
- </para>
-
- <para>
- Writing an observer for this event may be useful for setting additional field values on the entity, which aren't set
- as part of the standard <literal>createUser()</literal> functionality.
- </para>
- </sect4>
-
- <sect4>
- <title>JpaIdentityStore.EVENT_USER_CREATED</title>
-
- <para>
- This event is also raised in response to calling <literal>IdentityManager.createUser()</literal>. However, it is
- raised after the user entity has already been persisted to the database. Like the <literal>EVENT_PRE_PERSIST_USER</literal>
- event, it also passes the entity instance as an event parameter. It may be useful to observe this event if you also
- need to persist other entities that reference the user entity, for example contact detail records or other user-specific
- data.
- </para>
- </sect4>
-
- <sect4>
- <title>JpaIdentityStore.EVENT_USER_AUTHENTICATED</title>
-
- <para>
- This event is raised when calling <literal>IdentityManager.authenticate()</literal>. It passes the user entity instance
- as the event parameter, and is useful for reading additional properties from the user entity that is being authenticated.
- </para>
- </sect4>
- </sect3>
-
- </sect2>
-
- <sect2>
- <title>LdapIdentityStore</title>
-
- <para>
- This identity store implementation is designed for working with user records stored in an LDAP directory. It is very
- highly configurable, allowing great flexibility in how both users and roles are stored in the directory. The following
- sections describe the configuration options for this identity store, and provide some configuration examples.
- </para>
-
- <sect3>
- <title>Configuring LdapIdentityStore</title>
-
- <para>
- The following table describes the available properties that can be configured in <literal>components.xml</literal> for
- <literal>LdapIdentityStore</literal>.
- </para>
-
- <table>
- <title>LdapIdentityStore Configuration Properties</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="2*" />
- <colspec colnum="2" colwidth="1*" />
- <colspec colnum="3" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Property</para>
- </entry>
- <entry align="center">
- <para>Default Value</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <para>
- <literal>server-address</literal>
- </para>
- </entry>
- <entry>
- <para><literal>localhost</literal></para>
- </entry>
- <entry>
- <para>
- The address of the LDAP server.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>server-port</literal>
- </para>
- </entry>
- <entry>
- <para><literal>389</literal></para>
- </entry>
- <entry>
- <para>
- The port number that the LDAP server is listening on.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>user-context-DN</literal>
- </para>
- </entry>
- <entry>
- <para><literal>ou=Person,dc=acme,dc=com</literal></para>
- </entry>
- <entry>
- <para>
- The Distinguished Name (DN) of the context containing user records.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>user-DN-prefix</literal>
- </para>
- </entry>
- <entry>
- <para><literal>uid=</literal></para>
- </entry>
- <entry>
- <para>
- This value is prefixed to the front of the username to locate the user's record.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>user-DN-suffix</literal>
- </para>
- </entry>
- <entry>
- <para><literal>,ou=Person,dc=acme,dc=com</literal></para>
- </entry>
- <entry>
- <para>
- This value is appended to the end of the username to locate the user's record.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>role-context-DN</literal>
- </para>
- </entry>
- <entry>
- <para><literal>ou=Role,dc=acme,dc=com</literal></para>
- </entry>
- <entry>
- <para>
- The DN of the context containing role records.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>role-DN-prefix</literal>
- </para>
- </entry>
- <entry>
- <para><literal>cn=</literal></para>
- </entry>
- <entry>
- <para>
- This value is prefixed to the front of the role name to form the DN for locating the
- role record.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>role-DN-suffix</literal>
- </para>
- </entry>
- <entry>
- <para><literal>,ou=Roles,dc=acme,dc=com</literal></para>
- </entry>
- <entry>
- <para>
- This value is appended to the role name to form the DN for locating the role record.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>bind-DN</literal>
- </para>
- </entry>
- <entry>
- <para><literal>cn=Manager,dc=acme,dc=com</literal></para>
- </entry>
- <entry>
- <para>
- This is the context used to bind to the LDAP server.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>bind-credentials</literal>
- </para>
- </entry>
- <entry>
- <para><literal>secret</literal></para>
- </entry>
- <entry>
- <para>
- These are the credentials (the password) used to bind to the LDAP server.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>user-role-attribute</literal>
- </para>
- </entry>
- <entry>
- <para><literal>roles</literal></para>
- </entry>
- <entry>
- <para>
- This is the name of the attribute of the user record that contains the list of roles that the
- user is a member of.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>role-attribute-is-DN</literal>
- </para>
- </entry>
- <entry>
- <para><literal>true</literal></para>
- </entry>
- <entry>
- <para>
- This boolean property indicates whether the role attribute of the user record is itself a
- distinguished name.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>user-name-attribute</literal>
- </para>
- </entry>
- <entry>
- <para><literal>uid</literal></para>
- </entry>
- <entry>
- <para>
- Indicates which attribute of the user record contains the username.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>user-password-attribute</literal>
- </para>
- </entry>
- <entry>
- <para><literal>userPassword</literal></para>
- </entry>
- <entry>
- <para>
- Indicates which attribute of the user record contains the user's password.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>first-name-attribute</literal>
- </para>
- </entry>
- <entry>
- <para><literal>null</literal></para>
- </entry>
- <entry>
- <para>
- Indicates which attribute of the user record contains the user's first name.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>last-name-attribute</literal>
- </para>
- </entry>
- <entry>
- <para><literal>sn</literal></para>
- </entry>
- <entry>
- <para>
- Indicates which attribute of the user record contains the user's last name.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>full-name-attribute</literal>
- </para>
- </entry>
- <entry>
- <para><literal>cn</literal></para>
- </entry>
- <entry>
- <para>
- Indicates which attribute of the user record contains the user's full (common) name.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>enabled-attribute</literal>
- </para>
- </entry>
- <entry>
- <para><literal>null</literal></para>
- </entry>
- <entry>
- <para>
- Indicates which attribute of the user record determines whether the user is enabled.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>role-name-attribute</literal>
- </para>
- </entry>
- <entry>
- <para><literal>cn</literal></para>
- </entry>
- <entry>
- <para>
- Indicates which attribute of the role record contains the name of the role.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>object-class-attribute</literal>
- </para>
- </entry>
- <entry>
- <para><literal>objectClass</literal></para>
- </entry>
- <entry>
- <para>
- Indicates which attribute determines the class of an object in the directory.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>role-object-classes</literal>
- </para>
- </entry>
- <entry>
- <para><literal>organizationalRole</literal></para>
- </entry>
- <entry>
- <para>
- An array of the object classes that new role records should be created as.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>user-object-classes</literal>
- </para>
- </entry>
- <entry>
- <para><literal>person,uidObject</literal></para>
- </entry>
- <entry>
- <para>
- An array of the object classes that new user records should be created as.
- </para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </sect3>
-
- <sect3>
- <title>LdapIdentityStore Configuration Example</title>
-
- <para>
- The following configuration example shows how <literal>LdapIdentityStore</literal> may be configured for
- an LDAP directory running on fictional host <literal>directory.mycompany.com</literal>. The users are stored
- within this directory under the context <literal>ou=Person,dc=mycompany,dc=com</literal>, and are identified
- using the <literal>uid</literal> attribute (which corresponds to their username). Roles are stored in their
- own context, <literal>ou=Roles,dc=mycompany,dc=com</literal> and referenced from the user's entry via the
- <literal>roles</literal> attribute. Role entries are identified by their common name (the <literal>cn</literal> attribute)
- , which corresponds to the role name. In this example, users may be disabled by setting the value of their
- <literal>enabled</literal> attribute to false.
- </para>
-
- <programlisting role="XML"><![CDATA[
- <security:ldap-identity-store
- server-address="directory.mycompany.com"
- bind-DN="cn=Manager,dc=mycompany,dc=com"
- bind-credentials="secret"
- user-DN-prefix="uid="
- user-DN-suffix=",ou=Person,dc=mycompany,dc=com"
- role-DN-prefix="cn="
- role-DN-suffix=",ou=Roles,dc=mycompany,dc=com"
- user-context-DN="ou=Person,dc=mycompany,dc=com"
- role-context-DN="ou=Roles,dc=mycompany,dc=com"
- user-role-attribute="roles"
- role-name-attribute="cn"
- user-object-classes="person,uidObject"
- enabled-attribute="enabled"
- />]]></programlisting>
-
- </sect3>
-
- </sect2>
-
- <sect2>
- <title>Writing your own IdentityStore</title>
-
- <para>
- Writing your own identity store implementation allows you to authenticate and perform identity management
- operations against security providers that aren't supported out of the box by Seam. Only a single class is
- required to achieve this, and it must implement the
- <literal>org.jboss.seam.security.management.IdentityStore</literal> interface.
- </para>
-
- <para>
- Please refer to the JavaDoc for <literal>IdentityStore</literal> for a description of the methods that
- must be implemented.
- </para>
- </sect2>
-
-
- <sect2>
- <title>Authentication with Identity Management</title>
-
- <para>
- If you are using the Identity Management features in your Seam application, then it is not required
- to provide an authenticator component (see previous Authentication section) to enable authentication.
- Simply omit the <literal>authenticator-method</literal> from the <literal>identity</literal> configuration
- in <literal>components.xml</literal>, and the <literal>SeamLoginModule</literal> will by default
- use <literal>IdentityManager</literal> to authenticate your application's users, without any special
- configuration required.
- </para>
- </sect2>
-
- <sect2>
- <title>Using IdentityManager</title>
-
- <para>
- The <literal>IdentityManager</literal> can be accessed either by injecting it into your Seam
- component as follows:
- </para>
-
- <programlisting role="JAVA"><![CDATA[ @In IdentityManager identityManager;]]></programlisting>
-
- <para>
- or by accessing it through its static <literal>instance()</literal> method:
- </para>
-
- <programlisting role="JAVA"><![CDATA[ IdentityManager identityManager = IdentityManager.instance();]]></programlisting>
-
- <para>
- The following table describes <literal>IdentityManager</literal>'s API methods:
- </para>
-
- <table>
- <title>Identity Management API</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Method</para>
- </entry>
- <entry align="center">
- <para>Returns</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para>
- <literal>createUser(String name, String password)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Creates a new user account, with the specified name and password. Returns <literal>true</literal>
- if successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>deleteUser(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Deletes the user account with the specified name. Returns <literal>true</literal>
- if successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>createRole(String role)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Creates a new role, with the specified name. Returns <literal>true</literal>
- if successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>deleteRole(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Deletes the role with the specified name. Returns <literal>true</literal>
- if successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>enableUser(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Enables the user account with the specified name. Accounts that are not enabled are
- not able to authenticate. Returns <literal>true</literal> if successful, or
- <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>disableUser(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Disables the user account with the specified name. Returns <literal>true</literal> if
- successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>changePassword(String name, String password)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Changes the password for the user account with the specified name. Returns
- <literal>true</literal> if successful, or <literal>false</literal> if not.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>isUserEnabled(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns <literal>true</literal> if the specified user account is enabled, or
- <literal>false</literal> if it isn't.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>grantRole(String name, String role)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Grants the specified role to the specified user or role. The role must already exist for it to
- be granted. Returns <literal>true</literal> if the role is successfully granted, or
- <literal>false</literal> if it is already granted to the user.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>revokeRole(String name, String role)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Revokes the specified role from the specified user or role. Returns <literal>true</literal>
- if the specified user is a member of the role and it is successfully revoked, or
- <literal>false</literal> if the user is not a member of the role.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>userExists(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns <literal>true</literal> if the specified user exists, or <literal>false</literal>
- if it doesn't.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>listUsers()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>List</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of all user names, sorted in alpha-numeric order.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>listUsers(String filter)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>List</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of all user names filtered by the specified filter parameter, sorted in alpha-numeric order.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>listRoles()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>List</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of all role names.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>getGrantedRoles(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>List</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of the names of all the roles explicitly granted to the specified user name.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>getImpliedRoles(String name)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>List</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of the names of all the roles implicitly granted to the specified user name.
- Implicitly granted roles include those that are not directly granted to a user, rather they are
- granted to the roles that the user is a member of. For example, is the <literal>admin</literal>
- role is a member of the <literal>user</literal> role, and a user is a member of the <literal>admin</literal>
- role, then the implied roles for the user are both the <literal>admin</literal>, and <literal>user</literal>
- roles.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>authenticate(String name, String password)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Authenticates the specified username and password using the configured Identity Store. Returns
- <literal>true</literal> if successful or <literal>false</literal> if authentication failed.
- Successful authentication implies nothing beyond the return value of the method. It does not
- change the state of the <literal>Identity</literal> component - to perform a proper Seam login the
- <literal>Identity.login()</literal> must be used instead.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>addRoleToGroup(String role, String group)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Adds the specified role as a member of the specified group. Returns true if the operation is successful.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>removeRoleFromGroup(String role, String group)</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- Removes the specified role from the specified group. Returns true if the operation is successful.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>listRoles()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>List</literal>
- </para>
- </entry>
- <entry>
- <para>
- Lists the names of all roles.
- </para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <para>
- Using the Identity Management API requires that the calling user has the appropriate authorization to invoke
- its methods. The following table describes the permission requirements for each of the methods in
- <literal>IdentityManager</literal>. The permission targets listed below are literal String values.
- </para>
-
- <table>
- <title>Identity Management Security Permissions</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Method</para>
- </entry>
- <entry align="center">
- <para>Permission Target</para>
- </entry>
- <entry align="center">
- <para>Permission Action</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <para>
- <literal>createUser()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.user</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>create</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>deleteUser()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.user</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>delete</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>createRole()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.role</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>create</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>deleteRole()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.role</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>delete</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>enableUser()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.user</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>disableUser()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.user</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>changePassword()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.user</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>isUserEnabled()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.user</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>read</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>grantRole()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.user</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>revokeRole()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.user</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>userExists()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.user</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>read</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>listUsers()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.user</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>read</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>listRoles()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.role</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>read</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>addRoleToGroup()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.role</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>removeRoleFromGroup()</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.role</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>update</literal>
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
- The following code listing provides an example set of security rules that grants access to all
- Identity Management-related methods to members of the <literal>admin</literal> role:
- </para>
-
- <programlisting><![CDATA[rule ManageUsers
+}]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section id="security-id_management-jpaidstore">
+ <title>JpaIdentityStore Events</title>
+ <para>
+ When using <literal>JpaIdentityStore</literal> with <literal>IdentityManager</literal>, several events are raised when certain <literal>IdentityManager</literal> methods are invoked.
+ </para>
+ <section>
+ <title>JpaIdentityStore.EVENT_PRE_PERSIST_USER</title>
+ <para>
+ This event is raised in response to calling <literal>IdentityManager.createUser()</literal>. Just before the user entity is persisted to the database, this event is raised to pass the entity instance as an event parameter. The entity will be an instance of the <literal>user-class</literal> configured for <literal>JpaIdentityStore</literal>.
+ </para>
+ <para>
+ An observer can be useful, here, for setting entity field values that are not part of standard <literal>createUser()</literal> functionality.
+ </para>
+ </section>
+
+ <section>
+ <title>JpaIdentityStore.EVENT_USER_CREATED</title>
+ <para>
+ This event is also raised in response to calling <literal>IdentityManager.createUser()</literal>. However, it is raised after the user entity has already been persisted to the database. Like the <literal>EVENT_PRE_PERSIST_USER</literal> event, it also passes the entity instance as an event parameter. It may be useful to observe this event if you need to persist other entities that reference the user entity, such as contact detail records or other user-specific data.
+ </para>
+ </section>
+
+ <section>
+ <title>JpaIdentityStore.EVENT_USER_AUTHENTICATED</title>
+ <para>
+ This event is raised when calling <literal>IdentityManager.authenticate()</literal>. It passes the user entity instance as the event parameter, and is useful for reading additional properties from the user entity being authenticated.
+ </para>
+ </section>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>LdapIdentityStore</title>
+ <para>
+ This identity storage method is designed to work with user records stored in an LDAP directory. It is highly configurable, and allows very flexible directory storage of both users and roles. The following sections describe the configuration options for this identity store, and provide some configuration examples.
+ </para>
+ <section>
+ <title>Configuring LdapIdentityStore</title>
+ <para>
+ The following table describes the properties that can be configured in <filename>components.xml</filename> for <literal>LdapIdentityStore</literal>.
+ </para>
+ <table>
+ <title>LdapIdentityStore Configuration Properties</title>
+ <!-- <?dbhtml table-width="100%" ?>
+ <?dbfo table-width="100%" ?> -->
+
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="1.3*" />
+ <colspec colnum="2" colwidth="1.3*" />
+ <colspec colnum="3" colwidth="1.0*" />
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Property
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Default Value
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Description
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>server-address</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>localhost</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The address of the LDAP server.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>server-port</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>389</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The port number that the LDAP server listens on.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>user-context-DN</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>ou=Person,dc=acme,dc=com</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The Distinguished Name (DN) of the context containing user records.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>user-DN-prefix</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>uid=</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This value is prefixed to the front of the username to locate the user's record.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>user-DN-suffix</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>,ou=Person,dc=acme,dc=com</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This value is appended to the end of the username to locate the user's record.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>role-context-DN</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>ou=Role,dc=acme,dc=com</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The DN of the context containing role records.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>role-DN-prefix</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>cn=</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This value is prefixed to the front of the role name to form the DN that locates the role record.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>role-DN-suffix</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>,ou=Roles,dc=acme,dc=com</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This value is appended to the role name to form the DN that locates the role record.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>bind-DN</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>cn=Manager,dc=acme,dc=com</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This is the context used to bind to the LDAP server.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>bind-credentials</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>secret</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ These are the credentials (the password) used to bind to the LDAP server.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>user-role-attribute</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>roles</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The attribute name of the user record containing the list of roles that the user is a member of.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>role-attribute-is-DN</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>true</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This Boolean property indicates whether the role attribute of the user record is itself a distinguished name.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>user-name-attribute</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>uid</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Indicates the user record attribute containing the username.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>user-password-attribute</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>userPassword</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Indicates the user record attribute containing the user's password.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>first-name-attribute</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>null</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Indicates the user record attribute containing the user's first name.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>last-name-attribute</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>sn</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Indicates the user record attribute containing the user's last name.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>full-name-attribute</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>cn</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Indicates the user record attribute containing the user's full (common) name.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>enabled-attribute</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>null</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Indicates the user record attribute that determines whether the user is enabled.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>role-name-attribute</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>cn</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Indicates the role record attribute containing the name of the role.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>object-class-attribute</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>objectClass</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Indicates the attribute that determines the class of an object in the directory.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>role-object-classes</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>organizationalRole</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ An array of the object classes that new role records should be created as.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>user-object-classes</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>person,uidObject</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ An array of the object classes that new user records should be created as.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+
+ </section>
+
+ <section>
+ <title>LdapIdentityStore Configuration Example</title>
+ <para>
+ The following configuration example shows how <literal>LdapIdentityStore</literal> can be configured for an LDAP directory running on fictional host <literal>directory.mycompany.com</literal>. The users are stored within this directory under the <literal>ou=Person,dc=mycompany,dc=com</literal> context, and are identified by the <literal>uid</literal> attribute (which corresponds to their username). Roles are stored in their own context, <literal>ou=Roles,dc=mycompany,dc=com</literal>, and are referenced from the user's entry via the <literal>roles</literal> attribute. Role entries are identified by their common name (the <literal>cn</literal> attribute), which corresponds to the role name. In this example, users can be disabled by setting the value of their <literal>enabled</literal> attribute to <literal>false</literal>.
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<security:ldap-identity-store
+ server-address="directory.mycompany.com"
+ bind-DN="cn=Manager,dc=mycompany,dc=com"
+ bind-credentials="secret"
+ user-DN-prefix="uid="
+ user-DN-suffix=",ou=Person,dc=mycompany,dc=com"
+ role-DN-prefix="cn="
+ role-DN-suffix=",ou=Roles,dc=mycompany,dc=com"
+ user-context-DN="ou=Person,dc=mycompany,dc=com"
+ role-context-DN="ou=Roles,dc=mycompany,dc=com"
+ user-role-attribute="roles"
+ role-name-attribute="cn"
+ user-object-classes="person,uidObject"
+ enabled-attribute="enabled"
+/>]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Writing your own IdentityStore</title>
+ <para>
+ Writing your own identity store implementation allows you to authenticate and perform identity management operations against security providers that are not supported out of the box by Seam. You only need a single class that implements the <literal>org.jboss.seam.security.management.IdentityStore</literal> interface to achieve this.
+ </para>
+ <para>
+ Refer to the JavaDoc about <literal>IdentityStore</literal> for a description of the methods that must be implemented.
+ </para>
+ </section>
+
+ <section>
+ <title>Authentication with Identity Management</title>
+ <para>
+ If you use Identity Management features in your Seam application, then you do not need to provide an authenticator component (see previous Authentication section<!-- #modify: xref -->) to enable authentication. Simply omit the <literal>authenticator-method</literal> from the <literal>identity</literal> configuration in <literal>components.xml</literal>, and the <literal>SeamLoginModule</literal> will use <literal>IdentityManager</literal> to authenticate your application's users without any special configuration.
+ </para>
+ </section>
+
+ <section>
+ <title>Using IdentityManager</title>
+ <para>
+ Access the <literal>IdentityManager</literal> either by injecting it into your Seam component, like so:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[
+ at In IdentityManager identityManager;]]>
+</programlisting>
+ <para>
+ or, through its static <literal>instance()</literal> method:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[
+IdentityManager identityManager = IdentityManager.instance();]]>
+</programlisting>
+ <para>
+ The following table describes <literal>IdentityManager</literal>'s API methods:
+ </para>
+ <table>
+ <title>Identity Management API</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="2*"></colspec>
+ <colspec colnum="2" colwidth="1*"></colspec>
+ <colspec colnum="3" colwidth="2*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Method
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Returns
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Description
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>createUser(String name, String password)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Creates a new user account, with the specified name and password. Returns <literal>true</literal> if successful; otherwise, returns <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>deleteUser(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Deletes the user account with the specified name. Returns <literal>true</literal> if successful; otherwise, returns <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>createRole(String role)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Creates a new role, with the specified name. Returns <literal>true</literal> if successful; otherwise, returns <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>deleteRole(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Deletes the role with the specified name. Returns <literal>true</literal> if successful; otherwise, returns <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>enableUser(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Enables the user account with the specified name. Accounts that are not enabled cannot authenticate. Returns <literal>true</literal> if successful; otherwise, returns <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>disableUser(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Disables the user account with the specified name. Returns <literal>true</literal> if successful; otherwise, returns <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>changePassword(String name, String password)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Changes the password for the user account with the specified name. Returns <literal>true</literal> if successful; otherwise, returns <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>isUserEnabled(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns <literal>true</literal> if the specified user account is enabled; otherwise, returns <literal>false</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>grantRole(String name, String role)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Grants the specified role to the specified user or role. The role must already exist for it to be granted. Returns <literal>true</literal> if the role is successfully granted, or <literal>false</literal> if the user has already been granted the role.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>revokeRole(String name, String role)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Revokes the specified role from the specified user or role. Returns <literal>true</literal> if the specified user is a member of the role and it is successfully revoked, or <literal>false</literal> if the user is not a member of the role.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>userExists(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns <literal>true</literal> if the specified user exists, or <literal>false</literal> if it does not.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>listUsers()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of all user names, sorted in alpha-numeric order.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>listUsers(String filter)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of all user names filtered by the specified filter parameter, sorted in alpha-numeric order.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>listRoles()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of all role names.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>getGrantedRoles(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of all roles explicitly granted to the specified user name.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>getImpliedRoles(String name)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of all roles implicitly granted to the specified user name. Implicitly granted roles include those that are granted to the roles that the user is a member of, rather than granted directly to the user. For example, if the <literal>admin</literal> role is a member of the <literal>user</literal> role, and a user is a member of the <literal>admin</literal> role, then the implied roles for the user are both the <literal>admin</literal>, and <literal>user</literal> roles.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>authenticate(String name, String password)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Authenticates the specified username and password using the configured Identity Store. Returns <literal>true</literal> if successful or <literal>false</literal> if authentication failed. Successful authentication implies nothing beyond the return value of the method. It does not change the state of the <literal>Identity</literal> component - to perform a proper Seam login the <literal>Identity.login()</literal> must be used instead.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>addRoleToGroup(String role, String group)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Adds the specified role as a member of the specified group. Returns true if the operation is successful.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>removeRoleFromGroup(String role, String group)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Removes the specified role from the specified group. Returns true if the operation is successful.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>listRoles()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>List</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Lists the names of all roles.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ A calling user must have appropriate authorization to invoke methods on the Identity Management API. The following table describes the permission requirements for each of the methods in <literal>IdentityManager</literal>. The permission targets listed below are literal String values.
+ </para>
+ <table>
+ <title>Identity Management Security Permissions</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="2*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="1*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Method
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Permission Target
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Permission Action
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>createUser()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>create</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>deleteUser()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>delete</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>createRole()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.role</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>create</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>deleteRole()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.role</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>delete</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>enableUser()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>disableUser()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>changePassword()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>isUserEnabled()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>read</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>grantRole()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>revokeRole()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>userExists()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>read</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>listUsers()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.user</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>read</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>listRoles()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.role</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>read</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>addRoleToGroup()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.role</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>removeRoleFromGroup()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.role</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>update</literal>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ The following code listing provides an example set of security rules that grants all <literal>admin</literal> role members access to all Identity Management-related methods:
+ </para>
+
+<programlisting><![CDATA[rule ManageUsers
no-loop
activation-group "permissions"
when
@@ -2427,1845 +2151,1447 @@
then
check.grant();
end
-]]></programlisting>
-
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>Error Messages</title>
-
- <para>
- The security API produces a number of default faces messages for various security-related events.
- The following table lists the message keys that can be used to override these messages by specifying
- them in a <literal>message.properties</literal> resource file. To suppress the message, just put the
- key with an empty value in the resource file.
- </para>
-
- <table>
- <title>Security Message Keys</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="2*" />
- <colspec colnum="2" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Message Key</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.loginSuccessful</literal>
- </para>
- </entry>
- <entry>
- <para>
- This message is produced when a user successfully logs in via the security API.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.loginFailed</literal>
- </para>
- </entry>
- <entry>
- <para>
- This message is produced when the login process fails, either because the user provided an
- incorrect username or password, or because authentication failed in some other way.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.NotLoggedIn</literal>
- </para>
- </entry>
- <entry>
- <para>
- This message is produced when a user attempts to perform an action or access a page that requires
- a security check, and the user is not currently authenticated.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.AlreadyLoggedIn</literal>
- </para>
- </entry>
- <entry>
- <para>
- This message is produced when a user that is already authenticated attempts to log in again.
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </sect1>
-
- <sect1>
- <title>Authorization</title>
-
- <para>
- There are a number of authorization mechanisms provided by the Seam Security API for securing access to
- components, component methods, and pages. This section describes each of these. An important thing to
- note is that if you wish to use any of the advanced features (such as rule-based permissions) then
- your <literal>components.xml</literal> may need to be configured to support this - see the Configuration section
- above.
- </para>
-
- <sect2>
- <title>Core concepts</title>
-
- <para>
- Seam Security is built around the premise of users being granted roles and/or permissions, allowing them to
- perform operations that may not otherwise be permissible for users without the necessary security privileges.
- Each of the authorization mechanisms provided by the Seam Security API are built upon this core concept of roles and
- permissions, with an extensible framework providing multiple ways to secure application resources.
- </para>
-
- <sect3>
- <title>What is a role?</title>
-
- <para>
- A role is a <emphasis>group</emphasis>, or <emphasis>type</emphasis>, of user that may have been granted certain
- privileges for performing one or more specific actions within an application. They are simple constructs, consisting
- of just a name such as "admin", "user", "customer", etc. They can be granted either to users (or in some cases to other
- roles), and are used to create logical groups of users for the convenient assignment of specific application privileges.
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-roleclass.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-roleclass.png" align="center"/>
- </imageobject>
- </mediaobject>
- </sect3>
-
- <sect3>
- <title>What is a permission?</title>
-
- <para>
- A permission is a privilege (sometimes once-off) for performing a single, specific action. It is entirely possible to
- build an application using nothing but permissions, however roles offer a higher level of convenience when granting
- privileges to groups of users. They are slightly more complex in structure than roles, essentially consisting of three
- "aspects"; a target, an action, and a recipient. The target of a permission is the object (or an arbitrary name or class)
- for which a particular action is allowed to be performed by a specific recipient (or user). For example, the user "Bob"
- may have permission to delete customer objects. In this case, the permission target may be "customer", the permission
- action would be "delete" and the recipient would be "Bob".
- </para>
-
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-permissionclass.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-permissionclass.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>
- Within this documentation, permissions are generally represented in the form <literal>target:action</literal>
- (omitting the recipient, although in reality one is always required).
- </para>
- </sect3>
-
- </sect2>
-
- <sect2>
- <title>Securing components</title>
-
- <para>
- Let's start by examining the simplest form of authorization, component security, starting with the
- <literal>@Restrict</literal> annotation.
- </para>
-
- <note>
- <title>@Restrict vs Typesafe security annotations</title>
-
- <para>
- While using the <literal>@Restrict</literal> annotation provides a powerful and flexible method for security component methods
- due to its ability to support EL expressions, it is recommended that the typesafe equivalent (described later) be
- used, at least for the compile-time safety it provides.
- </para>
- </note>
-
- <sect3>
- <title>The @Restrict annotation</title>
-
- <para>
- Seam components may be secured either at the method or the class level, using the <literal>@Restrict</literal>
- annotation. If both a method and it's declaring class are annotated with <literal>@Restrict</literal>,
- the method restriction will take precedence (and the class restriction will not apply). If a method
- invocation fails a security check, then an exception will be thrown as per the contract for
- <literal>Identity.checkRestriction()</literal> (see Inline Restrictions). A <literal>@Restrict</literal>
- on just the component class itself is equivalent to adding <literal>@Restrict</literal> to each of its
- methods.
- </para>
-
- <para>
- An empty <literal>@Restrict</literal> implies a permission check of <literal>componentName:methodName</literal>.
- Take for example the following component method:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("account")
+]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Error Messages</title>
+ <para>
+ The security API produces a number of default Faces messages for various security-related events. The following table lists the message keys to specify in a <filename>message.properties</filename> resource file if you want to override the messages. To suppress a message, add the key (with an empty value) to the resource file.
+ </para>
+ <table>
+ <title>Security Message Keys</title>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="1.5*"></colspec>
+ <colspec colnum="2" colwidth="1*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Message Key
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Description
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.loginSuccessful</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This message is produced when a user successfully logs in via the security API.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.loginFailed</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This message is produced when the login process fails, either because the user provided an incorrect username or password, or because authentication failed in some other way.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.NotLoggedIn</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This message is produced when a user attempts to perform an action or access a page that requires a security check, and the user is not currently authenticated.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.AlreadyLoggedIn</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This message is produced when a user that is already authenticated attempts to log in again.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Authorization</title>
+ <para>
+ This section describes the range of authorization mechanisms provided by the Seam Security API for securing access to components, component methods, and pages. If you wish to use any of the advanced features (for example, rule-based permissions), you may need to configure your <filename>components.xml</filename> file — see the Configuration section previous.
+ </para>
+ <section>
+ <title>Core concepts</title>
+ <para>
+ Seam Security operates on the principle that users are granted roles or permissions, or both, which allow them to perform operations that are not permissible for users without the required security privileges. Each authorization mechanism provided by the Seam Security API is built upon this core concept of roles and permissions, with an extensible framework to provide multiple ways to secure application resources.
+ </para>
+ <section>
+ <title>What is a role?</title>
+ <para>
+ A role is a type of user that may have been granted certain privileges for performing one or more specific actions within an application. They are simple constructs, consisting of a name (such as "admin", "user", "customer", etc.) applied to users, or other roles. They are used to create logical user groups so that specific application privileges can be easily assigned.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/security-roleclass.png" format="PNG" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/security-roleclass.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ <section>
+ <title>What is a permission?</title>
+ <para>
+ A permission is a privilege (sometimes once-off) for performing a single, specific action. You can build an application that operates solely on permissions, but roles are more convenient when granting privileges to groups. Permissions are slightly more complex in structure than roles, consisting of three "aspects"; a target, an action, and a recipient. The target of a permission is the object (or an arbitrary name or class) for which a particular action is allowed to be performed by a specific recipient (or user). For example, the user "Bob" may have permission to delete customer objects. In this case, the permission target may be "customer", the permission action would be "delete" and the recipient would be "Bob".
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/security-permissionclass.png" format="PNG" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/security-permissionclass.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ In this documentation, permissions are usually represented in the form <literal>target:action</literal>, omitting the recipient. In reality, a recipient is always required.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Securing components</title>
+ <para>
+ We will start with the simplest form of authorization: component security. First, we will look at the <literal>@Restrict</literal> annotation.
+ </para>
+ <note>
+ <title>@Restrict vs Typesafe security annotations</title>
+ <para>
+ While the <literal>@Restrict</literal> annotation is a powerful and flexible method for security components, it cannot support EL expressions. Therefore, we recommend using the typesafe equivalent (described later in this chapter) for its compile-time safety.
+ </para>
+ </note>
+ <section>
+ <title>The @Restrict annotation</title>
+ <para>
+ Seam components can be secured at either the method or the class level with the <literal>@Restrict</literal> annotation. If both a method and its declaring class are annotated with <literal>@Restrict</literal>, the method restriction will take precedence and the class restriction will not apply. If a method invocation fails a security check, an exception will be thrown as per the contract for <literal>Identity.checkRestriction()</literal>. (See the section following for more information on Inline Restrictions.) Placing <literal>@Restrict</literal> on the component class itself is the equivalent of adding <literal>@Restrict</literal> to each of its methods.
+ </para>
+ <para>
+ An empty <literal>@Restrict</literal> implies a permission check of <literal>componentName:methodName</literal>. Take for example the following component method:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("account")
public class AccountAction {
- @Restrict public void delete() {
- ...
- }
-}]]></programlisting>
-
- <para>
- In this example, the implied permission required to call the <literal>delete()</literal> method is
- <literal>account:delete</literal>. The equivalent of this would be to write
- <literal>@Restrict("#{s:hasPermission('account','delete')}")</literal>. Now let's look at
- another example:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Restrict @Name("account")
+ @Restrict
+ public void delete() {
+ ...
+ }
+}]]>
+</programlisting>
+ <para>
+ In this example, <literal>account:delete</literal> is the implied permission required to call the <literal>delete()</literal> method. This is equivalent to writing <literal>@Restrict("#{s:hasPermission('account','delete')}")</literal>. The following is another example:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Restrict @Name("account")
public class AccountAction {
- public void insert() {
- ...
- }
- @Restrict("#{s:hasRole('admin')}")
- public void delete() {
- ...
- }
-}]]></programlisting>
-
- <para>
- This time, the component class itself is annotated with <literal>@Restrict</literal>. This means that
- any methods without an overriding <literal>@Restrict</literal> annotation require an implicit permission check.
- In the case of this example, the <literal>insert()</literal> method requires a permission of
- <literal>account:insert</literal>, while the <literal>delete()</literal> method requires that the user is a
- member of the <literal>admin</literal> role.
- </para>
-
- <para>
- Before we go any further, let's address the <literal>#{s:hasRole()}</literal> expression seen in the above
- example. Both <literal>s:hasRole</literal> and <literal>s:hasPermission</literal> are EL functions, which
- delegate to the correspondingly named methods of the <literal>Identity</literal> class. These
- functions can be used within any EL expression throughout the entirety of the security API.
- </para>
-
- <para>
- Being an EL expression, the value of the <literal>@Restrict</literal> annotation may reference any objects that
- exist within a Seam context. This is extremely useful when performing permission checks for a specific
- object instance. Look at this example:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("account")
+ public void insert() {
+ ...
+ }
+ @Restrict("#{s:hasRole('admin')}")
+ public void delete() {
+ ...
+ }
+}]]>
+</programlisting>
+ <para>
+ Here, the component class itself is annotated with <literal>@Restrict</literal>. This means that any methods without an overriding <literal>@Restrict</literal> annotation require an implicit permission check. In this case, the <literal>insert()</literal> method requires a permission of <literal>account:insert</literal>, while the <literal>delete()</literal> method requires that the user is a member of the <literal>admin</literal> role.
+ </para>
+ <para>
+ Before we go further, we will address the <literal>#{s:hasRole()}</literal> expression seen in the previous example. <literal>s:hasRole</literal> and <literal>s:hasPermission</literal> are EL functions that delegate to the correspondingly-named methods of the <literal>Identity</literal> class. These functions can be used within any EL expression throughout the entirety of the security API.
+ </para>
+ <para>
+ Being an EL expression, the value of the <literal>@Restrict</literal> annotation may refer to any object within a Seam context. This is extremely useful when checking permissions for a specific object instance. Take the following example:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("account")
public class AccountAction {
- @In Account selectedAccount;
- @Restrict("#{s:hasPermission(selectedAccount,'modify')}")
- public void modify() {
- selectedAccount.modify();
- }
-}]]></programlisting>
+ @In Account selectedAccount;
+ @Restrict("#{s:hasPermission(selectedAccount,'modify')}")
+ public void modify() {
+ selectedAccount.modify();
+ }
+}]]>
+</programlisting>
+ <para>
+ In this example, the <literal>hasPermission()</literal> function call refers to <literal>selectedAccount</literal>. The value of this variable will be looked up from within the Seam context, and passed to the <literal>hasPermission()</literal> method in <literal>Identity</literal>. This will determine whether the user has the required permissions to modify the specified <literal>Account</literal> object.
+ </para>
+ </section>
+
+ <section>
+ <title>Inline restrictions</title>
+ <para>
+ It is sometimes necessary to perform a security check in code, without using the <literal>@Restrict</literal> annotation. To do so, use <literal>Identity.checkRestriction()</literal> to evaluate a security expression, like this:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public void deleteCustomer() {
+ Identity.instance().checkRestriction("#{s:hasPermission(selectedCustomer,
+ 'delete')}");
+}]]>
+</programlisting>
+ <para>
+ If the specified expression does not evaluate to <literal>true</literal>, one of two exceptions occurs. If the user is not logged in, a <exceptionname>NotLoggedInException</exceptionname> is thrown. If the user is logged in, an <exceptionname>AuthorizationException</exceptionname> is thrown.
+ </para>
+ <para>
+ You can also call the <literal>hasRole()</literal> and <literal>hasPermission()</literal> methods directly from Java code:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[if (!Identity.instance().hasRole("admin"))
+ throw new AuthorizationException("Must be admin to perform this action");
- <para>
- The interesting thing to note from this example is the reference to <literal>selectedAccount</literal>
- seen within the <literal>hasPermission()</literal> function call. The value of this variable will be
- looked up from within the Seam context, and passed to the <literal>hasPermission()</literal> method
- in <literal>Identity</literal>, which in this case can then determine if the user has the required
- permission for modifying the specified <literal>Account</literal> object.
- </para>
- </sect3>
-
- <sect3>
- <title>Inline restrictions</title>
- <para>
- Sometimes it might be desirable to perform a security check in code, without using the
- <literal>@Restrict</literal> annotation. In this situation, simply use
- <literal>Identity.checkRestriction()</literal> to evaluate a security expression, like this:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public void deleteCustomer() {
- Identity.instance().checkRestriction("#{s:hasPermission(selectedCustomer,'delete')}");
-}]]></programlisting>
-
- <para>
- If the expression specified doesn't evaluate to <literal>true</literal>, either
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- if the user is not logged in, a <literal>NotLoggedInException</literal>
- exception is thrown or
- </para>
- </listitem>
- <listitem>
- <para>
- if the user is logged in, an <literal>AuthorizationException</literal>
- exception is thrown.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- It is also possible to call the <literal>hasRole()</literal> and <literal>hasPermission()</literal>
- methods directly from Java code:
- </para>
-
- <programlisting role="JAVA"><![CDATA[if (!Identity.instance().hasRole("admin"))
- throw new AuthorizationException("Must be admin to perform this action");
-
if (!Identity.instance().hasPermission("customer", "create"))
- throw new AuthorizationException("You may not create new customers");]]></programlisting>
-
- </sect3>
- </sect2>
-
- <sect2>
- <title>Security in the user interface</title>
-
- <para>
- One indication of a well designed user interface is that the user is not presented with options for
- which they don't have the necessary privileges to use. Seam Security allows conditional rendering of
- either 1) sections of a page or 2) individual controls, based upon the privileges of the user, using
- the very same EL expressions that are used for component security.
- </para>
-
- <para>
- Let's take a look at some examples of interface security. First of all, let's pretend that we have a
- login form that should only be rendered if the user is not already logged in. Using the
- <literal>identity.isLoggedIn()</literal> property, we can write this:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:form class="loginForm" rendered="#{not identity.loggedIn}">]]></programlisting>
-
- <para>
- If the user isn't logged in, then the login form will be rendered - very straight forward so far.
- Now let's pretend there is a menu on the page that contains some actions which should only be accessible
- to users in the <literal>manager</literal> role. Here's one way that these could be written:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:outputLink action="#{reports.listManagerReports}" rendered="#{s:hasRole('manager')}">
- Manager Reports
-</h:outputLink>]]></programlisting>
-
- <para>
- This is also quite straight forward. If the user is not a member of the <literal>manager</literal>
- role, then the outputLink will not be rendered. The <literal>rendered</literal> attribute can
- generally be used on the control itself, or on a surrounding <literal><s:div></literal> or
- <literal><s:span></literal> control.
- </para>
-
- <para>
- Now for something more complex. Let's say you have a <literal>h:dataTable</literal> control on a
- page listing records for which you may or may not wish to render action links depending on the
- user's privileges. The <literal>s:hasPermission</literal> EL function allows us to pass in an
- object parameter which can be used to determine whether the user has the requested permission
- for that object or not. Here's how a dataTable with secured links might look:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:dataTable value="#{clients}" var="cl">
- <h:column>
- <f:facet name="header">Name</f:facet>
- #{cl.name}
- </h:column>
- <h:column>
- <f:facet name="header">City</f:facet>
- #{cl.city}
- </h:column>
- <h:column>
- <f:facet name="header">Action</f:facet>
- <s:link value="Modify Client" action="#{clientAction.modify}"
- rendered="#{s:hasPermission(cl,'modify')"/>
- <s:link value="Delete Client" action="#{clientAction.delete}"
- rendered="#{s:hasPermission(cl,'delete')"/>
- </h:column>
-</h:dataTable>]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Securing pages</title>
- <para>
- Page security requires that the application is using a <literal>pages.xml</literal> file, however is
- extremely simple to configure. Simply include a <literal><restrict/></literal> element within
- the <literal>page</literal> elements that you wish to secure. If no explicit restriction is specified
- by the <literal>restrict</literal> element, an implied permission of <literal>/viewId.xhtml:render</literal>
- will be checked when the page is accessed via a non-faces (GET) request, and a permission of
- <literal>/viewId.xhtml:restore</literal> will be required when any JSF postback (form submission) originates
- from the page. Otherwise, the specified restriction will be evaluated as a standard security expression.
- Here's a couple of examples:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/settings.xhtml">
- <restrict/>
-</page>]]></programlisting>
-
- <para>
- This page has an implied permission of <literal>/settings.xhtml:render</literal> required for non-faces
- requests and an implied permission of <literal>/settings.xhtml:restore</literal> for faces requests.
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/reports.xhtml">
- <restrict>#{s:hasRole('admin')}</restrict>
-</page>]]></programlisting>
-
- <para>
- Both faces and non-faces requests to this page require that the user is a member of the
- <literal>admin</literal> role.
- </para>
-
- </sect2>
-
- <sect2>
- <title>Securing Entities</title>
-
- <para>
- Seam security also makes it possible to apply security restrictions to read, insert, update and
- delete actions for entities.
- </para>
-
- <para>
- To secure all actions for an entity class, add a <literal>@Restrict</literal> annotation on the class
- itself:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Entity
+ throw new AuthorizationException("You may not create new customers");]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Security in the user interface</title>
+ <para>
+ A well-designed interface does not present a user with options they are not permitted to use. Seam Security allows conditional rendering of page sections or individual controls based on user privileges, using the same EL expressions that are used for component security.
+ </para>
+ <para>
+ In this section, we will go through some examples of interface security. Say we have a login form that we want rendered only if the user is not already logged in. We can write the following with the <literal>identity.isLoggedIn()</literal> property:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:form class="loginForm" rendered="#{not identity.loggedIn}">]]>
+</programlisting>
+ <para>
+ If the user is not logged in, the login form will be rendered — very straightforward. Say we also have a menu on this page, and we want some actions to be accessed only by users in the <literal>manager</literal> role. One way you could write this is the following:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:outputLink action="#{reports.listManagerReports}"
+ rendered="#{s:hasRole('manager')}"> Manager Reports
+</h:outputLink>]]>
+</programlisting>
+ <para>
+ This, too, is straightforward — if the user is not a member of the <literal>manager</literal> role, the outputLink will not be rendered. The <literal>rendered</literal> attribute can generally be used on the control itself, or on a surrounding <literal><![CDATA[<s:div>]]></literal> or <literal><![CDATA[<s:span>]]></literal> control.
+ </para>
+ <para>
+ A more complex example of conditional rendering might be the following situation: say you have a <literal>h:dataTable</literal> control on a page, and you want to render action links on its records only for users with certain privileges. The <literal>s:hasPermission</literal> EL function lets us use an object parameter to determine whether the user has the necessary permission for that object. A dataTable with secured links might look like this:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:dataTable value="#{clients}" var="cl">
+ <h:column>
+ <f:facet name="header">Name</f:facet>
+ #{cl.name}
+ </h:column>
+ <h:column>
+ <f:facet name="header">City</f:facet>
+ #{cl.city}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Action</f:facet>
+ <s:link value="Modify Client" action="#{clientAction.modify}"
+ rendered="#{s:hasPermission(cl,'modify')"/>
+ <s:link value="Delete Client" action="#{clientAction.delete}"
+ rendered="#{s:hasPermission(cl,'delete')"/>
+ </h:column>
+</h:dataTable>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Securing pages</title>
+ <para>
+ To use page security, you will need a <filename>pages.xml</filename> file. Page security is easy to configure: simply include a <literal><![CDATA[<restrict/>]]></literal> element in the <literal>page</literal> elements that you want to secure. If no explicit restriction is specified in the <literal>restrict</literal> element, access via a non-Faces (GET) request requires an implied <literal>/viewId.xhtml:render</literal> permission, and <literal>/viewId.xhtml:restore</literal> permission is required when any JSF postback (form submission) originates from the page. Otherwise, the specified restriction will be evaluated as a standard security expression. Some examples are:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/settings.xhtml">
+ <restrict/>
+</page>]]>
+</programlisting>
+ <para>
+ This page requires an implied permission of <literal>/settings.xhtml:render</literal> for non-Faces requests, and an implied permission of <literal>/settings.xhtml:restore</literal> for Faces requests.
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/reports.xhtml">
+ <restrict>#{s:hasRole('admin')}</restrict>
+</page>]]>
+</programlisting>
+ <para>
+ Both Faces and non-Faces requests to this page require that the user is a member of the <literal>admin</literal> role.
+ </para>
+ </section>
+
+ <section>
+ <title>Securing Entities</title>
+ <para>
+ Seam Security also lets you apply security restrictions to certain actions (read, insert, update, and delete) for entities.
+ </para>
+ <para>
+ To secure all actions for an entity class, add a <literal>@Restrict</literal> annotation on the class itself:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Entity
@Name("customer")
@Restrict
public class Customer {
...
-}]]></programlisting>
-
- <para>
- If no expression is specified in the <literal>@Restrict</literal> annotation, the default security check
- that is performed is a permission check of <literal>entity:action</literal>, where the permission target
- is the entity instance, and the <literal>action</literal> is either <literal>read</literal>, <literal>insert</literal>,
- <literal>update</literal> or <literal>delete</literal>.
- </para>
-
- <para>
- It is also possible to only restrict certain actions, by placing a <literal>@Restrict</literal> annotation
- on the relevent entity lifecycle method (annotated as follows):
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- <literal>@PostLoad</literal> - Called after an entity instance is loaded from the database. Use this
- method to configure a <literal>read</literal> permission.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>@PrePersist</literal> - Called before a new instance of the entity is inserted. Use this method
- to configure an <literal>insert</literal> permission.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>@PreUpdate</literal> - Called before an entity is updated. Use this method
- to configure an <literal>update</literal> permission.
- </para>
- </listitem>
- <listitem>
- <para>
- <literal>@PreRemove</literal> - Called before an entity is deleted. Use this method
- to configure a <literal>delete</literal> permission.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Here's an example of how an entity would be configured to perform a security check for any <literal>insert</literal>
- operations. Please note that the method is not required to do anything, the only important thing in regard to
- security is how it is annotated:
- </para>
-
- <programlisting role="JAVA"><![CDATA[
- @PrePersist @Restrict
- public void prePersist() {}
- ]]></programlisting>
-
- <note>
- <title>Using <literal>/META-INF/orm.xml</literal></title>
-
-
- <para>
- You can also specify the call back method in <literal>/META-INF/orm.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+}]]>
+</programlisting>
+ <para>
+ If no expression is specified in the <literal>@Restrict</literal> annotation, the default action is a permission check of <literal>entity:action</literal>, where the permission target is the entity instance, and the <literal>action</literal> is either <literal>read</literal>, <literal>insert</literal>, <literal>update</literal> or <literal>delete</literal>.
+ </para>
+ <para>
+ You can also restrict certain actions by placing a <literal>@Restrict</literal> annotation on the relevant entity lifecycle method (annotated as follows):
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>@PostLoad</literal> — Called after an entity instance is loaded from the database. Use this method to configure a <literal>read</literal> permission.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>@PrePersist</literal> — Called before a new instance of the entity is inserted. Use this method to configure an <literal>insert</literal> permission.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>@PreUpdate</literal> — Called before an entity is updated. Use this method to configure an <literal>update</literal> permission.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>@PreRemove</literal> — Called before an entity is deleted. Use this method to configure a <literal>delete</literal> permission.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ The following example shows how an entity can be configured to perform a security check for any <literal>insert</literal> operations. Note that the method need not perform any action; it is only important that it be annotated correctly:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@PrePersist
+ at Restrict
+public void prePersist() {} ]]>
+</programlisting>
+ <note>
+ <title>Using <literal>/META-INF/orm.xml</literal></title>
+ <para>
+ You can also specify the callback method in <literal>/META-INF/orm.xml</literal>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"
- version="1.0">
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/persistence/orm
+ http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"
+ version="1.0">
- <entity class="Customer">
- <pre-persist method-name="prePersist" />
- </entity>
+ <entity class="Customer">
+ <pre-persist method-name="prePersist" />
+ </entity>
-</entity-mappings>]]></programlisting>
-
- <para>
- Of course, you still need to annotate the <literal>prePersist()</literal>
- method on <literal>Customer</literal> with <literal>@Restrict</literal>
- </para>
- </note>
-
- <para>
- And here's an example of an entity permission rule that checks if the authenticated user is allowed to insert
- a new <literal>MemberBlog</literal> record (from the seamspace example). The entity for which the security
- check is being made is automatically inserted into the working memory (in this case <literal>MemberBlog</literal>):
- </para>
-
- <programlisting><![CDATA[rule InsertMemberBlog
+</entity-mappings>]]>
+</programlisting>
+ <para>
+ You will still need to annotate the <literal>prePersist()</literal> method on <literal>Customer</literal> with <literal>@Restrict</literal>.
+ </para>
+ </note>
+ <para>
+ The following configuration is based on the Seamspace example, and checks if the authenticated user has permission to insert a new <literal>MemberBlog</literal> record. The entity being checked is automatically inserted into the working memory (in this case, <literal>MemberBlog</literal>):
+ </para>
+
+<programlisting><![CDATA[rule InsertMemberBlog
no-loop
activation-group "permissions"
when
principal: Principal()
- memberBlog: MemberBlog(member : member -> (member.getUsername().equals(principal.getName())))
- check: PermissionCheck(target == memberBlog, action == "insert", granted == false)
+ memberBlog: MemberBlog(member : member ->
+ (member.getUsername().equals(principal.getName())))
+ check: PermissionCheck(target == memberBlog,
+ action == "insert", granted == false)
then
check.grant();
-end;]]></programlisting>
-
- <para>
- This rule will grant the permission <literal>memberBlog:insert</literal> if the currently authenticated
- user (indicated by the <literal>Principal</literal> fact) has the same name as the member for which the
- blog entry is being created. The "<literal>principal: Principal()</literal>" structure that can be seen in the
- example code is a variable binding - it binds the instance of the <literal>Principal</literal> object from the
- working memory (placed there during authentication) and assigns it to a variable called <literal>principal</literal>.
- Variable bindings allow the value to be referred to in other places, such as the following line which compares the
- member's username to the <literal>Principal</literal> name. For more details, please refer to the JBoss Rules documentation.
- </para>
-
- <para>
- Finally, we need to install a listener class that integrates Seam security with
- your JPA provider.
- </para>
-
- <sect3>
- <title>Entity security with JPA</title>
-
- <para>
- Security checks for EJB3 entity beans are performed with an <literal>EntityListener</literal>.
- You can install this listener by using the following <literal>META-INF/orm.xml</literal> file:
- </para>
-
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+end;]]>
+</programlisting>
+ <para>
+ This rule grants the permission <literal>memberBlog:insert</literal> if the name of the currently authenticated user (indicated by the <literal>Principal</literal> fact) matches that of the member for whom the blog entry is being created. The <literal>principal: Principal()</literal> structure is a variable binding. It binds the instance of the <literal>Principal</literal> object placed in the working memory during authentication, and assigns it to a variable called <literal>principal</literal>. Variable bindings let the variable be referenced in other places, such as the following line, which compares the member name to the <literal>Principal</literal> name. For further details, refer to the JBoss Rules documentation. <!-- #modify: linkme? -->
+ </para>
+ <para>
+ Finally, install a listener class to integrate Seam Security with your JPA provider.
+ </para>
+ <section>
+ <title>Entity security with JPA</title>
+ <para>
+ Security checks for EJB3 entity beans are performed with an <literal>EntityListener</literal>. Install this listener with the following <literal>META-INF/orm.xml</literal> file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<entity-mappings xmlns="http://java.sun.com/xml/ns/persistence/orm"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/persistence/orm http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/persistence/orm
+ http://java.sun.com/xml/ns/persistence/orm_1_0.xsd"
version="1.0">
- <persistence-unit-metadata>
- <persistence-unit-defaults>
- <entity-listeners>
- <entity-listener class="org.jboss.seam.security.EntitySecurityListener"/>
- </entity-listeners>
- </persistence-unit-defaults>
- </persistence-unit-metadata>
+ <persistence-unit-metadata>
+ <persistence-unit-defaults>
+ <entity-listeners>
+ <entity-listener
+ class="org.jboss.seam.security.EntitySecurityListener"/>
+ </entity-listeners>
+ </persistence-unit-defaults>
+ </persistence-unit-metadata>
-</entity-mappings>]]></programlisting>
-
- </sect3>
-
- <sect3>
- <title>Entity security with a Managed Hibernate Session</title>
-
- <para>
- If you are using a Hibernate <literal>SessionFactory</literal> configured via Seam,
- and are using annotations, or <literal>orm.xml</literal>, then you don't
- need to do anything special to use entity security.
- </para>
-
- </sect3>
-
- </sect2>
-
- <sect2>
- <title>Typesafe Permission Annotations</title>
-
- <para>
- Seam provides a number of annotations that may be used as an alternative to <literal>@Restrict</literal>, which have
- the added advantage of providing compile-time safety as they don't support arbitrary EL expressions in the same way
- that <literal>@Restrict</literal> does.
- </para>
-
- <para>
- Out of the box, Seam comes with annotations for standard CRUD-based permissions, however it is a simple matter to
- add your own. The following annotations are provided in the <literal>org.jboss.seam.annotations.security</literal> package:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>@Insert</para>
- </listitem>
- <listitem>
- <para>@Read</para>
- </listitem>
- <listitem>
- <para>@Update</para>
- </listitem>
- <listitem>
- <para>@Delete</para>
- </listitem>
- </itemizedlist>
-
- <para>
- To use these annotations, simply place them on the method or parameter for which you wish to perform a security check.
- If placed on a method, then they should specify a target class for which the permission will be checked. Take the
- following example:
- </para>
-
- <programlisting><![CDATA[ @Insert(Customer.class)
- public void createCustomer() {
- ...
- }]]></programlisting>
-
- <para>
- In this example, a permission check will be performed for the user to ensure that they have the rights to create
- new <literal>Customer</literal> objects. The target of the permission check will be <literal>Customer.class</literal>
- (the actual <literal>java.lang.Class</literal> instance itself), and the action is the lower case representation of the
- annotation name, which in this example is <literal>insert</literal>.
- </para>
-
- <para>
- It is also possible to annotate the parameters of a component method in the same way. If this is done, then it is
- not required to specify a permission target (as the parameter value itself will be the target of the permission check):
- </para>
-
- <programlisting><![CDATA[ public void updateCustomer(@Update Customer customer) {
- ...
- }]]></programlisting>
-
- <para>
- To create your own security annotation, you simply need to annotate it with <literal>@PermissionCheck</literal>, for example:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Target({METHOD, PARAMETER})
+</entity-mappings>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Entity security with a Managed Hibernate Session</title>
+ <para>
+ If you use a Hibernate <literal>SessionFactory</literal> configured with Seam, and use annotations or <filename>orm.xml</filename>, you do not need to make any changes to use entity security.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Typesafe Permission Annotations</title>
+ <para>
+ Seam provides a number of alternative annotations to <literal>@Restrict</literal>. These support arbitrary EL expressions differently, which gives them additional compile-time safety.
+ </para>
+ <para>
+ Seam comes with a set of annotations for standard CRUD-based permissions. The following annotations are provided in the <literal>org.jboss.seam.annotations.security</literal> package:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ @Insert
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ @Read
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ @Update
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ @Delete
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ To use these annotations, place them on the method or parameter for which you wish to perform a security check. When placed on a method, they specify a target class for which the permission will be checked. Take the following example:
+ </para>
+
+<programlisting><![CDATA[
+ at Insert(Customer.class)
+public void createCustomer() { ... }]]>
+</programlisting>
+ <para>
+ Here, a permission check will be performed for the user to ensure that they have permission to create new <literal>Customer</literal> objects. The target of the permission check is <literal>Customer.class</literal> (the actual <literal>java.lang.Class</literal> instance itself), and the action is the lower case representation of the annotation name, which in this example is <literal>insert</literal>.
+ </para>
+ <para>
+ You can annotate a component method's parameters in the same way, as follows. If you do this, you need not specify a permission target, since the parameter value itself will be the target of the permission check.
+ </para>
+
+<programlisting><![CDATA[
+public void updateCustomer(@Update Customer customer) {
+ ...
+}]]>
+</programlisting>
+ <para>
+ To create your own security annotation, just annotate it with <literal>@PermissionCheck</literal>. For example:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Target({METHOD, PARAMETER})
@Documented
@Retention(RUNTIME)
@Inherited
@PermissionCheck
public @interface Promote {
- Class value() default void.class;
-}]]></programlisting>
-
- <para>
- If you wish to override the default permisison action name (which is the lower case version of the annotation name) with
- another value, you can specify it within the <literal>@PermissionCheck</literal> annotation:
- </para>
-
- <programlisting><![CDATA[@PermissionCheck("upgrade")]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Typesafe Role Annotations</title>
-
- <para>
- In addition to supporting typesafe permission annotation, Seam Security also provides typesafe role annotations that
- allow you to restrict access to component methods based on the role memberships of the currently authenticated user.
- Seam provides one such annotation out of the box, <literal>org.jboss.seam.annotations.security.Admin</literal>, used
- to restrict access to a method to users that are a member of the <literal>admin</literal> role (so long as your
- own application supports such a role). To create your own role annotations, simply meta-annotate them with
- <literal>org.jboss.seam.annotations.security.RoleCheck</literal>, like in the following example:
- </para>
-
- <programlisting><![CDATA[@Target({METHOD})
+ Class value() default void.class;
+}]]>
+</programlisting>
+ <para>
+ If you wish to override the default permission action name (the lower case version of the annotation name) with another value, you can specify this within the <literal>@PermissionCheck</literal> annotation:
+ </para>
+
+<programlisting><![CDATA[@PermissionCheck("upgrade")]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Typesafe Role Annotations</title>
+ <para>
+ In addition to typsesafe permission annotation support, Seam Security provides typesafe role annotations that let you restrict access to component methods based on the role memberships of the currently authenticated user. Seam provides one such annotation (<literal>org.jboss.seam.annotations.security.Admin</literal>) out of the box. This restricts access of a particular method to users that belong to the <literal>admin</literal> role, as long as such a role is supported by your application. To create your own role annotations, meta-annotate them with <literal>org.jboss.seam.annotations.security.RoleCheck</literal> as in the following example:
+ </para>
+
+<programlisting><![CDATA[@Target({METHOD})
@Documented
@Retention(RUNTIME)
@Inherited
@RoleCheck
-public @interface User {
-}]]></programlisting>
-
- <para>
- Any methods subsequently annotated with the <literal>@User</literal> annotation as shown in the above example
- will be automatically intercepted and the user checked for the membership of the corresponding role name
- (which is the lower case version of the annotation name, in this case <literal>user</literal>).
- </para>
-
- </sect2>
-
- <sect2>
- <title>The Permission Authorization Model</title>
-
- <para>
- Seam Security provides an extensible framework for resolving application permissions. The following class diagram
- shows an overview of the main components of the permission framework:
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-permission-classdiagram.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-permission-classdiagram.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>
- The relevant classes are explained in more detail in the following sections.
- </para>
-
- <sect3>
- <title>PermissionResolver</title>
-
- <para>
- This is actually an interface, which provides methods for resolving individual object permissions. Seam provides
- the following built-in <literal>PermissionResolver</literal> implementations, which are described in more detail later
- in the chapter:
- </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>RuleBasedPermissionResolver</literal> - This permission resolver uses Drools to resolve rule-based
- permission checks.</para>
- </listitem>
- <listitem>
- <para><literal>PersistentPermissionResolver</literal> - This permission resolver stores object permissions in a
- persistent store, such as a relational database.</para>
- </listitem>
- </itemizedlist>
-
- <sect4>
- <title>Writing your own PermissionResolver</title>
-
- <para>
- It is very simple to implement your own permission resolver. The <literal>PermissionResolver</literal>
- interface defines only two methods that must be implemented, as shown by the following table. By deploying
- your own <literal>PermissionResolver</literal> implementation in your Seam project, it will be automatically
- scanned during deployment and registered with the default <literal>ResolverChain</literal>.
- </para>
-
- <table>
- <title>PermissionResolver interface</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="2*" />
- <colspec colnum="2" colwidth="3*" />
- <colspec colnum="3" colwidth="3*" />
- <colspec colnum="4" colwidth="4*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Return type</para>
- </entry>
- <entry align="center">
- <para>Method</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>hasPermission(Object target, String action)</literal>
- </para>
- </entry>
- <entry>
- <para>
- This method must resolve whether the currently authenticated user (obtained via a call to
- <literal>Identity.getPrincipal()</literal>) has the permission specified by the <literal>target</literal>
- and <literal>action</literal> parameters. It should return <literal>true</literal> if the user has
- the permission, or <literal>false</literal> if they don't.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>void</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>filterSetByAction(Set<Object> targets, String action)</literal>
- </para>
- </entry>
- <entry>
- <para>
- This method should remove any objects from the specified set, that would
- return <literal>true</literal> if passed to the <literal>hasPermission()</literal> method with the
- same <literal>action</literal> parameter value.
- </para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <note>
- <para>
- As they are cached in the user's session, any custom <literal>PermissionResolver</literal>
- implementations must adhere to a couple of restrictions. Firstly, they may not contain any
- state that is finer-grained than session scope (and the scope of the component itself should
- either be application or session). Secondly, they must not use dependency
- injection as they may be accessed from multiple threads simultaneously. In fact, for
- performance reasons it is recommended that they are annotated with
- <literal>@BypassInterceptors</literal> to bypass Seam's interceptor stack altogether.
- </para>
- </note>
-
- </sect4>
- </sect3>
-
- <sect3>
- <title>ResolverChain</title>
-
- <para>
- A <literal>ResolverChain</literal> contains an ordered list of <literal>PermissionResolver</literal>s, for the
- purpose of resolving object permissions for a particular object class or permission target.
- </para>
-
- <para>
- The default <literal>ResolverChain</literal> consists of all permission resolvers discovered during
- application deployment. The <literal>org.jboss.seam.security.defaultResolverChainCreated</literal>
- event is raised (and the <literal>ResolverChain</literal> instance passed as an event parameter)
- when the default <literal>ResolverChain</literal> is created. This allows additional resolvers that
- for some reason were not discovered during deployment to be added, or for resolvers that are in the
- chain to be re-ordered or removed.
- </para>
-
- <para>
- The following sequence diagram shows the interaction between the components of the permission framework during a
- permission check (explanation follows). A permission check can originate from a number of possible sources,
- for example - the security interceptor, the <literal>s:hasPermission</literal> EL function, or via an API
- call to <literal>Identity.checkPermission</literal>:
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/security-permission-sequence.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/security-permission-sequence.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <itemizedlist>
- <listitem>
- <para>
- 1. A permission check is initiated somewhere (either in code or via an EL
- expression) resulting in a call to <literal>Identity.hasPermission()</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- 1.1. <literal>Identity</literal> invokes
- <literal>PermissionMapper.resolvePermission()</literal>, passing in the
- permission to be resolved.
- </para>
- </listitem>
- <listitem>
- <para>
- 1.1.1. <literal>PermissionMapper</literal> maintains a <literal>Map</literal> of
- <literal>ResolverChain</literal> instances, keyed by class. It uses this map
- to locate the correct <literal>ResolverChain</literal> for the permission's
- target object. Once it has the correct <literal>ResolverChain</literal>, it
- retrieves the list of <literal>PermissionResolver</literal>s it contains via
- a call to <literal>ResolverChain.getResolvers()</literal>.
- </para>
- </listitem>
- <listitem>
- <para>
- 1.1.2. For each <literal>PermissionResolver</literal> in the <literal>ResolverChain</literal>,
- the <literal>PermissionMapper</literal> invokes its <literal>hasPermission()</literal> method,
- passing in the permission instance to be checked. If any of the <literal>PermissionResolver</literal>s
- return <literal>true</literal>, then the permission check has succeeded and the
- <literal>PermissionMapper</literal> also returns <literal>true</literal> to <literal>Identity</literal>.
- If none of the <literal>PermissionResolver</literal>s return true, then the permission check
- has failed.
- </para>
- </listitem>
- </itemizedlist>
- </sect3>
-
- </sect2>
-
- <sect2>
- <title>RuleBasedPermissionResolver</title>
-
- <para>
- One of the built-in permission resolvers provided by Seam, <literal>RuleBasedPermissionResolver</literal>
- allows permissions to be evaluated based on a set of Drools (JBoss Rules) security rules. A couple of the
- advantages of using a rule engine are 1) a centralized location for the business logic that is used to
- evaluate user permissions, and 2) speed - Drools uses very efficient algorithms for evaluating large
- numbers of complex rules involving multiple conditions.
- </para>
-
- <sect3>
- <title>Requirements</title>
-
- <para>
- If using the rule-based permission features provided by Seam Security, the following jar files are required by Drools
- to be distributed with your project:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>drools-api.jar</para>
- </listitem>
- <listitem>
- <para>drools-compiler.jar</para>
- </listitem>
- <listitem>
- <para>drools-core.jar</para>
- </listitem>
- <listitem>
- <para>janino.jar</para>
- </listitem>
- <listitem>
- <para>antlr-runtime.jar</para>
- </listitem>
- <listitem>
- <para>mvel2.jar</para>
- </listitem>
- </itemizedlist>
-
- </sect3>
-
- <sect3>
- <title>Configuration</title>
-
- <para>
- The configuration for <literal>RuleBasedPermissionResolver</literal> requires that a Drools rule base is first
- configured in <literal>components.xml</literal>. By default, it expects that the rule base is named
- <literal>securityRules</literal>, as per the following example:
- </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:core="http://jboss.com/products/seam/core"
- xmlns:security="http://jboss.com/products/seam/security"
- xmlns:drools="http://jboss.com/products/seam/drools"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation=
- "http://jboss.com/products/seam/core http://jboss.com/products/seam/core-2.2.xsd
- http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.2.xsd
- http://jboss.com/products/seam/drools http://jboss.com/products/seam/drools-2.2.xsd
- http://jboss.com/products/seam/security http://jboss.com/products/seam/security-2.2.xsd">
+public @interface User { }]]>
+</programlisting>
+ <para>
+ Any methods subsequently annotated with the <literal>@User</literal> annotation will be automatically intercepted. The user will be checked for membership of the corresponding role name (the lower case version of the annotation name, in this case <literal>user</literal>).
+ </para>
+ </section>
+
+ <section>
+ <title>The Permission Authorization Model</title>
+ <para>
+ Seam Security provides an extensible framework for resolving application permissions. The following class diagram shows an overview of the main components of the permission framework:
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/security-permission-classdiagram.png" format="PNG" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/security-permission-classdiagram.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ The relevant classes are explained in more detail in the following sections.
+ </para>
+ <section>
+ <title>PermissionResolver</title>
+ <para>
+ An interface that provides methods for resolving individual object permissions. Seam provides the following built-in <literal>PermissionResolver</literal> implementations, which are described in greater detail later in the chapter:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>RuleBasedPermissionResolver</literal> — Resolves rule-based permission checks with Drools.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>PersistentPermissionResolver</literal> — Stores object permissions in a permanent store, such as a relational database.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Writing your own PermissionResolver</title>
+ <para>
+ Implementing your own permission resolver is simple. The <literal>PermissionResolver</literal> interface defines two methods that must be implemented, as seen in the following table. If your <literal>PermissionResolver</literal> is deployed in your Seam project, it will be scanned automatically during deployment and registered with the default <literal>ResolverChain</literal>.
+ </para>
+ <table>
+ <title>PermissionResolver interface</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="2*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Return type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Method
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Description
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>hasPermission(Object target, String action)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This method resolves whether the currently authenticated user (obtained via a call to <literal>Identity.getPrincipal()</literal>) has the permission specified by the <literal>target</literal> and <literal>action</literal> parameters. It returns <literal>true</literal> if the user has the specified permission, or <literal>false</literal> if they do not.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>void</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>filterSetByAction(Set<![CDATA[<Object>]]> targets, String action)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This method removes any objects from the specified set that would return <literal>true</literal> if passed to the <literal>hasPermission()</literal> method with the same <literal>action</literal> parameter value.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <note>
+ <para>
+ Because they are cached in the user's session, any custom <literal>PermissionResolver</literal> implementations must adhere to several restrictions. Firstly, they cannot contain any state that is more fine-grained than the session scope, and the component itself should be either application- or session-scoped. Secondly, they must not use dependency injection, as they may be accessed from multiple threads simultaneously. For optimal performance, we recommend annotating with <literal>@BypassInterceptors</literal> to bypass Seam's interceptor stack altogether.
+ </para>
+ </note>
+ </section>
+
+ </section>
+
+ <section>
+ <title>ResolverChain</title>
+ <para>
+ A <literal>ResolverChain</literal> contains an ordered list of <literal>PermissionResolver</literal>s, to resolve object permissions for a particular object class or permission target.
+ </para>
+ <para>
+ The default <literal>ResolverChain</literal> consists of all permission resolvers discovered during application deployment. The <literal>org.jboss.seam.security.defaultResolverChainCreated</literal> event is raised (and the <literal>ResolverChain</literal> instance passed as an event parameter) when the default <literal>ResolverChain</literal> is created. This allows additional resolvers that were not discovered during deployment to be added, or for resolvers that are in the chain to be re-ordered or removed.
+ </para>
+ <para>
+ The following sequence diagram shows the interaction between the components of the permission framework during a permission check. A permission check can originate from a number of possible sources: the security interceptor, the <literal>s:hasPermission</literal> EL function, or via an API call to <literal>Identity.checkPermission</literal>:
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/security-permission-sequence.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/security-permission-sequence.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <!-- #modify: FIX THAT DIAGRAM, IT IS RETARDED. --> <itemizedlist>
+ <listitem>
+ <para>
+ 1. A permission check is initiated (either in code or via an EL expression), resulting in a call to <literal>Identity.hasPermission()</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 1.1. <literal>Identity</literal> invokes <literal>PermissionMapper.resolvePermission()</literal>, passing in the permission to be resolved.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 1.1.1. <literal>PermissionMapper</literal> maintains a <literal>Map</literal> of <literal>ResolverChain</literal> instances, keyed by class. It uses this map to locate the correct <literal>ResolverChain</literal> for the permission's target object. Once it has the correct <literal>ResolverChain</literal>, it retrieves the list of <literal>PermissionResolver</literal>s it contains by calling <literal>ResolverChain.getResolvers()</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ 1.1.2. For each <literal>PermissionResolver</literal> in the <literal>ResolverChain</literal>, the <literal>PermissionMapper</literal> invokes its <literal>hasPermission()</literal> method, passing in the permission instance to be checked. If the <literal>PermissionResolver</literal>s return <literal>true</literal>, the permission check has succeeded and the <literal>PermissionMapper</literal> also returns <literal>true</literal> to <literal>Identity</literal>. If none of the <literal>PermissionResolver</literal>s return <literal>true</literal>, then the permission check has failed.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ </section>
+
+ <section>
+ <title>RuleBasedPermissionResolver</title>
+ <para>
+ One of the built-in permission resolvers provided by Seam. This evaluates permissions based on a set of Drools (JBoss Rules) security rules. Some advantages to the rule engine are a centralized location for the business logic used to evaluate user permissions, and speed — Drools algorithms are very efficient for evaluating large numbers of complex rules involving multiple conditions.
+ </para>
+ <section>
+ <title>Requirements</title>
+ <para>
+ If you want to use the rule-based permission features provided by Seam Security, Drools requires the following <filename>JAR</filename> files to be distributed with your project:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>drools-api.jar</para>
+ </listitem>
+ <listitem>
+ <para>drools-compiler.jar</para>
+ </listitem>
+ <listitem>
+ <para>drools-core.jar</para>
+ </listitem>
+ <listitem>
+ <para>janino.jar</para>
+ </listitem>
+ <listitem>
+ <para>antlr-runtime.jar</para>
+ </listitem>
+ <listitem>
+ <para>mvel2.jar</para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Configuration</title>
+ <para>
+ The configuration for <literal>RuleBasedPermissionResolver</literal> requires that a Drools rule base is first configured in <filename>components.xml</filename>. By default, it expects the rule base to be named <literal>securityRules</literal>, as per the following example:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:core="http://jboss.com/products/seam/core"
+ xmlns:security="http://jboss.com/products/seam/security"
+ xmlns:drools="http://jboss.com/products/seam/drools"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation=
+ "http://jboss.com/products/seam/core
+ http://jboss.com/products/seam/core-2.2.xsd
+ http://jboss.com/products/seam/components
+ http://jboss.com/products/seam/components-2.2.xsd
+ http://jboss.com/products/seam/drools
+ http://jboss.com/products/seam/drools-2.2.xsd
+ http://jboss.com/products/seam/security
+ http://jboss.com/products/seam/security-2.2.xsd">
- <drools:rule-base name="securityRules">
- <drools:rule-files>
- <value>/META-INF/security.drl</value>
- </drools:rule-files>
- </drools:rule-base>
+ <drools:rule-base name="securityRules">
+ <drools:rule-files>
+ <value>/META-INF/security.drl</value>
+ </drools:rule-files>
+ </drools:rule-base>
- </components>]]></programlisting>
+</components>]]>
+</programlisting>
+ <para>
+ The default rule base name can be overridden by specifying the <literal>security-rules</literal> property for <literal>RuleBasedPermissionResolver</literal>:
+ </para>
+
+<programlisting><![CDATA[
+<security:rule-based-permission-resolver
+ security-rules="#{prodSecurityRules}"/>]]>
+</programlisting>
+ <para>
+ Once the <literal>RuleBase</literal> component is configured, you must write the security rules.
+ </para>
+ </section>
+
+ <section>
+ <title>Writing Security Rules</title>
+ <para>
+ The first step to writing security rules is to create a new rule file in the <literal>/META-INF</literal> directory of your application's jar file. This file should be named <literal>security.drl</literal> or similar, but can be named anything as long as it is configured correspondingly in <filename>components.xml</filename>.
+ </para>
+ <para>
+ We recommend the Drools documentation when you write your rules file. A simple example of rules file contents is:
+ </para>
+
+<programlisting><![CDATA[package MyApplicationPermissions;
- <para>
- The default rule base name can be overridden by specifying the <literal>security-rules</literal>
- property for <literal>RuleBasedPermissionResolver</literal>:
- </para>
-
- <programlisting><![CDATA[
- <security:rule-based-permission-resolver security-rules="#{prodSecurityRules}"/>]]></programlisting>
-
- <para>
- Once the <literal>RuleBase</literal> component is configured, it's time to write the security rules.
- </para>
- </sect3>
-
- <sect3>
- <title>Writing Security Rules</title>
-
- <para>
- The first step to writing security rules is to create a new rule file in the <literal>/META-INF</literal>
- directory of your application's jar file. Usually this file would be named something like
- <literal>security.drl</literal>, however you can name it whatever you like as long as it is configured
- correspondingly in <literal>components.xml</literal>.
- </para>
-
- <para>
- So what should the security rules file contain? At this stage it might be a good idea to at least skim
- through the Drools documentation, however to get started here's an extremely simple example:
- </para>
+import org.jboss.seam.security.permission.PermissionCheck;
+import org.jboss.seam.security.Role;
- <programlisting><![CDATA[package MyApplicationPermissions;
-
- import org.jboss.seam.security.permission.PermissionCheck;
- import org.jboss.seam.security.Role;
-
- rule CanUserDeleteCustomers
- when
- c: PermissionCheck(target == "customer", action == "delete")
- Role(name == "admin")
- then
- c.grant();
- end]]></programlisting>
-
- <para>
- Let's break this down step by step. The first thing we see is the package declaration. A package in Drools
- is essentially a collection of rules. The package name can be anything you want - it doesn't relate
- to anything else outside the scope of the rule base.
- </para>
-
- <para>
- The next thing we can notice is a couple of import statements for the <literal>PermissionCheck</literal>
- and <literal>Role</literal> classes. These imports inform the rules engine that we'll be referencing
- these classes within our rules.
- </para>
-
- <para>
- Finally we have the code for the rule. Each rule within a package should be given a unique name (usually
- describing the purpose of the rule). In this case our rule is called <literal>CanUserDeleteCustomers</literal>
- and will be used to check whether a user is allowed to delete a customer record.
- </para>
-
- <para>
- Looking at the body of the rule definition we can notice two distinct sections. Rules have what is known
- as a left hand side (LHS) and a right hand side (RHS). The LHS consists of the conditional part of the
- rule, i.e. a list of conditions which must be satisfied for the rule to fire. The LHS is represented by
- the <literal>when</literal> section. The RHS is the consequence, or action section of the rule that will
- only be fired if all of the conditions in the LHS are met. The RHS is represented by the
- <literal>then</literal> section. The end of the rule is denoted by the <literal>end</literal> line.
- </para>
-
- <para>
- If we look at the LHS of the rule, we see two conditions listed there. Let's examine the first condition:
- </para>
-
- <programlisting><![CDATA[c: PermissionCheck(target == "customer", action == "delete")]]></programlisting>
-
- <para>
- In plain english, this condition is stating that there must exist a <literal>PermissionCheck</literal> object
- with a <literal>target</literal> property equal to "customer", and an <literal>action</literal> property equal
- to "delete" within the working memory.
- </para>
-
- <para>
- So what is the working memory? Also known as a "stateful session" in Drools terminology, the working memory
- is a session-scoped object that contains the contextual information that is required by the rules engine to
- make a decision about a permission check. Each time the <literal>hasPermission()</literal> method is called,
- a temporary <literal>PermissionCheck</literal> object, or <emphasis>Fact</emphasis>, is inserted into the
- working memory. This <literal>PermissionCheck</literal> corresponds exactly to the permission that is being
- checked, so for example if you call <literal>hasPermission("account", "create")</literal> then a
- <literal>PermissionCheck</literal> object with a <literal>target</literal> equal to "account" and
- <literal>action</literal> equal to "create" will be inserted into the working memory for the duration of the
- permission check.
- </para>
-
- <para>
- Besides the <literal>PermissionCheck</literal> facts, there is also a <literal>org.jboss.seam.security.Role</literal>
- fact for each of the roles that the authenticated user is a member of. These <literal>Role</literal> facts
- are synchronized with the user's authenticated roles at the beginning of every permission check. As a consequence,
- any <literal>Role</literal> object that is inserted into the working memory during the course of a permission
- check will be removed before the next permission check occurs, if the authenticated user is not actually a member of
- that role. Besides the <literal>PermissionCheck</literal> and <literal>Role</literal> facts, the working
- memory also contains the <literal>java.security.Principal</literal> object that was created as a result of
- the authentication process.
- </para>
-
- <para>
- It is also possible to insert additional long-lived facts into the working memory by calling
- <literal>RuleBasedPermissionResolver.instance().getSecurityContext().insert()</literal>,
- passing the object as a parameter. The exception to this is <literal>Role</literal> objects, which as
- already discussed are synchronized at the start of each permission check.
- </para>
-
- <para>
- Getting back to our simple example, we can also notice that the first line of our LHS is prefixed with
- <literal>c:</literal>. This is a variable binding, and is used to refer back to the object that is
- matched by the condition (in this case, the <literal>PermissionCheck</literal>). Moving on to the
- second line of our LHS, we see this:
- </para>
-
- <programlisting><![CDATA[Role(name == "admin")]]></programlisting>
-
- <para>
- This condition simply states that there must be a <literal>Role</literal> object with a
- <literal>name</literal> of "admin" within the working memory. As already mentioned, user roles are inserted into
- the working memory at the beginning of each permission check. So, putting both conditions together, this
- rule is essentially saying "I will fire if you are checking for the <literal>customer:delete</literal>
- permission and the user is a member of the <literal>admin</literal> role".
- </para>
-
- <para>
- So what is the consequence of the rule firing? Let's take a look at the RHS of the rule:
- </para>
-
- <programlisting><![CDATA[c.grant()]]></programlisting>
-
- <para>
- The RHS consists of Java code, and in this case is invoking the <literal>grant()</literal>
- method of the <literal>c</literal> object, which as already mentioned is a variable binding
- for the <literal>PermissionCheck</literal> object. Besides the <literal>name</literal> and
- <literal>action</literal> properties of the <literal>PermissionCheck</literal> object, there
- is also a <literal>granted</literal> property which is initially set to <literal>false</literal>.
- Calling <literal>grant()</literal> on a <literal>PermissionCheck</literal> sets the
- <literal>granted</literal> property to <literal>true</literal>, which means that the permission
- check was successful, allowing the user to carry out whatever action the permission check was
- intended for.
- </para>
- </sect3>
-
- <sect3>
- <title>Non-String permission targets</title>
-
- <para>
- So far we have only seen permission checks for String-literal permission targets. It is of course also
- possible to write security rules for permission targets of more complex types. For example, let's say that you wish
- to write a security rule to allow your users to create blog comments. The following rule demonstrates
- how this may be expressed, by requiring the target of the permission check to be an instance of
- <literal>MemberBlog</literal>, and also requiring that the currently authenticated user is a member of the
- <literal>user</literal> role:
- </para>
-
- <programlisting><![CDATA[rule CanCreateBlogComment
+rule CanUserDeleteCustomers
+when
+ c: PermissionCheck(target == "customer", action == "delete")
+ Role(name == "admin")
+then
+ c.grant();
+end]]>
+</programlisting>
+ <para>
+ Here, the first thing we see is the package declaration. A package in Drools is a collection of rules. The package name does not relate to anything outside the scope of the rule base, so it can be given any name.
+ </para>
+ <para>
+ Next, we have several import statements for the <literal>PermissionCheck</literal> and <literal>Role</literal> classes. These imports inform the rules engine that our rules will refer to these classes.
+ </para>
+ <para>
+ Finally, we have the rule code. Each rule within a package should have a unique name, usually to describe the rule's purpose. In this case our rule is called <literal>CanUserDeleteCustomers</literal> and will be used to check whether a user is allowed to delete a customer record.
+ </para>
+ <para>
+ There are two distinct sections in the body of the rule definition. Rules have a left hand side (LHS) and a right hand side (RHS). The LHS is the conditional portion of the rule, that is, a list of conditions that must be satisfied for the rule to fire. The LHS is represented by the <literal>when</literal> section. The RHS is the consequence or action section of the rule, which will only be fired if all conditions in the LHS are met. The RHS is represented by the <literal>then</literal> section. The end of the rule is denoted by the <literal>end</literal> line.
+ </para>
+ <para>
+ There are two conditions listed in the example LHS. The first condition is:
+ </para>
+
+<programlisting><![CDATA[c: PermissionCheck(target == "customer", action == "delete")]]>
+</programlisting>
+ <para>
+ More plainly, this condition states that, to be fulfilled, there must be a <literal>PermissionCheck</literal> object with a <literal>target</literal> property equal to <literal>customer</literal>, and an <literal>action</literal> property equal to <literal>delete</literal> within the working memory.
+ </para>
+ <para>
+ Working memory is also known as a <emphasis>stateful session</emphasis> in Drools terminology. It is a session-scoped object containing the contextual information that the rules engine requires to make a decision about a permission check. Each time the <literal>hasPermission()</literal> method is called, a temporary <literal>PermissionCheck</literal> object, or <emphasis>Fact</emphasis>, is inserted into the working memory. This <literal>PermissionCheck</literal> corresponds exactly to the permission being checked, so if you call <literal>hasPermission("account", "create")</literal>, a <literal>PermissionCheck</literal> object with a <literal>target</literal> equal to "account" and <literal>action</literal> equal to "create" will be inserted into the working memory for the duration of the permission check.
+ </para>
+ <para>
+ Other than the <literal>PermissionCheck</literal> facts, there is also an <literal>org.jboss.seam.security.Role</literal> fact for each role that the authenticated user is a member of. These <literal>Role</literal> facts are synchronized with the user's authenticated roles at the beginning of every permission check. As a consequence, any <literal>Role</literal> object inserted into the working memory during the course of a permission check will be removed before the next permission check occurs, unless the authenticated user is actually a member of that role. The working memory also contains the <literal>java.security.Principal</literal> object created as a result of the authentication process.
+ </para>
+ <para>
+ You can insert additional long-lived facts into the working memory by calling <literal>RuleBasedPermissionResolver.instance().getSecurityContext().insert ()</literal>, which passes the object as a parameter. <literal>Role</literal> objects are the exception, here, since they are synchronized at the start of each permission check.
+ </para>
+ <para>
+ To return to our simple example, the first line of our LHS is prefixed with <literal>c:</literal>. This is a variable binding, and is used to refer back to the object matching the condition (in this case, the <literal>PermissionCheck</literal>). The second line of the LHS is:
+ </para>
+
+<programlisting><![CDATA[Role(name == "admin")]]>
+</programlisting>
+ <para>
+ This condition states that there must be a <literal>Role</literal> object with a <literal>name</literal> of "admin" within the working memory. So, if you are checking for the <literal>customer:delete</literal> permission and the user is a member of the <literal>admin</literal> role, this rule will fire.
+ </para>
+ <para>
+ The RHS shows us the consequence of the rule firing:
+ </para>
+
+<programlisting><![CDATA[c.grant()]]>
+</programlisting>
+ <para>
+ The RHS consists of Java code. In this case it invokes the <literal>grant()</literal> method of the <literal>c</literal> object, which is a variable binding for the <literal>PermissionCheck</literal> object. Other than the <literal>name</literal> and <literal>action</literal> properties of the <literal>PermissionCheck</literal> object, there is also a <literal>granted</literal> property. This is initially set to <literal>false</literal>. Calling <literal>grant()</literal> on a <literal>PermissionCheck</literal> sets the <literal>granted</literal> property to <literal>true</literal>. This means the permission check succeeded, and the user has permission to carry out the action that prompted the permission check.
+ </para>
+ </section>
+
+ <section>
+ <title>Non-String permission targets</title>
+ <para>
+ So far, we have only looked at permission checks for String-literal permission targets. However, you can also write security rules for more complex permission targets. For example, say you want to write a security rule to allow your users to create blog comments. The following rule shows one way this can be expressed, by requiring that the target of the permission check be an instance of <literal>MemberBlog</literal>, and that the currently authenticated user be a member of the <literal>user</literal> role:
+ </para>
+
+<programlisting><![CDATA[rule CanCreateBlogComment
no-loop
activation-group "permissions"
when
blog: MemberBlog()
- check: PermissionCheck(target == blog, action == "create", granted == false)
+ check: PermissionCheck(target == blog, action == "create",
+ granted == false)
Role(name == "user")
then
check.grant();
end
-]]></programlisting>
-
- </sect3>
-
- <sect3>
- <title>Wildcard permission checks</title>
-
- <para>
- It is possible to implement a wildcard permission check (which allows all actions for a given permission
- target), by omitting the <literal>action</literal> constraint for the <literal>PermissionCheck</literal> in
- your rule, like this:
- </para>
-
- <programlisting><![CDATA[rule CanDoAnythingToCustomersIfYouAreAnAdmin
+]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Wildcard permission checks</title>
+ <para>
+ It is possible to implement a wildcard permission check (which allows all actions for a given permission target), by omitting the <literal>action</literal> constraint for the <literal>PermissionCheck</literal> in your rule, like so:
+ </para>
+
+<programlisting><![CDATA[rule CanDoAnythingToCustomersIfYouAreAnAdmin
when
c: PermissionCheck(target == "customer")
Role(name == "admin")
then
c.grant();
-end;
- ]]></programlisting>
-
- <para>
- This rule allows users with the <literal>admin</literal> role to perform <emphasis>any</emphasis> action for
- any <literal>customer</literal> permission check.
- </para>
-
- </sect3>
-
- </sect2>
-
- <sect2>
- <title>PersistentPermissionResolver</title>
-
- <para>
- Another built-in permission resolver provided by Seam, <literal>PersistentPermissionResolver</literal>
- allows permissions to be loaded from persistent storage, such as a relational database. This permission
- resolver provides ACL style instance-based security, allowing for specific object permissions to be assigned
- to individual users and roles. It also allows for persistent, arbitrarily-named permission targets (not
- necessarily object/class based) to be assigned in the same way.
- </para>
-
- <sect3>
- <title>Configuration</title>
-
- <para>
- Before it can be used, <literal>PersistentPermissionResolver</literal> must be configured with a
- valid <literal>PermissionStore</literal> in <literal>components.xml</literal>. If not configured,
- it will attempt to use the default permission store, <literal>JpaIdentityStore</literal> (see section
- further down for details). To use a permission store other than the default, configure the
- <literal>permission-store</literal> property as follows:
- </para>
-
- <programlisting><![CDATA[ <security:persistent-permission-resolver permission-store="#{myCustomPermissionStore}"/>]]></programlisting>
-
- </sect3>
-
- <sect3>
- <title>Permission Stores</title>
-
- <para>
- A permission store is required for <literal>PersistentPermissionResolver</literal> to connect to the
- backend storage where permissions are persisted. Seam provides one <literal>PermissionStore</literal>
- implementation out of the box, <literal>JpaPermissionStore</literal>, which is used to store
- permissions inside a relational database. It is possible to write your own permission store
- by implementing the <literal>PermissionStore</literal> interface, which defines the following
- methods:
- </para>
-
- <table>
- <title>PermissionStore interface</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="2*" />
- <colspec colnum="2" colwidth="3*" />
- <colspec colnum="3" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Return type</para>
- </entry>
- <entry align="center">
- <para>Method</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para>
- <literal>List<Permission></literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>listPermissions(Object target)</literal>
- </para>
- </entry>
- <entry>
- <para>
- This method should return a <literal>List</literal> of <literal>Permission</literal> objects
- representing all the permissions granted for the specified target object.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>List<Permission></literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>listPermissions(Object target, String action)</literal>
- </para>
- </entry>
- <entry>
- <para>
- This method should return a <literal>List</literal> of <literal>Permission</literal> objects
- representing all the permissions with the specified action, granted for the specified target object.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>List<Permission></literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>listPermissions(Set<Object> targets, String action)</literal>
- </para>
- </entry>
- <entry>
- <para>
- This method should return a <literal>List</literal> of <literal>Permission</literal> objects
- representing all the permissions with the specified action, granted for the specified set of
- target objects.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>grantPermission(Permission)</literal>
- </para>
- </entry>
- <entry>
- <para>
- This method should persist the specified <literal>Permission</literal> object to the backend
- storage, returning true if successful.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>grantPermissions(List<Permission> permissions)</literal>
- </para>
- </entry>
- <entry>
- <para>
- This method should persist all of the <literal>Permission</literal> objects contained in the
- specified <literal>List</literal>, returning true if successful.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>revokePermission(Permission permission)</literal>
- </para>
- </entry>
- <entry>
- <para>
- This method should remove the specified <literal>Permission</literal> object from persistent storage.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>revokePermissions(List<Permission> permissions)</literal>
- </para>
- </entry>
- <entry>
- <para>
- This method should remove all of the <literal>Permission</literal> objects in the specified list
- from persistent storage.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>List<String></literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>listAvailableActions(Object target)</literal>
- </para>
- </entry>
- <entry>
- <para>
- This method should return a list of all the available actions (as Strings) for the class of the
- specified target object. It is used in conjunction with permission management to build the user
- interface for granting specific class permissions (see section further down).
- </para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </sect3>
-
- <sect3>
- <title>JpaPermissionStore</title>
-
- <para>
- This is the default <literal>PermissionStore</literal> implementation (and the only one provided by Seam), which
- uses a relational database to store permissions. Before it can be used it must be configured with either one or
- two entity classes for storing user and role permissions. These entity classes must be annotated with a special
- set of security annotations to configure which properties of the entity correspond to various aspects of the
- permissions being stored.
- </para>
-
- <para>
- If you wish to use the same entity (i.e. a single database table) to store both user and role permissions, then
- only the <literal>user-permission-class</literal> property is required to be configured. If you wish to use
- separate tables for storing user and role permissions, then in addition to the <literal>user-permission-class</literal>
- property you must also configure the <literal>role-permission-class</literal> property.
- </para>
-
- <para>For example, to configure a single entity class to store both user and role permissions:</para>
-
- <programlisting role="XML"><![CDATA[ <security:jpa-permission-store user-permission-class="com.acme.model.AccountPermission"/>]]></programlisting>
-
- <para>To configure separate entity classes for storing user and role permissions:</para>
-
- <programlisting role="XML"><![CDATA[ <security:jpa-permission-store user-permission-class="com.acme.model.UserPermission"
- role-permission-class="com.acme.model.RolePermission"/>]]></programlisting>
-
- <sect4>
- <title>Permission annotations</title>
-
- <para>
- As mentioned, the entity classes that contain the user and role permissions must be configured with a
- special set of annotations, contained within the <literal>org.jboss.seam.annotations.security.permission</literal> package.
- The following table lists each of these annotations along with a description of how they are used:
- </para>
-
- <table>
- <title>Entity Permission annotations</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="2*" />
- <colspec colnum="2" colwidth="3*" />
- <colspec colnum="3" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Annotation</para>
- </entry>
- <entry align="center">
- <para>Target</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para>
- <literal>@PermissionTarget</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>FIELD,METHOD</literal>
- </para>
- </entry>
- <entry>
- <para>
- This annotation identifies the property of the entity that will contain the permission target. The property
- should be of type <literal>java.lang.String</literal>.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@PermissionAction</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>FIELD,METHOD</literal>
- </para>
- </entry>
- <entry>
- <para>
- This annotation identifies the property of the entity that will contain the permission action. The property
- should be of type <literal>java.lang.String</literal>.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@PermissionUser</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>FIELD,METHOD</literal>
- </para>
- </entry>
- <entry>
- <para>
- This annotation identifies the property of the entity that will contain the recipient user for the permission. It should
- be of type <literal>java.lang.String</literal> and contain the user's username.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@PermissionRole</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>FIELD,METHOD</literal>
- </para>
- </entry>
- <entry>
- <para>
- This annotation identifies the property of the entity that will contain the recipient role for the permission. It should
- be of type <literal>java.lang.String</literal> and contain the role name.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@PermissionDiscriminator</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>FIELD,METHOD</literal>
- </para>
- </entry>
- <entry>
- <para>
- This annotation should be used when the same entity/table is used to store both user and role permissions. It identifies
- the property of the entity that is used to discriminate between user and role permissions. By default, if the column
- value contains the string literal <literal>user</literal>, then the record will be treated as a user permission. If it
- contains the string literal <literal>role</literal>, then it will be treated as a role permission. It is also possible
- to override these defaults by specifying the <literal>userValue</literal> and <literal>roleValue</literal> properties
- within the annotation. For example, to use <literal>u</literal> and <literal>r</literal> instead of <literal>user</literal>
- and <literal>role</literal>, the annotation would be written like this:
- </para>
-
- <programlisting role="JAVA"><![CDATA[ @PermissionDiscriminator(userValue = "u", roleValue = "r")]]></programlisting>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </sect4>
-
- <sect4>
- <title>Example Entity</title>
-
- <para>
- Here is an example of an entity class that is used to store both user and role permissions. The following class can be found
- inside the SeamSpace example:
- </para>
-
- <programlisting role="JAVA"><![CDATA[
- at Entity
+end;]]>
+</programlisting>
+ <para>
+ This rule allows users with the <literal>admin</literal> role to perform <emphasis>any</emphasis> action for any <literal>customer</literal> permission check.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>PersistentPermissionResolver</title>
+ <para>
+ Another built-in permission resolver provided by Seam, <literal>PersistentPermissionResolver</literal>, allows permissions to be loaded from persistent storage, such as a relational database. This permission resolver provides Access Control List-style instance-based security, allowing specific object permissions to be assigned to individual users and roles. It also allows persistent, arbitrarily-named permission targets (which are not necessarily object/class based) to be assigned in the same way.
+ </para>
+ <section>
+ <title>Configuration</title>
+ <para>
+ To use <literal>PersistentPermissionResolver</literal>, you must configure a valid <literal>PermissionStore</literal> in <filename>components.xml</filename>. If this is not configured, the <literal>PersistentPermissionResolver</literal> will attempt to use the default permission store, <xref linkend="security-id_management-jpaidstore" />. To use a permission store other than the default, configure the <literal>permission-store</literal> property as follows:
+ </para>
+
+<programlisting><![CDATA[
+<security:persistent-permission-resolver
+ permission-store="#{myCustomPermissionStore}"/>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Permission Stores</title>
+ <para>
+ <literal>PersistentPermissionResolver</literal> requires a permission store to connect to the back-end storage where permissions are persisted. Seam provides one <literal>PermissionStore</literal> implementation out of the box, <literal>JpaPermissionStore</literal>, which stores permissions inside a relational database. You can write your own permission store by implementing the <literal>PermissionStore</literal> interface, which defines the following methods:
+ </para>
+ <table>
+ <title>PermissionStore interface</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="2.0*"></colspec>
+ <colspec colnum="3" colwidth="1*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Return type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Method
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Description
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>List<![CDATA[<Permission>]]></literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>listPermissions(Object target)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This method should return a <literal>List</literal> of <literal>Permission</literal> objects representing all the permissions granted for the specified target object.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>List<![CDATA[<Permission>]]></literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>listPermissions(Object target, String action)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This method should return a <literal>List</literal> of <literal>Permission</literal> objects representing all the permissions with the specified action granted for the specified target object.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>List<![CDATA[<Permission>]]></literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>listPermissions(Set<![CDATA[<Object>]]> targets, String action)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This method should return a <literal>List</literal> of <literal>Permission</literal> objects representing all the permissions with the specified action granted for the specified set of target objects.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>grantPermission(Permission)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This method should persist the specified <literal>Permission</literal> object to the back-end storage, and return <literal>true</literal> if successful.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>grantPermissions(List<![CDATA[<Permission>]]> permissions)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This method should persist all of the <literal>Permission</literal> objects contained in the specified <literal>List</literal>, and return <literal>true</literal> if successful.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>revokePermission(Permission permission)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This method should remove the specified <literal>Permission</literal> object from persistent storage.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>revokePermissions(List<![CDATA[<Permission>]]> permissions)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This method should remove all of the <literal>Permission</literal> objects in the specified list from persistent storage.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>List<![CDATA[<String>]]></literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>listAvailableActions(Object target)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This method should return a list of all available actions (as Strings) for the class of the specified target object. It is used in conjunction with permission management to build the user interface for granting specific class permissions.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>JpaPermissionStore</title>
+ <para>
+ The Seam-provided default <literal>PermissionStore</literal> implementation, which stores permissions in a relational database. It must be configured with either one or two entity classes for storing user and role permissions before it can be used. These entity classes must be annotated with a special set of security annotations to configure the entity properties that correspond to various aspects of the stored permissions.
+ </para>
+ <para>
+ If you want to use the same entity (that is, a single database table) to store both user and role permissions, then you only need to configure the <literal>user-permission-class</literal> property. To user separate tables for user and role permission storage, you must also configure the <literal>role-permission-class</literal> property.
+ </para>
+ <para>
+ For example, to configure a single entity class to store both user and role permissions:
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<security:jpa-permission-store
+ user-permission-class="com.acme.model.AccountPermission"/>]]>
+</programlisting>
+ <para>
+ To configure separate entity classes for storing user and role permissions:
+ </para>
+
+<programlisting role="XML"><![CDATA[<security:jpa-permission-store
+ user-permission-class="com.acme.model.UserPermission"
+ role-permission-class="com.acme.model.RolePermission"/>]]>
+</programlisting>
+ <section>
+ <title>Permission annotations</title>
+ <para>
+ The entity classes that contain the user and role permissions must be configured with a special set of annotations in the <literal>org.jboss.seam.annotations.security.permission</literal> package. The following table describes these annotations:
+ </para>
+ <table>
+ <title>Entity Permission annotations</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="2*"></colspec>
+ <colspec colnum="2" colwidth="1*"></colspec>
+ <colspec colnum="3" colwidth="2*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Annotation
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Target
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Description
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>@PermissionTarget</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>FIELD,METHOD</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation identifies the entity property containing the permission target. The property should be of type <literal>java.lang.String</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@PermissionAction</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>FIELD,METHOD</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation identifies the entity property containing the permission action. The property should be of type <literal>java.lang.String</literal>.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@PermissionUser</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>FIELD,METHOD</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation identifies the entity property containing the recipient user for the permission. It should be of type <literal>java.lang.String</literal> and contain the user's username.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@PermissionRole</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>FIELD,METHOD</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation identifies the entity property containing the recipient role for the permission. It should be of type <literal>java.lang.String</literal> and contain the role name.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@PermissionDiscriminator</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>FIELD,METHOD</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation should be used when the same entity/table stores both user and role permissions. It identifies the property of the entity being used to discriminate between user and role permissions. By default, if the column value contains the string literal <literal>user</literal>, then the record will be treated as a user permission. If it contains the string literal <literal>role</literal>, it will be treated as a role permission. You can also override these defaults by specifying the <literal>userValue</literal> and <literal>roleValue</literal> properties within the annotation. For example, to use <literal>u</literal> and <literal>r</literal> instead of <literal>user</literal> and <literal>role</literal>, write the annotation like so:
+
+
+<programlisting role="JAVA"><![CDATA[
+ at PermissionDiscriminator(
+ userValue = "u",
+ roleValue = "r")]]>
+</programlisting>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Example Entity</title>
+ <para>
+ The following is an example of an entity class that stores both user and role permissions, taken from the Seamspace example.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Entity
public class AccountPermission implements Serializable {
- private Integer permissionId;
- private String recipient;
- private String target;
- private String action;
- private String discriminator;
+ private Integer permissionId;
+ private String recipient;
+ private String target;
+ private String action;
+ private String discriminator;
- @Id @GeneratedValue
- public Integer getPermissionId() {
- return permissionId;
- }
+ @Id @GeneratedValue
+ public Integer getPermissionId() {
+ return permissionId;
+ }
- public void setPermissionId(Integer permissionId) {
- this.permissionId = permissionId;
- }
+ public void setPermissionId(Integer permissionId) {
+ this.permissionId = permissionId;
+ }
- @PermissionUser @PermissionRole
- public String getRecipient() {
- return recipient;
- }
+ @PermissionUser @PermissionRole
+ public String getRecipient() {
+ return recipient;
+ }
- public void setRecipient(String recipient) {
- this.recipient = recipient;
- }
+ public void setRecipient(String recipient) {
+ this.recipient = recipient;
+ }
- @PermissionTarget
- public String getTarget() {
- return target;
- }
+ @PermissionTarget
+ public String getTarget() {
+ return target;
+ }
- public void setTarget(String target) {
- this.target = target;
- }
+ public void setTarget(String target) {
+ this.target = target;
+ }
- @PermissionAction
- public String getAction() {
- return action;
- }
+ @PermissionAction
+ public String getAction() {
+ return action;
+ }
- public void setAction(String action) {
- this.action = action;
- }
+ public void setAction(String action) {
+ this.action = action;
+ }
- @PermissionDiscriminator
- public String getDiscriminator() {
- return discriminator;
- }
+ @PermissionDiscriminator
+ public String getDiscriminator() {
+ return discriminator;
+ }
- public void setDiscriminator(String discriminator) {
- this.discriminator = discriminator;
- }
-}
- ]]></programlisting>
-
- <para>
- As can be seen in the above example, the <literal>getDiscriminator()</literal> method has been annotated
- with the <literal>@PermissionDiscriminator</literal> annotation, to allow <literal>JpaPermissionStore</literal> to
- determine which records represent user permissions and which represent role permissions. In addition, it
- can also be seen that the <literal>getRecipient()</literal> method is annotated with both
- <literal>@PermissionUser</literal> and <literal>@PermissionRole</literal> annotations. This is perfectly valid,
- and simply means that the <literal>recipient</literal> property of the entity will either contain the name
- of the user or the name of the role, depending on the value of the <literal>discriminator</literal> property.
- </para>
-
- </sect4>
-
- <sect4>
- <title>Class-specific Permission Configuration</title>
-
- <para>
- A further set of class-specific annotations can be used to configure a specific set of allowable permissions
- for a target class. These permissions can be found in the <literal>org.jboss.seam.annotation.security.permission</literal>
- package:
- </para>
-
- <table>
- <title>Class Permission Annotations</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="2*" />
- <colspec colnum="2" colwidth="3*" />
- <colspec colnum="3" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Annotation</para>
- </entry>
- <entry align="center">
- <para>Target</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para>
- <literal>@Permissions</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>TYPE</literal>
- </para>
- </entry>
- <entry>
- <para>
- A container annotation, this annotation may contain an array of <literal>@Permission</literal> annotations.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>@Permission</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>TYPE</literal>
- </para>
- </entry>
- <entry>
- <para>
- This annotation defines a single allowable permission action for the target class. Its <literal>action</literal>
- property must be specified, and an optional <literal>mask</literal> property may also be specified if permission
- actions are to be persisted as bitmasked values (see next section).
- </para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- <para>
- Here's an example of the above annotations in action. The following class can also be found in the SeamSpace example:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Permissions({
- @Permission(action = "view"),
- @Permission(action = "comment")
+ public void setDiscriminator(String discriminator) {
+ this.discriminator = discriminator;
+ }
+}]]>
+</programlisting>
+ <para>
+ Here, the <literal>getDiscriminator()</literal> method has been annotated with <literal>@PermissionDiscriminator</literal>, to allow <literal>JpaPermissionStore</literal> to determine which records represent user permissions and which represent role permissions. The <literal>getRecipient()</literal> method is annotated with both <literal>@PermissionUser</literal> and <literal>@PermissionRole</literal>. This means that the <literal>recipient</literal> property of the entity will either contain the name of the user or the name of the role, depending on the value of the <literal>discriminator</literal> property.
+ </para>
+ </section>
+
+ <section>
+ <title>Class-specific Permission Configuration</title>
+ <para>
+ The permissions included in the <literal>org.jboss.seam.annotation.security.permission</literal> package can be used to configure a specific set of allowable permissions for a target class.
+ </para>
+ <table>
+ <title>Class Permission Annotations</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="2*"></colspec>
+ <colspec colnum="2" colwidth="3*"></colspec>
+ <colspec colnum="3" colwidth="3*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Annotation
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Target
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Description
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>@Permissions</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>TYPE</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ A container annotation, which can contain an array of <literal>@Permission</literal> annotations.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>@Permission</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>TYPE</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ This annotation defines a single allowable permission action for the target class. Its <literal>action</literal> property must be specified, and an optional <literal>mask</literal> property may also be specified if permission actions are to be persisted as bitmasked values (see section following).
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ The following shows the above annotations in use. They can also be seen in the SeamSpace example.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Permissions({
+ @Permission(action = "view"),
+ @Permission(action = "comment")
})
- at Entity
-public class MemberImage implements Serializable {]]></programlisting>
- <para>
- This example demonstrates how two allowable permission actions, <literal>view</literal> and <literal>comment</literal>
- can be declared for the entity class <literal>MemberImage</literal>.
- </para>
-
- </sect4>
-
- <sect4>
- <title>Permission masks</title>
-
- <para>
- By default, multiple permissions for the same target object and recipient will be persisted as a single database record,
- with the <literal>action</literal> property/column containing a comma-separated list of the granted actions. To reduce
- the amount of physical storage required to persist a large number of permissions, it is possible to use a bitmasked
- integer value (instead of a comma-separated list) to store the list of permission actions.
- </para>
-
- <para>
- For example, if recipient "Bob" is granted both the <literal>view</literal> and <literal>comment</literal> permissions
- for a particular <literal>MemberImage</literal> (an entity bean) instance, then by default the <literal>action</literal> property of the
- permission entity will contain "<literal>view,comment</literal>", representing the two granted permission actions.
- Alternatively, if using bitmasked values for the permission actions, as defined like so:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Permissions({
- @Permission(action = "view", mask = 1),
- @Permission(action = "comment", mask = 2)
-})
@Entity
-public class MemberImage implements Serializable {]]></programlisting>
+public class MemberImage implements Serializable {...}]]>
+</programlisting>
+ <para>
+ This example demonstrates how two allowable permission actions, <literal>view</literal> and <literal>comment</literal> can be declared for the entity class <literal>MemberImage</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Permission masks</title>
+ <para>
+ By default, multiple permissions for the same target object and recipient will be persisted as a single database record, with the <literal>action</literal> property/column containing a list of granted actions, separated by commas. You can use a bitmasked integer value to store the list of permission actions — this reduces the amount of physical storage required to persist a large number of permissions.
+ </para>
+ <para>
+ For example, if recipient "Bob" is granted both the <literal>view</literal> and <literal>comment</literal> permissions for a particular <literal>MemberImage</literal> (an entity bean) instance, then by default the <literal>action</literal> property of the permission entity will contain "<literal>view,comment</literal>", representing the two granted permission actions. Or, if you are using bitmasked values defined as follows:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Permissions({
+ @Permission(action = "view", mask = 1),
+ @Permission(action = "comment", mask = 2)
+})
- <para>
- The <literal>action</literal> property will instead simply contain "3" (with both the 1 bit and 2 bit switched on). Obviously
- for a large number of allowable actions for any particular target class, the storage required for the permission records
- is greatly reduced by using bitmasked actions.
- </para>
-
- <para>
- Obviously, it is very important that the <literal>mask</literal> values specified are powers of 2.
- </para>
- </sect4>
-
- <sect4>
- <title>Identifier Policy</title>
-
- <para>
- When storing or looking up permissions, <literal>JpaPermissionStore</literal> must be able to uniquely identify specific
- object instances to effectively operate on its permissions. To achieve this, an <emphasis>identifier strategy</emphasis>
- may be assigned to each target class for the generation of unique identifier values. Each identifier strategy
- implementation knows how to generate unique identifiers for a particular type of class, and it is a simple matter to
- create new identifier strategies.
- </para>
-
- <para>
- The <literal>IdentifierStrategy</literal> interface is very simple, declaring only two methods:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public interface IdentifierStrategy {
- boolean canIdentify(Class targetClass);
- String getIdentifier(Object target);
-}]]></programlisting>
-
- <para>
- The first method, <literal>canIdentify()</literal> simply returns <literal>true</literal> if the identifier strategy
- is capable of generating a unique identifier for the specified target class. The second method,
- <literal>getIdentifier()</literal> returns the unique identifier value for the specified target object.
- </para>
-
- <para>
- Seam provides two <literal>IdentifierStrategy</literal> implementations, <literal>ClassIdentifierStrategy</literal>
- and <literal>EntityIdentifierStrategy</literal> (see next sections for details).
- </para>
-
- <para>
- To explicitly configure a specific identifier strategy to use for a particular class, it should be annotated with
- <literal>org.jboss.seam.annotations.security.permission.Identifier</literal>, and the value should be set to
- a concrete implementation of the <literal>IdentifierStrategy</literal> interface. An optional <literal>name</literal>
- property can also be specified, the effect of which is dependent upon the actual <literal>IdentifierStrategy</literal>
- implementation used.
- </para>
- </sect4>
-
- <sect4>
- <title>ClassIdentifierStrategy</title>
-
- <para>
- This identifier strategy is used to generate unique identifiers for classes, and will use the value of the
- <literal>name</literal> (if specified) in the <literal>@Identifier</literal> annotation. If there is no
- <literal>name</literal> property provided, then it will attempt to use the component name of the class
- (if the class is a Seam component), or as a last resort it will create an identifier based on the name
- of the class (excluding the package name). For example, the identifier for the following class will
- be "<literal>customer</literal>":
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Identifier(name = "customer")
-public class Customer {]]></programlisting>
-
- <para>
- The identifier for the following class will be "<literal>customerAction</literal>":
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("customerAction")
-public class CustomerAction { ]]></programlisting>
-
- <para>
- Finally, the identifier for the following class will be "<literal>Customer</literal>":
- </para>
-
- <programlisting><![CDATA[public class Customer { ]]></programlisting>
-
- </sect4>
-
- <sect4>
- <title>EntityIdentifierStrategy</title>
-
- <para>
- This identifier strategy is used to generate unique identifiers for entity beans. It does so by
- concatenating the entity name (or otherwise configured name) with a string representation of the
- primary key value of the entity. The rules for generating the name section of the identifier are
- similar to <literal>ClassIdentifierStrategy</literal>. The primary key value (i.e. the
- <emphasis>id</emphasis> of the entity) is obtained using the <literal>PersistenceProvider</literal>
- component, which is able to correctly determine the value regardless of which persistence implementation
- is used within the Seam application. For entities not annotated with <literal>@Entity</literal>, it is
- necessary to explicitly configure the identifier strategy on the entity class itself, for example:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Identifier(value = EntityIdentifierStrategy.class)
-public class Customer { ]]></programlisting>
-
- <para>
- For an example of the type of identifier values generated, assume we have the following entity class:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Entity
+ at Entity
+public class MemberImage implements Serializable {...}]]>
+</programlisting>
+ <para>
+ The <literal>action</literal> property will contain "3" (with both the 1 bit and 2 bit switched on). For a large number of allowable actions for any particular target class, the storage required for the permission records is greatly reduced by using bitmasked actions.
+ </para>
+ <important>
+ <para>
+ The <literal>mask</literal> values specified must be powers of 2.
+ </para>
+ </important>
+ </section>
+
+ <section>
+ <title>Identifier Policy</title>
+ <para>
+ When storing or looking up permissions, <literal>JpaPermissionStore</literal> must be able to uniquely identify specific object instances. To achieve this, an <emphasis>identifier strategy</emphasis> may be assigned to each target class so that unique identifier values can be generated. Each identifier strategy implementation knows how to generate unique identifiers for a particular type of class, and creating new identifier strategies is simple.
+ </para>
+ <para>
+ The <literal>IdentifierStrategy</literal> interface is very simple, declaring only two methods:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public interface IdentifierStrategy {
+ boolean canIdentify(Class targetClass);
+ String getIdentifier(Object target);
+}]]>
+</programlisting>
+ <para>
+ The first method, <literal>canIdentify()</literal>, returns <literal>true</literal> if the identifier strategy is capable of generating a unique identifier for the specified target class. The second method, <literal>getIdentifier()</literal>, returns the unique identifier value for the specified target object.
+ </para>
+ <para>
+ Seam also provides two <literal>IdentifierStrategy</literal> implementations, <literal>ClassIdentifierStrategy</literal> and <literal>EntityIdentifierStrategy</literal>, which are described in the sections following.
+ </para>
+ <para>
+ To explicitly configure a specific identifier strategy for a particular class, annotate the strategy with <literal>org.jboss.seam.annotations.security.permission.Identifier</literal> and set the value to a concrete implementation of the <literal>IdentifierStrategy</literal> interface. You may also specify a <literal>name</literal> property. (The effect of this depends upon the <literal>IdentifierStrategy</literal> implementation used.)
+ </para>
+ </section>
+
+ <section>
+ <title>ClassIdentifierStrategy</title>
+ <para>
+ This identifier strategy generates unique identifiers for classes, and uses the value of the <literal>name</literal> (if specified) in the <literal>@Identifier</literal> annotation. If no <literal>name</literal> property is provided, the identifier strategy attempts to use the component name of the class (if the class is a Seam component). It will create an identifier based on the class name (excluding the package name) as a last resort. For example, the identifier for the following class will be <literal>customer</literal>:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Identifier(name = "customer")
+public class Customer {...}]]>
+</programlisting>
+ <para>
+ The identifier for the following class will be <literal>customerAction</literal>:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("customerAction")
+public class CustomerAction {...}]]>
+</programlisting>
+ <para>
+ Finally, the identifier for the following class will be <literal>Customer</literal>:
+ </para>
+
+<programlisting><![CDATA[public class Customer {...} ]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>EntityIdentifierStrategy</title>
+ <para>
+ This identifier strategy generates unique identifiers for entity beans. It concatenates the entity name (or otherwise configured name) with a string representation of the primary key value of the entity. The rules for generating the name section of the identifier are similar to those in <literal>ClassIdentifierStrategy</literal>. The primary key value (that is, the entity ID) is obtained with the <literal>PersistenceProvider</literal> component, which can determine the value regardless of the persistence implementation being used in the Seam application. For entities not annotated with <literal>@Entity</literal>, you must explicitly configure the identifier strategy on the entity class itself, like this:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Identifier(value = EntityIdentifierStrategy.class)
+public class Customer {...} ]]>
+</programlisting>
+ <para>
+ Assume we have the following entity class:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Entity
public class Customer {
private Integer id;
private String firstName;
@@ -4276,920 +3602,773 @@
public void setId(Integer id) { this.id = id; }
public String getFirstName() { return firstName; }
- public void setFirstName(String firstName) { this.firstName = firstName; }
+ public void setFirstName(String firstName) {
+ this.firstName = firstName;
+ }
public String getLastName() { return lastName; }
public void setLastName(String lastName) { this.lastName = lastName; }
-}]]></programlisting>
-
- <para>
- For a <literal>Customer</literal> instance with an <literal>id</literal> value of <literal>1</literal>,
- the value of the identifier would be "<literal>Customer:1</literal>". If the entity class is annotated
- with an explicit identifier name, like so:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Entity
- at Identifier(name = "cust")
-public class Customer { ]]></programlisting>
-
- <para>
- Then a <literal>Customer</literal> with an <literal>id</literal> value of <literal>123</literal>
- would have an identifier value of "<literal>cust:123</literal>".
- </para>
- </sect4>
-
- </sect3>
-
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>Permission Management</title>
-
- <para>
- In much the same way that Seam Security provides an Identity Management API for the management of users and roles,
- it also provides a Permissions Management API for the management of persistent user permissions, via the
- <literal>PermissionManager</literal> component.
- </para>
-
- <sect2>
- <title>PermissionManager</title>
-
- <para>
- The <literal>PermissionManager</literal> component is an application-scoped Seam component that provides a number of
- methods for managing permissions. Before it can be used, it must be configured with a permission store (although by
- default it will attempt to use <literal>JpaPermissionStore</literal> if it is available). To explicitly configure a
- custom permission store, specify the <literal>permission-store</literal> property in components.xml:
- </para>
-
- <programlisting role="XML"><![CDATA[
-<security:permission-manager permission-store="#{ldapPermissionStore}"/>
- ]]></programlisting>
-
- <para>
- The following table describes each of the available methods provided by <literal>PermissionManager</literal>:
- </para>
-
- <table>
- <title>PermissionManager API methods</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="2*" />
- <colspec colnum="2" colwidth="3*" />
- <colspec colnum="3" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Return type</para>
- </entry>
- <entry align="center">
- <para>Method</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para>
- <literal>List<Permission></literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>listPermissions(Object target, String action)</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of <literal>Permission</literal> objects representing all of the permissions that
- have been granted for the specified target and action.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>List<Permission></literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>listPermissions(Object target)</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of <literal>Permission</literal> objects representing all of the permissions that
- have been granted for the specified target and action.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>grantPermission(Permission permission)</literal>
- </para>
- </entry>
- <entry>
- <para>
- Persists (grants) the specified <literal>Permission</literal> to the backend permission store.
- Returns true if the operation was successful.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>grantPermissions(List<Permission> permissions)</literal>
- </para>
- </entry>
- <entry>
- <para>
- Persists (grants) the specified list of <literal>Permission</literal>s to the backend permission store.
- Returns true if the operation was successful.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>revokePermission(Permission permission)</literal>
- </para>
- </entry>
- <entry>
- <para>
- Removes (revokes) the specified <literal>Permission</literal> from the backend permission store.
- Returns true if the operation was successful.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>boolean</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>revokePermissions(List<Permission> permissions)</literal>
- </para>
- </entry>
- <entry>
- <para>
- Removes (revokes) the specified list of <literal>Permission</literal>s from the backend permission store.
- Returns true if the operation was successful.
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>List<String></literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>listAvailableActions(Object target)</literal>
- </para>
- </entry>
- <entry>
- <para>
- Returns a list of the available actions for the specified target object. The actions that this
- method returns are dependent on the <literal>@Permission</literal> annotations configured on the
- target object's class.
- </para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </sect2>
-
- <sect2>
- <title>Permission checks for PermissionManager operations</title>
-
- <para>
- Invoking the methods of <literal>PermissionManager</literal> requires that the currently-authenticated user
- has the appropriate authorization to perform that management operation. The following table lists the required
- permissions that the current user must have.
- </para>
-
- <table>
- <title>Permission Management Security Permissions</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
- <colspec colnum="2" colwidth="3*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Method</para>
- </entry>
- <entry align="center">
- <para>Permission Target</para>
- </entry>
- <entry align="center">
- <para>Permission Action</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <para>
- <literal>listPermissions()</literal>
- </para>
- </entry>
- <entry>
- <para>
- The specified <literal>target</literal>
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.read-permissions</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>grantPermission()</literal>
- </para>
- </entry>
- <entry>
- <para>
- The target of the specified <literal>Permission</literal>, or each of the targets
- for the specified list of <literal>Permission</literal>s (depending on which method is
- called).
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.grant-permission</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>grantPermission()</literal>
- </para>
- </entry>
- <entry>
- <para>
- The target of the specified <literal>Permission</literal>.
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.grant-permission</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>grantPermissions()</literal>
- </para>
- </entry>
- <entry>
- <para>
- Each of the targets of the specified list of <literal>Permission</literal>s.
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.grant-permission</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>revokePermission()</literal>
- </para>
- </entry>
- <entry>
- <para>
- The target of the specified <literal>Permission</literal>.
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.revoke-permission</literal>
- </para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>
- <literal>revokePermissions()</literal>
- </para>
- </entry>
- <entry>
- <para>
- Each of the targets of the specified list of <literal>Permission</literal>s.
- </para>
- </entry>
- <entry>
- <para>
- <literal>seam.revoke-permission</literal>
- </para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>SSL Security</title>
-
- <para>
- Seam includes basic support for serving sensitive pages via the HTTPS protocol. This is easily
- configured by specifying a <literal>scheme</literal> for the page in <literal>pages.xml</literal>.
- The following example shows how the view <literal>/login.xhtml</literal> is configured to use
- HTTPS:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="/login.xhtml" scheme="https"/>]]></programlisting>
-
- <para>
- This configuration is automatically extended to both <literal>s:link</literal> and
- <literal>s:button</literal> JSF controls, which (when specifying the <literal>view</literal>)
- will also render the link using the correct protocol. Based on the previous example, the following
- link will use the HTTPS protocol because <literal>/login.xhtml</literal> is configured to use it:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<s:link view="/login.xhtml" value="Login"/>]]></programlisting>
-
- <para>
- Browsing directly to a view when using the <emphasis>incorrect</emphasis> protocol will cause a
- redirect to the same view using the <emphasis>correct</emphasis> protocol. For example, browsing
- to a page that has <literal>scheme="https"</literal> using HTTP will cause a redirect to the same
- page using HTTPS.
- </para>
-
- <para>
- It is also possible to configure a <emphasis>default scheme</emphasis> for all pages. This is useful
- if you wish to use HTTPS for a only few pages. If no default scheme is specified then the normal
- behavior is to continue use the current scheme. So once the user accessed a page that required
- HTTPS, then HTTPS would continue to be used after the user navigated away to other non-HTTPS pages.
- (While this is good for security, it is not so great for performance!). To define HTTP as the
- default <literal>scheme</literal>, add this line to <literal>pages.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<page view-id="*" scheme="http" />]]></programlisting>
-
- <para>
- Of course, if <emphasis>none</emphasis> of the pages in your application use HTTPS then it is not
- required to specify a default scheme.
- </para>
-
- <para>
- You may configure Seam to automatically invalidate the current HTTP session each time the scheme
- changes. Just add this line to <literal>components.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<web:session invalidate-on-scheme-change="true"/>]]></programlisting>
-
- <para>
- This option helps make your system less vulnerable to sniffing of the session id or leakage of
- sensitive data from pages using HTTPS to other pages using HTTP.
- </para>
-
- <sect2>
- <title>Overriding the default ports</title>
-
- <para>
- If you wish to configure the HTTP and HTTPS ports manually, they may be configured in
- <literal>pages.xml</literal> by specifying the <literal>http-port</literal> and
- <literal>https-port</literal> attributes on the <literal>pages</literal> element:
- </para>
-
- <programlisting role="XML"><![CDATA[
+}]]>
+</programlisting>
+ <para>
+ For a <literal>Customer</literal> instance with an <literal>id</literal> value of <literal>1</literal>, the value of the identifier would be <literal>Customer:1</literal>. If the entity class is annotated with an explicit identifier name, like so:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Entity @Identifier(name = "cust")
+public class Customer {...}]]>
+</programlisting>
+ <para>
+ Then a <literal>Customer</literal> with an <literal>id</literal> value of <literal>123</literal> would have an identifier value of "<literal>cust:123</literal>".
+ </para>
+ </section>
+
+ </section>
+
+ </section>
+
+ </section>
+
+ <section>
+ <title>Permission Management</title>
+ <para>
+ Just as Seam Security provides an Identity Management API to let you manage users and roles, it also provides a Permissions Management API to let you manage persistent user permissions — the <literal>PermissionManager</literal> component.
+ </para>
+ <section>
+ <title>PermissionManager</title>
+ <para>
+ The <literal>PermissionManager</literal> component is an application-scoped Seam component that provides a number of permission-management methods. It must be configured with a permission store before use. By default, it will attempt to use <literal>JpaPermissionStore</literal>. To configure a custom permission store, specify the <literal>permission-store</literal> property in <filename>components.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<security:permission-manager permission-store="#{ldapPermissionStore}"/>]]>
+</programlisting>
+ <para>
+ The following table describes each of the methods provided by <literal>PermissionManager</literal>:
+ </para>
+ <table>
+ <title>PermissionManager API methods</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <colspec colnum="3" colwidth="1*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Return type
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Method
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Description
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>List<![CDATA[<Permission>]]></literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>listPermissions(Object target, String action)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of <literal>Permission</literal> objects representing all of the permissions that have been granted for the specified target and action.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>List<![CDATA[<Permission>]]></literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>listPermissions(Object target)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of <literal>Permission</literal> objects representing all of the permissions that have been granted for the specified target and action.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>grantPermission(Permission permission)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Persists (grants) the specified <literal>Permission</literal> to the back-end permission store. Returns <literal>true</literal> if the operation succeeds.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>grantPermissions(List<![CDATA[<Permission>]]> permissions)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Persists (grants) the specified list of <literal>Permission</literal>s to the back-end permission store. Returns <literal>true</literal> if the operation succeeds.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>revokePermission(Permission permission)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Removes (revokes) the specified <literal>Permission</literal> from the back-end permission store. Returns <literal>true</literal> if the operation succeeds.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>boolean</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>revokePermissions(List<![CDATA[<Permission>]]> permissions)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Removes (revokes) the specified list of <literal>Permission</literal>s from the back-end permission store. Returns <literal>true</literal> if the operation succeeds.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>List<![CDATA[<String>]]></literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>listAvailableActions(Object target)</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Returns a list of the available actions for the specified target object. The actions that this method returns are dependent on the <literal>@Permission</literal> annotations configured on the target object's class.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Permission checks for PermissionManager operations</title>
+ <para>
+ To invoke <literal>PermissionManager</literal> methods, the currently authenticated user must be authorized to perform that management operation. The following table lists the permissions required to invoke a particular method.
+ </para>
+ <table>
+ <title>Permission Management Security Permissions</title>
+ <tgroup cols="3">
+ <colspec colnum="1" colwidth="1*"></colspec>
+ <colspec colnum="2" colwidth="1*"></colspec>
+ <colspec colnum="3" colwidth="1*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Method
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Permission Target
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Permission Action
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>listPermissions()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The specified <literal>target</literal>.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.read-permissions</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>grantPermission()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The target of the specified <literal>Permission</literal>, or each of the targets for the specified list of <literal>Permission</literal>s (depending on the method called).
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.grant-permission</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>grantPermission()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The target of the specified <literal>Permission</literal>.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.grant-permission</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>grantPermissions()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Each of the targets of the specified list of <literal>Permission</literal>s.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.grant-permission</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>revokePermission()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ The target of the specified <literal>Permission</literal>.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.revoke-permission</literal>
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>revokePermissions()</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Each of the targets of the specified list of <literal>Permission</literal>s.
+ </para>
+ </entry>
+ <entry>
+ <para>
+ <literal>seam.revoke-permission</literal>
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ </section>
+
+ <section>
+ <title>SSL Security</title>
+ <para>
+ Seam includes basic support for serving sensitive pages via the HTTPS protocol. To configure this, specify a <literal>scheme</literal> for the page in <filename>pages.xml</filename>. The following example shows how the view <filename>/login.xhtml</filename> can be configured to use HTTPS:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/login.xhtml" scheme="https"/>]]>
+</programlisting>
+ <para>
+ This configuration automatically extends to both <literal>s:link</literal> and <literal>s:button</literal> JSF controls, which (when specifying the <literal>view</literal>) will render the link under the correct protocol. Based on the previous example, the following link will use the HTTPS protocol because <filename>/login.xhtml</filename> is configured to use it:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<s:link view="/login.xhtml" value="Login"/>]]>
+</programlisting>
+ <para>
+ If a user browses directly to a view with the incorrect protocol, a redirect is triggered, and the same view will be reloaded with the correct protocol. For example, browsing to a <literal>scheme="https"</literal> page with HTTP triggers a redirect to the same page using HTTPS.
+ </para>
+ <para>
+ You can also configure a <emphasis>default scheme</emphasis> for all pages. This is useful if you only want to use HTTPS for a few pages. If no default scheme is specified, the current scheme will be used. So, once the user accesses a page requiring HTTPS, then HTTPS continues to be used after the user has navigated to other non-HTTPS pages. This is good for security, but not for performance. To define HTTP as the default <literal>scheme</literal>, add this line to <filename>pages.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="*" scheme="http" />]]>
+</programlisting>
+ <para>
+ If <emphasis>none</emphasis> of the pages in your application use HTTPS, you need not define a default scheme.
+ </para>
+ <para>
+ You can configure Seam to automatically invalidate the current HTTP session each time the scheme changes. To do so, add this line to <literal>components.xml</literal>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<web:session invalidate-on-scheme-change="true"/>]]>
+</programlisting>
+ <para>
+ This option offers more protection from session ID sniffing and sensitive data leakage from pages using HTTPS to pages using HTTP.
+ </para>
+ <section>
+ <title>Overriding the default ports</title>
+ <para>
+ If you wish to configure the HTTP and HTTPS ports manually, you can do so in <filename>pages.xml</filename> by specifying the <literal>http-port</literal> and <literal>https-port</literal> attributes on the <literal>pages</literal> element:
+ </para>
+
+<programlisting role="XML"><![CDATA[
<pages xmlns="http://jboss.com/products/seam/pages"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://jboss.com/products/seam/pages http://jboss.com/products/seam/pages-2.2.xsd"
no-conversation-view-id="/home.xhtml"
- login-view-id="/login.xhtml"
- http-port="8080"
- https-port="8443">
- ]]></programlisting>
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>CAPTCHA</title>
-
- <para>
- Though strictly not part of the security API, Seam provides a built-in CAPTCHA (<emphasis>C</emphasis>ompletely
- <emphasis>A</emphasis>utomated <emphasis>P</emphasis>ublic <emphasis>T</emphasis>uring test to tell
- <emphasis>C</emphasis>omputers and <emphasis>H</emphasis>umans <emphasis>A</emphasis>part) algorithm to
- prevent automated processes from interacting with your application.
- </para>
-
- <sect2>
- <title>Configuring the CAPTCHA Servlet</title>
- <para>
- To get up and running, it is necessary to configure the Seam Resource Servlet, which will provide the Captcha
- challenge images to your pages. This requires the following entry in <literal>web.xml</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<servlet>
- <servlet-name>Seam Resource Servlet</servlet-name>
- <servlet-class>org.jboss.seam.servlet.SeamResourceServlet</servlet-class>
+ login-view-id="/login.xhtml" http-port="8080" https-port="8443">
+]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section>
+ <title>CAPTCHA</title>
+ <para>
+ Though not strictly part of the security API, Seam provides a built-in CAPTCHA (<emphasis>C</emphasis>ompletely <emphasis>A</emphasis>utomated <emphasis>P</emphasis>ublic <emphasis>T</emphasis>uring test to tell <emphasis>C</emphasis>omputers and <emphasis>H</emphasis>umans <emphasis>A</emphasis>part) algorithm to prevent automated processes from interacting with your application.
+ </para>
+ <section>
+ <title>Configuring the CAPTCHA Servlet</title>
+ <para>
+ To use CAPTCHA, you need to configure the Seam Resource Servlet, which provides your pages with CAPTCHA challenge images. Add the following to <filename>web.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<servlet>
+ <servlet-name>Seam Resource Servlet</servlet-name>
+ <servlet-class>org.jboss.seam.servlet.SeamResourceServlet</servlet-class>
</servlet>
<servlet-mapping>
- <servlet-name>Seam Resource Servlet</servlet-name>
- <url-pattern>/seam/resource/*</url-pattern>
-</servlet-mapping>]]></programlisting>
-
- </sect2>
-
- <sect2>
- <title>Adding a CAPTCHA to a form</title>
-
- <para>
- Adding a CAPTCHA challenge to a form is extremely easy. Here's an example:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:graphicImage value="/seam/resource/captcha"/>
-<h:inputText id="verifyCaptcha" value="#{captcha.response}" required="true">
- <s:validate />
-</h:inputText>
-<h:message for="verifyCaptcha"/>]]></programlisting>
-
- <para>
- That's all there is to it. The <literal>graphicImage</literal> control displays the CAPTCHA challenge,
- and the <literal>inputText</literal> receives the user's response. The response is automatically
- validated against the CAPTCHA when the form is submitted.
- </para>
-
- </sect2>
-
- <sect2>
- <title>Customising the CAPTCHA algorithm</title>
-
- <para>
- You may customize the CAPTCHA algorithm by overriding the built-in component:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("org.jboss.seam.captcha.captcha")
+ <servlet-name>Seam Resource Servlet</servlet-name>
+ <url-pattern>/seam/resource/*</url-pattern>
+</servlet-mapping>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Adding a CAPTCHA to a form</title>
+ <para>
+ It is easy to add a CAPTCHA challenge to a form:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:graphicImage value="/seam/resource/captcha"/>
+ <h:inputText id="verifyCaptcha" value="#{captcha.response}"
+ required="true">
+ <s:validate />
+ </h:inputText>
+<h:message for="verifyCaptcha"/>]]>
+</programlisting>
+ <para>
+ That is all you need to do. The <literal>graphicImage</literal> control displays the CAPTCHA challenge, and the <literal>inputText</literal> receives the user's response. The response is automatically validated against the CAPTCHA when the form is submitted.
+ </para>
+ </section>
+
+ <section>
+ <title>Customising the CAPTCHA algorithm</title>
+ <para>
+ You can customize the CAPTCHA algorithm by overriding the built-in component:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("org.jboss.seam.captcha.captcha")
@Scope(SESSION)
public class HitchhikersCaptcha extends Captcha
{
- @Override @Create
- public void init()
- {
- setChallenge("What is the answer to life, the universe and everything?");
- setCorrectResponse("42");
- }
+ @Override @Create
+ public void init() {
+ setChallenge("What is the answer to life, the universe and everything?");
+ setCorrectResponse("42");
+ }
- @Override
- public BufferedImage renderChallenge()
- {
- BufferedImage img = super.renderChallenge();
- img.getGraphics().drawOval(5, 3, 60, 14); //add an obscuring decoration
- return img;
- }
-}]]></programlisting>
-
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>Security Events</title>
-
- <para>
- The following table describes a number of events (see <xref linkend="events"/>) raised by Seam Security
- in response to certain security-related events.
- </para>
-
- <table>
- <title>Security Events</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="3*" />
- <colspec colnum="2" colwidth="2*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Event Key</para>
- </entry>
- <entry align="center">
- <para>Description</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
-
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.security.loginSuccessful</literal>
- </para>
- </entry>
- <entry>
- <para>
- Raised when a login attempt is successful.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.security.loginFailed</literal>
- </para>
- </entry>
- <entry>
- <para>
- Raised when a login attempt fails.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.security.alreadyLoggedIn</literal>
- </para>
- </entry>
- <entry>
- <para>
- Raised when a user that is already authenticated attempts to log in again.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.security.notLoggedIn</literal>
- </para>
- </entry>
- <entry>
- <para>
- Raised when a security check fails when the user is not logged in.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.security.notAuthorized</literal>
- </para>
- </entry>
- <entry>
- <para>
- Raised when a security check fails when the user is logged in however doesn't have sufficient privileges.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.security.preAuthenticate</literal>
- </para>
- </entry>
- <entry>
- <para>
- Raised just prior to user authentication.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.security.postAuthenticate</literal>
- </para>
- </entry>
- <entry>
- <para>
- Raised just after user authentication.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.security.loggedOut</literal>
- </para>
- </entry>
- <entry>
- <para>
- Raised after the user has logged out.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.security.credentialsUpdated</literal>
- </para>
- </entry>
- <entry>
- <para>
- Raised when the user's credentials have been changed.
- </para>
- </entry>
- </row>
- <row>
- <entry>
- <para>
- <literal>org.jboss.seam.security.rememberMe</literal>
- </para>
- </entry>
- <entry>
- <para>
- Raised when the Identity's rememberMe property is changed.
- </para>
- </entry>
- </row>
-
- </tbody>
- </tgroup>
- </table>
-
- </sect1>
-
- <sect1>
- <title>Run As</title>
-
- <para>
- Sometimes it may be necessary to perform certain operations with elevated privileges, such
- as creating a new user account as an unauthenticated user. Seam Security supports such a
- mechanism via the <literal>RunAsOperation</literal> class. This class allows either the
- <literal>Principal</literal> or <literal>Subject</literal>, or the user's roles to be
- overridden for a single set of operations.
- </para>
-
- <para>
- The following code example demonstrates how <literal>RunAsOperation</literal> is used, by
- calling its <literal>addRole()</literal> method to provide a set of roles to masquerade
- as for the duration of the operation. The <literal>execute()</literal> method contains the
- code that will be executed with the elevated privileges.
- </para>
-
- <programlisting role="JAVA"><![CDATA[ new RunAsOperation() {
- public void execute() {
- executePrivilegedOperation();
- }
- }.addRole("admin")
- .run();]]></programlisting>
-
- <para>
- In a similar way, the <literal>getPrincipal()</literal> or <literal>getSubject()</literal>
- methods can also be overriden to specify the <literal>Principal</literal> and
- <literal>Subject</literal> instances to use for the duration of the operation.
- Finally, the <literal>run()</literal> method is used to carry out the
- <literal>RunAsOperation</literal>.
- </para>
-
- </sect1>
-
- <sect1>
- <title>Extending the Identity component</title>
-
- <para>
- Sometimes it might be necessary to extend the Identity component if your application has
- special security requirements. The following example (contrived, as credentials would normally
- be handled by the <literal>Credentials</literal> component instead) shows an extended Identity
- component with an additional <literal>companyCode</literal> field. The install precendence of <literal>APPLICATION</literal>
- ensures that this extended Identity gets installed in preference to the built-in Identity.
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("org.jboss.seam.security.identity")
+ @Override
+ public BufferedImage renderChallenge() {
+ BufferedImage img = super.renderChallenge();
+ img.getGraphics().drawOval(5, 3, 60, 14); //add an obscuring decoration
+ return img;
+ }
+}]]>
+</programlisting>
+ </section>
+
+ </section>
+
+ <section id="security-security_events">
+ <title>Security Events</title>
+ <para>
+ The following table describes a number of events (see <xref linkend="events" />) raised by Seam Security in response to certain security-related events.
+ </para>
+ <table>
+ <title>Security Events</title>
+ <tgroup cols="2">
+ <colspec colnum="1" colwidth="3*"></colspec>
+ <colspec colnum="2" colwidth="2*"></colspec>
+ <thead>
+ <row>
+ <entry align="center">
+ <para>
+ Event Key
+ </para>
+ </entry>
+ <entry align="center">
+ <para>
+ Description
+ </para>
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.security.loginSuccessful</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Raised when a login attempt is successful.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.security.loginFailed</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Raised when a login attempt fails.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.security.alreadyLoggedIn</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Raised when a user that is already authenticated attempts to log in again.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.security.notLoggedIn</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Raised when a security check fails when the user is not logged in.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.security.notAuthorized</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Raised when a security check fails because the user is logged in, but does not have sufficient privileges.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.security.preAuthenticate</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Raised just prior to user authentication.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.security.postAuthenticate</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Raised just after user authentication.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.security.loggedOut</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Raised after the user has logged out.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.security.credentialsUpdated</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Raised when the user's credentials have been changed.
+ </para>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <para>
+ <literal>org.jboss.seam.security.rememberMe</literal>
+ </para>
+ </entry>
+ <entry>
+ <para>
+ Raised when the Identity's rememberMe property is changed.
+ </para>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ </section>
+
+ <section>
+ <title>Run As</title>
+ <para>
+ Users sometimes need to perform certain operations with elevated privileges — for example, an unauthenticated user may need to create a new user account. Seam Security provides support in this situation with the <literal>RunAsOperation</literal> class. This class allows either the <literal>Principal</literal> or <literal>Subject</literal>, or the user's roles, to be overridden for a single set of operations.
+ </para>
+ <para>
+ The following code demonstrates <literal>RunAsOperation</literal> usage. The <literal>addRole()</literal> method is called to provide a set of roles to 'borrow' for the duration of the operation. The <literal>execute()</literal> method contains the code that will be executed with the elevated privileges.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[
+new RunAsOperation() {
+ public void execute() {
+ executePrivilegedOperation();
+ }
+}.addRole("admin")
+ .run();]]>
+</programlisting>
+ <para>
+ Similarly, the <literal>getPrincipal()</literal> or <literal>getSubject()</literal> methods can also be overriden to specify the <literal>Principal</literal> and <literal>Subject</literal> instances to use for the duration of the operation. Finally, the <literal>run()</literal> method is used to carry out the <literal>RunAsOperation</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Extending the Identity component</title>
+ <para>
+ If your application has special security requirements, you may need to extend your Identity component. The following example shows an Identity component extended with an additional <literal>companyCode</literal> field to handle credentials. (Usually this would be handled by a <literal>Credentials</literal> component.) The install precendence of <literal>APPLICATION</literal> ensures that this extended Identity is installed instead of the built-in Identity.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("org.jboss.seam.security.identity")
@Scope(SESSION)
@Install(precedence = APPLICATION)
@BypassInterceptors
@Startup
-public class CustomIdentity extends Identity
-{
- private static final LogProvider log = Logging.getLogProvider(CustomIdentity.class);
+public class CustomIdentity extends Identity {
+ private static final LogProvider log =
+ Logging.getLogProvider(CustomIdentity.class);
- private String companyCode;
+ private String companyCode;
- public String getCompanyCode()
- {
- return companyCode;
- }
+ public String getCompanyCode() {
+ return companyCode;
+ }
- public void setCompanyCode(String companyCode)
- {
- this.companyCode = companyCode;
- }
+ public void setCompanyCode(String companyCode) {
+ this.companyCode = companyCode;
+ }
- @Override
- public String login()
- {
- log.info("###### CUSTOM LOGIN CALLED ######");
- return super.login();
- }
-}]]></programlisting>
+ @Override
+ public String login() {
+ log.info("###### CUSTOM LOGIN CALLED ######");
+ return super.login();
+ }
+}]]>
+</programlisting>
+ <warning>
+ <para>
+ An <literal>Identity</literal> component must be marked <literal>@Startup</literal> so that it is available immediately after the <literal>SESSION</literal> context begins. Failing to do this may render certain Seam functionality inoperable in your application.
+ </para>
+ </warning>
+ </section>
+
+ <section>
+ <title>OpenID</title>
+ <warning>
+ <title>OpenID integration is a Technology Preview</title>
+ <para>Technology Preview features are not fully supported under Red Hat subscription level agreements (SLAs), may not be functionally complete, and are not intended for production use. However, these features provide early access to upcoming product innovations, enabling customers to test functionality and provide feedback during the development process. As Red Hat considers making future iterations of Technology Preview features generally available, we will provide commercially reasonable efforts to resolve any reported issues that customers experience when using these features.</para>
+ </warning>
- <warning>
- <para>
- Note that an <literal>Identity</literal> component must be marked <literal>@Startup</literal>, so that it is
- available immediately after the <literal>SESSION</literal> context begins. Failing to do this may render
- certain Seam functionality inoperable in your application.
- </para>
- </warning>
-
-
- </sect1>
-
-
- <sect1>
- <title>OpenID</title>
-
- <para>
- OpenID is a community standard for external web-based authentication. The basic
- idea is that any web application can supplement (or replace) its local handling of
- authentication by delegating responsibility to an external OpenID server of the user's
- chosing. This benefits the user, who no longer has to remember a name and password for
- every web application he uses, and the developer, who is relieved of some of the burden of
- maintaining a complex authentication system.
- </para>
-
- <para>When using OpenID, the user selects an OpenID provider, and the provider assigns the user
- an OpenID. The id will take the form of a URL, for example <literal>http://maximoburrito.myopenid.com</literal> however,
- it's acceptable to leave off the <literal>http://</literal> part of the identifier when logging into a site. The web application
- (known as a relying party in OpenID-speak) determines which OpenID server to contact and redirects the user to the remote
- site for authentication. Upon successful authentication the user is given
- the (cryptographically secure) token proving his identity and is redirected back to the original web application.The
- local web application can then be sure the user accessing the application controls the OpenID he presented.
- </para>
-
- <para>
- It's important to realize at this
- point that authentication does not imply authorization. The web application still needs to make a determination of how to
- use that information. The web application could treat the user as instantly logged in and give full access to the system or
- it could try and map the presented OpenID to a local user account, prompting the user to register if he hasn't already.
- The choice of how to handle the OpenID is left as a design decision for the local application.
- </para>
-
-
- <sect2>
- <title>Configuring OpenID</title>
- <para>
- Seam uses the openid4java package and requires four additional JARs to make use of the Seam integration. These
- are: <literal>htmlparser.jar</literal>, <literal>openid4java.jar</literal>, <literal>openxri-client.jar</literal>
- and <literal>openxri-syntax.jar</literal>.
- </para>
-
- <para>
- OpenID processing requires the use of the <literal>OpenIdPhaseListener</literal>, which should be added to your
- <literal>faces-config.xml</literal> file. The phase listener processes the callback from the OpenID provider, allowing
- re-entry into the local application.
- </para>
-
- <programlisting role="XML"><lifecycle>
- <phase-listener>org.jboss.seam.security.openid.OpenIdPhaseListener</phase-listener>
-</lifecycle></programlisting>
-
-
- <para>
- With this configuration, OpenID support is available to your application.
- The OpenID support component, <literal>org.jboss.seam.security.openid.openid</literal>, is installed automatically if the openid4java
- classes are on the classpath.
- </para>
- </sect2>
-
- <sect2>
- <title>Presenting an OpenIdDLogin form</title>
-
- <para>
- To initiate an OpenID login, you can present a simply form to the user asking for the user's OpenID. The <literal>#{openid.id}</literal>
- value
- accepts the user's OpenID and the <literal>#{openid.login}</literal> action initiates an authentication request.
- </para>
- <programlisting role="XML"><h:form>
- <h:inputText value="#{openid.id}" />
- <h:commandButton action="#{openid.login}" value="OpenID Login"/>
-</h:form></programlisting>
-
- <para>
- When the user submits the login form, he will be redirected to his OpenID provider. The user will eventually
- return to your application through the Seam pseudo-view <literal>/openid.xhtml</literal>, which is
- provided by the <literal>OpenIdPhaseListener</literal>. Your application can handle the OpenID response by means
- of a <literal>pages.xml</literal> navigation from that view, just as if the user had never left your application.
- </para>
- </sect2>
-
- <sect2>
- <title>Logging in immediately</title>
-
- <para> The simplest strategy is to simply login the user immediately. The following navigation rule shows how to handle this using
- the <literal>#{openid.loginImmediately()}</literal> action.
- </para>
-
- <programlisting role="XML"><page view-id="/openid.xhtml">
- <navigation evaluate="#{openid.loginImmediately()}">
- <rule if-outcome="true">
- <redirect view-id="/main.xhtml">
- <message>OpenID login successful...</message>
- </redirect>
- </rule>
- <rule if-outcome="false">
- <redirect view-id="/main.xhtml">
- <message>OpenID login rejected...</message>
- </redirect>
- </rule>
- </navigation>
-</page></programlisting>
-
- <para>Thie <literal>loginImmediately()</literal> action checks to see if the OpenID is valid. If it is valid, it adds an
- OpenIDPrincipal to the identity component, marks the user as logged in (i.e. <literal>#{identity.loggedIn}</literal> will be true)
- and returns true. If the OpenID was not validated, the method returns false, and the user re-enters the application un-authenticated.
- If the user's OpenID is valid, it will be accessible using the expression <literal>#{openid.validatedId}</literal> and
- <literal>#{openid.valid}</literal> will be true.
- </para>
-
-
- </sect2>
-
- <sect2>
- <title>Deferring login</title>
-
- <para>
- You may not want the user to be immediately logged in to your application. In that case, your navigation
- should check the <literal>#{openid.valid}</literal> property and redirect the user to a local registration or processing
- page. Actions you might take would be asking for more information and creating a local user account or presenting a captcha
- to avoid programmatic registrations. When you are done processing, if you want to log the user in, you can call
- the <literal>loginImmediately</literal> method, either through EL as shown previously or by directly interaction with the
- <literal>org.jboss.seam.security.openid.OpenId</literal> component. Of course, nothing prevents you from writing custom
- code to interact with the Seam identity component on your own for even more customized behaviour.
- </para>
-
- </sect2>
-
-
- <sect2>
- <title>Logging out</title>
-
- <para>
- Logging out (forgetting an OpenID association) is done by calling <literal>#{openid.logout}</literal>. If you
- are not using Seam security, you can call this method directly. If you are using Seam security, you should
- continue to use <literal>#{identity.logout}</literal> and install an event handler to capture the logout event, calling
- the OpenID logout method.
-
- </para>
- <programlisting role="XML"><event type="org.jboss.seam.security.loggedOut">
- <action execute="#{openid.logout}" />
-</event> </programlisting>
-
- <para>It's important that you do not leave this out or the user will not be able to login again in the same session.</para>
- </sect2>
-
-
-
-
- </sect1>
-
-
+ <para>
+ OpenID is a community standard for external web-based authentication. Any web application can supplement (or replace) its local authentication handling by delegating responsibility to an external OpenID server selected by the user. This benefits both user and developer — the user (who no longer needs to remember login details for multiple web applications), and the developer (who need not maintain an entire complex authentication system).
+ </para>
+ <para>
+ When using OpenID, the user selects an OpenID provider, and the provider assigns the user an OpenID. The ID takes the form of a URL — <literal>http://maximoburrito.myopenid.com</literal>, for example. (The <literal>http://</literal> portion of the identifier can be omitted when logging into a site.) The web application (known as a <emphasis>relying party</emphasis>) determines which OpenID server to contact and redirects the user to the remote site for authentication. When authentication succeeds, the user is given the (cryptographically secure) token proving his identity and is redirected back to the original web application. The local web application can then assume that the user accessing the application owns the OpenID presented.
+ </para>
+ <para>
+ However, authentication does not imply authorization. The web application must still determine how to treat the OpenID authentication. The web application can choose to treat the user as instantly logged in and grant full access to the system, or it can attempt to map the OpenID to a local user account and prompt unregistered users to register. This is a design decision for the local application.
+ </para>
+ <section>
+ <title>Configuring OpenID</title>
+ <para>
+ Seam uses the <literal>opemid4java</literal> package, and requires four additional <filename>JAR</filename>s to make use of Seam integration. These are <filename>htmlparser.jar</filename>, <filename>openid4java.jar</filename>, <filename>openxri-client.jar</filename> and <filename>openxri-syntax.jar</filename>.
+ </para>
+ <para>
+ OpenID processing requires the <literal>OpenIdPhaseListener</literal>, which should be added to your <filename>faces-config.xml</filename> file. The phase listener processes the callback from the OpenID provider, allowing re-entry into the local application.
+ </para>
+
+<programlisting role="XML"><![CDATA[<lifecycle>
+ <phase-listener>
+ org.jboss.seam.security.openid.OpenIdPhaseListener
+ </phase-listener>
+</lifecycle>]]>
+</programlisting>
+ <para>
+ This configuration makes OpenID support available to your application. The OpenID support component, <literal>org.jboss.seam.security.openid.openid</literal>, is installed automatically if the <literal>openid4java</literal> classes are on the classpath.
+ </para>
+ </section>
+
+ <section>
+ <title>Presenting an OpenIdLogin form</title>
+ <para>
+ To initiate an OpenID login, present a form to the user requesting the user's OpenID. The <literal>#{openid.id}</literal> value accepts the user's OpenID and the <literal>#{openid.login}</literal> action initiates an authentication request.
+ </para>
+
+<programlisting role="XML"><![CDATA[<h:form>
+ <h:inputText value="#{openid.id}" />
+ <h:commandButton action="#{openid.login}" value="OpenID Login"/>
+</h:form>]]>
+</programlisting>
+ <para>
+ When the user submits the login form, they are redirected to their OpenID provider. The user eventually returns to your application through the Seam pseudo-view <filename>/openid.xhtml</filename>, provided by the <literal>OpenIdPhaseListener</literal>. Your application can handle the OpenID response with a <filename>pages.xml</filename> navigation from that view, just as if the user had never left your application.
+ </para>
+ </section>
+
+ <section>
+ <title>Logging in immediately</title>
+ <para>
+ The simplest strategy is to simply log the user in immediately. The following navigation rule shows how to handle this using the <literal>#{openid.loginImmediately()}</literal> action.
+ </para>
+
+<programlisting role="XML"><![CDATA[<page view-id="/openid.xhtml">
+ <navigation evaluate="#{openid.loginImmediately()}">
+ <rule if-outcome="true">
+ <redirect view-id="/main.xhtml">
+ <message>OpenID login successful...</message>
+ </redirect>
+ </rule>
+ <rule if-outcome="false">
+ <redirect view-id="/main.xhtml">
+ <message>OpenID login rejected...</message>
+ </redirect>
+ </rule>
+ </navigation>
+</page>]]>
+</programlisting>
+ <para>
+ The <literal>loginImmediately()</literal> action checks whether the OpenID is valid. If it is valid, an <literal>OpenIdPrincipal</literal> is added to the identity component, and the user is marked as logged in (that is, <literal>#{identity.loggedIn}</literal> is marked <literal>true</literal>), and the <literal>loginImmediately()</literal> action returns <literal>true</literal>. If the OpenID is not validated, the method returns <literal>false</literal>, and the user re-enters the application un-authenticated. If the user's OpenID is valid, it will be accessible using the expression <literal>#{openid.validatedId}</literal> and <literal>#{openid.valid}</literal> will be true.
+ </para>
+ </section>
+
+ <section>
+ <title>Deferring login</title>
+ <para>
+ If you do not want the user to be immediately logged in to your application, your navigation should check the <literal>#{openid.valid}</literal> property, and redirect the user to a local registration or processing page. Here, you can ask for more information and create a local user account, or present a CAPTCHA to avoid programmatic registrations. When your process is complete, you can log the user in by calling the <literal>loginImmediately</literal> method, either through EL (as shown previously), or direct interaction with the <literal>org.jboss.seam.security.openid.OpenId</literal> component. You can also write custom code to interact with the Seam identity component to create even more customized behaviour.
+ </para>
+ </section>
+
+ <section>
+ <title>Logging out</title>
+ <para>
+ Logging out (forgetting an OpenID association) is done by calling <literal>#{openid.logout}</literal>. You can call this method directly if you are not using Seam Security. If you are using Seam Security, you should continue to use <literal>#{identity.logout}</literal> and install an event handler to capture the logout event, calling the OpenID logout method.
+ </para>
+
+<programlisting role="XML"><![CDATA[<event type="org.jboss.seam.security.loggedOut">
+ <action execute="#{openid.logout}" />
+</event>]]>
+</programlisting>
+ <para>
+ It is important to include this, or the user will not be able to log in again in the same session.
+ </para>
+ </section>
+
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Spring.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Spring.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Spring.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,405 +1,401 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="spring">
+<chapter id="spring" >
+ <title>Spring Framework integration</title>
+ <para>
+ The Spring Framework is part of the Seam inversion-of-control (IoC) module. It allows easy migration of Spring-based projects to Seam, and benefits Spring applications with Seam features, such as conversations and a more sophisticated persistence context management.
+ </para>
+ <note>
+ <para>
+ The Spring integration code is included in the <literal>jboss-seam-ioc</literal> library. This library is a required dependency for all Seam-Spring integration techniques covered in this chapter.
+ </para>
+ </note>
+ <para>
+ Seam's support for Spring gives you:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Seam component injection into Spring beans,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Spring bean injection into Seam components,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Spring bean to Seam component transformation,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the ability to place Spring beans in any Seam context,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the ability to start a spring WebApplicationContext with a Seam component,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ support for using Spring PlatformTransactionManagement with your Seam-based applications,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ support for using a Seam-managed replacement for Spring's <literal>OpenEntityManagerInViewFilter</literal> and <literal>OpenSessionInViewFilter</literal>, and
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ support for backing <literal>@Asynchronous</literal> calls with Spring <literal>TaskExecutors</literal>.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <section>
+ <title>Injecting Seam components into Spring beans</title>
+ <para>
+ Inject Seam component instances into Spring beans with the <literal><![CDATA[<seam:instance/>]]></literal> namespace handler. To enable the Seam namespace handler, the Seam namespace must first be added to the Spring beans definition file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans"
+ xmlns:seam="http://jboss.com/products/seam/spring-seam"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation=
+ "http://www.springframework.org/schema/beans
+ http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
+ http://jboss.com/products/seam/spring-seam
+ http://jboss.com/products/seam/spring-seam-2.2.xsd">]]>
+</programlisting>
+ <para>
+ Any Seam component can now be injected into any Spring bean, like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<bean id="someSpringBean" class="SomeSpringBeanClass" scope="prototype">
+ <property name="someProperty">
+ <seam:instance name="someComponent"/>
+ </property>
+</bean>]]>
+</programlisting>
+ <para>
+ You can use an EL expression instead of a component name:
+ </para>
+
+<programlisting role="XML"><![CDATA[<bean id="someSpringBean" class="SomeSpringBeanClass" scope="prototype">
+ <property name="someProperty">
+ <seam:instance name="#{someExpression}"/>
+ </property>
+</bean>]]>
+</programlisting>
+ <para>
+ You can inject a Seam component instance into a Spring bean by using a Spring bean ID, like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<seam:instance name="someComponent" id="someSeamComponentInstance"/>
- <title>Spring Framework integration</title>
-
- <para>The Spring integration (part of the Seam IoC module) allows easy migration of Spring-based projects to Seam and allows Spring
- applications to take advantage of key Seam features like conversations and Seam's more sophisticated persistence
- context management.</para>
-
- <para>Note! The Spring integration code is included in the jboss-seam-ioc library. This dependency is required for
- all seam-spring integration techniques covered in this chapter.</para>
-
- <para>Seam's support for Spring provides the ability to: </para>
-
- <itemizedlist>
- <listitem>
- <para>inject Seam component instances into Spring beans</para>
- </listitem>
- <listitem>
- <para>inject Spring beans into Seam components</para>
- </listitem>
- <listitem>
- <para>turn Spring beans into Seam components</para>
- </listitem>
- <listitem>
- <para>allow Spring beans to live in any Seam context</para>
- </listitem>
- <listitem>
- <para>start a spring WebApplicationContext with a Seam component</para>
- </listitem>
- <listitem>
- <para>Support for Spring PlatformTransactionManagement</para>
- </listitem>
- <listitem>
- <para>provides a Seam managed replacement for Spring's <literal>OpenEntityManagerInViewFilter</literal> and <literal>OpenSessionInViewFilter</literal></para>
- </listitem>
- <listitem>
- <para>Support for Spring <literal>TaskExecutors</literal> to back <literal>@Asynchronous</literal> calls</para>
- </listitem>
- </itemizedlist>
-
- <section>
- <title>Injecting Seam components into Spring beans</title>
-
- <para> Injecting Seam component instances into Spring beans is accomplished using the
- <literal><seam:instance/></literal> namespace handler. To enable the Seam namespace
- handler, the Seam namespace must be added to the Spring beans definition file:</para>
-
- <programlisting role="XML"><![CDATA[<beans xmlns="http://www.springframework.org/schema/beans"
- xmlns:seam="http://jboss.com/products/seam/spring-seam"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://www.springframework.org/schema/beans
- http://www.springframework.org/schema/beans/spring-beans-2.0.xsd
- http://jboss.com/products/seam/spring-seam
- http://jboss.com/products/seam/spring-seam-2.2.xsd">]]></programlisting>
-
- <para> Now any Seam component may be injected into any Spring bean: </para>
-
- <programlisting role="XML"><![CDATA[<bean id="someSpringBean" class="SomeSpringBeanClass" scope="prototype">
- <property name="someProperty">
- <seam:instance name="someComponent"/>
- </property>
-</bean>]]></programlisting>
-
- <para> An EL expression may be used instead of a component name: </para>
-
- <programlisting role="XML"><![CDATA[<bean id="someSpringBean" class="SomeSpringBeanClass" scope="prototype">
- <property name="someProperty">
- <seam:instance name="#{someExpression}"/>
- </property>
-</bean>]]></programlisting>
-
- <para> Seam component instances may even be made available for injection into Spring beans by a Spring bean id. </para>
-
- <programlisting role="XML"><![CDATA[<seam:instance name="someComponent" id="someSeamComponentInstance"/>
-
<bean id="someSpringBean" class="SomeSpringBeanClass" scope="prototype">
- <property name="someProperty" ref="someSeamComponentInstance">
+ <property name="someProperty" ref="someSeamComponentInstance">
</bean>
-]]></programlisting>
+]]>
+</programlisting>
+ <para>
+ However, Spring, unlike Seam, was not designed to support a stateful component model with multiple contexts. Spring injection does not occur at method invocation time, but when the Spring bean is instantiated.
+ </para>
+ <para>
+ The instance available when the bean is instantiated will be used for the entire life of the bean. Say you inject a Seam conversation-scoped component instance directly into a singleton Spring bean — that singleton will hold a reference to the same instance long after the conversation is over. This is called <emphasis>scope impedance</emphasis>.
+ </para>
+ <para>
+ Seam bijection maintains scope impedance naturally as an invocation flows through the system. In Spring, we must inject a proxy of the Seam component, and resolve the reference when the proxy is invoked.
+ </para>
+ <para>
+ The <literal><![CDATA[<seam:instance/>]]></literal> tag lets us automatically proxy the Seam component.
+ </para>
+
+<programlisting role="XML"><![CDATA[<seam:instance id="seamManagedEM"
+ name="someManagedEMComponent"
+ proxy="true"/>
- <para>Now for the caveat!</para>
-
- <para> Seam was designed from the ground up to support a stateful component model with multiple contexts. Spring
- was not. Unlike Seam bijection, Spring injection does not occur at method invocation time. Instead,
- injection happens only when the Spring bean is instantiated. So the instance available when the bean is
- instantiated will be the same instance that the bean uses for the entire life of the bean. For example, if a
- Seam <literal>CONVERSATION</literal>-scoped component instance is directly injected into a singleton Spring
- bean, that singleton will hold a reference to the same instance long after the conversation is over! We call
- this problem <emphasis>scope impedance</emphasis>. Seam bijection ensures that scope impedance is maintained
- naturally as an invocation flows through the system. In Spring, we need to inject a proxy of the Seam
- component, and resolve the reference when the proxy is invoked.</para>
-
- <para>The <literal><seam:instance/></literal> tag lets us automatically proxy the Seam component.</para>
-
- <programlisting role="XML"><![CDATA[<seam:instance id="seamManagedEM" name="someManagedEMComponent" proxy="true"/>
-
<bean id="someSpringBean" class="SomeSpringBeanClass">
- <property name="entityManager" ref="seamManagedEM">
-</bean>]]></programlisting>
-
- <para> This example shows one way to use a Seam-managed persistence context from a Spring bean. (For a more robust
- way to use Seam-managed persistence contexts as a replacement for the Spring
- <literal>OpenEntityManagerInView</literal> filter see section on
- <link linkend="spring-persistence">Using a Seam Managed Persistence Context in Spring</link>)</para>
- </section>
-
- <section>
- <title>Injecting Spring beans into Seam components</title>
-
- <para> It is even easier to inject Spring beans into Seam component instances. Actually, there are two possible
- approaches: </para>
-
- <itemizedlist>
- <listitem>
- <para> inject a Spring bean using an EL expression </para>
- </listitem>
- <listitem>
- <para> make the Spring bean a Seam component </para>
- </listitem>
- </itemizedlist>
-
- <para> We'll discuss the second option in the next section. The easiest approach is to access the Spring beans
- via EL. </para>
-
- <para> The Spring <literal>DelegatingVariableResolver</literal> is an integration point Spring provides for
- integrating Spring with JSF. This <literal>VariableResolver</literal> makes all Spring beans available in EL
- by their bean id. You'll need to add the <literal>DelegatingVariableResolver</literal> to
- <literal>faces-config.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<application>
- <variable-resolver>
- org.springframework.web.jsf.DelegatingVariableResolver
- </variable-resolver>
-</application>]]></programlisting>
-
- <para> Then you can inject Spring beans using <literal>@In</literal>: </para>
-
- <programlisting role="JAVA"><![CDATA[@In("#{bookingService}")
-private BookingService bookingService;]]></programlisting>
-
- <para>The use of Spring beans in EL is not limited to injection. Spring beans may be used anywhere that EL
- expressions are used in Seam: process and pageflow definitions, working memory assertions, etc... </para>
-
- </section>
-
- <section>
- <title>Making a Spring bean into a Seam component</title>
-
- <para> The <literal><seam:component/></literal> namespace handler can be used to make any Spring
- bean a Seam component. Just place the <literal><seam:component/></literal> tag within the
- declaration of the bean that you wish to be a Seam component: </para>
-
- <programlisting role="XML"><![CDATA[<bean id="someSpringBean" class="SomeSpringBeanClass" scope="prototype">
- <seam:component/>
-</bean>]]></programlisting>
-
- <para> By default, <literal><seam:component/></literal> will create a <literal>STATELESS</literal>
- Seam component with class and name provided in the bean definition. Occasionally, such as when a
- <literal>FactoryBean</literal> is used, the class of the Spring bean may not be the class appearing in
- the bean definition. In such cases the <literal>class</literal> should be explicitly specified. A Seam
- component name may be explicitly specified in cases where there is potential for a naming conflict. </para>
-
- <para> The <literal>scope</literal> attribute of <literal><seam:component/></literal> may be used
- if you wish the Spring bean to be managed in a particular Seam scope. The Spring bean must be scoped to
- <literal>prototype</literal> if the Seam scope specified is anything other than
- <literal>STATELESS</literal>. Pre-existing Spring beans usually have a fundamentally stateless character, so
- this attribute is not usually needed. </para>
-
- </section>
-
- <section>
- <title>Seam-scoped Spring beans</title>
-
- <para> The Seam integration package also lets you use Seam's contexts as Spring 2.0 style custom scopes. This
- lets you declare any Spring bean in any of Seam's contexts. However, note once again that Spring's component
- model was never architected to support statefulness, so please use this feature with great care. In
- particular, clustering of session or conversation scoped Spring beans is deeply problematic, and care must
- be taken when injecting a bean or component from a wider scope into a bean of a narrower scope.</para>
-
- <para> By specifying <literal><seam:configure-scopes/></literal> once in a Spring bean factory
- configuration, all of the Seam scopes will be available to Spring beans as custom scopes. To associate a
- Spring bean with a particular Seam scope, specify the Seam scope in the <literal>scope</literal> attribute
- of the bean definition. </para>
-
- <programlisting role="XML"><![CDATA[<!-- Only needs to be specified once per bean factory-->
+ <property name="entityManager" ref="seamManagedEM">
+</bean>]]>
+</programlisting>
+ <para>
+ Here, we see one example of using a Seam-managed persistence context from a Spring bean. See the section on <xref linkend="spring-persistence" /> for a more robust way to use Seam-managed persistence contexts as a replacement for the Spring <literal>OpenEntityManagerInView</literal> filter.
+ </para>
+ </section>
+
+ <section>
+ <title>Injecting Spring beans into Seam components</title>
+ <para>
+ You can inject a Spring bean into a Seam component instance either by using an EL expression, or by making the Spring bean a Seam component.
+ </para>
+ <para>
+ The simplest approach is to access the Spring beans with EL.
+ </para>
+ <para>
+ The Spring <literal>DelegatingVariableResolver</literal> assists Spring integration with JavaServer Faces (JSF). This <literal>VariableResolver</literal> uses EL with bean IDs to make Spring beans available to JSF. You will need to add the <literal>DelegatingVariableResolver</literal> to <filename>faces-config.xml</filename>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<application>
+ <variable-resolver>
+ org.springframework.web.jsf.DelegatingVariableResolver
+ </variable-resolver>
+</application>]]>
+</programlisting>
+ <para>
+ You can then inject Spring beans using <literal>@In</literal>:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@In("#{bookingService}")
+private BookingService bookingService;]]>
+</programlisting>
+ <para>
+ Spring beans are not limited to injection. They can be used wherever EL expressions are used in Seam: process and pageflow definitions, working memory assertions, etc.
+ </para>
+ </section>
+
+ <section>
+ <title>Making a Spring bean into a Seam component</title>
+ <para>
+ The <literal><![CDATA[<seam:component/>]]></literal> namespace handler can be used to transform any Spring bean into a Seam component. Just add the <literal><![CDATA[<seam:component/>]]></literal> tag to the declaration of the bean that you want to make into a Seam component:
+ </para>
+
+<programlisting role="XML"><![CDATA[<bean id="someSpringBean" class="SomeSpringBeanClass" scope="prototype">
+ <seam:component/>
+</bean>
+]]>
+</programlisting>
+ <para>
+ By default, <literal><![CDATA[<seam:component/>]]></literal> creates a stateless Seam component with the class and name provided in the bean definition. Occasionally — when a <literal>FactoryBean</literal> is used, for example — the Spring bean class may differ from the class listed in the bean definition. In this case, specify the <literal>class</literal> explicitly. You should also explicitly specify a Seam component name where there is a potential naming conflict.
+ </para>
+ <para>
+ If you want the Spring bean to be managed in a particular Seam scope, use the <literal>scope</literal> attribute of <literal><![CDATA[<seam:component/>]]></literal>. If the Seam scope specified is anything other than <literal>STATELESS</literal>, you must scope your Spring bean to <literal>prototype</literal>. Pre-existing Spring beans usually have a fundamentally stateless character, so this attribute is not usually necessary.
+ </para>
+ </section>
+
+ <section>
+ <title>Seam-scoped Spring beans</title>
+ <para>
+ With the Seam integration package, you can also use Seam's contexts as Spring 2.0-style <emphasis>custom scopes</emphasis>, which lets you declare any Spring bean in any Seam context. However, because Spring's component model was not built to support statefulness, this feature should be used with care. In particular, there are problems with clustering session- or conversation-scoped Spring beans, and care must be taken when injecting a bean or component from a wider scope into a bean of narrower scope.
+ </para>
+ <para>
+ Specify <literal><![CDATA[<seam:configure-scopes/>]]></literal> in a Spring bean factory configuration to make all Seam scopes available to Spring beans as custom scopes. To associate a Spring bean with a particular Seam scope, specify the desired scope in the <literal>scope</literal> attribute of the bean definition.
+ </para>
+
+<programlisting role="XML"><![CDATA[<!-- Only needs to be specified once per bean factory-->
<seam:configure-scopes/>
...
-<bean id="someSpringBean" class="SomeSpringBeanClass" scope="seam.CONVERSATION"/>]]></programlisting>
+<bean id="someSpringBean" class="SomeSpringBeanClass"
+ scope="seam.CONVERSATION"/>]]>
+</programlisting>
+ <para>
+ You can change the scope name's prefix by specifying the <literal>prefix</literal> attribute in the <literal>configure-scopes</literal> definition. (The default prefix is <literal>seam.</literal>.)
+ </para>
+ <para>
+ By default, a Spring component instance that is registered this way is not created automatically when referenced with <literal>@In</literal>. To automatically create an instance, you must either specify <literal>@In(create=true)</literal> at the injection point (to auto-create a specific bean), or use the <literal>default-auto-create</literal> attribute of <literal>configure-scopes</literal> to auto-create all Seam-scoped Spring beans.
+ </para>
+ <para>
+ The latter approach lets you inject Seam-scoped Spring beans into other Spring beans without using <literal><![CDATA[<seam:instance/>]]></literal>. However, you must be careful to maintain scope impedance. Normally, you would specify <literal><![CDATA[<aop:scoped-proxy/>]]></literal> in the bean definition, but Seam-scoped Spring beans are not compatible with <literal><![CDATA[<aop:scoped-proxy/>]]></literal>. Therefore, to inject a Seam-scoped Spring bean into a singleton, use <literal><![CDATA[<seam:instance/>]]></literal>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<bean id="someSpringBean" class="SomeSpringBeanClass" scope="seam.CONVERSATION"/>
- <para> The prefix of the scope name may be changed by specifying the <literal>prefix</literal> attribute in the
- <literal>configure-scopes</literal> definition. (The default prefix is <literal>seam.</literal>) </para>
-
- <para> By default an instance of a Spring Component registered in this way is not automatically created when
- referenced using <literal>@In</literal>. To have an instance auto-created you must either specify <literal>@In(create=true)</literal>
- at the injection point to identify a specific bean to be auto created or you can use the <literal>default-auto-create</literal>
- attribute of <literal>configure-scopes</literal> to make all spring beans who use a seam scope auto created.</para>
-
- <para> Seam-scoped Spring beans defined this way can be injected into other Spring beans without the use of
- <literal><seam:instance/></literal>. However, care must be taken to ensure scope impedance
- is maintained. The normal approach used in Spring is to specify
- <literal><aop:scoped-proxy/></literal> in the bean definition. However, Seam-scoped Spring
- beans are <emphasis>not</emphasis> compatible with <literal><aop:scoped-proxy/></literal>. So
- if you need to inject a Seam-scoped Spring bean into a singleton,
- <literal><seam:instance/></literal> must be used: </para>
-
- <programlisting role="XML"><![CDATA[<bean id="someSpringBean" class="SomeSpringBeanClass" scope="seam.CONVERSATION"/>
-
...
<bean id="someSingleton">
- <property name="someSeamScopedSpringBean">
- <seam:instance name="someSpringBean" proxy="true"/>
- </property>
-</bean>]]></programlisting>
-
- </section>
- <section id="spring-transactions">
- <title>Using Spring PlatformTransactionManagement</title>
-
- <para>Spring provides an extensible transaction management abstraction with support for many
- transaction APIs (JPA, Hibernate, JDO, and JTA) Spring also provides tight integrations with many application
- server TransactionManagers such as Websphere and Weblogic. Spring
- transaction management exposes support for many advanced features such as nested
- transactions and supports full Java EE transaction propagation rules like REQUIRES_NEW and NOT_SUPPORTED. For more
- information see the spring documentation
- <ulink url="http://static.springframework.org/spring/docs/2.0.x/reference/transaction.html">here</ulink>.</para>
-
- <para>To configure Seam to use Spring transactions enable the SpringTransaction component like so:</para>
-
- <programlisting role="XML"><![CDATA[<spring:spring-transaction platform-transaction-manager="#{transactionManager}"/>]]></programlisting>
-
- <para>
- The <literal>spring:spring-transaction</literal> component will utilize Springs transaction synchronization
- capabilities for synchronization callbacks.
+ <property name="someSeamScopedSpringBean">
+ <seam:instance name="someSpringBean" proxy="true"/>
+ </property>
+</bean>]]>
+</programlisting>
+ </section>
+
+ <section id="spring-transactions">
+ <title>Using Spring PlatformTransactionManagement</title>
+ <para>
+ Spring's extensible transaction management provides support for many transaction APIs, including the Java Persistence API (JPA), Hibernate, Java Data Objects (JDO), and Java Transaction API (JTA). It also exposes support for many advanced features such as nested transactions. Spring also provides tight integration with many application server TransactionManagers, such as Websphere and Weblogic, and supports full Java EE transaction propagation rules, such as <literal>REQUIRES_NEW</literal> and <literal>NOT_SUPPORTED</literal>. See the <ulink url="http://static.springframework.org/spring/docs/2.0.x/reference/ transaction.html">Spring Documentation</ulink> for further information.
</para>
- </section>
- <section id="spring-persistence">
- <title>Using a Seam Managed Persistence Context in Spring</title>
-
- <para>One of the most powerful features of Seam is its conversation scope and the ability to
- have an EntityManager open for the life of a conversation. This eliminates many
- of the problems associated with the detachment and re-attachment of entities as well as mitigates occurrences
- of the dreaded <literal>LazyInitializationException</literal>. Spring does not provide a way to manage
- an persistence context beyond the scope of a single web request
- (<literal>OpenEntityManagerInViewFilter</literal>). So, it would be nice if Spring developers
- could have access to a Seam managed persistence context using all of the same tools Spring provides
- for integration with JPA(e.g. <literal>PersistenceAnnotationBeanPostProcessor</literal>,
- <literal>JpaTemplate</literal>, etc.)</para>
-
- <para>Seam provides a way for Spring to access a Seam managed persistence context with
- Spring's provided JPA tools bringing conversation scoped persistence context capabilities to
- Spring applications.</para>
-
- <para>This integration work provides the following functionality:</para>
-
- <itemizedlist>
- <listitem>
- <para>transparent access to a Seam managed persistence context using Spring provided tools</para>
- </listitem>
- <listitem>
- <para>access to Seam conversation scoped persistence contexts in a non web request
- (e.g. asynchronous quartz job)</para>
- </listitem>
- <listitem>
- <para>allows for using Seam managed persistence contexts with Spring managed transactions (will need to
- flush the persistence context manually)</para>
- </listitem>
- </itemizedlist>
-
- <para>Spring's persistence context propagation model allows only one open EntityManager per EntityManagerFactory
- so the Seam integration works by wrapping an EntityManagerFactory around a Seam managed persistence
- context.</para>
-
- <programlisting role="XML"><![CDATA[<bean id="seamEntityManagerFactory" class="org.jboss.seam.ioc.spring.SeamManagedEntityManagerFactoryBean">
- <property name="persistenceContextName" value="entityManager"/>
-</bean>]]></programlisting>
-
- <para>Where 'persistenceContextName' is the name of the Seam managed persistence context component. By default
- this EntityManagerFactory has a unitName equal to the Seam component name or in this case 'entityManager'.
- If you wish to provide a different unitName you can do so by providing a persistenceUnitName like so:
+ <para>
+ To configure Seam to use Spring transactions, enable the <literal>SpringTransaction</literal> component, like so:
</para>
-
- <programlisting role="XML"><![CDATA[<bean id="seamEntityManagerFactory" class="org.jboss.seam.ioc.spring.SeamManagedEntityManagerFactoryBean">
- <property name="persistenceContextName" value="entityManager"/>
- <property name="persistenceUnitName" value="bookingDatabase:extended"/>
-</bean>]]></programlisting>
-
- <para>This EntityManagerFactory can then be used in any Spring provided tools. For example,
- using Spring's <literal>PersistenceAnnotationBeanPostProcessor</literal> is the exact same as before.</para>
-
- <programlisting role="XML"><![CDATA[<bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor"/>]]></programlisting>
-
- <para>If you define your real EntityManagerFactory in Spring but wish to use a Seam managed persistence context
- you can tell the <literal>PersistenceAnnotationBeanPostProcessor</literal> which persistenctUnitName you wish
- to use by default by specifying the <literal>defaultPersistenceUnitName</literal> property.
+
+<programlisting role="XML"><![CDATA[<spring:spring-transaction
+ platform-transaction-manager="#{transactionManager}"/>]]>
+</programlisting>
+ <para>
+ The <literal>spring:spring-transaction</literal> component will utilizes Spring's transaction synchronization capabilities for synchronization callbacks.
</para>
-
- <para>The <literal>applicationContext.xml</literal> might look like:</para>
- <programlisting role="XML"><![CDATA[<bean id="entityManagerFactory" class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean">
- <property name="persistenceUnitName" value="bookingDatabase"/>
+ </section>
+
+ <section id="spring-persistence">
+ <title>Using a Seam-Managed Persistence Context in Spring</title>
+ <para>
+ Some of Seam's most powerful features are its conversation scope, and the ability to keep an <literal>EntityManager</literal> open for the life of a conversation. These eliminate many problems associated with detaching and reattaching entities, and mitigate the occurrence of <exceptionname>LazyInitializationException</exceptionname>. Spring does not provide a way to manage persistence contexts beyond the scope of a single web request (<literal>OpenEntityManagerInViewFilter</literal>).
+ </para>
+ <para>
+ Seam brings conversation-scoped persistence context capabilities to Spring applications by allowing Spring developers to access a Seam-managed persistence context with the JPA tools provided with Spring (<literal>PersistenceAnnotationBeanPostProcessor</literal>, <literal>JpaTemplate</literal>, etc.)
+ </para>
+ <para>
+ This integration work provides:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ transparent access to a Seam-managed persistence context using Spring-provided tools
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ access to Seam conversation-scoped persistence contexts in a non-web request — for example, an asynchronous Quartz job
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the ability to use Seam-managed persistence contexts with Spring-managed transactions. This requires manual flushing of the persistenct context.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Spring's persistence context propagation model allows only one open <literal>EntityManager</literal> per <literal>EntityManagerFactory</literal>, so the Seam integration works by wrapping an <literal>EntityManagerFactory</literal> around a Seam-managed persistence context, like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<bean id="seamEntityManagerFactory"
+ class="org.jboss.seam.ioc.spring.SeamManagedEntityManagerFactoryBean">
+ <property name="persistenceContextName" value="entityManager"/>
+</bean>]]>
+</programlisting>
+ <para>
+ Here, <literal>persistenceContextName</literal> is the name of the Seam-managed persistence context component. By default, this <literal>EntityManagerFactory</literal> has a <literal>unitName</literal> equal to the Seam component name — in this case, <literal>entityManager</literal>. If you wish to provide a different <literal>unitName</literal>, you can provide a <literal>persistenceUnitName</literal> like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<bean id="seamEntityManagerFactory"
+ class="org.jboss.seam.ioc.spring.SeamManagedEntityManagerFactoryBean">
+ <property name="persistenceContextName" value="entityManager"/>
+ <property name="persistenceUnitName" value="bookingDatabase:extended"/>
+</bean>]]>
+</programlisting>
+ <para>
+ This <literal>EntityManagerFactory</literal> can now be used in any Spring-provided tools; in this case, you can use Spring's <literal>PersistenceAnnotationBeanPostProcessor</literal> just as you would in Spring.
+ </para>
+
+<programlisting role="XML"><![CDATA[<bean class="org.springframework.orm.jpa.support
+ .PersistenceAnnotationBeanPostProcessor"/>]]>
+</programlisting>
+ <para>
+ If you define your real <literal>EntityManagerFactory</literal> in Spring, but wish to use a Seam-managed persistence context, you can tell the <literal>PersistenceAnnotationBeanPostProcessor</literal> your desired default <literal>persistenctUnitName</literal> by specifying the <literal>defaultPersistenceUnitName</literal> property.
+ </para>
+ <para>
+ The <filename>applicationContext.xml</filename> might look like:
+ </para>
+
+<programlisting role="XML"><![CDATA[<bean id="entityManagerFactory"
+ class="org.springframework.orm.jpa.LocalEntityManagerFactoryBean">
+ <property name="persistenceUnitName" value="bookingDatabase"/>
</bean>
-<bean id="seamEntityManagerFactory" class="org.jboss.seam.ioc.spring.SeamManagedEntityManagerFactoryBean">
- <property name="persistenceContextName" value="entityManager"/>
- <property name="persistenceUnitName" value="bookingDatabase:extended"/>
+<bean id="seamEntityManagerFactory"
+ class="org.jboss.seam.ioc.spring.SeamManagedEntityManagerFactoryBean">
+ <property name="persistenceContextName" value="entityManager"/>
+ <property name="persistenceUnitName" value="bookingDatabase:extended"/>
</bean>
-<bean class="org.springframework.orm.jpa.support.PersistenceAnnotationBeanPostProcessor">
- <property name="defaultPersistenceUnitName" value="bookingDatabase:extended"/>
-</bean>]]></programlisting>
-
- <para>The <literal>component.xml</literal> might look like:</para>
- <programlisting role="XML"><![CDATA[<persistence:managed-persistence-context name="entityManager"
- auto-create="true" entity-manager-factory="#{entityManagerFactory}"/>]]></programlisting>
-
-
- <para><literal>JpaTemplate</literal> and <literal>JpaDaoSupport</literal> are configured the same way for a
- Seam managed persistence context as they would be fore a Seam managed persistence context.</para>
-
- <programlisting role="XML"><![CDATA[<bean id="bookingService" class="org.jboss.seam.example.spring.BookingService">
- <property name="entityManagerFactory" ref="seamEntityManagerFactory"/>
-</bean>]]></programlisting>
- </section>
- <section id="spring-hibernate">
- <title>Using a Seam Managed Hibernate Session in Spring</title>
-
- <para>The Seam Spring integration also provides support for complete access to a Seam managed Hibernate session
- using spring's tools. This integration is very similar to the <link linkend="spring-persistence">JPA integration</link>.</para>
-
- <para>Like Spring's JPA integration spring's propagation model allows only one open EntityManager per
- EntityManagerFactory per transaction??? to be available to spring tools. So, the Seam Session integration works
- by wrapping a proxy SessionFactory around a Seam managed Hibernate session
- context.</para>
-
- <programlisting role="XML"><![CDATA[<bean id="seamSessionFactory" class="org.jboss.seam.ioc.spring.SeamManagedSessionFactoryBean">
- <property name="sessionName" value="hibernateSession"/>
-</bean>]]></programlisting>
-
- <para>Where 'sessionName' is the name of the <literal>persistence:managed-hibernate-session</literal> component.
- This SessionFactory can then be used in any Spring provided tools. The integration
- also provides support for calls to <literal>SessionFactory.getCurrentInstance()</literal> as long as you call
- getCurrentInstance() on the <literal>SeamManagedSessionFactory</literal>.</para>
- </section>
- <section>
- <title>Spring Application Context as a Seam Component</title>
-
- <para> Although it is possible to use the Spring <literal>ContextLoaderListener</literal> to start your
- application's Spring ApplicationContext there are a couple of limitations.</para>
-
- <itemizedlist>
- <listitem>
- <para> the Spring ApplicationContext must be started <emphasis>after</emphasis> the
- <literal>SeamListener</literal> </para>
- </listitem>
- <listitem>
- <para> it can be tricky starting a Spring ApplicationContext for use in Seam unit and integration
- tests </para>
- </listitem>
- </itemizedlist>
-
- <para> To overcome these two limitations the Spring integration includes a Seam component that will start a
- Spring ApplicationContext. To use this Seam component place the
- <literal><spring:context-loader/></literal> definition in the <literal>components.xml</literal>.
- Specify your Spring context file location in the <literal>config-locations</literal> attribute. If more
- than one config file is needed you can place them in the nested
- <literal><spring:config-locations/></literal> element following standard
- <literal>components.xml</literal> multi value practices. </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+<bean class="org.springframework.orm.jpa
+ .support.PersistenceAnnotationBeanPostProcessor">
+ <property name="defaultPersistenceUnitName"
+ value="bookingDatabase:extended"/>
+</bean>]]>
+</programlisting>
+ <para>
+ The <filename>component.xml</filename> might look like:
+ </para>
+
+<programlisting role="XML"><![CDATA[<persistence:managed-persistence-context name="entityManager"
+ auto-create="true" entity-manager-factory="#{entityManagerFactory}"/>]]>
+</programlisting>
+ <para>
+ <literal>JpaTemplate</literal> and <literal>JpaDaoSupport</literal> have an identical configuration in a Spring-based persistence context and in a normal Seam-managed persistence context.<!-- #modify: Please confirm; the original paragraph had two identical terms. -->
+ </para>
+
+<programlisting role="XML"><![CDATA[<bean id="bookingService"
+ class="org.jboss.seam.example.spring.BookingService">
+ <property name="entityManagerFactory" ref="seamEntityManagerFactory"/>
+</bean>]]>
+</programlisting>
+ </section>
+
+ <section id="spring-hibernate">
+ <title>Using a Seam-Managed Hibernate Session in Spring</title>
+ <para>
+ Spring integration into Seam also provides support for complete Spring tool access to a Seam-managed Hibernate session. This integration is very similar to the JPA integration — see <xref linkend="spring-persistence" /> for details.
+ </para>
+ <para>
+ Spring's propagation model allows only one open <literal>EntityManager</literal> per <literal>EntityManagerFactory</literal> to be available to Spring tools, so Seam integrates by wrapping a proxy <literal>SessionFactory</literal> around a Seam-managed Hibernate session context.
+ </para>
+
+<programlisting role="XML"><![CDATA[<bean id="seamSessionFactory"
+ class="org.jboss.seam.ioc.spring.SeamManagedSessionFactoryBean">
+ <property name="sessionName" value="hibernateSession"/>
+</bean>]]>
+</programlisting>
+ <para>
+ Here, <literal>sessionName</literal> is the name of the <literal>persistence:managed-hibernate-session</literal> component. This <literal>SessionFactory</literal> can then be used with any Spring-provided tool. The integration also provides support for calls to <literal>SessionFactory.getCurrentInstance()</literal>, provided that <literal>getCurrentInstance()</literal> is called on the <literal>SeamManagedSessionFactory</literal>.
+ </para>
+ </section>
+
+ <section>
+ <title>Spring Application Context as a Seam Component</title>
+ <para>
+ Although it is possible to use the Spring <literal>ContextLoaderListener</literal> to start your application's Spring <literal>ApplicationContext</literal>, there are some limitations: the Spring <literal>ApplicationContext</literal> must be started after the <literal>SeamListener</literal>, and starting a Spring <literal>ApplicationContext</literal> for use in Seam unit and integration tests can be complicated.
+ </para>
+ <para>
+ To overcome these limitations, the Spring integration includes a Seam component that can start a Spring <literal>ApplicationContext</literal>. To use this component, place the <literal><![CDATA[<spring:context-loader/>]]></literal> definition in the <filename>components.xml</filename> file. Specify your Spring context file location in the <literal>config-locations</literal> attribute. If more than one configuration file is required, you can place them in the nested <literal><![CDATA[<spring:config-locations/>]]></literal> element, as per standard <filename>components.xml</filename> multi-value practices.
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
xmlns:spring="http://jboss.com/products/seam/spring"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://jboss.com/products/seam/components
- http://jboss.com/products/seam/components-2.2.xsd
- http://jboss.com/products/seam/spring
- http://jboss.com/products/seam/spring-2.2.xsd">
+ xsi:schemaLocation=
+ "http://jboss.com/products/seam/components
+ http://jboss.com/products/seam/components-2.2.xsd
+ http://jboss.com/products/seam/spring
+ http://jboss.com/products/seam/spring-2.2.xsd">
- <spring:context-loader config-locations="/WEB-INF/applicationContext.xml"/>
+ <spring:context-loader config-locations=
+ "/WEB-INF/applicationContext.xml"/>
-</components>]]></programlisting>
- </section>
- <section>
- <title>Using a Spring TaskExecutor for @Asynchronous</title>
-
- <para>Spring provides an abstraction for executing code asynchronously called a <literal>TaskExecutor</literal>.
- The Spring Seam integration allows for the use of a Spring <literal>TaskExecutor</literal> for executing
- immediate <literal>@Asynchronous</literal> method calls. To enable this functionality install the
- <literal>SpringTaskExecutorDispatchor</literal> and provide a spring bean defined taskExecutor like so:</para>
-
- <programlisting role="XML"><![CDATA[<spring:task-executor-dispatcher task-executor="#{springThreadPoolTaskExecutor}"/>]]></programlisting>
-
- <para>Because a Spring <literal>TaskExecutor</literal> does not support scheduling of an asynchronous event
- a fallback Seam <literal>Dispatcher</literal> can be provided to handle scheduled asynchronous event like so:</para>
-
- <programlisting role="XML">
- <![CDATA[<!-- Install a ThreadPoolDispatcher to handle scheduled asynchronous event -->
+</components>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Using a Spring TaskExecutor for <literal>@Asynchronous</literal></title>
+ <para>
+ Spring provides an abstraction for executing code asynchronously, called a <literal>TaskExecutor</literal>. The Spring-Seam integration lets you use a Spring <literal>TaskExecutor</literal> to execute immediate <literal>@Asynchronous</literal> method calls. To enable this functionality, install the <literal>SpringTaskExecutorDispatchor</literal> and provide a Spring -bean defined <literal>taskExecutor</literal> like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<spring:task-executor-dispatcher
+ task-executor="#{springThreadPoolTaskExecutor}"/>]]>
+</programlisting>
+ <para>
+ Because a Spring <literal>TaskExecutor</literal> does not support scheduling asynchronous events, you can provide handling with a fallback Seam <literal>Dispatcher</literal>, like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<!--
+ Install a ThreadPoolDispatcher to handle scheduled asynchronous event
+-->
<core:thread-pool-dispatcher name="threadPoolDispatcher"/>
<!-- Install the SpringDispatcher as default -->
-<spring:task-executor-dispatcher task-executor="#{springThreadPoolTaskExecutor}" schedule-dispatcher="#{threadPoolDispatcher}"/>]]>
- </programlisting>
- </section>
+<spring:task-executor-dispatcher
+ task-executor="#{springThreadPoolTaskExecutor}"
+ schedule-dispatcher="#{threadPoolDispatcher}"/>]]>
+</programlisting>
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Testing.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Testing.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Testing.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,678 +1,541 @@
-<chapter id="testing">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
+
+<chapter id="testing" >
<title>Testing Seam applications</title>
- <para>
- Most Seam applications will need at least two kinds of automated tests:
- <emphasis>unit tests</emphasis>, which test a particular Seam component
- in isolation, and scripted <emphasis>integration tests</emphasis> which
- exercise all Java layers of the application (that is, everything except the
- view pages).
+ <para>
+ Most Seam applications will require at least two kinds of automated tests: <firstterm>unit tests</firstterm>, which test a particular Seam component in isolation, and scripted <firstterm>integration tests</firstterm>, which exercise all Java layers of the application (that is, everything except the view pages).
</para>
- <para>
- Both kinds of tests are very easy to write.
+ <para>
+ Both test types are easily written.
</para>
-
- <section>
+ <section>
<title>Unit testing Seam components</title>
- <para>
- All Seam components are POJOs. This is a great place to start if you
- want easy unit testing. And since Seam emphasises the use of bijection
- for inter-component interactions and access to contextual objects, it's
- very easy to test a Seam component outside of its normal runtime
- environment.
+ <para>
+ All Seam components are POJOs (Plain Old Java Objects), which simplifies unit testing. Since Seam also emphasizes the use of bijection for component interaction and contextual object access, testing Seam components outside their normal runtime environments is very easy.
</para>
- <para>
- Consider the following Seam Component which creates a statement of
- account for a customer:
+ <para>
+ The following Seam Component which creates a statement of account for a customer:
</para>
-
- <programlisting role="JAVA"><![CDATA[@Stateless
+
+<programlisting role="JAVA"><![CDATA[@Stateless
@Scope(EVENT)
@Name("statementOfAccount")
public class StatementOfAccount {
- @In(create=true) EntityManager entityManager
+ @In(create=true) EntityManager entityManager
- private double statementTotal;
+ private double statementTotal;
- @In
- private Customer customer;
+ @In
+ private Customer customer;
- @Create
- public void create() {
- List<Invoice> invoices = entityManager
- .createQuery("select invoice from Invoice invoice where invoice.customer = :customer")
- .setParameter("customer", customer)
- .getResultList();
- statementTotal = calculateTotal(invoices);
- }
+ @Create
+ public void create() {
+ List<Invoice> invoices = entityManager
+ .createQuery("select invoice from Invoice invoice where " +
+ "invoice.customer = :customer")
+ .setParameter("customer", customer)
+ .getResultList();
+ statementTotal = calculateTotal(invoices);
+ }
- public double calculateTotal(List<Invoice> invoices) {
- double total = 0.0;
- for (Invoice invoice: invoices)
- {
- double += invoice.getTotal();
+ public double calculateTotal(List<Invoice> invoices) {
+ double total = 0.0;
+ for (Invoice invoice: invoices) {
+ double += invoice.getTotal();
}
return total;
- }
-
+ }
// getter and setter for statementTotal
+}]]>
+</programlisting>
+ <para>
+ We can test the <literal>calculateTotal</literal> method, which tests the component's business logic, as follows:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public class StatementOfAccountTest {
+ @Test
+ public testCalculateTotal {
+ List<Invoice> invoices =
+ generateTestInvoices(); // A test data generator
+ double statementTotal =
+ new StatementOfAccount().calculateTotal(invoices);
+ assert statementTotal = 123.45;
+ }
+}]]>
+</programlisting>
+ <para>
+ Note that we are not testing data retrieval or persistence, or any of the functions provided by Seam. Here, we are testing only the logic of our POJOs. Seam components do not usually depend directly upon container infrastructure, so most unit tests are just as easy.
+ </para>
+ <para>
+ If you do want to test the entire application, read the section following.
+ </para>
+ </section>
+
+ <section>
+ <title>Integration testing Seam components</title>
+ <para>
+ Integration testing is more complicated. We cannot eliminate the container infrastructure, but neither do we want to deploy our application to an application server to run automated tests. Therefore, our testing environment must replicate enough container infrastructure that we can exercise the entire application, without impacting performance too heavily.
+ </para>
+ <para>
+ Seam lets you use the JBoss Embedded container to test your components — see the configuration chapter for details. This means you can write tests to exercise your application fully within a minimized container:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public class RegisterTest extends SeamTest {
-}]]></programlisting>
-
- <para>
- We could write a unit test for the calculateTotal method (which tests
- the business logic of the component) as follows:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public class StatementOfAccountTest {
-
- @Test
- public testCalculateTotal {
- List<Invoice> invoices = generateTestInvoices(); // A test data generator
- double statementTotal = new StatementOfAccount().calculateTotal(invoices);
- assert statementTotal = 123.45;
- }
-}
-]]></programlisting>
-
- <para>
- You'll notice we aren't testing retrieving data from or persisting
- data to the database; nor are we testing any functionality
- provided by Seam. We are just testing the logic of our POJOs. Seam
- components don't usually depend directly upon container infrastructure,
- so most unit testing are as easy as that!
- </para>
- <para>
- However, if you want to test the entire application, read on.
- </para>
-
- </section>
-
- <section>
- <title>Integration testing Seam components</title>
-
- <para>
- Integration testing is slightly more difficult. In this case, we can't eliminate
- the container infrastructure; indeed, that is part of what is being tested! At
- the same time, we don't want to be forced to deploy our application to an
- application server to run the automated tests. We need to be able to reproduce
- just enough of the container infrastructure inside our testing environment to be
- able to exercise the whole application, without hurting performance too much.
- </para>
-
- <para>
- The approach taken by Seam is to let you write tests that exercise your
- components while running inside a pruned down container environment (Seam,
- together with the JBoss Embedded container; see
- <xref linkend="config.install.embedded" /> for configuration details)
- </para>
-
-<programlisting role="JAVA"><![CDATA[public class RegisterTest extends SeamTest
-{
-
- @Test
- public void testRegisterComponent() throws Exception
- {
+ @Test
+ public void testRegisterComponent() throws Exception {
- new ComponentTest() {
+ new ComponentTest() {
- protected void testComponents() throws Exception
- {
- setValue("#{user.username}", "1ovthafew");
- setValue("#{user.name}", "Gavin King");
- setValue("#{user.password}", "secret");
- assert invokeMethod("#{register.register}").equals("success");
- assert getValue("#{user.username}").equals("1ovthafew");
- assert getValue("#{user.name}").equals("Gavin King");
- assert getValue("#{user.password}").equals("secret");
- }
+ protected void testComponents() throws Exception {
+ setValue("#{user.username}", "1ovthafew");
+ setValue("#{user.name}", "Gavin King");
+ setValue("#{user.password}", "secret");
+ assert invokeMethod("#{register.register}").equals("success");
+ assert getValue("#{user.username}").equals("1ovthafew");
+ assert getValue("#{user.name}").equals("Gavin King");
+ assert getValue("#{user.password}").equals("secret");
+ }
- }.run();
+ }.run();
- }
+ }
- ...
+ ...
-}]]></programlisting>
-
-
- <section>
- <title>Using mocks in integration tests</title>
-
- <para>
- Occasionally, we need to be able to replace the implementation of some
- Seam component that depends upon resources which are not available in
- the integration test environment. For example, suppose we have some
- Seam component which is a facade to some payment processing system:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("paymentProcessor")
+}]]>
+</programlisting>
+ <section>
+ <title>Using mocks in integration tests</title>
+ <para>
+ You may need to replace Seam components requiring resources that are unavailable in the integration test environment. For example, suppose that you use the following Seam component as a facade to some payment processing system:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("paymentProcessor")
public class PaymentProcessor {
- public boolean processPayment(Payment payment) { .... }
-}]]></programlisting>
-
- <para>
- For integration tests, we can mock out this component as follows:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("paymentProcessor")
+ public boolean processPayment(Payment payment) { .... }
+}]]>
+</programlisting>
+ <para>
+ For integration tests, we can make a mock component like so:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("paymentProcessor")
@Install(precedence=MOCK)
public class MockPaymentProcessor extends PaymentProcessor {
- public boolean processPayment(Payment payment) {
- return true;
- }
-}]]></programlisting>
-
- <para>
- Since the <literal>MOCK</literal> precedence is higher than the default
- precedence of application components, Seam will install the mock
- implementation whenever it is in the classpath. When deployed into
- production, the mock implementation is absent, so the real component
- will be installed.
- </para>
-
- </section>
-
- </section>
-
- <section>
- <title>Integration testing Seam application user interactions</title>
-
- <para>
- An even harder problem is emulating user interactions. A third problem is where
- to put our assertions. Some test frameworks let us test the whole application
- by reproducing user interactions with the web browser. These frameworks have
- their place, but they are not appropriate for use at development time.
- </para>
-
- <para>
- <literal>SeamTest</literal> lets you write <emphasis>scripted</emphasis> tests,
- in a simulated JSF environment. The role of a scripted test is to reproduce
- the interaction between the view and the Seam components. In other words, you
- get to pretend you are the JSF implementation!
- </para>
-
- <para>
- This approach tests everything except the view.
- </para>
-
- <para>
- Let's consider a JSP view for the component we unit tested above:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<html>
- <head>
- <title>Register New User</title>
- </head>
- <body>
- <f:view>
- <h:form>
- <table border="0">
- <tr>
- <td>Username</td>
- <td><h:inputText value="#{user.username}"/></td>
- </tr>
- <tr>
- <td>Real Name</td>
- <td><h:inputText value="#{user.name}"/></td>
- </tr>
- <tr>
- <td>Password</td>
- <td><h:inputSecret value="#{user.password}"/></td>
- </tr>
- </table>
- <h:messages/>
- <h:commandButton type="submit" value="Register" action="#{register.register}"/>
- </h:form>
- </f:view>
- </body>
-</html>]]></programlisting>
-
- <para>
- We want to test the registration functionality of our application (the stuff
- that happens when the user clicks the Register button). We'll reproduce the JSF
- request lifecycle in an automated TestNG test:
- </para>
-
-<programlisting role="JAVA"><![CDATA[public class RegisterTest extends SeamTest
-{
+ public boolean processPayment(Payment payment) {
+ return true;
+ }
+}]]>
+</programlisting>
+ <para>
+ The <literal>MOCK</literal> precedence is higher than the default precedence of application components, so Seam will install the mock implementation whenever it is in the classpath. When deployed into production, the mock implementation is absent, so the real component will be installed.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>Integration testing Seam application user interactions</title>
+ <para>
+ It is more difficult to emulate user interactions, and to place assertions appropriately. Some test frameworks let us test the whole application by reproducing user interactions with the web browser. These are useful, but not appropriate during development.
+ </para>
+ <para>
+ <literal>SeamTest</literal> lets you write <emphasis>scripted</emphasis> tests in a simulated JSF environment. A scripted test reproduces the interaction between the view and the Seam components, so you play the role of the JSF implementation during testing. You can test everything but the view with this approach.
+ </para>
+ <para>
+ Consider a JSP view for the component we unit tested above:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<html>
+ <head>
+ <title>Register New User</title>
+ </head>
+ <body>
+ <f:view>
+ <h:form>
+ <table border="0">
+ <tr>
+ <td>Username</td>
+ <td><h:inputText value="#{user.username}"/></td>
+ </tr>
+ <tr>
+ <td>Real Name</td>
+ <td><h:inputText value="#{user.name}"/></td>
+ </tr>
+ <tr>
+ <td>Password</td>
+ <td><h:inputSecret value="#{user.password}"/></td>
+ </tr>
+ </table>
+ <h:messages/>
+ <h:commandButton type="submit" value="Register"
+ action="#{register.register}"/>
+ </h:form>
+ </f:view>
+ </body>
+</html>]]>
+</programlisting>
+ <para>
+ We want to test the registration functionality of our application (that is, what happens when a user clicks the Register button). We will reproduce the JSF request lifecycle in an automated TestNG test:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public class RegisterTest extends SeamTesFt {
- @Test
- public void testRegister() throws Exception
- {
+ @Test
+ public void testRegister() throws Exception {
- new FacesRequest() {
+ new FacesRequest() {
- @Override
- protected void processValidations() throws Exception
- {
- validateValue("#{user.username}", "1ovthafew");
- validateValue("#{user.name}", "Gavin King");
- validateValue("#{user.password}", "secret");
- assert !isValidationFailure();
- }
+ @Override
+ protected void processValidations() throws Exception {
+ validateValue("#{user.username}", "1ovthafew");
+ validateValue("#{user.name}", "Gavin King");
+ validateValue("#{user.password}", "secret");
+ assert !isValidationFailure();
+ }
- @Override
- protected void updateModelValues() throws Exception
- {
- setValue("#{user.username}", "1ovthafew");
- setValue("#{user.name}", "Gavin King");
- setValue("#{user.password}", "secret");
- }
+ @Override
+ protected void updateModelValues() throws Exception {
+ setValue("#{user.username}", "1ovthafew");
+ setValue("#{user.name}", "Gavin King");
+ setValue("#{user.password}", "secret");
+ }
- @Override
- protected void invokeApplication()
- {
- assert invokeMethod("#{register.register}").equals("success");
- }
+ @Override
+ protected void invokeApplication() {
+ assert invokeMethod("#{register.register}").equals("success");
+ }
- @Override
- protected void renderResponse()
- {
- assert getValue("#{user.username}").equals("1ovthafew");
- assert getValue("#{user.name}").equals("Gavin King");
- assert getValue("#{user.password}").equals("secret");
- }
-
- }.run();
-
- }
-
- ...
+ @Override
+ protected void renderResponse() {
+ assert getValue("#{user.username}").equals("1ovthafew");
+ assert getValue("#{user.name}").equals("Gavin King");
+ assert getValue("#{user.password}").equals("secret");
+ }
+ }.run();
+ }
+ ...
+}]]>
+</programlisting>
+ <para>
+ Here, we extend <literal>SeamTest</literal> to provide a Seam environment for our components, and our test script is written as an anonymous class that extends <literal>SeamTest.FacesRequest</literal>, which provides an emulated JSF request lifecycle. (There is also a <literal>SeamTest.NonFacesRequest</literal> for testing GET requests.) Our code includes methods named for various JSF phases, to emulate the calls that JSF would make to our components. We have then included various assertions. <!-- #modify: descriptions of the assertions and JSF phases would help. -->
+ </para>
+ <para>
+ The Seam example applications include integration tests demonstrating more complex cases. You can run these tests with Ant, or with the TestNG plugin for Eclipse:
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/plugin-testng.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/plugin-testng.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <section>
+ <title>Configuration</title>
+ <para>
+ If you created your project with <application>seam-gen</application>, you can start writing tests immediately. Otherwise, you must first set up a testing environment in a build tool such as Ant, Maven, or Eclipse.
+ </para>
+ <para>
+ You will require at <emphasis>least</emphasis> the following dependencies:
+ </para>
+ <table>
+ <title></title>
+ <tgroup cols="3">
+ <thead>
+ <row>
+ <entry>
+ Group ID
+ </entry>
+ <entry>
+ Artifact ID
+ </entry>
+ <entry>
+ Location in Seam
+ </entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>
+ <literal>org.jboss.seam.embedded</literal>
+ </entry>
+ <entry>
+ <literal>hibernate-all</literal>
+ </entry>
+ <entry>
+ <literal>lib/test/hibernate-all.jar</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>org.jboss.seam.embedded</literal>
+ </entry>
+ <entry>
+ <literal>jboss-embedded-all</literal>
+ </entry>
+ <entry>
+ <literal>lib/test/jboss-embedded-all.jar</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>org.jboss.seam.embedded</literal>
+ </entry>
+ <entry>
+ <literal>thirdparty-all</literal>
+ </entry>
+ <entry>
+ <literal>lib/test/thirdparty-all.jar</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>org.jboss.seam.embedded</literal>
+ </entry>
+ <entry>
+ <literal>jboss-embedded-api</literal>
+ </entry>
+ <entry>
+ <literal>lib/jboss-embedded-api.jar</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>org.jboss.seam</literal>
+ </entry>
+ <entry>
+ <literal>jboss-seam</literal>
+ </entry>
+ <entry>
+ <literal>lib/jboss-seam.jar</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>org.jboss.el</literal>
+ </entry>
+ <entry>
+ <literal>jboss-el</literal>
+ </entry>
+ <entry>
+ <literal>lib/jboss-el.jar</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>javax.faces</literal>
+ </entry>
+ <entry>
+ <literal>jsf-api</literal>
+ </entry>
+ <entry>
+ <literal>lib/jsf-api.jar</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>javax.el</literal>
+ </entry>
+ <entry>
+ <literal>el-api</literal>
+ </entry>
+ <entry>
+ <literal>lib/el-api.jar</literal>
+ </entry>
+ </row>
+ <row>
+ <entry>
+ <literal>javax.activation</literal>
+ </entry>
+ <entry>
+ <literal>javax.activation</literal>
+ </entry>
+ <entry>
+ <literal>lib/activation.jar</literal>
+ </entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
+ <para>
+ Do not put the compile-time JBoss AS dependencies from <literal>lib/</literal> (such as <literal>jboss-system.jar</literal>) on the classpath, as this will prevent Embedded JBoss from booting. Add dependencies such as Drools and jBPM as you require them.
+ </para>
+ <para>
+ You must include the <literal>bootstrap/</literal> directory on the classpath, since it contains the configuration for Embedded JBoss.
+ </para>
+ <para>
+ You must also include your built project, tests, and the <filename>jar</filename> for your test framework on the classpath, as well as configuration files for JPA and Seam. Seam asks Embedded JBoss to deploy any resource (JAR or directory) with <literal>seam.properties</literal> in its root. If the structure of the directory containing your built project does not resemble that of a deployable archive, you must include <literal>seam.properties</literal> in each resource.
+ </para>
+ <para>
+ By default, a generated project uses the <literal>java:/DefaultDS</literal> (a built in HSQL datasource in Embedded JBoss) for testing. To use another datasource, place the <literal>foo-ds.xml</literal> into <literal>bootstrap/deploy</literal> directory.
+ </para>
+ </section>
+
+ <section>
+ <title>Using SeamTest with another test framework</title>
+ <para>
+ Seam provides TestNG support out of the box, but you can also use other test frameworks such as JUnit. To do so, you must provide an implementation of <literal>AbstractSeamTest</literal> that does the following:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ Calls <literal>super.begin()</literal> before every test method.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Calls <literal>super.end()</literal> after every test method.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Calls <literal>super.setupClass()</literal> to set up the integration test environment. This should be called prior to any test methods.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Calls <literal>super.cleanupClass()</literal> to clean up the integration test environment.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Calls <literal>super.startSeam()</literal> to start Seam when integration testing begins.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Calls <literal>super.stopSeam()</literal> to cleanly shut down Seam at the end of integration testing.
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Integration Testing with Mock Data</title>
+ <para>
+ To insert or clean data in your database before each test, you can use Seam's integration with DBUnit. To do this, extend DBUnitSeamTest rather than <literal>SeamTest</literal>.
+ </para>
+ <para>
+ You must provide a dataset for DBUnit.
+ </para>
+ <para>
+ DBUnit supports two formats for dataset files, flat and XML. Seam's DBUnitSeamTest assumes that you use the flat format, so make sure that your dataset is in this format.
+ </para>
+
+<programlisting role="XML"><![CDATA[<dataset>
-}]]></programlisting>
-
- <para>
- Notice that we've extended <literal>SeamTest</literal>, which provides a
- Seam environment for our components, and written our test script as an
- anonymous class that extends <literal>SeamTest.FacesRequest</literal>,
- which provides an emulated JSF request lifecycle. (There is also a
- <literal>SeamTest.NonFacesRequest</literal> for testing GET requests.)
- We've written our code in methods which are named for the various JSF
- phases, to emulate the calls that JSF would make to our components. Then
- we've thrown in various assertions.
- </para>
-
- <para>
- You'll find plenty of integration tests for the Seam example applications
- which demonstrate more complex cases. There are instructions for running
- these tests using Ant, or using the TestNG plugin for eclipse:
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/plugin-testng.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/plugin-testng.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <section>
- <title>Configuration</title>
-
- <para>
- If you used seam-gen to create your project you are ready to start
- writing tests. Otherwise you'll need to setup the testing
- environment in your favorite build tool (e.g. ant, maven,
- eclipse).
- </para>
-
- <para>
- First, lets look at the dependencies you need at a minimum:
- </para>
-
- <table>
- <title></title>
- <tgroup cols="3">
- <thead>
- <row >
- <entry>
- Group Id
- </entry>
- <entry>
- Artifact Id
- </entry>
- <entry>
- Location in Seam
- </entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>
- <literal>org.jboss.seam.embedded</literal>
- </entry>
- <entry>
- <literal>hibernate-all</literal>
- </entry>
- <entry>
- <literal>lib/test/hibernate-all.jar</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>org.jboss.seam.embedded</literal>
- </entry>
- <entry>
- <literal>jboss-embedded-all</literal>
- </entry>
- <entry>
- <literal>lib/test/jboss-embedded-all.jar</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>org.jboss.seam.embedded</literal>
- </entry>
- <entry>
- <literal>thirdparty-all</literal>
- </entry>
- <entry>
- <literal>lib/test/thirdparty-all.jar</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>org.jboss.seam.embedded</literal>
- </entry>
- <entry>
- <literal>jboss-embedded-api</literal>
- </entry>
- <entry>
- <literal>lib/jboss-embedded-api.jar</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>org.jboss.seam</literal>
- </entry>
- <entry>
- <literal>jboss-seam</literal>
- </entry>
- <entry>
- <literal>lib/jboss-seam.jar</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>org.jboss.el</literal>
- </entry>
- <entry>
- <literal>jboss-el</literal>
- </entry>
- <entry>
- <literal>lib/jboss-el.jar</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>javax.faces</literal>
- </entry>
- <entry>
- <literal>jsf-api</literal>
- </entry>
- <entry>
- <literal>lib/jsf-api.jar</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>javax.el</literal>
- </entry>
- <entry>
- <literal>el-api</literal>
- </entry>
- <entry>
- <literal>lib/el-api.jar</literal>
- </entry>
- </row>
- <row>
- <entry>
- <literal>javax.activation</literal>
- </entry>
- <entry>
- <literal>javax.activation</literal>
- </entry>
- <entry>
- <literal>lib/activation.jar</literal>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>
- It's very important you don't put the compile time JBoss AS
- dependencies from <literal>lib/</literal> (e.g.
- <literal>jboss-system.jar</literal>) on the classpath, these
- will cause Embedded JBoss to not boot. So, just add the
- dependencies (e.g. Drools, jBPM)you need as you go.
- </para>
-
- <para>
- You also need to include the <literal>bootstrap/</literal>
- directory on the classpath; <literal>bootstrap/</literal> contains
- the configuration for Embedded JBoss.
- </para>
-
- <para>
- And, of course you need to put your built project and tests onto
- the classpath as well as jar for your test framework. Don't forget
- to put all the correct configuration files for JPA and Seam onto
- the classpath as well.Seam asks Embedded JBoss to deploy any
- resource (jar or directory) which has
- <literal>seam.properties</literal> in it's root. Therefore, if you
- don't assemble a directory structure that resembles a deployable
- archive containing your built project, you must put a
- <literal>seam.properties</literal> in each resource.
- </para>
-
- <para>
- By default, a generated project will use the
- <literal>java:/DefaultDS</literal> (a built in HSQL datasource in
- Embedded JBoss) for testing. If you want to use another datasource
- place the <literal>foo-ds.xml</literal> into
- <literal>bootstrap/deploy</literal> directory.
- </para>
-
- </section>
-
- <section>
- <title>Using SeamTest with another test framework</title>
-
- <para>
- Seam provides TestNG support out of the box, but you can also use
- another test framework, such as JUnit, if you want.
- </para>
-
- <para>
- You'll need to provide an implementation of
- <literal>AbstractSeamTest</literal> which does the following:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>
- Calls <literal>super.begin()</literal> before every test
- method.
- </para>
- </listitem>
- <listitem>
- <para>
- Calls <literal>super.end()</literal> after every test
- method.
- </para>
- </listitem>
- <listitem>
- <para>
- Calls <literal>super.setupClass()</literal> to setup
- integration test environment. This should be called before
- any test methods are called.
- </para>
- </listitem>
- <listitem>
- <para>
- Calls <literal>super.cleanupClass()</literal> to clean up
- the integration test environment.
- </para>
- </listitem>
- <listitem>
- <para>
- Calls <literal>super.startSeam()</literal> to start Seam at
- the start of integration testing.
- </para>
- </listitem>
- <listitem>
- <para>
- Calls <literal>super.stopSeam()</literal> to cleanly shut
- down Seam at the end of integration testing.
- </para>
- </listitem>
- </itemizedlist>
- </section>
-
- <section>
- <title>Integration Testing with Mock Data</title>
-
- <para>
- If you want to insert or clean data in your database before each
- test you can use Seam's integration with DBUnit. To do this, extend
- <literal>DBUnitSeamTest</literal> rather than <literal>SeamTest</literal>.
- </para>
-
- <para>
- You have to provide a dataset for DBUnit.
- </para>
-
- <caution>
- DBUnit supports two formats for dataset files, flat and XML. Seam's
- <literal>DBUnitSeamTest</literal> assumes the flat format is used, so make sure that
- your dataset is in this format.
- </caution>
-
- <programlisting role="XML"><![CDATA[<dataset>
-
- <ARTIST
- id="1"
- dtype="Band"
- name="Pink Floyd" />
+ <ARTIST
+ id="1"
+ dtype="Band"
+ name="Pink Floyd" />
- <DISC
- id="1"
- name="Dark Side of the Moon"
- artist_id="1" />
+ <DISC
+ id="1"
+ name="Dark Side of the Moon"
+ artist_id="1" />
-</dataset>]]></programlisting>
-
- <para>
- In your test class, configure your dataset with overriding
- <literal>prepareDBUnitOperations()</literal>:
- </para>
-
- <programlisting role="JAVA"><![CDATA[protected void prepareDBUnitOperations() {
- beforeTestOperations.add(
- new DataSetOperation("my/datasets/BaseData.xml")
- );
- }]]></programlisting>
-
- <para>
- <literal>DataSetOperation</literal> defaults to <literal>DatabaseOperation.CLEAN_INSERT</literal>
- if no other operation is specified as a constructor argument. The
- above example cleans all tables defined <literal>BaseData.xml</literal>,
- then inserts all rows declared in <literal>BaseData.xml</literal>
- before each <literal>@Test</literal> method is invoked.
- </para>
-
- <para>
- If you require extra cleanup after a test method executes, add
- operations to <literal>afterTestOperations</literal> list.
- </para>
-
- <para>
- You need to tell DBUnit about the datasource you are using by
- setting a TestNG test parameter named <literal>datasourceJndiName</literal>:
- </para>
-
- <programlisting role="XML"><![CDATA[<parameter name="datasourceJndiName" value="java:/seamdiscsDatasource"/>]]></programlisting>
-
- <para>
- DBUnitSeamTest has support for MySQL and HSQL - you need to tell it
- which database is being used, otherwise it defaults to HSQL:
- </para>
-
- <programlisting role="XML"><![CDATA[<parameter name="database" value="MYSQL" />]]></programlisting>
-
- <para>
- It also allows you to insert binary data into the test data set (n.b.
- this is untested on Windows). You need to tell it where to locate
- these resources on your classpath:
- </para>
-
- <programlisting role="XML"><![CDATA[<parameter name="binaryDir" value="images/" />]]></programlisting>
-
- <para>
- You do not have to configure any of these parameters if you use HSQL and have
- no binary imports. However, unless you specify <literal>datasourceJndiName</literal>
- in your test configuration, you will have to call <literal>setDatabaseJndiName()</literal>
- before your test runs. If you are not using HSQL or MySQL, you need to override some
- methods. See the Javadoc of <literal>DBUnitSeamTest</literal> for more details.
- </para>
-
- </section>
-
- <section id="testing.mail">
- <title>Integration Testing Seam Mail</title>
-
- <caution>
- Warning! This feature is still under development.
- </caution>
-
- <para>
- It's very easy to integration test your Seam Mail:
- </para>
-
- <programlisting role="JAVA"><![CDATA[public class MailTest extends SeamTest {
+</dataset>]]>
+</programlisting>
+ <para>
+ In your test class, configure your dataset by overriding <literal>prepareDBUnitOperations()</literal> as follows:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[protected void prepareDBUnitOperations() {
+ beforeTestOperations.add(
+ new DataSetOperation("my/datasets/BaseData.xml")
+ );
+}]]>
+</programlisting>
+ <para>
+ <literal>DataSetOperation</literal> defaults to <literal>DatabaseOperation.CLEAN_INSERT</literal> if no other operation is specified as a constructor argument. The previous example cleans all tables defined <literal>BaseData.xml</literal>, then inserts all rows declared in <literal>BaseData.xml</literal> before each <literal>@Test</literal> method is invoked.
+ </para>
+ <para>
+ If you require extra cleanup after a test method executes, add operations to the <literal>afterTestOperations</literal> list.
+ </para>
+ <para>
+ You need to tell DBUnit about your datasource by setting a TestNG test parameter named <literal>datasourceJndiName</literal>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<parameter name="datasourceJndiName" value="java:/seamdiscsDatasource"/>]]></programlisting>
+ <para>
+ DBUnitSeamTest supports both MySQL and HSQL. You must tell it which database is being used, otherwise it defaults to HSQL:
+ </para>
+
+ <programlisting role="XML"><![CDATA[ <parameter name="database" value="MYSQL" />]]>
+ </programlisting>
+ <para>
+ It also allows you to insert binary data into the test data set. (Note that this is <emphasis>untested on Windows</emphasis>.) Tell DBUnitSeamTest where to find these resources on your classpath:
+ </para>
+
+<programlisting role="XML"><![CDATA[<parameter name="binaryDir" value="images/" />]]>
+</programlisting>
+ <para>
+ You do not have to configure any of these parameters if you use HSQL and have no binary imports. However, unless you specify <literal>datasourceJndiName</literal> in your test configuration, you will have to call <literal>setDatabaseJndiName()</literal> before your test runs. If you are not using HSQL or MySQL, you need to override some methods. See the Javadoc of <literal>DBUnitSeamTest</literal> for more details.
+ </para>
+ <!--
+ <para>
+ You must specify these three parameters in your <literal>testng.xml</literal>.
+ </para>
+
+ <para>
+ To use DBUnitSeamTest with another database, you need to implement several methods —read the section on <literal>AbstractDBUnitSeamTest</literal> in the Java documentation for more information.
+ </para>
+ -->
+ </section>
+
+ <section id="testing.mail">
+ <title>Integration Testing Seam Mail</title>
+ <warning>
+ <para>
+ This feature is still under development.
+ </para>
+ </warning>
+ <para>
+ It is very easy to integration test your Seam Mail:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public class MailTest extends SeamTest {
- @Test
- public void testSimpleMessage() throws Exception {
+ @Test
+ public void testSimpleMessage() throws Exception {
- new FacesRequest() {
+ new FacesRequest() {
- @Override
- protected void updateModelValues() throws Exception {
- setValue("#{person.firstname}", "Pete");
- setValue("#{person.lastname}", "Muir");
- setValue("#{person.address}", "test at example.com");
- }
+ @Override
+ protected void updateModelValues() throws Exception {
+ setValue("#{person.firstname}", "Pete");
+ setValue("#{person.lastname}", "Muir");
+ setValue("#{person.address}", "test at example.com");
+ }
- @Override
- protected void invokeApplication() throws Exception {
- MimeMessage renderedMessage = getRenderedMailMessage("/simple.xhtml");
- assert renderedMessage.getAllRecipients().length == 1;
- InternetAddress to = (InternetAddress) renderedMessage.getAllRecipients()[0];
- assert to.getAddress().equals("test at example.com");
- }
+ @Override
+ protected void invokeApplication() throws Exception {
+ MimeMessage renderedMessage =
+ getRenderedMailMessage("/simple.xhtml");
+ assert renderedMessage.getAllRecipients().length == 1;
+ InternetAddress to =
+ (InternetAddress) renderedMessage.getAllRecipients()[0];
+ assert to.getAddress().equals("test at example.com");
+ }
- }.run();
- }
-}]]></programlisting>
-
- <para>
- We create a new <literal>FacesRequest</literal> as normal. Inside
- the invokeApplication hook we render the message using
- <literal>getRenderedMailMessage(viewId);</literal>, passing the
- viewId of the message to render. The method returns the rendered
- message on which you can do your tests. You can of course also use
- any of the standard JSF lifecycle methods.
- </para>
-
- <para>
- There is no support for rendering standard JSF components so you
- can't test the content body of the mail message easily.
- </para>
- </section>
-
- </section>
+ }.run();
+ }
+}]]>
+</programlisting>
+ <para>
+ Create a new <literal>FacesRequest</literal> as normal. Inside the <literal>invokeApplication</literal> hook, we render the message using <literal>getRenderedMailMessage(viewId);</literal>, which passes the <literal>viewId</literal> of he message to be rendered. The method returns the rendered message on which you can perform tests. You can also use any standard JSF lifecycle method.
+ </para>
+ <para>
+ There is no support for rendering standard JSF components, so you cannot easily test the contents of the mail message.
+ </para>
+ </section>
+
+ </section>
-</chapter>
\ No newline at end of file
+</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Text.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Text.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Text.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,73 +1,67 @@
-<chapter id="text">
- <title>Seam Text</title>
-
- <para>
- Collaboration-oriented websites require a human-friendly markup language for easy entry
- of formatted text in forum posts, wiki pages, blogs, comments, etc. Seam provides the
- <literal><s:formattedText/></literal> control for display of formatted text that
- conforms to the <emphasis>Seam Text</emphasis> language. Seam Text is implemented using
- an ANTLR-based parser. You don't need to know anything about ANTLR to use it, however.
- </para>
-
- <section>
- <title>Basic fomatting</title>
- <para>
- Here is a simple example:
- </para>
-
- <programlisting><![CDATA[It's easy to make *emphasis*, |monospace|,
-~deleted text~, super^scripts^ or _underlines_.]]></programlisting>
-
- <para>
- If we display this using <literal><s:formattedText/></literal>, we will get
- the following HTML produced:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<p>
-It's easy to make <i>emphasis</i>, <tt>monospace</tt>
-<del>deleted text</del>, super<sup>scripts</sup> or <u>underlines</u>.
-</p>]]></programlisting>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- <para>
- We can use a blank line to indicate a new paragraph, and <literal>+</literal> to
- indicate a heading:
- </para>
-
- <programlisting><![CDATA[+This is a big heading
+<chapter id="text" >
+ <title>Seam Text</title>
+ <para>
+ Collaboration-oriented websites require a human-friendly markup language so that formatted text can be entered easily in forum posts, wiki pages, blogs, comments, etc. Seam provides the <literal><![CDATA[<s:formattedText/>]]></literal> control to display formatted text that conforms to the <emphasis>Seam Text</emphasis> language. Seam Text is implemented with an ANTLR-based parser. (Experience with ANTLR is not required.)
+ </para>
+ <section>
+ <title>Basic fomatting</title>
+ <para>
+ Here is a simple example:
+ </para>
+
+<programlisting><![CDATA[It's easy to make *emphasized*, |monospaced|, ~deleted~, super^scripted^ or _underlined_ text.]]>
+</programlisting>
+ <para>
+ If we display this using <literal><![CDATA[<s:formattedText/>]]></literal>, the following HTML will be produced:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<p>
+ It's easy to make <i>emphasized</i>, <tt>monospaced</tt>,
+ <del>deleted</del>, super<sup>scripted</sup> or
+ <u>underlined</u> text.
+</p>]]>
+</programlisting>
+ <para>
+ We can use a blank line to indicate a new paragraph, and <literal>+</literal> to indicate a heading:
+ </para>
+
+<programlisting><![CDATA[+This is a big heading
You /must/ have some text following a heading!
++This is a smaller heading
This is the first paragraph. We can split it across multiple
lines, but we must end it with a blank line.
-This is the second paragraph.]]></programlisting>
-
- <para>
- (Note that a simple newline is ignored, you need an additional blank line to wrap text into a new paragraph.)
- This is the HTML that results:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h1>This is a big heading</h1>
+This is the second paragraph.]]>
+</programlisting>
+ <para>
+ A simple new line is ignored — you need an additional blank line to wrap text into a new paragraph. This is the HTML that results:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h1>This is a big heading</h1>
<p>
-You <i>must</i> have some text following a heading!
+ You <i>must</i> have some text following a heading!
</p>
<h2>This is a smaller heading</h2>
<p>
-This is the first paragraph. We can split it across multiple
-lines, but we must end it with a blank line.
+ This is the first paragraph. We can split it across multiple
+ lines, but we must end it with a blank line.
</p>
<p>
-This is the second paragraph.
-</p>]]></programlisting>
-
- <para>
- Ordered lists are created using the <literal>#</literal> character. Unordered lists
- use the <literal>=</literal> character:
- </para>
-
- <programlisting><![CDATA[An ordered list:
+ This is the second paragraph.
+</p>]]>
+</programlisting>
+ <para>
+ The <literal>#</literal> character creates items in an ordered list. Unordered lists use the <literal>=</literal> character:
+ </para>
+
+<programlisting><![CDATA[An ordered list:
#first item
#second item
@@ -76,222 +70,195 @@
An unordered list:
=an item
-=another item]]></programlisting>
-
- <programlisting role="XHTML"><![CDATA[<p>
-An ordered list:
+=another item]]>
+</programlisting>
+
+<programlisting role="XHTML"><![CDATA[<p>
+ An ordered list:
</p>
<ol>
-<li>first item</li>
-<li>second item</li>
-<li>and even the <i>third</i> item</li>
+ <li>first item</li>
+ <li>second item</li>
+ <li>and even the <i>third</i> item</li>
</ol>
<p>
-An unordered list:
+ An unordered list:
</p>
<ul>
-<li>an item</li>
-<li>another item</li>
-</ul>]]></programlisting>
+ <li>an item</li>
+ <li>another item</li>
+</ul>]]>
+</programlisting>
+ <para>
+ Quoted sections should be surrounded in double quotes: <!-- #modify: This is lovely, of course, but can we have an example of more than three years' age? -->
+ </para>
+
+<programlisting><![CDATA[The other guy said:
- <para>
- Quoted sections should be surrounded in double quotes:
- </para>
-
- <programlisting><![CDATA[The other guy said:
-
"Nyeah nyeah-nee
/nyeah/ nyeah!"
-But what do you think he means by "nyeah-nee"?]]></programlisting>
-
- <programlisting role="XHTML"><![CDATA[<p>
-The other guy said:
+But what do you think he means by "nyeah-nee"?]]>
+</programlisting>
+
+<programlisting role="XHTML"><![CDATA[<p>
+ The other guy said:
</p>
<q>Nyeah nyeah-nee
<i>nyeah</i> nyeah!</q>
<p>
-But what do you think he means by <q>nyeah-nee</q>?
-</p>]]></programlisting>
+ But what do you think he means by <q>nyeah-nee</q>?
+</p>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Entering code and text with special characters</title>
+ <para>
+ Special characters such as <literal>*</literal>, <literal>|</literal> and <literal>#</literal>, and HTML characters such as <literal><![CDATA[<</literal>, <literal>>]]></literal> and <literal>&</literal> can be escaped with <literal>\</literal>:
+ </para>
+
+<programlisting><![CDATA[You can write down equations like 2\*3\=6 and HTML tags
+like \<body\> using the escape character: \\.]]>
+</programlisting>
+
+<programlisting role="XHTML"><![CDATA[<p>
+ You can write down equations like 2*3=6 and HTML tags
+ like <body> using the escape character: \.
+</p>]]>
+</programlisting>
+ <para>
+ And we can quote code blocks with backticks:
+ </para>
+
+<programlisting><![CDATA[My code doesn't work:
- </section>
-
- <section>
- <title>Entering code and text with special characters</title>
- <para>
- Special characters such as <literal>*</literal>, <literal>|</literal>
- and <literal>#</literal>, along with HTML characters such as
- <literal><</literal>, <literal>></literal> and <literal>&</literal>
- may be escaped using <literal>\</literal>:
- </para>
-
- <programlisting><![CDATA[You can write down equations like 2\*3\=6 and HTML tags
-like \<body\> using the escape character: \\.]]></programlisting>
-
- <programlisting role="XHTML"><![CDATA[<p>
-You can write down equations like 2*3=6 and HTML tags
-like <body> using the escape character: \.
-</p>]]></programlisting>
-
- <para>
- And we can quote code blocks using backticks:
- </para>
-
- <programlisting><![CDATA[My code doesn't work:
-
`for (int i=0; i<100; i--)
{
doSomething();
}`
-Any ideas?]]></programlisting>
-
- <programlisting role="XHTML"><![CDATA[<p>
-My code doesn't work:
+Any ideas?]]>
+</programlisting>
+
+<programlisting role="XHTML"><![CDATA[<p>
+ My code doesn't work:
</p>
-<pre>for (int i=0; i<100; i--)
+<pre>for (int i=0; i<100; i--)
{
doSomething();
}</pre>
<p>
-Any ideas?
-</p>]]></programlisting>
-
- <para>
- Note that inline monospace formatting always escapes (most monospace formatted text is in fact
- code or tags with many special characters). So you can, for example, write:
- </para>
-
- <programlisting><![CDATA[This is a |<tag attribute="value"/>| example.]]></programlisting>
-
- <para>
- without escaping any of the characters inside the monospace bars. The downside is that
- you can't format inline monospace text in any other way (italics, underscore, and so on).
- </para>
-
- </section>
-
- <section>
- <title>Links</title>
-
- <para>
- A link may be created using the following syntax:
- </para>
-
- <programlisting><![CDATA[Go to the Seam website at [=>http://jboss.com/products/seam].]]></programlisting>
-
- <para>
- Or, if you want to specify the text of the link:
- </para>
-
- <programlisting><![CDATA[Go to [the Seam website=>http://jboss.com/products/seam].]]></programlisting>
-
- <para>
- For advanced users, it is even possible to customize the Seam Text parser to understand
- wikiword links written using this syntax.
- </para>
-
- </section>
-
- <section>
- <title>Entering HTML</title>
-
- <para>
- Text may even include a certain limited subset of HTML (don't worry, the subset is chosen
- to be safe from cross-site scripting attacks). This is useful for creating links:
- </para>
-
- <programlisting role="XHTML"><![CDATA[You might want to link to <a href="http://jboss.com/products/seam">something
-cool</a>, or even include an image: <img src="/logo.jpg"/>]]></programlisting>
-
- <para>
- And for creating tables:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<table>
- <tr><td>First name:</td><td>Gavin</td></tr>
- <tr><td>Last name:</td><td>King</td></tr>
-</table>]]></programlisting>
-
- <para>
- But you can do much more if you want!
- </para>
-
- </section>
-
- <section>
+ Any ideas?
+</p>]]>
+</programlisting>
+ <para>
+ Since most monospace-formatted text is either code, or involves special characters, inline monospace formatting always escapes. So, you can write:
+ </para>
+
+<programlisting><![CDATA[This is a |<tag attribute="value"/>| example.]]>
+</programlisting>
+ <para>
+ without escaping any of the characters inside the monospace bars. This also means that inline monospace text cannot be formatted in any other way.
+ </para>
+ </section>
+
+ <section>
+ <title>Links</title>
+ <para>
+ You can create a link like so:
+ </para>
+
+<programlisting><![CDATA[Go to the Seam website at [=>http://jboss.com/products/seam].]]>
+</programlisting>
+ <para>
+ If you want to specify the link text:
+ </para>
+
+<programlisting><![CDATA[Go to [the Seam website=>http://jboss.com/products/seam].]]>
+</programlisting>
+ <para>
+ For advanced users, you can also customize the Seam Text parser to understand wikiword links written in this syntax.
+ </para>
+ </section>
+
+ <section>
+ <title>Entering HTML</title>
+ <para>
+ Text can include a certain limited subset of HTML. (The subset was selected to remain safe from cross-site scripting attacks.) This is useful for creating links:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[You might want to link to
+<a href="http://jboss.com/products/seam">something cool</a>,
+or even include an image: <img src="/logo.jpg"/>]]>
+</programlisting>
+ <para>
+ And for creating tables:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<table>
+ <tr><td>First name:</td><td>Gavin</td></tr>
+ <tr><td>Last name:</td><td>King</td></tr>
+</table>]]>
+</programlisting>
+ </section>
+ <section>
<title>Using the SeamTextParser</title>
<para>
- The <literal><s:formattedText/></literal> JSF component internally uses the
- <literal>org.jboss.seam.text.SeamTextParser</literal>. You can use that class directly and implement
- your own text parsing, rendering, or HTML sanitation procedure. This is especially useful if you have
- a custom frontend for entering rich text, such as a Javascript-based HTML editor, and you want to validate
- user input to protect your website against Cross-Site Scripting (XSS) attacks. Another usecase
- are custom wiki text parsing and rendering engines.
+ The <literal><![CDATA[<s:formattedText/>]]></literal> JSF component uses the <literal>org.jboss.seam.text.SeamTextParser</literal> internally. You can use this class directly to implement your own text parsing, rendering, and HTML sanitation procedures. If you have a custom front-end interface for entering rich text, such as a JavaScript-based HTML editor, this can be useful for validating user input in order to defend against Cross-Site Scripting (XSS) attacks. You could also use it as a custom Wiki text-parsing and rendering engine.
</para>
<para>
- The following example defines a custom text parser that overrides the default HTML sanitizer:
+ The following example defines a custom text parser, which overrides the default HTML sanitizer:
</para>
<programlisting role="JAVA"><![CDATA[public class MyTextParser extends SeamTextParser {
- public MyTextParser(String myText) {
- super(new SeamTextLexer(new StringReader(myText)));
+ public MyTextParser(String myText) {
+ super(new SeamTextLexer(new StringReader(myText)));
- setSanitizer(
- new DefaultSanitizer() {
- @Override
- public void validateHtmlElement(Token element) throws SemanticException {
- // TODO: I want to validate HTML elements myself!
- }
- }
- );
- }
+ setSanitizer(
+ new DefaultSanitizer() {
+ @Override
+ public void validateHtmlElement(Token element) throws SemanticException {
+ // TODO: I want to validate HTML elements myself!
+ }
+ }
+ );
+ }
- // Customizes rendering of Seam text links such as [Some Text=>http://example.com]
- @Override
- protected String linkTag(String descriptionText, String linkText) {
- return "<a href=\"" + linkText + "\">My Custom Link: " + descriptionText + "</a>";
- }
+ // Customizes rendering of Seam text links such as [Some Text=>http://example.com]
+ @Override
+ protected String linkTag(String descriptionText, String linkText) {
+ return "<a href=\"" + linkText + "\">My Custom Link: " +
+ descriptionText + "</a>";
+ }
- // Renders a <p> or equivalent tag
- @Override
- protected String paragraphOpenTag() {
- return "<p class=\"myCustomStyle\">";
- }
+ // Renders a <p> or equivalent tag
+ @Override
+ protected String paragraphOpenTag() {
+ return "<p class=\"myCustomStyle\">";
+ }
- public void parse() throws ANTLRException {
- startRule();
- }
+ public void parse() throws ANTLRException {
+ startRule();
+ }
-}]]></programlisting>
+}]]>
+</programlisting>
<para>
- The <literal>linkTag()</literal> and <literal>paragraphOpenTag()</literal> methods are just some of many
- you can override to customize rendered output. These methods generally return <literal>String</literal>.
- See the Javadoc for more details.
+ <literal>linkTag()</literal> and <literal>paragraphOpenTag()</literal> methods are two of the methods you can override in order to customize rendered output. These methods usually return <literal>String</literal> output. For further details, refer to the Java Documentation. The <literal>org.jboss.seam.text.SeamTextParser.DefaultSanitizer</literal> Java Documentation also contains more information about the HTML elements, attributes, and attribute values that are filtered by default.
</para>
-
- <para>
- Also consult the Javadoc of <literal>org.jboss.seam.text.SeamTextParser.DefaultSanitizer</literal> for
- more information on what HTML elements, attributes, and attribute values or filtered by default.
- </para>
-
</section>
</chapter>
-
-<!--
- <programlisting role="JAVA"><![CDATA[
-]]></programlisting>
--->
\ No newline at end of file
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Tools.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Tools.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Tools.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,623 +1,52 @@
-<chapter id="tools">
- <title>Seam tools</title>
-
- <section>
- <title>jBPM designer and viewer</title>
-
- <para>
- The jBPM designer and viewer will let you design and view in a nice way your business processes and your pageflows.
- This convenient tool is part of JBoss Eclipse IDE and more details can be found in the jBPM's <ulink url="http://docs.jboss.com/jbpm/v3/gpd/">documentation</ulink>
- </para>
-
- <section>
- <title>Business process designer</title>
-
- <para>
- This tool lets you design your own business process in a graphical way.
- </para>
-
- <screenshot>
- <screeninfo>Business process designer</screeninfo>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/bpmd.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/bpmd.png" align="center"/>
- </imageobject>
- </mediaobject>
- </screenshot>
-
- </section>
-
- <section>
- <title>Pageflow viewer</title>
-
- <para>
- This tool let you design to some extend your pageflows and let you build graphical views of them so you can
- easily share and compare ideas on how it should be designed.
- </para>
-
- <screenshot>
- <screeninfo>Business process designer</screeninfo>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/bpmpfv.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/bpmpfv.png" align="center"/>
- </imageobject>
- </mediaobject>
- </screenshot>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- </section>
-
- </section>
-
- <!--
- <section>
- <title>CRUD-application generator</title>
-
- <para>
- This chapter, will give you a short overview of the support for Seam that is available in the Hibernate Tools.
- Hibernate Tools is a set of tools for working with Hibernate and related technologies, such as JBoss Seam and EJB3.
- The tools are available as a set of eclipse plugins and Ant tasks. You can download the Hibernate Tools from the JBoss Eclipse IDE or Hibernate Tools websites.
- </para>
-
- <para>
- The specific support for Seam that is currently available is generation of a fully functional Seam based CRUD-application.
- The CRUD-application can be generated based on your existing Hibernate mapping files or EJB3 annotated POJO's or even fully
- reverse engineered from your existing database schema.
- </para>
-
- <para>
- The following sections is focused on the features required to understand for usage with Seam. The content is derived from the the Hibernate Tools reference documentation. Thus if you
- need more detailed information please refer to the Hibernate Tools documentation.
- </para>
-
- <section>
- <title>Creating a Hibernate configuration file</title>
-
- <para>
- To be able to reverse engineer and generate code a hibernate.properties
- or hibernate.cfg.xml file is needed. The Hibernate Tools provide a wizard for generating the
- hibernate.cfg.xml file if you do not already have such file.
- </para>
-
- <para>
- Start the wizard by clicking "New Wizard" (Ctrl+N), select the
- Hibernate/Hibernate Configuration file (cfg.xml) wizard and press "Next".
- After selecting the wanted location for the hibernate.cfg.xml file, you
- will see the following page:
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="/images/hibernatecfgwizard.gif" format="gif" contentwidth="5cm" />
- </imageobject>
-
- <imageobject role="html">
- <imagedata align="center"
- fileref="/images/hibernatecfgwizard.gif"
- format="gif" />
- </imageobject>
- </mediaobject>
-
- <para>
- Tip: The contents in the combo boxes for the JDBC driver class and
- JDBC URL change automatically, depending on the Dialect and actual driver
- you have chosen.
- </para>
-
- <para>
- Enter your configuration information in this dialog. Details about
- the configuration options can be found in Hibernate reference
- documentation.
- </para>
-
- <para>
- Press "Finish" to create the configuration file, after optionally
- creating a Console onfiguration, the hibernate.cfg.xml will be
- automatically opened in an editor. The last option "Create Console
- Configuration" is enabled by default and when enabled i will automatically
- use the hibernate.cfg.xml for the basis of a "Console
- Configuration"
- </para>
- </section>
-
- <section>
- <title>Creating a Hibernate Console configuration</title>
-
- <para>
- A Console Configuration describes to the Hibernate plugin which configuration files
- should be used to configure hibernate, including which classpath is needed to load the POJO's,
- JDBC drivers etc. It is required to make usage of query prototyping, reverse engineering and
- code generation. You can have multiple named console configurations. Normally you would just
- need one per project, but more (or less) is definitly possible.
- </para>
-
- <para>
- You create a console configuration by running the Console
- Configuration wizard, shown in the following screenshot. The same wizard
- will also be used if you are coming from the hibernate.cfg.xml wizard and
- had enabled "Create Console Configuration".
- </para>
-
- <mediaobject>
- <title>Creating a Hibernate Console configuration</title>
-
- <imageobject role="fo">
- <imagedata fileref="/images/consolecfgwizard.gif" format="GIF" />
- </imageobject>
-
- <imageobject role="html">
- <imagedata align="center"
- fileref="/images/consolecfgwizard.gif"
- format="gif" />
- </imageobject>
- </mediaobject>
-
- <para>
- The following table describes the relevant settings. The wizard can
- automatically detect default values for most of these if you started the
- Wizard with the relevant java project selected
- </para>
-
- <table>
- <title>Hibernate Console Configuration Parameters</title>
-
- <tgroup cols="3">
- <colspec colnum="1" colwidth="1*" />
-
- <colspec colnum="2" colwidth="3*" />
-
- <colspec colnum="3" colwidth="1*" />
-
- <thead>
- <row>
- <entry align="center">
- <para>Parameter</para>
- </entry>
-
- <entry align="center">
- <para>Description</para>
- </entry>
-
- <entry align="center">
- <para>Auto detected value</para>
- </entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry>
- <para>Name</para>
- </entry>
-
- <entry>
- <para>The unique name of the configuration</para>
- </entry>
-
- <entry>
- <para>Name of the selected project</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>Property file</para>
- </entry>
-
- <entry>
- <para>Path to a hibernate.properties file</para>
- </entry>
-
- <entry>
- <para>First hibernate.properties file found in the selected
- project</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>Configuration file</para>
- </entry>
-
- <entry>
- <para>Path to a hibernate.cfg.xml file</para>
- </entry>
-
- <entry>
- <para>First hibernate.cfg.xml file found in the selected
- project</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>Enable Hibernate ejb3/annotations</para>
- </entry>
-
- <entry>
- <para>Selecting this option enables usage of annotated classes.
- hbm.xml files are of course still possible to use too. This
- feature requires running the Eclipse IDE with a JDK 5 runtime,
- otherwise you will get classloading and/or version
- errors.</para>
- </entry>
-
- <entry>
- <para>Not enabled</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>Mapping files</para>
- </entry>
-
- <entry>
- <para>List of additional mapping files that should be loaded.
- Note: A hibernate.cfg.xml can also contain mappings. Thus if
- these a duplicated here, you will get "Duplicate mapping" errors
- when using the console configuration.</para>
- </entry>
-
- <entry>
- <para>If no hibernate.cfg.xml file is found, all hbm.xml files
- found in the selected project</para>
- </entry>
- </row>
-
- <row>
- <entry>
- <para>Classpath</para>
- </entry>
-
- <entry>
- <para>The classpath for loading POJO and JDBC drivers. Do not
- add Hibernate core libraries or dependencies, they are already
- included. If you get ClassNotFound errors then check this list
- for possible missing or redundant directories/jars.</para>
- </entry>
-
- <entry>
- <para>The default build output directory and any JARs with a
- class implementing java.sql.Driver in the selected
- project</para>
- </entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- <para>Clicking "Finish" creates the configuration and shows it in the
- "Hibernate Configurations" view</para>
-
- <mediaobject>
- <title>Console overview</title>
-
- <imageobject role="fo">
- <imagedata align="center"
- fileref="/images/consoleoutline-before-reveng.gif"
- format="GIF" />
- </imageobject>
-
- <imageobject role="html">
- <imagedata align="center"
- fileref="/images/consoleoutline-before-reveng.gif"
- format="gif" />
- </imageobject>
- </mediaobject>
-
- </section>
-
- <section>
- <title>Reverse engineering and code generation</title>
-
- <para>
- A very simple "click-and-generate" reverse engineering and code
- generation facility is available. It is this facility that allows you to
- generate the skeleton for a full Seam CRUD application.
- </para>
-
- <para>
- To start working with this process, start the "Hibernate Code
- Generation" which is available in the toolbar via the Hibernate icon or
- via the "Run/Hibernate Code Generation" menu item.
- </para>
-
- <section>
- <title>Code Generation Launcher</title>
-
- <para>When you click on "Hibernate Code Generation" the standard Eclipse
- launcher dialog will appear. In this dialog you can create, edit and
- delete named Hibernate code generation "launchers".</para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="/images/codegendropdown.gif" format="GIF" />
- </imageobject>
-
- <imageobject role="html">
- <imagedata align="center"
- fileref="/images/codegendropdown.gif"
- format="gif" />
- </imageobject>
- </mediaobject>
-
- <para>The dialog has the standard tabs "Refresh" and "Common" that can
- be used to configure which directories should be automatically refreshed
- and various general settings launchers, such as saving them in a project
- for sharing the launcher within a team.</para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="/images/codegenmaintab.gif" format="GIF" />
- </imageobject>
-
- <imageobject role="html">
- <imagedata align="center"
- fileref="/images/codegenmaintab.gif"
- format="gif" />
- </imageobject>
- </mediaobject>
-
- <para>The first time you create a code generation launcher you should
- give it a meaningfull name, otherwise the default prefix
- "New_Generation" will be used.</para>
-
- <para>Note: The "At least one exporter option must be selected" is just
- a warning stating that for this launch to work you need to select an
- exporter on the Exporter tab. When an exporter has been selected the
- warning will disappear.</para>
-
- <para>On the "Main" tab you the following fields:</para>
-
- <table>
- <title>Code generation "Main" tab fields</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
-
- <colspec colnum="2" colwidth="3*" />
-
- <colspec colnum="3" colwidth="0.5*" />
-
- <thead>
- <row>
- <entry align="center"><para>Field</para></entry>
-
- <entry align="center"><para>Description</para></entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><para>Console Configuration</para></entry>
-
- <entry><para>The name of the console configuration which should
- be used when code generating.</para></entry>
- </row>
-
- <row>
- <entry><para>Output directory</para></entry>
-
- <entry><para>Path to a directory into where all output will be
- written by default. Be aware that existing files will be
- overwritten, so be sure to specify the correct
- directory.</para></entry>
- </row>
+<chapter id="tools" >
+ <title>Seam tools</title>
+ <section>
+ <title>jBPM designer and viewer</title>
+ <para>
+ The jBPM designer and viewer is included in JBoss Eclipse IDE, and lets you design and view business processes and pageflows aesthetically. You can find more information in the <ulink url="http://docs.jboss.com/jbpm/v3/gpd/">jBPM documentation</ulink>.
+ </para>
+ <section>
+ <title>Business process designer</title>
+ <para>
+ This tool lets you design your own business process graphically.
+ </para>
+ <mediaobject>
+ <textobject>
+ <phrase>Business process designer</phrase>
+ </textobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/bpmd.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/bpmd.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ <section>
+ <title>Pageflow viewer</title>
+ <para>
+ This tool lets you build graphical representations of pageflows so that complex designs can be shared and compared easily.
+ </para>
+ <mediaobject>
+ <textobject>
+ <phrase>Business process designer</phrase>
+ </textobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/bpmpfv.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/bpmpfv.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ </section>
- <row>
- <entry><para>Reverse engineer from JDBC
- Connection</para></entry>
-
- <entry><para>If enabled the tools will reverse engineer the
- database available via the connection information in the
- selected Hibernate Console Configuration and generate code based
- on the database schema. If not enabled the code generation will
- just be based on the mappings already specified in the Hibernate
- Console configuration.</para></entry>
- </row>
-
- <row>
- <entry><para>Package</para></entry>
-
- <entry><para>The package name here is used as the default
- package name for any entities found when reverse
- engineering.</para></entry>
- </row>
-
- <row>
- <entry><para>reveng.xml</para></entry>
-
- <entry><para>Path to a reveng.xml file. A reveng.xml file allows
- you to control certain aspects of the reverse engineering. e.g.
- how jdbc types are mapped to hibernate types and especially
- important which tables are included/excluded from the process.
- Clicking "setup" allows you to select an existing reveng.xml
- file or create a new one..</para></entry>
- </row>
-
- <row>
- <entry><para>reveng. strategy</para></entry>
-
- <entry><para>If reveng.xml does not provide enough customization
- you can provide your own implementation of an
- ReverseEngineeringStrategy. The class need to be in the claspath
- of the Console Configuration, otherwise you will get class not
- found exceptions.</para></entry>
- </row>
-
- <row>
- <entry><para>Generate basic typed composite ids</para></entry>
-
- <entry><para>This field should always be enabled when generating the Seam CRUD application.
- A table that has a multi-colum primary key a
- <composite-id> mapping will always be created. If this
- option is enabled and there are matching foreign-keys each key
- column is still considered a 'basic' scalar (string, long, etc.)
- instead of a reference to an entity. If you disable this option
- a <key-many-to-one> instead. Note: a <many-to-one>
- property is still created, but is simply marked as non-updatable
- and non-insertable.</para></entry>
- </row>
-
- <row>
- <entry><para>Use custom templates</para></entry>
-
- <entry><para>If enabled, the Template directory will be searched
- first when looking up the velocity templates, allowing you to
- redefine how the individual templates process the hibernate
- mapping model.</para></entry>
- </row>
-
- <row>
- <entry><para>Template directory</para></entry>
-
- <entry><para>A path to a directory with custom velocity
- templates.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
- </section>
-
- <section>
- <title>Exporters</title>
-
- <para>The exporters tab is used to specify which type of code that
- should be generated. Each selection represents an "Exporter" that are
- responsible for generating the code, hence the name.</para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="/images/codegenselectseam.gif" format="GIF" />
- </imageobject>
-
- <imageobject role="html">
- <imagedata align="center"
- fileref="/images/codegenselectseam.gif"
- format="gif" />
- </imageobject>
- </mediaobject>
-
- <para>
- The following table describes in short the various
- exporters. The most relevant for Seam is of course the "JBoss Seam Skeleton app".
- </para>
-
- <table>
- <title>Code generation "Exporter" tab fields</title>
-
- <tgroup cols="2">
- <colspec colnum="1" colwidth="1*" />
-
- <colspec colnum="2" colwidth="3*" />
-
- <colspec colnum="3" colwidth="0.5*" />
-
- <thead>
- <row>
- <entry align="center"><para>Field</para></entry>
-
- <entry align="center"><para>Description</para></entry>
- </row>
- </thead>
-
- <tbody>
- <row>
- <entry><para>Generate domain code</para></entry>
-
- <entry><para>Generates POJO's for all the persistent classes and
- components found in the given Hibernate
- configuration.</para></entry>
- </row>
-
- <row>
- <entry><para>JDK 1.5 constructs</para></entry>
-
- <entry><para>When enabled the POJO's will use JDK 1.5
- constructs.</para></entry>
- </row>
-
- <row>
- <entry><para>EJB3/JSR-220 annotations</para></entry>
-
- <entry><para>When enabled the POJO's will be annotated according
- to the EJB3/JSR-220 persistency specification.</para></entry>
- </row>
-
- <row>
- <entry><para>Generate DAO code</para></entry>
-
- <entry><para>Generates a set of DAO's for each entity
- found.</para></entry>
- </row>
-
- <row>
- <entry><para>Generate Mappings</para></entry>
-
- <entry><para>Generate mapping (hbm.xml) files for each
- entity</para></entry>
- </row>
-
- <row>
- <entry><para>Generate hibernate configuration
- file</para></entry>
-
- <entry><para>Generate a hibernate.cfg.xml file. Used to keep the
- hibernate.cfg.xml uptodate with any new found mapping
- files.</para></entry>
- </row>
-
- <row>
- <entry><para>Generate schema html-documentation</para></entry>
-
- <entry><para>Generates set of html pages that documents the
- database schema and some of the mappings.</para></entry>
- </row>
-
- <row>
- <entry><para>Generate JBoss Seam skeleton app
- (beta)</para></entry>
-
- <entry><para>Generates a complete JBoss Seam skeleton app. The
- generation will include annotated POJO's, Seam controller beans
- and a JSP for the presentation layer. See the generated
- readme.txt for how to use it. </para><para>Note: this exporter
- generates a full application, including a build.xml thus you
- will get the best results if you use an output directory which
- is the root of your project.</para></entry>
- </row>
- </tbody>
- </tgroup>
- </table>
-
- </section>
-
- <section>
- <title>Generating and using the code</title>
-
- <para>
- When you have finished filling out the settings, simply press "Run" to start the generation of code.
- This might take a little while if you are reverse engineering from a database.
- </para>
-
- <para>
- When the generation have finished you should now have a complete skeleton Seam application in the output directory.
- In the output directory there is a <literal>readme.txt</literal> file describing the steps needed to deploy and run the example.
- </para>
-
- <para>
- If you want to regenerate/update the skeleton code then simply run the code generation again by selecting the "Hibernate Code Generation" in the toolbar or "Run" menu. Enjoy.
- </para>
- </section>
-
- </section>
-
- </section>
- -->
+ <!-- #modify: TODO I'm assuming this content is to be added back in at some point? --> <!-- <section> <title>CRUD-application generator</title> <para> This chapter, will give you a short overview of the support for Seam that is available in the Hibernate Tools. Hibernate Tools is a set of tools for working with Hibernate and related technologies, such as JBoss Seam and EJB3. The tools are available as a set of eclipse plugins and Ant tasks. You can download the Hibernate Tools from the JBoss Eclipse IDE or Hibernate Tools websites. </para> <para> The specific support for Seam that is currently available is generation of a fully functional Seam based CRUD-application. The CRUD-application can be generated based on your existing Hibernate mapping files or EJB3 annotated POJO's or even fully reverse engineered from your existing database schema. </para> <para> The following sections is focused on the features required to understand for usage with Seam. The content is derive!
d from the the Hibernate Tools reference documentation. Thus if you need more detailed information please refer to the Hibernate Tools documentation. </para> <section> <title>Creating a Hibernate configuration file</title> <para> To be able to reverse engineer and generate code a hibernate.properties or hibernate.cfg.xml file is needed. The Hibernate Tools provide a wizard for generating the hibernate.cfg.xml file if you do not already have such file. </para> <para> Start the wizard by clicking "New Wizard" (Ctrl+N), select the Hibernate/Hibernate Configuration file (cfg.xml) wizard and press "Next". After selecting the wanted location for the hibernate.cfg.xml file, you will see the following page: </para> <mediaobject> <imageobject role="fo"> <imagedata fileref="/images/hibernatecfgwizard.gif" format="gif" contentwidth="5cm" /> </imageobject> <imageobject role="html"> <imagedata align="center" fileref="/images/hibernatecfgwizard.gif" format="gif" /> </imageobject> </media!
object> <para> Tip: The contents in the combo boxes for the JD!
BC drive
r class and JDBC URL change automatically, depending on the Dialect and actual driver you have chosen. </para> <para> Enter your configuration information in this dialog. Details about the configuration options can be found in Hibernate reference documentation. </para> <para> Press "Finish" to create the configuration file, after optionally creating a Console onfiguration, the hibernate.cfg.xml will be automatically opened in an editor. The last option "Create Console Configuration" is enabled by default and when enabled i will automatically use the hibernate.cfg.xml for the basis of a "Console Configuration" </para> </section> <section> <title>Creating a Hibernate Console configuration</title> <para> A Console Configuration describes to the Hibernate plugin which configuration files should be used to configure hibernate, including which classpath is needed to load the POJO's, JDBC drivers etc. It is required to make usage of query prototyping, reverse engineering and code g!
eneration. You can have multiple named console configurations. Normally you would just need one per project, but more (or less) is definitly possible. </para> <para> You create a console configuration by running the Console Configuration wizard, shown in the following screenshot. The same wizard will also be used if you are coming from the hibernate.cfg.xml wizard and had enabled "Create Console Configuration". </para> <mediaobject> <title>Creating a Hibernate Console configuration</title> <imageobject role="fo"> <imagedata fileref="/images/consolecfgwizard.gif" format="GIF" /> </imageobject> <imageobject role="html"> <imagedata align="center" fileref="/images/consolecfgwizard.gif" format="gif" /> </imageobject> </mediaobject> <para> The following table describes the relevant settings. The wizard can automatically detect default values for most of these if you started the Wizard with the relevant java project selected </para> <table> <title>Hibernate Console Configuration !
Parameters</title> <tgroup cols="3"> <colspec colnum="1" colwi!
dth="1*"
/> <colspec colnum="2" colwidth="3*" /> <colspec colnum="3" colwidth="1*" /> <thead> <row> <entry align="center"> <para>Parameter</para> </entry> <entry align="center"> <para>Description</para> </entry> <entry align="center"> <para>Auto detected value</para> </entry> </row> </thead> <tbody> <row> <entry> <para>Name</para> </entry> <entry> <para>The unique name of the configuration</para> </entry> <entry> <para>Name of the selected project</para> </entry> </row> <row> <entry> <para>Property file</para> </entry> <entry> <para>Path to a hibernate.properties file</para> </entry> <entry> <para>First hibernate.properties file found in the selected project</para> </entry> </row> <row> <entry> <para>Configuration file</para> </entry> <entry> <para>Path to a hibernate.cfg.xml file</para> </entry> <entry> <para>First hibernate.cfg.xml file found in the selected project</para> </entry> </row> <row> <entry> <para>Enable Hibernate ejb3/annotations</para> </entry> <entry> <para>Selecting!
this option enables usage of annotated classes. hbm.xml files are of course still possible to use too. This feature requires running the Eclipse IDE with a JDK 5 runtime, otherwise you will get classloading and/or version errors.</para> </entry> <entry> <para>Not enabled</para> </entry> </row> <row> <entry> <para>Mapping files</para> </entry> <entry> <para>List of additional mapping files that should be loaded. Note: A hibernate.cfg.xml can also contain mappings. Thus if these a duplicated here, you will get "Duplicate mapping" errors when using the console configuration.</para> </entry> <entry> <para>If no hibernate.cfg.xml file is found, all hbm.xml files found in the selected project</para> </entry> </row> <row> <entry> <para>Classpath</para> </entry> <entry> <para>The classpath for loading POJO and JDBC drivers. Do not add Hibernate core libraries or dependencies, they are already included. If you get ClassNotFound errors then check this list for possible missing or re!
dundant directories/jars.</para> </entry> <entry> <para>The de!
fault bu
ild output directory and any JARs with a class implementing java.sql.Driver in the selected project</para> </entry> </row> </tbody> </tgroup> </table> <para>Clicking "Finish" creates the configuration and shows it in the "Hibernate Configurations" view</para> <mediaobject> <title>Console overview</title> <imageobject role="fo"> <imagedata align="center" fileref="/images/consoleoutline-before-reveng.gif" format="GIF" /> </imageobject> <imageobject role="html"> <imagedata align="center" fileref="/images/consoleoutline-before-reveng.gif" format="gif" /> </imageobject> </mediaobject> </section> <section> <title>Reverse engineering and code generation</title> <para> A very simple "click-and-generate" reverse engineering and code generation facility is available. It is this facility that allows you to generate the skeleton for a full Seam CRUD application. </para> <para> To start working with this process, start the "Hibernate Code Generation" which is available in the toolbar via!
the Hibernate icon or via the "Run/Hibernate Code Generation" menu item. </para> <section> <title>Code Generation Launcher</title> <para>When you click on "Hibernate Code Generation" the standard Eclipse launcher dialog will appear. In this dialog you can create, edit and delete named Hibernate code generation "launchers".</para> <mediaobject> <imageobject role="fo"> <imagedata fileref="/images/codegendropdown.gif" format="GIF" /> </imageobject> <imageobject role="html"> <imagedata align="center" fileref="/images/codegendropdown.gif" format="gif" /> </imageobject> </mediaobject> <para>The dialog has the standard tabs "Refresh" and "Common" that can be used to configure which directories should be automatically refreshed and various general settings launchers, such as saving them in a project for sharing the launcher within a team.</para> <mediaobject> <imageobject role="fo"> <imagedata fileref="/images/codegenmaintab.gif" format="GIF" /> </imageobject> <imageobject role="h!
tml"> <imagedata align="center" fileref="/images/codegenmainta!
b.gif" f
ormat="gif" /> </imageobject> </mediaobject> <para>The first time you create a code generation launcher you should give it a meaningfull name, otherwise the default prefix "New_Generation" will be used.</para> <para>Note: The "At least one exporter option must be selected" is just a warning stating that for this launch to work you need to select an exporter on the Exporter tab. When an exporter has been selected the warning will disappear.</para> <para>On the "Main" tab you the following fields:</para> <table> <title>Code generation "Main" tab fields</title> <tgroup cols="2"> <colspec colnum="1" colwidth="1*" /> <colspec colnum="2" colwidth="3*" /> <colspec colnum="3" colwidth="0.5*" /> <thead> <row> <entry align="center"><para>Field</para></entry> <entry align="center"><para>Description</para></entry> </row> </thead> <tbody> <row> <entry><para>Console Configuration</para></entry> <entry><para>The name of the console configuration which should be used when code generating.</!
para></entry> </row> <row> <entry><para>Output directory</para></entry> <entry><para>Path to a directory into where all output will be written by default. Be aware that existing files will be overwritten, so be sure to specify the correct directory.</para></entry> </row> <row> <entry><para>Reverse engineer from JDBC Connection</para></entry> <entry><para>If enabled the tools will reverse engineer the database available via the connection information in the selected Hibernate Console Configuration and generate code based on the database schema. If not enabled the code generation will just be based on the mappings already specified in the Hibernate Console configuration.</para></entry> </row> <row> <entry><para>Package</para></entry> <entry><para>The package name here is used as the default package name for any entities found when reverse engineering.</para></entry> </row> <row> <entry><para>reveng.xml</para></entry> <entry><para>Path to a reveng.xml file. A reveng.xml file a!
llows you to control certain aspects of the reverse engineerin!
g. e.g.
how jdbc types are mapped to hibernate types and especially important which tables are included/excluded from the process. Clicking "setup" allows you to select an existing reveng.xml file or create a new one..</para></entry> </row> <row> <entry><para>reveng. strategy</para></entry> <entry><para>If reveng.xml does not provide enough customization you can provide your own implementation of an ReverseEngineeringStrategy. The class need to be in the claspath of the Console Configuration, otherwise you will get class not found exceptions.</para></entry> </row> <row> <entry><para>Generate basic typed composite ids</para></entry> <entry><para>This field should always be enabled when generating the Seam CRUD application. A table that has a multi-colum primary key a <composite-id> mapping will always be created. If this option is enabled and there are matching foreign-keys each key column is still considered a 'basic' scalar (string, long, etc.) instead of a reference to an en!
tity. If you disable this option a <key-many-to-one> instead. Note: a <many-to-one> property is still created, but is simply marked as non-updatable and non-insertable.</para></entry> </row> <row> <entry><para>Use custom templates</para></entry> <entry><para>If enabled, the Template directory will be searched first when looking up the velocity templates, allowing you to redefine how the individual templates process the hibernate mapping model.</para></entry> </row> <row> <entry><para>Template directory</para></entry> <entry><para>A path to a directory with custom velocity templates.</para></entry> </row> </tbody> </tgroup> </table> </section> <section> <title>Exporters</title> <para>The exporters tab is used to specify which type of code that should be generated. Each selection represents an "Exporter" that are responsible for generating the code, hence the name.</para> <mediaobject> <imageobject role="fo"> <imagedata fileref="/images/codegenselectseam.gif" form!
at="GIF" /> </imageobject> <imageobject role="html"> <imagedat!
a align=
"center" fileref="/images/codegenselectseam.gif" format="gif" /> </imageobject> </mediaobject> <para> The following table describes in short the various exporters. The most relevant for Seam is of course the "JBoss Seam Skeleton app". </para> <table> <title>Code generation "Exporter" tab fields</title> <tgroup cols="2"> <colspec colnum="1" colwidth="1*" /> <colspec colnum="2" colwidth="3*" /> <colspec colnum="3" colwidth="0.5*" /> <thead> <row> <entry align="center"><para>Field</para></entry> <entry align="center"><para>Description</para></entry> </row> </thead> <tbody> <row> <entry><para>Generate domain code</para></entry> <entry><para>Generates POJO's for all the persistent classes and components found in the given Hibernate configuration.</para></entry> </row> <row> <entry><para>JDK 1.5 constructs</para></entry> <entry><para>When enabled the POJO's will use JDK 1.5 constructs.</para></entry> </row> <row> <entry><para>EJB3/JSR-220 annotations</para></entry> <entry><para>Wh!
en enabled the POJO's will be annotated according to the EJB3/JSR-220 persistency specification.</para></entry> </row> <row> <entry><para>Generate DAO code</para></entry> <entry><para>Generates a set of DAO's for each entity found.</para></entry> </row> <row> <entry><para>Generate Mappings</para></entry> <entry><para>Generate mapping (hbm.xml) files for each entity</para></entry> </row> <row> <entry><para>Generate hibernate configuration file</para></entry> <entry><para>Generate a hibernate.cfg.xml file. Used to keep the hibernate.cfg.xml uptodate with any new found mapping files.</para></entry> </row> <row> <entry><para>Generate schema html-documentation</para></entry> <entry><para>Generates set of html pages that documents the database schema and some of the mappings.</para></entry> </row> <row> <entry><para>Generate JBoss Seam skeleton app (beta)</para></entry> <entry><para>Generates a complete JBoss Seam skeleton app. The generation will include annotated POJO's, Seam c!
ontroller beans and a JSP for the presentation layer. See the !
generate
d readme.txt for how to use it. </para><para>Note: this exporter generates a full application, including a build.xml thus you will get the best results if you use an output directory which is the root of your project.</para></entry> </row> </tbody> </tgroup> </table> </section> <section> <title>Generating and using the code</title> <para> When you have finished filling out the settings, simply press "Run" to start the generation of code. This might take a little while if you are reverse engineering from a database. </para> <para> When the generation have finished you should now have a complete skeleton Seam application in the output directory. In the output directory there is a <literal>readme.txt</literal> file describing the steps needed to deploy and run the example. </para> <para> If you want to regenerate/update the skeleton code then simply run the code generation again by selecting the "Hibernate Code Generation" in the toolbar or "Run" menu. Enjoy. </para> </section>!
</section> </section> -->
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Tutorial.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Tutorial.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Tutorial.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,1628 +1,1561 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
-<chapter id="tutorial">
- <title>Seam Tutorial</title>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- <section id="try-examples">
- <title>Using the Seam examples</title>
-
- <para>Seam provides a number of example applications demonstrating how to use the various features
- of Seam. This tutorial will guide you through a few of those examples to help you get started
- learning Seam. The Seam examples are located in the <filename>examples</filename> subdirectory
- of the Seam distribution. The registration example, which will be the first example we look at,
- is in the <filename>examples/registration</filename> directory.</para>
-
- <para>Each example has the same directory structure:</para>
-
- <itemizedlist>
- <listitem>
- <para> The <filename>view</filename> directory contains view-related files such as
- web page templates, images and stylesheets.
-
- </para>
- </listitem>
- <listitem>
- <para> The <filename>resources</filename> directory contains deployment descriptors and
- other configuration files.
- </para>
- </listitem>
- <listitem>
- <para> The <filename>src</filename> directory contains the application source code. </para>
- </listitem>
-
- </itemizedlist>
-
- <para>
- Note that all the examples are built and run from the Ant
- <filename>build.xml</filename>, so you'll need a recent version
- of Ant installed before you get started.
+<chapter id="tutorial" >
+ <title>Seam Tutorial</title>
+ <section id="try-examples">
+ <title>Using the Seam examples</title>
+ <para>
+ Seam provides a number of example applications which demonstrate how to use a variety of Seam's features. This tutorial will guide you through a few of those examples to help you get started learning Seam. The Seam examples are located in the <filename>examples</filename> subdirectory of the Seam distribution. The first example, on registration, is in the <filename>examples/registration</filename> directory.
</para>
-
- <section>
- <title>Running the examples on JBoss AS</title>
+ <para>
+ Each example has the same directory structure:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <filename>view</filename> directory contains view-related files such as web page templates, images and stylesheets.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>resources</filename> directory contains deployment descriptors and other configuration files.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <filename>src</filename> directory contains the application source code.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Note that all examples are built and run from the Ant <filename>build.xml</filename>, so you will need a recent version of Ant installed before you get started.
+ </para>
+ <section>
+ <title>Running the examples on JBoss AS</title>
+ <para>
+ The examples are configured for use on JBoss Enterprise Application Platform. You will need to set <literal>jboss.home</literal>, in the shared <filename>build.properties</filename> file (in the root folder of your Seam installation) to the location of your JBoss AS installation.
+ </para>
+ <para>
+ Once you have set the location of JBoss AS and started the application server, you can build and deploy any example by typing <literal>ant explode</literal> in that example's directory. Any example that is packaged as an EAR (Enterprise Archive) deploys to a URL like <literal>/seam-<replaceable>example</replaceable></literal>, where <replaceable>example</replaceable> is the name of the example folder, with one exception: if the example folder begins with "seam", the prefix "seam" is ommitted. For instance, if JBoss AS is running on port 8080, the URL for the Registration example is <ulink url="http://localhost:8080/seam-registration/"> <literal>http://localhost:8080/seam-registration/</literal></ulink>, whereas the URL for the SeamSpace example is <ulink url="http://localhost:8080/seam-space/"> <literal>http://localhost:8080/seam-space/</literal></ulink>.
+ </para>
+ <para>
+ If, on the other hand, the example is packaged as a WAR, then it deploys to a URL like <literal>/jboss-seam-<replaceable>example</replaceable></literal>. <!--Most of the examples can be deployed as a WAR to Tomcat with Embedded JBoss by typing <literal>ant tomcat.deploy</literal>.-->
+ </para>
+ <note>
+ <para>
+ Several of the examples — groovybooking, hibernate, jpa, and spring — can only be deployed as a WAR.
+ </para>
+ </note>
+ </section>
+
+ <!--<section>
+ <title>Running the examples on Tomcat</title>
+ <para>
+ The examples are also configured for use on Tomcat 6.0. You will need to follow the instructions for installing JBoss Embedded on Tomcat 6.0 in <xref linkend="config.install.embedded" />. JBoss Embedded is only required to run the Seam demonstrations that use Enterprise JavaBeans 3.0 (EJB3) components on Tomcat. There are also examples of non-EJB3 applications that can be run on Tomcat without the use of JBoss Embedded.
+ </para>
+ <para>
+ You will need to set <literal>tomcat.home</literal> (in the shared <literal>build.properties</literal> file in the root folder of your Seam installation) to the location of your Tomcat installation. Make sure to set the location of your Tomcat.
+ </para>
+ <para>
+ You will also need to use a different Ant target when using Tomcat. Use <literal>ant tomcat.deploy</literal> in the example subdirectory to build and deploy any example for Tomcat.
+ </para>
+ <para>
+ On Tomcat, the examples deploy to URLs like <literal>/jboss-seam-<replaceable>example</replaceable>]]></literal>, so for the registration example, the URL would be <ulink url="http://localhost:8080/jboss-seam-registration/"> <literal>http://localhost:8080/jboss-seam-registration/</literal></ulink>. The same is true for examples that deploy as a WAR, as mentioned in the previous section.
+ </para>
+ </section>-->
+
+ <section>
+ <title>Running the example tests</title>
+ <para>
+ Most of the examples come with a suite of TestNG integration tests. The easiest way to run the tests is to run <literal>ant test</literal>. It is also possible to run the tests inside your IDE using the TestNG plugin. Consult the readme.txt in the examples directory of the Seam distribution for more information.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="registration-example">
+ <title>Your first Seam application: the registration example</title>
+ <para>
+ The registration example is a simple application that lets a new user store their username, real name, and password in the database. This example uses only basic functions to demonstrate the use of an EJB3 session bean as a JSF action listener, and the basic configuration of Seam.
+ </para>
+ <para>
+ The start page displays a basic form with three input fields. Filling them in and submitting the form will save a user object in the database.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/registration.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/registration.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <section>
+ <title>Understanding the code</title>
+ <para>
+ The example is implemented with two Facelets templates: one entity bean, and one stateless session bean. This section will take you through the code in detail, starting from the base level.
+ </para>
+ <section>
+ <title>The entity bean: <literal>User.java</literal></title>
+ <para>
+ We need an EJB entity bean for user data. This class defines <emphasis>persistence</emphasis> and <emphasis>validation</emphasis> declaratively, via annotations. It also requires some extra annotations to define the class as a Seam component.
+ </para>
+ <!-- Can't use code hightlighting with callouts --> <!-- #removed: Because it broke things. <example> <title>User.java</title> <programlistingco> <areaspec> <area id="registration-entity-annotation" coords="1"/> <area id="registration-name-annotation" coords="2"/> <area id="registration-scope-annotation" coords="3"/> <area id="registration-table-annotation" coords="4"/> <area id="registration-attributes" coords="9"/> <area id="registration-empty-constructor" coords="20"/> <area id="registration-notnull" coords="22"/> <area id="registration-id-annotation" coords="44"/> </areaspec> <programlisting role="JAVA"><![CDATA[@Entity @Name("user") @Scope(SESSION) @Table(name="users") public class User implements Serializable { private static final long serialVersionUID = 1881413500711441951L; private String username; private String password; private String name; public User(String name, String password, String username) { this.name = name; this.password = password; this.use!
rname = username; } public User() {} @NotNull @Length(min=5, max=15) public String getPassword() { return password; } public void setPassword(String password) { this.password = password; } @NotNull public String getName() { return name; } public void setName(String name) { this.name = name; } @Id @NotNull @Length(min=5, max=15) public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } }]]></programlisting> <calloutlist> <callout arearefs="registration-entity-annotation"> <para> The EJB3 standard <literal>@Entity</literal> annotation indicates that the <literal>User</literal> class is an entity bean. </para> </callout>
+ <callout arearefs="registration-name-annotation"> <para> A Seam component must have a <emphasis>component name</emphasis> specified by the <xref linkend="name-annotation"> <literal>@Name</literal> </xref> annotation. This name must be unique within the Seam application. When JSF asks Seam to resolve a currently undefined (null) context variable whose name matches that of a Seam component, Seam will instantiate that component, and bind the new instance to the context variable. In this case, Seam will instantiate a <literal>User</literal> the first time JSF encounters a variable named <literal>user</literal>.</para> </callout>
+ <callout arearefs="registration-scope-annotation"> <para> Whenever Seam instantiates a component, it binds the new instance to a context variable in the component's <emphasis>default context</emphasis>. The default context is specified using the <xref linkend="scope-annotation"> <literal>@Scope</literal> </xref> annotation. The <literal>User</literal> bean is a session scoped component. </para> </callout>
+ <callout arearefs="registration-table-annotation"> <para> The EJB standard <literal>@Table</literal> annotation indicates that the <literal>User</literal> class is mapped to the <literal>users</literal> table. </para> </callout>
+ <callout arearefs="registration-attributes"> <para> <literal>name</literal>, <literal>password</literal>, and <literal>username</literal> are the persistent attributes of the entity bean. All of our persistent attributes define accessor methods. These are needed when this component is used by JSF in the render response and update model values phases. </para> </callout>
+ <callout arearefs="registration-empty-constructor"> <para> An empty constructor is required by both the EJB specification and by Seam. </para> </callout>
+ <callout arearefs="registration-notnull"> <para> The <literal>@NotNull</literal> and <literal>@Length</literal> annotations are part of the Hibernate Validator framework. Seam integrates Hibernate Validator and lets you use it for data validation (even if you are not using Hibernate for persistence). </para> </callout>
+ <callout arearefs="registration-id-annotation"> <para> The EJB standard <literal>@Id</literal> annotation indicates the primary key attribute of the entity bean. </para> </callout>
+ </calloutlist> </programlistingco> </example> -->
+ <!-- <example>
+ <title>User.java</title> -->
- <para>The examples are configured for use on JBoss EAP AS. You'll need to set <literal>jboss.home</literal>,
- in the shared <literal>build.properties</literal> file in the root folder of your Seam
- installation, to the location of your JBoss AS installation.</para>
-
- <para>Once you've set the location of JBoss EAP AS and started the application server, you can build and deploy
- any example by typing <literal>ant explode</literal> in the the directory for that example. Any example
- that is packaged as an EAR deploys to a URL like
- <literal>/seam-<replaceable>example</replaceable></literal>, where <replaceable>example</replaceable> is
- the name of the example folder, with one exception. If the example folder begins with seam, the prefix
- "seam" is ommitted. For instance, if JBoss AS is running on port 8080, the URL for the registration
- example is <ulink url="http://localhost:8080/seam-registration/">
- <literal>http://localhost:8080/seam-registration/</literal></ulink>, whereas the URL for the seamspace
- example is <ulink url="http://localhost:8080/seam-space/">
- <literal>http://localhost:8080/seam-space/</literal></ulink>.</para>
-
- <para>If, on the other hand, the example gets packaged as a WAR, then it deploys to a URL like
- <literal>/jboss-seam-<replaceable>example</replaceable></literal>. Several of the examples
- can only be deployed as a WAR. Those examples are groovybooking, hibernate, jpa, and spring.
- </para>
-
- </section>
-
- <section>
- <title>Running the example tests</title>
- <para>
- Most of the examples come with a suite of TestNG integration tests. The easiest way to run the tests is
- to run <literal>ant test</literal>.
- </para>
-
- <para>
- It is also possible to run the tests inside your IDE using the
- TestNG plugin. This requires to run ant test, before running or debugging Seam test cases in Eclipse IDE.
-
-So the following steps are the corect way:
-1. Run ant test for the used example in its directory, e.g. booking -> go to booking example directory and in that location run ant test.
-2. Create a New Java project in Eclipse from existing ant build file and select booking example build file.
-3. Select testng suite or testng class and Choose Run As -> TestNg Test, you can cancel the processing of testng run.
-4. Go to Run -> Run configurations and edit the created TestNG runner.
-5. If you use java 6 as runtime, add jvm argument "-Dsun.lang.ClassLoader.allowArraySyntax=true" on Arguments tab.
-6. goto Classpath tab and remove all User entries.
-7. Then in according to this page http://seamframework.org/Community/GettingStartedDevelopingTheSeamFramework#H-RunningIntegrationTestsFromTheTestNGEclipsePlugin, add necessary jars and folders (<instalation_of_seam>/bootstrap, booking/test-build).
- </para>
- </section>
-
- </section>
-
- <section id="registration-example">
- <title>Your first Seam application: the registration example</title>
-
- <para> The registration example is a simple application that lets a new user store his username, real
- name and password in the database. The example isn't intended to show off all of the cool functionality of
- Seam. However, it demonstrates the use of an EJB3 session bean as a JSF action listener, and basic
- configuration of Seam. </para>
-
- <para> We'll go slowly, since we realize you might not yet be familiar with EJB 3.0. </para>
-
- <para> The start page displays a very basic form with three input fields. Try filling them in and then
- submitting the form. This will save a user object in the database. </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/registration.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/registration.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <section>
- <title>Understanding the code</title>
-
- <para> The example is implemented with two Facelets templates, one entity bean and one
- stateless session bean. Let's take a look at the code, starting from the "bottom".
- </para>
-
- <section>
- <title>The entity bean: <literal>User.java</literal></title>
-
- <para> We need an EJB entity bean for user data. This class defines <emphasis>persistence</emphasis> and
- <emphasis>validation</emphasis> declaratively, via annotations. It also needs some extra
- annotations that define the class as a Seam component. </para>
- <!-- Can't use code hightlighting with callouts -->
- <example>
- <title>User.java</title>
- <programlistingco>
- <areaspec>
- <area id="registration-entity-annotation" coords="1"/>
- <area id="registration-name-annotation" coords="2"/>
- <area id="registration-scope-annotation" coords="3"/>
- <area id="registration-table-annotation" coords="4"/>
- <area id="registration-attributes" coords="9"/>
- <area id="registration-empty-constructor" coords="20"/>
- <area id="registration-notnull" coords="22"/>
- <area id="registration-id-annotation" coords="44"/>
- </areaspec>
- <programlisting role="JAVA"><![CDATA[@Entity
+ <!-- <example><title>User.java</title> -->
+ <formalpara><title>User.java Example</title>
+ <para>
+<programlisting role="JAVA"><![CDATA[@Entity
@Name("user")
@Scope(SESSION)
@Table(name="users")
-public class User implements Serializable
-{
- private static final long serialVersionUID = 1881413500711441951L;
-
- private String username;
- private String password;
- private String name;
-
- public User(String name, String password, String username)
- {
- this.name = name;
- this.password = password;
- this.username = username;
- }
-
- public User() {}
-
- @NotNull @Length(min=5, max=15)
- public String getPassword()
- {
- return password;
- }
+public class User implements Serializable {
+ private static final long serialVersionUID = 1881413500711441951L;
+
+ private String username;
+ private String password;
+ private String name;
+
+ public User(String name, String password, String username) {
+ this.name = name;
+ this.password = password;
+ this.username = username;
+ }
+
+ public User() {}
+
+ @NotNull @Length(min=5, max=15)
+ public String getPassword() {
+ return password;
+ }
- public void setPassword(String password)
- {
- this.password = password;
- }
-
- @NotNull
- public String getName()
- {
- return name;
- }
+ public void setPassword(String password) {
+ this.password = password;
+ }
+
+ @NotNull
+ public String getName() {
+ return name;
+ }
- public void setName(String name)
- {
- this.name = name;
- }
-
- @Id @NotNull @Length(min=5, max=15)
- public String getUsername()
- {
- return username;
- }
+ public void setName(String name) {
+ this.name = name;
+ }
+
+ @Id @NotNull @Length(min=5, max=15)
+ public String getUsername() {
+ return username;
+ }
- public void setUsername(String username)
- {
- this.username = username;
- }
+ public void setUsername(String username) {
+ this.username = username;
+ }
-}]]></programlisting>
- <calloutlist>
- <callout arearefs="registration-entity-annotation">
- <para> The EJB3 standard <literal>@Entity</literal> annotation indicates that the
- <literal>User</literal> class is an entity bean. </para>
- </callout>
- <callout arearefs="registration-name-annotation">
- <para> A Seam component needs a <emphasis>component name</emphasis> specified by the
- <link linkend="name-annotation">
- <literal>@Name</literal>
- </link> annotation. This name must be unique within the Seam application. When JSF
- asks Seam to resolve a context variable with a name that is the same as a Seam
- component name, and the context variable is currently undefined (null), Seam will
- instantiate that component, and bind the new instance to the context variable. In
- this case, Seam will instantiate a <literal>User</literal> the first time JSF
- encounters a variable named <literal>user</literal>. </para>
- </callout>
- <callout arearefs="registration-scope-annotation">
- <para> Whenever Seam instantiates a component, it binds the new instance to a context
- variable in the component's <emphasis>default context</emphasis>. The default
- context is specified using the <link linkend="scope-annotation">
- <literal>@Scope</literal>
- </link> annotation. The <literal>User</literal> bean is a session scoped component.
- </para>
- </callout>
- <callout arearefs="registration-table-annotation">
- <para> The EJB standard <literal>@Table</literal> annotation indicates that the
- <literal>User</literal> class is mapped to the <literal>users</literal> table.
- </para>
- </callout>
- <callout arearefs="registration-attributes">
- <para>
- <literal>name</literal>, <literal>password</literal> and <literal>username</literal>
- are the persistent attributes of the entity bean. All of our persistent attributes
- define accessor methods. These are needed when this component is used by JSF in the
- render response and update model values phases. </para>
- </callout>
- <callout arearefs="registration-empty-constructor">
- <para> An empty constructor is both required by both the EJB specification and by Seam.
- </para>
- </callout>
- <callout arearefs="registration-notnull">
- <para> The <literal>@NotNull</literal> and <literal>@Length</literal> annotations are
- part of the Hibernate Validator framework. Seam integrates Hibernate Validator and
- lets you use it for data validation (even if you are not using Hibernate for
- persistence). </para>
- </callout>
- <callout arearefs="registration-id-annotation">
- <para> The EJB standard <literal>@Id</literal> annotation indicates the primary key
- attribute of the entity bean. </para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
- <para> The most important things to notice in this example are the <literal>@Name</literal> and
- <literal>@Scope</literal> annotations. These annotations establish that this class is a Seam component. </para>
- <para> We'll see below that the properties of our <literal>User</literal> class are bound
- directly to JSF components and are populated by JSF during the update model values phase. We
- don't need any tedious glue code to copy data back and forth between the JSP pages and the
- entity bean domain model. </para>
- <para> However, entity beans shouldn't do transaction management or database access. So we can't use
- this component as a JSF action listener. For that we need a session bean. </para>
+}]]>
+</programlisting>
+ </para>
+ </formalpara>
- </section>
+
+ <!-- </example> -->
+
+<formalpara><title>User.java Explanatory Notes</title>
+<para>
- <section>
- <title>The stateless session bean class: <literal>RegisterAction.java</literal></title>
-
- <para> Most Seam application use session beans as JSF action listeners (you can use JavaBeans instead if
- you like). </para>
- <para> We have exactly one JSF action in our application, and one session bean method attached to it. In
- this case, we'll use a stateless session bean, since all the state associated with our action is
- held by the <literal>User</literal> bean. </para>
-
- <para> This is the only really interesting code in the example! </para>
- <!-- Can't use code hightlighting with callouts -->
- <example>
- <title>RegisterAction.java</title>
- <programlistingco>
- <areaspec>
- <area id="registration-stateless-annotation" coords="1"/>
- <area id="registration-in-annotation" coords="6"/>
- <area id="registration-persistencecontext-annotation" coords="9"/>
- <area id="registration-logger-annotation" coords="12"/>
- <area id="registration-action-listener" coords="15"/>
- <area id="registration-query" coords="18"/>
- <area id="registration-log" coords="24"/>
- <area id="registration-outcome" coords="25"/>
- <area id="registration-builtin" coords="29"/>
- </areaspec>
- <programlisting><![CDATA[@Stateless
+ <orderedlist>
+ <listitem>
+ <para>
+ The EJB3 standard <literal>@Entity</literal> annotation indicates that the <literal>User</literal> class is an entity bean.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A Seam component must have a <emphasis>component name</emphasis> specified by the <xref linkend="name-annotation" /> <literal>@Name</literal> annotation. This name must be unique within the Seam application. When JSF asks Seam to resolve a currently undefined (null) context variable whose name matches that of a Seam component, Seam will instantiate that component, and bind the new instance to the context variable. In this case, Seam will instantiate a <literal>User</literal> the first time JSF encounters a variable named <literal>user</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Whenever Seam instantiates a component, it binds the new instance to a context variable in the component's <emphasis>default context</emphasis>. The default context is specified using the <xref linkend="scope-annotation" /> <literal>@Scope</literal> annotation. The <literal>User</literal> bean is a session scoped component.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The EJB standard <literal>@Table</literal> annotation indicates that the <literal>User</literal> class is mapped to the <literal>users</literal> table.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>name</literal>, <literal>password</literal>, and <literal>username</literal> are the persistent attributes of the entity bean. All of our persistent attributes define accessor methods. These are needed when this component is used by JSF in the render response and update model values phases.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ An empty constructor is required by both the EJB specification and by Seam.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>@NotNull</literal> and <literal>@Length</literal> annotations are part of the Hibernate Validator framework. Seam integrates Hibernate Validator and lets you use it for data validation (even if you are not using Hibernate for persistence).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The EJB standard <literal>@Id</literal> annotation indicates the primary key attribute of the entity bean.
+ </para>
+ </listitem>
+ </orderedlist>
+ <!-- </example> -->
+ </para>
+</formalpara>
+ <para>
+ The most important things to notice in this example are the <literal>@Name</literal> and <literal>@Scope</literal> annotations. These annotations establish that this class is a Seam component.
+ </para>
+ <para>
+ In the next section, you will see that the properties of the <literal>User</literal> class are bound directly to JSF components and populated by JSF during the update model values phase. There is no glue code to copy data back and forth between the JSP pages and the entity bean domain model.
+ </para>
+ <para>
+ However, entity beans should not perform transaction management or database access, so this component should not be used as a JSF action listener. In this situation, a session bean is a better choice.
+ </para>
+ </section>
+
+ <section>
+ <title>The stateless session bean class: <literal>RegisterAction.java</literal></title>
+ <para>
+ Most Seam applications use session beans as JSF action listeners, though you may also use JavaBeans.
+ </para>
+ <para>
+ We have exactly one JSF action in this application, and one session bean method attached to it. In this case, we'll use a stateless session bean, since all the state associated with our action is held by the <literal>User</literal> bean.
+ </para>
+ <para>
+ The relevant code is shown below:
+ </para>
+ <!-- Can't use code hightlighting with callouts --> <!-- #removed: so that it would not break things. <example> <title>RegisterAction.java</title> <programlistingco> <areaspec> <area id="registration-stateless-annotation" coords="1"/> <area id="registration-in-annotation" coords="6"/> <area id="registration-persistencecontext-annotation" coords="9"/> <area id="registration-logger-annotation" coords="12"/> <area id="registration-action-listener" coords="15"/> <area id="registration-query" coords="18"/> <area id="registration-log" coords="24"/> <area id="registration-outcome" coords="25"/> <area id="registration-builtin" coords="29"/> </areaspec> <programlisting><![CDATA[@Stateless @Name("register") public class RegisterAction implements Register { @In private User user; @PersistenceContext private EntityManager em; @Logger private Log log; public String register() { List existing = em.createQuery( "select username from User where username = #{user.username}") .getResu!
ltList(); if (existing.size()==0) { em.persist(user); log.info("Registered new user #{user.username}"); return "/registered.xhtml"; } else { FacesMessages.instance().add("User #{user.username} already exists"); return null; } } }]]></programlisting> <calloutlist> <callout arearefs="registration-stateless-annotation"> <para> The EJB <literal>@Stateless</literal> annotation marks this class as a stateless session bean. </para> </callout> <callout arearefs="registration-in-annotation"> <para> The <xref linkend="in-annotation"> <literal>@In</literal> </xref> annotation marks an attribute of the bean as injected by Seam. In this case, the attribute is injected from a context variable named <literal>user</literal> (the instance variable name). </para> </callout> <callout arearefs="registration-persistencecontext-annotation"> <para> The EJB standard <literal>@PersistenceContext</literal> annotation is used to inject the EJB3 entity manager. </para> </callout> <callout arearefs="re!
gistration-logger-annotation"> <para> The Seam <literal>@Logge!
r</liter
al> annotation is used to inject the component's <literal>Log</literal> instance. </para> </callout> <callout arearefs="registration-action-listener"> <para> The action listener method uses the standard EJB3 <literal>EntityManager</literal> API to interact with the database, and returns the JSF outcome. Note that, since this is a session bean, a transaction begins automatically when the <literal>register()</literal> method is called, and is committed when it completes. </para> </callout> <callout arearefs="registration-query"> <para>Notice that Seam lets you use a JSF EL expression inside EJB-QL. This results in an ordinary JPA <literal>setParameter()</literal> call on the standard JPA <literal>Query</literal> object.</para> </callout> <callout arearefs="registration-log"> <para> The <literal>Log</literal> API allows easily display templated log messages that can include JSF EL expressions. </para> </callout> <callout arearefs="registration-outcome"> <para>JSF action listene!
r methods return a string-valued outcome that determines the next page displayed. A null outcome (or a void action listener method) redisplays the previous page. In plain JSF, it is normal to always use a JSF <emphasis>navigation rule</emphasis> to determine the JSF view ID from the outcome. For complex applications, this redirection is good practice. However, for very simple examples like this one, Seam lets you use the JSF view ID as the outcome, eliminating the need for a navigation rule. </para> <note><para>When a view ID is used as an outcome, Seam always performs a browser redirect. </para></note> </callout> <callout arearefs="registration-builtin"> <para> Seam provides a number of <emphasis>built-in components</emphasis> to help solve common problems. The <literal>FacesMessages</literal> component makes it easy to display templated error or success messages. (As of Seam 2.1, you can use <literal>StatusMessages</literal> instead, to remove the semantic dependency on J!
SF.) Built-in Seam components may be obtained by injection, or!
by call
ing the <literal>instance()</literal> method on the class of the built-in component. </para> </callout> </calloutlist> </programlistingco> </example> -->
+ <!-- <example>
+ <title>RegisterAction.java</title> -->
+ <formalpara><title>RegisterAction.java Example</title>
+ <para>
+
+
+<programlisting><![CDATA[@Stateless
@Name("register")
-public class RegisterAction implements Register
-{
- @In
- private User user;
-
- @PersistenceContext
- private EntityManager em;
-
- @Logger
- private Log log;
-
- public String register()
- {
- List existing = em.createQuery(
- "select username from User where username = #{user.username}")
- .getResultList();
-
- if (existing.size()==0)
- {
- em.persist(user);
- log.info("Registered new user #{user.username}");
- return "/registered.xhtml";
- }
- else
- {
- FacesMessages.instance().add("User #{user.username} already exists");
- return null;
- }
- }
+public class RegisterAction implements Register {
+ @In
+ private User user;
+
+ @PersistenceContext
+ private EntityManager em;
+
+ @Logger
+ private Log log;
+
+ public String register() {
+ List existing = em.createQuery(
+ "select username from User where username = #{user.username}")
+ .getResultList();
+
+ if (existing.size()==0) {
+ em.persist(user);
+ log.info("Registered new user #{user.username}");
+ return "/registered.xhtml";
+ } else {
+ FacesMessages.instance().add("User #{user.username} already exists");
+ return null;
+ }
+ }
+}]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <formalpara><title>RegisterAction.java Explanatory Notes</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The EJB <literal>@Stateless</literal> annotation marks this class as a stateless session bean.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <xref linkend="in-annotation" /> <literal>@In</literal> annotation marks an attribute of the bean as injected by Seam. In this case, the attribute is injected from a context variable named <literal>user</literal> (the instance variable name).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The EJB standard <literal>@PersistenceContext</literal> annotation is used to inject the EJB3 entity manager.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Seam <literal>@Logger</literal> annotation is used to inject the component's <literal>Log</literal> instance.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The action listener method uses the standard EJB3 <literal>EntityManager</literal> API to interact with the database, and returns the JSF outcome. Note that, since this is a session bean, a transaction begins automatically when the <literal>register()</literal> method is called, and is committed when it completes.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Notice that Seam lets you use a JSF EL expression inside EJB-QL. This results in an ordinary JPA <literal>setParameter()</literal> call on the standard JPA <literal>Query</literal> object.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>Log</literal> API allows easily display templated log messages that can include JSF EL expressions.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ JSF action listener methods return a string-valued outcome that determines the next page displayed. A null outcome (or a void action listener method) redisplays the previous page. In plain JSF, it is normal to always use a JSF <emphasis>navigation rule</emphasis> to determine the JSF view ID from the outcome. For complex applications, this redirection is good practice. However, for very simple examples like this one, Seam lets you use the JSF view ID as the outcome, eliminating the need for a navigation rule.
+ </para>
+ <note>
+ <para>
+ When a view ID is used as an outcome, Seam always performs a browser redirect.
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ Seam provides a number of <emphasis>built-in components</emphasis> to help solve common problems. The <literal>FacesMessages</literal> component makes it easy to display templated error or success messages. (As of Seam 2.1, you can use <literal>StatusMessages</literal> instead, to remove the semantic dependency on JSF.) Built-in Seam components may be obtained by injection, or by calling the <literal>instance()</literal> method on the class of the built-in component.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ Note that we did not explicitly specify a <literal>@Scope</literal> this time. Each Seam component type has a default scope, which will be used if scope is not explicitly specified. For stateless session beans, the default scope is the stateless context.
+ </para>
+ <para>
+ The session bean action listener performs the business and persistence logic for our mini-application. In a more complex application, a separate service layer might be necessary, but Seam allows you to implement your own strategies for application layering. You can make any application as simple, or as complex, as you want.
+ </para>
+ <note>
+ <para>
+ This application is more complex than necessary for the sake of clear example code. All of the application code could have been eliminated by using Seam's application framework controllers.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>The session bean local interface: <literal>Register.java</literal></title>
+ <para>
+ The session bean requires a local interface.
+ </para>
+ <formalpara><title>Register.java Example</title>
+ <para>
+ <!-- <example>
+ <title>Register.java</title> -->
+
+<programlisting role="JAVA"><![CDATA[@Local
+public interface Register {
+ public String register();
}]]></programlisting>
-
- <calloutlist>
- <callout arearefs="registration-stateless-annotation">
- <para> The EJB <literal>@Stateless</literal> annotation marks this class as
- a stateless session bean. </para>
- </callout>
- <callout arearefs="registration-in-annotation">
- <para> The <link linkend="in-annotation">
- <literal>@In</literal>
- </link> annotation marks an attribute of the bean as injected by Seam. In this case,
- the attribute is injected from a context variable named <literal>user</literal> (the
- instance variable name). </para>
- </callout>
- <callout arearefs="registration-persistencecontext-annotation">
- <para> The EJB standard <literal>@PersistenceContext</literal> annotation is used to
- inject the EJB3 entity manager. </para>
- </callout>
- <callout arearefs="registration-logger-annotation">
- <para> The Seam <literal>@Logger</literal> annotation is used to inject the component's
- <literal>Log</literal> instance. </para>
- </callout>
- <callout arearefs="registration-action-listener">
- <para> The action listener method uses the standard EJB3
- <literal>EntityManager</literal> API to interact with the database, and returns the
- JSF outcome. Note that, since this is a session bean, a transaction is automatically
- begun when the <literal>register()</literal> method is called, and committed when it
- completes. </para>
- </callout>
- <callout arearefs="registration-query">
- <para> Notice that Seam lets you use a JSF EL expression inside EJB-QL. Under the
- covers, this results in an ordinary JPA <literal>setParameter()</literal> call on
- the standard JPA <literal>Query</literal> object. Nice, huh? </para>
- </callout>
- <callout arearefs="registration-log">
- <para> The <literal>Log</literal> API lets us easily display templated log messages which
- can also make use of JSF EL expressions.
- </para>
- </callout>
- <callout arearefs="registration-outcome">
- <para> JSF action listener methods return a string-valued outcome that determines what
- page will be displayed next. A null outcome (or a void action listener method)
- redisplays the previous page. In plain JSF, it is normal to always use a JSF
- <emphasis>navigation rule</emphasis> to determine the JSF view id from the
- outcome. For complex application this indirection is useful and a good practice.
- However, for very simple examples like this one, Seam lets you use the JSF view id
- as the outcome, eliminating the requirement for a navigation rule. <emphasis>Note
- that when you use a view id as an outcome, Seam always performs a browser
- redirect.</emphasis>
- </para>
- </callout>
- <callout arearefs="registration-builtin">
- <para> Seam provides a number of <emphasis>built-in components</emphasis> to help solve
- common problems. The <literal>FacesMessages</literal> component makes it easy to
- display templated error or success messages. (As of Seam 2.1, you can use
- <literal>StatusMessages</literal> instead to remove the semantic dependency on JSF).
- Built-in Seam components may be obtained by injection, or by calling the
- <literal>instance()</literal> method on the class of the built-in component.
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
- <para> Note that we did not explicitly specify a <literal>@Scope</literal> this time. Each Seam
- component type has a default scope if not explicitly specified. For stateless session beans, the
- default scope is the stateless context, which is the only sensible value.</para>
-
- <para> Our session bean action listener performs the business and persistence logic for our
- mini-application. In more complex applications, we might need require a separate service
- layer. This is easy to achieve with Seam, but it's overkill for most web applications.
- Seam does not force you into any particular strategy for application layering, allowing
- your application to be as simple, or as complex, as you want.
- </para>
- <para>Note that in this simple
- application, we've actually made it far more complex than it needs to be. If we had
- used the Seam application framework controllers, we would have eliminated all of our
- application code. However, then we wouldn't have had much of an application to explain.
- </para>
-
- </section>
-
- <section>
- <title>The session bean local interface: <literal>Register.java</literal></title>
-
- <para>Naturally, our session bean needs a local interface.</para>
-
- <example><title>Register.java</title>
- <programlisting role="JAVA"><![CDATA[@Local
-public interface Register
-{
- public String register();
-}]]></programlisting></example>
-
-
- <para> That's the end of the Java code. Now we'll look at the view.</para>
-
- </section>
-
- <section>
- <title>The view: <literal>register.xhtml</literal> and <literal>registered.xhtml</literal></title>
-
- <para> The view pages for a Seam application could be implemented using any technology that supports
- JSF. In this example we use Facelets, because we think it's better than JSP.</para>
-
- <example>
- <title>register.xhtml</title>
- <programlisting role="XHTML"><![CDATA[<?xml version="1.0" encoding="utf-8"?>
+ <!-- </example> -->
+ </para>
+ </formalpara>
+ <para>
+ That's the end of the Java code. The next level to examine is the view.
+ </para>
+ </section>
+
+ <section>
+ <title>The view: <literal>register.xhtml</literal> and <literal>registered.xhtml</literal></title>
+ <para>
+ The view pages for a Seam application can be implemented using any technology that supports JSF. This example was written with Facelets.
+ </para>
+
+ <formalpara><title>Register.xhtml Example</title>
+ <para>
+ <!-- <example>
+ <title>register.xhtml</title> -->
+
+<programlisting role="XHTML"><![CDATA[<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
- xmlns:s="http://jboss.com/products/seam/taglib"
- xmlns:h="http://java.sun.com/jsf/html"
- xmlns:f="http://java.sun.com/jsf/core">
+ xmlns:s="http://jboss.com/products/seam/taglib"
+ xmlns:h="http://java.sun.com/jsf/html"
+ xmlns:f="http://java.sun.com/jsf/core">
- <head>
- <title>Register New User</title>
- </head>
- <body>
- <f:view>
- <h:form>
- <s:validateAll>
- <h:panelGrid columns="2">
- Username: <h:inputText value="#{user.username}" required="true"/>
- Real Name: <h:inputText value="#{user.name}" required="true"/>
- Password: <h:inputSecret value="#{user.password}" required="true"/>
- </h:panelGrid>
- </s:validateAll>
- <h:messages/>
- <h:commandButton value="Register" action="#{register.register}"/>
- </h:form>
- </f:view>
- </body>
+ <head>
+ <title>Register New User</title>
+ </head>
+ <body>
+ <f:view>
+ <h:form>
+ <s:validateAll>
+ <h:panelGrid columns="2">
+ Username: <h:inputText value="#{user.username}"
+ required="true"/>
+ Real Name: <h:inputText value="#{user.name}"
+ required="true"/>
+ Password: <h:inputSecret value="#{user.password}"
+ required="true"/>
+ </h:panelGrid>
+ </s:validateAll>
+ <h:messages/>
+ <h:commandButton value="Register" action="#{register.register}"/>
+ </h:form>
+ </f:view>
+ </body>
-</html>]]></programlisting></example>
-
-
- <para> The only thing here that is specific to Seam is the
- <literal><s:validateAll></literal> tag. This JSF component tells JSF to validate all
- the contained input fields against the Hibernate Validator annotations specified on the entity bean. </para>
-
- <example>
- <title>registered.xhtml</title>
- <programlisting role="XHTML"><![CDATA[<?xml version="1.0" encoding="utf-8"?>
+</html>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ The only Seam-specific tag here is <literal><![CDATA[<s:validateAll>]]></literal>. This JSF component tells JSF to validate all the contained input fields against the Hibernate Validator annotations specified on the entity bean.
+ </para>
+ <formalpara><title>registered.xhtml Example</title>
+ <para>
+ <!-- <example>
+ <title>registered.xhtml</title>-->
+
+<programlisting role="XHTML"><![CDATA[<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
- xmlns:f="http://java.sun.com/jsf/core">
+ xmlns:f="http://java.sun.com/jsf/core">
- <head>
- <title>Successfully Registered New User</title>
- </head>
- <body>
- <f:view>
- Welcome, #{user.name}, you are successfully registered as #{user.username}.
- </f:view>
- </body>
+ <head>
+ <title>Successfully Registered New User</title>
+ </head>
+ <body>
+ <f:view>
+ Welcome, #{user.name}, you are successfully
+ registered as #{user.username}.
+ </f:view>
+ </body>
</html>
-]]></programlisting>
- </example>
-
-
- <para> This is a simple Facelets page using some inline EL. There's nothing specific to Seam here. </para>
-
- </section>
-
- <section>
- <title>The Seam component deployment descriptor: <literal>components.xml</literal></title>
-
- <para>Since this is the first Seam app we've seen, we'll take a look at the deployment
- descriptors. Before we get into them, it is worth noting that Seam strongly values
- minimal configuration. These configuration files will be created for you when you create a Seam
- application. You'll never need to touch most of these files. We're presenting them
- now only to help you understand what all the pieces in the example are doing.
- </para>
-
- <para> If you've used many Java frameworks before, you'll be used to having to declare all your
- component classes in some kind of XML file that gradually grows more and more unmanageable as your
- project matures. You'll be relieved to know that Seam does not require that application components
- be accompanied by XML. Most Seam applications require a very small amount of XML that does not grow
- very much as the project gets bigger. </para>
-
- <para> Nevertheless, it is often useful to be able to provide for <emphasis>some</emphasis> external
- configuration of <emphasis>some</emphasis> components (particularly the components built in to
- Seam). You have a couple of options here, but the most flexible option is to provide this
- configuration in a file called <literal>components.xml</literal>, located in the
- <literal>WEB-INF</literal> directory. We'll use the <literal>components.xml</literal> file to tell
- Seam how to find our EJB components in JNDI: </para>
- <example>
- <title>components.xml</title>
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+]]>
+</programlisting>
+ <!-- </example> -->
+ </para>
+ </formalpara>
+ <para>
+ The above is a simple Facelets page, created with inline EL — it contains nothing specific to Seam.
+ </para>
+ </section>
+
+ <section>
+ <title>The Seam component deployment descriptor: <literal>components.xml</literal></title>
+ <para>
+ Before looking at deployment descriptors, it is worth noting that Seam strongly values minimal configuration. These configuration files will be created for you when you create a Seam application, and there will rarely be any need to alter them. They are presented here solely to assist you in understanding the purpose and function of all of the example code.
+ </para>
+ <para>
+ If you have used Java frameworks previously, you will be used to declaring your component classes in an XML file. You have probably also noticed that as a project matures, these XML files tend to become unmanageable. Fortunately, Seam does not require application components to be accompanied by XML. Most Seam applications require only a small amount of XML, which does not tend to increase in size as projects expand.
+ </para>
+ <para>
+ However, it is often useful to be able to provide for some external configuration of some components, particularly the components that are built into Seam. The most flexible option, here, is to provide this configuration in a file called <literal>components.xml</literal>, located in the <literal>WEB-INF</literal> directory. The <literal>components.xml</literal> file can be used to tell Seam how to find our EJB components in JNDI:
+ </para>
+
+ <!-- <example>
+ <title>components.xml</title> -->
+ <formalpara><title>components.xml Example</title>
+ <para>
+
+<programlisting role="XML"><![CDATA[<?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-2.2.xsd
- http://jboss.com/products/seam/components
- http://jboss.com/products/seam/components-2.2.xsd">
+ 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-2.2.xsd
+ http://jboss.com/products/seam/components
+ http://jboss.com/products/seam/components-2.2.xsd">
- <core:init jndi-pattern="@jndiPattern@"/>
+ <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>. The funny <literal>@</literal> symbols are
- there because our Ant build script puts the correct JNDI pattern in when we deploy the application,
- which it reads from the components.properties file. You learn more about how this process works in
- <xref linkend="xml.descriptor"/>.</para>
-
- </section>
-
- <section>
- <title>The web deployment description: <literal>web.xml</literal></title>
-
- <para> The presentation layer for our mini-application will be deployed in a WAR. So we'll need a web
- deployment descriptor. </para>
- <example>
- <title>web.xml</title>
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+</components>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ The above code configures a property named <literal>jndiPattern</literal>, which belongs to a built-in Seam component named <literal>org.jboss.seam.core.init</literal>. The <literal>@</literal> symbols are used to direct the Ant build script to insert the correct JNDI pattern from the components.properties file when the application is deployed. You will learn more about this process in <xref linkend="xml.descriptor" />.
+ </para>
+ </section>
+
+ <section>
+ <title>The web deployment description: <literal>web.xml</literal></title>
+ <para>
+ The presentation layer for our mini-application will be deployed in a WAR, so a web deployment descriptor is required:
+ </para>
+ <!-- <example>
+ <title>web.xml</title> -->
+ <formalpara><title>web.xml Example</title>
+ <para>
+
+<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<web-app xmlns="http://java.sun.com/xml/ns/javaee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://java.sun.com/xml/ns/javaee
- http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
- version="2.5">
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation=
+ "http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
+ version="2.5">
- <listener>
- <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
- </listener>
+ <listener>
+ <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
+ </listener>
- <context-param>
- <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
- <param-value>.xhtml</param-value>
- </context-param>
+ <context-param>
+ <param-name>javax.faces.DEFAULT_SUFFIX</param-name>
+ <param-value>.xhtml</param-value>
+ </context-param>
- <servlet>
- <servlet-name>Faces Servlet</servlet-name>
- <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
- <load-on-startup>1</load-on-startup>
- </servlet>
+ <servlet>
+ <servlet-name>Faces Servlet</servlet-name>
+ <servlet-class>javax.faces.webapp.FacesServlet</servlet-class>
+ <load-on-startup>1</load-on-startup>
+ </servlet>
- <servlet-mapping>
- <servlet-name>Faces Servlet</servlet-name>
- <url-pattern>*.seam</url-pattern>
- </servlet-mapping>
+ <servlet-mapping>
+ <servlet-name>Faces Servlet</servlet-name>
+ <url-pattern>*.seam</url-pattern>
+ </servlet-mapping>
- <session-config>
- <session-timeout>10</session-timeout>
- </session-config>
+ <session-config>
+ <session-timeout>10</session-timeout>
+ </session-config>
-</web-app>]]></programlisting></example>
-
-
- <para> This <literal>web.xml</literal> file configures Seam and JSF. The configuration you see here is
- pretty much identical in all Seam applications. </para>
-
- </section>
-
- <section>
- <title>The JSF configration: <literal>faces-config.xml</literal></title>
-
- <para> Most Seam applications use JSF views as the presentation layer. So usually we'll need
- <literal>faces-config.xml</literal>. In our case, we are going to use Facelets for
- defining our views, so we need to tell JSF to use Facelets as its templating engine. </para>
-
- <example>
- <title>faces-config.xml</title>
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+</web-app>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ The above <literal>web.xml</literal> file configures both Seam and JSF. The configuration you see here changes very little between Seam applications.
+ </para>
+ </section>
+
+ <section>
+ <title>The JSF configration: <literal>faces-config.xml</literal></title>
+ <para>
+ Most Seam applications use JSF views as the presentation layer, so <literal>faces-config.xml</literal> is usually a requirement. In this case, Facelets is used to define our views, so we need to tell JSF to use Facelets as its templating engine.
+ </para>
+ <!-- <example>
+ <title>faces-config.xml</title> -->
+ <formalpara><title>faces-config.xml Example</title>
+ <para>
+
+<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<faces-config xmlns="http://java.sun.com/xml/ns/javaee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://java.sun.com/xml/ns/javaee
- http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"
- version="1.2">
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation=
+ "http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/web-facesconfig_1_2.xsd"
+ version="1.2">
- <application>
- <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
- </application>
+ <application>
+ <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
+ </application>
-</faces-config>]]></programlisting>
- </example>
-
-
- <para> Note that we don't need
- any JSF managed bean declarations! Our managed beans are annotated Seam components. In Seam applications,
- the <literal>faces-config.xml</literal> is used much less often than in plain JSF. Here, we are simply
- using it to enable Facelets as the view handler instead of JSP.</para>
-
- <para> In fact, once you have all the basic descriptors set up, the <emphasis>only</emphasis> XML you
- need to write as you add new functionality to a Seam application is orchestration: navigation rules
- or jBPM process definitions. Seam's stand is that <emphasis>process flow</emphasis> and
- <emphasis>configuration data</emphasis> are the only things that truly belong in XML. </para>
-
- <para> In this simple example, we don't even need a navigation rule, since we decided to embed the view
- id in our action code. </para>
-
- </section>
-
- <section>
- <title>The EJB deployment descriptor: <literal>ejb-jar.xml</literal></title>
-
- <para> The <literal>ejb-jar.xml</literal> file integrates Seam with EJB3, by attaching the
- <literal>SeamInterceptor</literal> to all session beans in the archive. </para>
-
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+</faces-config>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ Note that JSF managed bean declarations are unnecessary because the managed beans are annotated Seam components. In Seam applications, <literal>faces-config.xml</literal> is used much less often than in plain JSF. Here, we use it simply to enable Facelets (and not JSP) as the view handler.
+ </para>
+ <para>
+ Once you have set up all the basic descriptors, the only XML you need write to add functionality to a Seam application will be for orchestration: navigation rules or jBPM process definitions. Seam operates on the principle that <emphasis>process flow</emphasis> and <emphasis>configuration data</emphasis> are all that truly belongs in XML.
+ </para>
+ <para>
+ The above example does not require a navigation rule, since the view ID was embedded in our action code.
+ </para>
+ </section>
+
+ <section>
+ <title>The EJB deployment descriptor: <literal>ejb-jar.xml</literal></title>
+ <para>
+ The <filename>ejb-jar.xml</filename> file integrates Seam with EJB3 by attaching the <literal>SeamInterceptor</literal> to all session beans in the archive.
+ </para>
+
+<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<ejb-jar xmlns="http://java.sun.com/xml/ns/javaee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://java.sun.com/xml/ns/javaee
- http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
- version="3.0">
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation=
+ "http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/ejb-jar_3_0.xsd"
+ version="3.0">
- <interceptors>
- <interceptor>
- <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
- </interceptor>
- </interceptors>
+ <interceptors>
+ <interceptor>
+ <interceptor-class>
+ org.jboss.seam.ejb.SeamInterceptor
+ </interceptor-class>
+ </interceptor>
+ </interceptors>
- <assembly-descriptor>
- <interceptor-binding>
- <ejb-name>*</ejb-name>
- <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
- </interceptor-binding>
- </assembly-descriptor>
+ <assembly-descriptor>
+ <interceptor-binding>
+ <ejb-name>*</ejb-name>
+ <interceptor-class>
+ org.jboss.seam.ejb.SeamInterceptor
+ </interceptor-class>
+ </interceptor-binding>
+ </assembly-descriptor>
-</ejb-jar>]]></programlisting>
-
- </section>
-
- <section>
- <title>The EJB persistence deployment descriptor: <literal>persistence.xml</literal></title>
-
- <para> The <literal>persistence.xml</literal> file tells the EJB persistence provider where to find the
- datasource, and contains some vendor-specific settings. In this case, enables automatic schema
- export at startup time. </para>
-
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+</ejb-jar>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>The EJB persistence deployment descriptor: <literal>persistence.xml</literal></title>
+ <para>
+ The <literal>persistence.xml</literal> file directs the EJB persistence provider to the appropriate datasource, and contains some vendor-specific settings. In this case, it enables automatic schema export at startup time.
+ </para>
+
+<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://java.sun.com/xml/ns/persistence
- http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
- version="1.0">
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation=
+ "http://java.sun.com/xml/ns/persistence
+ http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
+ version="1.0">
- <persistence-unit name="userDatabase">
- <provider>org.hibernate.ejb.HibernatePersistence</provider>
- <jta-data-source>java:/DefaultDS</jta-data-source>
- <properties>
- <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
- </properties>
- </persistence-unit>
+ <persistence-unit name="userDatabase">
+ <provider>org.hibernate.ejb.HibernatePersistence</provider>
+ <jta-data-source>java:/DefaultDS</jta-data-source>
+ <properties>
+ <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
+ </properties>
+ </persistence-unit>
-</persistence>]]></programlisting>
-
- </section>
-
- <section>
- <title>The EAR deployment descriptor: <literal>application.xml</literal></title>
-
- <para> Finally, since our application is deployed as an EAR, we need a deployment descriptor there, too. </para>
-
- <example id="registration-application-xml"><title>registration application</title>
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+</persistence>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>The EAR deployment descriptor: <literal>application.xml</literal></title>
+ <para>
+ Finally, since our application is deployed as an EAR, we also require a deployment descriptor.
+ </para>
+ <!--
+ <example id="registration-application-xml">
+ <title>registration application</title> -->
+ <formalpara><title>registration application Example</title>
+ <para>
+
+<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<application xmlns="http://java.sun.com/xml/ns/javaee"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="
- http://java.sun.com/xml/ns/javaee
- http://java.sun.com/xml/ns/javaee/application_5.xsd"
- version="5">
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation=
+ "http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/application_5.xsd"
+ version="5">
- <display-name>Seam Registration</display-name>
+ <display-name>Seam Registration</display-name>
- <module>
- <web>
- <web-uri>jboss-seam-registration.war</web-uri>
- <context-root>/seam-registration</context-root>
- </web>
- </module>
- <module>
- <ejb>jboss-seam-registration.jar</ejb>
- </module>
- <module>
- <ejb>jboss-seam.jar</ejb>
- </module>
- <module>
- <java>jboss-el.jar</java>
- </module>
+ <module>
+ <web>
+ <web-uri>jboss-seam-registration.war</web-uri>
+ <context-root>/seam-registration</context-root>
+ </web>
+ </module>
+ <module>
+ <ejb>jboss-seam-registration.jar</ejb>
+ </module>
+ <module>
+ <ejb>jboss-seam.jar</ejb>
+ </module>
+ <module>
+ <java>jboss-el.jar</java>
+ </module>
-</application>]]></programlisting>
- </example>
-
- <para> This deployment descriptor links modules in the enterprise archive and binds the web application
- to the context root <literal>/seam-registration</literal>. </para>
-
- <para> We've now seen <emphasis>all</emphasis> the files in the entire application! </para>
-
- </section>
-</section>
-
- <section>
- <title>How it works</title>
-
- <para> When the form is submitted, JSF asks Seam to resolve the variable named <literal>user</literal>.
- Since there is no value already bound to that name (in any Seam context), Seam instantiates the
- <literal>user</literal> component, and returns the resulting <literal>User</literal> entity bean
- instance to JSF after storing it in the Seam session context. </para>
- <para> The form input values are now validated against the Hibernate Validator constraints specified on the
- <literal>User</literal> entity. If the constraints are violated, JSF redisplays the page. Otherwise,
- JSF binds the form input values to properties of the <literal>User</literal> entity bean. </para>
- <para> Next, JSF asks Seam to resolve the variable named <literal>register</literal>. Seam uses the JNDI
- pattern mentioned earlier to locate the stateless session bean, wraps it as a Seam component, and
- returns it. Seam then presents this component to JSF and JSF invokes the <literal>register()</literal>
- action listener method.</para>
- <para> But Seam is not done yet. Seam intercepts the method call and injects the <literal>User</literal>
- entity from the Seam session context, before allowing the invocation to continue. </para>
- <para> The <literal>register()</literal> method checks if a user with the entered username already exists.
- If so, an error message is queued with the <literal>FacesMessages</literal> component, and a null
- outcome is returned, causing a page redisplay. The <literal>FacesMessages</literal> component
- interpolates the JSF expression embedded in the message string and adds a JSF
- <literal>FacesMessage</literal> to the view. </para>
- <para> If no user with that username exists, the <literal>"/registered.xhtml"</literal> outcome triggers a
- browser redirect to the <literal>registered.xhtml</literal> page. When JSF comes to render the page, it
- asks Seam to resolve the variable named <literal>user</literal> and uses property values of the returned
- <literal>User</literal> entity from Seam's session scope. </para>
-
- </section>
-
- </section>
-
- <section id="messages">
- <title>Clickable lists in Seam: the messages example</title>
-
- <para> Clickable lists of database search results are such an important part of any online application that Seam
- provides special functionality on top of JSF to make it easier to query data using EJB-QL or HQL and display
- it as a clickable list using a JSF <literal><h:dataTable></literal>. The messages example
- demonstrates this functionality. </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/messages.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/messages.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <section>
- <title>Understanding the code</title>
- <para> The message list example has one entity bean, <literal>Message</literal>, one session bean,
- <literal>MessageListBean</literal> and one JSP. </para>
-
- <section>
- <title>The entity bean: <literal>Message.java</literal></title>
-
- <para> The <literal>Message</literal> entity defines the title, text, date and time of a message, and a
- flag indicating whether the message has been read: </para>
-
- <example>
- <title>Message.java</title>
- <programlisting role="JAVA"><![CDATA[@Entity
+</application>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ This deployment descriptor links modules in the enterprise archive and binds the web application to the context root <literal>/seam-registration</literal>.
+ </para>
+ <para>
+ You have now seen all of the files in the application.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>How it works</title>
+ <para>
+ When the form is submitted, JSF asks Seam to resolve the variable named <literal>user</literal>. Since no value is yet bound to that name (in any Seam context), Seam instantiates the <literal>user</literal> component, and returns the resulting <literal>User</literal> entity bean instance to JSF after storing it in the Seam session context.
+ </para>
+ <para>
+ The form input values are now validated against the Hibernate Validator constraints specified on the <literal>User</literal> entity. If the constraints are violated, JSF redisplays the page. Otherwise, JSF binds the form input values to properties of the <literal>User</literal> entity bean.
+ </para>
+ <para>
+ Next, JSF asks Seam to resolve the variable named <literal>register</literal>. Seam uses the JNDI pattern mentioned earlier to locate the stateless session bean, wraps it as a Seam component, and returns it. Seam then presents this component to JSF and JSF invokes the <literal>register()</literal> action listener method.
+ </para>
+ <para>
+ Seam then intercepts the method call and injects the <literal>User</literal> entity from the Seam session context, before allowing the invocation to continue.
+ </para>
+ <para>
+ The <literal>register()</literal> method checks if a user with the entered username already exists. If so, an error message is queued with the <literal>FacesMessages</literal> component, and a null outcome is returned, causing a page redisplay. The <literal>FacesMessages</literal> component interpolates the JSF expression embedded in the message string and adds a JSF <literal>FacesMessage</literal> to the view.
+ </para>
+ <para>
+ If no user with that username exists, the <literal>"/registered.xhtml"</literal> outcome triggers a browser redirect to the <literal>registered.xhtml</literal> page. When JSF comes to render the page, it asks Seam to resolve the variable named <literal>user</literal> and uses property values of the returned <literal>User</literal> entity from Seam's session scope.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="messages">
+ <title>Clickable lists in Seam: the messages example</title>
+ <para>
+ Clickable lists of database search results are a vital part of any online application. Seam provides special functionality on top of JSF to make it easier to query data with EJB-QL or HQL, and display it as a clickable list using a JSF <literal><![CDATA[<h:dataTable>]]></literal>. The messages example demonstrates this functionality.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/messages.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/messages.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <section>
+ <title>Understanding the code</title>
+ <para>
+ The message list example has one entity bean (<literal>Message</literal>), one session bean (<literal>MessageListBean</literal>), and one JSP.
+ </para>
+ <section>
+ <title>The entity bean: <literal>Message.java</literal></title>
+ <para>
+ The <literal>Message</literal> entity defines the title, text, date and time of a message, and a flag indicating whether the message has been read:
+ </para>
+ <!-- <example>
+ <title>Message.java</title> -->
+ <formalpara><title>Message.java Example</title>
+ <para>
+
+<programlisting role="JAVA"><![CDATA[@Entity
@Name("message")
@Scope(EVENT)
-public class Message implements Serializable
-{
- private Long id;
- private String title;
- private String text;
- private boolean read;
- private Date datetime;
-
- @Id @GeneratedValue
- public Long getId()
- {
- return id;
- }
- public void setId(Long id)
- {
- this.id = id;
- }
-
- @NotNull @Length(max=100)
- public String getTitle()
- {
- return title;
- }
- public void setTitle(String title)
- {
- this.title = title;
- }
-
- @NotNull @Lob
- public String getText()
- {
- return text;
- }
- public void setText(String text)
- {
- this.text = text;
- }
-
- @NotNull
- public boolean isRead()
- {
- return read;
- }
- public void setRead(boolean read)
- {
- this.read = read;
- }
-
- @NotNull
- @Basic @Temporal(TemporalType.TIMESTAMP)
- public Date getDatetime()
- {
- return datetime;
- }
- public void setDatetime(Date datetime)
- {
- this.datetime = datetime;
- }
-
-}]]></programlisting>
- </example>
-
- </section>
-
- <section>
- <title>The stateful session bean: <literal>MessageManagerBean.java</literal></title>
-
- <para> Just like in the previous example, we have a session bean, <literal>MessageManagerBean</literal>,
- which defines the action listener methods for the two buttons on our form. One of the buttons
- selects a message from the list, and displays that message. The other button deletes a message. So
- far, this is not so different to the previous example. </para>
-
- <para> But <literal>MessageManagerBean</literal> is also responsible for fetching the list of messages
- the first time we navigate to the message list page. There are various ways the user could navigate
- to the page, and not all of them are preceded by a JSF action — the user might have
- bookmarked the page, for example. So the job of fetching the message list takes place in a Seam
- <emphasis>factory method</emphasis>, instead of in an action listener method. </para>
-
- <para> We want to cache the list of messages in memory between server requests, so we will make this a
- stateful session bean. </para>
- <!-- Can't use code hightlighting with callouts -->
- <example>
- <title>MessageManagerBean.java</title>
- <programlistingco>
- <areaspec>
- <area id="messages-datamodel" coords="7"/>
- <area id="messages-datamodelselection" coords="10"/>
- <area id="messages-out" coords="11"/>
- <area id="messages-persistencecontext" coords="14"/>
- <area id="messages-factory" coords="17"/>
- <area id="messages-select" coords="24"/>
- <area id="messages-delete" coords="29"/>
- <area id="messages-remove" coords="36"/>
- </areaspec>
- <programlisting><![CDATA[@Stateful
+public class Message implements Serializable {
+ private Long id;
+ private String title;
+ private String text;
+ private boolean read;
+ private Date datetime;
+
+ @Id @GeneratedValue
+ public Long getId() {
+ return id;
+ }
+ public void setId(Long id) {
+ this.id = id;
+ }
+
+ @NotNull @Length(max=100)
+ public String getTitle() {
+ return title;
+ }
+ public void setTitle(String title) {
+ this.title = title;
+ }
+
+ @NotNull @Lob
+ public String getText() {
+ return text;
+ }
+ public void setText(String text) {
+ this.text = text;
+ }
+
+ @NotNull
+ public boolean isRead() {
+ return read;
+ }
+ public void setRead(boolean read) {
+ this.read = read;
+ }
+
+ @NotNull
+ @Basic @Temporal(TemporalType.TIMESTAMP)
+ public Date getDatetime() {
+ return datetime;
+ }
+ public void setDatetime(Date datetime) {
+ this.datetime = datetime;
+ }
+}]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ </section>
+
+ <section>
+ <title>The stateful session bean: <literal>MessageManagerBean.java</literal></title>
+ <para>
+ As in the previous example, this example contains a session bean (<literal>MessageManagerBean</literal>) which defines the action listener methods for both of the buttons on our form. As in the previous example, one of the buttons selects a message from the list and displays that message; the other button deletes a message.
+ </para>
+ <para>
+ However, <literal>MessageManagerBean</literal> is also responsible for fetching the list of messages the first time we navigate to the message list page. There are various ways for users to navigate to the page, not all of which are preceded by a JSF action. (Navigating to the page from your favourites will not necessarily call the JSF action, for example.) Therefore, fetching the message list must take place in a Seam <emphasis>factory method</emphasis>, instead of in an action listener method.
+ </para>
+ <para>
+ We want to cache the list of messages in memory between server requests, so we will make this a stateful session bean.
+ </para>
+ <!-- Can't use code hightlighting with callouts --> <!-- <example> <title>MessageManagerBean.java</title> <programlistingco> <areaspec> <area id="messages-datamodel" coords="7"/> <area id="messages-datamodelselection" coords="10"/> <area id="messages-out" coords="11"/> <area id="messages-persistencecontext" coords="14"/> <area id="messages-factory" coords="17"/> <area id="messages-select" coords="24"/> <area id="messages-delete" coords="29"/> <area id="messages-remove" coords="36"/> </areaspec> <programlisting><![CDATA[@Stateful @Scope(SESSION) @Name("messageManager") public class MessageManagerBean implements Serializable, MessageManager { @DataModel private List<Message> messageList; @DataModelSelection @Out(required=false) private Message message; @PersistenceContext(type=EXTENDED) private EntityManager em; @Factory("messageList") public void findMessages() { messageList = em.createQuery("select msg from Message msg order by msg.datetime desc") .getResultList(); }!
public void select() { message.setRead(true); } public void delete() { messageList.remove(message); em.remove(message); message=null; } @Remove public void destroy() {} }]]></programlisting> <calloutlist> <callout arearefs="messages-datamodel"> <para> The <literal>@DataModel</literal> annotation exposes an attibute of type <literal>java.util.List</literal> to the JSF page as an instance of <literal>javax.faces.model.DataModel</literal>. This allows us to use the list in a JSF <literal><![CDATA[<h:dataTable>]]></literal> with clickable links for each row. In this case, the <literal>DataModel</literal> is made available in a session context variable named <literal>messageList</literal>. </para> </callout> <callout arearefs="messages-datamodelselection"> <para> The <literal>@DataModelSelection</literal> annotation tells Seam to inject the <literal>List</literal> element corresponding to the clicked link. </para> </callout> <callout arearefs="messages-out"> <para> The <literal!
>@Out</literal> annotation then exposes the selected value dir!
ectly to
the page. Every time a row of the clickable list is selected, the <literal>Message</literal> is injected to the attribute of the stateful bean, and subsequently "outjected" to the event context variable named <literal>message</literal>. </para> </callout> <callout arearefs="messages-persistencecontext"> <para> This stateful bean has an EJB3 <emphasis>extended persistence context</emphasis>. This means that messages retrieved in the query remain in the managed state for as long as the bean exists. Any subsequent method calls to the stateful bean can therefore update the messages without needing to make an explicit call to the <literal>EntityManager</literal>. </para> </callout> <callout arearefs="messages-factory"> <para> The first time we navigate to the JSP page, the <literal>messageList</literal> context variable does not hold a value. The <literal>@Factory</literal> annotation tells Seam to create an instance of <literal>MessageManagerBean</literal> and invoke <literal>f!
indMessages()</literal> — a factory method for messages — to initialize the value.</para> </callout> <callout arearefs="messages-select"> <para> The <literal>select()</literal> action listener method marks the selected <literal>Message</literal> as read, and updates it in the database. </para> </callout> <callout arearefs="messages-delete"> <para> The <literal>delete()</literal> action listener method removes the selected <literal>Message</literal> from the database. </para> </callout> <callout arearefs="messages-remove"> <para> All stateful session bean Seam components <emphasis>must</emphasis> have a method <literal>@Remove</literal> defined, with no parameters marked. Seam uses this to remove the stateful bean and clean up any server-side state when the Seam context ends. </para> </callout> </calloutlist> </programlistingco> </example> --> <!-- <example>
+ <title>MessageManagerBean.java</title> -->
+ <formalpara><title>MessageManagerBean.java Example</title>
+ <para>
+
+<programlisting><![CDATA[@Stateful
@Scope(SESSION)
@Name("messageManager")
-public class MessageManagerBean implements Serializable, MessageManager
-{
- @DataModel
- private List<Message> messageList;
-
- @DataModelSelection
- @Out(required=false)
- private Message message;
-
- @PersistenceContext(type=EXTENDED)
- private EntityManager em;
-
- @Factory("messageList")
- public void findMessages()
- {
- messageList = em.createQuery("select msg from Message msg order by msg.datetime desc")
- .getResultList();
- }
-
- public void select()
- {
- message.setRead(true);
- }
-
- public void delete()
- {
- messageList.remove(message);
- em.remove(message);
- message=null;
- }
-
- @Remove
- public void destroy() {}
+public class MessageManagerBean implements Serializable, MessageManager {
+ @DataModel
+ private List<Message> messageList;
+
+ @DataModelSelection
+ @Out(required=false)
+ private Message message;
+
+ @PersistenceContext(type=EXTENDED)
+ private EntityManager em;
+
+ @Factory("messageList")
+ public void findMessages() {
+ messageList = em.createQuery("select msg from Message msg " +
+ "order by msg.datetime desc")
+ .getResultList();
+ }
+
+ public void select() {
+ message.setRead(true);
+ }
+
+ public void delete() {
+ messageList.remove(message);
+ em.remove(message);
+ message=null;
+ }
+
+ @Remove
+ public void destroy() {}
-}]]></programlisting>
- <calloutlist>
- <callout arearefs="messages-datamodel">
- <para> The <literal>@DataModel</literal> annotation exposes an attibute of type
- <literal>java.util.List</literal> to the JSF page as an instance of
- <literal>javax.faces.model.DataModel</literal>. This allows us to use the list
- in a JSF <literal><h:dataTable></literal> with clickable links for
- each row. In this case, the <literal>DataModel</literal> is made available in a
- session context variable named <literal>messageList</literal>. </para>
- </callout>
- <callout arearefs="messages-datamodelselection">
- <para> The <literal>@DataModelSelection</literal> annotation tells Seam to inject the
- <literal>List</literal> element that corresponded to the clicked link. </para>
- </callout>
- <callout arearefs="messages-out">
- <para> The <literal>@Out</literal> annotation then exposes the selected value directly
- to the page. So every time a row of the clickable list is selected, the
- <literal>Message</literal> is injected to the attribute of the stateful bean,
- and the subsequently <emphasis>outjected</emphasis> to the event context variable
- named <literal>message</literal>. </para>
- </callout>
- <callout arearefs="messages-persistencecontext">
- <para> This stateful bean has an EJB3 <emphasis>extended persistence context</emphasis>.
- The messages retrieved in the query remain in the managed state as long as the bean
- exists, so any subsequent method calls to the stateful bean can update them without
- needing to make any explicit call to the <literal>EntityManager</literal>. </para>
- </callout>
- <callout arearefs="messages-factory">
- <para> The first time we navigate to the JSP page, there will be no value in the
- <literal>messageList</literal> context variable. The <literal>@Factory</literal>
- annotation tells Seam to create an instance of <literal>MessageManagerBean</literal>
- and invoke the <literal>findMessages()</literal> method to initialize the value. We
- call <literal>findMessages()</literal> a <emphasis>factory method</emphasis> for
- <literal>messages</literal>. </para>
- </callout>
- <callout arearefs="messages-select">
- <para> The <literal>select()</literal> action listener method marks the selected
- <literal>Message</literal> as read, and updates it in the database. </para>
- </callout>
- <callout arearefs="messages-delete">
- <para> The <literal>delete()</literal> action listener method removes the selected
- <literal>Message</literal> from the database. </para>
- </callout>
- <callout arearefs="messages-remove">
- <para> All stateful session bean Seam components <emphasis>must</emphasis> have a method
- with no parameters marked <literal>@Remove</literal> that Seam uses to remove
- the stateful bean when the Seam context ends, and clean up any server-side state.
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
- <para> Note that this is a session-scoped Seam component. It is associated with the user login session,
- and all requests from a login session share the same instance of the component. (In Seam
- applications, we usually use session-scoped components sparingly.) </para>
-
- </section>
-
- <section>
- <title>The session bean local interface: <literal>MessageManager.java</literal></title>
-
- <para> All session beans have a business interface, of course. </para>
- <example>
- <title>MessageManager.java</title>
-
- <programlisting role="JAVA"><![CDATA[@Local
-public interface MessageManager
-{
- public void findMessages();
- public void select();
- public void delete();
- public void destroy();
-}]]></programlisting></example>
-
- <para> From now on, we won't show local interfaces in our code examples. </para>
-
- <para> Let's skip over <literal>components.xml</literal>, <literal>persistence.xml</literal>,
- <literal>web.xml</literal>, <literal>ejb-jar.xml</literal>, <literal>faces-config.xml</literal>
- and <literal>application.xml</literal> since they are much the same as the previous example, and go
- straight to the JSP. </para>
-
- </section>
-
- <section>
- <title>The view: <literal>messages.jsp</literal></title>
-
- <para> The JSP page is a straightforward use of the JSF <literal><h:dataTable></literal>
- component. Again, nothing specific to Seam. </para>
- <example>
- <title>messages.jsp</title>
- <programlisting role="XHTML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
+}]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <formalpara><title>MessageManagerBean.java Explanatory Notes</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The <literal>@DataModel</literal> annotation exposes an attibute of type <literal>java.util.List</literal> to the JSF page as an instance of <literal>javax.faces.model.DataModel</literal>. This allows us to use the list in a JSF <literal><![CDATA[<h:dataTable>]]></literal> with clickable links for each row. In this case, the <literal>DataModel</literal> is made available in a session context variable named <literal>messageList</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>@DataModelSelection</literal> annotation tells Seam to inject the <literal>List</literal> element corresponding to the clicked link.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>@Out</literal> annotation then exposes the selected value directly to the page. Every time a row of the clickable list is selected, the <literal>Message</literal> is injected to the attribute of the stateful bean, and subsequently "outjected" to the event context variable named <literal>message</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ This stateful bean has an EJB3 <emphasis>extended persistence context</emphasis>. This means that messages retrieved in the query remain in the managed state for as long as the bean exists. Any subsequent method calls to the stateful bean can therefore update the messages without needing to make an explicit call to the <literal>EntityManager</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The first time we navigate to the JSP page, the <literal>messageList</literal> context variable does not hold a value. The <literal>@Factory</literal> annotation tells Seam to create an instance of <literal>MessageManagerBean</literal> and invoke <literal>findMessages()</literal> — a factory method for messages — to initialize the value.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>select()</literal> action listener method marks the selected <literal>Message</literal> as read, and updates it in the database.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>delete()</literal> action listener method removes the selected <literal>Message</literal> from the database.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ All stateful session bean Seam components <emphasis>must</emphasis> have a method <literal>@Remove</literal> defined, with no parameters marked. Seam uses this to remove the stateful bean and clean up any server-side state when the Seam context ends.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <note>
+ <para>
+ This is a session-scoped Seam component. It is associated with the user login session, and all requests from a login session share the same instance of the component. Session-scoped components are usually used sparingly in Seam applications.
+ </para>
+ </note>
+ </section>
+
+ <section>
+ <title>The session bean local interface: <literal>MessageManager.java</literal></title>
+ <para>
+ All session beans have a business interface:
+ </para>
+ <!-- <example>
+ <title>MessageManager.java</title> -->
+ <formalpara><title>MessageManager.java Example</title>
+ <para>
+
+<programlisting role="JAVA"><![CDATA[@Local
+public interface MessageManager {
+ public void findMessages();
+ public void select();
+ public void delete();
+ public void destroy();
+}]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ From this point, local interfaces are no longer shown in these code examples. <filename>Components.xml</filename>, <filename>persistence.xml</filename>, <filename>web.xml</filename>, <filename>ejb-jar.xml</filename>, <filename>faces-config.xml</filename> and <filename>application.xml</filename> operate in a similar fashion to the previous example, and go directly to the JSP.
+ </para>
+ </section>
+
+ <section>
+ <title>The view: <literal>messages.jsp</literal></title>
+ <para>
+ The JSP page is a straightforward use of the JSF <literal><![CDATA[<h:dataTable>]]></literal> component. Once again, these functions are not Seam-specific.
+ </para>
+ <!-- <example>
+ <title>messages.jsp</title> -->
+ <formalpara><title>messages.jsp Example</title>
+ <para>
+<programlisting role="XHTML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<html>
- <head>
- <title>Messages</title>
- </head>
- <body>
- <f:view>
- <h:form>
- <h2>Message List</h2>
- <h:outputText value="No messages to display"
- rendered="#{messageList.rowCount==0}"/>
- <h:dataTable var="msg" value="#{messageList}"
- rendered="#{messageList.rowCount>0}">
- <h:column>
- <f:facet name="header">
+ <head>
+ <title>Messages</title>
+ </head>
+ <body>
+ <f:view>
+ <h:form>
+ <h2>Message List</h2>
+ <h:outputText value="No messages to display"
+ rendered="#{messageList.rowCount==0}"/>
+ <h:dataTable var="msg" value="#{messageList}"
+ rendered="#{messageList.rowCount>0}">
+ <h:column>
+ <f:facet name="header">
<h:outputText value="Read"/>
- </f:facet>
- <h:selectBooleanCheckbox value="#{msg.read}" disabled="true"/>
- </h:column>
- <h:column>
- <f:facet name="header">
+ </f:facet>
+ <h:selectBooleanCheckbox value="#{msg.read}" disabled="true"/>
+ </h:column>
+ <h:column>
+ <f:facet name="header">
<h:outputText value="Title"/>
- </f:facet>
- <h:commandLink value="#{msg.title}" action="#{messageManager.select}"/>
- </h:column>
- <h:column>
- <f:facet name="header">
+ </f:facet>
+ <h:commandLink value="#{msg.title}"
+ action="#{messageManager.select}"/>
+ </h:column>
+ <h:column>
+ <f:facet name="header">
<h:outputText value="Date/Time"/>
- </f:facet>
- <h:outputText value="#{msg.datetime}">
- <f:convertDateTime type="both" dateStyle="medium" timeStyle="short"/>
- </h:outputText>
- </h:column>
- <h:column>
- <h:commandButton value="Delete" action="#{messageManager.delete}"/>
- </h:column>
- </h:dataTable>
- <h3><h:outputText value="#{message.title}"/></h3>
- <div><h:outputText value="#{message.text}"/></div>
- </h:form>
- </f:view>
- </body>
-</html>]]></programlisting>
- </example>
-
-
- </section>
-
- </section>
-
- <section>
- <title>How it works</title>
-
- <para> The first time we navigate to the <literal>messages.jsp</literal> page, the page will try to resolve the
- <literal>messageList</literal> context variable. Since this context variable is not initialized,
- Seam will call the factory method <literal>findMessages()</literal>, which performs a query against the
- database and results in a <literal>DataModel</literal> being outjected. This
- <literal>DataModel</literal> provides the row data needed for rendering the
- <literal><h:dataTable></literal>. </para>
-
- <para> When the user clicks the <literal><h:commandLink></literal>, JSF calls the
- <literal>select()</literal> action listener. Seam intercepts this call and injects the selected row
- data into the <literal>message</literal> attribute of the <literal>messageManager</literal> component.
- The action listener fires, marking the selected <literal>Message</literal> as read. At the end of the
- call, Seam outjects the selected <literal>Message</literal> to the context variable named
- <literal>message</literal>. Next, the EJB container commits the transaction, and the change to the
- <literal>Message</literal> is flushed to the database. Finally, the page is re-rendered,
- redisplaying the message list, and displaying the selected message below it. </para>
-
- <para> If the user clicks the <literal><h:commandButton></literal>, JSF calls the
- <literal>delete()</literal> action listener. Seam intercepts this call and injects the selected row
- data into the <literal>message</literal> attribute of the <literal>messageList</literal> component. The
- action listener fires, removing the selected <literal>Message</literal> from the list, and also calling
- <literal>remove()</literal> on the <literal>EntityManager</literal>. At the end of the call, Seam
- refreshes the <literal>messageList</literal> context variable and clears the context variable named
- <literal>message</literal>. The EJB container commits the transaction, and deletes the
- <literal>Message</literal> from the database. Finally, the page is re-rendered, redisplaying the
- message list. </para>
-
- </section>
-
- </section>
-
- <section id="todo">
- <title>Seam and jBPM: the todo list example</title>
-
- <para> jBPM provides sophisticated functionality for workflow and task management. To get a small taste of how
- jBPM integrates with Seam, we'll show you a simple "todo list" application. Since managing lists of tasks is
- such core functionality for jBPM, there is hardly any Java code at all in this example. </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/todo.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/todo.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <section>
- <title>Understanding the code</title>
- <para> The center of this example is the jBPM process definition. There are also two JSPs and two trivial
- JavaBeans (There was no reason to use session beans, since they do not access the database, or have any
- other transactional behavior). Let's start with the process definition: </para>
- <!-- Can't use code hightlighting with callouts -->
- <example>
- <title>todo.jpdl.xml</title>
- <programlistingco>
- <areaspec>
- <area id="todo-startstate" coords="3"/>
- <area id="todo-tasknode" coords="7"/>
- <area id="todo-task" coords="8"/>
- <area id="todo-assignment" coords="9"/>
- <area id="todo-endstate" coords="14"/>
- </areaspec>
- <programlisting><![CDATA[<process-definition name="todo">
+ </f:facet>
+ <h:outputText value="#{msg.datetime}">
+ <f:convertDateTime type="both" dateStyle="medium"
+ timeStyle="short"/>
+ </h:outputText>
+ </h:column>
+ <h:column>
+ <h:commandButton value="Delete"
+ action="#{messageManager.delete}"/>
+ </h:column>
+ </h:dataTable>
+ <h3><h:outputText value="#{message.title}"/></h3>
+ <div><h:outputText value="#{message.text}"/></div>
+ </h:form>
+ </f:view>
+ </body>
+</html>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ </section>
+
+ </section>
+
+ <section>
+ <title>How it works</title>
+ <para>
+ The first time we navigate to <literal>messages.jsp</literal>, the page will try to resolve the <literal>messageList</literal> context variable. Since this variable is not yet initialized, Seam calls the factory method <literal>findMessages</literal>, which queries the database and retrieves a <literal>DataModel</literal>. This provides the row data required to render the <literal><![CDATA[<h:dataTable>]]></literal>.
+ </para>
+ <para>
+ When the user clicks the <literal><![CDATA[<h:commandLink>]]></literal>, JSF calls the <literal>select()</literal> action listener. Seam intercepts this call and injects the selected row data into the <literal>message</literal> attribute of the <literal>messageManager</literal> component. The action listener fires, marking the selected <literal>Message</literal> as read. At the end of the call, Seam outjects the selected <literal>Message</literal> to the <literal>message</literal> context variable. Next, the EJB container commits the transaction, and the change to the <literal>Message</literal> is flushed to the database. Finally, the page is re-rendered, redisplaying the message list, and displaying the selected message below it.
+ </para>
+ <para>
+ When the user clicks the <literal><![CDATA[<h:commandButton>]]></literal>, JSF calls the <literal>delete()</literal> action listener. Seam intercepts this call and injects the selected row data into the <literal>message</literal> attribute of the <literal>messageList</literal> component. The action listener fires, which removes the selected <literal>Message</literal> from the list, and also calls <literal>remove()</literal> on the <literal>EntityManager</literal>. At the end of the call, Seam refreshes the <literal>messageList</literal> context variable and clears the <literal>message</literal> context variable. The EJB container commits the transaction, and deletes the <literal>Message</literal> from the database. Finally, the page is re-rendered, redisplaying the message list.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="todo">
+ <title>Seam and jBPM: the todo list example</title>
+ <para>
+ jBPM provides sophisticated functionality for workflow and task management. As an example of jBPM's integration with Seam, what follows is a simple "todo list" application. Managing task lists is a core function of jBPM, so little Java is required in this example.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/todo.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/todo.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <section>
+ <title>Understanding the code</title>
+ <para>
+ This example revolves around the jBPM process definition. It also uses two JSPs and two basic JavaBeans. (Session beans are not required here since they would not access the database or have any transactional behavior.) We will start with the process definition:
+ </para>
+ <!-- Can't use code hightlighting with callouts -->
+ <!-- <example>
+ <title>todo.jpdl.xml</title> -->
+ <formalpara><title>todo.jpdl.xml Example</title>
+ <para>
+ <!-- <programlistingco> <areaspec> <area id="todo-startstate" coords="3"/> <area id="todo-tasknode" coords="7"/> <area id="todo-task" coords="8"/> <area id="todo-assignment" coords="9"/> <area id="todo-endstate" coords="14"/> </areaspec> -->
+<programlisting><![CDATA[<process-definition name="todo">
+
+ <start-state name="start">
+ <transition to="todo"/>
+ </start-state>
+
+ <task-node name="todo">
+ <task name="todo" description="#{todoList.description}">
+ <assignment actor-id="#{actor.id}"/>
+ </task>
+ <transition to="done"/>
+ </task-node>
+
+ <end-state name="done"/>
- <start-state name="start">
- <transition to="todo"/>
- </start-state>
-
- <task-node name="todo">
- <task name="todo" description="#{todoList.description}">
- <assignment actor-id="#{actor.id}"/>
- </task>
- <transition to="done"/>
- </task-node>
-
- <end-state name="done"/>
-
-</process-definition>]]></programlisting>
- <calloutlist>
- <callout arearefs="todo-startstate">
- <para> The <literal><start-state></literal> node represents the logical start
- of the process. When the process starts, it immediately transitions to the
- <literal>todo</literal> node. </para>
- </callout>
- <callout arearefs="todo-tasknode">
- <para> The <literal><task-node></literal> node represents a <emphasis>wait
- state</emphasis>, where business process execution pauses, waiting for one or more
- tasks to be performed. </para>
- </callout>
- <callout arearefs="todo-task">
- <para> The <literal><task></literal> element defines a task to be performed by
- a user. Since there is only one task defined on this node, when it is complete,
- execution resumes, and we transition to the end state. The task gets its description
- from a Seam component named <literal>todoList</literal> (one of the JavaBeans). </para>
- </callout>
- <callout arearefs="todo-assignment">
- <para> Tasks need to be assigned to a user or group of users when they are created. In this
- case, the task is assigned to the current user, which we get from a built-in Seam
- component named <literal>actor</literal>. Any Seam component may be used to perform task
- assignment. </para>
- </callout>
- <callout arearefs="todo-endstate">
- <para> The <literal><end-state></literal> node defines the logical end of the
- business process. When execution reaches this node, the process instance is destroyed.
- </para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
+</process-definition>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <formalpara><title>messages.jsp Explanatory Notes</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The <literal><![CDATA[<start-state>]]></literal> node represents the logical beginning of the process. When the process begins, it immediately transitions to the <literal>todo</literal> node.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal><![CDATA[<task-node>]]></literal> node represents a <emphasis>wait state</emphasis>, where business process execution pauses, waiting for one or more tasks to be performed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal><![CDATA[<task>]]></literal> element defines a task to be performed by a user. Since there is only one task defined on this node, when it is complete, execution resumes, and we transition to the end state. The task receives its description from the <literal>todoList</literal> JavaBean.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Tasks are assigned to a user or group of users when they are created. Here, the task is assigned to the current user, retrieved from the built-in <literal>actor</literal> Seam component. (Any Seam component may be used to perform task assignment.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal><![CDATA[<end-state>]]></literal> node defines the logical end of the business process. When execution reaches this node, the process instance is destroyed.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </formalpara>
+ <!-- </programlistingco> -->
+ <!-- </example> -->
+ <para>
+ Viewed with the process definition editor provided by JBossIDE, the process definition looks like this:
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/todo-process.png" format="PNG" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/todo-process.png" format="PNG" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ This document defines our <emphasis>business process</emphasis> as a graph of nodes. This is the simplest possible business process: there is one <emphasis>task</emphasis> to be performed, and when that task is complete, the business process ends.
+ </para>
+ <para>
+ The first JavaBean handles the login screen, <literal>login.jsp</literal>. Here, it simply initializes the jBPM actor ID with the <literal>actor</literal> component. In a real application, it would also need to authenticate the user.
+ </para>
+ <!-- <example>
+ <title>Login.java</title> -->
+ <formalpara><title>Login.java Example</title>
+ <para>
+
+<programlisting role="JAVA"><![CDATA[@Name("login")
+public class Login {
+ @In
+ private Actor actor;
+
+ private String user;
- <para> If we view this process definition using the process definition editor provided by JBossIDE, this is
- what it looks like: </para>
+ public String getUser() {
+ return user;
+ }
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/todo-process.png" align="center"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/todo-process.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para> This document defines our <emphasis>business process</emphasis> as a graph of nodes. This is the most
- trivial possible business process: there is one <emphasis>task</emphasis> to be performed, and when that
- task is complete, the business process ends. </para>
-
- <para> The first JavaBean handles the login screen <literal>login.jsp</literal>. Its job is just to
- initialize the jBPM actor id using the <literal>actor</literal> component. In a real application, it
- would also need to authenticate the user.</para>
- <example>
- <title>Login.java</title>
- <programlisting role="JAVA"><![CDATA[@Name("login")
-public class Login
-{
- @In
- private Actor actor;
-
- private String user;
-
- public String getUser()
- {
- return user;
- }
-
- public void setUser(String user)
- {
- this.user = user;
- }
-
- public String login()
- {
- actor.setId(user);
- return "/todo.jsp";
- }
-}]]></programlisting>
- </example>
-
-
- <para> Here we see the use of <literal>@In</literal> to inject the built-in <literal>Actor</literal>
- component. </para>
-
- <para> The JSP itself is trivial: </para>
-
- <example>
- <title>login.jsp</title>
- <programlisting role="XHTML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
+ public void setUser(String user) {
+ this.user = user;
+ }
+
+ public String login() {
+ actor.setId(user);
+ return "/todo.jsp";
+ }
+}]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ Here we see the use of <literal>@In</literal> to inject the built-in <literal>Actor</literal> component.
+ </para>
+ <para>
+ The JSP itself is trivial:
+ </para>
+ <!--
+ <example>
+ <title>login.jsp</title> -->
+ <formalpara><title>login.jsp Example</title>
+ <para>
+
+<programlisting role="XHTML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<html>
-<head>
-<title>Login</title>
-</head>
-<body>
-<h1>Login</h1>
-<f:view>
- <h:form>
- <div>
- <h:inputText value="#{login.user}"/>
- <h:commandButton value="Login" action="#{login.login}"/>
- </div>
- </h:form>
-</f:view>
-</body>
-</html>]]></programlisting></example>
+ <head>
+ <title>Login</title>
+ </head>
+ <body>
+ <h1>Login</h1>
+ <f:view>
+ <h:form>
+ <div>
+ <h:inputText value="#{login.user}"/>
+ <h:commandButton value="Login" action="#{login.login}"/>
+ </div>
+ </h:form>
+ </f:view>
+ </body>
+</html>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ The second JavaBean is responsible for starting business process instances, and ending tasks.
+ </para>
+ <!-- Can't use code hightlighting with callouts -->
+ <!-- <example>
+ <title>TodoList.java</title> -->
+ <!-- <programlistingco> <areaspec> <area id="todo-description" coords="6"/> <area id="todo-createprocess-annotation" coords="15"/> <area id="todo-task-annotations" coords="18"/> </areaspec> -->
+ <formalpara><title>TodoList.java Example</title>
+ <para>
+<programlisting><![CDATA[@Name("todoList")
+public class TodoList {
+ private String description;
+
+ public String getDescription() {
+ return description;
+ }
-
+ public void setDescription(String description) {
+ this.description = description;
+ }
+
+ @CreateProcess(definition="todo")
+ public void createTodo() {}
+
+ @StartTask @EndTask
+ public void done() {}
- <para> The second JavaBean is responsible for starting business process instances, and ending tasks. </para>
-
- <!-- Can't use code hightlighting with callouts -->
- <example>
- <title>TodoList.java</title>
- <programlistingco>
- <areaspec>
- <area id="todo-description" coords="6"/>
- <area id="todo-createprocess-annotation" coords="15"/>
- <area id="todo-task-annotations" coords="18"/>
- </areaspec>
- <programlisting><![CDATA[@Name("todoList")
-public class TodoList
-{
- private String description;
-
- public String getDescription()
- {
- return description;
- }
-
- public void setDescription(String description)
- {
- this.description = description;
- }
-
- @CreateProcess(definition="todo")
- public void createTodo() {}
-
- @StartTask @EndTask
- public void done() {}
-
-}]]></programlisting>
- <calloutlist>
- <callout arearefs="todo-description">
- <para> The description property accepts user input from the JSP page, and exposes it to the
- process definition, allowing the task description to be set. </para>
- </callout>
- <callout arearefs="todo-createprocess-annotation">
- <para> The Seam <literal>@CreateProcess</literal> annotation creates a new jBPM process
- instance for the named process definition. </para>
- </callout>
- <callout arearefs="todo-task-annotations">
- <para> The Seam <literal>@StartTask</literal> annotation starts work on a task. The
- <literal>@EndTask</literal> ends the task, and allows the business process execution
- to resume. </para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
-
- <para> In a more realistic example, <literal>@StartTask</literal> and <literal>@EndTask</literal> would not
- appear on the same method, because there is usually work to be done using the application in order to
- complete the task. </para>
-
- <para> Finally, the core of the application is in <literal>todo.jsp</literal>: </para>
- <example>
- <title>todo.jsp</title>
- <programlisting role="XHTML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
+}]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <formalpara><title>TodoList.java Explanatory Notes</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The description property accepts user input from the JSP page, and exposes it to the process definition, allowing the task description to be set.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Seam <literal>@CreateProcess</literal> annotation creates a new jBPM process instance for the named process definition.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Seam <literal>@StartTask</literal> annotation starts work on a task. The <literal>@EndTask</literal> ends the task, and allows the business process execution to resume.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </formalpara>
+ <!-- </programlistingco> -->
+ <!-- </example> -->
+ <note>
+ <para>
+ In a more realistic example, <literal>@StartTask</literal> and <literal>@EndTask</literal> would not appear on the same method, because some work would need to be done with the application in order to complete the task.
+ </para>
+ </note>
+ <para>
+ Finally, the core of the application is in <literal>todo.jsp</literal>:
+ </para>
+ <!-- <example>
+ <title>todo.jsp</title> -->
+ <formalpara><title>todo.jsp Example</title>
+ <para>
+
+<programlisting role="XHTML"><![CDATA[<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<%@ taglib uri="http://jboss.com/products/seam/taglib" prefix="s" %>
<html>
-<head>
-<title>Todo List</title>
-</head>
-<body>
-<h1>Todo List</h1>
-<f:view>
- <h:form id="list">
- <div>
- <h:outputText value="There are no todo items."
- rendered="#{empty taskInstanceList}"/>
- <h:dataTable value="#{taskInstanceList}" var="task"
- rendered="#{not empty taskInstanceList}">
+ <head>
+ <title>Todo List</title>
+ </head>
+ <body>
+ <h1>Todo List</h1>
+ <f:view>
+ <h:form id="list">
+ <div>
+ <h:outputText value="There are no todo items."
+ rendered="#{empty taskInstanceList}"/>
+ <h:dataTable value="#{taskInstanceList}" var="task"
+ rendered="#{not empty taskInstanceList}">
<h:column>
- <f:facet name="header">
- <h:outputText value="Description"/>
- </f:facet>
- <h:inputText value="#{task.description}"/>
+ <f:facet name="header">
+ <h:outputText value="Description"/>
+ </f:facet>
+ <h:inputText value="#{task.description}"/>
</h:column>
<h:column>
- <f:facet name="header">
- <h:outputText value="Created"/>
- </f:facet>
- <h:outputText value="#{task.taskMgmtInstance.processInstance.start}">
- <f:convertDateTime type="date"/>
- </h:outputText>
+ <f:facet name="header">
+ <h:outputText value="Created"/>
+ </f:facet>
+ <h:outputText value=
+ "#{task.taskMgmtInstance.processInstance.start}">
+ <f:convertDateTime type="date"/>
+ </h:outputText>
</h:column>
<h:column>
- <f:facet name="header">
- <h:outputText value="Priority"/>
- </f:facet>
- <h:inputText value="#{task.priority}" style="width: 30"/>
+ <f:facet name="header">
+ <h:outputText value="Priority"/>
+ </f:facet>
+ <h:inputText value="#{task.priority}" style="width: 30"/>
</h:column>
<h:column>
- <f:facet name="header">
- <h:outputText value="Due Date"/>
- </f:facet>
- <h:inputText value="#{task.dueDate}" style="width: 100">
- <f:convertDateTime type="date" dateStyle="short"/>
- </h:inputText>
+ <f:facet name="header">
+ <h:outputText value="Due Date"/>
+ </f:facet>
+ <h:inputText value="#{task.dueDate}" style="width: 100">
+ <f:convertDateTime type="date" dateStyle="short"/>
+ </h:inputText>
</h:column>
<h:column>
- <s:button value="Done" action="#{todoList.done}" taskInstance="#{task}"/>
+ <s:button value="Done" action="#{todoList.done}"
+ taskInstance="#{task}"/>
</h:column>
- </h:dataTable>
- </div>
- <div>
- <h:messages/>
- </div>
- <div>
- <h:commandButton value="Update Items" action="update"/>
- </div>
- </h:form>
- <h:form id="new">
- <div>
- <h:inputText value="#{todoList.description}"/>
- <h:commandButton value="Create New Item" action="#{todoList.createTodo}"/>
- </div>
- </h:form>
-</f:view>
-</body>
-</html>]]></programlisting>
- </example>
-
-
- <para> Let's take this one piece at a time. </para>
-
- <para> The page renders a list of tasks, which it gets from a built-in Seam component named
- <literal>taskInstanceList</literal>. The list is defined inside a JSF form. </para>
- <example>
- <title>todo.jsp</title>
- <programlisting role="XHTML"><![CDATA[<h:form id="list">
- <div>
- <h:outputText value="There are no todo items." rendered="#{empty taskInstanceList}"/>
- <h:dataTable value="#{taskInstanceList}" var="task"
- rendered="#{not empty taskInstanceList}">
- ...
- </h:dataTable>
- </div>
-</h:form>]]></programlisting>
- </example>
-
- <para> Each element of the list is an instance of the jBPM class <literal>TaskInstance</literal>. The
- following code simply displays the interesting properties of each task in the list. For the description,
- priority and due date, we use input controls, to allow the user to update these values. </para>
-
- <programlisting role="XHTML"><![CDATA[<h:column>
- <f:facet name="header">
- <h:outputText value="Description"/>
- </f:facet>
- <h:inputText value="#{task.description}"/>
+ </h:dataTable>
+ </div>
+ <div>
+ <h:messages/>
+ </div>
+ <div>
+ <h:commandButton value="Update Items" action="update"/>
+ </div>
+ </h:form>
+ <h:form id="new">
+ <div>
+ <h:inputText value="#{todoList.description}"/>
+ <h:commandButton value="Create New Item"
+ action="#{todoList.createTodo}"/>
+ </div>
+ </h:form>
+ </f:view>
+ </body>
+</html>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ For simplicity's sake, we will look at this once section at a time.
+ </para>
+ <para>
+ The page renders a list of tasks, which it retrieves from a built-in Seam component named <literal>taskInstanceList</literal>. The list is defined inside a JSF form.
+ </para>
+ <!-- <example>
+ <title>todo.jsp (taskInstanceList)</title> -->
+ <formalpara><title>todo.jsp - taskInstanceList</title>
+ <para>
+<programlisting role="XHTML"><![CDATA[<h:form id="list">
+ <div>
+ <h:outputText value="There are no todo items."
+ rendered="#{empty taskInstanceList}"/>
+ <h:dataTable value="#{taskInstanceList}" var="task"
+ rendered="#{not empty taskInstanceList}">
+ ...
+ </h:dataTable>
+ </div>
+</h:form>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ Each element of the list is an instance of the jBPM class <literal>TaskInstance</literal>. The following code displays certain properties for every task in the list. Input controls are used for description, priority, and due date to allow users to update these values.
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:column>
+ <f:facet name="header">
+ <h:outputText value="Description"/>
+ </f:facet>
+ <h:inputText value="#{task.description}"/>
</h:column>
<h:column>
- <f:facet name="header">
- <h:outputText value="Created"/>
- </f:facet>
- <h:outputText value="#{task.taskMgmtInstance.processInstance.start}">
- <f:convertDateTime type="date"/>
- </h:outputText>
+ <f:facet name="header">
+ <h:outputText value="Created"/>
+ </f:facet>
+ <h:outputText value="#{task.taskMgmtInstance.processInstance.start}">
+ <f:convertDateTime type="date"/>
+ </h:outputText>
</h:column>
<h:column>
- <f:facet name="header">
- <h:outputText value="Priority"/>
- </f:facet>
- <h:inputText value="#{task.priority}" style="width: 30"/>
+ <f:facet name="header">
+ <h:outputText value="Priority"/>
+ </f:facet>
+ <h:inputText value="#{task.priority}" style="width: 30"/>
</h:column>
<h:column>
- <f:facet name="header">
- <h:outputText value="Due Date"/>
- </f:facet>
- <h:inputText value="#{task.dueDate}" style="width: 100">
- <f:convertDateTime type="date" dateStyle="short"/>
- </h:inputText>
-</h:column>]]></programlisting>
-
- <note>Seam provides a default JSF date converter for converting a string to a date (no time).
- Thus, the converter is not necessary for the field bound to <literal>#{task.dueDate}</literal>.</note>
-
- <para> This button ends the task by calling the action method annotated <literal>@StartTask
- @EndTask</literal>. It passes the task id to Seam as a request parameter: </para>
-
- <programlisting role="XHTML"><![CDATA[<h:column>
- <s:button value="Done" action="#{todoList.done}" taskInstance="#{task}"/>
-</h:column>]]></programlisting>
-
- <para> Note that this is using a Seam <literal><s:button></literal> JSF control from the
- <literal>seam-ui.jar</literal> package. This button is used to update the properties of the
- tasks. When the form is submitted, Seam and jBPM will make any changes to the tasks persistent.
- There is no need for any action listener method: </para>
-
- <programlisting role="XHTML"><![CDATA[<h:commandButton value="Update Items" action="update"/>]]></programlisting>
-
- <para> A second form on the page is used to create new items, by calling the action method annotated
- <literal>@CreateProcess</literal>. </para>
-
- <programlisting role="XHTML"><![CDATA[<h:form id="new">
- <div>
- <h:inputText value="#{todoList.description}"/>
- <h:commandButton value="Create New Item" action="#{todoList.createTodo}"/>
- </div>
-</h:form>]]></programlisting>
-
-
- </section>
-
-
- <section>
- <title>How it works</title>
- <para>After logging in, todo.jsp uses the <literal>taskInstanceList</literal> component to display a table
- of outstanding todo items for a the current user. Initially there are none. It
- also presents a form to enter a new entry. When the user types the todo item and
- hits the "Create New Item" button, <literal>#{todoList.createTodo}</literal> is called. This starts
- the todo process, as defined in <literal>todo.jpdl.xml</literal>. </para>
-
- <para>The process instance is created, starting in the start state and immediately transition to
- the <literal>todo</literal> state, where a new task is created. The task description is set
- based on the user's
- input, which was saved to <literal>#{todoList.description}</literal>. Then, the task is
- assigned to
- the current user, which was stored in the seam actor component. Note that in
- this example, the process has no extra process state. All the state in this example
- is stored in the task definition. The process and task information is stored in the database
- at the end of the request.
- </para>
-
- <para>
- When <literal>todo.jsp</literal> is redisplayed, <literal>taskInstanceList</literal> now finds
- the task that was just created.
- The task is shown in an <literal>h:dataTable</literal>. The internal state of the task is
- displayed in
- each column: <literal>#{task.description}</literal>, <literal>#{task.priority}</literal>,
- <literal>#{task.dueDate}</literal>, etc... These fields
- can all be edited and saved back to the database.
- </para>
-
- <para>Each todo item also has "Done" button, which calls <literal>#{todoList.done}</literal>. The
- <literal>todoList</literal> component
- knows which task the button is for because each s:button specificies
- <literal>taskInstance="#{task}"</literal>, referring
- to the task for that particular line of of the table. The <literal>@StartTast</literal> and
- <literal>@EndTask</literal> annotations
- cause seam to make the task active and immediately complete the task. The original process then
- transitions into the <literal>done</literal> state, according to the process definition, where it ends.
- The state of the task and process are both updated in the database.
- </para>
-
- <para>When <literal>todo.jsp</literal> is displayed again, the now-completed task is no longer
- displayed in the
- <literal>taskInstanceList</literal>, since that component only display active tasks for the user.</para>
- </section>
-
- </section>
-
- <section id="numberguess">
- <title>Seam pageflow: the numberguess example</title>
-
- <para> For Seam applications with relatively freeform (ad hoc) navigation, JSF/Seam navigation rules are a
- perfectly good way to define the page flow. For applications with a more constrained style of navigation,
- especially for user interfaces which are more stateful, navigation rules make it difficult to really
- understand the flow of the system. To understand the flow, you need to piece it together from the view
- pages, the actions and the navigation rules. </para>
-
- <para> Seam allows you to use a jPDL process definition to define pageflow. The simple number guessing example
- shows how this is done. </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/numberguess.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/numberguess.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <section>
- <title>Understanding the code</title>
- <para> The example is implemented using one JavaBean, three JSP pages and a jPDL pageflow definition. Let's
- begin with the pageflow: </para>
- <!-- Can't use code hightlighting with callouts -->
- <example>
- <title>pageflow.jpdl.xml</title>
- <programlistingco>
- <areaspec>
- <area id="numberguess-page" coords="8"/>
- <area id="numberguess-transition" coords="10"/>
- <area id="numberguess-action" coords="11"/>
- <area id="numberguess-decision" coords="16"/>
- </areaspec>
- <programlisting><![CDATA[<pageflow-definition
+ <f:facet name="header">
+ <h:outputText value="Due Date"/>
+ </f:facet>
+ <h:inputText value="#{task.dueDate}" style="width: 100">
+ <f:convertDateTime type="date" dateStyle="short"/>
+ </h:inputText>
+</h:column>]]>
+</programlisting>
+ <note>
+ <para>
+ Seam provides a default JSF date converter for converting a string into a date, so no converter is necessary for the field bound to <literal>#{task.dueDate}</literal>.
+ </para>
+ </note>
+ <para>
+ This button ends the task by calling the action method annotated <literal>@StartTask @EndTask</literal>. It passes the task ID to Seam as a request parameter:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:column>
+ <s:button value="Done" action="#{todoList.done}"
+ taskInstance="#{task}"/>
+</h:column>]]>
+</programlisting>
+ <para>
+ Note that this uses a Seam <literal><![CDATA[<s:button>]]></literal> JSF control from the <literal>seam-ui.jar</literal> package. This button updates the properties of the tasks. When the form is submitted, Seam and jBPM will make any changes to the tasks persistent. There is no need for any action listener method:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:commandButton value="Update Items" action="update"/>]]>
+</programlisting>
+ <para>
+ A second form on the page creates new items with the action method annotated <literal>@CreateProcess</literal>.
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:form id="new <div>
+ <h:inputText value="#{todoList.description}"/>
+ <h:commandButton value="Create New Item"
+ action="#{todoList.createTodo}"/>
+ </div>
+</h:form>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>How it works</title>
+ <para>
+ After logging in, <filename>todo.jsp</filename> uses the <literal>taskInstanceList</literal> component to display a table of outstanding todo items for the current user. (Initially there are none.) The page also displays a form to enter a new task item. When the user types the todo item and clicks the <guibutton>Create New Item</guibutton> button, <literal>#{todoList.createTodo}</literal> is called. This starts the todo process, as defined in <literal>todo.jpdl.xml</literal>.
+ </para>
+ <para>
+ When the process instance is created, it transitions immediately to the <literal>todo</literal> state, where a new task is created. The task description is set based on the user input saved to <literal>#{todoList.description}</literal>. The task is then assigned to the current user, stored in the seam actor component. In this example, the process has no extra process state — all the state is stored in the task definition. The process and task information is stored in the database at the end of the request.
+ </para>
+ <para>
+ When <filename>todo.jsp</filename> is redisplayed, <literal>taskInstanceList</literal> finds the newly-created task and displays it in an <literal>h:dataTable</literal>. The internal state of the task is displayed in each column: <literal>#{task.description}</literal>, <literal>#{task.priority}</literal>, <literal>#{task.dueDate}</literal>, etc. These fields can all be edited and saved to the database.
+ </para>
+ <para>
+ Each todo item also has a <guibutton>Done</guibutton> button, which calls <literal>#{todoList.done}</literal>. Each button specifies <literal>taskInstance="#{task}"</literal> (the task for that particular row of the table) so that the <literal>todoList</literal> component is able to distinctly identify which task is complete. The <literal>@StartTask</literal> and <literal>@EndTask</literal> annotations activate and immediately complete the task. The original process then transitions into the <literal>done</literal> state (according to the process definition) and ends. The state of the task and process are both updated in the database.
+ </para>
+ <para>
+ When <filename>todo.jsp</filename> is displayed again, the completed task is no longer shown in the <literal>taskInstanceList</literal>, since this component displays only incomplete tasks.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="numberguess">
+ <title>Seam pageflow: the numberguess example</title>
+ <para>
+ For Seam applications with freeform (ad hoc) navigation, JSF/Seam navigation rules are a good way to define page flow. However, in applications with more constrained navigation styles, especially user interfaces that are more stateful, navigation rules make understanding system flow difficult. Combining information from view pages, actions, and navigation rules makes this flow easier to understand.
+ </para>
+ <para>
+ With Seam, jPDL process definition can be used to define pageflow, as seen in the number guessing example that follows.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/numberguess.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/numberguess.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <section>
+ <title>Understanding the code</title>
+ <para>
+ The example uses one JavaBean, three JSP pages and a jPDL pageflow definition. We will start by looking at the pageflow:
+ </para>
+ <!-- Can't use code hightlighting with callouts -->
+ <!-- <example>
+ <title>pageflow.jpdl.xml</title> -->
+ <!-- <programlistingco> <areaspec> <area id="numberguess-page" coords="8"/> <area id="numberguess-transition" coords="10"/> <area id="numberguess-action" coords="11"/> <area id="numberguess-decision" coords="16"/> </areaspec> -->
+ <formalpara><title>pageflow.jpdl.xml Example</title>
+ <para>
+<programlisting><![CDATA[<pageflow-definition
xmlns="http://jboss.com/products/seam/pageflow"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://jboss.com/products/seam/pageflow
- http://jboss.com/products/seam/pageflow-2.2.xsd"
+ xsi:schemaLocation=
+ "http://jboss.com/products/seam/pageflow
+ http://jboss.com/products/seam/pageflow-2.2.xsd"
name="numberGuess">
- <start-page name="displayGuess" view-id="/numberGuess.jspx">
- <redirect/>
- <transition name="guess" to="evaluateGuess">
- <action expression="#{numberGuess.guess}"/>
- </transition>
- <transition name="giveup" to="giveup"/>
- <transition name="cheat" to="cheat"/>
- </start-page>
+ <start-page name="displayGuess" view-id="/numberGuess.jspx">
+ <redirect/>
+ <transition name="guess" to="evaluateGuess">
+ <action expression="#{numberGuess.guess}"/>
+ </transition>
+ <transition name="giveup" to="giveup"/>
+ <transition name="cheat" to="cheat"/>
+ </start-page>
- <decision name="evaluateGuess" expression="#{numberGuess.correctGuess}">
- <transition name="true" to="win"/>
- <transition name="false" to="evaluateRemainingGuesses"/>
- </decision>
+ <decision name="evaluateGuess" expression="#{numberGuess.correctGuess}">
+ <transition name="true" to="win"/>
+ <transition name="false" to="evaluateRemainingGuesses"/>
+ </decision>
- <decision name="evaluateRemainingGuesses" expression="#{numberGuess.lastGuess}">
- <transition name="true" to="lose"/>
- <transition name="false" to="displayGuess"/>
- </decision>
+ <decision name="evaluateRemainingGuesses"
+ expression="#{numberGuess.lastGuess}">
+ <transition name="true" to="lose"/>
+ <transition name="false" to="displayGuess"/>
+ </decision>
- <page name="giveup" view-id="/giveup.jspx">
- <redirect/>
- <transition name="yes" to="lose"/>
- <transition name="no" to="displayGuess"/>
- </page>
+ <page name="giveup" view-id="/giveup.jspx">
+ <redirect/>
+ <transition name="yes" to="lose"/>
+ <transition name="no" to="displayGuess"/>
+ </page>
- <process-state name="cheat">
- <sub-process name="cheat"/>
- <transition to="displayGuess"/>
- </process-state>
+ <process-state name="cheat">
+ <sub-process name="cheat"/>
+ <transition to="displayGuess"/>
+ </process-state>
- <page name="win" view-id="/win.jspx">
- <redirect/>
- <end-conversation/>
- </page>
+ <page name="win" view-id="/win.jspx">
+ <redirect/>
+ <end-conversation/>
+ </page>
- <page name="lose" view-id="/lose.jspx">
- <redirect/>
- <end-conversation/>
- </page>
+ <page name="lose" view-id="/lose.jspx">
+ <redirect/>
+ <end-conversation/>
+ </page>
-</pageflow-definition>]]></programlisting>
- <calloutlist>
- <callout arearefs="numberguess-page">
- <para> The <literal><page></literal> element defines a wait state where the
- system displays a particular JSF view and waits for user input. The
- <literal>view-id</literal> is the same JSF view id used in plain JSF navigation rules.
- The <literal>redirect</literal> attribute tells Seam to use post-then-redirect when
- navigating to the page. (This results in friendly browser URLs.) </para>
- </callout>
- <callout arearefs="numberguess-transition">
- <para> The <literal><transition></literal> element names a JSF outcome. The
- transition is triggered when a JSF action results in that outcome. Execution will then
- proceed to the next node of the pageflow graph, after invocation of any jBPM transition
- actions. </para>
- </callout>
- <callout arearefs="numberguess-action">
- <para> A transition <literal><action></literal> is just like a JSF action,
- except that it occurs when a jBPM transition occurs. The transition action can invoke
- any Seam component. </para>
- </callout>
- <callout arearefs="numberguess-decision">
- <para> A <literal><decision></literal> node branches the pageflow, and
- determines the next node to execute by evaluating a JSF EL expression. </para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
-
- <para> Here is what the pageflow looks like in the JBoss Developer Studio pageflow editor: </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/numberguess-pageflow.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/numberguess-pageflow.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para> Now that we have seen the pageflow, it is very, very easy to understand the rest of the application! </para>
-
- <para> Here is the main page of the application, <literal>numberGuess.jspx</literal>: </para>
-
- <example>
- <title>numberGuess.jspx</title>
- <programlisting role="XHTML"><![CDATA[<<?xml version="1.0"?>
+</pageflow-definition>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <formalpara><title>pageflow.jpdl.xml Explanatory Notes.</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The <literal><![CDATA[<page>]]></literal> element defines a wait state, during which the system displays a particular JSF view and waits for user input. The <literal>view-id</literal> is the same JSF view ID used in plain JSF navigation rules. The <literal>redirect</literal> attribute tells Seam to use post-then-redirect when navigating to the page. (This results in browser-friendly URLs.)
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal><![CDATA[<transition>]]></literal> element names a JSF outcome. The transition itself is triggered when a JSF action results in the named outcome. After any jBPM transition actions are invoked, execution will proceed to the next node of the pageflow graph.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A transition <literal><![CDATA[<action>]]></literal> is just like a JSF action, except that it is triggered when a jBPM transition occurs. The transition action can invoke any Seam component.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ A <literal><![CDATA[<decision>]]></literal> node branches the pageflow, and determines the next node to be executed by evaluating a JSF EL expression.
+ </para>
+ </listitem>
+ </orderedlist>
+ </para>
+ </formalpara>
+ <!-- </programlistingco> -->
+ <!-- </example> -->
+ <para>
+ In the JBoss Developer Studio pageflow editor, the pageflow looks like this:
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/numberguess-pageflow.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/numberguess-pageflow.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ With that pageflow in mind, the rest of the application is much easier to understand.
+ </para>
+ <para>
+ Here is the main page of the application, <literal>numberGuess.jspx</literal>:
+ </para>
+<!-- <example>
+ <title>numberGuess.jspx</title> -->
+ <formalpara><title>numberGuess.jspx Example</title>
+ <para>
+
+<programlisting role="XHTML"><![CDATA[<?xml version="1.0"?>
<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core"
@@ -1631,77 +1564,100 @@
version="2.0">
<jsp:output doctype-root-element="html"
doctype-public="-//W3C//DTD XHTML 1.0 Transitional//EN"
- doctype-system="http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"/>
+ doctype-system=
+ "http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"/>
<jsp:directive.page contentType="text/html"/>
<html>
- <head>
- <title>Guess a number...</title>
- <link href="niceforms.css" rel="stylesheet" type="text/css" />
- <script language="javascript" type="text/javascript" src="niceforms.js" />
- </head>
- <body>
- <h1>Guess a number...</h1>
- <f:view>
- <h:form styleClass="niceform">
+ <head>
+ <title>Guess a number...</title>
+ <link href="niceforms.css" rel="stylesheet" type="text/css" />
+ <script language="javascript" type="text/javascript"
+ src="niceforms.js" />
+ </head>
+ <body>
+ <h1>Guess a number...</h1>
+ <f:view>
+ <h:form styleClass="niceform">
- <div>
- <h:messages globalOnly="true"/>
- <h:outputText value="Higher!"
- rendered="#{numberGuess.randomNumber gt numberGuess.currentGuess}"/>
- <h:outputText value="Lower!"
- rendered="#{numberGuess.randomNumber lt numberGuess.currentGuess}"/>
- </div>
+ <div>
+ <h:messages globalOnly="true"/>
+ <h:outputText value="Higher!"
+ rendered="#{
+ numberGuess.randomNumber gt
+ numberGuess.currentGuess}"/>
+ <h:outputText value="Lower!"
+ rendered="#{
+ numberGuess.randomNumber lt
+ numberGuess.currentGuess}"/>
+ </div>
- <div>
- I'm thinking of a number between
- <h:outputText value="#{numberGuess.smallest}"/> and
- <h:outputText value="#{numberGuess.biggest}"/>. You have
- <h:outputText value="#{numberGuess.remainingGuesses}"/> guesses.
- </div>
+ <div>
+ I'm thinking of a number between
+ <h:outputText value="#{numberGuess.smallest}"/> and
+ <h:outputText value="#{numberGuess.biggest}"/>. You have
+ <h:outputText value="#{numberGuess.remainingGuesses}"/>
+ guesses.
+ </div>
- <div>
- Your guess:
- <h:inputText value="#{numberGuess.currentGuess}" id="inputGuess"
- required="true" size="3"
- rendered="#{(numberGuess.biggest-numberGuess.smallest) gt 20}">
- <f:validateLongRange maximum="#{numberGuess.biggest}"
- minimum="#{numberGuess.smallest}"/>
- </h:inputText>
- <h:selectOneMenu value="#{numberGuess.currentGuess}"
- id="selectGuessMenu" required="true"
- rendered="#{(numberGuess.biggest-numberGuess.smallest) le 20 and
- (numberGuess.biggest-numberGuess.smallest) gt 4}">
- <s:selectItems value="#{numberGuess.possibilities}" var="i" label="#{i}"/>
- </h:selectOneMenu>
- <h:selectOneRadio value="#{numberGuess.currentGuess}" id="selectGuessRadio"
- required="true"
- rendered="#{(numberGuess.biggest-numberGuess.smallest) le 4}">
- <s:selectItems value="#{numberGuess.possibilities}" var="i" label="#{i}"/>
- </h:selectOneRadio>
- <h:commandButton value="Guess" action="guess"/>
- <s:button value="Cheat" view="/confirm.jspx"/>
- <s:button value="Give up" action="giveup"/>
- </div>
+ <div>
+ Your guess:
+ <h:inputText value="#{numberGuess.currentGuess}"
+ id="inputGuess" required="true" size="3"
+ rendered="#{
+ (numberGuess.biggest-numberGuess.smallest) gt
+ 20}">
+ <f:validateLongRange maximum="#{numberGuess.biggest}"
+ minimum="#{numberGuess.smallest}"/>
+ </h:inputText>
+ <h:selectOneMenu value="#{numberGuess.currentGuess}"
+ id="selectGuessMenu" required="true"
+ rendered="#{
+ (numberGuess.biggest-numberGuess.smallest) le
+ 20 and
+ (numberGuess.biggest-numberGuess.smallest) gt
+ 4}">
+ <s:selectItems value="#{numberGuess.possibilities}"
+ var="i" label="#{i}"/>
+ </h:selectOneMenu>
+ <h:selectOneRadio value="#{numberGuess.currentGuess}"
+ id="selectGuessRadio"
+ required="true"
+ rendered="#{
+ (numberGuess.biggest-numberGuess.smallest) le
+ 4}">
+ <s:selectItems value="#{numberGuess.possibilities}"
+ var="i" label="#{i}"/>
+ </h:selectOneRadio>
+ <h:commandButton value="Guess" action="guess"/>
+ <s:button value="Cheat" view="/confirm.jspx"/>
+ <s:button value="Give up" action="giveup"/>
+ </div>
- <div>
- <h:message for="inputGuess" style="color: red"/>
- </div>
+ <div>
+ <h:message for="inputGuess" style="color: red"/>
+ </div>
- </h:form>
- </f:view>
- </body>
+ </h:form>
+ </f:view>
+ </body>
</html>
-</jsp:root>]]></programlisting>
- </example>
-
-
- <para> Notice how the command button names the <literal>guess</literal> transition instead of calling an
- action directly. </para>
-
- <para> The <literal>win.jspx</literal> page is predictable: </para>
- <example>
- <title>win.jspx</title>
- <programlisting role="JSP"><![CDATA[<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"
+</jsp:root>]]>
+</programlisting>
+</para>
+</formalpara>
+ <!-- </example> -->
+ <para>
+ Note that the command button names the <literal>guess</literal> transition instead of calling an action directly.
+ </para>
+ <para>
+ The <literal>win.jspx</literal> page is predictable:
+ </para>
+ <!-- <example>
+ <title>win.jspx</title> -->
+ <formalpara><title>win.jspx Example</title>
+ <para>
+
+<programlisting role="JSP"><![CDATA[<jsp:root xmlns:jsp="http://java.sun.com/JSP/Page"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core"
xmlns="http://www.w3.org/1999/xhtml"
@@ -1711,161 +1667,156 @@
doctype-system="http://www.w3c.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"/>
<jsp:directive.page contentType="text/html"/>
<html>
- <head>
- <title>You won!</title>
- <link href="niceforms.css" rel="stylesheet" type="text/css" />
- </head>
- <body>
- <h1>You won!</h1>
- <f:view>
- Yes, the answer was <h:outputText value="#{numberGuess.currentGuess}" />.
- It took you <h:outputText value="#{numberGuess.guessCount}" /> guesses.
- <h:outputText value="But you cheated, so it doesn't count!"
- rendered="#{numberGuess.cheat}"/>
- Would you like to <a href="numberGuess.seam">play again</a>?
- </f:view>
- </body>
+ <head>
+ <title>You won!</title>
+ <link href="niceforms.css" rel="stylesheet" type="text/css" />
+ </head>
+ <body>
+ <h1>You won!</h1>
+ <f:view>
+ Yes, the answer was
+ <h:outputText value="#{numberGuess.currentGuess}" />.
+ It took you
+ <h:outputText value="#{numberGuess.guessCount}" /> guesses.
+ <h:outputText value="But you cheated, so it doesn't count!"
+ rendered="#{numberGuess.cheat}"/>
+ Would you like to <a href="numberGuess.seam">play again</a>?
+ </f:view>
+ </body>
</html>
</jsp:root>
-]]></programlisting>
- </example>
-
-
- <para>The <literal>lose.jspx</literal> looks roughly the same, so we'll skip over it.</para>
-
- <para>Finally, we'll look at the actual application code: </para>
- <!-- Can't use code hightlighting with callouts -->
- <example>
- <title>NumberGuess.java</title>
- <programlistingco>
- <areaspec>
- <area id="numberguess-create" coords="13"/>
- </areaspec>
- <programlisting><![CDATA[@Name("numberGuess")
+]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ The <literal>lose.jspx</literal> is very similar, so we have not included it here.
+ </para>
+ <para>
+ Finally, the application code is as follows:
+ </para>
+ <!-- Can't use code hightlighting with callouts -->
+ <!-- <example>
+ <title>NumberGuess.java</title> -->
+ <!-- <programlistingco> <areaspec> <area id="numberguess-create" coords="13"/> </areaspec> -->
+ <formalpara><title>NumberGuess.java Example</title>
+ <para>
+<programlisting><![CDATA[@Name("numberGuess")
@Scope(ScopeType.CONVERSATION)
public class NumberGuess implements Serializable {
- private int randomNumber;
- private Integer currentGuess;
- private int biggest;
- private int smallest;
- private int guessCount;
- private int maxGuesses;
- private boolean cheated;
-
- @Create
- public void begin()
- {
- randomNumber = new Random().nextInt(100);
- guessCount = 0;
- biggest = 100;
- smallest = 1;
- }
-
- public void setCurrentGuess(Integer guess)
- {
- this.currentGuess = guess;
- }
-
- public Integer getCurrentGuess()
- {
- return currentGuess;
- }
-
- public void guess()
- {
- if (currentGuess>randomNumber)
- {
- biggest = currentGuess - 1;
- }
- if (currentGuess<randomNumber)
- {
- smallest = currentGuess + 1;
- }
- guessCount ++;
- }
-
- public boolean isCorrectGuess()
- {
- return currentGuess==randomNumber;
- }
-
- public int getBiggest()
- {
- return biggest;
- }
-
- public int getSmallest()
- {
- return smallest;
- }
-
- public int getGuessCount()
- {
- return guessCount;
- }
-
- public boolean isLastGuess()
- {
- return guessCount==maxGuesses;
- }
+ private int randomNumber;
+ private Integer currentGuess;
+ private int biggest;
+ private int smallest;
+ private int guessCount;
+ private int maxGuesses;
+ private boolean cheated;
+
+ @Create
+ public void begin() {
+ randomNumber = new Random().nextInt(100);
+ guessCount = 0;
+ biggest = 100;
+ smallest = 1;
+ }
+
+ public void setCurrentGuess(Integer guess) {
+ this.currentGuess = guess;
+ }
+
+ public Integer getCurrentGuess() {
+ return currentGuess;
+ }
+
+ public void guess() {
+ if (currentGuess>randomNumber) {
+ biggest = currentGuess - 1;
+ }
+ if (currentGuess<randomNumber) {
+ smallest = currentGuess + 1;
+ }
+ guessCount ++;
+ }
+
+ public boolean isCorrectGuess() {
+ return currentGuess==randomNumber;
+ }
+
+ public int getBiggest() {
+ return biggest;
+ }
+
+ public int getSmallest() {
+ return smallest;
+ }
+
+ public int getGuessCount() {
+ return guessCount;
+ }
+
+ public boolean isLastGuess() {
+ return guessCount==maxGuesses;
+ }
- public int getRemainingGuesses() {
- return maxGuesses-guessCount;
- }
+ public int getRemainingGuesses() {
+ return maxGuesses-guessCount;
+ }
- public void setMaxGuesses(int maxGuesses) {
- this.maxGuesses = maxGuesses;
- }
+ public void setMaxGuesses(int maxGuesses) {
+ this.maxGuesses = maxGuesses;
+ }
- public int getMaxGuesses() {
- return maxGuesses;
- }
+ public int getMaxGuesses() {
+ return maxGuesses;
+ }
- public int getRandomNumber() {
- return randomNumber;
- }
+ public int getRandomNumber() {
+ return randomNumber;
+ }
- public void cheated()
- {
- cheated = true;
- }
-
- public boolean isCheat() {
- return cheated;
- }
-
- public List<Integer> getPossibilities()
- {
- List<Integer> result = new ArrayList<Integer>();
- for(int i=smallest; i<=biggest; i++) result.add(i);
- return result;
- }
-
-}
-]]></programlisting>
- <calloutlist>
- <callout arearefs="numberguess-create">
- <para> The first time a JSP page asks for a <literal>numberGuess</literal> component, Seam
- will create a new one for it, and the <literal>@Create</literal> method will be invoked,
- allowing the component to initialize itself. </para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
-
-
- <para>The <literal>pages.xml</literal> file starts a Seam
- <emphasis>conversation</emphasis> (much more about that later), and specifies the
- pageflow definition to use for the conversation's page flow.
- </para>
-
- <example>
- <title>pages.xml</title>
-
-
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ public void cheated() {
+ cheated = true;
+ }
+
+ public boolean isCheat() {
+ return cheated;
+ }
+
+ public List<Integer> getPossibilities() {
+ List<Integer> result = new ArrayList<Integer>();
+ for(int i=smallest; i<=biggest; i++) result.add(i);
+ return result;
+ }
+
+}]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <formalpara><title>NumberGuess.java Explanatory Notes</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The first time a JSP page asks for a <literal>numberGuess</literal> component, Seam creates a new component, and the <literal>@Create</literal> method will be invoked, allowing the component to initialize itself.
+ </para>
+ </listitem>
+ </orderedlist>
+ <!-- </programlistingco> -->
+ <!-- </example> -->
+ </para>
+ </formalpara>
+ <para>
+ The <literal>pages.xml</literal> file starts a Seam <emphasis>conversation</emphasis>, and specifies the pageflow definition to use for the conversation's page flow. <!-- #retag: (More information on conversations is available in §ion;, but for the moment a thorough understanding is not necessary.) -->
+ </para>
+ <!-- <example>
+ <title>pages.xml</title> -->
+ <formalpara><title>pages.xml Example</title>
+ <para>
+
+<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<pages xmlns="http://jboss.com/products/seam/pages"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://jboss.com/products/seam/pages http://jboss.com/products/seam/pages-2.2.xsd">
@@ -1875,415 +1826,353 @@
</page>
</pages>
-]]></programlisting>
- </example>
-
-
- <para> As you can see, this Seam component is pure business logic! It doesn't need to know anything at all
- about the user interaction flow. This makes the component potentially more reuseable. </para>
-
- </section>
-
- <section>
- <title>How it works</title>
- <para>We'll step through basic flow of the application. The game starts with the
- <literal>numberGuess.jspx</literal> view. When the page is first displayed, the
- <literal>pages.xml</literal> configuration causes conversation to begin and associates
- the <literal>numberGuess</literal> pageflow
- with that conversation. The pageflow starts with a <literal>start-page</literal> tag,
- which is a wait state, so the <literal>numberGuess.xhtml</literal> is rendered.
- </para>
-
- <para>The view references the <literal>numberGuess</literal> component, causing a new
- instance to be created and stored in the conversation. The <literal>@Create</literal> method
- is called, initializing the state of the game. The view displays an <literal>h:form</literal>
- that allows the user to edit <literal>#{numberGuess.currentGuess}</literal>.
- </para>
-
- <para>The "Guess" button triggers the <literal>guess</literal> action. Seam defers to the pageflow
- to handle the action, which says that the pageflow should transition to the <literal>evaluateGuess</literal>
- state, first invoking <literal>#{numberGuess.guess}</literal>, which updates the guess count
- and highest/lowest suggestions in the <literal>numberGuess</literal> component.
- </para>
-
- <para> The <literal>evaluateGuess</literal> state checks the value of <literal>#{numberGuess.correctGuess}</literal>
- and transitions either to the <literal>win</literal> or <literal>evaluatingRemainingGuesses</literal>
- state. We'll assume the number was incorrect, in which case the pageflow transitions to
- <literal>evaluatingRemainingGuesses</literal>. That is also a decision state, which
- tests the <literal>#{numberGuess.lastGuess}</literal> state to determine whether or not the user has
- more guesses. If there are more guesses (<literal>lastGuess</literal> is <literal>false</literal>),
- we transition back to the original <literal>displayGuess</literal> state. Finally we've
- reached a page state, so the associated page <literal>/numberGuess.jspx</literal> is displayed.
- Since the page has a redirect element, Seam sends a redirect to the the user's browser,
- starting the process over.
- </para>
-
- <para>
- We won't follow the state any more except to note that if on a future request either the
- <literal>win</literal> or the <literal>lose</literal> transition were taken, the user would
- be taken to either the <literal>/win.jspx</literal> or <literal>/lose.jspx</literal>.
- Both states specify that Seam should end the conversation, tossing away all the game state and
- pageflow state, before redirecting the user to the
- final page.
-
- </para>
-
- <para>The numberguess example also contains Giveup and Cheat buttons. You should be able to
- trace the pageflow state for both actions relatively easily. Pay particular attention
- to the <literal>cheat</literal> transition, which loads a sub-process to handle that flow.
- Although it's
- overkill for this application, it does demonstrate how complex pageflows can be broken down into
- smaller parts to make them easier to understand.
+]]>
+</programlisting>
</para>
- </section>
-
- </section>
-
- <section id="booking">
- <title>A complete Seam application: the Hotel Booking example</title>
-
- <section>
- <title>Introduction</title>
-
- <para> The booking application is a complete hotel room reservation system incorporating the following
- features: </para>
-
- <itemizedlist>
- <listitem>
- <para>User registration</para>
- </listitem>
- <listitem>
- <para>Login</para>
- </listitem>
- <listitem>
- <para>Logout</para>
- </listitem>
- <listitem>
- <para>Set password</para>
- </listitem>
- <listitem>
- <para>Hotel search</para>
- </listitem>
- <listitem>
- <para>Hotel selection</para>
- </listitem>
- <listitem>
- <para>Room reservation</para>
- </listitem>
- <listitem>
- <para>Reservation confirmation</para>
- </listitem>
- <listitem>
- <para>Existing reservation list</para>
- </listitem>
- </itemizedlist>
-
- <screenshot>
- <screeninfo>Booking example</screeninfo>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/booking.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/booking.png" align="center"/>
- </imageobject>
- </mediaobject>
- </screenshot>
-
- <para> The booking application uses JSF, EJB 3.0 and Seam, together with Facelets for the view. There is
- also a port of this application to JSF, Facelets, Seam, JavaBeans and Hibernate3. </para>
-
- <para> One of the things you'll notice if you play with this application for long enough is that it is
- extremely <emphasis>robust</emphasis>. You can play with back buttons and browser refresh and opening
- multiple windows and entering nonsensical data as much as you like and you will find it very difficult
- to make the application crash. You might think that we spent weeks testing and fixing bugs to achive
- this. Actually, this is not the case. Seam was designed to make it very straightforward to build robust
- web applications and a lot of robustness that you are probably used to having to code yourself comes
- naturally and automatically with Seam. </para>
- <para> As you browse the sourcecode of the example application, and learn how the application works, observe
- how the declarative state management and integrated validation has been used to achieve this robustness. </para>
-
- </section>
-
- <section>
- <title>Overview of the booking example</title>
-
- <para> The project structure is identical to the previous one, to install and deploy this application,
- please refer to <xref linkend="try-examples"/>. Once you've successfully started the application, you
- can access it by pointing your browser to <ulink url="http://localhost:8080/seam-booking/">
- <literal>http://localhost:8080/seam-booking/</literal>
- </ulink>
- </para>
-
- <para>The application uses six session beans for to implement the business logic for the listed features. </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>AuthenticatorAction</literal> provides the login authentication logic.</para>
- </listitem>
- <listitem>
- <para><literal>BookingListAction</literal> retrieves existing bookings for the currently logged in user. </para>
- </listitem>
- <listitem>
- <para><literal>ChangePasswordAction</literal> updates the password of the currently logged in user.</para>
- </listitem>
- <listitem>
- <para><literal>HotelBookingAction</literal> implements booking and confirmation
- functionality. This functionality is implemented as a
- <emphasis>conversation</emphasis>, so this is one of the most interesting classes in the
- application.</para></listitem>
- <listitem>
- <para><literal>HotelSearchingAction</literal> implements the hotel search functionality.
- </para></listitem>
- <listitem>
- <para><literal>RegisterAction</literal> registers a new system user.</para>
- </listitem>
- </itemizedlist>
-
- <para> Three entity beans implement the application's persistent domain model. </para>
-
- <itemizedlist>
- <listitem>
- <para><literal>Hotel</literal> is an entity bean that represent a hotel </para></listitem>
- <listitem>
- <para><literal>Booking</literal> is an entity bean that represents an existing booking </para></listitem>
- <listitem>
- <para><literal>User</literal> is an entity bean to represents a user who can make hotel bookings</para>
- </listitem>
- </itemizedlist>
-
- </section>
-
- <section>
- <title>Understanding Seam conversations</title>
- <para> We encourage you browse the sourcecode at your pleasure. In this tutorial we'll concentrate upon one
- particular piece of functionality: hotel search, selection, booking and confirmation. From the point of
- view of the user, everything from selecting a hotel to confirming a booking is one continuous unit of
- work, a <emphasis>conversation</emphasis>. Searching, however, is <emphasis>not</emphasis> part of the
- conversation. The user can select multiple hotels from the same search results page, in different
- browser tabs. </para>
- <para> Most web application architectures have no first class construct to represent a conversation. This
- causes enormous problems managing conversational state. Usually, Java web applications
- use a combination of several techniques. Some state can be transfered in the URL.
- What can't is either thrown into the
- <literal>HttpSession</literal> or flushed to the database after every
- request, and reconstructed from the database at the beginning of each new request. </para>
- <para> Since the database is the least scalable tier, this often results in an utterly unacceptable lack of
- scalability. Added latency is also a problem, due to the extra traffic to and from the database on every
- request. To reduce this redundant traffic, Java applications often introduce a data (second-level) cache
- that keeps commonly accessed data between requests. This cache is necessarily inefficient, because
- invalidation is based upon an LRU policy instead of being based upon when the user has finished working
- with the data. Furthermore, because the cache is shared between many concurrent transactions, we've
- introduced a whole raft of problem's associated with keeping the cached state consistent with the
- database. </para>
- <para> Now consider the state held in the <literal>HttpSession</literal>. The HttpSession is great
- place for true session data, data that is common to all requests that the user has with the application.
- However, it's a bad place to store data related to individual series of requests. Using the session of
- conversational quickly breaks down when dealing with the back button and multiple windows.
- On top of that, without careful
- programming, data in the HTTP Session can grow quite large, making the HTTP session difficult
- to cluster. Developing mechanisms to isolate session state associated with different concurrent
- conversations, and incorporating failsafes to ensure that conversation state is destroyed when
- the user aborts one of the
- conversations by closing a browser window or tab is not for the faint hearted. Fortunately, with Seam,
- you don't have to worry about that.
- </para>
-
- <para> Seam introduces the <emphasis>conversation context</emphasis> as a first class construct. You can
- safely keep conversational state in this context, and be assured that it will have a well-defined
- lifecycle. Even better, you won't need to be continually pushing data back and forth between the
- application server and the database, since the conversation context is a natural cache of data that the
- user is currently working with. </para>
- <para> In this application, we'll use the conversation context to store stateful session beans.
- There is an ancient canard in the Java
- community that stateful session beans are a scalability killer. This may have been true in the
- early days of enterprise Java, but it is no longer true today. Modern application servers have
- extremely
- sophisticated mechanisms for stateful session bean state replication. JBoss AS, for example, performs
- fine-grained replication, replicating only those bean attribute values which actually
- changed. Note that all the traditional technical arguments for why stateful beans are inefficient apply
- equally to the <literal>HttpSession</literal>, so the practice of shifting state from business tier
- stateful session bean components to the web session to try and improve performance is unbelievably
- misguided. It is certainly possible to write unscalable applications using stateful session beans, by
- using stateful beans incorrectly, or by using them for the wrong thing. But that doesn't mean you should
- <emphasis>never</emphasis> use them.
- If you remain unconvinced, Seam allows the use of POJOs instead of stateful session beans.
- With Seam, the choice is yours.
- </para>
-
-
- <para> The booking example application shows how stateful components with different scopes can collaborate
- together to achieve complex behaviors. The main page of the booking application allows the user to
- search for hotels. The search results are kept in the Seam session scope. When the user navigates to one
- of these hotels, a conversation begins, and a conversation scoped component calls back to the session
- scoped component to retrieve the selected hotel. </para>
-
- <para> The booking example also demonstrates the use of RichFaces Ajax to implement rich client behavior without
- the use of handwritten JavaScript. </para>
-
- <para> The search functionality is implemented using a session-scope stateful session bean, similar to the
- one we saw in the message list example. </para>
-
- <example>
- <title>HotelSearchingAction.java</title>
- <!-- Can't use code hightlighting with callouts -->
- <programlistingco>
- <areaspec>
- <area id="booking-stateful-annotation" coords="1"/>
- <area id="booking-restrict-annotation" coords="4"/>
- <area id="booking-datamodel-annotation" coords="15"/>
- <area id="booking-destroy-annotation" coords="70"/>
- </areaspec>
- <programlisting><![CDATA[@Stateful
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ This component is pure business logic. Since it requires no information about the user interaction flow, it is potentially more reuseable.
+ </para>
+ </section>
+
+ <section>
+ <title>How it works</title>
+ <para>
+ The game begins in the <filename>numberGuess.jspx</filename> view. When the page is first displayed, the <filename>pages.xml</filename> configuration activates a conversation and associates it with the <literal>numberGuess</literal> pageflow. The pageflow starts with a <literal>start-page</literal> tag (a <emphasis>wait</emphasis> state), so the <filename>numberGuess.xhtml</filename> is rendered.
+ </para>
+ <para>
+ The view references the <literal>numberGuess</literal> component, which causes a new instance to be created and stored in the conversation. the <literal>@Create</literal> method is called, initializing the game's state. The view displays an <literal>h:form</literal>, which allows the user to edit <literal>#{numberGuess.currentGuess}</literal>.
+ </para>
+ <para>
+ The "Guess" button triggers the <literal>guess</literal> action. Seam refers to the pageflow to handle the action, and the pageflow invokes <literal>#{numberGuess.guess}</literal> (which updates the guess count and highest/lowest suggestions in the <literal>numberGuess</literal> component), and transitions to the <literal>evaluateGuess</literal> state.
+ </para>
+ <para>
+ The <literal>evaluateGuess</literal> state checks the value of <literal>#{numberGuess.correctGuess}</literal> and transitions to either the <literal>win</literal> or <literal>evaluatingRemainingGuesses</literal> state. Assuming the number was incorrect, the pageflow transitions to <literal>evaluatingRemainingGuesses</literal>. This is also a decision state, which tests the <literal>#{numberGuess.lastGuess}</literal> state to determine whether or not the user is allowed further guesses. If further guesses are allowed (<literal>lastGuess</literal> is <literal>false</literal>), we transition back to the original <literal>displayGuess</literal> state. Since this is a page state, the associated page <filename>/numberGuess.jspx</filename> is displayed. This page also contains a redirect element, so Seam sends a redirect to the user's browser, which begins the process again.
+ </para>
+ <para>
+ If on a future request either the <literal>win</literal> or the <literal>lose</literal> transition were invoked, the user would be taken to <filename>/win.jspx</filename> or <filename>/lose.jspx</filename> respectively. Both states specify that Seam should end the conversation, stop holding game and pageflow state, and redirect the user to the final page.
+ </para>
+ <para>
+ The numberguess example also contains <guibutton>Give up</guibutton> and <guibutton>Cheat</guibutton> buttons. The pageflow state for both actions is relatively easy to trace, so we do not describe it here. Pay particular attention to the <literal>cheat</literal> transition, which loads a sub-process to handle that particular flow. Although in this application this process is superfluous, this demonstrates how complex pageflows can be broken down into smaller, simpler structures to make them easier to understand.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="booking">
+ <title>A complete Seam application: the Hotel Booking example</title>
+ <section>
+ <title>Introduction</title>
+ <para>
+ The booking application is a complete hotel room reservation system incorporating the following features:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ User registration
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Login
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Logout
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Set password
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Hotel search
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Hotel selection
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Room reservation
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Reservation confirmation
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Existing reservation list
+ </para>
+ </listitem>
+ </itemizedlist>
+ <mediaobject>
+ <textobject>
+ <phrase>Booking example</phrase>
+ </textobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/booking.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/booking.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ The booking application uses JSF, EJB 3.0 and Seam, together with Facelets for the view. There is also a port of this application to JSF, Facelets, Seam, JavaBeans and Hibernate3.
+ </para>
+ <para>
+ One of the things you will notice about this application is that it is extremely <emphasis>robust</emphasis>. You can open multiple windows, use the back and browser refresh buttons, and enter nonsensical data, but the application is difficult to crash. Seam was designed to make building robust web applications straightforward, so robustness that would previously be hand-coded comes naturally and automatically with Seam.
+ </para>
+ <para>
+ As you browse the source code of the example application and learn how the application works, pay particular attention to the way the declarative state management and integrated validation has been used to achieve this robustness.
+ </para>
+ </section>
+
+ <section>
+ <title>Overview of the booking example</title>
+ <para>
+ The project structure here is identical to that of the previous project. To install and deploy this application, refer to <xref linkend="try-examples" />. Once you have successfully started the application, you can access it by pointing your browser to <ulink url="http://localhost:8080/seam-booking/"> <literal>http://localhost:8080/seam-booking/</literal> </ulink>
+ </para>
+ <para>
+ The application uses six session beans to implement the business logic for the following features:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>AuthenticatorAction</literal> provides the login authentication logic.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>BookingListAction</literal> retrieves existing bookings for the currently logged in user.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>ChangePasswordAction</literal> updates the password of the currently logged in user.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>HotelBookingAction</literal> implements booking and confirmation functionality. This is implemented as a <emphasis>conversation</emphasis>, so this is one of the more important classes in the application.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>HotelSearchingAction</literal> implements the hotel search functionality.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>RegisterAction</literal> registers a new system user.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Three entity beans implement the application's persistent domain model:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ <literal>Hotel</literal> is an entity bean that represents a hotel
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>Booking</literal> is an entity bean that represents an existing booking
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ <literal>User</literal> is an entity bean representing a user who can make hotel bookings
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
+ <section>
+ <title>Understanding Seam conversations</title>
+ <para>
+ This tutorial concentrates upon one particular piece of functionality: placing a hotel reservation. From the user's perspective, hotel search, selection, booking, and confirmation are one continuous unit of work — a <emphasis>conversation</emphasis>. However, from our perspective, it is important that searching remains separate so that users can select multiple hotels from the same search results page, and open distinct conversations in separate browswer tabs.
+ </para>
+ <para>
+ Most web application architectures do not have first class constructs to represent conversations, which makes managing conversational state problematic. Java web applications generally use a combination of several techniques. Some state is transferred in the URL, but what cannot be transferred here is either added to the <literal>HttpSession</literal> or recorded to the database at the beginning and end of each request.
+ </para>
+ <para>
+ Since the database is the least-scalable tier, this drastically reduces scalability. The extra traffic to and from the database also increases latency. In order to reduce redundant traffic, Java applications often introduce a data cache to store commonly-accessed data between requests. However, since invalidation is based upon an LRU policy, rather than whether the user has finished using the data, this cache is inefficient. It is also shared between concurrent transactions, which introduces further issues associated with keeping the cached state consistent with that of the database.
+ </para>
+ <para>
+ State held in the <literal>HttpSession</literal> suffers similar issues. The <literal>HttpSession</literal> is fine for storing true session data — data common to all requests between user and application — but for data related to individual request series, it does not work so well. Conversations stored here quickly break down when dealing with multiple windows or the back button. Without careful programming, data in the <literal>HttpSession</literal> can also grow quite large, which makes the session difficult to cluster. Developing mechanisms to deal with the problems these methods present (by isolating session state associated with distinct concurrent conversations, and incorporating failsafes to ensure conversation state is destroyed when a conversation is aborted) can be complicated.
+ </para>
+ <para>
+ Seam greatly improves conditions by introducing <emphasis>conversation context</emphasis> as a first class construct. Conversation state is stored safely in this context, with a well-defined lifecycle. Even better, there is no need to push data continually between the application server and the database; the conversation context is a natural cache for currently-used data.
+ </para>
+ <para>
+ In the following application, the conversation context is used to store stateful session beans. These are sometimes regarded as detrimental to scalability, and in the past, they may have been. However, modern application servers have sophisticated mechanisms for stateful session bean replication. JBoss AS performs fine-grained replication, replicating only altered bean attribute values. Used correctly, stateful session beans pose no scalability problems, but for those uncomfortable or unfamiliar with the use of stateful session beans, Seam also allows the use of POJOs.
+ </para>
+ <para>
+ The booking example shows one way that stateful components with different scopes can collaborate to achieve complex behaviors. The main page of the booking application allows the user to search for hotels. Search results are stored in the Seam session scope. When the user navigate to a hotel, a conversation begins, and a conversation scoped component retrieves the selected hotel from the session scoped component.
+ </para>
+ <para>
+ The booking example also demonstrates the use of RichFaces Ajax to implement rich client behavior without handwritten JavaScript.
+ </para>
+ <para>
+ The search function is implemented with a session-scoped stateful session bean, similar to the one used in the message list example.
+ </para>
+ <!-- <example>
+ <title>HotelSearchingAction.java</title> -->
+
+ <!-- Can't use code hightlighting with callouts --> <!-- <programlistingco> <areaspec> <area id="booking-stateful-annotation" coords="1"/> <area id="booking-restrict-annotation" coords="4"/> <area id="booking-datamodel-annotation" coords="15"/> <area id="booking-destroy-annotation" coords="70"/> </areaspec> -->
+ <formalpara><title>HotelSearchingAction.java Example</title>
+ <para>
+<!-- <programlisting language="java"><xi:include href="extras/booking.java" parse="text" xmlns:xi="http://www.w3.org/2001/XInclude"></xi:include></programlisting>
+ </example> -->
+<programlisting><![CDATA[@Stateful
@Name("hotelSearch")
@Scope(ScopeType.SESSION)
@Restrict("#{identity.loggedIn}")
-public class HotelSearchingAction implements HotelSearching
-{
+public class HotelSearchingAction implements HotelSearching {
- @PersistenceContext
- private EntityManager em;
-
- private String searchString;
- private int pageSize = 10;
- private int page;
-
- @DataModel
- private List<Hotel> hotels;
-
- public void find()
- {
- page = 0;
- queryHotels();
- }
- public void nextPage()
- {
- page++;
- queryHotels();
- }
-
- private void queryHotels()
- {
- hotels =
- em.createQuery("select h from Hotel h where lower(h.name) like #{pattern} " +
- "or lower(h.city) like #{pattern} " +
- "or lower(h.zip) like #{pattern} " +
- "or lower(h.address) like #{pattern}")
+ @PersistenceContext
+ private EntityManager em;
+
+ private String searchString;
+ private int pageSize = 10;
+ private int page;
+
+ @DataModel
+ private List<Hotel> hotels;
+
+ public void find() {
+ page = 0;
+ queryHotels();
+ }
+ public void nextPage() {
+ page++;
+ queryHotels();
+ }
+
+ private void queryHotels() {
+ hotels = em.createQuery(
+ "select h from Hotel h where lower(h.name) like #{pattern}" +
+ "or lower(h.city) like #{pattern} " +
+ "or lower(h.zip) like #{pattern} " +
+ "or lower(h.address) like #{pattern}")
.setMaxResults(pageSize)
.setFirstResult( page * pageSize )
.getResultList();
- }
-
- public boolean isNextPageAvailable()
- {
- return hotels!=null && hotels.size()==pageSize;
- }
-
- public int getPageSize() {
- return pageSize;
- }
-
- public void setPageSize(int pageSize) {
- this.pageSize = pageSize;
- }
-
- @Factory(value="pattern", scope=ScopeType.EVENT)
- public String getSearchPattern()
- {
- return searchString==null ?
- "%" : '%' + searchString.toLowerCase().replace('*', '%') + '%';
- }
-
- public String getSearchString()
- {
- return searchString;
- }
-
- public void setSearchString(String searchString)
- {
- this.searchString = searchString;
- }
-
- @Remove
- public void destroy() {}
-}]]></programlisting>
- <calloutlist>
- <callout arearefs="booking-stateful-annotation">
- <para> The EJB standard <literal>@Stateful</literal> annotation identifies this class as a
- stateful session bean. Stateful session beans are scoped to the conversation context by
- default. </para>
- </callout>
- <callout arearefs="booking-restrict-annotation">
- <para> The <literal>@Restrict</literal> annotation applies a security restriction to the
- component. It restricts access to the component allowing only logged-in users. The
- security chapter explains more about security in Seam. </para>
- </callout>
- <callout arearefs="booking-datamodel-annotation">
- <para> The <link linkend="datamodel-annotation">
- <literal>@DataModel</literal>
- </link> annotation exposes a <literal>List</literal> as a JSF
- <literal>ListDataModel</literal>. This makes it easy to implement clickable lists for
- search screens. In this case, the list of hotels is exposed to the page as a
- <literal>ListDataModel</literal> in the conversation variable named
- <literal>hotels</literal>. </para>
- </callout>
- <callout arearefs="booking-destroy-annotation">
- <para> The EJB standard <literal>@Remove</literal> annotation specifies that a stateful
- session bean should be removed and its state destroyed after invocation of the annotated
- method. In Seam, all stateful session beans must define a method with no parameters marked
- <literal>@Remove</literal>. This method will be
- called when Seam destroys the session context.</para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
-
- <para> The main page of the application is a Facelets page. Let's look at the fragment which relates to
- searching for hotels: </para>
- <example>
- <title>main.xhtml</title>
- <!-- Can't use code hightlighting with callouts -->
- <programlistingco>
- <areaspec>
- <area id="booking-support-element" coords="14"/>
- <area id="booking-status-element" coords="20"/>
- <area id="booking-outputpanel-element" coords="37"/>
- <area id="booking-link-element" coords="61"/>
- </areaspec>
- <programlisting><![CDATA[<div class="section">
+ }
- <span class="errors">
- <h:messages globalOnly="true"/>
- </span>
+ public boolean isNextPageAvailable() {
+ return hotels!=null && hotels.size()==pageSize;
+ }
+
+ public int getPageSize() {
+ return pageSize;
+ }
+
+ public void setPageSize(int pageSize) {
+ this.pageSize = pageSize;
+ }
+
+ @Factory(value="pattern", scope=ScopeType.EVENT)
+ public String getSearchPattern() {
+ return searchString==null ?
+ "%" : '%' + searchString.toLowerCase().replace('*', '%') + '%';
+ }
+
+ public String getSearchString() {
+ return searchString;
+ }
+
+ public void setSearchString(String searchString) {
+ this.searchString = searchString;
+ }
+
+ @Remove
+ public void destroy() {}
+}]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <formalpara><title>HotelSearchingAction.java Explanatory Notes</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The EJB standard <literal>@Stateful</literal> annotation identifies this class as a stateful session bean. Stateful session beans are scoped to the conversation context by default.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>@Restrict</literal> annotation applies a security restriction to the component. It restricts access to the component, allowing only logged-in users. The <!-- #retag: xref plz -->security chapter explains more about security in Seam.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <xref linkend="datamodel-annotation" /> annotation exposes a <literal>List</literal> as a JSF <literal>ListDataModel</literal>. This makes it easy to implement clickable lists for search screens. In this case, the list of hotels is exposed to the page as a <literal>ListDataModel</literal> in the conversation variable named <literal>hotels</literal>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The EJB standard <literal>@Remove</literal> annotation specifies that a stateful session bean should be removed and its state destroyed after invocation of the annotated method. In Seam, all stateful session beans must define a method <literal>@Remove</literal>, with no marked parameters. This method will be called when Seam destroys the session context.
+ </para>
+ </listitem>
+ </orderedlist>
+ <!-- </programlistingco> -->
+ <!-- </example> -->
+ </para>
+ </formalpara>
+ <para>
+ The main page of the application is a Facelets page. The fragment that relates to searching for hotels is shown below:
+ </para>
+ <!-- <example>
+ <title>main.xhtml</title> -->
+ <!-- Can't use code hightlighting with callouts --> <!-- <programlistingco> <areaspec> <area id="booking-support-element" coords="14"/> <area id="booking-status-element" coords="20"/> <area id="booking-outputpanel-element" coords="37"/> <area id="booking-link-element" coords="61"/> </areaspec> -->
+ <formalpara><title>main.xhtml Example</title>
+ <para>
+<programlisting><![CDATA[<div class="section">
+
+ <span class="errors">
+ <h:messages globalOnly="true"/>
+ </span>
- <h1>Search Hotels</h1>
+ <h1>Search Hotels</h1>
- <h:form id="searchCriteria">
+ <h:form id="searchCriteria">
<fieldset>
- <h:inputText id="searchString" value="#{hotelSearch.searchString}"
- style="width: 165px;">
- <a:support event="onkeyup" actionListener="#{hotelSearch.find}"
- reRender="searchResults" />
- </h:inputText>
-  
- <a:commandButton id="findHotels" value="Find Hotels" action="#{hotelSearch.find}"
- reRender="searchResults"/>
-  
- <a:status>
- <f:facet name="start">
- <h:graphicImage value="/img/spinner.gif"/>
- </f:facet>
- </a:status>
- <br/>
- <h:outputLabel for="pageSize">Maximum results:</h:outputLabel> 
- <h:selectOneMenu value="#{hotelSearch.pageSize}" id="pageSize">
- <f:selectItem itemLabel="5" itemValue="5"/>
- <f:selectItem itemLabel="10" itemValue="10"/>
- <f:selectItem itemLabel="20" itemValue="20"/>
- </h:selectOneMenu>
+ <h:inputText id="searchString" value="#{hotelSearch.searchString}"
+ style="width: 165px;">
+ <a:support event="onkeyup" actionListener="#{hotelSearch.find}"
+ reRender="searchResults" />
+ </h:inputText>
+  
+ <a:commandButton id="findHotels" value="Find Hotels"
+ action="#{hotelSearch.find}"
+ reRender="searchResults"/>
+  
+ <a:status>
+ <f:facet name="start">
+ <h:graphicImage value="/img/spinner.gif"/>
+ </f:facet>
+ </a:status>
+ <br/>
+ <h:outputLabel for="pageSize">Maximum results:</h:outputLabel> 
+ <h:selectOneMenu value="#{hotelSearch.pageSize}" id="pageSize">
+ <f:selectItem itemLabel="5" itemValue="5"/>
+ <f:selectItem itemLabel="10" itemValue="10"/>
+ <f:selectItem itemLabel="20" itemValue="20"/>
+ </h:selectOneMenu>
</fieldset>
- </h:form>
+ </h:form>
</div>
@@ -2293,946 +2182,847 @@
rendered="#{hotels != null and hotels.rowCount==0}"/>
<h:dataTable id="hotels" value="#{hotels}" var="hot"
rendered="#{hotels.rowCount>0}">
- <h:column>
- <f:facet name="header">Name</f:facet>
- #{hot.name}
- </h:column>
- <h:column>
- <f:facet name="header">Address</f:facet>
- #{hot.address}
- </h:column>
- <h:column>
- <f:facet name="header">City, State</f:facet>
- #{hot.city}, #{hot.state}, #{hot.country}
- </h:column>
- <h:column>
- <f:facet name="header">Zip</f:facet>
- #{hot.zip}
- </h:column>
- <h:column>
- <f:facet name="header">Action</f:facet>
- <s:link id="viewHotel" value="View Hotel"
- action="#{hotelBooking.selectHotel(hot)}"/>
- </h:column>
+ <h:column>
+ <f:facet name="header">Name</f:facet>
+ #{hot.name}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Address</f:facet>
+ #{hot.address}
+ </h:column>
+ <h:column>
+ <f:facet name="header">City, State</f:facet>
+ #{hot.city}, #{hot.state}, #{hot.country}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Zip</f:facet>
+ #{hot.zip}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Action</f:facet>
+ <s:link id="viewHotel" value="View Hotel"
+ action="#{hotelBooking.selectHotel(hot)}"/>
+ </h:column>
</h:dataTable>
<s:link value="More results" action="#{hotelSearch.nextPage}"
rendered="#{hotelSearch.nextPageAvailable}"/>
</div>
-</a:outputPanel> ]]></programlisting>
- <calloutlist>
- <callout arearefs="booking-support-element">
- <para> The RichFaces Ajax <literal><a:support></literal> tag allows a JSF action
- event listener to be called by asynchronous <literal>XMLHttpRequest</literal> when a
- JavaScript event like <literal>onkeyup</literal> occurs. Even better, the
- <literal>reRender</literal> attribute lets us render a fragment of the JSF page and
- perform a partial page update when the asynchronous response is received. </para>
- </callout>
- <callout arearefs="booking-status-element">
- <para> The RichFaces Ajax <literal><a:status></literal> tag lets us display an
- animated image while we wait for asynchronous requests to return. </para>
- </callout>
- <callout arearefs="booking-outputpanel-element">
- <para> The RichFaces Ajax <literal><a:outputPanel></literal> tag defines a region of
- the page which can be re-rendered by an asynchronous request. </para>
- </callout>
- <callout arearefs="booking-link-element">
- <para> The Seam <literal><s:link></literal> tag lets us attach a JSF action
- listener to an ordinary (non-JavaScript) HTML link. The advantage of this over the
- standard JSF <literal><h:commandLink></literal> is that it preserves the
- operation of "open in new window" and "open in new tab". Also notice that we use a
- method binding with a parameter: <literal>#{hotelBooking.selectHotel(hot)}</literal>.
- This is not possible in the standard Unified EL, but Seam provides an extension to the
- EL that lets you use parameters on any method binding expression. </para>
- <para> If you're wondering how navigation occurs,
- you can find all the rules in <literal>WEB-INF/pages.xml</literal>;
- this is discussed in <xref linkend="events.pageaction.navigation"/>. </para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
-
- <para> This page displays the search results dynamically as we type, and lets us choose a hotel and pass it
- to the <literal>selectHotel()</literal> method of the <literal>HotelBookingAction</literal>, which is
- where the <emphasis>really</emphasis> interesting stuff is going to happen. </para>
-
-
- <para> Now let's see how the booking example application uses a conversation-scoped stateful session bean to
- achieve a natural cache of persistent data related to the conversation. The following code example is
- pretty long. But if you think of it as a list of scripted actions that implement the various steps of
- the conversation, it's understandable. Read the class from top to bottom, as if it were a story. </para>
- <example>
- <title>HotelBookingAction.java</title>
- <!-- Can't use code hightlighting with callouts -->
- <programlistingco>
- <areaspec>
- <area id="booking-extendedpersistencecontext-annotation" coords="7"/>
- <area id="booking-out-annotation" coords="17"/>
- <area id="booking-begin-annotation" coords="31"/>
- <area id="booking-end-annotation" coords="72"/>
- <area id="booking-dest-annotation" coords="85"/>
- </areaspec>
- <programlisting><![CDATA[@Stateful
+</a:outputPanel>]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <formalpara><title>main.xhtml Explanatory Notes</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The RichFaces Ajax <literal><![CDATA[<a:support>]]></literal> tag allows a JSF action event listener to be called by asynchronous <literal>XMLHttpRequest</literal> when a JavaScript event such as <literal>onkeyup</literal> occurs. Even better, the <literal>reRender</literal> attribute lets us render a fragment of the JSF page and perform a partial page update when the asynchronous response is received.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The RichFaces Ajax <literal><![CDATA[<a:status>]]></literal> tag lets us display an animated image while we wait for asynchronous requests to return.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The RichFaces Ajax <literal><![CDATA[<a:outputPanel>]]></literal> tag defines a region of the page which can be re-rendered by an asynchronous request.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The Seam <literal><![CDATA[<s:link>]]></literal> tag lets us attach a JSF action listener to an ordinary (non-JavaScript) HTML link. The advantage of this over the standard JSF <literal><![CDATA[<h:commandLink>]]></literal> is that it preserves the "open in new window" and "open in new tab" operations. Also note that we use a method binding with a parameter: <literal>#{hotelBooking.selectHotel(hot)}</literal>. This is not possible in standard Unified EL, but Seam provides an extension to an EL that allows parameters on any method binding expression.
+ </para>
+ <para>
+ Navigation rules can be found in <literal>WEB-INF/pages.xml</literal>. These are discussed further in <xref linkend="events.pageaction.navigation" />.
+ </para>
+ </listitem>
+ </orderedlist>
+ <!-- </programlistingco> -->
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ This page displays search results dynamically as the user types, and passes a selected hotel to the <literal>selectHotel()</literal> method of <literal>HotelBookingAction</literal>, where the real work occurs.
+ </para>
+ <para>
+ The following code shows how the booking example application uses a conversation-scoped stateful session bean to achieve a natural cache of persistent data related to the conversation. Think of the code as a list of scripted actions that implement the various steps of the conversation.
+ </para>
+ <!-- <example>
+ <title>HotelBookingAction.java</title> -->
+ <!-- Can't use code hightlighting with callouts --> <!-- <programlistingco> <areaspec> <area id="booking-extendedpersistencecontext-annotation" coords="7"/> <area id="booking-out-annotation" coords="17"/> <area id="booking-begin-annotation" coords="31"/> <area id="booking-end-annotation" coords="72"/> <area id="booking-dest-annotation" coords="85"/> </areaspec> -->
+ <formalpara><title>HotelBookingAction.java Example</title>
+ <para>
+<programlisting><![CDATA[@Stateful
@Name("hotelBooking")
@Restrict("#{identity.loggedIn}")
-public class HotelBookingAction implements HotelBooking
-{
+public class HotelBookingAction implements HotelBooking {
- @PersistenceContext(type=EXTENDED)
- private EntityManager em;
-
- @In
- private User user;
-
- @In(required=false) @Out
- private Hotel hotel;
-
- @In(required=false)
- @Out(required=false)
- private Booking booking;
-
- @In
- private FacesMessages facesMessages;
-
- @In
- private Events events;
-
- @Logger
- private Log log;
-
- private boolean bookingValid;
-
- @Begin
- public void selectHotel(Hotel selectedHotel)
- {
- hotel = em.merge(selectedHotel);
- }
-
- public void bookHotel()
- {
- booking = new Booking(hotel, user);
- Calendar calendar = Calendar.getInstance();
- booking.setCheckinDate( calendar.getTime() );
- calendar.add(Calendar.DAY_OF_MONTH, 1);
- booking.setCheckoutDate( calendar.getTime() );
- }
-
- public void setBookingDetails()
- {
- Calendar calendar = Calendar.getInstance();
- calendar.add(Calendar.DAY_OF_MONTH, -1);
- if ( booking.getCheckinDate().before( calendar.getTime() ) )
- {
- facesMessages.addToControl("checkinDate", "Check in date must be a future date");
- bookingValid=false;
- }
- else if ( !booking.getCheckinDate().before( booking.getCheckoutDate() ) )
- {
- facesMessages.addToControl("checkoutDate",
- "Check out date must be later than check in date");
- bookingValid=false;
- }
- else
- {
- bookingValid=true;
- }
- }
-
- public boolean isBookingValid()
- {
- return bookingValid;
- }
-
- @End
- public void confirm()
- {
- em.persist(booking);
- facesMessages.add("Thank you, #{user.name}, your confimation number " +
- " for #{hotel.name} is #{booki g.id}");
- log.info("New booking: #{booking.id} for #{user.username}");
- events.raiseTransactionSuccessEvent("bookingConfirmed");
- }
-
- @End
- public void cancel() {}
-
- @Remove
- public void destroy() {}
-]]></programlisting>
- <calloutlist>
- <callout arearefs="booking-extendedpersistencecontext-annotation">
- <para> This bean uses an EJB3 <emphasis>extended persistence context</emphasis>, so that any
- entity instances remain managed for the whole lifecycle of the stateful session bean.
- </para>
- </callout>
- <callout arearefs="booking-out-annotation">
- <para> The <link linkend="out-annotation">
- <literal>@Out</literal>
- </link> annotation declares that an attribute value is <emphasis>outjected</emphasis> to
- a context variable after method invocations. In this case, the context variable named
- <literal>hotel</literal> will be set to the value of the <literal>hotel</literal>
- instance variable after every action listener invocation completes. </para>
- </callout>
- <callout arearefs="booking-begin-annotation">
- <para> The <link linkend="begin-annotation">
- <literal>@Begin</literal>
- </link> annotation specifies that the annotated method begins a <emphasis>long-running
- conversation</emphasis>, so the current conversation context will not be destroyed
- at the end of the request. Instead, it will be reassociated with every request from the
- current window, and destroyed either by timeout due to conversation inactivity or
- invocation of a matching <literal>@End</literal> method. </para>
- </callout>
- <callout arearefs="booking-end-annotation">
- <para> The <link linkend="end-annotation">
- <literal>@End</literal>
- </link> annotation specifies that the annotated method ends the current long-running
- conversation, so the current conversation context will be destroyed at the end of the
- request. </para>
- </callout>
- <callout arearefs="booking-dest-annotation">
- <para> This EJB remove method will be called when Seam destroys the conversation context.
- Don't forget to define this method! </para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
-
- <para>
- <literal>HotelBookingAction</literal> contains all the action listener methods that implement selection,
- booking and booking confirmation, and holds state related to this work in its instance variables. We
- think you'll agree that this code is much cleaner and simpler than getting and setting
- <literal>HttpSession</literal> attributes. </para>
-
- <para> Even better, a user can have multiple isolated conversations per login session. Try it! Log in, run a
- search, and navigate to different hotel pages in multiple browser tabs. You'll be able to work on
- creating two different hotel reservations at the same time. If you leave any one conversation inactive
- for long enough, Seam will eventually time out that conversation and destroy its state. If, after ending
- a conversation, you backbutton to a page of that conversation and try to perform an action, Seam will
- detect that the conversation was already ended, and redirect you to the search page. </para>
-
- </section>
-
- <section>
- <title>The Seam Debug Page</title>
-
- <para> The WAR also includes <literal>seam-debug.jar</literal>. The Seam debug page will be available
- if this jar is deployed in
- <literal>WEB-INF/lib</literal>, along with the Facelets, and if you set the debug property
- of the <literal>init</literal> component:</para>
-
- <programlisting role="XML"><![CDATA[<core:init jndi-pattern="@jndiPattern@" debug="true"/>]]></programlisting>
-
- <para> This page lets you browse and inspect the Seam components
- in any of the Seam contexts associated with your current login session. Just point your browser at
- <ulink url="http://localhost:8080/seam-booking/debug.seam">
- <literal>http://localhost:8080/seam-booking/debug.seam</literal>
- </ulink>. </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/debug.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/debug.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- </section>
-
- </section>
-
- <section id="nestedbooking">
- <title>Nested conversations: extending the Hotel Booking example</title>
-
- <section>
- <title>Introduction</title>
-
- <para>Long-running conversations make it simple to maintain consistency of state in an application
-even in the face of multi-window operation and back-buttoning. Unfortunately, simply beginning and ending a
-long-running conversation is not always enough. Depending on the requirements of the application, inconsistencies
-between what the user's expectations and the reality of the application’s state can still result.</para>
-
- <para>The nested booking application extends the features of the hotel booking application to incorporate
-the selection of rooms. Each hotel has available rooms with descriptions for a user to select from. This requires
-the addition of a room selection page in the hotel reservation flow.</para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/nested-booking.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/nested-booking.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>The user now has the option to select any available room to be included in the booking. As with the
-hotel booking application we saw previously, this can lead to issues with state consistency. As with storing state
-in the <varname>HTTPSession</varname>, if a conversation variable changes it affects all windows operating within
-the same conversation context.</para>
-
- <para>To demonstrate this, let’s suppose the user clones the room selection screen in a new window. The
-user then selects the <emphasis>Wonderful Room</emphasis> and proceeds to the confirmation screen. To see just how much
-it would cost to live the high-life, the user returns to the original window, selects the <emphasis>Fantastic
-Suite</emphasis> for booking, and again proceeds to confirmation. After reviewing the total cost, the user decides
-that practicality wins out and returns to the window showing <emphasis>Wonderful Room</emphasis> to confirm.</para>
-
- <para>In this scenario, if we simply store all state in the conversation, we are not protected from
-multi-window operation within the same conversation. Nested conversations allow us to achieve correct behavior even
-when context can vary within the same conversation.</para>
- </section>
-
- <section>
- <title>Understanding Nested Conversations</title>
-
- <para>Now let's see how the nested booking example extends the behavior of the hotel booking application through
-use of nested conversations. Again, we can read the class from top to bottom, as if it were a story.</para>
-
- <example>
- <title>RoomPreferenceAction.java</title>
- <!-- Can't use code hightlighting with callouts -->
- <programlistingco>
- <areaspec>
- <area id="nested-booking-load-rooms" coords="25"/>
- <area id="nested-booking-nested-conversation" coords="38"/>
- <area id="nested-booking-select-preference" coords="43"/>
- <area id="nested-booking-end-annotation" coords="58"/>
- </areaspec>
- <programlisting><![CDATA[@Stateful
+ @PersistenceContext(type=EXTENDED)
+ private EntityManager em;
+
+ @In
+ private User user;
+
+ @In(required=false) @Out
+ private Hotel hotel;
+
+ @In(required=false)
+ @Out(required=false)
+ private Booking booking;
+
+ @In
+ private FacesMessages facesMessages;
+
+ @In
+ private Events events;
+
+ @Logger
+ private Log log;
+
+ private boolean bookingValid;
+
+ @Begin
+ public void selectHotel(Hotel selectedHotel) {
+ hotel = em.merge(selectedHotel);
+ }
+
+ public void bookHotel() {
+ booking = new Booking(hotel, user);
+ Calendar calendar = Calendar.getInstance();
+ booking.setCheckinDate( calendar.getTime() );
+ calendar.add(Calendar.DAY_OF_MONTH, 1);
+ booking.setCheckoutDate( calendar.getTime() );
+ }
+
+ public void setBookingDetails() {
+ Calendar calendar = Calendar.getInstance();
+ calendar.add(Calendar.DAY_OF_MONTH, -1);
+ if ( booking.getCheckinDate().before( calendar.getTime() ) ) {
+ facesMessages.addToControl("checkinDate",
+ "Check in date must be a future date");
+ bookingValid=false;
+ }
+ else if (!booking.getCheckinDate().before(booking.getCheckoutDate()))
+ {
+ facesMessages.addToControl("checkoutDate",
+ "Check out date must be later than check in date");
+ bookingValid=false;
+ }
+ else
+ {
+ bookingValid=true;
+ }
+ }
+
+ public boolean isBookingValid() {
+ return bookingValid;
+ }
+
+ @End
+ public void confirm() {
+ em.persist(booking);
+ facesMessages.add("Thank you, #{user.name}, " +
+ "your confimation number " +
+ "for #{hotel.name} is #{booki g.id}");
+ log.info("New booking: #{booking.id} for #{user.username}");
+ events.raiseTransactionSuccessEvent("bookingConfirmed");
+ }
+
+ @End
+ public void cancel() {}
+
+ @Remove
+ public void destroy() {}]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <formalpara><title>HotelBookingAction.java Explanatory Notes</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ This bean uses an EJB3 <emphasis>extended persistence context</emphasis>, so that entity instances remain managed for the whole lifecycle of the stateful session bean.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <xref linkend="out-annotation" /> annotation declares that an attribute value is "outjected" to a context variable after method invocations. In this case, the context variable named <literal>hotel</literal> will be set to the value of the <literal>hotel</literal> instance variable after every action listener invocation.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <xref linkend="begin-annotation" /> annotation specifies that the annotated method begins a <emphasis>long-running conversation</emphasis>, so the current conversation context will not be destroyed at the end of the request. Instead, it will be reassociated with every request from the current window, and destroyed either by timeout due to conversation inactivity or invocation of a matching <literal>@End</literal> method.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <xref linkend="end-annotation" /> annotation specifies that the annotated method ends the current long-running conversation, so the current conversation context will be destroyed at the end of the request.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ This EJB remove method must be defined, and will be called when Seam destroys the conversation context.
+ </para>
+ </listitem>
+ </orderedlist>
+ <!-- </programlistingco> -->
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ <literal>HotelBookingAction</literal> contains all the action listener methods that implement selection, booking and booking confirmation, and holds state related to this work in its instance variables. This code is much cleaner and simpler than getting and setting <literal>HttpSession</literal> attributes.
+ </para>
+ <para>
+ Even better, a user can have multiple isolated conversations per login session. Log in, run a search, and navigate to different hotel pages in multiple browser tabs. You'll be able to work on creating two different hotel reservations at the same time. If you leave any one conversation inactive for long enough, Seam will eventually time out that conversation and destroy its state. If, after ending a conversation, you backbutton to a page of that conversation and try to perform an action, Seam will detect that the conversation was already ended, and redirect you to the search page.
+ </para>
+ </section>
+
+ <section>
+ <title>The Seam Debug Page</title>
+ <para>
+ The WAR also includes <filename>seam-debug.jar</filename>. To make the Seam debug page available, deploy this jar in <literal>WEB-INF/lib</literal> alongside Facelets, and set the debug property of the <literal>init</literal> component as shown here:
+ </para>
+
+<programlisting role="XML"><![CDATA[<core:init jndi-pattern="@jndiPattern@" debug="true"/>]]>
+</programlisting>
+ <para>
+ The debug page lets you browse and inspect the Seam components in any of the Seam contexts associated with your current login session. Just point your browser at <ulink url="http://localhost:8080/seam-booking/debug.seam"> <literal>http://localhost:8080/seam-booking/debug.seam</literal> </ulink>.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/debug.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/debug.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ </section>
+
+ </section>
+
+ <section id="nestedbooking">
+ <title>Nested conversations: extending the Hotel Booking example</title>
+ <section>
+ <title>Introduction</title>
+ <para>
+ Long-running conversations let you easily maintain state consistency in an application, even in the face of multi-window operation and back-buttoning. Unfortunately, simply beginning and ending a long-running conversation is not always enough. Depending on the requirements of the application, inconsistencies between user expectations and application state can still result.
+ </para>
+ <para>
+ The nested booking application extends the features of the hotel booking application to incorporate room selection. Each hotel has a list of available rooms from which the user can select. This requires the addition of a room selection page in the hotel reservation flow.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/nested-booking.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/nested-booking.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ The user can now select any available room to be included in the booking. If room selection were left in the same conversation context, this could lead to issues with state consistency — if a conversation variable changes, it affects all windows operating within the same conversation context.
+ </para>
+ <para>
+ For example, suppose the user clones the room selection screen in a new window. The user then selects the <emphasis>Wonderful Room</emphasis> and proceeds to the confirmation screen. To check the cost of a more expensive room, the user returns to the original window, selects the <emphasis>Fantastic Suite</emphasis> for booking, and again proceeds to confirmation. After reviewing the total cost, the user returns to the window showing <emphasis>Wonderful Room</emphasis> to confirm.
+ </para>
+ <para>
+ In this scenario, if all state were stored in the conversation, flexibility for multi-window operation within the same conversation would be limited. Nested conversations allow us to achieve correct behavior even when context can vary within the same conversation.
+ </para>
+ </section>
+
+ <section>
+ <title>Understanding Nested Conversations</title>
+ <para>
+ The following code shows the behavior of the hotel booking application with entended behavior for nested conversations. Again, think of the code as a set of steps to be read in sequence.
+ </para>
+ <!-- <example>
+ <title>RoomPreferenceAction.java</title> -->
+ <!-- Can't use code hightlighting with callouts --> <!-- <programlistingco> <areaspec> <area id="nested-booking-load-rooms" coords="25"/> <area id="nested-booking-nested-conversation" coords="38"/> <area id="nested-booking-select-preference" coords="43"/> <area id="nested-booking-end-annotation" coords="58"/> </areaspec> -->
+ <formalpara><title>RoomPreferenceAction.java Example</title>
+ <para>
+<programlisting><![CDATA[@Stateful
@Name("roomPreference")
@Restrict("#{identity.loggedIn}")
-public class RoomPreferenceAction implements RoomPreference
-{
+public class RoomPreferenceAction implements RoomPreference {
- @Logger
- private Log log;
+ @Logger
+ private Log log;
- @In private Hotel hotel;
+ @In private Hotel hotel;
+
+ @In private Booking booking;
+
+ @DataModel(value="availableRooms")
+ private List<Room> availableRooms;
+
+ @DataModelSelection(value="availableRooms")
+ private Room roomSelection;
- @In private Booking booking;
+ @In(required=false, value="roomSelection")
+ @Out(required=false, value="roomSelection")
+ private Room room;
- @DataModel(value="availableRooms")
- private List<Room> availableRooms;
+ @Factory("availableRooms")
+ public void loadAvailableRooms() {
+ availableRooms = hotel.getAvailableRooms(booking.getCheckinDate(),
+ booking.getCheckoutDate());
+ log.info("Retrieved #0 available rooms", availableRooms.size());
+ }
- @DataModelSelection(value="availableRooms")
- private Room roomSelection;
+ public BigDecimal getExpectedPrice() {
+ log.info("Retrieving price for room #0", roomSelection.getName());
- @In(required=false, value="roomSelection")
- @Out(required=false, value="roomSelection")
- private Room room;
+ return booking.getTotal(roomSelection);
+ }
- @Factory("availableRooms")
- public void loadAvailableRooms()
- {
- availableRooms = hotel.getAvailableRooms(booking.getCheckinDate(), booking.getCheckoutDate());
- log.info("Retrieved #0 available rooms", availableRooms.size());
- }
+ @Begin(nested=true)
+ public String selectPreference() {
+ log.info("Room selected");
+
+ this.room = this.roomSelection;
+
+ return "payment";
+ }
- public BigDecimal getExpectedPrice()
- {
- log.info("Retrieving price for room #0", roomSelection.getName());
-
- return booking.getTotal(roomSelection);
- }
+ public String requestConfirmation() {
+ // all validations are performed through the s:validateAll,
+ // so checks are already performed
+ log.info("Request confirmation from user");
+
+ return "confirm";
+ }
- @Begin(nested=true)
- public String selectPreference()
- {
- log.info("Room selected");
-
- this.room = this.roomSelection;
-
- return "payment";
- }
+ @End(beforeRedirect=true)
+ public String cancel() {
+ log.info("ending conversation");
- public String requestConfirmation()
- {
- // all validations are performed through the s:validateAll, so checks are already
- // performed
- log.info("Request confirmation from user");
-
- return "confirm";
- }
+ return "cancel";
+ }
- @End(beforeRedirect=true)
- public String cancel()
- {
- log.info("ending conversation");
+ @Destroy @Remove
+ public void destroy() {}
+}]]>
+</programlisting>
- return "cancel";
- }
-
- @Destroy @Remove
- public void destroy() {}
-}
-]]></programlisting>
- <calloutlist>
- <callout arearefs="nested-booking-load-rooms">
- <para> The <varname>hotel</varname> instance is injected from the conversation context. The hotel
- is loaded through an <emphasis>extended persistence context</emphasis> so that the entity
- remains managed throughout the conversation. This allows us to lazily load the
- <varname>availableRooms</varname> through an <varname>@Factory</varname> method by
- simply walking the association.
- </para>
- </callout>
- <callout arearefs="nested-booking-nested-conversation">
- <para> When <link linkend="begin-annotation">
- <literal>@Begin(nested=true)</literal>
- </link> is encountered, a nested conversation is pushed onto the conversation stack. When
- executing within a nested conversation, components still have access to all outer conversation
- state, but setting any values in the nested conversation’s state container does not affect
- the outer conversation. In addition, nested conversations can exist concurrently stacked on the
- same outer conversation, allowing independent state for each.</para>
- </callout>
- <callout arearefs="nested-booking-select-preference">
- <para>The <varname>roomSelection</varname> is outjected to the conversation based on the
- <varname>@DataModelSelection</varname>. Note that because the nested conversation has an
- independent context, the <varname>roomSelection</varname> is only set into the new nested
- conversation. Should the user select a different preference in another window or tab a new
- nested conversation would be started.</para>
- </callout>
- <callout arearefs="nested-booking-end-annotation">
- <para> The <link linkend="end-annotation">
- <literal>@End</literal>
- </link> annotation pops the conversation stack and resumes the outer conversation. The
- <varname>roomSelection</varname> is destroyed along with the conversation context.</para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
- <para>When we begin a nested conversation it is pushed onto the conversation stack. In the <varname>nestedbooking</varname>
-example, the conversation stack consists of the outer long-running conversation (the booking) and each of the nested conversations (room
-selections).</para>
-
- <example>
- <title>rooms.xhtml</title>
- <!-- Can't use code hightlighting with callouts -->
- <programlistingco>
- <areaspec>
- <area id="nested-booking-available-rooms" coords="19"/>
- <area id="nested-booking-selection-action" coords="36"/>
- <area id="nested-booking-cancel-action" coords="45"/>
- </areaspec>
- <programlisting><![CDATA[<div class="section">
- <h1>Room Preference</h1>
+ </para>
+ </formalpara>
+ <formalpara><title>RoomPreferenceAction.java Explanatory Notes</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ The <varname>hotel</varname> instance is injected from the conversation context. The hotel is loaded through an <emphasis>extended persistence context</emphasis> so that the entity remains managed throughout the conversation. This lets us load the <varname>availableRooms</varname> through an <varname>@Factory</varname> method by walking the association.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ When <literal>@Begin(nested=true)</literal> is encountered, a nested conversation is pushed onto the conversation stack. When executing within a nested conversation, components still have access to all extra-conversation state, but setting any values in the nested conversation’s state container does not affect the external conversation. In addition, nested conversations can exist concurrently stacked on the same external conversation, allowing independent state for each.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <varname>roomSelection</varname> is outjected to the conversation based on the <varname>@DataModelSelection</varname>. Note that, because the nested conversation has an independent context, the <varname>roomSelection</varname> is only set into the new nested conversation. Should the user select a different preference in another window or tab, a new nested conversation would be invoked.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>@End</literal> annotation terminates the conversation stack and resumes the external conversation. The <varname>roomSelection</varname> is destroyed along with the conversation context.
+ </para>
+ </listitem>
+ </orderedlist>
+ <!-- </programlistingco> -->
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ When we begin a nested conversation, it is pushed onto the conversation stack. In the <varname>nestedbooking</varname> example, the conversation stack consists of the external long-running conversation (the booking) and each of the nested conversations (room selections).
+ </para>
+ <!-- <example>
+ <title>rooms.xhtml</title> -->
+ <!-- Can't use code hightlighting with callouts --> <!-- <programlistingco> <areaspec> <area id="nested-booking-available-rooms" coords="19"/> <area id="nested-booking-selection-action" coords="36"/> <area id="nested-booking-cancel-action" coords="45"/> </areaspec> -->
+ <formalpara><title>rooms.xhtml Example</title>
+ <para>
+<programlisting><![CDATA[<div class="section">
+ <h1>Room Preference</h1>
</div>
<div class="section">
- <h:form id="room_selections_form">
- <div class="section">
- <h:outputText styleClass="output"
- value="No rooms available for the dates selected: "
- rendered="#{availableRooms != null and availableRooms.rowCount == 0}"/>
- <h:outputText styleClass="output"
- value="Rooms available for the dates selected: "
- rendered="#{availableRooms != null and availableRooms.rowCount > 0}"/>
-
- <h:outputText styleClass="output" value="#{booking.checkinDate}"/> -
- <h:outputText styleClass="output" value="#{booking.checkoutDate}"/>
-
- <br/><br/>
-
- <h:dataTable value="#{availableRooms}" var="room"
- rendered="#{availableRooms.rowCount > 0}">
- <h:column>
- <f:facet name="header">Name</f:facet>
- #{room.name}
- </h:column>
- <h:column>
- <f:facet name="header">Description</f:facet>
- #{room.description}
- </h:column>
- <h:column>
- <f:facet name="header">Per Night</f:facet>
- <h:outputText value="#{room.price}">
- <f:convertNumber type="currency" currencySymbol="$"/>
- </h:outputText>
- </h:column>
- <h:column>
- <f:facet name="header">Action</f:facet>
- <h:commandLink id="selectRoomPreference"
- action="#{roomPreference.selectPreference}">Select</h:commandLink>
- </h:column>
- </h:dataTable>
- </div>
- <div class="entry">
- <div class="label"> </div>
- <div class="input">
- <s:button id="cancel" value="Revise Dates" view="/book.xhtml"/>
- </div>
- </div>
- </h:form>
+ <h:form id="room_selections_form">
+ <div class="section">
+ <h:outputText styleClass="output"
+ value="No rooms available for the dates selected: "
+ rendered="#{availableRooms != null
+ and availableRooms.rowCount == 0}"/>
+ <h:outputText styleClass="output"
+ value="Rooms available for the dates selected: "
+ rendered="#{availableRooms != null and
+ availableRooms.rowCount > 0}"/>
+
+ <h:outputText styleClass="output" value="#{booking.checkinDate}"/> -
+ <h:outputText styleClass="output" value="#{booking.checkoutDate}"/>
+
+ <br/><br/>
+
+ <h:dataTable value="#{availableRooms}" var="room"
+ rendered="#{availableRooms.rowCount > 0}">
+ <h:column>
+ <f:facet name="header">Name</f:facet>
+ #{room.name}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Description</f:facet>
+ #{room.description}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Per Night</f:facet>
+ <h:outputText value="#{room.price}">
+ <f:convertNumber type="currency" currencySymbol="$"/>
+ </h:outputText>
+ </h:column>
+ <h:column>
+ <f:facet name="header">Action</f:facet>
+ <h:commandLink id="selectRoomPreference"
+ action="#{roomPreference.selectPreference}">Select
+ </h:commandLink>
+ </h:column>
+ </h:dataTable>
+ </div>
+ <div class="entry">
+ <div class="label"> </div>
+ <div class="input">
+ <s:button id="cancel" value="Revise Dates" view="/book.xhtml"/>
+ </div>
+ </div>
+ </h:form>
</div>
-]]></programlisting>
- <calloutlist>
- <callout arearefs="nested-booking-available-rooms">
- <para>When requested from EL, the <varname>#{availableRooms}</varname> are loaded by the <varname>@Factory</varname>
-method defined in <varname>RoomPreferenceAction</varname>. The <varname>@Factory</varname> method will only be executed once to load the values
-into the current context as a <link linkend="datamodel-annotation">
- <varname>@DataModel</varname>
-</link> instance.</para>
- </callout>
- <callout arearefs="nested-booking-selection-action">
- <para>Invoking the <varname>#{roomPreference.selectPreference}</varname> action results in the row being selected
-and set into the <varname>@DataModelSelection</varname>. This value is then outjected to the nested conversation context.</para>
- </callout>
- <callout arearefs="nested-booking-cancel-action">
- <para>Revising the dates simply returns to the <varname>/book.xhtml</varname>. Note that we have not yet nested
-a conversation (no room preference has been selected), so the current conversation can simply be resumed. The <varname><s:button></varname>
-component simply propagates the current conversation when displaying the <varname>/book.xhtml</varname> view.</para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
- <para>Now that we have seen how to nest a conversation, let's see how we can confirm the booking once a room has been selected. This
-can be achieved by simply extending the behavior of the <varname>HotelBookingAction</varname>.</para>
-
- <example>
- <title>HotelBookingAction.java</title>
- <!-- Can't use code hightlighting with callouts -->
- <programlistingco>
- <areaspec>
- <area id="nested-booking-end-root" coords="77"/>
- <area id="nested-booking-confirm" coords="82"/>
- <area id="nested-booking-cancel" coords="89" />
- </areaspec>
- <programlisting><![CDATA[@Stateful
+]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <formalpara><title>rooms.xhtml Explanatory Notes</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ When requested from EL, the <varname>#{availableRooms}</varname> are loaded by the <varname>@Factory</varname> method defined in <varname>RoomPreferenceAction</varname>. The <varname>@Factory</varname> method will only be executed once to load the values into the current context as a <xref linkend="datamodel-annotation" /> instance.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Invoking the <varname>#{roomPreference.selectPreference}</varname> action results in the row being selected and set into the <varname>@DataModelSelection</varname>. This value is then outjected to the nested conversation context.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Revising the dates simply returns to the <varname>/book.xhtml</varname>. Note that we have not yet nested a conversation (no room preference has been selected), so the current conversation can simply be resumed. The <varname><![CDATA[<s:button>]]></varname> component simply propagates the current conversation when displaying the <varname>/book.xhtml</varname> view.
+ </para>
+ </listitem>
+ </orderedlist>
+ <!-- </programlistingco> -->
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ Now that you have seen how to nest a conversation, the following code shows how we can confirm the booking of a selected room by extending the behavior of the <varname>HotelBookingAction</varname>.
+ </para>
+ <!-- <example>
+ <title>HotelBookingAction.java</title> -->
+ <!-- Can't use code hightlighting with callouts --> <!-- <programlistingco> <areaspec> <area id="nested-booking-end-root" coords="77"/> <area id="nested-booking-confirm" coords="82"/> <area id="nested-booking-cancel" coords="89" /> </areaspec> -->
+ <formalpara><title>HotelBookingAction.java Example</title>
+ <para>
+<programlisting><![CDATA[@Stateful
@Name("hotelBooking")
@Restrict("#{identity.loggedIn}")
-public class HotelBookingAction implements HotelBooking
-{
+public class HotelBookingAction implements HotelBooking {
- @PersistenceContext(type=EXTENDED)
- private EntityManager em;
-
- @In
- private User user;
-
- @In(required=false) @Out
- private Hotel hotel;
-
- @In(required=false)
- @Out(required=false)
- private Booking booking;
-
- @In(required=false)
- private Room roomSelection;
-
- @In
- private FacesMessages facesMessages;
-
- @In
- private Events events;
-
- @Logger
- private Log log;
-
- @Begin
- public void selectHotel(Hotel selectedHotel)
- {
- log.info("Selected hotel #0", selectedHotel.getName());
- hotel = em.merge(selectedHotel);
- }
-
- public String setBookingDates()
- {
- // the result will indicate whether or not to begin the nested conversation
- // as well as the navigation. if a null result is returned, the nested
- // conversation will not begin, and the user will be returned to the current
- // page to fix validation issues
- String result = null;
-
- Calendar calendar = Calendar.getInstance();
- calendar.add(Calendar.DAY_OF_MONTH, -1);
-
- // validate what we have received from the user so far
- if ( booking.getCheckinDate().before( calendar.getTime() ) )
- {
- facesMessages.addToControl("checkinDate", "Check in date must be a future date");
- }
- else if ( !booking.getCheckinDate().before( booking.getCheckoutDate() ) )
- {
- facesMessages.addToControl("checkoutDate", "Check out date must be later than check in date");
- }
- else
- {
- result = "rooms";
- }
-
- return result;
- }
-
- public void bookHotel()
- {
- booking = new Booking(hotel, user);
- Calendar calendar = Calendar.getInstance();
- booking.setCheckinDate( calendar.getTime() );
- calendar.add(Calendar.DAY_OF_MONTH, 1);
- booking.setCheckoutDate( calendar.getTime() );
- }
-
- @End(root=true)
- public void confirm()
- {
- // on confirmation we set the room preference in the booking. the room preference
- // will be injected based on the nested conversation we are in.
- booking.setRoomPreference(roomSelection);
-
- em.persist(booking);
- facesMessages.add("Thank you, #{user.name}, your confimation number for #{hotel.name} is #{booking.id}");
- log.info("New booking: #{booking.id} for #{user.username}");
- events.raiseTransactionSuccessEvent("bookingConfirmed");
- }
-
- @End(root=true, beforeRedirect=true)
- public void cancel() {}
-
- @Destroy @Remove
- public void destroy() {}
-}
-]]></programlisting>
- <calloutlist>
- <callout arearefs="nested-booking-end-root">
- <para>Annotating an action with <link linkend="end-annotation">
- <varname>@End(root=true)</varname>
- </link> ends the root conversation which effectively destroys the entire conversation stack.
- When any conversation is ended, its nested conversations are ended as well. As the root is
- the conversation that started it all, this is a simple way to destroy and release all state
- associated with a workspace once the booking is confirmed.</para>
- </callout>
- <callout arearefs="nested-booking-confirm">
- <para>The <varname>roomSelection</varname> is only associated with the <varname>booking</varname>
- on user confirmation. While outjecting values to the nested conversation context will not
- impact the outer conversation, any objects injected from the outer conversation are injected
- by reference. This means that any changing to these objects will be reflected in the parent
- conversation as well as other concurrent nested conversations.</para>
- </callout>
- <callout arearefs="nested-booking-cancel">
- <para>By simply annotating the cancellation action with <link linkend="end-annotation">
- <varname>@End(root=true, beforeRedirect=true)</varname>
- </link>
- we can easily destroy and release all state associated with the
- workspace prior to redirecting the user back to the hotel selection view.</para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
- <para>Feel free to deploy the application, open many windows or tabs and attempt combinations of various hotels with
-various room preferences. Confirming a booking always results in the correct hotel and room preference thanks to the nested
-conversation model.</para>
- </section>
- </section>
+ @PersistenceContext(type=EXTENDED)
+ private EntityManager em;
+
+ @In
+ private User user;
+
+ @In(required=false) @Out
+ private Hotel hotel;
+
+ @In(required=false)
+ @Out(required=false)
+ private Booking booking;
+
+ @In(required=false)
+ private Room roomSelection;
+
+ @In
+ private FacesMessages facesMessages;
- <section id="dvdstore">
- <title>A complete application featuring Seam and jBPM: the DVD Store example</title>
+ @In
+ private Events events;
+
+ @Logger
+ private Log log;
+
+ @Begin
+ public void selectHotel(Hotel selectedHotel) {
+ log.info("Selected hotel #0", selectedHotel.getName());
+ hotel = em.merge(selectedHotel);
+ }
+
+ public String setBookingDates() {
+ // the result will indicate whether or not to begin the nested conversation
+ // as well as the navigation. if a null result is returned, the nested
+ // conversation will not begin, and the user will be returned to the current
+ // page to fix validation issues
+ String result = null;
- <para> The DVD Store demo application shows the practical usage of jBPM for both task management and pageflow. </para>
+ Calendar calendar = Calendar.getInstance();
+ calendar.add(Calendar.DAY_OF_MONTH, -1);
- <para> The user screens take advantage of a jPDL pageflow to implement searching and shopping cart
- functionality. </para>
+ // validate what we have received from the user so far
+ if ( booking.getCheckinDate().before( calendar.getTime() ) ) {
+ facesMessages.addToControl("checkinDate",
+ "Check in date must be a future date");
+ }
+ else if (!booking.getCheckinDate().before(booking.getCheckoutDate()))
+ {
+ facesMessages.addToControl("checkoutDate",
+ "Check out date must be later than check in date");
+ }
+ else
+ {
+ result = "rooms";
+ }
- <screenshot>
- <screeninfo>DVD Store example</screeninfo>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/dvdsearch.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/dvdsearch.png" align="center"/>
- </imageobject>
- </mediaobject>
- </screenshot>
+ return result;
+ }
+
+ public void bookHotel() {
+ booking = new Booking(hotel, user);
+ Calendar calendar = Calendar.getInstance();
+ booking.setCheckinDate( calendar.getTime() );
+ calendar.add(Calendar.DAY_OF_MONTH, 1);
+ booking.setCheckoutDate( calendar.getTime() );
+ }
+
+ @End(root=true)
+ public void confirm() {
+ // on confirmation we set the room preference in the booking.
+ // the room preference will be injected based on the nested
+ // conversation we are in.
+ booking.setRoomPreference(roomSelection);
- <para> The administration screens take use jBPM to manage the approval and shipping cycle for orders. The
- business process may even be changed dynamically, by selecting a different process definition! </para>
-
- <screenshot>
- <screeninfo>DVD Store example</screeninfo>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/dvdtasks.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/dvdtasks.png" align="center"/>
- </imageobject>
- </mediaobject>
- </screenshot>
-
-
- <para>The Seam DVD Store demo can be run from <literal>dvdstore</literal> directory,
- just like the other demo applications.</para>
-
- </section>
-
-
- <section id="blog">
- <title>Bookmarkable URLs with the Blog example</title>
-
- <para> Seam makes it very easy to implement applications which keep state on the server-side. However,
- server-side state is not always appropriate, especially in for functionality that serves up
- <emphasis>content</emphasis>. For this kind of problem we often want to keep
- application state in the URL so that any page can be accessed at any time through
- a bookmark. The blog example shows how to a implement an
- application that supports bookmarking throughout, even on the search results page. This
- example
- demonstrates how Seam can manage application state in the URL as well as how Seam can rewrite
- those URLs to be even
-
- </para>
-
- <screenshot>
- <screeninfo>Blog example</screeninfo>
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/blog.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/blog.png" align="center"/>
- </imageobject>
- </mediaobject>
- </screenshot>
-
- <para> The Blog example demonstrates the use of "pull"-style MVC, where instead of using action listener methods
- to retrieve data and prepare the data for the view, the view pulls data from components as it is being
- rendered. </para>
-
- <section>
- <title>Using "pull"-style MVC</title>
-
- <para> This snippet from the <literal>index.xhtml</literal> facelets page displays a list of recent blog
- entries: </para>
- <example>
- <title></title>
- <programlisting role="XHTML"><![CDATA[<h:dataTable value="#{blog.recentBlogEntries}" var="blogEntry" rows="3">
- <h:column>
+ em.persist(booking);
+ facesMessages.add("Thank you, #{user.name}, your confimation number " +
+ "for #{hotel.name} is #{booking.id}");
+ log.info("New booking: #{booking.id} for #{user.username}");
+ events.raiseTransactionSuccessEvent("bookingConfirmed");
+ }
+
+ @End(root=true, beforeRedirect=true)
+ public void cancel() {}
+
+ @Destroy @Remove
+ public void destroy() {}
+}]]>
+</programlisting>
+ </para>
+ </formalpara>
+ <formalpara><title>HotelBookingAction.java Explanatory Notes</title>
+ <para>
+ <orderedlist>
+ <listitem>
+ <para>
+ Annotating an action with <literal>@End(root=true)</literal> ends the root conversation, which effectively destroys the entire conversation stack. When any conversation is ended, conversations nested within it are ended as well. Since the root is the original conversation, this is a simple way to destroy and release all state associated with a workspace once the booking is confirmed.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <varname>roomSelection</varname> is only associated with the <varname>booking</varname> upon user confirmation. While outjecting values to the nested conversation context will not impact the external conversation, any objects injected from the external conversation are injected by reference. This means that any changes to these objects will be reflected in the parent conversation as well as other concurrent nested conversations.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ By simply annotating the cancellation action with <literal>@End(root=true, beforeRedirect=true)</literal> we can easily destroy and release all state associated with the workspace prior to redirecting the user back to the hotel selection view.
+ </para>
+ </listitem>
+ </orderedlist>
+ <!-- </programlistingco> -->
+ </para>
+ </formalpara>
+ <!-- </example> -->
+ <para>
+ Feel free to deploy the application and test it yourself. Open many windows or tabs, and attempt combinations of various hotel and room preferences. Confirming a booking will always result in the correct hotel and room preference with the nested conversation model.
+ </para>
+ </section>
+
+ </section>
+
+ <section id="dvdstore">
+ <title>A complete application featuring Seam and jBPM: the DVD Store example</title>
+ <para>
+ The DVD Store demo application shows the practical usage of jBPM for both task management and pageflow.
+ </para>
+ <para>
+ The user screens take advantage of a jPDL pageflow to implement search and shopping cart functionality.
+ </para>
+ <mediaobject>
+ <textobject>
+ <phrase>DVD Store example</phrase>
+ </textobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/dvdsearch.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/dvdsearch.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ The administration screens use jBPM to manage the approval and shipping cycle for orders. The business process can even be changed dynamically by selecting a different process definition.
+ </para>
+ <mediaobject>
+ <textobject>
+ <phrase>DVD Store example</phrase>
+ </textobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/dvdtasks.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/dvdtasks.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ The Seam DVD Store demo can be run from the <filename>dvdstore</filename> directory, as with previous applications.
+ </para>
+ </section>
+
+ <section id="blog">
+ <title>Bookmarkable URLs with the Blog example</title>
+ <para>
+ Seam makes it easy to implement applications which keep state on the server side. However, server-side state is not always appropriate, particularly for functionality that serves up content. For this, application state is often stored as part of the URL, so that any page can be accessed through a bookmark at any time. The blog example shows how to implement an application that supports bookmarking throughout, even on the search results page. This example demonstrates Seam's management of application state in the URL<!-- #modify: as well as, hypothetically, other stuff - original cut off mid-sentence -->.
+ </para>
+ <!-- <para> Seam makes it very easy to implement applications which keep state on the server-side. However, server-side state is not always appropriate, especially for functionality that serves up content. For this kind of problem we often want to keep application state in the URL so that any page can be accessed at any time through a bookmark. The blog example shows how to a implement an application that supports bookmarking throughout, even on the search results page. This example demonstrates how Seam can manage application state in the URL as well as how Seam can rewrite those URLs to be even </para> --> <mediaobject>
+ <textobject>
+ <phrase>Blog example</phrase>
+ </textobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/blog.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/blog.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ The blog example demonstrates the use of "pull"-style model view control (MVC), where the view pulls data from components as it is being rendered rather than using action listener methods to retrieve and prepare data for the view.
+ </para>
+ <section>
+ <title>Using "pull"-style MVC</title>
+ <para>
+ This snippet from the <literal>index.xhtml</literal> facelets page displays a list of recent blog entries:
+ </para>
+ <!-- <example>
+ <title></title> -->
+
+<programlisting role="XHTML"><![CDATA[<h:dataTable value="#{blog.recentBlogEntries}" var="blogEntry" rows="3">
+ <h:column>
<div class="blogEntry">
- <h3>#{blogEntry.title}</h3>
- <div>
- <s:formattedText value="#{blogEntry.excerpt==null ? blogEntry.body : blogEntry.excerpt}"/>
- </div>
- <p>
- <s:link view="/entry.xhtml" rendered="#{blogEntry.excerpt!=null}" propagation="none"
- value="Read more...">
- <f:param name="blogEntryId" value="#{blogEntry.id}"/>
- </s:link>
- </p>
- <p>
- [Posted on 
- <h:outputText value="#{blogEntry.date}">
- <f:convertDateTime timeZone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
- </h:outputText>]
-  
- <s:link view="/entry.xhtml" propagation="none" value="[Link]">
- <f:param name="blogEntryId" value="#{blogEntry.id}"/>
- </s:link>
- </p>
+ <h3>#{blogEntry.title}</h3>
+ <div>
+ <s:formattedText value="#{blogEntry.excerpt==null ?
+ blogEntry.body : blogEntry.excerpt}"/>
+ </div>
+ <p>
+ <s:link view="/entry.xhtml" rendered="#{blogEntry.excerpt!=null}"
+ propagation="none" value="Read more...">
+ <f:param name="blogEntryId" value="#{blogEntry.id}"/>
+ </s:link>
+ </p>
+ <p>
+ [Posted on 
+ <h:outputText value="#{blogEntry.date}">
+ <f:convertDateTime timeZone="#{blog.timeZone}"
+ locale="#{blog.locale}" type="both"/>
+ </h:outputText>]
+  
+ <s:link view="/entry.xhtml" propagation="none" value="[Link]">
+ <f:param name="blogEntryId" value="#{blogEntry.id}"/>
+ </s:link>
+ </p>
</div>
- </h:column>
-</h:dataTable>]]></programlisting>
-</example>
-
-
- <para> If we navigate to this page from a bookmark, how does the <literal>#{blog.recentBlogEntries}</literal>
- data used by the <literal><h:dataTable></literal> actually get initialized?
- The <literal>Blog</literal> is retrieved lazily — "pulled" — when needed, by a Seam
- component named <literal>blog</literal>. This is the opposite flow of control to what is used in
- traditional action-based web frameworks like Struts. </para>
- <example>
- <title></title>
- <!-- Can't use code hightlighting with callouts -->
- <programlistingco>
- <areaspec>
- <area id="blog-seampc" coords="7"/>
- <area id="blog-unwrap" coords="9"/>
- </areaspec>
- <programlisting><![CDATA[@Name("blog")
+ </h:column>
+</h:dataTable>]]>
+</programlisting>
+ <!-- </example> -->
+ <para>
+ If we navigate to this page from a bookmark, the <literal>#{blog.recentBlogEntries}</literal> data used by the <literal><![CDATA[<h:dataTable>]]></literal> is retrieved lazily — "pulled" — when required, by a Seam component named <literal>blog</literal>. This flow of control is the reverse of that used in traditional action-based web frameworks like Struts.
+ </para>
+ <!-- <example>
+ <title></title> -->
+ <!-- Can't use code hightlighting with callouts --> <!-- <programlistingco> <areaspec> <area id="blog-seampc" coords="7"/> <area id="blog-unwrap" coords="9"/> </areaspec> -->
+<programlisting><![CDATA[@Name("blog")
@Scope(ScopeType.STATELESS)
@AutoCreate
-public class BlogService
-{
-
- @In EntityManager entityManager;
+public class BlogService {
- @Unwrap
- public Blog getBlog()
- {
- return (Blog) entityManager.createQuery("select distinct b from Blog b left join fetch b.blogEntries")
- .setHint("org.hibernate.cacheable", true)
- .getSingleResult();
- }
+ @In EntityManager entityManager;
+
+ @Unwrap
+ public Blog getBlog() {
+ return (Blog) entityManager.createQuery(
+ "select distinct b from Blog b left join fetch b.blogEntries")
+ .setHint("org.hibernate.cacheable", true)
+ .getSingleResult();
+ }
-}]]></programlisting>
- <calloutlist>
- <callout arearefs="blog-seampc">
- <para> This component uses a <emphasis>seam-managed persistence context</emphasis>. Unlike
- the other examples we've seen, this persistence context is managed by Seam, instead of
- by the EJB3 container. The persistence context spans the entire web request, allowing us
- to avoid any exceptions that occur when accessing unfetched associations in the view.
- </para>
- </callout>
- <callout arearefs="blog-unwrap">
- <para> The <literal>@Unwrap</literal> annotation tells Seam to provide the return value of
- the method — the <literal>Blog</literal> — instead of the actual
- <literal>BlogService</literal> component to clients. This is the Seam
- <emphasis>manager component pattern</emphasis>. </para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
-
-
- <para> This is good so far, but what about bookmarking the result of form submissions, such as a search
- results page? </para>
-
- </section>
-
- <section>
- <title>Bookmarkable search results page</title>
-
- <para> The blog example has a tiny form in the top right of each page that allows the user to search for
- blog entries. This is defined in a file, <literal>menu.xhtml</literal>, included by the facelets
- template, <literal>template.xhtml</literal>: </para>
- <example>
- <title></title>
- <programlisting role="XHTML"><![CDATA[<div id="search">
- <h:form>
- <h:inputText value="#{searchAction.searchPattern}"/>
- <h:commandButton value="Search" action="/search.xhtml"/>
- </h:form>
-</div>]]></programlisting>
-
-
- <para> To implement a bookmarkable search results page, we need to perform a browser redirect after
- processing the search form submission. Because we used the JSF view id as the action outcome, Seam
- automatically redirects to the view id when the form is submitted. Alternatively, we could have defined
- a navigation rule like this: </para>
-
- <programlisting role="XML"><![CDATA[<navigation-rule>
- <navigation-case>
- <from-outcome>searchResults</from-outcome>
- <to-view-id>/search.xhtml</to-view-id>
- <redirect/>
- </navigation-case>
-</navigation-rule>]]></programlisting>
- </example>
-
- <para> Then the form would have looked like this: </para>
-
- <programlisting role="XHTML"><![CDATA[<div id="search">
- <h:form>
- <h:inputText value="#{searchAction.searchPattern}"/>
- <h:commandButton value="Search" action="searchResults"/>
- </h:form>
-</div>]]></programlisting>
-
-
- <para> But when we redirect, we need to include the values submitted with the form
- in the URL to get a bookmarkable URL like
- <literal>http://localhost:8080/seam-blog/search/</literal>. JSF does not provide
- an easy way to do this, but Seam does. We use two Seam features
- to accomplish this: <emphasis>page parameters</emphasis> and <emphasis>URL rewriting</emphasis>.
- Both are defined in <literal>WEB-INF/pages.xml</literal>: </para>
- <example>
- <title></title>
- <programlisting role="XML"><![CDATA[<pages>
- <page view-id="/search.xhtml">
- <rewrite pattern="/search/{searchPattern}"/>
- <rewrite pattern="/search"/>
+}]]>
+</programlisting>
+ <orderedlist>
+ <listitem>
+ <para>
+ This component uses a <emphasis>Seam-managed persistence context</emphasis>. Unlike previous examples, this persistence context is managed by Seam rather than the EJB3 container. The persistence context spans the entire web request, allowing us to avoid exceptions that may occur when accessing unfetched associations in the view.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>@Unwrap</literal> annotation tells Seam to provide the return value of the method — the <literal>Blog</literal> — instead of the actual <literal>BlogService</literal> component to clients. This is the Seam <emphasis>manager component pattern</emphasis>.
+ </para>
+ </listitem>
+ </orderedlist>
+ <!-- </programlistingco> -->
+ <!-- </example> -->
+ <para>
+ This will store basic view content, but to bookmark form submission results like a search results page, there are several other required definitions.
+ </para>
+ </section>
+
+ <section>
+ <title>Bookmarkable search results page</title>
+ <para>
+ The blog example has a small form at the top right of each page that allows the user to search for blog entries. This is defined in <literal>menu.xhtml</literal>, which is included by the Facelets template <literal>template.xhtml</literal>:
+ </para>
+ <!-- <example>
+ <title></title> -->
+
+<programlisting role="XHTML"><![CDATA[<div id="search">
+ <h:form>
+ <h:inputText value="#{searchAction.searchPattern}"/>
+ <h:commandButton value="Search" action="/search.xhtml"/>
+ </h:form>
+</div>]]>
+</programlisting>
+ <para>
+ To implement a bookmarkable search results page, after the search form submission is processed, we must perform a browser redirect. Because the JSF view ID is used as the action outcome, Seam automatically redirects to the view ID when the form is submitted. We could also have defined a navigation rule as follows:
+ </para>
+
+<programlisting role="XML"><![CDATA[<navigation-rule>
+ <navigation-case>
+ <from-outcome>searchResults</from-outcome>
+ <to-view-id>/search.xhtml</to-view-id>
+ <redirect/>
+ </navigation-case>
+</navigation-rule>]]>
+</programlisting>
+ <!-- </example> -->
+ <para>
+ In that case, the form would have looked like this:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<div id="search">
+ <h:form>
+ <h:inputText value="#{searchAction.searchPattern}"/>
+ <h:commandButton value="Search" action="searchResults"/>
+ </h:form>
+</div>]]>
+</programlisting>
+ <para>
+ However, to get a bookmarkable URL like <literal>http://localhost:8080/seam-blog/search/</literal>, the values submitted with the form must be included in the URL. There is no easy way to do this with JSF, but with Seam, only two features are required: <emphasis>page parameters</emphasis> and <emphasis>URL rewriting</emphasis>. Both are defined here in <literal>WEB-INF/pages.xml</literal>:
+ </para>
+ <!-- <example>
+ <title></title> -->
+
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/search.xhtml">
+ <rewrite pattern="/search/{searchPattern}"/>
+ <rewrite pattern="/search"/>
- <param name="searchPattern" value="#{searchService.searchPattern}"/>
+ <param name="searchPattern" value="#{searchService.searchPattern}"/>
- </page>
+ </page>
...
-</pages>]]></programlisting>
-</example>
-
- <para>
- The page parameter instructs Seam to link the request parameter named <literal>searchPattern</literal>
- to the value of <literal>#{searchService.searchPattern}</literal>, both whenever a request for
- the Search page comes in and whenever a link to the search page is generated. Seam
- takes responsibility for maintaining the link between URL state and application state, and you,
- the developer, don't have to worry about it.</para>
-
- <para>Without URL rewriting, the URL for a search on the term <literal>book</literal>
- would be <literal>http://localhost:8080/seam-blog/seam/search.xhtml?searchPattern=book</literal>.
- This is nice, but Seam can make the URL even simpler using a rewrite rule. The first
- rewrite rule, for the pattern <literal>/search/{searchPattern}</literal>, says that
- any time we have a URL for search.xhtml with a searchPattern request parameter, we can
- fold that URL into the simpler URL. So,the URL we saw earlier,
- <literal>http://localhost:8080/seam-blog/seam/search.xhtml?searchPattern=book</literal>
- can be written instead as <literal>http://localhost:8080/seam-blog/search/book</literal>.
- </para>
-
- <para>Just like with page parameters, URL rewriting is bi-directional. That means that Seam
- forwards requests for the simpler URL to the the right view, and it also automatically generates
- the simpler view for you. You never need to worry about constructing URLs. It's
- all handled transparently behind the scenes. The only requirement is that to use URL rewriting,
- the rewrite filter needs to be enabled in <literal>components.xml</literal>.
- </para>
-
-
- <programlisting><web:rewrite-filter view-mapping="/seam/*" /></programlisting>
-
- <para> The redirect takes us to the <literal>search.xhtml</literal> page: </para>
-
- <programlisting role="XHTML"><![CDATA[<h:dataTable value="#{searchResults}" var="blogEntry">
+</pages>]]>
+</programlisting>
+ <!-- </example> -->
+ <para>
+ The page parameter instructs Seam to link the <literal>searchPattern</literal> request parameter to the value held by <literal>#{searchService.searchPattern}</literal>, whenever the search page is requested, and whenever a link to the search page is generated. Seam takes responsibility for maintaining the link between URL state and application state.
+ </para>
+ <para>
+ The URL for a search on the term <parameter>book</parameter> would ordinarily be <literal>http://localhost:8080/seam-blog/seam/search.xhtml?searchPattern=book</literal>. Seam can simplify this URL by using a rewrite rule. The first rewrite rule, for the pattern <literal>/search/{searchPattern}</literal>, states that whenever a URL for search.xhtml contains a searchPattern request parameter, that URL can be compressed into a simplified URL. So, the earlier URL (<literal>http://localhost:8080/seam-blog/seam/search.xhtml?searchPattern= book</literal>) can instead be written as <literal>http://localhost:8080/seam-blog/search/book</literal>.
+ </para>
+ <para>
+ As with page parameters, rewriting URLs is bidirectional. This means that Seam forwards requests for the simplified URL to the correct view, and it automatically generates the simplified view — users need not construct URLs. The entire process is handled transparently. The only requirement for rewriting URLs is to enable the rewrite filter in <filename>components.xml</filename>:
+ </para>
+
+<programlisting><![CDATA[<web:rewrite-filter view-mapping="/seam/*" />]]>
+</programlisting>
+ <para>
+ The redirect takes us to the <literal>search.xhtml</literal> page:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:dataTable value="#{searchResults}" var="blogEntry">
<h:column>
- <div>
- <s:link view="/entry.xhtml" propagation="none" value="#{blogEntry.title}">
- <f:param name="blogEntryId" value="#{blogEntry.id}"/>
- </s:link>
- posted on
- <h:outputText value="#{blogEntry.date}">
- <f:convertDateTime timeZone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
- </h:outputText>
- </div>
+ <div>
+ <s:link view="/entry.xhtml" propagation="none"
+ value="#{blogEntry.title}">
+ <f:param name="blogEntryId" value="#{blogEntry.id}"/>
+ </s:link>
+ posted on
+ <h:outputText value="#{blogEntry.date}">
+ <f:convertDateTime timeZone="#{blog.timeZone}"
+ locale="#{blog.locale}" type="both"/>
+ </h:outputText>
+ </div>
</h:column>
-</h:dataTable>]]></programlisting>
-
-
- <para> Which again uses "pull"-style MVC to retrieve the actual search results using
- Hibernate Search.</para>
-
- <programlisting role="JAVA"><![CDATA[@Name("searchService")
-public class SearchService
-{
+</h:dataTable>]]>
+</programlisting>
+ <para>
+ Again, this uses "pull"-style MVC to retrieve the search results with Hibernate Search.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("searchService")
+public class SearchService {
- @In
- private FullTextEntityManager entityManager;
+ @In
+ private FullTextEntityManager entityManager;
- private String searchPattern;
+ private String searchPattern;
- @Factory("searchResults")
- public List<BlogEntry> getSearchResults()
- {
- if (searchPattern==null || "".equals(searchPattern) ) {
- searchPattern = null;
- return entityManager.createQuery("select be from BlogEntry be order by date desc").getResultList();
+ @Factory("searchResults")
+ public List<BlogEntry> getSearchResults() {
+ if (searchPattern==null || "".equals(searchPattern) ) {
+ searchPattern = null;
+ return entityManager.createQuery(
+ "select be from BlogEntry be order by date desc").getResultList();
+ }
+ else
+ {
+ Map<String,Float> boostPerField = new HashMap<String,Float>();
+ boostPerField.put( "title", 4f );
+ boostPerField.put( "body", 1f );
+ String[] productFields = {"title", "body"};
+ QueryParser parser = new MultiFieldQueryParser(productFields,
+ new StandardAnalyzer(), boostPerField);
+ parser.setAllowLeadingWildcard(true);
+ org.apache.lucene.search.Query luceneQuery;
+ try
+ {
+ luceneQuery = parser.parse(searchPattern);
}
- else
+ catch (ParseException e)
{
- Map<String,Float> boostPerField = new HashMap<String,Float>();
- boostPerField.put( "title", 4f );
- boostPerField.put( "body", 1f );
- String[] productFields = {"title", "body"};
- QueryParser parser = new MultiFieldQueryParser(productFields, new StandardAnalyzer(), boostPerField);
- parser.setAllowLeadingWildcard(true);
- org.apache.lucene.search.Query luceneQuery;
- try
- {
- luceneQuery = parser.parse(searchPattern);
- }
- catch (ParseException e)
- {
- return null;
- }
+ return null;
+ }
- return entityManager.createFullTextQuery(luceneQuery, BlogEntry.class)
- .setMaxResults(100)
- .getResultList();
+ return entityManager
+ .createFullTextQuery(luceneQuery, BlogEntry.class)
+ .setMaxResults(100)
+ .getResultList();
}
}
@@ -3246,156 +3036,147 @@
this.searchPattern = searchPattern;
}
-}
-]]></programlisting>
-
-
- </section>
-
- <section>
- <title>Using "push"-style MVC in a RESTful application</title>
-
- <para> Very occasionally, it makes more sense to use push-style MVC for processing RESTful pages, and so
- Seam provides the notion of a <emphasis>page action</emphasis>. The Blog example uses a page action for
- the blog entry page, <literal>entry.xhtml</literal>. Note that this is a little bit contrived, it would
- have been easier to use pull-style MVC here as well. </para>
-
- <para> The <literal>entryAction</literal> component works much like an action class in a traditional
- push-MVC action-oriented framework like Struts: </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("entryAction")
+}]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Using "push"-style MVC in a RESTful application</title>
+ <para>
+ Push-style MVC is sometimes used to process RESTful pages, so Seam provides the notion of a <emphasis>page action</emphasis>. The blog example uses a page action for the blog entry page, <filename>entry.xhtml</filename>.
+ </para>
+ <note>
+ <para>
+ We use push-style for the sake of an example, but this particular function would be simpler to implement with pull-style MVC.
+ </para>
+ </note>
+ <para>
+ The <literal>entryAction</literal> component works much like an action class in a traditional push-MVC action-oriented framework like Struts.
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("entryAction")
@Scope(STATELESS)
public class EntryAction
{
- @In Blog blog;
+ @In Blog blog;
+
+ @Out BlogEntry blogEntry;
+
+ public void loadBlogEntry(String id) throws EntryNotFoundException {
+ blogEntry = blog.getBlogEntry(id);
+ if (blogEntry==null) throw new EntryNotFoundException(id);
+ }
- @Out BlogEntry blogEntry;
-
- public void loadBlogEntry(String id) throws EntryNotFoundException
- {
- blogEntry = blog.getBlogEntry(id);
- if (blogEntry==null) throw new EntryNotFoundException(id);
- }
-
-}]]></programlisting>
-
-
- <para> Page actions are also declared in <literal>pages.xml</literal>: </para>
-
- <programlisting role="XML"><![CDATA[<pages>
+}]]>
+</programlisting>
+ <para>
+ Page actions are also declared in <literal>pages.xml</literal>:
+ </para>
+
+<programlisting role="XML"><![CDATA[<pages>
...
- <page view-id="/entry.xhtml">
- <rewrite pattern="/entry/{blogEntryId}" />
- <rewrite pattern="/entry" />
-
- <param name="blogEntryId"
- value="#{blogEntry.id}"/>
-
- <action execute="#{entryAction.loadBlogEntry(blogEntry.id)}"/>
- </page>
+ <page view-id="/entry.xhtml">
+ <rewrite pattern="/entry/{blogEntryId}" />
+ <rewrite pattern="/entry" />
- <page view-id="/post.xhtml" login-required="true">
- <rewrite pattern="/post" />
-
- <action execute="#{postAction.post}"
- if="#{validation.succeeded}"/>
-
- <action execute="#{postAction.invalid}"
- if="#{validation.failed}"/>
-
- <navigation from-action="#{postAction.post}">
- <redirect view-id="/index.xhtml"/>
- </navigation>
- </page>
+ <param name="blogEntryId"
+ value="#{blogEntry.id}"/>
+
+ <action execute="#{entryAction.loadBlogEntry(blogEntry.id)}"/>
+ </page>
+
+ <page view-id="/post.xhtml" login-required="true">
+ <rewrite pattern="/post" />
+
+ <action execute="#{postAction.post}"
+ if="#{validation.succeeded}"/>
+
+ <action execute="#{postAction.invalid}"
+ if="#{validation.failed}"/>
+
+ <navigation from-action="#{postAction.post}">
+ <redirect view-id="/index.xhtml"/>
+ </navigation>
+ </page>
- <page view-id="*">
- <action execute="#{blog.hitCount.hit}"/>
- </page>
+ <page view-id="*">
+ <action execute="#{blog.hitCount.hit}"/>
+ </page>
-</pages>]]></programlisting>
-
-
- <para> Notice that the example is using page actions for post validation
- and the pageview counter. Also notice the use of a parameter in the page action method
- binding. This is not a standard feature of JSF EL, but Seam lets you use it, not just
- for page actions but also in JSF method bindings. </para>
-
- <para> When the <literal>entry.xhtml</literal> page is requested, Seam first binds the page parameter
- <literal>blogEntryId</literal> to the model. Keep in mind that because of the URL rewriting,
- the blogEntryId parameter name won't show up in the URL. Seam then runs the page action, which retrieves
- the needed
- data — the <literal>blogEntry</literal> — and places it in the Seam event context.
- Finally, the following is rendered: </para>
-
- <programlisting role="XHTML"><![CDATA[<div class="blogEntry">
- <h3>#{blogEntry.title}</h3>
- <div>
- <s:formattedText value="#{blogEntry.body}"/>
- </div>
- <p>
- [Posted on 
- <h:outputText value="#{blogEntry.date}">
- <f:convertDateTime timeZone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
- </h:outputText>]
- </p>
-</div>]]></programlisting>
-
-
- <para> If the blog entry is not found in the database, the <literal>EntryNotFoundException</literal>
- exception is thrown. We want this exception to result in a 404 error, not a 505, so we annotate the
- exception class: </para>
-
- <programlisting role="JAVA"><![CDATA[@ApplicationException(rollback=true)
+</pages>]]>
+</programlisting>
+ <note>
+ <para>
+ Note that the example uses page actions for post validation and the pageview counter. Also note the use of a parameter in the page action method binding. This is not a standard JSF EL feature, but Seam allows it both here and in JSF method bindings.
+ </para>
+ </note>
+ <para>
+ When the <filename>entry.xhtml</filename> page is requested, Seam first binds the <literal>blogEntryId</literal> page parameter to the model. Remember that, because of URL rewriting, the blogEntryId parameter name won't appear in the URL. Seam then runs the page action, which retrieves the required data — the <literal>blogEntry</literal> — and places it in the Seam event context. Finally, it renders the following:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<div class="blogEntry">
+ <h3>#{blogEntry.title}</h3>
+ <div>
+ <s:formattedText value="#{blogEntry.body}"/>
+ </div>
+ <p>
+ [Posted on 
+ <h:outputText value="#{blogEntry.date}">
+ <f:convertDateTime timeZone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
+ </h:outputText>]
+ </p>
+</div>]]>
+</programlisting>
+ <para>
+ If the blog entry is not found in the database, the <literal>EntryNotFoundException</literal> exception is thrown. We want this exception to result in a 404 error, not a 505, so we annotate the exception class:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@ApplicationException(rollback=true)
@HttpError(errorCode=HttpServletResponse.SC_NOT_FOUND)
-public class EntryNotFoundException extends Exception
-{
- EntryNotFoundException(String id)
- {
- super("entry not found: " + id);
- }
-}]]></programlisting>
-
-
- <para> An alternative implementation of the example does not use the parameter in the method binding: </para>
-
- <programlisting role="JAVA"><![CDATA[@Name("entryAction")
+public class EntryNotFoundException extends Exception {
+ EntryNotFoundException(String id) {
+ super("entry not found: " + id);
+ }
+}]]>
+</programlisting>
+ <para>
+ An alternative implementation of the example does not use the parameter in the method binding:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Name("entryAction")
@Scope(STATELESS)
-public class EntryAction
-{
- @In(create=true)
- private Blog blog;
-
- @In @Out
- private BlogEntry blogEntry;
-
- public void loadBlogEntry() throws EntryNotFoundException
- {
- blogEntry = blog.getBlogEntry( blogEntry.getId() );
- if (blogEntry==null) throw new EntryNotFoundException(id);
- }
-}]]></programlisting>
-
- <programlisting role="XML"><![CDATA[<pages>
- ...
-
- <page view-id="/entry.xhtml" action="#{entryAction.loadBlogEntry}">
- <param name="blogEntryId" value="#{blogEntry.id}"/>
- </page>
-
- ...
-</pages>]]></programlisting>
-
-
- <para> It is a matter of taste which implementation you prefer. </para>
-
-
- <para>
- The blog demo also demonstrates very simple password authentication, posting to
- the blog, page fragment caching and atom feed generation.
- </para>
- </section>
-
- </section>
-
+public class EntryAction {
+ @In(create=true)
+ private Blog blog;
+
+ @In @Out
+ private BlogEntry blogEntry;
+
+ public void loadBlogEntry() throws EntryNotFoundException {
+ blogEntry = blog.getBlogEntry( blogEntry.getId() );
+ if (blogEntry==null) throw new EntryNotFoundException(id);
+ }
+}]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[<pages>
+ ...
+ <page view-id="/entry.xhtml" action="#{entryAction.loadBlogEntry}">
+ <param name="blogEntryId" value="#{blogEntry.id}"/>
+</page>
+ ...
+</pages>]]>
+</programlisting>
+ <para>
+ The implementation used depends entirely upon personal preference.
+ </para>
+ <para>
+ The blog example also demonstrates very simple password authentication, posting to the blog, page fragment caching and atom feed generation.
+ </para>
+ </section>
+
+ </section>
+
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Validation.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Validation.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Validation.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,226 +1,190 @@
-<chapter id="validation">
- <title>JSF form validation in Seam</title>
- <para>
- In plain JSF, validation is defined in the view:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:form>
- <h:messages/>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- <div>
- Country:
- <h:inputText value="#{location.country}" required="true">
- <my:validateCountry/>
- </h:inputText>
- </div>
-
- <div>
- Zip code:
- <h:inputText value="#{location.zip}" required="true">
- <my:validateZip/>
- </h:inputText>
- </div>
+<chapter id="validation" >
+ <title>JSF form validation in Seam</title>
+ <para>
+ In plain JSF, validation is defined in the view:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:form>
+ <h:messages/>
- <h:commandButton/>
-</h:form>]]></programlisting>
-
- <para>
- In practice, this approach usually violates DRY, since most
- "validation" actually enforces constraints that are part of
- the data model, and exist all the way down to the database
- schema definition. Seam provides support for model-based
- constraints defined using Hibernate Validator.
- </para>
+ <div>
+ Country:
+ <h:inputText value="#{location.country}" required="true">
+ <my:validateCountry/>
+ </h:inputText>
+ </div>
- <para>
- Let's start by defining our constraints, on our
- <literal>Location</literal> class:
- </para>
+ <div>
+ Zip code:
+ <h:inputText value="#{location.zip}" required="true">
+ <my:validateZip/>
+ </h:inputText>
+ </div>
- <programlisting role="JAVA"><![CDATA[public class Location {
- private String country;
- private String zip;
-
- @NotNull
- @Length(max=30)
- public String getCountry() { return country; }
- public void setCountry(String c) { country = c; }
+ <h:commandButton/>
+</h:form>]]>
+</programlisting>
+ <para>
+ In practice, this approach usually violates DRY, since most "validation" actually enforces constraints that are part of the data model, and exist all the way down to the database schema definition. Seam provides support for model-based constraints defined with Hibernate Validator.
+ </para>
+ <para>
+ We will begin by defining our constraints, on our <literal>Location</literal> class:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public class Location {
+ private String country;
+ private String zip;
+
+ @NotNull
+ @Length(max=30)
+ public String getCountry() { return country; }
+ public void setCountry(String c) { country = c; }
- @NotNull
- @Length(max=6)
- @Pattern("^\d*$")
- public String getZip() { return zip; }
- public void setZip(String z) { zip = z; }
-}]]></programlisting>
+ @NotNull
+ @Length(max=6)
+ @Pattern("^\d*$")
+ public String getZip() { return zip; }
+ public void setZip(String z) { zip = z; }
+}]]>
+</programlisting>
+ <para>
+ In practice, it may be more elegant to use custom constraints rather than those built into Hibernate Validator:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[public class Location {
+ private String country;
+ private String zip;
+
+ @NotNull
+ @Country
+ public String getCountry() { return country; }
+ public void setCountry(String c) { country = c; }
- <para>
- Well, that's a decent first cut, but in practice it might be
- more elegant to use custom constraints instead of the ones
- built into Hibernate Validator:
- </para>
+ @NotNull
+ @ZipCode
+ public String getZip() { return zip; }
+ public void setZip(String z) { zip = z; }
+}]]>
+</programlisting>
+ <para>
+ Whichever method we choose, we no longer need specify the validation type to be used in the JSF page. Instead, we use <literal><![CDATA[<s:validate>]]></literal> to validate against the constraint defined on the model object.
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:form>
+ <h:messages/>
- <programlisting role="JAVA"><![CDATA[public class Location {
- private String country;
- private String zip;
+ <div>
+ Country:
+ <h:inputText value="#{location.country}" required="true">
+ <s:validate/>
+ </h:inputText>
+ </div>
- @NotNull
- @Country
- public String getCountry() { return country; }
- public void setCountry(String c) { country = c; }
-
- @NotNull
- @ZipCode
- public String getZip() { return zip; }
- public void setZip(String z) { zip = z; }
-}]]></programlisting>
+ <div>
+ Zip code:
+ <h:inputText value="#{location.zip}" required="true">
+ <s:validate/>
+ </h:inputText>
+ </div>
- <para>
- Whichever route we take, we no longer need to specify the
- type of validation to be used in the JSF page. Instead, we
- can use <literal><s:validate></literal> to validate
- against the constraint defined on the model object.
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:form>
- <h:messages/>
+ <h:commandButton/>
- <div>
- Country:
- <h:inputText value="#{location.country}" required="true">
- <s:validate/>
- </h:inputText>
- </div>
+</h:form>]]>
+</programlisting>
+ <note>
+ <para>
+ Specifying <literal>@NotNull</literal> on the model does <emphasis>not</emphasis> eliminate the need for <literal>required="true"</literal> to appear on the control. This is a limitation of the JSF validation architecture.
+ </para>
+ </note>
+ <para>
+ This approach defines constraints on the model, and presents constraint violations in the view.
+ </para>
+ <para>
+ The design is better, but not much less verbose than our initial design. Now, we will use <literal><![CDATA[<s:validateAll>]]></literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:form>
- <div>
- Zip code:
- <h:inputText value="#{location.zip}" required="true">
- <s:validate/>
- </h:inputText>
- </div>
-
- <h:commandButton/>
+ <h:messages/>
-</h:form>]]></programlisting>
+ <s:validateAll>
- <para>
- <emphasis>Note:</emphasis> specifying <literal>@NotNull</literal>
- on the model does <emphasis>not</emphasis> eliminate the requirement
- for <literal>required="true"</literal> to appear on the control!
- This is due to a limitation of the JSF validation architecture.
- </para>
+ <div>
+ Country:
+ <h:inputText value="#{location.country}" required="true"/>
+ </div>
- <para>
- This approach <emphasis>defines</emphasis> constraints on the model, and
- <emphasis>presents</emphasis> constraint violations in the view — a
- significantly better design.
- </para>
-
- <para>
- However, it is not much less verbose than what we started with,
- so let's try <literal><s:validateAll></literal>:
- </para>
+ <div>
+ Zip code:
+ <h:inputText value="#{location.zip}" required="true"/>
+ </div>
- <programlisting role="XHTML"><![CDATA[<h:form>
-
- <h:messages/>
+ <h:commandButton/>
- <s:validateAll>
+ </s:validateAll>
- <div>
- Country:
- <h:inputText value="#{location.country}" required="true"/>
- </div>
-
- <div>
- Zip code:
- <h:inputText value="#{location.zip}" required="true"/>
- </div>
-
- <h:commandButton/>
-
- </s:validateAll>
-
-</h:form>]]></programlisting>
-
- <para>
- This tag simply adds an <literal><s:validate></literal>
- to every input in the form. For a large form, it can save a lot
- of typing!
- </para>
-
- <para>
- Now we need to do something about displaying feedback to the
- user when validation fails. Currently we are displaying all
- messages at the top of the form. In order for the user to correlate the message with an input, you need to define a label using the standard <literal>label</literal> attribute on the input component.
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:inputText value="#{location.zip}" required="true" label="Zip:">
- <s:validate/>
-</h:inputText>]]></programlisting>
-
- <para>
- You can then inject this value into the message string using
- the placeholder {0} (the first and only parameter passed to a
- JSF message for a Hiberate Validator restriction). See the
- internationalization section for more information regarding
- where to define these messages.
- </para>
-
- <programlisting>validator.length={0} length must be between {min} and {max}</programlisting>
-
- <para>
- What we would really like to do, though, is display the message
- next to the field with the error (this is possible in plain
- JSF), highlight the field and label (this is not possible) and,
- for good measure, display some image next to the field (also
- not possible). We also want to display a little colored
- asterisk next to the label for each required form field. Using
- this approach, the identifying label is not necessary.
- </para>
-
- <para>
- That's quite a lot of functionality we need for each field
- of our form. We wouldn't want to have to specify higlighting
- and the layout of the image, message and input field for every
- field on the form. So, instead, we'll specify the common
- layout in a facelets template:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<ui:composition xmlns="http://www.w3.org/1999/xhtml"
+</h:form>]]>
+</programlisting>
+ <para>
+ This tag adds an <literal><![CDATA[<s:validate>]]></literal> to every input in the form. In a large form, this can save a lot of typing.
+ </para>
+ <para>
+ Next, we need to display feedback to the user when validation fails. Currently, all messages are displayed at the top of the form. To correlate the message with an input, you must define a label by using the standard <literal>label</literal> attribute on the input component.
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:inputText value="#{location.zip}" required="true" label="Zip:">
+ <s:validate/>
+</h:inputText>]]>
+</programlisting>
+ <para>
+ Inject this value into the message string with the placeholder {0} (the first and only parameter passed to a JSF message for a Hiberate Validator restriction). See the internationalization section<!-- #modify: xrefme! --> for more information on where to define these messages.
+ </para>
+
+<programlisting>validator.length={0} length must be between {min} and {max}
+</programlisting>
+ <para>
+ We would prefer the message to be displayed beside the field with the error, highlight the field and label, and display an image next to the field. In plain JSF, only the first is possible. We also want to display a coloured asterisk beside the label of each required form field.
+ </para>
+ <para>
+ This is a lot of functionality for each field. We do not want to specify highlighting and the layout of the image, message, and input field for every field on the form, so we specify the layout in a facelets template:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<ui:composition xmlns="http://www.w3.org/1999/xhtml"
xmlns:ui="http://java.sun.com/jsf/facelets"
xmlns:h="http://java.sun.com/jsf/html"
xmlns:f="http://java.sun.com/jsf/core"
- xmlns:s="http://jboss.com/products/seam/taglib">
-
- <div>
-
- <s:label styleClass="#{invalid?'error':''}">
- <ui:insert name="label"/>
- <s:span styleClass="required" rendered="#{required}">*</s:span>
- </s:label>
+ xmlns:s="http://jboss.com/products/seam/taglib">
+ <div>
+
+ <s:label styleClass="#{invalid?'error':''}">
+ <ui:insert name="label"/>
+ <s:span styleClass="required" rendered="#{required}">*</s:span>
+ </s:label>
- <span class="#{invalid?'error':''}">
- <h:graphicImage value="/img/error.gif" rendered="#{invalid}"/>
- <s:validateAll>
- <ui:insert/>
- </s:validateAll>
- </span>
+ <span class="#{invalid?'error':''}">
+ <h:graphicImage value="/img/error.gif" rendered="#{invalid}"/>
+ <s:validateAll>
+ <ui:insert/>
+ </s:validateAll>
+ </span>
- <s:message styleClass="error"/>
+ <s:message styleClass="error"/>
- </div>
+ </div>
-</ui:composition>]]></programlisting>
-
- <para>
- We can include this template for each of our form fields using
- <literal><s:decorate></literal>.
- </para>
+</ui:composition>]]>
+</programlisting>
+ <para>
+ We can include this template for each of our form fields by using <literal><![CDATA[<s:decorate>]]></literal>:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:form>
+ <h:messages globalOnly="true"/>
- <programlisting role="XHTML"><![CDATA[<h:form>
-
- <h:messages globalOnly="true"/>
-
<s:decorate template="edit.xhtml">
<ui:define name="label">Country:</ui:define>
<h:inputText value="#{location.country}" required="true"/>
@@ -233,88 +197,82 @@
<h:commandButton/>
-</h:form>]]></programlisting>
+</h:form>]]>
+</programlisting>
+ <para>
+ Finally, we can use RichFaces Ajax to display validation messages while the user navigates around the form:
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:form>
+ <h:messages globalOnly="true"/>
- <para>
- Finally, we can use RichFaces Ajax to display validation messages as the user
- is navigating around the form:
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:form>
-
- <h:messages globalOnly="true"/>
-
<s:decorate id="countryDecoration" template="edit.xhtml">
<ui:define name="label">Country:</ui:define>
<h:inputText value="#{location.country}" required="true">
- <a:support event="onblur" reRender="countryDecoration" bypassUpdates="true"/>
+ <a:support event="onblur" reRender="countryDecoration"
+ bypassUpdates="true"/>
</h:inputText>
</s:decorate>
<s:decorate id="zipDecoration" template="edit.xhtml">
<ui:define name="label">Zip code:</ui:define>
<h:inputText value="#{location.zip}" required="true">
- <a:support event="onblur" reRender="zipDecoration" bypassUpdates="true"/>
+ <a:support event="onblur" reRender="zipDecoration"
+ bypassUpdates="true"/>
</h:inputText>
</s:decorate>
<h:commandButton/>
-</h:form>]]></programlisting>
+</h:form>]]>
+</programlisting>
+ <para>
+ Stylistically, it is better to define explicit IDs for important page controls, particularly if you want automated UI testing. If explicit IDs are not provided, JSF will generate its own — but they will not remain static if anything on the page is changed.
+ </para>
+
+<programlisting role="XHTML"><![CDATA[<h:form id="form">
+ <h:messages globalOnly="true"/>
- <para>
- It's better style to define explicit ids for
- important controls on the page, especially if you want to do
- automated testing for the UI, using some toolkit like
- Selenium. If you don't provide explicit ids, JSF will generate
- them, but the generated values will change if you change
- anything on the page.
- </para>
-
- <programlisting role="XHTML"><![CDATA[<h:form id="form">
-
- <h:messages globalOnly="true"/>
-
<s:decorate id="countryDecoration" template="edit.xhtml">
- <ui:define name="label">Country:</ui:define>
- <h:inputText id="country" value="#{location.country}" required="true">
- <a:support event="onblur" reRender="countryDecoration" bypassUpdates="true"/>
- </h:inputText>
+ <ui:define name="label">Country:</ui:define>
+ <h:inputText id="country" value="#{location.country}"
+ required="true">
+ <a:support event="onblur" reRender="countryDecoration"
+ bypassUpdates="true"/>
+ </h:inputText>
</s:decorate>
<s:decorate id="zipDecoration" template="edit.xhtml">
- <ui:define name="label">Zip code:</ui:define>
- <h:inputText id="zip" value="#{location.zip}" required="true">
- <a:support event="onblur" reRender="zipDecoration" bypassUpdates="true"/>
- </h:inputText>
+ <ui:define name="label">Zip code:</ui:define>
+ <h:inputText id="zip" value="#{location.zip}" required="true">
+ <a:support event="onblur" reRender="zipDecoration"
+ bypassUpdates="true"/>
+ </h:inputText>
</s:decorate>
<h:commandButton/>
-</h:form>]]></programlisting>
-
- <para>
- And what if you want to specify a different message to be
- displayed when validation fails? You can use the Seam message
- bundle (and all it's goodies like el expressions inside the message,
- and per-view message bundles) with the Hibernate Validator:
- </para>
-
+</h:form>]]>
+</programlisting>
+ <para>
+ If you want to specify a different message to be displayed when validation fails, you can use the Seam message bundle with the Hibernate Validator:
+ </para>
+
<programlisting role="JAVA"><![CDATA[public class Location {
- private String name;
- private String zip;
-
- // Getters and setters for name
+ private String name;
+ private String zip;
+
+ // Getters and setters for name
- @NotNull
- @Length(max=6)
- @ZipCode(message="#{messages['location.zipCode.invalid']}")
- public String getZip() { return zip; }
- public void setZip(String z) { zip = z; }
-}]]></programlisting>
-
-<programlisting>
-location.zipCode.invalid = The zip code is not valid for #{location.name}
+ @NotNull
+ @Length(max=6)
+ @ZipCode(message="#{messages['location.zipCode.invalid']}")
+ public String getZip() { return zip; }
+ public void setZip(String z) { zip = z; }
+}]]>
</programlisting>
-
+
+<programlisting> location.zipCode.invalid = The zip code is not valid for #{location.name}
+</programlisting>
</chapter>
+
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Webservices.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Webservices.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Webservices.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,206 +1,184 @@
-<chapter id="webservices">
- <title>Web Services</title>
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
- <para>
- Seam integrates with JBossWS to allow standard JEE web services to take full advantage of Seam's contextual framework,
- including support for conversational web services. This chapter walks through the steps required to allow web
- services to run within a Seam environment.
- </para>
-
- <sect1>
- <title>Configuration and Packaging</title>
- <para>
- To allow Seam to intercept web service requests so that the necessary Seam contexts can be created for the request,
- a special SOAP handler must be configured; <literal>org.jboss.seam.webservice.SOAPRequestHandler</literal>
- is a <literal>SOAPHandler</literal> implementation that does the work of managing Seam's lifecycle during the scope
- of a web service request.
- </para>
-
- <para>
- A special configuration file, <literal>standard-jaxws-endpoint-config.xml</literal> should be placed
- into the <literal>META-INF</literal> directory of the <literal>jar</literal> file that contains the
- web service classes. This file contains the following SOAP handler configuration:
- </para>
-
- <programlisting role="XML"><![CDATA[<jaxws-config xmlns="urn:jboss:jaxws-config:2.0"
+<chapter id="webservices" >
+ <title>Web Services</title>
+ <para>
+ Seam integrates with JBossWS (JWS) to allow standard Java EE web services to take full advantage of Seam's contextual framework, including conversational web service support. This chapter guides you through web service configuration for a Seam environment.
+ </para>
+ <section>
+ <title>Configuration and Packaging</title>
+ <para>
+ For Seam to create contexts for web service requests, it must first have access to those requests. <literal>org.jboss.seam.webservice.SOAPRequestHandler</literal> is a <literal>SOAPHandler</literal> implementation that manages the Seam component lifecycle during the scope of a web service request.
+ </para>
+ <para>
+ <filename>standard-jaxws-endpoint-config.xml</filename> (a configuration file) should be placed in the <literal>META-INF</literal> directory of the <filename>JAR</filename> file that contains the web service classes. This file contains the following SOAP handler configuration:
+ </para>
+
+<programlisting role="XML"><![CDATA[<jaxws-config xmlns="urn:jboss:jaxws-config:2.0"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xmlns:javaee="http://java.sun.com/xml/ns/javaee"
- xsi:schemaLocation="urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
- <endpoint-config>
- <config-name>Seam WebService Endpoint</config-name>
- <pre-handler-chains>
- <javaee:handler-chain>
- <javaee:protocol-bindings>##SOAP11_HTTP</javaee:protocol-bindings>
- <javaee:handler>
- <javaee:handler-name>SOAP Request Handler</javaee:handler-name>
- <javaee:handler-class>org.jboss.seam.webservice.SOAPRequestHandler</javaee:handler-class>
- </javaee:handler>
- </javaee:handler-chain>
- </pre-handler-chains>
- </endpoint-config>
-</jaxws-config>]]></programlisting>
-
- </sect1>
-
- <sect1>
- <title>Conversational Web Services</title>
- <para>
- So how are conversations propagated between web service requests? Seam uses a SOAP header element present
- in both the SOAP request and response messages to carry the conversation ID from the consumer to the service,
- and back again. Here's an example of a web service request that contains a conversation ID:
- </para>
+ xsi:schemaLocation=
+ "urn:jboss:jaxws-config:2.0 jaxws-config_2_0.xsd">
+
+ <endpoint-config>
+ <config-name>Seam WebService Endpoint</config-name>
- <programlisting role="XML"><![CDATA[<soapenv:Envelope xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
- xmlns:seam="http://seambay.example.seam.jboss.org/">
+ <pre-handler-chains>
+ <javaee:handler-chain>
+ <javaee:protocol-bindings>
+ ##SOAP11_HTTP
+ </javaee:protocol-bindings>
+ <javaee:handler>
+ <javaee:handler-name>
+ SOAP Request Handler
+ </javaee:handler-name>
+ <javaee:handler-class>
+ org.jboss.seam.webservice.SOAPRequestHandler
+ </javaee:handler-class>
+ </javaee:handler>
+ </javaee:handler-chain>
+
+ </pre-handler-chains>
+
+ </endpoint-config>
+
+</jaxws-config>]]>
+</programlisting>
+ </section>
+
+ <section>
+ <title>Conversational Web Services</title>
+ <para>
+ Seam uses a SOAP header element in both SOAP request and response messages to carry the conversation ID beteen the consumer and the service. One example of a web service request containing a conversation ID is:
+ </para>
+
+<programlisting role="XML"><![CDATA[
+<soapenv:Envelope
+ xmlns:soapenv="http://schemas.xmlsoap.org/soap/envelope/"
+ xmlns:seam="http://seambay.example.seam.jboss.org/">
+
<soapenv:Header>
- <seam:conversationId xmlns:seam='http://www.jboss.org/seam/webservice'>2</seam:conversationId>
+ <seam:conversationId xmlns:seam='http://www.jboss.org/seam/webservice'>
+ 2
+ </seam:conversationId>
</soapenv:Header>
+
<soapenv:Body>
<seam:confirmAuction/>
</soapenv:Body>
+
</soapenv:Envelope>
- ]]></programlisting>
-
- <para>
- As you can see in the above SOAP message, there is a <literal>conversationId</literal> element within the
- SOAP header that contains the conversation ID for the request, in this case <literal>2</literal>.
- Unfortunately, because web services may be consumed by a variety of web service clients written in a
- variety of languages, it is up to the developer to implement conversation ID propagation between individual
- web services that are intended to be used within the scope of a single conversation.
- </para>
-
- <para>
- An important thing to note is that the <literal>conversationId</literal> header element must be qualified
- with a namespace of <literal>http://www.jboss.org/seam/webservice</literal>, otherwise Seam will not be
- able to read the conversation ID from the request. Here's an example of a response to the above request message:
- </para>
-
- <programlisting role="XML"><![CDATA[<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
+ ]]>
+</programlisting>
+ <para>
+ The above SOAP message contains a <literal>conversationId</literal> element, which contains the conversation ID for the request — in this case, <literal>2</literal>. Because web services can be consumed by a variety of web service clients written in a variety of languages, the developer is responsible for implementing conversation ID propagation between individual web services to be used in a single conversation's scope.
+ </para>
+ <para>
+ The <literal>conversationId</literal> header element must be qualified with a namespace of <literal>http://www.jboss.org/seam/webservice</literal>, or Seam will be unable to read the conversation ID from the request. An example response to the above request message is:
+ </para>
+
+<programlisting role="XML"><![CDATA[<env:Envelope xmlns:env='http://schemas.xmlsoap.org/soap/envelope/'>
<env:Header>
- <seam:conversationId xmlns:seam='http://www.jboss.org/seam/webservice'>2</seam:conversationId>
+ <seam:conversationId xmlns:seam='http://www.jboss.org/seam/webservice'>
+ 2
+ </seam:conversationId>
</env:Header>
<env:Body>
- <confirmAuctionResponse xmlns="http://seambay.example.seam.jboss.org/"/>
+ <confirmAuctionResponse
+ xmlns="http://seambay.example.seam.jboss.org/"/>
</env:Body>
-</env:Envelope>
- ]]></programlisting>
-
- <para>
- As you can see, the response message contains the same <literal>conversationId</literal> element as the request.
- </para>
-
- <sect2>
- <title>A Recommended Strategy</title>
-
- <para>
- As web services must be implemented as either a stateless session bean or POJO, it is recommended that for
- conversational web services, the web service acts as a facade to a conversational Seam component.
- </para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/ws-strategy.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/ws-strategy.png" align="center"/>
- </imageobject>
- </mediaobject>
-
- <para>
- If the web service is written as a stateless session bean, then it is also possible to make it a Seam
- component by giving it a <literal>@Name</literal>. Doing this allows Seam's bijection (and other)
- features to be used in the web service class itself.
- </para>
-
- </sect2>
-
- </sect1>
-
- <sect1>
- <title>An example web service</title>
-
- <para>
- Let's walk through an example web service. The code in this section all comes from the seamBay example
- application in Seam's <literal>/examples</literal> directory, and follows the recommended strategy as
- described in the previous section. Let's first take a look at the web service class and one of its web
- service methods:
- </para>
-
- <programlisting role="JAVA"><![CDATA[@Stateless
+</env:Envelope>]]>
+</programlisting>
+ <para>
+ Note that the response message contains the same <literal>conversationId</literal> element as the request.
+ </para>
+ <section>
+ <title>A Recommended Strategy</title>
+ <para>
+ Since web services must be implemented as either stateless session beans or POJOs, we recommend that conversational web services implement the web service as a facade for a conversational Seam component.
+ </para>
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata align="center" fileref="images/ws-strategy.png" format="PNG" scalefit="1" />
+ </imageobject>
+ <imageobject role="html">
+ <imagedata align="center" fileref="images/ws-strategy.png" format="PNG" scalefit="1" />
+ </imageobject>
+ </mediaobject>
+ <para>
+ If the web service is written as a stateless session bean, it can be transformed into a Seam component by annotating it with <literal>@Name</literal>. This allows Seam bijection, and other features, to be used in the web service class itself.
+ </para>
+ </section>
+
+ </section>
+
+ <section>
+ <title>An example web service</title>
+ <para>
+ The example code that follows is from the seamBay example application, which can be found in Seam's <literal>/examples</literal> directory, and follows the recommended strategy outlined in the previous section. First, we will look at the web service class and one of its web service methods:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Stateless
@WebService(name = "AuctionService", serviceName = "AuctionService")
public class AuctionService implements AuctionServiceRemote
{
- @WebMethod
- public boolean login(String username, String password)
- {
- Identity.instance().setUsername(username);
- Identity.instance().setPassword(password);
- Identity.instance().login();
- return Identity.instance().isLoggedIn();
- }
+ @WebMethod
+ public boolean login(String username, String password)
+ {
+ Identity.instance().setUsername(username);
+ Identity.instance().setPassword(password);
+ Identity.instance().login();
+ return Identity.instance().isLoggedIn();
+ }
- // snip
-}]]></programlisting>
+ // snip
+}]]>
+</programlisting>
+ <para>
+ Here, the web service is a stateless session bean annotated with the JWS annotations from the <literal>javax.jws</literal> package, as defined by JSR-181. The <literal>@WebService</literal> annotation tells the container that this class implements a web service. The <literal>@WebMethod</literal> annotation on the <literal>login()</literal> method identifies the method as a web service method. The <literal>name</literal> and <literal>serviceName</literal> attributes in the <literal>@WebService</literal> annotation are optional.
+ </para>
+ <para>
+ When the web service is a stateless session bean, each method that will be exposed as a web service method must also be declared in the remote interface of the web service class. In the previous example, since the <literal>AuctionServiceRemote</literal> interface is annotated as a <literal>@WebService</literal>, it must declare the <literal>login()</literal> method.
+ </para>
+ <para>
+ In the previous example, the web service implements a <literal>login()</literal> method that delegates to Seam's built-in <literal>Identity</literal> component. As our recommended strategy suggests, the web service is written as a simple facade. The real work takes place in a Seam component. This means that business logic is reused efficiently between web services and other clients.
+ </para>
+ <para>
+ In the following example, the web service method begins a new conversation by delegating to the <literal>AuctionAction.createAuction()</literal> method:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@WebMethod
+public void createAuction(String title, String description, int categoryId)
+{
+ AuctionAction action =
+ (AuctionAction) Component.getInstance(AuctionAction.class, true);
+ action.createAuction();
+ action.setDetails(title, description, categoryId);
+}]]>
+</programlisting>
+ <para>
+ The code from <literal>AuctionAction</literal> is as follows:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[@Begin
+public void createAuction()
+{
+ auction = new Auction();
+ auction.setAccount(authenticatedAccount);
+ auction.setStatus(Auction.STATUS_UNLISTED);
+ durationDays = DEFAULT_AUCTION_DURATION;
+}]]>
+</programlisting>
+ <para>
+ Here, we see how web services can participate in long-running conversations by acting as a facade and delegating the real work to a conversational Seam component.
+ </para>
+ </section>
+
+ <section>
+ <title>RESTful HTTP webservices with RESTEasy</title>
- <para>
- As you can see, our web service is a stateless session bean, and is annotated using the JWS annotations
- from the <literal>javax.jws</literal> package, as defined by JSR-181. The <literal>@WebService</literal>
- annotation tells the container that this class implements a web service, and the <literal>@WebMethod</literal>
- annotation on the <literal>login()</literal> method identifies the method as a web service method.
- The <literal>name</literal> and <literal>serviceName</literal> attributes in the <literal>@WebService</literal>
- annotation are optional.
- </para>
-
- <para>
- As is required by the specification, each method that is to be exposed as a web service method must also be
- declared in the remote interface of the web service class (when the web service is a stateless session bean).
- In the above example, the <literal>AuctionServiceRemote</literal> interface must declare the <literal>login()</literal>
- method as it is annotated as a <literal>@WebMethod</literal>.
- </para>
-
- <para>
- As you can see in the above code, the web service implements a <literal>login()</literal> method that
- delegates to Seam's built-in <literal>Identity</literal> component. In keeping with our recommended strategy,
- the web service is written as a simple facade, passing off the real work to a Seam component. This allows
- for the greatest reuse of business logic between web services and other clients.
- </para>
-
- <para>
- Let's look at another example. This web service method begins a new conversation by delegating to the
- <literal>AuctionAction.createAuction()</literal> method:
- </para>
-
- <programlisting role="JAVA"><![CDATA[ @WebMethod
- public void createAuction(String title, String description, int categoryId)
- {
- AuctionAction action = (AuctionAction) Component.getInstance(AuctionAction.class, true);
- action.createAuction();
- action.setDetails(title, description, categoryId);
- }]]></programlisting>
-
- <para>
- And here's the code from <literal>AuctionAction</literal>:
- </para>
-
- <programlisting role="JAVA"><![CDATA[ @Begin
- public void createAuction()
- {
- auction = new Auction();
- auction.setAccount(authenticatedAccount);
- auction.setStatus(Auction.STATUS_UNLISTED);
- durationDays = DEFAULT_AUCTION_DURATION;
- }]]></programlisting>
-
- <para>
- From this we can see how web services can participate in long running conversations, by acting as a facade
- and delegating the real work to a conversational Seam component.
- </para>
-
- </sect1>
-
- <sect1>
- <title>RESTful HTTP webservices with RESTEasy</title>
-
<para>
Seam integrates the RESTEasy implementation of the JAX-RS specification (JSR 311). You can decide how
"deep" the integration into your Seam application is going to be:
@@ -215,8 +193,8 @@
</listitem>
<listitem>
<para>
- Serving HTTP/REST requests with the SeamResourceServlet, no external servlet or configuration in
- web.xml required.
+ Serving HTTP/REST requests with the <classname>SeamResourceServlet</classname>, no external servlet or configuration in
+ <filename>web.xml</filename> required.
</para>
</listitem>
<listitem>
@@ -226,13 +204,13 @@
</listitem>
</itemizedlist>
- <sect2>
+ <section>
<title>RESTEasy configuration and request serving</title>
<para>
- First, get the RESTEasy libraries and the <literal>jaxrs-api.jar</literal>, deploy them with the
+ First, get the RESTEasy libraries and the <filename>jaxrs-api.jar</filename> and deploy them with the
other libraries of your application. Also deploy the integration library,
- <literal>jboss-seam-resteasy.jar</literal>.
+ <filename>jboss-seam-resteasy.jar</filename>.
</para>
<para>
@@ -250,34 +228,34 @@
</listitem>
<listitem>
<para>
- Then the pattern mapped in <literal>web.xml</literal> for the <literal>SeamResourceServlet</literal>,
- e.g <literal>/seam/resource</literal> if you follow the common examples, is appended.
+ Then the pattern mapped in <filename>web.xml</filename> for the <classname>SeamResourceServlet</classname>,
+ for example, <filename>/seam/resource</filename> if you follow the common examples, is appended.
Change this setting to expose your RESTful resources under a different base.
- Note that this is a global change and other Seam resources (e.g. <literal>s:graphicImage</literal>)
+ Note that this is a global change and other Seam resources (for example, <literal>s:graphicImage</literal>)
are then also served under that base path.
</para>
</listitem>
<listitem>
<para>
The RESTEasy integration for Seam then appends a configurable string to the base path, by default
- this is <literal>/rest</literal>. Hence, the full base path of your resources would e.g. be
- <literal>/myapp/seam/resource/rest</literal>. We recommend that you change this string in your application,
+ this is <filename>/rest</filename>. Hence, the full base path of your resources would e.g. be
+ <filename>/myapp/seam/resource/rest</filename>. We recommend that you change this string in your application,
you could for example add a version number to prepare for a future REST API upgrade of your services
- (old clients would keep the old URI base): <literal>/myapp/seam/resource/restv1</literal>.
+ (old clients would keep the old URI base): <filename>/myapp/seam/resource/restv1</filename>.
</para>
</listitem>
<listitem>
<para>
- Finally, the actual resource is available under the defined <literal>@Path</literal>, e.g. a resource
+ Finally, the actual resource is available under the defined <literal>@Path</literal>, for example, a resource
mapped with <literal>@Path("/customer")</literal> would be available under
- <literal>/myapp/seam/resource/rest/customer</literal>.
+ <filename>/myapp/seam/resource/rest/customer</filename>.
</para>
</listitem>
</itemizedlist>
<para>
As an example, the following resource definition would return a plaintext representation for any
- GET requests using the URI <literal>http://your.hostname/myapp/seam/resource/rest/customer/123</literal>:
+ GET requests using the URI <filename>http://your.hostname/myapp/seam/resource/rest/customer/123</filename>:
</para>
<programlisting role="JAVA"><![CDATA[@Path("/customer")
@@ -309,13 +287,13 @@
http://jboss.com/products/seam/components-2.2.xsd">]]></programlisting>
<para>
- You can then change the <literal>/rest</literal> prefix as mentioned earlier:
+ You can then change the <filename>/rest</filename> prefix as mentioned earlier:
</para>
<programlisting role="XML"><![CDATA[<resteasy:application resource-path-prefix="/restv1"/>]]></programlisting>
<para>
- The full base path to your resources is now <literal>/myapp/seam/resource/restv1/{resource}</literal> - note
+ The full base path to your resources is now <filename>/myapp/seam/resource/restv1/{resource}</filename> - note
that your <literal>@Path</literal> definitions and mappings do NOT change. This is an application-wide
switch usually used for versioning of the HTTP interface.
</para>
@@ -351,8 +329,8 @@
<para>
RESTEasy supports plain EJBs (EJBs that are not Seam components) as resources. Instead of configuring the
- JNDI names in a non-portable fashion in <literal>web.xml</literal> (see RESTEasy documentation), you can
- simply list the EJB implementation classes, not the business interfaces, in <literal>components.xml</literal>
+ JNDI names in a non-portable fashion in <filename>web.xml</filename> (see RESTEasy documentation), you can
+ simply list the EJB implementation classes, not the business interfaces, in <filename>components.xml</filename>
as shown above. Note that you have to annotate the <literal>@Local</literal> interface of the EJB with
<literal>@Path</literal>, <literal>@GET</literal>, and so on - not the bean implementation class. This allows
you to keep your application deployment-portable with the global Seam <literal>jndi-pattern</literal> switch
@@ -384,9 +362,9 @@
<literal>text/plain</literal> and <literal>de-DE</literal>.
</para>
- </sect2>
+ </section>
- <sect2>
+ <section>
<title>Resources as Seam components</title>
<para>
@@ -512,14 +490,14 @@
</para>
</note>
- </sect2>
+ </section>
- <sect2>
+ <section>
<title>Securing resources</title>
<para>
You can enable the Seam authentication filter for HTTP Basic and Digest authentication in
- <literal>components.xml</literal>:
+ <filename>components.xml</filename>:
</para>
<programlisting role="XML"><![CDATA[<web:authentication-filter url-pattern="/seam/resource/rest/*" auth-type="basic"/>]]></programlisting>
@@ -535,22 +513,22 @@
regular Seam security features for authorization are available.
</para>
- </sect2>
+ </section>
- <sect2>
+ <section>
<title>Mapping exceptions to HTTP responses</title>
<para>
Section 3.3.4 of the JAX-RS specification defines how checked or unchecked exceptions are handled by the
JAX RS implementation. In addition to using an exception mapping provider as defined by JAX-RS, the integration
- of RESTEasy with Seam allows you to map exceptions to HTTP response codes within Seam's <literal>pages.xml</literal>
- facility. If you are already using <literal>pages.xml</literal> declarations, this is easier to maintain than
+ of RESTEasy with Seam allows you to map exceptions to HTTP response codes within Seam's <filename>pages.xml</filename>
+ facility. If you are already using <filename>pages.xml</filename> declarations, this is easier to maintain than
potentially many JAX RS exception mapper classes.
</para>
<para>
Exception handling within Seam requires that the Seam filter is executed for your HTTP request. Ensure that
- you do filter <emphasis>all</emphasis> requests in your <literal>web.xml</literal>, not - as
+ you do filter <emphasis>all</emphasis> requests in your <filename>web.xml</filename>, not - as
some Seam examples might show - a request URI pattern that doesn't cover your REST request paths.
The following example intercepts <emphasis>all</emphasis> HTTP requests and enables Seam exception handling:
</para>
@@ -568,7 +546,7 @@
<para>
To convert the unchecked <literal>UnsupportedOperationException</literal> thrown by your resource
methods to a <literal>501 Not Implemented</literal> HTTP status response, add the following to your
- <literal>pages.xml</literal> descriptor:
+ <filename>pages.xml</filename> descriptor:
</para>
<programlisting role="XML"><![CDATA[<exception class="java.lang.UnsupportedOperationException">
@@ -591,18 +569,18 @@
You do not have to send an HTTP error to the client if an exception occurs. Seam allows you to map the
exception as a redirect to a view of your Seam application. As this feature is typically used for human
clients (web browsers) and not for REST API remote clients, you should pay extra attention to conflicting
- exception mappings in <literal>pages.xml</literal>.
+ exception mappings in <filename>pages.xml</filename>.
</para>
<para>
Note that the HTTP response still passes through the servlet container, so an additional mapping might apply
- if you have <literal><error-page></literal> mappings in your <literal>web.xml</literal> configuration.
+ if you have <literal><error-page></literal> mappings in your <filename>web.xml</filename> configuration.
The HTTP status code would then be mapped to a rendered HTML error page with status <literal>200 OK</literal>!
</para>
- </sect2>
+ </section>
- <sect2>
+ <section>
<title>Exposing entities via RESTful API</title>
<para>
@@ -613,7 +591,7 @@
(<xref linkend="framework"/>). These components allow you to bind domain model entity classes to an HTTP API.
</para>
- <sect3>
+ <section>
<title>ResourceQuery</title>
<para>
@@ -640,13 +618,13 @@
</listitem>
<listitem>
<para>
- The component will handle HTTP requests on the URI path <literal>/user</literal>.
+ The component will handle HTTP requests on the URI path <filename>/user</filename>.
</para>
</listitem>
<listitem>
<para>
The component will by default transform the data into XML or JSON (based on client's preference).
- The set of supported mime types can be altered by using the <literal>media-types</literal> attribute,
+ The set of supported mime types can be altered by using the <varname>media-types</varname> attribute,
for example:
</para>
</listitem>
@@ -710,9 +688,9 @@
</para>
</note>
- </sect3>
+ </section>
- <sect3>
+ <section>
<title>ResourceHome</title>
@@ -722,43 +700,44 @@
</para>
<table>
- <tgroup cols='4'>
- <thead>
- <row>
- <entry>HTTP method</entry>
- <entry>Path</entry>
- <entry>Function</entry>
- <entry>ResourceHome method</entry>
- </row>
- </thead>
- <tbody>
- <row>
- <entry>GET</entry>
- <entry>{path}/{id}</entry>
- <entry>Read</entry>
- <entry>getResource()</entry>
- </row>
- <row>
- <entry>POST</entry>
- <entry>{path}</entry>
- <entry>Create</entry>
- <entry>postResource()</entry>
- </row>
- <row>
- <entry>PUT</entry>
- <entry>{path}/{id}</entry>
- <entry>Update</entry>
- <entry>putResource()</entry>
- </row>
- <row>
- <entry>DELETE</entry>
- <entry>{path}/{id}</entry>
- <entry>Delete</entry>
- <entry>deleteResource()</entry>
- </row>
- </tbody>
- </tgroup>
- </table>
+ <title>Bindings in ResourceHome</title>
+ <tgroup cols='4'>
+ <thead>
+ <row>
+ <entry>HTTP method</entry>
+ <entry>Path</entry>
+ <entry>Function</entry>
+ <entry>ResourceHome method</entry>
+ </row>
+ </thead>
+ <tbody>
+ <row>
+ <entry>GET</entry>
+ <entry>{path}/{id}</entry>
+ <entry>Read</entry>
+ <entry>getResource()</entry>
+ </row>
+ <row>
+ <entry>POST</entry>
+ <entry>{path}</entry>
+ <entry>Create</entry>
+ <entry>postResource()</entry>
+ </row>
+ <row>
+ <entry>PUT</entry>
+ <entry>{path}/{id}</entry>
+ <entry>Update</entry>
+ <entry>putResource()</entry>
+ </row>
+ <row>
+ <entry>DELETE</entry>
+ <entry>{path}/{id}</entry>
+ <entry>Delete</entry>
+ <entry>deleteResource()</entry>
+ </row>
+ </tbody>
+ </tgroup>
+ </table>
<itemizedlist>
<listitem>
@@ -768,7 +747,7 @@
</listitem>
<listitem>
<para>
- Sending a POST request to <literal>/user</literal> creates a new user entity instance and persists it.
+ Sending a POST request to <filename>/user</filename> creates a new user entity instance and persists it.
Usually, you leave it up to the persistence layer to provide the entity instance with an identifier
value and thus an URI. Therefore, the URI is sent back to the client in the
<literal>Location</literal> header of the HTTP response.
@@ -811,11 +790,11 @@
for testing purposes.
</para>
- </sect3>
+ </section>
- </sect2>
+ </section>
- <sect2>
+ <section>
<title>Testing resources and providers</title>
<para>
@@ -874,7 +853,7 @@
<para>
This test only executes local calls, it does not communicate with the <literal>SeamResourceServlet</literal>
through TCP. The mock request is passed through the Seam servlet and filters and the response is then
- available for test assertions. Overriding the <literal>getDefaultHeaders()</literal> method in a shared
+ available for test assertions. Overriding the <methodname>getDefaultHeaders()</methodname> method in a shared
instance of <literal>ResourceRequestEnvironment</literal> allows you to set request headers for every
test method in the test class.
</para>
@@ -885,8 +864,7 @@
such as <literal>@BeforeClass</literal>.
</para>
- </sect2>
-
- </sect1>
-
+ </section>
+
+ </section>
</chapter>
Modified: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Xml.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Xml.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/Xml.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,597 +1,573 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+<?xml version='1.0' encoding='utf-8' ?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
+]>
-<chapter id="xml">
-
- <title>Configuring Seam components</title>
-
- <para>
- The philosophy of minimizing XML-based configuration is extremely strong in Seam. Nevertheless,
- there are various reasons why we might want to configure a Seam component using XML: to isolate
- deployment-specific information from the Java code, to enable the creation of re-usable frameworks,
- to configure Seam's built-in functionality, etc.
- Seam provides two basic approaches to configuring components: configuration via property settings in a
- properties file or in <literal>web.xml</literal>, and configuration via <literal>components.xml</literal>.
- </para>
-
- <section>
- <title>Configuring components via property settings</title>
- <para>
- Seam components may be provided with configuration properties either via servlet context parameters, via
- system properties, or via a properties file named <literal>seam.properties</literal> in the root of the classpath.
- </para>
- <para>
- The configurable Seam component must expose 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, a system
- property named <literal>org.jboss.seam.properties.com.jboss.myapp.settings.locale</literal> via -D at startup, 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>, <literal>seam.properties</literal>, or via a system property prefixed with
- <literal>org.jboss.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>
- </section>
-
- <section id="xml.descriptor">
- <title>Configuring components via <literal>components.xml</literal></title>
-
- <para>
- The <literal>components.xml</literal> file is a bit more powerful than property settings. It lets
- you:
- </para>
-
- <itemizedlist>
- <listitem>
- <para> Configure components that have been installed automatically — including both built-in
- components, and application components that have been annotated with the
- <literal>@Name</literal> annotation and picked up by Seam's deployment scanner. </para>
- </listitem>
- <listitem>
- <para> Install classes with no <literal>@Name</literal> annotation as Seam components — this
- is most useful for certain kinds of infrastructural components which can be installed multiple
- times with different names (for example Seam-managed persistence contexts). </para>
- </listitem>
- <listitem>
- <para> Install components that <emphasis>do</emphasis> have a <literal>@Name</literal> annotation
- but are not installed by default because of an <literal>@Install</literal> annotation that
- indicates the component should not be installed. </para>
- </listitem>
- <listitem>
- <para> Override the scope of a component. </para>
- </listitem>
- </itemizedlist>
-
- <para>
- A <literal>components.xml</literal> file may appear in one of three different places:
- </para>
-
- <itemizedlist>
- <listitem>
- <para>The <literal>WEB-INF</literal> directory of a <literal>war</literal>.</para>
- </listitem>
- <listitem>
- <para>The <literal>META-INF</literal> directory of a <literal>jar</literal>.</para>
- </listitem>
- <listitem>
- <para>
- Any directory of a <literal>jar</literal> that contains classes with an
- <literal>@Name</literal> annotation.
- </para>
- </listitem>
- </itemizedlist>
-
- <para>
- Usually, Seam components are installed when the deployment scanner discovers a class with a
- <literal>@Name</literal> annotation sitting in an archive with a <literal>seam.properties</literal>
- file or a <literal>META-INF/components.xml</literal> file. (Unless the component has an
- <literal>@Install</literal> annotation indicating it should not be installed by default.)
- 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 jBPM:
- </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xmlns:bpm="http://jboss.com/products/seam/bpm">
- <bpm:jbpm/>
-</components>]]></programlisting>
-
- <para>
- This example does the same thing:
- </para>
-
- <programlisting role="XML"><![CDATA[<components>
- <component class="org.jboss.seam.bpm.Jbpm"/>
-</components>]]></programlisting>
-
- <para>
- This one installs and configures two different Seam-managed persistence contexts:
- </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+<chapter id="xml" >
+ <title>Configuring Seam components</title>
+ <para>
+ Seam aims to minimize the need for XML-based configuration. However, there are various reasons you might want to configure Seam components with XML: to isolate deployment-specific information from the Java code, to enable the creation of reuseable frameworks, to configure Seam's built-in functionality, etc. Seam provides two basic approaches to component configuration: via property settings in a properties file or <filename>web.xml</filename>, and via <filename>components.xml</filename>.
+ </para>
+ <section>
+ <title>Configuring components via property settings</title>
+ <para>
+ You can provide Seam with configuration properties with either servlet context parameters (in system properties), or with a properties file named <filename>seam.properties</filename> in the root of the classpath.
+ </para>
+ <para>
+ The configurable Seam component must expose JavaBean-style property setter methods for the configurable attributes. That is, if a Seam component named <literal>com.jboss.myapp.settings</literal> has a setter method named <literal>setLocale()</literal>, we can provide either:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ a property named <literal>com.jboss.myapp.settings.locale</literal> in the <filename>seam.properties</filename> file,
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ a system property named <literal>org.jboss.seam.properties.com.jboss.myapp.settings.locale</literal> via <command>-D</command> at startup, or
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ the same system property as a Servlet context parameter.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Any of these will set the value of the <literal>locale</literal> attribute in the root of the class path.
+ </para>
+ <para>
+ The same mechanism is used to configure Seam itself. For example, to set conversation timeout, we provide a value for <literal>org.jboss.seam.core.manager.conversationTimeout</literal> in <literal>web.xml</literal>, <literal>seam.properties</literal>, or via a system property prefixed with <literal>org.jboss.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>
+ </section>
+
+ <section id="xml.descriptor">
+ <title>Configuring components via <filename>components.xml</filename></title>
+ <para>
+ The <filename>components.xml</filename> file is more powerful than property settings. It lets you:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ configure components that have been installed automatically, including built-in components, and application components that have been annotated with <literal>@Name</literal> 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 infrastructural components which can be installed multiple times with different names (for example, Seam-managed persistence contexts).
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ install components that do 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 <filename>components.xml</filename> file appears in one of three locations:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ The <literal>WEB-INF</literal> directory of a <filename>WAR</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ The <literal>META-INF</literal> directory of a <filename>JAR</filename>.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Any <filename>JAR</filename> directory containing classes with a <literal>@Name</literal> annotation.
+ </para>
+ </listitem>
+ </itemizedlist>
+ <para>
+ Seam components are installed when the deployment scanner discovers a class with a <literal>@Name</literal> annotation in an archive with a <filename>seam.properties</filename> file, or a <filename>META-INF/components.xml</filename> file, unless the component also has an <literal>@Install</literal> annotation indicating that it should not be installed by default. The <filename>components.xml</filename> file handles special cases where the annotations must be overridden.
+ </para>
+ <para>
+ For example, the following <filename>components.xml</filename> file installs jBPM:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xmlns:bpm="http://jboss.com/products/seam/bpm">
+ <bpm:jbpm/>
+</components>]]>
+</programlisting>
+ <para>
+ The following example also installs jBPM:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components>
+ <component class="org.jboss.seam.bpm.Jbpm"/>
+</components>]]>
+</programlisting>
+ <para>
+ This example installs and configures two different Seam-managed persistence contexts:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
xmlns:persistence="http://jboss.com/products/seam/persistence"
<persistence:managed-persistence-context name="customerDatabase"
- persistence-unit-jndi-name="java:/customerEntityManagerFactory"/>
+ persistence-unit-jndi-name="java:/customerEntityManagerFactory"/>
<persistence:managed-persistence-context name="accountingDatabase"
- persistence-unit-jndi-name="java:/accountingEntityManagerFactory"/>
+ persistence-unit-jndi-name="java:/accountingEntityManagerFactory"/>
-</components>]]></programlisting>
-
- <para>
- As does this one:
- </para>
-
- <programlisting role="XML"><![CDATA[<components>
- <component name="customerDatabase"
- class="org.jboss.seam.persistence.ManagedPersistenceContext">
- <property name="persistenceUnitJndiName">java:/customerEntityManagerFactory</property>
- </component>
+</components>]]>
+</programlisting>
+ <para>
+ This example also installs and configures two different Seam-managed persistence contexts:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components>
+ <component name="customerDatabase"
+ class="org.jboss.seam.persistence.ManagedPersistenceContext">
+ <property name="persistenceUnitJndiName">
+ java:/customerEntityManagerFactory
+ </property>
+ </component>
- <component name="accountingDatabase"
- class="org.jboss.seam.persistence.ManagedPersistenceContext">
- <property name="persistenceUnitJndiName">java:/accountingEntityManagerFactory</property>
- </component>
-</components>]]></programlisting>
-
- <para>
- This example creates a session-scoped Seam-managed persistence context (this is not recommended in
- practice):
- </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+ <component name="accountingDatabase"
+ class="org.jboss.seam.persistence.ManagedPersistenceContext">
+ <property name="persistenceUnitJndiName">
+ java:/accountingEntityManagerFactory
+ </property>
+ </component>
+</components>]]>
+</programlisting>
+ <para>
+ The following examples create a session-scoped Seam-managed persistence context. (This is not recommended in practice.)
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
xmlns:persistence="http://jboss.com/products/seam/persistence"
- <persistence:managed-persistence-context name="productDatabase"
- scope="session"
- persistence-unit-jndi-name="java:/productEntityManagerFactory"/>
+ <persistence:managed-persistence-context
+ name="productDatabase" scope="session"
+ persistence-unit-jndi-name="java:/productEntityManagerFactory"/>
-</components>]]></programlisting>
-
- <programlisting role="XML"><![CDATA[<components>
+</components>]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[<components>
- <component name="productDatabase"
- scope="session"
- class="org.jboss.seam.persistence.ManagedPersistenceContext">
- <property name="persistenceUnitJndiName">java:/productEntityManagerFactory</property>
- </component>
+ <component name="productDatabase" scope="session"
+ class="org.jboss.seam.persistence.ManagedPersistenceContext">
+ <property name="persistenceUnitJndiName">
+ java:/productEntityManagerFactory
+ </property>
+ </component>
-</components>]]></programlisting>
-
- <para>
- It is common to use the <literal>auto-create</literal> option for infrastructural
- objects like persistence contexts, which saves you from having to explicitly
- specify <literal>create=true</literal> when you use the <literal>@In</literal>
- annotation.
- </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+</components>]]>
+</programlisting>
+ <para>
+ The <literal>auto-create</literal> option is commonly used for infrastructural objects such as persistence contexts, removing the need to specify <literal>create=true</literal> explicitly when using the <literal>@In</literal> annotation.
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
xmlns:persistence="http://jboss.com/products/seam/persistence"
- <persistence:managed-persistence-context name="productDatabase"
- auto-create="true"
- persistence-unit-jndi-name="java:/productEntityManagerFactory"/>
+ <persistence:managed-persistence-context
+ name="productDatabase" auto-create="true"
+ persistence-unit-jndi-name="java:/productEntityManagerFactory"/>
-</components>]]></programlisting>
-
- <programlisting role="XML"><![CDATA[<components>
+</components>]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[<components>
- <component name="productDatabase"
- auto-create="true"
- class="org.jboss.seam.persistence.ManagedPersistenceContext">
- <property name="persistenceUnitJndiName">java:/productEntityManagerFactory</property>
- </component>
+ <component name="productDatabase"
+ auto-create="true"
+ class="org.jboss.seam.persistence.ManagedPersistenceContext">
+ <property name="persistenceUnitJndiName">
+ java:/productEntityManagerFactory
+ </property>
+ </component>
-</components>]]></programlisting>
+</components>]]>
+</programlisting>
+ <para>
+ The <literal><![CDATA[<factory>]]></literal> declaration specifies a value- or method-binding expression that will initialize the value of a context variable when it is first referenced.
+ </para>
+
+<programlisting role="XML"><![CDATA[<components>
+ <factory name="contact" method="#{contactManager.loadContact}"
+ scope="CONVERSATION"/>
+</components>]]>
+</programlisting>
+ <para>
+ You can create an <emphasis>alias</emphasis> (a second name) for a Seam component like so:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components>
+ <factory name="user" value="#{actor}" scope="STATELESS"/>
+</components>]]>
+</programlisting>
+ <para>
+ You can even create an alias for a commonly used expression:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components>
+ <factory name="contact" value="#{contactManager.contact}"
+ scope="STATELESS"/>
+</components>]]>
+</programlisting>
+ <para>
+ <literal>auto-create="true"</literal> is often used with the <literal><![CDATA[<factory>]]></literal> declaration:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components>
+ <factory name="session" value="#{entityManager.delegate}"
+ scope="STATELESS" auto-create="true"/>
+</components>]]>
+</programlisting>
+ <para>
+ The same <filename>components.xml</filename> file is sometimes used (with minor changes) during both deployment and testing. Seam allows wildcards of the form <literal>@wildcard@</literal> to be placed in <filename>components.xml</filename>, which can be replaced at deployment time by either your Ant build script, or providing a file named <filename>components.properties</filename> in the classpath. (The latter approach appears in the Seam examples.)
+ </para>
+ </section>
+
+ <section>
+ <title>Fine-grained configuration files</title>
+ <para>
+ If a large number of components require XML configuration, it is sensible to split <filename>components.xml</filename> into several smaller files. With Seam, configuration for a class named <literal>com.helloworld.Hello</literal> can be placed in a resource named <literal>com/helloworld/Hello.component.xml</literal>. (This pattern is also used in Hibernate.) The root element of the file may either be a <literal><![CDATA[<components>]]></literal> or <literal><![CDATA[<component>]]></literal> element.
+ </para>
+ <para>
+ <literal><![CDATA[<components>]]></literal> lets you define multiple components in the file:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components>
- <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 role="XML"><![CDATA[<components>
-
- <factory name="contact" method="#{contactManager.loadContact}" scope="CONVERSATION"/>
-
-</components>]]></programlisting>
-
- <para>
- You can create an "alias" (a second name) for a Seam component like so:
- </para>
-
- <programlisting role="XML"><![CDATA[<components>
-
- <factory name="user" value="#{actor}" scope="STATELESS"/>
-
-</components>]]></programlisting>
-
- <para>
- You can even create an "alias" for a commonly used expression:
- </para>
-
- <programlisting role="XML"><![CDATA[<components>
-
- <factory name="contact" value="#{contactManager.contact}" scope="STATELESS"/>
-
-</components>]]></programlisting>
-
- <para>
- It is especially common to see the use of <literal>auto-create="true"</literal> with the
- <literal><factory></literal> declaration:
- </para>
-
- <programlisting role="XML"><![CDATA[<components>
-
- <factory name="session" value="#{entityManager.delegate}" scope="STATELESS" auto-create="true"/>
-
-</components>]]></programlisting>
-
- <para>
- Sometimes we want to reuse the same <literal>components.xml</literal> file with minor changes during
- both deployment and testing. Seam lets 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>
-
- </section>
-
- <section>
- <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.xml</literal> into many small files. Seam lets
- you put configuration for a class named, for example, <literal>com.helloworld.Hello</literal> in a
- resource named <literal>com/helloworld/Hello.component.xml</literal>. (You might be familiar with this
- pattern, since it is the same one we use in Hibernate.) The root element of the file may be either a
- <literal><components></literal> or <literal><component></literal>
- element. </para>
-
- <para>
- The first option lets you define multiple components in the file:
- </para>
-
- <programlisting role="XML"><![CDATA[<components>
- <component class="com.helloworld.Hello" name="hello">
- <property name="name">#{user.name}</property>
- </component>
- <factory name="message" value="#{hello.message}"/>
-</components>]]></programlisting>
-
- <para>
- The second option only lets you define or configure one component, but is less noisy:
- </para>
-
- <programlisting role="XML"><![CDATA[<component name="hello">
+ <component class="com.helloworld.Hello" name="hello">
<property name="name">#{user.name}</property>
-</component>]]></programlisting>
+ </component>
+ <factory name="message" value="#{hello.message}"/>
+
+</components>]]>
+</programlisting>
+ <para>
+ <literal><![CDATA[<component>]]></literal> only lets you configure one component, but is less verbose:
+ </para>
+
+<programlisting role="XML"><![CDATA[<component name="hello">
+ <property name="name">#{user.name}</property>
+</component>]]>
+</programlisting>
+ <para>
+ The class name in the latter 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>
+ </section>
+
+ <section>
+ <title>Configurable property types</title>
+ <para>
+ Properties of string, primitive or primitive wrapper type are configured as follows:
+ </para>
+
+<programlisting><![CDATA[org.jboss.seam.core.manager.conversationTimeout 60000]]></programlisting>
- <para>
- In the second option, the class name is implied by the file in which the component definition
- appears.
- </para>
+<programlisting role="XML"><![CDATA[<core:manager conversation-timeout="60000"/>]]></programlisting>
+<programlisting role="XML"><![CDATA[<component name="org.jboss.seam.core.manager">
+ <property name="conversationTimeout">60000</property>
+</component>]]>
+</programlisting>
+ <para>
+ Arrays, sets, and lists of strings or primitives are also supported:
+ </para>
+
+<programlisting><![CDATA[org.jboss.seam.bpm.jbpm.processDefinitions
+order.jpdl.xml,
+return.jpdl.xml,
+inventory.jpdl.xml]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[<bpm:jbpm>
+ <bpm:process-definitions>
+ <value>order.jpdl.xml</value>
+ <value>return.jpdl.xml</value>
+ <value>inventory.jpdl.xml</value>
+ </bpm:process-definitions>
+</bpm:jbpm>]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[<component name="org.jboss.seam.bpm.jbpm">
- <para>
- Alternatively, you may put configuration for all classes in the <literal>com.helloworld</literal>
- package in <literal>com/helloworld/components.xml</literal>.
- </para>
- </section>
+ <property name="processDefinitions">
+ <value>order.jpdl.xml</value>
+ <value>return.jpdl.xml</value>
+ <value>inventory.jpdl.xml</value>
+ </property>
+
+</component>]]>
+</programlisting>
+ <para>
+ Even maps with String-valued keys and string or primitive values are supported:
+ </para>
+
+<programlisting role="XML"><![CDATA[<component name="issueEditor">
- <section>
- <title>Configurable property types</title>
- <para>
- Properties of string, primitive or primitive wrapper type may be configured just as you would expect:
- </para>
+ <property name="issueStatuses">
+ <key>open</key> <value>open issue</value>
+ <key>resolved</key> <value>issue resolved by developer</value>
+ <key>closed</key> <value>resolution accepted by user</value>
+ </property>
+
+</component>]]>
+</programlisting>
+ <para>
+ When configuring multi-valued properties, Seam preserves the order of attributes set out in <filename>components.xml</filename> by default, unless <literal>SortedSet</literal>/<literal>SortedMap</literal> are used, in which case Seam refers to <literal>TreeMap</literal>/<literal>TreeSet</literal>. If the property has a concrete type (<literal>LinkedList</literal>, for example) Seam will use that type.
+ </para>
+ <para>
+ You can also override the type by specifying a fully qualified class name:
+ </para>
+
+<programlisting role="XML"><![CDATA[<component name="issueEditor">
- <programlisting><![CDATA[org.jboss.seam.core.manager.conversationTimeout 60000]]></programlisting>
-
- <programlisting role="XML"><![CDATA[<core:manager conversation-timeout="60000"/>]]></programlisting>
-
- <programlisting role="XML"><![CDATA[<component name="org.jboss.seam.core.manager">
- <property name="conversationTimeout">60000</property>
-</component>]]></programlisting>
-
- <para>
- Arrays, sets and lists of strings or primitives are also supported:
- </para>
-
- <programlisting><![CDATA[org.jboss.seam.bpm.jbpm.processDefinitions order.jpdl.xml, return.jpdl.xml, inventory.jpdl.xml]]></programlisting>
-
- <programlisting role="XML"><![CDATA[<bpm:jbpm>
- <bpm:process-definitions>
- <value>order.jpdl.xml</value>
- <value>return.jpdl.xml</value>
- <value>inventory.jpdl.xml</value>
- </bpm:process-definitions>
-</bpm:jbpm>]]></programlisting>
-
- <programlisting role="XML"><![CDATA[<component name="org.jboss.seam.bpm.jbpm">
- <property name="processDefinitions">
- <value>order.jpdl.xml</value>
- <value>return.jpdl.xml</value>
- <value>inventory.jpdl.xml</value>
- </property>
-</component>]]></programlisting>
-
- <para>
- Even maps with String-valued keys and string or primitive values are supported:
- </para>
-
- <programlisting role="XML"><![CDATA[<component name="issueEditor">
- <property name="issueStatuses">
- <key>open</key> <value>open issue</value>
- <key>resolved</key> <value>issue resolved by developer</value>
- <key>closed</key> <value>resolution accepted by user</value>
- </property>
-</component>]]></programlisting>
-
- <para>
- When configuring multi-valued properties, by default, Seam will preserve the order in which you place the attributes
- in <literal>components.xml</literal> (unless you use a <literal>SortedSet</literal>/<literal>SortedMap</literal>
- then Seam will use <literal>TreeMap</literal>/<literal>TreeSet</literal>). If the property has a concrete type (for
- example <literal>LinkedList</literal>) Seam will use that type.
- </para>
- <para>
- You can also override the type by specifying a fully qualified class name:
- </para>
-
- <programlisting role="XML"><![CDATA[<component name="issueEditor">
- <property name="issueStatusOptions" type="java.util.LinkedHashMap">
- <key>open</key> <value>open issue</value>
- <key>resolved</key> <value>issue resolved by developer</value>
- <key>closed</key> <value>resolution accepted by user</value>
- </property>
-</component>]]></programlisting>
-
- <para>
- Finally, you may wire together components using a value-binding expression. Note that this is quite
- different to injection using <literal>@In</literal>, since it happens at component instantiation time
- instead of invocation time. It is therefore much more similar to the dependency injection facilities
- offered by traditional IoC containers like JSF or Spring.
- </para>
-
-
- <programlisting role="XML"><![CDATA[<drools:managed-working-memory name="policyPricingWorkingMemory"
- rule-base="#{policyPricingRules}"/>]]></programlisting>
-
- <programlisting role="XML"><![CDATA[<component name="policyPricingWorkingMemory"
- class="org.jboss.seam.drools.ManagedWorkingMemory">
- <property name="ruleBase">#{policyPricingRules}</property>
-</component>]]></programlisting>
-
- <para>
- Seam also resolves an EL expression string prior to assigning the initial value to the bean property of
- the component. So you can inject some contextual data into your components.
- </para>
-
- <programlisting role="XML"><![CDATA[<component name="greeter" class="com.example.action.Greeter">
- <property name="message">Nice to see you, #{identity.username}!</property>
-</component>]]></programlisting>
-
- <para>
- However, there is one important exception. If the type of the property to which the initial value is
- being assigned is either a Seam <literal>ValueExpression</literal> or
- <literal>MethodExpression</literal>, then the evaluation of the EL is deferred. Instead, the appropriate
- expression wrapper is created and assigned to the property. The message templates on the Home component
- from the Seam Application Framework serve as an example.
- </para>
-
- <programlisting role="XML"><![CDATA[<framework:entity-home name="myEntityHome"
- class="com.example.action.MyEntityHome" entity-class="com.example.model.MyEntity"
- created-message="'#{myEntityHome.instance.name}' has been successfully added."/>]]></programlisting>
-
- <para>
- Inside the component, you can access the expression string by calling
- <literal>getExpressionString()</literal> on the <literal>ValueExpression</literal> or
- <literal>MethodExpression</literal>. If the property is a <literal>ValueExpression</literal>, you can
- resolve the value using <literal>getValue()</literal> and if the property is a
- <literal>MethodExpression</literal>, you can invoke the method using <literal>invoke(Object
- args...)</literal>. Obviously, to assign a value to a <literal>MethodExpression</literal> property, the
- entire initial value must be a single EL expression.
- </para>
-
- </section>
-
- <section>
- <title>Using XML Namespaces</title>
- <para>
- Throughout the examples, there have been two competing ways of declaring components: with and without
- the use of XML namespaces. The following shows a typical <literal>components.xml</literal> file
- without namespaces:
- </para>
-
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+ <property name="issueStatusOptions" type="java.util.LinkedHashMap">
+ <key>open</key> <value>open issue</value>
+ <key>resolved</key> <value>issue resolved by developer</value>
+ <key>closed</key> <value>resolution accepted by user</value>
+ </property>
+
+</component>]]>
+</programlisting>
+ <para>
+ Finally, you can link components with a value-binding expression. Note that since this occurs upon component instantiation, not invocation, this is quite different to injection with <literal>@In</literal>. It is more similar to the dependency injection facilities offered by traditional Inversion of Control containers such as JavaServer Faces (JSF) or Spring.
+ </para>
+
+<programlisting role="XML"><![CDATA[<drools:managed-working-memory name="policyPricingWorkingMemory"
+ rule-base="#{policyPricingRules}"/>]]>
+</programlisting>
+
+<programlisting role="XML"><![CDATA[<component name="policyPricingWorkingMemory"
+ class="org.jboss.seam.drools.ManagedWorkingMemory">
+ <property name="ruleBase">#{policyPricingRules}</property>
+</component>]]>
+</programlisting>
+ <para>
+ Seam also resolves EL expression strings prior to assigning the initial value to the bean property of the component, so some contextual data can be injected into components:
+ </para>
+
+<programlisting role="XML"><![CDATA[<component name="greeter" class="com.example.action.Greeter">
+ <property name="message">
+ Nice to see you, #{identity.username}!
+ </property>
+</component>]]>
+</programlisting>
+ <para>
+ However, there is one important exception: if the initial value is assigned to either a Seam <literal>ValueExpression</literal> or <literal>MethodExpression</literal>, then the evaluation of the EL is deferred, and the appropriate expression wrapper is created and assigned to the property. The message templates on the <literal>Home</literal> component of the Seam Application Framework are a good example of this:
+ </para>
+
+<programlisting role="XML"><![CDATA[<framework:entity-home name="myEntityHome"
+ class="com.example.action.MyEntityHome"
+ entity-class="com.example.model.MyEntity"
+ created-message="'#{myEntityHome.instance.name}'
+ has been successfully added."/>]]>
+</programlisting>
+ <para>
+ Within the component, you can access the expression string by calling <literal>getExpressionString()</literal> on either <literal>ValueExpression</literal> or <literal>MethodExpression</literal>. If the property is a <literal>ValueExpression</literal>, resolve the value with <literal>getValue()</literal>. If the property is a <literal>MethodExpression</literal>, invoke the method with <literal>invoke({Object arguments})</literal>. To assign a value to a <literal>MethodExpression</literal> property, the entire initial value must be a single EL expression.
+ </para>
+ </section>
+
+ <section>
+ <title>Using XML Namespaces</title>
+ <para>
+ Previous examples have alternated between two component declaration methods: with and without using XML namespaces. The following shows a typical <filename>components.xml</filename> file that does not use namespaces:
+ </para>
+
+<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://jboss.com/products/seam/components"
- xsi:schemaLocation="http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.2.xsd">
+ xsi:schemaLocation=
+ "http://jboss.com/products/seam/components
+ http://jboss.com/products/seam/components-2.2.xsd">
- <component class="org.jboss.seam.core.init">
- <property name="debug">true</property>
- <property name="jndiPattern">@jndiPattern@</property>
- </component>
+ <component class="org.jboss.seam.core.init">
+ <property name="debug">true</property>
+ <property name="jndiPattern">@jndiPattern@</property>
+ </component>
-</components>]]></programlisting>
-
- <para>
- As you can see, this is somewhat verbose. Even worse, the component and attribute names cannot be
- validated at development time.
- </para>
-
- <para>The namespaced version looks like this:</para>
-
- <programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
+</components>]]>
+</programlisting>
+ <para>
+ As you can see, this code is verbose. More importantly, the component and attribute names cannot be validated at development time.
+ </para>
+ <para>
+ Using namespaces gives us:
+ </para>
+
+<programlisting role="XML"><![CDATA[<?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-2.2.xsd
- http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.2.xsd">
+ "http://jboss.com/products/seam/core
+ http://jboss.com/products/seam/core-2.2.xsd
+ http://jboss.com/products/seam/components
+ http://jboss.com/products/seam/components-2.2.xsd">
- <core:init debug="true" jndi-pattern="@jndiPattern@"/>
+ <core:init debug="true" jndi-pattern="@jndiPattern@"/>
-</components>]]></programlisting>
-
- <para>
- Even though the schema declarations are verbose, 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 autocomplete. The use of namespaced elements makes generating and
- maintaining correct <literal>components.xml</literal> files much simpler.
- </para>
-
- <para>
- Now, this works great for the built-in Seam components, but what about user components? There are two options.
- First, Seam supports mixing the two models, allowing the use of the generic <literal><component></literal>
- declarations for user components, along with namespaced declarations for built-in components. But even better,
- Seam allows you to quickly declare namespaces for your own components.
- </para>
-
- <para>
- Any Java package can be associated with an XML namespace by annotating the package with the
- <literal>@Namespace</literal> annotation. (Package-level annotations are declared in a file named
- <literal>package-info.java</literal> in the package directory.) Here is an example from the seampay demo:
- </para>
-
- <programlisting role="JAVA">@Namespace(value="http://jboss.com/products/seam/examples/seampay")
-package org.jboss.seam.example.seampay;
-
-import org.jboss.seam.annotations.Namespace;</programlisting>
-
- <para>
- That is all you need to do to use the namespaced style in <literal>components.xml</literal>!
- Now we can write:
- </para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+</components>]]>
+</programlisting>
+ <para>
+ Although the schema declarations are verbose, the XML content itself is lean and easy to understand. The schemas provide detailed information about each component and the available attributes, allowing XML editors to offer intelligent auto-completion. Using namespaced elements makes it easier to generate and maintain correct <filename>components.xml</filename> files.
+ </para>
+ <para>
+ This works well for built-in Seam components, but for user components there are two available options. First, Seam supports mixing both models, allowing the use of generic <literal><![CDATA[<component>]]></literal> declarations for user components, and namespaced declarations for built-in components. More importantly, Seam lets you quickly declare namespaces for your own components.
+ </para>
+ <para>
+ Any Java package can be associated with an XML namespace by annotating the package with <literal>@Namespace</literal>. (Package-level annotations are declared in a file named <literal>package-info.java</literal> in the package directory.) An example of this from the seampay demo is:
+ </para>
+
+<programlisting role="JAVA">@Namespace(value="http://jboss.com/products/seam/examples/ seampay") package org.jboss.seam.example.seampay; import org.jboss.seam.annotations.Namespace;
+</programlisting>
+ <para>
+ Using the namespaced style in <filename>components.xml</filename> is that simple. Now we can write:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
xmlns:pay="http://jboss.com/products/seam/examples/seampay"
... >
- <pay:payment-home new-instance="#{newPayment}"
- created-message="Created a new payment to #{newPayment.payee}" />
+ <pay:payment-home 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}" />
+ <pay:payment name="newPayment"
+ payee="Somebody"
+ account="#{selectedAccount}"
+ payment-date="#{currentDatetime}"
+ created-date="#{currentDatetime}" />
...
-</components>]]></programlisting>
-
- <para>Or:</para>
-
- <programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
+</components>]]>
+</programlisting>
+ <para>
+ Or:
+ </para>
+
+<programlisting role="XML"><![CDATA[<components xmlns="http://jboss.com/products/seam/components"
xmlns:pay="http://jboss.com/products/seam/examples/seampay"
... >
- <pay:payment-home>
- <pay:new-instance>"#{newPayment}"</pay:new-instance>
- <pay:created-message>Created a new payment to #{newPayment.payee}</pay:created-message>
- </pay:payment-home>
+ <pay:payment-home>
+ <pay:new-instance>"#{newPayment}"</pay:new-instance>
+ <pay:created-message>
+ Created a new payment to #{newPayment.payee}
+ </pay:created-message>
+ </pay:payment-home>
- <pay:payment name="newPayment">
- <pay:payee>Somebody"</pay:payee>
- <pay:account>#{selectedAccount}</pay:account>
- <pay:payment-date>#{currentDatetime}</pay:payment-date>
- <pay:created-date>#{currentDatetime}</pay:created-date>
- </pay:payment>
- ...
-</components>]]></programlisting>
-
- <para>
- These examples illustrate the two usage models of a namespaced element. In the first declaration,
- the <literal><pay:payment-home></literal> references the <literal>paymentHome</literal>
- component:
- </para>
-
- <programlisting role="JAVA"><![CDATA[package org.jboss.seam.example.seampay;
+ <pay:payment name="newPayment">
+ <pay:payee>Somebody"</pay:payee>
+ <pay:account>#{selectedAccount}</pay:account>
+ <pay:payment-date>#{currentDatetime}</pay:payment-date>
+ <pay:created-date>#{currentDatetime}</pay:created-date>
+ </pay:payment>
+ ...
+</components>]]>
+</programlisting>
+ <para>
+ The previous examples illustrate the two usage models of a namespaced element. In the first declaration, <literal><![CDATA[<pay:payment-home>]]></literal> references the <literal>paymentHome</literal> component:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[package org.jboss.seam.example.seampay;
...
@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 are
- the hyphenated form of the property names.
- </para>
-
- <para>
- In the second declaration, the <literal><pay:payment></literal> element refers to the
- <literal>Payment</literal> class in the <literal>org.jboss.seam.example.seampay</literal> package.
- In this case <literal>Payment</literal> is an entity that is being declared as a Seam component:
- </para>
-
- <programlisting role="JAVA"><![CDATA[package org.jboss.seam.example.seampay;
+public class PaymentController extends EntityHome<Payment> {
+ ...
+}]]>
+</programlisting>
+ <para>
+ The element name is the hyphenated form of the component name. The attributes of the element are the hyphenated forms of the property names.
+ </para>
+ <para>
+ In the second declaration, the <literal><![CDATA[<pay:payment>]]></literal> element refers to the <literal>Payment</literal> class in the <literal>org.jboss.seam.example.seampay</literal> package. In this case, <literal>Payment</literal> is an entity that is being declared as a Seam component:
+ </para>
+
+<programlisting role="JAVA"><![CDATA[package org.jboss.seam.example.seampay;
...
@Entity
-public class Payment
- implements Serializable
-{
- ...
-}]]></programlisting>
-
- <para>
- If we want validation and autocompletion to work for user-defined components, we will need a schema.
- Seam does not yet provide a mechanism to automatically generate a schema for a set of components, so
- it is necessary to generate one manually. The schema definitions for the standard Seam packages can
- be used for guidance.
- </para>
-
- <para>The following are the the namespaces used by Seam:</para>
-
- <itemizedlist>
- <listitem>
- <para>components — <literal>http://jboss.com/products/seam/components</literal></para>
- </listitem>
- <listitem>
- <para>core — <literal>http://jboss.com/products/seam/core</literal></para>
- </listitem>
- <listitem>
- <para>drools — <literal>http://jboss.com/products/seam/drools</literal></para>
- </listitem>
- <listitem>
- <para>framework — <literal>http://jboss.com/products/seam/framework</literal></para>
- </listitem>
- <listitem>
- <para>jms — <literal>http://jboss.com/products/seam/jms</literal></para>
- </listitem>
- <listitem>
- <para>remoting — <literal>http://jboss.com/products/seam/remoting</literal></para>
- </listitem>
- <listitem>
- <para>theme — <literal>http://jboss.com/products/seam/theme</literal></para>
- </listitem>
- <listitem>
- <para>security — <literal>http://jboss.com/products/seam/security</literal></para>
- </listitem>
- <listitem>
- <para>mail — <literal>http://jboss.com/products/seam/mail</literal></para>
- </listitem>
- <listitem>
- <para>web — <literal>http://jboss.com/products/seam/web</literal></para>
- </listitem>
- <listitem>
- <para>pdf — <literal>http://jboss.com/products/seam/pdf</literal></para>
- </listitem>
- <listitem>
- <para> spring — <literal>http://jboss.com/products/seam/spring</literal></para>
- </listitem>
-
- </itemizedlist>
-
- </section>
-
-
+public class Payment implements Serializable {
+ ...
+}]]>
+</programlisting>
+ <para>
+ A schema is required for validation and auto-completion to work for user-defined components. Seam cannot yet generate a schema for a set of components automatically, so schema must be manually created. You can use schema definitions for standard Seam packages for guidance.
+ </para>
+ <para>
+ The following are the the namespaces used by Seam:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ components — <literal>http://jboss.com/products/seam/components</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ core — <literal>http://jboss.com/products/seam/core</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ drools — <literal>http://jboss.com/products/seam/drools</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ framework — <literal>http://jboss.com/products/seam/framework</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ jms — <literal>http://jboss.com/products/seam/jms</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ remoting — <literal>http://jboss.com/products/seam/remoting</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ theme — <literal>http://jboss.com/products/seam/theme</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ security — <literal>http://jboss.com/products/seam/security</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ mail — <literal>http://jboss.com/products/seam/mail</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ web — <literal>http://jboss.com/products/seam/web</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ pdf — <literal>http://jboss.com/products/seam/pdf</literal>
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ spring — <literal>http://jboss.com/products/seam/spring</literal>
+ </para>
+ </listitem>
+ </itemizedlist>
+ </section>
+
</chapter>
+
Deleted: branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/master.xml
===================================================================
--- branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/master.xml 2010-05-25 10:35:05 UTC (rev 12793)
+++ branches/enterprise/JBPAPP_5_0/doc/Seam_Reference_Guide/en-US/master.xml 2010-05-25 14:38:51 UTC (rev 12794)
@@ -1,43 +0,0 @@
-<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd" [ ]>
-
-<book>
- <xi:include href="Book_Info.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Preface.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Tutorial.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Gettingstarted.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Getting_Started_With_JBoss_Tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Concepts.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Xml.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Events.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Conversations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Jbpm.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Persistence.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Validation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Groovy.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Framework.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Drools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Security.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="I18n.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Text.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Itext.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Excel.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Mail.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Jms.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Cache.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Webservices.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Remoting.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Gwt.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Spring.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Hsearch.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Configuration.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Annotations.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Components.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Controls.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Elenhancements.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="ClusteringAndEJBPassivation.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Performance.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Testing.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Tools.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
- <xi:include href="Dependencies.xml" xmlns:xi="http://www.w3.org/2001/XInclude" />
-</book>
More information about the seam-commits
mailing list