[jboss-cvs] JBossAS SVN: r92718 - projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US.
jboss-cvs-commits at lists.jboss.org
jboss-cvs-commits at lists.jboss.org
Sun Aug 23 20:58:29 EDT 2009
Author: irooskov at redhat.com
Date: 2009-08-23 20:58:29 -0400 (Sun, 23 Aug 2009)
New Revision: 92718
Added:
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Migration.xml
Modified:
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Annotations.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Clustering_EJBPassivation.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Components.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Concepts.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Configuration.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Controls.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Conversations.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Dependencies.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Drools.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Events.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Framework.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Gettingstarted.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Groovy.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Gwt.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Hsearch.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/I18n.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Itext.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Jbpm.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Jms.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Mail.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Performance.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Persistence.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Remoting.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Seam_Reference_Guide.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Security.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Spring.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Testing.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Text.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Tutorial.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Validation.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Webservices.xml
projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Xml.xml
Log:
adding in Laura's edit with new chapter and revised editing of the community version
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Annotations.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Annotations.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Annotations.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -53,12 +53,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>name</literal> — the context variable name.
+ <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.
+ <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>
@@ -119,7 +119,7 @@
</para>
<warning>
<para>
- This is ill-defined, since it implies that a component will be visible only for a specific part of a request cycle. This is not a recommended application feature.
+ 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>
@@ -131,18 +131,18 @@
<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.
+ 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) @Startup]]>
</programlisting>
<para>
- Specifies that a session scope component is started immediately at session creation time.
+ 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.
+ <literal>depends</literal> — specifies that the named components must be started first, if they are installed.
</para>
</listitem>
</itemizedlist>
@@ -184,27 +184,27 @@
<itemizedlist>
<listitem>
<para>
- <literal>BUILT_IN</literal> — precedence of all built-in Seam components.
+ <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.
+ <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).
+ <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.
+ <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.
+ <literal>MOCK</literal> — precedence for mock objects used in testing.
</para>
</listitem>
</itemizedlist>
@@ -288,17 +288,17 @@
<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>.
+ <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>.
+ <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.
+ <literal>required</literal> — specifies that Seam should throw an exception if the context variable is undefined in all contexts.
</para>
</listitem>
</itemizedlist>
@@ -337,12 +337,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>value</literal> — specifies the name of the context variable. Default to the name of the component attribute.
+ <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.
+ <literal>required</literal> — specifies that Seam should throw an exception if the component attribute is null during outjection.
</para>
</listitem>
</itemizedlist>
@@ -393,17 +393,17 @@
<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.
+ <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.
+ <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>.
+ <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>
@@ -426,7 +426,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>value</literal> — specifies the name of the log category. Defaults to the name of the component class.
+ <literal>value</literal> — specifies the name of the log category. Defaults to the name of the component class.
</para>
</listitem>
</itemizedlist>
@@ -449,7 +449,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>value</literal> — specifies the name of the request parameter. Defaults to the name of the component attribute.
+ <literal>value</literal> — specifies the name of the request parameter. Defaults to the name of the component attribute.
</para>
</listitem>
</itemizedlist>
@@ -554,22 +554,22 @@
<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.
+ <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.
+ <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.
+ <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>.
+ <literal>pageflow</literal> — the name of a jBPM process definition deployed via <literal>org.jboss.seam.bpm.jbpm.pageflowDefinitions</literal>.
</para>
</listitem>
</itemizedlist>
@@ -587,12 +587,12 @@
<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.
+ <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.
+ <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>
@@ -615,12 +615,12 @@
</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.
+ <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.
+ <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>
@@ -643,12 +643,12 @@
</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.
+ <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.
+ <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>
@@ -667,17 +667,17 @@
<programlisting role="JAVA"><![CDATA[@EndTask(transition="transitionName")]]>
</programlisting>
<para>
- Triggers the given jBPM transition.
+ 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.
+ <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.
+ <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>
@@ -695,7 +695,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>definition</literal> — the name of the jBPM process definition deployed via <literal>org.jboss.seam.bpm.jbpm.processDefinitions</literal>.
+ <literal>definition</literal> — the name of the jBPM process definition deployed via <literal>org.jboss.seam.bpm.jbpm.processDefinitions</literal>.
</para>
</listitem>
</itemizedlist>
@@ -713,7 +713,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>processIdParameter</literal> — the name of the request parameter that holds the process ID. Defaults to <literal>"processId"</literal>.
+ <literal>processIdParameter</literal> — the name of the request parameter that holds the process ID. Defaults to <literal>"processId"</literal>.
</para>
</listitem>
</itemizedlist>
@@ -750,7 +750,7 @@
</para>
<note>
<para>
- This annotation should not be used on EJB3 components — use <literal>@TransactionAttribute</literal> instead.
+ This annotation should not be used on EJB3 components — use <literal>@TransactionAttribute</literal> instead.
</para>
</note>
</listitem>
@@ -762,22 +762,22 @@
<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.
+ 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.
+ 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.
+ <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.
+ <literal>end</literal> — by default <literal>false</literal>, if <literal>true</literal>, this exception ends the current long-running conversation.
</para>
</listitem>
</itemizedlist>
@@ -794,7 +794,7 @@
</para>
<note>
<para>
- This annotation should not be used on EJB3 components — use <literal>@javax.interceptor.Interceptors</literal> instead.
+ This annotation should not be used on EJB3 components — use <literal>@javax.interceptor.Interceptors</literal> instead.
</para>
</note>
</listitem>
@@ -823,17 +823,17 @@
<itemizedlist>
<listitem>
<para>
- <literal>viewId</literal> — specifies the JSF view ID to redirect to. You can use EL here.
+ <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.
+ <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>.
+ <literal>end</literal> — specifies that the long-running conversation should end. Defaults to <literal>false</literal>.
</para>
</listitem>
</itemizedlist>
@@ -851,17 +851,17 @@
<itemizedlist>
<listitem>
<para>
- <literal>errorCode</literal> — the HTTP error code. Defaults to <literal>500</literal>.
+ <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.
+ <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>.
+ <literal>end</literal> — specifies that the long-running conversation should end. Defaults to <literal>false</literal>.
</para>
</listitem>
</itemizedlist>
@@ -1005,12 +1005,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>id</literal> — the JSF converter ID. Defaults to the component name.
+ <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.
+ <literal>forClass</literal> — if specified, registers this component as the default converter for a type.
</para>
</listitem>
</itemizedlist>
@@ -1025,7 +1025,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>id</literal> — the JSF validator ID. Defaults to the component name.
+ <literal>id</literal> — the JSF validator ID. Defaults to the component name.
</para>
</listitem>
</itemizedlist>
@@ -1050,12 +1050,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>value</literal> — name of the conversation context variable. Default to the attribute name.
+ <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.
+ <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>
@@ -1076,7 +1076,7 @@
<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.
+ <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>
@@ -1094,7 +1094,7 @@
<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.
+ <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>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Clustering_EJBPassivation.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Clustering_EJBPassivation.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Clustering_EJBPassivation.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -2,11 +2,7 @@
<!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>
- <!--Note to QE: This chapter is new and has not been revised as of 03 Aug 2009. Trying to have it complete for CR02 on 07 Aug. Contact lbailey at redhat.com if any issues.-->
- <!--<para>
- <emphasis>Please note that this chapter is still being reviewed. Tread carefully.</emphasis>
- </para>-->
-
+
<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>
@@ -51,7 +47,6 @@
</note>
</section>
-<!--hajime-->
<section id="clustering.deployment">
<title>Deploying a Seam application to a JBoss AS cluster with session replication</title>
@@ -75,7 +70,7 @@
<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 RHEL 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>:
+ 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
@@ -140,14 +135,8 @@
</para>
<programlisting> ./bin/run.sh -c all -b 192.168.1.2</programlisting>
<para>
- You should see the following in the log:
+ The log should report one cluster member and zero other members.
</para>
- <screen>
-00:00:00,000 INFO [DefaultPartition] Number of cluster members: 1
-00:00:00,000 INFO [DefaultPartition] Other members: 0
-00:00:00,000 INFO [DefaultPartition] Fetching state (will wait for 30000 milliseconds):
-00:00:00,000 INFO [DefaultPartition] State could not be retrieved (we are the first member in group)
- </screen>
</listitem>
<listitem>
<para>
@@ -160,65 +149,21 @@
</para>
<programlisting> ./bin/run.sh -c all -b 192.168.1.3</programlisting>
<para>
- The log should show the following:
+ The log should report two cluster members and one other member. It should also show the state being retrieved from the master instance.
</para>
- <screen>
-00:00:00,000 INFO [DefaultPartition] Number of cluster members: 2
-00:00:00,000 INFO [DefaultPartition] Other members: 1
-00:00:00,000 INFO [DefaultPartition] Fetching state (will wait for 30000 milliseconds):
-00:00:00,000 INFO [DefaultPartition] state was retrieved successfully (in 120 milliseconds)
- </screen>
- <para>In the log of the first instance, you should see acknowledgement of the new member:</para>
- <screen>
-00:00:00,000 INFO [DefaultPartition] I am (192.168.1.2:1099) received membershipChanged event:
-00:00:00,000 INFO [DefaultPartition] Dead members: 0 ([])
-00:00:00,000 INFO [DefaultPartition] New Members : 1 ([192.168.1.3:1099])
-00:00:00,000 INFO [DefaultPartition] All Members : 2 ([192.168.1.2:1099, 192.168.1.3:1099])
- </screen>
</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:
+ 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>
- <screen>
-00:00:00,000 INFO [ConnectionFactoryBindingService] Bound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=vehiclesDatasource' to JNDI name 'java:vehiclesDatasource'
-00:00:00,000 INFO [ClusterFileTransfer] Start push of file vehicles-ds.xml to cluster.
-00:00:00,000 INFO [ClusterFileTransfer] Finished push of file vehicles-ds.xml to cluster.
- </screen>
- <para>In the log of the slave instance, you should see a complementary message:</para>
- <screen>
-00:00:00,000 INFO [FarmMemberService] farmDeployment(), deploy locally: farm/vehicles-ds.xml
-00:00:00,000 INFO [ConnectionFactoryBindingService] Unbound ConnectionManager 'jboss.jca:service=DataSourceBinding,name=vehiclesDatasource' from JNDI name 'java:vehiclesDatasource'
- </screen>
</listitem>
<listitem>
<para>
- Deploy the application to the server/all/farm directory:
+ 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>
- <para>
- In the log of the master instance you should see acknowlegement of this deployment after the normal application startup messages have finished:
- </para>
- <screen>
-00:00:00,000 INFO [ClusterFileTransfer] Start push of file vehicles.war to cluster.
- </screen>
- <para>
- Wait for the deployed archive to be transferred. (This takes approximately three minutes.) In the log of the master instance, you should see acknowledgement of this deployment prior to the normal application startup messages:
- </para>
- <screen>
-00:00:00,000 INFO [FarmMemberService] farmDeployment(), deploy locally: farm/vehicles.war
- </screen>
- <para>
- Once the application is transferred, you should see confirmation in the log of the master instance:
- </para>
- <screen>
-00:00:00,000 INFO [ClusterFileTransfer] Finished push of file vehicles.war to cluster.
- </screen>
- <para>
-Finally, you should see the application startup messages in the slave instance log.
- </para>
</listitem>
</orderedlist>
<para>
@@ -255,32 +200,16 @@
</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 inserializing correctly.
+ 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>
- First, remove at least the <literal>JSESSIONID</literal> cookie for the <literal>192.168.1.2</literal> domain. Then, open the application on the master instance. (We used <literal>http://192.168.1.2/seam-booking/</literal>.)
- </para>
- <para>Create a URL for the second instance:</para>
- <itemizedlist>
- <listitem><para>Copy the URL in the workspace list at the bottom of the page (the Servlet path), and change the IP address to that of the slave instance. (We changed it from <literal>192.168.1.2</literal> to <literal>192.168.1.3</literal>.)</para></listitem>
- <listitem><para>Place <literal>;jsessionid=XXXX</literal> directly after the Servlet path, where <replaceable>XXXX</replaceable> is the value of the <literal>JSESSIONID</literal> cookie of the current page.</para></listitem>
- </itemizedlist>
- <para>Visit this URL in a second browser which has cookies disabled. (This ensures that the session ID specified in the URL will be used.)</para>
- <para>Complete the booking form and click the <guibutton>Proceed</guibutton> button.</para>
- <para>Now, return to the original browser and change the URL to match the form of the confirmation page, keeping the <literal>cid</literal> request parameter, like so:</para>
- <programlisting>http://192.168.1.2/seam-booking/confirm.seam?cid=4
-</programlisting>
- <para>If desired, verity that you can continue without the slave instance: go to JMX console and execute the <literal>shutdown()</literal> method on <literal>jboss.system:type=Server</literal>.</para>
- <para>Confirm the booking.</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>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 is to create a session- or conversation-scoped Seam component and implement 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>
+ 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);]]>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Components.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Components.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Components.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -5,7 +5,7 @@
<chapter id="components" lang="en-US">
<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>.
+ 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.
@@ -23,7 +23,7 @@
<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>.
+ Component that provides access to Seam Context objects such as <literal>org.jboss.seam.core.contexts.sessionContext['user']</literal>.
</para>
</listitem>
</varlistentry>
@@ -54,7 +54,7 @@
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>.
+ 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.
@@ -70,32 +70,32 @@
<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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <literal>clear()</literal> — clears all messages.
</para>
</listitem>
</itemizedlist>
@@ -110,27 +110,27 @@
<itemizedlist>
<listitem>
<para>
- <literal>redirect.viewId</literal> — the JSF view ID to redirect to.
+ <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.
+ <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.
+ <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.
+ <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>.
+ <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>
@@ -148,7 +148,7 @@
<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.
+ 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).
@@ -156,7 +156,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>maxSize</literal> — The maximum number of stamps to keep in the store. The default is <literal>100</literal>.
+ <literal>maxSize</literal> — The maximum number of stamps to keep in the store. The default is <literal>100</literal>.
</para>
</listitem>
</itemizedlist>
@@ -183,22 +183,22 @@
<itemizedlist>
<listitem>
<para>
- <literal>raiseEvent(String type)</literal> — raises an event of a particular type and distributes it to all observers.
+ <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.
+ <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.
+ <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.
+ <literal>addListener(String type, String methodBinding)</literal> — adds an observer for a particular event type.
</para>
</listitem>
</itemizedlist>
@@ -213,7 +213,7 @@
<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.
+ <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>
@@ -228,12 +228,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>createValueBinding(String expression)</literal> — creates a value binding object.
+ <literal>createValueBinding(String expression)</literal> — creates a value binding object.
</para>
</listitem>
<listitem>
<para>
- <literal>createMethodBinding(String expression)</literal> — creates a method binding object.
+ <literal>createMethodBinding(String expression)</literal> — creates a method binding object.
</para>
</listitem>
</itemizedlist>
@@ -248,7 +248,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>pojoCache.cfgResourceName</literal> — the name of the configuration file. Defaults to <filename>treecache.xml</filename>.
+ <literal>pojoCache.cfgResourceName</literal> — the name of the configuration file. Defaults to <filename>treecache.xml</filename>.
</para>
</listitem>
</itemizedlist>
@@ -299,7 +299,7 @@
<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>.
+ <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>
@@ -314,42 +314,42 @@
<itemizedlist>
<listitem>
<para>
- <literal>select()</literal> — selects the specified locale.
+ <literal>select()</literal> — selects the specified locale.
</para>
</listitem>
<listitem>
<para>
- <literal>localeSelector.locale</literal> — the actual <literal>java.util.Locale</literal>.
+ <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.
+ <literal>localeSelector.localeString</literal> — the string representation of the locale.
</para>
</listitem>
<listitem>
<para>
- <literal>localeSelector.language</literal> — the language for the specified locale.
+ <literal>localeSelector.language</literal> — the language for the specified locale.
</para>
</listitem>
<listitem>
<para>
- <literal>localeSelector.country</literal> — the country for the specified locale.
+ <literal>localeSelector.country</literal> — the country for the specified locale.
</para>
</listitem>
<listitem>
<para>
- <literal>localeSelector.variant</literal> — the variant for the specified locale.
+ <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>.
+ <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.
+ <literal>localeSelector.cookieEnabled</literal> — specifies that the locale selection should be persisted via a cookie.
</para>
</listitem>
</itemizedlist>
@@ -364,22 +364,22 @@
<itemizedlist>
<listitem>
<para>
- <literal>select()</literal> — selects the specified locale.
+ <literal>select()</literal> — selects the specified locale.
</para>
</listitem>
<listitem>
<para>
- <literal>timezoneSelector.timezone</literal> — the actual <literal>java.util.TimeZone</literal>.
+ <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.
+ <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.
+ <literal>timezoneSelector.cookieEnabled</literal> — specifies that the timezone selection should be persisted via a cookie.
</para>
</listitem>
</itemizedlist>
@@ -402,27 +402,27 @@
<itemizedlist>
<listitem>
<para>
- <literal>select()</literal> — select the specified theme.
+ <literal>select()</literal> — select the specified theme.
</para>
</listitem>
<listitem>
<para>
- <literal>theme.availableThemes</literal> — the list of defined themes.
+ <literal>theme.availableThemes</literal> — the list of defined themes.
</para>
</listitem>
<listitem>
<para>
- <literal>themeSelector.theme</literal> — the selected theme.
+ <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.
+ <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.
+ <literal>themeSelector.cookieEnabled</literal> — specifies that the theme selection should be persisted via a cookie.
</para>
</listitem>
</itemizedlist>
@@ -452,92 +452,92 @@
<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.
+ 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.
+ <literal>getId()</literal> — returns the current conversation ID.
</para>
</listitem>
<listitem>
<para>
- <literal>isNested()</literal> — specifies whether the current conversation is a nested conversation.
+ <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.
+ <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.
+ <literal>getId()</literal> — returns the current conversation ID.
</para>
</listitem>
<listitem>
<para>
- <literal>getParentId()</literal> — returns the conversation ID of the parent conversation.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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>).
+ <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>).
+ <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>).
+ <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.
+ <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.
+ <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.
+ <literal>changeFlushMode(FlushModeType flushMode)</literal> — changes the flush mode of the conversation.
</para>
</listitem>
</itemizedlist>
@@ -588,22 +588,22 @@
<itemizedlist>
<listitem>
<para>
- <literal>isInProcess()</literal> — returns <literal>true</literal> if there is currently a pageflow in process.
+ <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.
+ <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.
+ <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.
+ <literal>reposition(String nodeName)</literal> — repositions the current pageflow to a particular node.
</para>
</listitem>
</itemizedlist>
@@ -618,12 +618,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>setId(String actorId)</literal> — sets the jBPM actor ID of the current user.
+ <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.
+ <literal>getGroupActorIds()</literal> — returns a <literal>Set</literal> to which jBPM actor IDs for the current users groups may be added.
</para>
</listitem>
</itemizedlist>
@@ -633,12 +633,12 @@
<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.
+ 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>.
+ <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>
@@ -653,52 +653,52 @@
<itemizedlist>
<listitem>
<para>
- <literal>businessProcess.taskId</literal> — the ID of the task associated with the current conversation.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <literal>transition(String transitionName)</literal> — triggers the transition.
</para>
</listitem>
</itemizedlist>
@@ -800,7 +800,7 @@
<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>.
+ 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>
@@ -835,7 +835,7 @@
<section id="components.mail">
<title>Mail-related components</title>
<para>
- These components are for use with Seam's Email support.
+ These components are for use with Seam's Email support.
</para>
<variablelist>
<varlistentry>
@@ -847,40 +847,40 @@
<itemizedlist>
<listitem>
<para>
- <literal>org.jboss.seam.mail.mailSession.host</literal> — the hostname of the SMTP server to use.
+ <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.
+ <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.
+ <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.
+ <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).
+ <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).
+ <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>.
+ <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.
+ <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>
@@ -904,22 +904,22 @@
<itemizedlist>
<listitem>
<para>
- <literal>org.jboss.seam.core.init.jndiPattern</literal> — the JNDI pattern used for looking up session beans.
+ <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.
+ <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>.
+ <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.
+ <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>
@@ -934,27 +934,27 @@
<itemizedlist>
<listitem>
<para>
- <literal>org.jboss.seam.core.manager.conversationTimeout</literal> — the conversation context timeout in milliseconds.
+ <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.
+ <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>.
+ <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>.
+ <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>.
+ <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>
@@ -969,27 +969,27 @@
<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.
+ <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.
+ <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.
+ <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.
+ <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>.
+ <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>
@@ -999,17 +999,17 @@
<term><literal>org.jboss.seam.bpm.jbpm</literal></term>
<listitem>
<para>
- BThis component bootstraps a <literal>JbpmConfiguration</literal>. Install it as the <literal>org.jboss.seam.bpm.Jbpm</literal> class.
+ 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.
+ <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.
+ <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>
@@ -1048,7 +1048,7 @@
<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>.
+ <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>
@@ -1063,7 +1063,7 @@
<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>.
+ <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>
@@ -1205,10 +1205,10 @@
<itemizedlist>
<listitem>
<para>
- <emphasis><entityManager></emphasis>.entityManagerFactory — a value binding expression that evaluates to an instance of <literal>EntityManagerFactory</literal>.
+ <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> .
+ <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>
@@ -1224,7 +1224,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>entityManagerFactory.persistenceUnitName</literal> — the name of the persistence unit.
+ <literal>entityManagerFactory.persistenceUnitName</literal> — the name of the persistence unit.
</para>
</listitem>
</itemizedlist>
@@ -1243,10 +1243,10 @@
<itemizedlist>
<listitem>
<para>
- <emphasis><session></emphasis>.sessionFactory — a value binding expression that evaluates to an instance of <literal>SessionFactory</literal>.
+ <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>.
+ <emphasis><session></emphasis>.sessionFactoryJndiName — the JNDI name of the session factory. By default, this is <literal>java:/<option><managedSession></option></literal>.
</para>
</listitem>
</itemizedlist>
@@ -1262,7 +1262,7 @@
<itemizedlist>
<listitem>
<para>
- <literal><sessionFactory>.cfgResourceName</literal> — specifies the path to the configuration file. By default, this is <filename>hibernate.cfg.xml</filename>.
+ <literal><sessionFactory>.cfgResourceName</literal> — specifies the path to the configuration file. By default, this is <filename>hibernate.cfg.xml</filename>.
</para>
</listitem>
</itemizedlist>
@@ -1281,7 +1281,7 @@
<itemizedlist>
<listitem>
<para>
- <emphasis><managedQueueSender></emphasis>.queueJndiName — the JNDI name of the JMS queue.
+ <emphasis><managedQueueSender></emphasis>.queueJndiName — the JNDI name of the JMS queue.
</para>
</listitem>
</itemizedlist>
@@ -1297,7 +1297,7 @@
<itemizedlist>
<listitem>
<para>
- <emphasis><managedTopicPublisher></emphasis>.topicJndiName — the JNDI name of the JMS topic.
+ <emphasis><managedTopicPublisher></emphasis>.topicJndiName — the JNDI name of the JMS topic.
</para>
</listitem>
</itemizedlist>
@@ -1313,7 +1313,7 @@
<itemizedlist>
<listitem>
<para>
- <emphasis><managedWorkingMemory></emphasis>.ruleBase — a value expression that evaluates to an instance of <literal>RuleBase</literal>.
+ <emphasis><managedWorkingMemory></emphasis>.ruleBase — a value expression that evaluates to an instance of <literal>RuleBase</literal>.
</para>
</listitem>
</itemizedlist>
@@ -1329,10 +1329,10 @@
<itemizedlist>
<listitem>
<para>
- <emphasis><ruleBase></emphasis>.ruleFiles — a list of files containing Drools rules.
+ <emphasis><ruleBase></emphasis>.ruleFiles — a list of files containing Drools rules.
</para>
<para>
- <emphasis><ruleBase></emphasis>.dslFile — a Drools DSL definition.
+ <emphasis><ruleBase></emphasis>.dslFile — a Drools DSL definition.
</para>
</listitem>
</itemizedlist>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Concepts.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Concepts.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Concepts.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -653,7 +653,8 @@
<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>
+ <!-- #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>
@@ -725,7 +726,43 @@
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") @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 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 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.
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Configuration.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Configuration.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Configuration.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -64,7 +64,7 @@
<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>.
+ 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>
@@ -95,17 +95,17 @@
<itemizedlist>
<listitem>
<para>
- <literal>url-pattern</literal> — Specifies which requests are filtered. The default is all requests. <literal>url-pattern</literal> is a Tomcat-style pattern which allows a wildcard suffix.
+ <literal>url-pattern</literal> — Specifies 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> — Specifies which requests are filtered. The default is all requests. <literal>regex-url-pattern</literal> is a true regular expression match for request path.
+ <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.
+ <literal>disabled</literal> — Disables a built in filter.
</para>
</listitem>
</itemizedlist>
@@ -165,12 +165,12 @@
<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>.
+ <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.)
+ <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>
@@ -187,12 +187,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>encoding</literal> — The type of encoding to use.
+ <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>.
+ <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>
@@ -215,17 +215,17 @@
<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.
+ <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.
+ <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 -->
+ <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>
@@ -250,7 +250,7 @@
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.
+ 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>:
@@ -269,7 +269,7 @@
<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>.)
+ 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 @Scope(APPLICATION) @Name("org.jboss.seam.web.multipartFilter") @BypassInterceptors @Filter(within="org.jboss.seam.web.ajax4jsfFilter") public class MultipartFilter extends AbstractFilter {]]>
@@ -294,7 +294,7 @@
<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>:
+ 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:
@@ -359,7 +359,7 @@
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.
+ 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:
@@ -399,7 +399,7 @@
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>.
+ 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>
@@ -412,7 +412,7 @@
</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.
+ 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>
@@ -451,7 +451,40 @@
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 META-INF/ MANIFEST.MF application.xml my-application.war/ META-INF/ MANIFEST.MF WEB-INF/ web.xml components.xml faces-config.xml lib/ jsf-facelets.jar jboss-seam-ui.jar login.jsp register.jsp ... my-application.jar/ META-INF/ MANIFEST.MF persistence.xml seam.properties org/ jboss/ myapplication/ User.class Login.class LoginBean.class Register.class RegisterBean.class ...]]>
+<programlisting><![CDATA[my-application.ear/
+ jboss-seam.jar
+ lib/
+ jboss-el.jar
+ META-INF/
+ MANIFEST.MF
+ application.xml
+ my-application.war/
+ META-INF/
+ MANIFEST.MF
+ WEB-INF/
+ web.xml
+ components.xml
+ faces-config.xml
+ lib/
+ jsf-facelets.jar
+ jboss-seam-ui.jar
+ login.jsp
+ register.jsp
+ ...
+ my-application.jar/
+ META-INF/
+ MANIFEST.MF
+ persistence.xml
+ seam.properties
+ org/
+ jboss/
+ myapplication/
+ User.class
+ Login.class
+ LoginBean.class
+ Register.class
+ RegisterBean.class
+ ...]]>
</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.
@@ -463,13 +496,13 @@
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>.
+ 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.
+ Seam also ships with several example applications — these are deployable in any Java EE container with EJB3 support.
</para>
</section>
@@ -480,7 +513,7 @@
<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>
- <!-- #modify: again, this diagram means nothing to me. --> <mediaobject>
+ <mediaobject>
<imageobject role="fo">
<imagedata align="center" fileref="images/hibernate-ee.png" format="PNG" />
</imageobject>
@@ -492,7 +525,7 @@
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.
+ 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>
@@ -532,7 +565,37 @@
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/ web.xml components.xml faces-config.xml lib/ jboss-seam.jar jboss-seam-ui.jar jboss-el.jar jsf-facelets.jar hibernate3.jar hibernate-annotations.jar hibernate-validator.jar ... my-application.jar/ META-INF/ MANIFEST.MF seam.properties hibernate.cfg.xml org/ jboss/ myapplication/ User.class Login.class Register.class ... login.jsp register.jsp ...]]>
+<programlisting><![CDATA[my-application.war/
+ META-INF/
+ MANIFEST.MF
+ WEB-INF/
+ web.xml
+ components.xml
+ faces-config.xml
+ lib/
+ jboss-seam.jar
+ jboss-seam-ui.jar
+ jboss-el.jar
+ jsf-facelets.jar
+ hibernate3.jar
+ hibernate-annotations.jar
+ hibernate-validator.jar
+ ...
+ my-application.jar/
+ META-INF/
+ MANIFEST.MF
+ seam.properties
+ hibernate.cfg.xml
+ org/
+ jboss/
+ myapplication/
+ User.class
+ Login.class
+ Register.class
+ ...
+ login.jsp
+ register.jsp
+ ...]]>
</programlisting>
<para>
Some additional configuration is required in order to deploy Hibernate in a non-EE environment, such as Tomcat or TestNG.
@@ -544,7 +607,7 @@
<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:
+ 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}"/>]]>
@@ -587,74 +650,7 @@
<imagedata align="center" fileref="images/e-ejb3.png" format="PNG" />
</imageobject>
</mediaobject>
- <section id="config.install.embedded">
- <title>Installing Embedded JBoss</title>
- <para>
- Seam applications require Embedded JBoss to run correctly on Tomcat. Embedded JBoss runs with JDK 5 or JDK 6 (see <xref linkend="jdk_dependencies" /> for details on using JDK 6), and can be downloaded <ulink url="http://sourceforge.net/project/showfiles.php?group_id=22866& package_id=228977">here</ulink>. To install Embedded JBoss into Tomcat 6, first copy the Embedded JBoss JARs and configuration files into Tomcat:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Copy all files and directories under the Embedded JBoss <literal>bootstrap</literal> and <literal>lib</literal> directories <emphasis>except the <literal>jndi.properties</literal> file</emphasis> into the Tomcat <literal>lib</literal> directory.
- </para>
- </listitem>
- <listitem>
- <para>
- Remove the <filename>annotations-api.jar</filename> file from the Tomcat <literal>lib</literal> directory.
- </para>
- </listitem>
- </itemizedlist>
- <para>
- Next, add the following updated configuration files to enable Embedded JBoss-specific functionality:
- </para>
- <itemizedlist>
- <listitem>
- <para>
- Add the Embedded JBoss listener <literal>EmbeddedJBossBootstrapListener</literal> to <filename>conf/server.xml</filename>. This listener must appear after all other listeners in the file:
- </para>
-
-<programlisting role="XML"><![CDATA[<Server port="8005" shutdown="SHUTDOWN"> <!-- Comment these entries out to disable JMX MBeans support used for the administration web application --> <Listener className="org.apache.catalina.core.AprLifecycleListener" /> <Listener className="org.apache.catalina.mbeans.ServerLifecycleListener" /> <Listener className="org.apache.catalina.mbeans.GlobalResourcesLifecycleListener" /> <Listener className="org.apache.catalina.storeconfig.StoreConfigLifecycleListener" />]]>
-</programlisting>
-
-<programlisting role="XML"><![CDATA[ <!-- Add this listener --> <Listener className="org.jboss.embedded.tomcat.EmbeddedJBossBootstrapListener" />]]>
-</programlisting>
- </listitem>
- <listitem>
- <para>
- Enable <filename>WAR</filename> file scanning by adding the <literal>WebinfScanner</literal> listener to <filename>conf/context.xml</filename>:
- </para>
-
-<programlisting role="XML"><![CDATA[<Context> <!-- Default set of monitored resources --> <WatchedResource>WEB-INF/web.xml</WatchedResource> <!-- Uncomment this to disable session persistence across Tomcat restarts --> <!-- <Manager pathname="" /> -->]]>
-</programlisting>
-
-<programlisting role="XML"><![CDATA[ <!-- Add this listener --> <Listener className="org.jboss.embedded.tomcat.WebinfScanner" />]]>
-</programlisting>
-
-<programlisting role="XML"><![CDATA[</Context>]]>
-</programlisting>
- </listitem>
- <listitem>
- <para>
- If you use Sun JDK 6, you must set the <literal>sun.lang.ClassLoader.allowArraySyntax</literal> Java option to <literal>true</literal>. (This is found in the JAVA_OPTS environment variable used by the Catalina startup script — <literal>catalina.bat</literal> on Windows or <literal>catalina.sh</literal> on Unix.)
- </para>
- <para>
- Open the script appropriate for your operating system in a text editor. Add a new line immediately below the comments at the top of the file. On Windows, define the <literal>JAVA_OPTS</literal> variable like so:
- </para>
-
-<programlisting><![CDATA[set JAVA_OPTS=%JAVA_OPTS% -Dsun.lang.ClassLoader.allowArraySyntax=true]]>
-</programlisting>
- <para>
- On Unix, define it as follows:
- </para>
-
-<programlisting><![CDATA[JAVA_OPTS="$JAVA_OPTS -Dsun.lang.ClassLoader.allowArraySyntax=true"]]>
-</programlisting>
- </listitem>
- </itemizedlist>
- <para>
- For more configuration options, please see the Embedded JBoss Tomcat integration <ulink url="http://wiki.jboss.org/wiki/Wiki.jsp?page=EmbeddedAndTomcat">wiki entry</ulink>.
- </para>
- </section>
+
<section>
<title>Packaging</title>
@@ -662,7 +658,38 @@
A <filename>WAR</filename>-based deployment on a Servlet engine like Tomcat will be structured as follows:
</para>
-<programlisting><![CDATA[my-application.war/ META-INF/ MANIFEST.MF WEB-INF/ web.xml components.xml faces-config.xml lib/ jboss-seam.jar jboss-seam-ui.jar jboss-el.jar jsf-facelets.jar jsf-api.jar jsf-impl.jar ... my-application.jar/ META-INF/ MANIFEST.MF persistence.xml seam.properties org/ jboss/ myapplication/ User.class Login.class LoginBean.class Register.class RegisterBean.class ... login.jsp register.jsp ...]]>
+<programlisting><![CDATA[my-application.war/
+ META-INF/
+ MANIFEST.MF
+ WEB-INF/
+ web.xml
+ components.xml
+ faces-config.xml
+ lib/
+ jboss-seam.jar
+ jboss-seam-ui.jar
+ jboss-el.jar
+ jsf-facelets.jar
+ jsf-api.jar
+ jsf-impl.jar
+ ...
+ my-application.jar/
+ META-INF/
+ MANIFEST.MF
+ persistence.xml
+ seam.properties
+ org/
+ jboss/
+ myapplication/
+ User.class
+ Login.class
+ LoginBean.class
+ Register.class
+ RegisterBean.class
+ ...
+ login.jsp
+ register.jsp
+ ...]]>
</programlisting>
<para>
You can deploy most of Seam's example applications to Tomcat by running <literal>ant deploy.tomcat</literal>.
@@ -686,7 +713,7 @@
<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>
- Note that jBPM transaction control is disabled — JTA transactions should be controlled by either Seam or EJB3.
+ Note that jBPM transaction control is disabled — JTA transactions should be controlled by either Seam or EJB3.
</para>
<section>
<title>Packaging</title>
@@ -694,7 +721,47 @@
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 jbpm-3.1.jar META-INF/ MANIFEST.MF application.xml my-application.war/ META-INF/ MANIFEST.MF WEB-INF/ web.xml components.xml faces-config.xml lib/ jsf-facelets.jar jboss-seam-ui.jar login.jsp register.jsp ... my-application.jar/ META-INF/ MANIFEST.MF persistence.xml seam.properties org/ jboss/ myapplication/ User.class Login.class LoginBean.class Register.class RegisterBean.class ... jbpm.cfg.xml hibernate.cfg.xml createDocument.jpdl.xml editDocument.jpdl.xml approveDocument.jpdl.xml documentLifecycle.jpdl.xml]]>
+<programlisting><![CDATA[my-application.ear/
+ jboss-seam.jar
+ lib/
+ jboss-el.jar
+ jbpm-jpdl.jar
+ META-INF/
+ MANIFEST.MF
+ application.xml
+ my-application.war/
+ META-INF/
+ MANIFEST.MF
+ WEB-INF/
+ web.xml
+ components.xml
+ faces-config.xml
+ lib/
+ jsf-facelets.jar
+ jboss-seam-ui.jar
+ login.jsp
+ register.jsp
+ ...
+ my-application.jar/
+ META-INF/
+ MANIFEST.MF
+ persistence.xml
+ seam.properties
+ org/
+ jboss/
+ myapplication/
+ User.class
+ Login.class
+ LoginBean.class
+ Register.class
+ RegisterBean.class
+ ...
+ jbpm.cfg.xml
+ hibernate.cfg.xml
+ createDocument.jpdl.xml
+ editDocument.jpdl.xml
+ approveDocument.jpdl.xml
+ documentLifecycle.jpdl.xml]]>
</programlisting>
</section>
@@ -703,13 +770,30 @@
<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.
+ 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> <!-- 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 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>
You can modify the default HTTP Session timeout in <filename>server/default/deploy/jbossweb-tomcat55.sar/conf/web.xml</filename> for JBoss 4.0.x, or 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:
@@ -735,7 +819,7 @@
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:
+ 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]]>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Controls.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Controls.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Controls.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -34,37 +34,37 @@
<itemizedlist>
<listitem>
<para>
- <literal>value</literal> — the button label.
+ <literal>value</literal> — the button label.
</para>
</listitem>
<listitem>
<para>
- <literal>action</literal> — a method binding that specifies the action listener.
+ <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.
+ <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.
+ <literal>fragment</literal> — specifies the fragment identifier to link to.
</para>
</listitem>
<listitem>
<para>
- <literal>disabled</literal> — specifies whether the link is disabled.
+ <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>.
+ <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.)
+ <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>
@@ -131,37 +131,37 @@
<itemizedlist>
<listitem>
<para>
- <literal>value</literal> — specifies the link label.
+ <literal>value</literal> — specifies the link label.
</para>
</listitem>
<listitem>
<para>
- <literal>action</literal> — a method binding that specifies the action listener.
+ <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.
+ <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.
+ <literal>fragment</literal> — specifies the fragment identifier to link to.
</para>
</listitem>
<listitem>
<para>
- <literal>disabled</literal> — specifies whether the link is disabled.
+ <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>.
+ <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>.)
+ <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>
@@ -190,12 +190,12 @@
<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>.
+ <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>.)
+ <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>
@@ -285,7 +285,7 @@
You must use <emphasis>Seam managed transactions</emphasis> (see <xref linkend="persistence.seam-managed-transactions" />) with <literal><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>:
+ 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}" />
@@ -297,13 +297,13 @@
<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 <literal>components.xml</literal>:
+ 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 <literal>components.xml</literal>. The entity converter delegates to the entity loader to perform persistence operations like so:
+ 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}" />]]>
@@ -421,51 +421,51 @@
<itemizedlist>
<listitem>
<para>
- <literal>for</literal> — The ID of a control to validate against.
+ <literal>for</literal> — The ID of a control to validate against.
</para>
</listitem>
<listitem>
<para>
- <literal>message</literal> — Message to show on failure.
+ <literal>message</literal> — Message to show on failure.
</para>
</listitem>
<listitem>
<para>
- <literal>messageId</literal> — Message ID to show on failure.
+ <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:
+ <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>.
+ <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>
+ <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]]>
+ <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]]>
+ <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]]>
+ <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]]>
+ <literal>less_or_equal</literal> — <![CDATA[validates that ((Comparable)value).compareTo(forValue) <= 0]]>
</para>
</listitem>
</itemizedlist>
@@ -542,17 +542,17 @@
<itemizedlist>
<listitem>
<para>
- <literal>template</literal> — the Facelets template used to decorate the component.
+ <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.)
+ <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.
+ <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>
@@ -607,7 +607,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>title</literal> — Title for a span.
+ <literal>title</literal> — Title for a span.
</para>
</listitem>
</itemizedlist>
@@ -657,12 +657,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>style</literal> — The control's style.
+ <literal>style</literal> — The control's style.
</para>
</listitem>
<listitem>
<para>
- <literal>styleClass</literal> — The control's style class.
+ <literal>styleClass</literal> — The control's style class.
</para>
</listitem>
</itemizedlist>
@@ -730,7 +730,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>value</literal> — an EL expression specifying the rich text markup to render.
+ <literal>value</literal> — an EL expression specifying the rich text markup to render.
</para>
</listitem>
</itemizedlist>
@@ -771,17 +771,17 @@
<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.)
+ <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>.
+ <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>.
+ <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>
@@ -807,12 +807,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>enumValue</literal> — the string representation of the enum value.
+ <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>.
+ <literal>label</literal> — the label to be used when rendering the <literal>SelectItem</literal>.
</para>
</listitem>
</itemizedlist>
@@ -820,7 +820,16 @@
<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 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>
@@ -838,37 +847,37 @@
<itemizedlist>
<listitem>
<para>
- <literal>value</literal> — an EL expression specifying the data that backs the <literal>List<SelectItem></literal>
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <literal>hideNoSelectionLabel</literal> — if true, the <literal>noSelectionLabel</literal> will be hidden when a value is selected.
</para>
</listitem>
</itemizedlist>
@@ -892,7 +901,7 @@
<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>:
+ 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>]]>
@@ -906,12 +915,12 @@
<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.
+ <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.
+ <literal>maxRequestSize</literal> — the maximum size of a file upload request, in bytes.
</para>
</listitem>
</itemizedlist>
@@ -927,37 +936,37 @@
<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>.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <literal>style</literal> — The control's style.
</para>
</listitem>
<listitem>
<para>
- <literal>styleClass</literal> — The control's style class.
+ <literal>styleClass</literal> — The control's style class.
</para>
</listitem>
</itemizedlist>
@@ -987,17 +996,17 @@
<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>.
+ <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.
+ <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.
+ <literal>region</literal> — specifies the JBoss Cache node to use. Different nodes can have different expiry policies.
</para>
</listitem>
</itemizedlist>
@@ -1005,7 +1014,21 @@
<emphasis>Usage</emphasis>
</para>
-<programlisting role="XHTML"><![CDATA[<s:cache key="entry-#{blogEntry.id}" region="pageFragments"> <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> </s:cache>]]>
+<programlisting role="XHTML"><![CDATA[<s:cache key="entry-#{blogEntry.id}" region="pageFragments">
+ <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>
+</s:cache>]]>
</programlisting>
</section>
@@ -1029,22 +1052,22 @@
<itemizedlist>
<listitem>
<para>
- <literal>data</literal> — specifies data that should be downloaded. May be a java.util.File, an InputStream or a byte array.
+ <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.
+ <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.
+ <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>.
+ <literal>disposition</literal> — the disposition to use. The default disposition is <literal>inline</literal>.
</para>
</listitem>
</itemizedlist>
@@ -1058,7 +1081,7 @@
<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>.
+ 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>
@@ -1073,7 +1096,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>src</literal> — Resource file serving files.
+ <literal>src</literal> — Resource file serving files.
</para>
</listitem>
</itemizedlist>
@@ -1105,12 +1128,12 @@
<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>.
+ <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.
+ <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>
@@ -1127,22 +1150,22 @@
<itemizedlist>
<listitem>
<para>
- <literal>width</literal> — specifies the new width of the image.
+ <literal>width</literal> — specifies the new width of the image.
</para>
</listitem>
<listitem>
<para>
- <literal>height</literal> — specifies the new height of the image.
+ <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.
+ <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.
+ <literal>factor</literal> — scales the image by the specified factor.
</para>
</listitem>
</itemizedlist>
@@ -1154,7 +1177,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>radius</literal> — performs a convolution blur with the specified radius.
+ <literal>radius</literal> — performs a convolution blur with the specified radius.
</para>
</listitem>
</itemizedlist>
@@ -1166,7 +1189,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>contentType</literal> — alters the image type to either <literal>image/jpeg</literal> or <literal>image/png</literal>.
+ <literal>contentType</literal> — alters the image type to either <literal>image/jpeg</literal> or <literal>image/png</literal>.
</para>
</listitem>
</itemizedlist>
@@ -1198,7 +1221,7 @@
<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.
+ <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>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Conversations.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Conversations.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Conversations.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -8,7 +8,7 @@
Now we will take you through Seam's conversation model in finer detail.
</para>
<para>
- The notion of a Seam "conversation" came about as a combination of three separate concepts:
+ The notion of a Seam <emphasis>conversation</emphasis> came about as a combination of three separate concepts:
</para>
<itemizedlist>
<listitem>
@@ -73,7 +73,7 @@
</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.
+ 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:
@@ -199,7 +199,7 @@
<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.
+ 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:
@@ -208,7 +208,7 @@
<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 that <literal>#{conversation.end}</literal> similarly ends conversations.
+ 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><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.
@@ -253,8 +253,44 @@
</listitem>
</itemizedlist>
</section>
-
- <section>
+
+ <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 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>
+ 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>
+
+ <note>
+ <para>
+ 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 the page has been requested while no long-running conversation is present, it performs the following actions:
+ </para>
+
+ <itemizedlist>
+ <listitem>
+ <para>raises a contextual event called <literal>org.jboss.seam.noConversation</literal></para>
+ </listitem>
+ <listitem>
+ <para>registers a warning status message with the bundle key, <literal>org.jboss.seam.NoConversation</literal></para>
+ </listitem>
+ <listitem>
+ <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>
+ </section>
+
+ <section>
<title>Using <literal><s:link></literal> and <literal><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><h:outputLink></literal>, but there are two major limitations to this method:
@@ -385,7 +421,7 @@
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.
+ 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>
@@ -493,7 +529,7 @@
<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 contains a menu that includes an item for each conversation, plus two additional items that let the user begin an additional conversation.
+ 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.
@@ -514,7 +550,29 @@
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:colum!
n> </h:dataTable>]]>
+<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.
@@ -586,7 +644,7 @@
<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.
+ <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.
@@ -618,13 +676,13 @@
The first question is whether to use the simpler "serial" request method, or a polling approach.
</para>
<para>
- If you want to use "serial" 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.
+ 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:
+ 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 when an event occurs on the client // It takes a really long time to execute @Asynchronous public void calculateTotal() { total = someReallyComplicatedCalculation(); } // This method is called as the result of the poll // It's very quick to execute public int getTotal() { return total; }]]>
@@ -652,7 +710,7 @@
<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:
+ 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>]]>
@@ -664,7 +722,7 @@
<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:
+ 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.]]>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Dependencies.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Dependencies.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Dependencies.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -798,7 +798,7 @@
</table>
</section>
- <section id="dependencies.rss">
+<!-- <section id="dependencies.rss">
<title>Seam RSS support</title>
<table>
<title>Seam RSS Dependencies</title>
@@ -986,7 +986,7 @@
</para>
</entry>
</row>
- <!-- #modify: Should the above be labeled .jar (or whatever) for consistency? --> <row>
+ TODO: Should the above be labeled .jar (or whatever) for consistency? <row>
<entry>
<para>
<filename>jboss-seam-rss.jar</filename>
@@ -1011,7 +1011,7 @@
</tbody>
</tgroup>
</table>
- </section>
+ </section>-->
<section>
<title>JBoss Rules</title>
@@ -1441,7 +1441,7 @@
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>
- <!-- #modify: ...Seam, or Maven? --> 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>.
+ 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:
@@ -1468,7 +1468,59 @@
The following sample POM will give you Seam, a JPA (provided by Hibernate), and Hibernate Validator:
</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"> <modelVersion>4.0.0</modelVersion> <groupId>org.jboss.seam.example/groupId> <artifactId>my-project</artifactId> <version>1.0</version> <name>My Seam Project</name> <packaging>jar</packaging> <repositories> <repository> <id>repository.jboss.org</id> <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.0.0.GA</version> </dependency> <depend!
ency> <groupId>org.hibernate</groupId> <artifactId>hibernate-annotations</artifactId> <version>3.3.0.ga</version> </dependency> <dependency> <groupId>org.hibernate</groupId> <artifactId>hibernate-entitymanager</artifactId> <version>3.3.1.ga</version> </dependency> <dependency> <groupId>org.jboss.seam</groupId> <artifactId>jboss-seam</artifactId> <version>2.0.0.GA</version> </dependency> </dependencies> </project>]]>
+<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">
+ <modelVersion>4.0.0</modelVersion>
+ <groupId>org.jboss.seam.example/groupId>
+ <artifactId>my-project</artifactId>
+ <version>1.0</version>
+ <name>My Seam Project</name>
+ <packaging>jar</packaging>
+ <repositories>
+ <repository>
+ <id>repository.jboss.org</id>
+ <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>
+ <version>3.4.0.GA</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-entitymanager</artifactId>
+ <version>3.4.0.GA</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.hibernate</groupId>
+ <artifactId>hibernate-search</artifactId>
+ <version>3.1.1.GA</version>
+ </dependency>
+
+ <dependency>
+ <groupId>org.jboss.seam</groupId>
+ <artifactId>jboss-seam</artifactId>
+ <version>2.2.0.GA</version>
+ </dependency>
+
+ </dependencies>
+
+</project>]]>
</programlisting>
</section>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Drools.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Drools.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Drools.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -13,7 +13,11 @@
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 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 <filename>.drl</filename> 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.
@@ -69,7 +73,31 @@
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 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>.
@@ -78,16 +106,47 @@
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 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><![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><![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>
@@ -99,11 +158,6 @@
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>
- <note>
- <para>
- Drools comes with MVEL compiled for Java 1.4, which is compatible with Java 1.4, Java 5 and Java 6. You may need to replace your MVEL <filename>JAR</filename> with one compiled for the version of Java you are using.
- </para>
- </note>
</section>
</chapter>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Events.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Events.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Events.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -88,7 +88,12 @@
Multiple or conditional page actions can be specified with 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 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.
@@ -334,7 +339,7 @@
<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:
+ 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>]]>
@@ -342,7 +347,7 @@
</section>
<section>
- <title>Fine-grained files for definition of navigation, page actions and parameters</title>
+ <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><page></literal> is the root element, and the view ID is implied:
</para>
@@ -682,7 +687,15 @@
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> <filter-mapping> <filter-name>Seam Filter</filter-name> <url-pattern>*.seam</url-pattern> </filter-mapping>]]>
+<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>
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>.
@@ -705,7 +718,7 @@
</programlisting>
<note>
<para>
- Seam cannot handle exceptions that occur during JSF's RENDER_RESPONSE phase, as it is not possible to perform a redirect once writing to the response has begun.
+ 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>
@@ -725,7 +738,27 @@
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"/> </exception> <exception class="javax.persistence.PersistenceException"> <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 role="XML"><![CDATA[<pages>
+
+ <exception class="javax.persistence.EntityNotFoundException">
+ <http-error error-code="404"/>
+ </exception>
+
+ <exception class="javax.persistence.PersistenceException">
+ <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 final <literal><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>.
@@ -737,7 +770,19 @@
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 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 handled by an exception handler. The outermost (wrapper) exception is also available as <literal>org.jboss.seam.caughtException</literal>.
@@ -748,7 +793,11 @@
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 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:
@@ -769,25 +818,54 @@
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 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 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 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 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. <literal>no-conversation-view-id</literal> and <literal>conversation-required</literal> allow finer-grained control over session expiry from within a conversation.
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Framework.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Framework.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Framework.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -28,7 +28,7 @@
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. If you are using JBoss AS, you will need version 4.2.2.GA or later:
+ 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 @Name("personHome") public class PersonHome extends EntityHome<Person> implements LocalPersonHome { }]]>
@@ -149,7 +149,7 @@
<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>.
+ 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]]>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Getting_Started_With_JBoss_Tools.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -8,12 +8,12 @@
JBoss Tools is a collection of Eclipse plugins: a project creation wizard for Seam, a content assistant for the Unified Expression Language (EL) in both Facelets and Java, a graphical editor for jPDL, a graphical editor for Seam configuration files, support for running Seam integration tests from within Eclipse, and much more.
</para>
<para>
- As with seam-gen, JBoss Tools works best with JBoss AS. It is possible to run your application on other servers with a few tweaks — the changes required are similar to those for seam-gen, described later in this reference manual.<!-- #modify: xref plz! -->
+ As with seam-gen, JBoss Tools works best with JBoss. It is possible to run your application on other servers with a few tweaks — the changes required are similar to those for seam-gen, described later in this reference manual.
</para>
<section>
<title>Before you start</title>
<para>
- Make sure you have JDK 5, JBoss AS 4.2 or 5.0, Eclipse 3.3, the JBoss Tools plugins (at least Seam Tools, the Visual Page Editor, jBPM Tools and JBoss AS Tools) and the TestNG plugin for Eclipse correctly installed before starting.
+ Make sure you have JDK 5, JBoss EAP 5, Eclipse 3.3, the JBoss Tools plugins (at least Seam Tools, the Visual Page Editor, jBPM Tools and JBoss AS Tools) and the TestNG plugin for Eclipse correctly installed before starting.
</para>
<para>
Please see the official <ulink url="http://www.jboss.org/tools/download/installation">JBoss Tools installation</ulink> page for the quickest way to get JBoss Tools set up in Eclipse. You can also check out the <ulink url="http://www.jboss.org/community/wiki/InstallingJBossTools">Installing JBoss Tools</ulink> page on the JBoss community wiki for more details and a set of alternative installation approaches.
@@ -26,7 +26,7 @@
Start up Eclipse and select the <guilabel>Seam</guilabel> perspective.
</para>
<para>
- Go to <guimenu>File</guimenu> → <guimenu>New</guimenu> → <guimenu>Seam Web Project</guimenu>.
+ Go to <guimenu>File</guimenu> → <guimenu>New</guimenu> → <guimenu>Seam Web Project</guimenu>.
</para>
<mediaobject>
<imageobject role="fo">
@@ -189,7 +189,7 @@
<para>
Review the username and password used to connect, test the connection with the <guibutton>Test Connection</guibutton> button, and when the test passes, click on <guibutton>Finish</guibutton> to return to the Seam Project Wizard.
</para>
- <!-- #modify: two 'finish' sections one after another? missing text? --> <para>
+ <para>
Finally, review the package names for your generated beans, and if you are happy, click <guibutton>Finish</guibutton>:
</para>
<mediaobject>
@@ -253,7 +253,7 @@
<section>
<title>Creating a new action</title>
<para>
- To create a simple web page with a stateless action method, select <guimenu>New</guimenu> → <guimenu>Seam Action</guimenu>:
+ To create a simple web page with a stateless action method, select <guimenu>New</guimenu> → <guimenu>Seam Action</guimenu>:
</para>
<mediaobject>
<imageobject role="fo">
@@ -281,7 +281,7 @@
Now go to <literal>http://localhost:8080/helloworld/ping.seam</literal> and click the button. You can see 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, open the <literal>helloworld-test</literal> project, locate <literal>PingTest</literal> class, right click on it, and choose <guimenu>Run As</guimenu> → <guimenu>TestNG Test</guimenu>:
+ Finally, open the <literal>helloworld-test</literal> project, locate <literal>PingTest</literal> class, right click on it, and choose <guimenu>Run As</guimenu> → <guimenu>TestNG Test</guimenu>:
</para>
<mediaobject>
<imageobject role="fo">
@@ -296,7 +296,7 @@
<section>
<title>Creating a form with an action</title>
<para>
- The first step is to create a form. Select <guimenu>New</guimenu> → <guimenu>Seam Form</guimenu>:
+ The first step is to create a form. Select <guimenu>New</guimenu> → <guimenu>Seam Form</guimenu>:
</para>
<mediaobject>
<imageobject role="fo">
@@ -325,7 +325,7 @@
<section>
<title>Generating an application from an existing database</title>
<para>
- Manually create tables in your database. (To switch to a different database, create a new project, and select the correct database.) Then, select <guimenu>New</guimenu> → <guimenu>Seam Generate Entities</guimenu>:
+ Manually create tables in your database. (To switch to a different database, create a new project, and select the correct database.) Then, select <guimenu>New</guimenu> → <guimenu>Seam Generate Entities</guimenu>:
</para>
<mediaobject>
<imageobject role="fo">
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Gettingstarted.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Gettingstarted.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Gettingstarted.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -8,7 +8,7 @@
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 AS. You can use the generated project with other J2EE or Java EE 5 application servers by making a few manual changes to the project configuration.
+ In this release, <application>seam-gen</application> works best in conjunction with JBoss EAP.
</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.
@@ -16,7 +16,7 @@
<section>
<title>Before you start</title>
<para>
- Make sure you have JDK 5 or JDK 6 (see <xref linkend="jdk_dependencies" /> for details), JBoss AS 4.2 or 5.0 and <!-- #modify: Check Ant version; I thought we needed earlier versions to work with Seam? -->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.
+ 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 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:
@@ -47,13 +47,66 @@
You will receive the following prompt for the required information:
</para>
-<programlisting>~/workspace/jboss-seam$ ./seam setup Buildfile: build.xml init: setup: [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] /Applications/jboss-4.2.3.GA [input] Enter the project name [myproject] [myproject] helloworld [echo] Accepted project name as: helloworld [input] Select a RichFaces skin (not applicable if using ICEFaces) [blueSky] ([blueSky], classic, ruby, wine, deepMarine, emeraldTown, sakura, DEFAULT) [input] Is this project deployed as an EAR (with EJB components) or a WAR (with no EJB support) [ear] ([ear], war, ) [input] Enter the Java package name for your session beans [com.mydomain.helloworld] [com.mydomain.helloworld] org.jboss.helloworld [input] Enter the Java package name for your entity beans [org.jboss.helloworld] [or!
g.jboss.helloworld] [input] Enter the Java package name for your test cases [org.jboss.helloworld.test] [org.jboss.helloworld.test] [input] What kind of database are you using? [hsql] ([hsql], mysql, oracle, postgres, mssql, db2, sybase, enterprisedb, h2) mysql [input] Enter the Hibernate dialect for your database [org.hibernate.dialect.MySQLDialect] [org.hibernate.dialect.MySQLDialect] [input] Enter the filesystem path to the JDBC driver jar [lib/hsqldb.jar] [lib/hsqldb.jar] /Users/pmuir/java/mysql.jar [input] Enter JDBC driver class for your database [com.mysql.jdbc.Driver] [com.mysql.jdbc.Driver] [input] Enter the JDBC URL for your database [jdbc:mysql:///test] [jdbc:mysql:///test] jdbc:mysql:///helloworld [input] Enter database username [sa] [sa] pmuir [input] Enter database password [] [] [input] skipping input as property hibernate.default_schema.new has already been set. [input] Enter the database catalog name (it is OK to leave this blank) [] [] [input] Are you wor!
king with tables that already exist in the database? [n] (y, !
[n], ) y
[input] Do you want to drop and recreate the database tables and data in import.sql each time you deploy? [n] (y, [n], ) n [input] Enter your ICEfaces home directory (leave blank to omit ICEfaces) [] [] [propertyfile] Creating new property file: /Users/pmuir/workspace/jboss-seam/seam-gen/build.properties [echo] Installing JDBC driver jar to JBoss server [echo] Type 'seam create-project' to create the new project BUILD SUCCESSFUL Total time: 1 minute 32 seconds ~/workspace/jboss-seam $
+<programlisting><seam_distribution_dir>$ ./seam setup
+Buildfile: build.xml
+
+init:
+
+setup:
+ [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]
+/var/lib/jbossas
+ [input] Enter the project name [myproject] [myproject]
+helloworld
+ [echo] Accepted project name as: helloworld
+ [input] Select a RichFaces skin (not applicable if using ICEFaces) [blueSky] ([blueSky], classic, ruby, wine, deepMarine, emeraldTown, sakura, DEFAULT)
+
+ [input] Is this project deployed as an EAR (with EJB components) or a WAR (with no EJB support) [ear] ([ear], war, )
+
+ [input] Enter the Java package name for your session beans [com.mydomain.helloworld] [com.mydomain.helloworld]
+org.jboss.helloworld
+ [input] Enter the Java package name for your entity beans [org.jboss.helloworld] [org.jboss.helloworld]
+
+ [input] Enter the Java package name for your test cases [org.jboss.helloworld.test] [org.jboss.helloworld.test]
+
+ [input] What kind of database are you using? [hsql] ([hsql], mysql, oracle, postgres, mssql, db2, sybase, enterprisedb, h2)
+mysql
+ [input] Enter the Hibernate dialect for your database [org.hibernate.dialect.MySQLDialect] [org.hibernate.dialect.MySQLDialect]
+
+ [input] Enter the filesystem path to the JDBC driver jar [lib/hsqldb.jar] [lib/hsqldb.jar]
+/usr/share/java/mysql.jar
+ [input] Enter JDBC driver class for your database [com.mysql.jdbc.Driver] [com.mysql.jdbc.Driver]
+
+ [input] Enter the JDBC URL for your database [jdbc:mysql:///test] [jdbc:mysql:///test]
+jdbc:mysql:///helloworld
+ [input] Enter database username [sa] [sa]
+pmuir
+ [input] Enter database password [] []
+
+ [input] skipping input as property hibernate.default_schema.new has already been set.
+ [input] Enter the database catalog name (it is OK to leave this blank) [] []
+
+ [input] Are you working with tables that already exist in the database? [n] (y, [n], )
+y
+ [input] Do you want to drop and recreate the database tables and data in import.sql each time you deploy? [n] (y, [n], )
+n
+ [input] Enter your ICEfaces home directory (leave blank to omit ICEfaces) [] []
+
+[propertyfile] Creating new property file: /Users/pmuir/workspace/jboss-seam/seam-gen/build.properties
+ [echo] Installing JDBC driver jar to JBoss server
+ [echo] Type 'seam create-project' to create the new project
+
+BUILD SUCCESSFUL
+Total time: 1 minute 32 seconds
+~/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 AS 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.
+ 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.
@@ -68,10 +121,10 @@
<programlisting>C:\Projects\jboss-seam>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 jars, dependent jars and the JDBC driver jar 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 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.
+ 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>.
+ 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>.
@@ -99,7 +152,39 @@
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 validate-workspace: validate-project: action-input: [input] Enter the Seam component name ping [input] Enter the local interface name [Ping] [input] Enter the bean class name [PingBean] [input] Enter the action method name [ping] [input] Enter the page name [ping] setup-filters: new-action: [echo] Creating a new stateless session bean component with an action method [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld\test [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld\test [copy] Copying 1 file to C:\Projects\helloworld\view [echo] Type 'seam restart' and go to http://localhost:8080/helloworld/ping.seam BUILD SUCCESSFUL Total time: 13 seconds C:\Projects\jboss-seam>
+<programlisting>C:\Projects\jboss-seam>seam new-action
+Buildfile: build.xml
+
+validate-workspace:
+
+validate-project:
+
+action-input:
+ [input] Enter the Seam component name
+ping
+ [input] Enter the local interface name [Ping]
+
+ [input] Enter the bean class name [PingBean]
+
+ [input] Enter the action method name [ping]
+
+ [input] Enter the page name [ping]
+
+
+setup-filters:
+
+new-action:
+ [echo] Creating a new stateless session bean component with an action method
+ [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld
+ [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld
+ [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld\test
+ [copy] Copying 1 file to C:\Projects\helloworld\src\hot\org\jboss\helloworld\test
+ [copy] Copying 1 file to C:\Projects\helloworld\view
+ [echo] Type 'seam restart' and go to http://localhost:8080/helloworld/ping.seam
+
+BUILD SUCCESSFUL
+Total time: 13 seconds
+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.
@@ -126,7 +211,39 @@
<programlisting>seam new-form
</programlisting>
-<programlisting>C:\Projects\jboss-seam>seam new-form Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml validate-workspace: validate-project: action-input: [input] Enter the Seam component name hello [input] Enter the local interface name [Hello] [input] Enter the bean class name [HelloBean] [input] Enter the action method name [hello] [input] Enter the page name [hello] setup-filters: new-form: [echo] Creating a new stateful session bean component with an action method [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello\test [copy] Copying 1 file to C:\Projects\hello\view [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello\test [echo] Type 'seam restart' and go to http://localhost:8080/hello/hello.seam BUILD SUCCESSFUL Total time: 5 seconds C:\Projects\jboss-seam>
+<programlisting>C:\Projects\jboss-seam>seam new-form
+Buildfile: C:\Projects\jboss-seam\seam-gen\build.xml
+
+validate-workspace:
+
+validate-project:
+
+action-input:
+ [input] Enter the Seam component name
+hello
+ [input] Enter the local interface name [Hello]
+
+ [input] Enter the bean class name [HelloBean]
+
+ [input] Enter the action method name [hello]
+
+ [input] Enter the page name [hello]
+
+
+setup-filters:
+
+new-form:
+ [echo] Creating a new stateful session bean component with an action method
+ [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello
+ [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello
+ [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello\test
+ [copy] Copying 1 file to C:\Projects\hello\view
+ [copy] Copying 1 file to C:\Projects\hello\src\hot\com\hello\test
+ [echo] Type 'seam restart' and go to http://localhost:8080/hello/hello.seam
+
+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>. 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.)
@@ -248,7 +365,7 @@
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>
@@ -271,7 +388,7 @@
</para>
</section>
- </section>
+ </section>-->
</chapter>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Groovy.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Groovy.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Groovy.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -28,7 +28,40 @@
<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 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>
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.
@@ -41,7 +74,35 @@
You can write Seam components in Groovy exactly as you would in Java: annotations mark classes as Seam components.
</para>
-<programlisting role="JAVA">@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 @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() } 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 role="JAVA">@Scope(ScopeType.SESSION)
+ at Name("bookingList")
+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
+ where b.user.username = :username
+ 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])
+ }
+}
</programlisting>
</section>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Gwt.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Gwt.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Gwt.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -38,7 +38,24 @@
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) { 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. It's the real question that you seek now."; } public boolean validate(String q) { ValidationUtility util = new ValidationUtility(); return util.isValid(q); } }]]>
+<programlisting role="JAVA"><![CDATA[@Name("org.jboss.seam.example.remoting.gwt.client.MyService")
+public class ServiceImpl implements MyService {
+
+ @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.";
+ }
+
+ 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>.
@@ -51,13 +68,57 @@
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 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>
<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(); 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); initWidget(panel); } 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); } }); } ...]]>
+<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);
+
+ initWidget(panel);
+ }
+
+ 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);
+ }
+ });
+ }
+
+ ...]]>
</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.
@@ -96,7 +157,22 @@
This must point to the directory in which GWT is installed. Next, create a target:
</para>
-<programlisting role="XML"><![CDATA[<!-- the following 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 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).
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Hsearch.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Hsearch.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Hsearch.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -26,7 +26,18 @@
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 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.
@@ -78,7 +89,22 @@
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; 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 role="JAVA"><![CDATA[@Stateful
+ at Name("search")
+public class FullTextSearchAction implements FullTextSearch, Serializable {
+
+ @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>
@@ -98,7 +124,23 @@
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 { @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 role="JAVA"><![CDATA[@Stateful
+ at Name("search")
+public class FullTextSearchAction implements FullTextSearch, Serializable {
+
+ @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>
<note>
<para>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/I18n.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/I18n.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/I18n.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -18,7 +18,7 @@
<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. If you use Tomcat or JBoss AS, add the <literal>URIEncoding="UTF-8"</literal> attribute to the connector configuration. For JBoss AS 4.2, edit <literal>${JBOSS_HOME}/server/(default)/deploy/jboss-web.deployer/server. xml</literal>:
+ 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. If you use Tomcat or JBoss AS, add the <literal>URIEncoding="UTF-8"</literal> attribute to the connector configuration. For JBoss AS 4.2, edit <literal>${JBOSS_HOME}/server/(default)/deploy/jboss-web.deployer/server. xml</literal>:
</para>
<programlisting role="XML"><Connector port="8080" URIEncoding="UTF-8"/>
@@ -37,7 +37,7 @@
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 \uXXXX, where XXXX is the hexadecimal representation of the character.
+ 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.
@@ -232,7 +232,13 @@
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 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>
The first theme listed is the default theme.
@@ -262,7 +268,11 @@
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" 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 role="XHTML"><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>
<para>
Just like the locale selector, there is a built-in theme selector to allow the user to freely switch themes:
@@ -278,7 +288,15 @@
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"><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 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>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Itext.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Itext.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Itext.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -281,8 +281,21 @@
<emphasis>Usage</emphasis>
</para>
-<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> </p:html> <p:html> <s:formattedText value="*This* is |Seam Text| as HTML. It's very^cool^." /> </p:html> ]]>
-</programlisting>
+<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>
+</p:html>
+
+<p:html>
+ <s:formattedText value="*This* is |Seam Text| as HTML. It's very^cool^." />
+</p:html>
+]]></programlisting>
</entry>
</row>
<row>
@@ -557,7 +570,14 @@
<emphasis>Usage</emphasis>
</para>
-<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 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>
</entry>
</row>
@@ -634,7 +654,20 @@
<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 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>
@@ -664,7 +697,14 @@
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 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">
@@ -717,7 +757,11 @@
<emphasis>Usage</emphasis>
</para>
-<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 role="XHTML"><![CDATA[<p:list style="numbered">
+ <ui:repeat value="#{documents}" var="doc">
+ <p:listItem>#{doc.name}</p:listItem>
+ </ui:repeat>
+</p:list>]]>
</programlisting>
</entry>
</row>
@@ -889,7 +933,16 @@
<emphasis>Usage</emphasis>
</para>
-<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> <ui:repeat value="#{documents}" var="doc"> <p:cell>#{doc.name}</p:cell> <p:cell>#{doc.user.name}</p:cell> <p:cell>#{doc.size}</p:cell> </ui:repeat> </p:table>]]>
+<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>
+ <ui:repeat value="#{documents}" var="doc">
+ <p:cell>#{doc.name}</p:cell>
+ <p:cell>#{doc.user.name}</p:cell>
+ <p:cell>#{doc.size}</p:cell>
+ </ui:repeat>
+</p:table>]]>
</programlisting>
</entry>
</row>
@@ -1244,7 +1297,16 @@
<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 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>
@@ -1430,7 +1492,16 @@
<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 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>
@@ -1571,7 +1642,16 @@
<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 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>
@@ -1992,7 +2072,13 @@
</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 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>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Jbpm.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Jbpm.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Jbpm.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -55,13 +55,48 @@
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>guess</from-outcome> <to-view-id>/numberGuess.jsp</to-view-id> <redirect/> </navigation-case> <navigation-case> <from-outcome>win</from-outcome> <to-view-id>/win.jsp</to-view-id> <redirect/> </navigation-case> <navigation-case> <from-outcome>lose</from-outcome> <to-view-id>/lose.jsp</to-view-id> <redirect/> </navigation-case> </navigation-rule>]]>
+<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>
+
+ <navigation-case>
+ <from-outcome>win</from-outcome>
+ <to-view-id>/win.jsp</to-view-id>
+ <redirect/>
+ </navigation-case>
+
+ <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> <rule if-outcome="win"> <redirect view-id="/win.jsp"/> </rule> <rule if-outcome="lose"> <redirect view-id="/lose.jsp"/> </rule> </navigation> </page>]]>
+<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 too verbose, you can return view IDs directly from your action listener methods:
@@ -82,7 +117,36 @@
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="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="lose" view-id="/lose.jsp"> <redirect/> <end-conversation /> </page> </pageflow-definition>]]>
+<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="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="lose" view-id="/lose.jsp">
+ <redirect/>
+ <end-conversation />
+ </page>
+
+</pageflow-definition>]]>
</programlisting>
<mediaobject>
<imageobject role="fo">
@@ -98,7 +162,7 @@
<itemizedlist>
<listitem>
<para>
- The JSF/Seam navigation rules are much simpler. (However, this obscures the fact that the underlying Java code is more complex.)
+ 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>
@@ -111,7 +175,7 @@
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 stateful/stateless navigation distinction is similar to the traditional view of modal/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.
+ 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.
@@ -133,7 +197,13 @@
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 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.
@@ -147,7 +217,14 @@
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 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.
@@ -195,7 +272,25 @@
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><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="notFound" view-id="/404.jsp"> <end-conversation/> </page> </pageflow-definition>]]>
+<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="notFound" view-id="/404.jsp">
+ <end-conversation/>
+ </page>
+
+</pageflow-definition>]]>
</programlisting>
</section>
@@ -298,7 +393,22 @@
A simple business process definition resembles a pageflow definition, except that instead of <literal><page></literal> nodes, we use <literal><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> <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 role="XML"><![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"/>
+
+</process-definition>]]>
</programlisting>
<mediaobject>
<imageobject role="fo">
@@ -321,7 +431,11 @@
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 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.
@@ -334,7 +448,14 @@
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; public String login() { ... actor.setId( user.getUserName() ); actor.getGroupActorIds().addAll( user.getGroupNames() ); ... }]]>
+<programlisting role="JAVA"><![CDATA[@In Actor actor;
+
+public String login() {
+ ...
+ actor.setId( user.getUserName() );
+ actor.getGroupActorIds().addAll( user.getGroupNames() );
+ ...
+}]]>
</programlisting>
</section>
@@ -376,7 +497,15 @@
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 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 can use a plain JSF <literal><h:commandLink></literal>:
@@ -391,7 +520,15 @@
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 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>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Jms.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Jms.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Jms.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -8,7 +8,7 @@
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 overkill. Seam layers a simple, asynchronous method and event facility over your choice of <emphasis>dispatchers</emphasis>:
+ 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>
@@ -27,6 +27,7 @@
</para>
</listitem>
</itemizedlist>
+
<section>
<title>Asynchronicity</title>
<para>
@@ -56,7 +57,12 @@
For EJB components, annotate the local interface to specify that a method be processed asynchronously:
</para>
-<programlisting role="JAVA"><![CDATA[@Local public interface PaymentHandler { @Asynchronous public void processPayment(Payment payment); }]]>
+<programlisting role="JAVA"><![CDATA[@Local
+public interface PaymentHandler
+{
+ @Asynchronous
+ public void processPayment(Payment payment);
+}]]>
</programlisting>
<para>
For JavaBean components, you can also annotate the component class.
@@ -65,13 +71,33 @@
The use of asynchronicity is transparent to the bean class:
</para>
-<programlisting role="JAVA"><![CDATA[@Stateless @Name("paymentHandler") public class PaymentHandlerBean implements PaymentHandler { public void processPayment(Payment payment) { //do some work! } }]]>
+<programlisting role="JAVA"><![CDATA[@Stateless
+ at Name("paymentHandler")
+public class PaymentHandlerBean implements PaymentHandler
+{
+ public void processPayment(Payment payment)
+ {
+ //do some work!
+ }
+}]]>
</programlisting>
<para>
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; public String pay() { paymentHandler.processPayment( new Payment(bill) ); return "success"; } }]]>
+<programlisting role="JAVA"><![CDATA[@Stateful
+ at Name("paymentAction")
+public class CreatePaymentAction
+{
+ @In(create=true) PaymentHandler paymentHandler;
+ @In Bill bill;
+
+ 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.
@@ -80,22 +106,82 @@
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); @Asynchronous public void processRecurringPayment(Payment payment, @Expiration Date date, @IntervalDuration Long interval)' }]]>
+<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 @Name("paymentAction") public class CreatePaymentAction { @In(create=true) PaymentHandler paymentHandler; @In Bill bill; 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 role="JAVA"><[CDATA[@Stateful
+ at Name("paymentAction")
+public class CreatePaymentAction
+{
+ @In(create=true) PaymentHandler paymentHandler;
+ @In Bill bill;
+
+ 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 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 role="JAVA"><[CDATA[@Local
+public interface PaymentHandler
+{
+ @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 Timer processScheduledPayment(Payment payment, @Expiration Date date) { //do some work! return timer; //note that return value is completely ignored } }]]>
+<programlisting role="JAVA"><![CDATA[@Stateless
+ at Name("paymentHandler")
+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 @Name("paymentAction") public class CreatePaymentAction { @In(create=true) PaymentHandler paymentHandler; @In Bill bill; public String schedulePayment() { Timer timer = paymentHandler.processScheduledPayment( new Payment(bill), bill.getDueDate() ); return "success"; } }]]>
+<programlisting role="JAVA"><![CDATA[@Stateful
+ at Name("paymentAction")
+public class CreatePaymentAction
+{
+ @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.
@@ -111,31 +197,117 @@
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; // 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 } ... ... // 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 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
+ }
+
+ ... ...
+
+ // 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 // later ... // Retrieve payment from DB // Cancel the remaining scheduled tasks payment.getQuartzTriggerHandle().cancel(); ]]>
+<programlisting role="JAVA"><[CDATA[QuartzTriggerHandle handle =
+ processor.schedulePayment(payment.getPaymentDate(),
+ payment.getPaymentCron(),
+ payment);
+ payment.setQuartzTriggerHandle( handle );
+ // Save payment to DB
+
+ // 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 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 @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 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
+ }
+
+ ... ...
+
+ // 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 @Asynchronous public QuartzTriggerHandle schedulePayment(@Expiration Date when, @IntervalBusinessDay NthBusinessDay nth, 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 role="JAVA"><![CDATA[
+ // Define the method
+ @Asynchronous
+ public QuartzTriggerHandle schedulePayment(@Expiration Date when,
+ @IntervalBusinessDay NthBusinessDay nth,
+ 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>
<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; public enum BusinessDayIntervalType { WEEKLY, MONTHLY, YEARLY } public NthBusinessDay () { n = 1; fireAtTime = "12:00"; additionalHolidays = new ArrayList <Date> (); interval = BusinessDayIntervalType.WEEKLY; excludeWeekends = true; excludeUsFederalHolidays = true; } ... ... } ]]>
+<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 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. Attempting to use them in the same method will cause a <exceptionname>RuntimeException</exceptionname> error.
@@ -158,7 +330,21 @@
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; @In Future timer; @Override public void handleException(Exception exception) { log.debug(exception); timer.cancel(false); } }]]>
+<programlisting role="JAVA"><![CDATA[@Scope(ScopeType.STATELESS)
+ at Name("org.jboss.seam.async.asynchronousExceptionHandler")
+public class MyAsynchronousExceptionHandler extends AsynchronousExceptionHandler {
+
+ @Logger Log log;
+
+ @In Future timer;
+
+ @Override
+ public void handleException(Exception exception) {
+ log.debug(exception);
+ timer.cancel(false);
+ }
+
+}]]>
</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.
@@ -190,7 +376,13 @@
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 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>
@@ -200,21 +392,116 @@
Once configuration is complete, you can inject a JMS <literal>TopicPublisher</literal> and <literal>TopicSession</literal> into any component:
</para>
-<programlisting role="JAVA"><![CDATA[@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 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[@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 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.
+ 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>
+ First, create a message-driven bean 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>
+ 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>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Mail.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Mail.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Mail.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -22,7 +22,23 @@
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"> <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:message>]]>
+<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: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 specify the sender, a <literal><m:to></literal> tag to specify a recipient, and a <literal><m:subject></literal> tag. (Note that EL is used as it would be in a normal Facelet.)
@@ -34,7 +50,18 @@
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 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 is thrown, caught and then displayed to the user.
@@ -75,22 +102,34 @@
You can attach a Seam-generated PDF, or any standard JSF view, by wrapping a <literal><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 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><ui:repeat></literal>:
+ To attach a set of files — for example, a set of pictures loaded from a database — you can use a <literal><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 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 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.
+ 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.
@@ -103,7 +142,9 @@
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 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>
@@ -113,17 +154,26 @@
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><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 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><ui:repeat></literal>:
+ 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><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 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>
@@ -136,13 +186,28 @@
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 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 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.)
@@ -158,7 +223,9 @@
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 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:
@@ -198,7 +265,26 @@
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; public void onMessage(Message message) { // Process the message orderProcessor.process(message.getSubject()); } }]]>
+<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")
+})
+ at ResourceAdapter("mail-ra.rar")
+ at Name("mailListener")
+public class MailListenerMDB implements MailListener {
+
+ @In(create=true)
+ private OrderProcessor orderProcessor;
+
+ public void onMessage(Message message) {
+ // Process the message
+ orderProcessor.process(message.getSubject());
+ }
+
+}]]>
</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.
@@ -230,7 +316,7 @@
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 mailSession component's properties are described in more detail in <xref linkend="components.mail" />.
+ 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>
@@ -238,7 +324,13 @@
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 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.
@@ -266,7 +358,7 @@
</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>.
+ 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>
@@ -289,27 +381,27 @@
<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>.
+ <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>.
+ <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>.
+ <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><h:graphicImage></literal> in your emails.
+ <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> — Explicitly sets the Message-ID.
+ <literal>messageId</literal> — Explicitly sets the Message-ID.
</para>
</listitem>
</itemizedlist>
@@ -324,12 +416,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>name</literal> — The name that the email comes from.
+ <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.
+ <literal>address</literal> — The email address that the email comes from.
</para>
</listitem>
</itemizedlist>
@@ -344,7 +436,7 @@
<itemizedlist>
<listitem>
<para>
- <literal>address</literal> — the email address the email comes from.
+ <literal>address</literal> — the email address the email comes from.
</para>
</listitem>
</itemizedlist>
@@ -359,12 +451,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>name</literal> — The name of the recipient.
+ <literal>name</literal> — The name of the recipient.
</para>
</listitem>
<listitem>
<para>
- <literal>address</literal> — The email address of the recipient.
+ <literal>address</literal> — The email address of the recipient.
</para>
</listitem>
</itemizedlist>
@@ -379,12 +471,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>name</literal> — The name of the recipient.
+ <literal>name</literal> — The name of the recipient.
</para>
</listitem>
<listitem>
<para>
- <literal>address</literal> — The email address of the recipient.
+ <literal>address</literal> — The email address of the recipient.
</para>
</listitem>
</itemizedlist>
@@ -399,12 +491,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>name</literal> — The name of the recipient.
+ <literal>name</literal> — The name of the recipient.
</para>
</listitem>
<listitem>
<para>
- <literal>address</literal> — The email address of the recipient.
+ <literal>address</literal> — The email address of the recipient.
</para>
</listitem>
</itemizedlist>
@@ -419,12 +511,12 @@
<itemizedlist>
<listitem>
<para>
- <literal>name</literal> — The name of the header to add. (For example, <literal>X-Sent-From</literal>.)
+ <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>.)
+ <literal>value</literal> — The value of the header to add. (For example, <literal>JBoss Seam</literal>.)
</para>
</listitem>
</itemizedlist>
@@ -439,32 +531,32 @@
<itemizedlist>
<listitem>
<para>
- <literal>value</literal> — The file to attach:
+ <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.
+ <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.
+ <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.
+ <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.
+ <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.
+ <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>
@@ -486,12 +578,12 @@
</listitem>
<listitem>
<para>
- <literal>fileName</literal> — Specifies the file name to use for the attached file.
+ <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.
+ <literal>contentType</literal> — Specifies the MIME type of the attached file.
</para>
</listitem>
</itemizedlist>
@@ -514,7 +606,7 @@
<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.
+ <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>
Added: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Migration.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Migration.xml (rev 0)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Migration.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -0,0 +1,586 @@
+<?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>
+ <para>
+ Seam 2.0 has been successfully tested in the following container environments:
+ </para>
+ <itemizedlist>
+ <listitem>
+ <para>
+ JBoss 4.2
+ </para>
+ <note>
+ <para>
+ It is also possible to run Seam 2.0 on JBoss 4.0.5 by upgrading JavaServer Faces (JSF)
+to version 1.2.
+ </para>
+ </note>
+ </listitem>
+ <listitem>
+ <para>
+ Apache Tomcat 6.0 — Tomcat 5.5 is <emphasis>not compatible</emphasis> with JSF 1.2.
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ GlassFish 2.0
+ </para>
+ </listitem>
+ <listitem>
+ <para>
+ Oracle Containers for J2EE 11g (Technology Preview)
+ </para>
+ </listitem>
+ </itemizedlist>
+ <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"><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><faces-config></literal> root tag, like so:</para>
+ <programlisting role="XML"><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><core:managed-persistence-context></literal> with <literal><persistence:managed-persistence-context></literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Replace <literal><core:entity-manager-factory></literal> with <literal><persistence:entity-manager-factory></literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Remove <varname>conversation-is-long-running</varname> parameter from <literal><core:manager/></literal> element.</para>
+ </listitem>
+ <listitem>
+ <para>Remove <literal><core:ejb/></literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Remove <literal><core:microcontainer/></literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Replace <literal><core:transaction-listener/></literal> with <literal><transaction:ejb-transaction/></literal>.</para>
+ </listitem>
+ <listitem>
+ <para>Replace <literal><core:resource-bundle/></literal> with <literal><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">
+<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"><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"><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><s:selectDate></literal> has been deprecated in favour of <literal><rich:calendar></literal>. There will be no further development of <literal><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><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"><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><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><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>
+ at In private Session hibernateSession;
+ </programlisting>
+ <programlisting>
+ 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>
+<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>
+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>
+ <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>
+ <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>
+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>
+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"><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>
+<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><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">
+<cache:jboss-pojo-cache-provider />
+ </programlisting>
+ <para>
+ Then, inject it:
+ </para>
+ <programlisting>
+ at 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 <emphasis>provided</emphasis> platform is now JBoss AS 4.2.3, 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: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Performance.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Performance.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Performance.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -10,7 +10,7 @@
<section>
<title>Bypassing Interceptors</title>
<para>
- For repetitive value bindings such as those found in a JavaServer Faces (JSF) dataTable, 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>.
+ 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>
@@ -21,7 +21,24 @@
The following code listing demonstrates a Seam component with its interceptors disabled:
</para>
-<programlisting><![CDATA[@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"); // 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><![CDATA[@Name("foo")
+ at Scope(EVENT)
+ at 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");
+
+ // 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>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Persistence.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Persistence.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Persistence.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -88,7 +88,9 @@
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"/> <transaction:no-transaction />]]>
+<programlisting role="XML"><![CDATA[<core:init transaction-management-enabled="false"/>
+
+<transaction:no-transaction />]]>
</programlisting>
</section>
@@ -202,13 +204,24 @@
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"/> <persistence:managed-hibernate-session name="bookingDatabase" auto-create="true" session-factory-jndi-name="java:/bookingSessionFactory"/>]]>
+<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>
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 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>
@@ -238,13 +251,21 @@
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 role="JAVA"><![CDATA[@In EntityManager em; //a Seam-managed persistence context
+
+ at 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 entire conversation. We can make changes to the claim:
</para>
-<programlisting role="JAVA"><![CDATA[public void addPartyToClaim() { Party party = ....; claim.addParty(party); }]]>
+<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:
@@ -289,7 +310,12 @@
The session can now be injected directly:
</para>
-<programlisting role="JAVA"><![CDATA[@In Session session; @Create public void init() { session.enableFilter("currentVersions"); }]]>
+<programlisting role="JAVA"><![CDATA[@In Session session;
+
+ at Create
+public void init() {
+ session.enableFilter("currentVersions");
+}]]>
</programlisting>
</section>
@@ -329,7 +355,29 @@
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: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 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: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>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Remoting.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Remoting.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Remoting.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -13,7 +13,15 @@
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 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>
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:
@@ -109,7 +117,38 @@
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">@Name("customer") @Entity public class Customer implements Serializable { private Integer customerId; private String firstName; private String lastName; @Column public Integer getCustomerId() { return customerId; } public void setCustomerId(Integer customerId} { this.customerId = customerId; } @Column public String getFirstName() { return firstName; } public void setFirstName(String firstName) { this.firstName = firstName; } @Column public String getLastName() { return lastName; } public void setLastName(String lastName) { this.lastName = lastName; } }
+<programlisting role="JAVA">@Name("customer")
+ at Entity
+public class Customer implements Serializable
+{
+ private Integer customerId;
+ private String firstName;
+ private String lastName;
+
+ @Column public Integer getCustomerId() {
+ return customerId;
+ }
+
+ public void setCustomerId(Integer customerId} {
+ this.customerId = customerId;
+ }
+
+ @Column public String getFirstName() {
+ return firstName;
+ }
+
+ public void setFirstName(String firstName) {
+ this.firstName = firstName;
+ }
+
+ @Column public String getLastName() {
+ return lastName;
+ }
+
+ public void setLastName(String lastName) {
+ this.lastName = lastName;
+ }
+}
</programlisting>
<para>
To create a client-side Customer you would write the following code:
@@ -144,7 +183,10 @@
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 role="XHTML">if (Seam.Component.getComponentName(instance) == "customer")
+ alert("Customer");
+else if (Seam.Component.getComponentName(instance) == "staff")
+ alert("Staff member");
</programlisting>
</section>
@@ -182,7 +224,14 @@
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()); } } Seam.Remoting.eval("#{customers}", customersCallback); ]]>
+<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>
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:
@@ -448,7 +497,16 @@
The examples that follow are all based on this <literal>Widget</literal> class:
</para>
-<programlisting role="JAVA">@Name("widget") public class Widget { private String value; private String secret; private Widget child; private Map<String,Widget> widgetMap; private List<Widget> widgetList; // getters and setters for all fields }
+<programlisting role="JAVA">@Name("widget")
+public class Widget
+{
+ private String value;
+ private String secret;
+ private Widget child;
+ private Map<String,Widget> widgetMap;
+ private List<Widget> widgetList;
+
+ // getters and setters for all fields
</programlisting>
<section>
<title>Constraining normal fields</title>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Seam_Reference_Guide.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Seam_Reference_Guide.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Seam_Reference_Guide.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -5,6 +5,7 @@
<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" />
@@ -15,7 +16,7 @@
<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="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" />
@@ -23,7 +24,7 @@
<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="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" />
@@ -37,11 +38,12 @@
<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="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>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Security.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Security.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Security.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -94,7 +94,18 @@
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.1.xsd http://jboss.com/products/seam/security http://jboss.com/products/seam/security-2.1.xsd"> <security:identity authenticate-method="#{authenticator.authenticate}"/> </components>]]>
+<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.1.xsd
+ http://jboss.com/products/seam/security http://jboss.com/products/seam/security-2.1.xsd">
+
+<security:identity authenticate-method="#{authenticator.authenticate}"/>
+
+</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.
@@ -107,7 +118,34 @@
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; 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()); } return true; } catch (NoResultException ex) { return false; } } }]]>
+<programlisting role="JAVA"> <![CDATA[@Name("authenticator")
+public class Authenticator {
+ @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();
+
+ if (user.getRoles() != null) {
+ for (UserRole mr : user.getRoles())
+ identity.addRole(mr.getName());
+ }
+
+ return true;
+ }
+ catch (NoResultException ex) {
+ return false;
+ }
+
+ }
+
+}]]>
</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.
@@ -141,7 +179,14 @@
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[ @In UserStats userStats; @Observer("org.jboss.seam.security.loginSuccessful") public void updateUserStats() { userStats.setLastLoginDate(new Date()); userStats.incrementLoginCount(); }]]>
+<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. More information about other security-related events appears later in the chapter.
@@ -156,7 +201,19 @@
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}"/> </div> <div> <h:commandButton value="Login" action="#{identity.login}"/> </div>]]>
+<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}"/>
+</div>
+
+<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.
@@ -207,7 +264,20 @@
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 class="loginRow"> <h:outputLabel for="rememberMe" value="Remember me"/> <h:selectBooleanCheckbox id="rememberMe" value="#{rememberMe.enabled}"/> </div>]]>
+<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 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>
@@ -218,7 +288,39 @@
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; @Id @GeneratedValue public Integer getTokenId() { return tokenId; } public void setTokenId(Integer tokenId) { this.tokenId = tokenId; } @TokenUsername public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } @TokenValue public String getValue() { return value; } public void setValue(String value) { this.value = value; } }]]>
+<programlisting role="JAVA"><![CDATA[@Entity
+public class AuthenticationToken implements Serializable {
+ private Integer tokenId;
+ private String username;
+ private String value;
+
+ @Id @GeneratedValue
+ public Integer getTokenId() {
+ return tokenId;
+ }
+
+ public void setTokenId(Integer tokenId) {
+ this.tokenId = tokenId;
+ }
+
+ @TokenUsername
+ public String getUsername() {
+ return username;
+ }
+
+ public void setUsername(String username) {
+ this.username = username;
+ }
+
+ @TokenValue
+ public String getValue() {
+ return value;
+ }
+
+ 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.
@@ -242,7 +344,13 @@
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 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>
@@ -269,7 +377,24 @@
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> ... <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 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 more sophisticated handling of login redirection. Seam includes some special functionality, outlined in the following section.
@@ -282,7 +407,11 @@
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"> <page view-id="/members/*" login-required="true"/> ... </pages>]]>
+<programlisting role="XML"><![CDATA[<pages login-view-id="/login.xhtml">
+
+<page view-id="/members/*" login-required="true"/>
+...
+</pages>]]>
</programlisting>
<note>
<para>
@@ -293,7 +422,13 @@
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"><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 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>
<note>
<para>
@@ -325,7 +460,24 @@
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 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>
</section>
@@ -381,13 +533,18 @@
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 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 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.
@@ -405,7 +562,11 @@
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 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>
@@ -652,10 +813,48 @@
</imageobject>
</mediaobject>
-<programlisting role="JAVA"><![CDATA[@Entity public class User { private Integer userId; private String username; private String passwordHash; private Set<Role> roles; @Id @GeneratedValue public Integer getUserId() { return userId; } public void setUserId(Integer userId) { this.userId = userId; } @UserPrincipal public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } @UserPassword(hash = "md5") public String getPasswordHash() { return 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")) public Set<Role> getRoles() { return roles; } public void setRoles(Set<Role> roles) { this.roles = roles; } }]]>
+<programlisting role="JAVA"><![CDATA[@Entity
+public class User {
+ private Integer userId;
+ private String username;
+ private String passwordHash;
+ private Set<Role> roles;
+
+ @Id @GeneratedValue
+ public Integer getUserId() { return userId; }
+ public void setUserId(Integer userId) { this.userId = userId; }
+
+ @UserPrincipal
+ public String getUsername() { return username; }
+ public void setUsername(String username) { this.username = username; }
+
+ @UserPassword(hash = "md5")
+ public String getPasswordHash() { return 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"))
+ public Set<Role> getRoles() { return roles; }
+ public void setRoles(Set<Role> roles) { this.roles = roles; }
+}]]>
</programlisting>
-<programlisting> <![CDATA[@Entity public class Role { private Integer roleId; private String rolename; @Id @Generated public Integer getRoleId() { return roleId; } public void setRoleId(Integer roleId) { this.roleId = roleId; } @RoleName public String getRolename() { return rolename; } public void setRolename(String rolename) { this.rolename = rolename; } }]]>
+<programlisting> <[CDATA[@Entity
+public class Role {
+ private Integer roleId;
+ private String rolename;
+
+ @Id @Generated
+ public Integer getRoleId() { return roleId; }
+ public void setRoleId(Integer roleId) { this.roleId = roleId; }
+
+ @RoleName
+ public String getRolename() { return rolename; }
+ public void setRolename(String rolename) { this.rolename = rolename; }
+}]]>
</programlisting>
</section>
@@ -673,10 +872,77 @@
</imageobject>
</mediaobject>
-<programlisting role="JAVA"><![CDATA[@Entity public class User { private Integer userId; private String username; private String passwordHash; private Set<Role> roles; private String firstname; private String lastname; private boolean enabled; @Id @GeneratedValue public Integer getUserId() { return userId; } public void setUserId(Integer userId) { this.userId = userId; } @UserPrincipal public String getUsername() { return username; } public void setUsername(String username) { this.username = username; } @UserPassword(hash = "md5") public String getPasswordHash() { return passwordHash; } public void setPasswordHash(String passwordHash) { this.passwordHash = passwordHash; } @UserFirstName public String getFirstname() { return firstname; } public void setFirstname(String firstname) { this.firstname = firstname; } @UserLastName public String getLastname() { return lastname; } public void setLastname(String lastname) { this.lastname = lastname; } @UserEnabled public boo!
lean isEnabled() { return enabled; } public void setEnabled(boolean enabled) { this.enabled = enabled; } @UserRoles @ManyToMany(targetEntity = Role.class) @JoinTable(name = "UserRoles", joinColumns = @JoinColumn(name = "UserId"), inverseJoinColumns = @JoinColumn(name = "RoleId")) public Set<Role> getRoles() { return roles; } public void setRoles(Set<Role> roles) { this.roles = roles; } }]]>
+<programlisting role="JAVA"><![CDATA[@Entity
+public class User {
+ private Integer userId;
+ private String username;
+ private String passwordHash;
+ private Set<Role> roles;
+ private String firstname;
+ private String lastname;
+ private boolean enabled;
+
+ @Id @GeneratedValue
+ public Integer getUserId() { return userId; }
+ public void setUserId(Integer userId) { this.userId = userId; }
+
+ @UserPrincipal
+ public String getUsername() { return username; }
+ public void setUsername(String username) { this.username = username; }
+
+ @UserPassword(hash = "md5")
+ public String getPasswordHash() { return passwordHash; }
+ public void setPasswordHash(String passwordHash) { this.passwordHash = passwordHash; }
+
+ @UserFirstName
+ public String getFirstname() { return firstname; }
+ public void setFirstname(String firstname) { this.firstname = firstname; }
+
+ @UserLastName
+ public String getLastname() { return lastname; }
+ public void setLastname(String lastname) { this.lastname = lastname; }
+
+ @UserEnabled
+ public boolean isEnabled() { return enabled; }
+ public void setEnabled(boolean enabled) { this.enabled = enabled; }
+
+ @UserRoles
+ @ManyToMany(targetEntity = Role.class)
+ @JoinTable(name = "UserRoles",
+ 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><![CDATA[@Entity public class Role { private Integer roleId; private String rolename; private boolean conditional; @Id @Generated public Integer getRoleId() { return roleId; } public void setRoleId(Integer roleId) { this.roleId = roleId; } @RoleName public String getRolename() { return rolename; } public void setRolename(String rolename) { this.rolename = rolename; } @RoleConditional public boolean isConditional() { return 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")) public Set<Role> getGroups() { return groups; } public void setGroups(Set<Role> groups) { this.groups = groups; } }]]>
+<programlisting><![CDATA[@Entity
+public class Role {
+ private Integer roleId;
+ private String rolename;
+ private boolean conditional;
+
+ @Id @Generated
+ public Integer getRoleId() { return roleId; }
+ public void setRoleId(Integer roleId) { this.roleId = roleId; }
+
+ @RoleName
+ public String getRolename() { return rolename; }
+ public void setRolename(String rolename) { this.rolename = rolename; }
+
+ @RoleConditional
+ public boolean isConditional() { return 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"))
+ public Set<Role> getGroups() { return groups; }
+ public void setGroups(Set<Role> groups) { this.groups = groups; }
+
+}]]>
</programlisting>
</section>
@@ -1136,7 +1402,22 @@
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 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>
@@ -1836,7 +2117,26 @@
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 check: PermissionCheck(name == "seam.user", granted == false) Role(name == "admin") then check.grant(); end rule ManageRoles no-loop activation-group "permissions" when check: PermissionCheck(name == "seam.role", granted == false) Role(name == "admin") then check.grant(); end ]]>
+<programlisting><![CDATA[rule ManageUsers
+ no-loop
+ activation-group "permissions"
+when
+ check: PermissionCheck(name == "seam.user", granted == false)
+ Role(name == "admin")
+then
+ check.grant();
+end
+
+rule ManageRoles
+ no-loop
+ activation-group "permissions"
+when
+ check: PermissionCheck(name == "seam.role", granted == false)
+ Role(name == "admin")
+then
+ check.grant();
+end
+]]>
</programlisting>
</section>
@@ -1985,13 +2285,27 @@
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 role="JAVA"><![CDATA[@Name("account")
+public class AccountAction {
+ @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 role="JAVA"><![CDATA[@Restrict @Name("account")
+public class AccountAction {
+ 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.
@@ -2003,7 +2317,14 @@
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 role="JAVA"><![CDATA[@Name("account")
+public class AccountAction {
+ @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.
@@ -2025,7 +2346,11 @@
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"); if (!Identity.instance().hasPermission("customer", "create")) throw new AuthorizationException("You may not create new customers");]]>
+<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>
</section>
@@ -2046,7 +2371,8 @@
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 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><s:div></literal> or <literal><s:span></literal> control.
@@ -2055,7 +2381,23 @@
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 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>
@@ -2087,7 +2429,12 @@
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 role="JAVA"><![CDATA[@Entity
+ at Name("customer")
+ at Restrict
+public class Customer {
+ ...
+}]]>
</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>.
@@ -2129,7 +2476,17 @@
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"> <entity class="Customer"> <pre-persist method-name="prePersist" /> </entity> </entity-mappings>]]>
+<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">
+
+ <entity class="Customer">
+ <pre-persist method-name="prePersist" />
+ </entity>
+
+</entity-mappings>]]>
</programlisting>
<para>
You will still need to annotate the <literal>prePersist()</literal> method on <literal>Customer</literal> with <literal>@Restrict</literal>.
@@ -2139,7 +2496,16 @@
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) then check.grant(); end;]]>
+<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)
+then
+ check.grant();
+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? -->
@@ -2153,7 +2519,21 @@
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" 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> </entity-mappings>]]>
+<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">
+
+ <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>
</section>
@@ -2215,7 +2595,14 @@
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 role="JAVA"><![CDATA[@Target({METHOD, PARAMETER})
+ at Documented
+ at Retention(RUNTIME)
+ at Inherited
+ at PermissionCheck
+public @interface Promote {
+ 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:
@@ -2231,7 +2618,13 @@
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><![CDATA[@Target({METHOD})
+ at Documented
+ at Retention(RUNTIME)
+ at Inherited
+ at RoleCheck
+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>).
@@ -2438,7 +2831,24 @@
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.1.xsd http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.1.xsd http://jboss.com/products/seam/drools http://jboss.com/products/seam/drools-2.1.xsd" http://jboss.com/products/seam/security http://jboss.com/products/seam/security-2.1.xsd"> <drools:rule-base name="securityRules"> <drools:rule-files> <value>/META-INF/security.drl</value> </drools:rule-files> </drools:rule-base> </components>]]>
+<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>
+
+ </components>]]>
</programlisting>
<para>
The default rule base name can be overridden by specifying the <literal>security-rules</literal> property for <literal>RuleBasedPermissionResolver</literal>:
@@ -2460,7 +2870,18 @@
We recommend the Drools documentation when you write your rules file. A simple example of rules file contents is:
</para>
-<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><![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>
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.
@@ -2518,7 +2939,17 @@
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) Role(name == "user") then check.grant(); end ]]>
+<programlisting><![CDATA[rule CanCreateBlogComment
+ no-loop
+ activation-group "permissions"
+when
+ blog: MemberBlog()
+ check: PermissionCheck(target == blog, action == "create", granted == false)
+ Role(name == "user")
+then
+ check.grant();
+end
+]]>
</programlisting>
</section>
@@ -2528,7 +2959,14 @@
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><![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.
@@ -2874,7 +3312,61 @@
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; @Id @GeneratedValue public Integer getPermissionId() { return permissionId; } public void setPermissionId(Integer permissionId) { this.permissionId = permissionId; } @PermissionUser @PermissionRole public String getRecipient() { return recipient; } public void setRecipient(String recipient) { this.recipient = recipient; } @PermissionTarget public String getTarget() { return target; } public void setTarget(String target) { this.target = target; } @PermissionAction public String getAction() { return action; } public void setAction(String action) { this.action = action; } @PermissionDiscriminator public String getDiscriminator() { return discriminator; } public void setDiscriminator(String discriminator) { this.discriminator = discriminator; !
} } ]]>
+<programlisting role="JAVA"><![CDATA[
+ at Entity
+public class AccountPermission implements Serializable {
+ private Integer permissionId;
+ private String recipient;
+ private String target;
+ private String action;
+ private String discriminator;
+
+ @Id @GeneratedValue
+ public Integer getPermissionId() {
+ return permissionId;
+ }
+
+ public void setPermissionId(Integer permissionId) {
+ this.permissionId = permissionId;
+ }
+
+ @PermissionUser @PermissionRole
+ public String getRecipient() {
+ return recipient;
+ }
+
+ public void setRecipient(String recipient) {
+ this.recipient = recipient;
+ }
+
+ @PermissionTarget
+ public String getTarget() {
+ return target;
+ }
+
+ public void setTarget(String target) {
+ this.target = target;
+ }
+
+ @PermissionAction
+ public String getAction() {
+ return action;
+ }
+
+ public void setAction(String action) {
+ this.action = action;
+ }
+
+ @PermissionDiscriminator
+ public String getDiscriminator() {
+ return discriminator;
+ }
+
+ 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.
@@ -2953,7 +3445,12 @@
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") }) @Entity public class MemberImage implements Serializable {]]>
+<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>.
@@ -2969,7 +3466,12 @@
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) }) @Entity public class MemberImage implements Serializable {]]>
+<programlisting role="JAVA"><![CDATA[@Permissions({
+ @Permission(action = "view", mask = 1),
+ @Permission(action = "comment", mask = 2)
+})
+ 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.
@@ -3037,7 +3539,22 @@
Assume we have the following entity class:
</para>
-<programlisting role="JAVA"><![CDATA[@Entity public class Customer { private Integer id; private String firstName; private String lastName; @Id public Integer getId() { return id; } public void setId(Integer id) { this.id = id; } public String getFirstName() { return firstName; } public void setFirstName(String firstName) { this.firstName = firstName; } public String getLastName() { return lastName; } public void setLastName(String lastName) { this.lastName = lastName; } }]]>
+<programlisting role="JAVA"><![CDATA[@Entity
+public class Customer {
+ private Integer id;
+ private String firstName;
+ private String lastName;
+
+ @Id
+ public Integer getId() { return id; }
+ public void setId(Integer id) { this.id = id; }
+
+ public String getFirstName() { return 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:
@@ -3403,7 +3920,15 @@
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.1.xsd" no-conversation-view-id="/home.xhtml" login-view-id="/login.xhtml" http-port="8080" https-port="8443"> ]]>
+<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>
</section>
@@ -3420,7 +3945,15 @@
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"><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 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>
@@ -3430,7 +3963,11 @@
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 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.
@@ -3443,7 +3980,25 @@
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 public BufferedImage renderChallenge() { BufferedImage img = super.renderChallenge(); img.getGraphics().drawOval(5, 3, 60, 14); //add an obscuring decoration return img; } }]]>
+<programlisting role="JAVA"><![CDATA[@Name("org.jboss.seam.captcha.captcha")
+ at 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
+ public BufferedImage renderChallenge()
+ {
+ BufferedImage img = super.renderChallenge();
+ img.getGraphics().drawOval(5, 3, 60, 14); //add an obscuring decoration
+ return img;
+ }
+}]]>
</programlisting>
</section>
@@ -3608,7 +4163,12 @@
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 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>.
@@ -3621,7 +4181,34 @@
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); private String companyCode; public String getCompanyCode() { return companyCode; } public void setCompanyCode(String companyCode) { this.companyCode = companyCode; } @Override public String login() { log.info("###### CUSTOM LOGIN CALLED ######"); return super.login(); } }]]>
+<programlisting role="JAVA"><[CDATA[@Name("org.jboss.seam.security.identity")
+ at Scope(SESSION)
+ at Install(precedence = APPLICATION)
+ at BypassInterceptors
+ at Startup
+public class CustomIdentity extends Identity
+{
+ private static final LogProvider log = Logging.getLogProvider(CustomIdentity.class);
+
+ private String companyCode;
+
+ public String getCompanyCode()
+ {
+ return companyCode;
+ }
+
+ public void setCompanyCode(String companyCode)
+ {
+ this.companyCode = companyCode;
+ }
+
+ @Override
+ public String login()
+ {
+ log.info("###### CUSTOM LOGIN CALLED ######");
+ return super.login();
+ }
+}]]>
</programlisting>
<warning>
<para>
@@ -3676,7 +4263,20 @@
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"><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 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>
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.
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Spring.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Spring.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Spring.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -63,25 +63,44 @@
Inject Seam component instances into Spring beans with the <literal><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.1.xsd">]]>
+<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 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 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"/> <bean id="someSpringBean" class="SomeSpringBeanClass" scope="prototype"> <property name="someProperty" ref="someSeamComponentInstance"> </bean> ]]>
+<programlisting role="XML"><![CDATA[<seam:instance name="someComponent" id="someSeamComponentInstance"/>
+
+<bean id="someSpringBean" class="SomeSpringBeanClass" scope="prototype">
+ <property name="someProperty" ref="someSeamComponentInstance">
+</bean>
+]]>
</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.
@@ -96,7 +115,11 @@
The <literal><seam:instance/></literal> tag lets us automatically proxy the Seam component.
</para>
-<programlisting role="XML"><seam:instance id="seamManagedEM" name="someManagedEMComponent" proxy="true"/> <bean id="someSpringBean" class="SomeSpringBeanClass"> <property name="entityManager" ref="seamManagedEM"> </bean>
+<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>
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.
@@ -115,7 +138,11 @@
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 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>:
@@ -134,7 +161,9 @@
The <literal><seam:component/></literal> namespace handler can be used to transform any Spring bean into a Seam component. Just add the <literal><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 role="XML"><![CDATA[<bean id="someSpringBean" class="SomeSpringBeanClass" scope="prototype">
+ <seam:component/> </bean>
+]]>
</programlisting>
<para>
By default, <literal><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.
@@ -153,7 +182,12 @@
Specify <literal><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 role="XML"><![CDATA[<!-- Only needs to be specified once per bean factory-->
+<seam:configure-scopes/>
+
+...
+
+<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>.)
@@ -165,7 +199,15 @@
The latter approach lets you inject Seam-scoped Spring beans into other Spring beans without using <literal><seam:instance/></literal>. However, you must be careful to maintain scope impedance. Normally, you would specify <literal><aop:scoped-proxy/></literal> in the bean definition, but Seam-scoped Spring beans are not compatible with <literal><aop:scoped-proxy/></literal>. Therefore, to inject a Seam-scoped Spring bean into a singleton, use <literal><seam:instance/></literal>:
</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 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>
@@ -223,7 +265,10 @@
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 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.
@@ -238,19 +283,33 @@
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> <bean class="org.springframework.orm.jpa.support. PersistenceAnnotationBeanPostProcessor"> <property name="defaultPersistenceUnitName" value="bookingDatabase:extended"/> </bean>]]>
+<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>
+<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 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 role="XML"><![CDATA[<bean id="bookingService"
+ class="org.jboss.seam.example.spring.BookingService">
+ <property name="entityManagerFactory" ref="seamEntityManagerFactory"/>
+</bean>]]>
</programlisting>
</section>
@@ -263,7 +322,10 @@
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 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>.
@@ -279,7 +341,17 @@
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><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><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.1.xsd http://jboss.com/products/seam/spring http://jboss.com/products/seam/spring-2.1.xsd"> <spring:context-loader config-locations="/WEB-INF/applicationContext.xml"/> </components>]]>
+<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">
+
+ <spring:context-loader config-locations="/WEB-INF/applicationContext.xml"/>
+
+</components>]]>
</programlisting>
</section>
@@ -295,7 +367,11 @@
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 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>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Testing.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Testing.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Testing.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -19,7 +19,39 @@
The following Seam Component which creates a statement of account for a customer:
</para>
-<programlisting role="JAVA"><![CDATA[@Stateless @Scope(EVENT) @Name("statementOfAccount") public class StatementOfAccount { @In(create=true) EntityManager entityManager private double statementTotal; @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); } 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 role="JAVA"><![CDATA[@Stateless
+ at Scope(EVENT)
+ at Name("statementOfAccount")
+public class StatementOfAccount {
+
+ @In(create=true) EntityManager entityManager
+
+ private double statementTotal;
+
+ @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);
+ }
+
+ 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:
@@ -41,10 +73,36 @@
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 <xref linkend="config.install.embedded" /> for configuration details. This means you can write tests to exercise your application fully within a minimized container:
+ 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 { @Test public void testRegisterComponent() throws Exception { 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"); } }.run(); } ... }]]>
+<programlisting role="JAVA"><![CDATA[public class RegisterTest extends SeamTest
+{
+
+ @Test
+ public void testRegisterComponent() throws Exception
+ {
+
+ 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");
+ }
+
+ }.run();
+
+ }
+
+ ...
+
+}]]>
</programlisting>
<section>
<title>Using mocks in integration tests</title>
@@ -52,13 +110,22 @@
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 role="JAVA"><![CDATA[@Name("paymentProcessor")
+public class 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 role="JAVA"><![CDATA[@Name("paymentProcessor")
+ at Install(precedence=MOCK)
+public class MockPaymentProcessor extends PaymentProcessor {
+ 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.
@@ -79,13 +146,85 @@
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 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 SeamTest { @Test public void testRegister() throws Exception { 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 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 renderResponse() { assert getValue("#{user.username}").equals("1ovthafew"); assert getValue("#{user.name}").equals("Gavin King"); assert getValue("#{user.password}").equals("secret"); } }.run(); } ... }]]>
+<programlisting role="JAVA"><![CDATA[public class RegisterTest extends SeamTest
+{
+
+ @Test
+ public void testRegister() throws Exception
+ {
+
+ 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 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 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. -->
@@ -293,13 +432,29 @@
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> <ARTIST id="1" dtype="Band" name="Pink Floyd" /> <DISC id="1" name="Dark Side of the Moon" artist_id="1" /> </dataset>]]>
+<programlisting role="XML"><![CDATA[<dataset>
+
+ <ARTIST
+ id="1"
+ dtype="Band"
+ name="Pink Floyd" />
+
+ <DISC
+ id="1"
+ name="Dark Side of the Moon"
+ artist_id="1" />
+
+</dataset>]]>
</programlisting>
<para>
Tell Seam about this format by overriding <literal>prepareDBUnitOperations()</literal> as follows:
</para>
-<programlisting role="JAVA"><![CDATA[protected void prepareDBUnitOperations() { beforeTestOperations.add( new DataSetOperation("my/datasets/BaseData.xml") ); }]]>
+<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.
@@ -344,7 +499,31 @@
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 { 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 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 role="JAVA"><![CDATA[public class MailTest extends SeamTest {
+
+ @Test
+ public void testSimpleMessage() throws Exception {
+
+ 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 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>
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.
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Text.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Text.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Text.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -19,37 +19,99 @@
If we display this using <literal><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 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><![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>
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! </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. </p> <p> This is the second paragraph. </p>]]>
+<programlisting role="XHTML"><![CDATA[<h1>This is a big heading</h1>
+<p>
+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.
+</p>
+
+<p>
+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 #and even the /third/ item An unordered list: =an item =another item]]>
+<programlisting><![CDATA[An ordered list:
+
+#first item
+#second item
+#and even the /third/ item
+
+An unordered list:
+
+=an item
+=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> </ol> <p> An unordered list: </p> <ul> <li>an item</li> <li>another item</li> </ul>]]>
+<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>
+</ol>
+
+<p>
+An unordered list:
+</p>
+
+<ul>
+<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: "Nyeah nyeah-nee /nyeah/ nyeah!" But what do you think he means by "nyeah-nee"?]]>
+<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: </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 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>
</section>
@@ -59,19 +121,41 @@
Special characters such as <literal>*</literal>, <literal>|</literal> and <literal>#</literal>, and HTML characters such as <literal><</literal>, <literal>></literal> and <literal>&</literal> can be escaped with <literal>\</literal>:
</para>
-<programlisting>You can write down equations like 2\*3\=6 and HTML tags like \<body\> with the escape character: \\.
+<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> with the escape character: \. </p>]]>
+<programlisting role="XHTML"><![CDATA[<p>
+ You can write down equations like 2*3=6 and HTML tags
+ like <body> with the escape character: \.
+</p>]]>
</programlisting>
<para>
And we can quote code blocks with backticks:
</para>
-<programlisting><![CDATA[My code doesn't work: `for (int i=0; i<100; i--) { doSomething(); }` Any ideas?]]>
+<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: </p> <pre>for (int i=0; i<100; i--) { doSomething(); }</pre> <p> Any ideas? </p>]]>
+<programlisting role="XHTML"><![CDATA[<p>
+My code doesn't work:
+</p>
+
+<pre>for (int i=0; i<100; i--)
+{
+ doSomething();
+}</pre>
+
+<p>
+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:
@@ -115,10 +199,60 @@
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 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> #modify: list available HTML subset? -->
</section>
-
+ <section>
+ <title>Using the SeamTextParser</title>
+
+ <para>
+ The <literal><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, 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)));
+
+ 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>";
+ }
+
+ // Renders a <p> or equivalent tag
+ @Override
+ protected String paragraphOpenTag() {
+ return "<p class=\"myCustomStyle\">";
+ }
+
+ public void parse() throws ANTLRException {
+ startRule();
+ }
+
+}]]></programlisting>
+
+ <para>
+ <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>
+ </section>
+
</chapter>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Tutorial.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Tutorial.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Tutorial.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -50,7 +50,7 @@
</note>
</section>
- <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.
@@ -64,7 +64,7 @@
<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>-->
<section>
<title>Running the example tests</title>
@@ -104,7 +104,61 @@
<!-- 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 reso!
lve a currently undefined (null) context variable whose name m!
atches t
hat 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>
-<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 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 role="JAVA"><![CDATA[@Entity
+ at Name("user")
+ at Scope(SESSION)
+ at 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 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>
<orderedlist>
<listitem>
@@ -174,7 +228,39 @@
<!-- 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}") .getR!
esultList(); 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 areare!
fs="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 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 l!
istener 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 dependenc!
y on JSF.) Built-in Seam components may be obtained by injecti!
on, or b
y calling the <literal>instance()</literal> method on the class of the built-in component. </para> </callout> </calloutlist> </programlistingco> </example> --> <example>
<title>RegisterAction.java</title>
-<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; } } }]]>
+<programlisting><![CDATA[@Stateless
+ at 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;
+ }
+ }
+
+}]]>
</programlisting>
<orderedlist>
<listitem>
@@ -250,7 +336,11 @@
<example>
<title>Register.java</title>
-<programlisting role="JAVA"><![CDATA[@Local public interface Register { public String register(); }]]>
+<programlisting role="JAVA"><![CDATA[@Local
+public interface Register
+{
+ public String register();
+}]]>
</programlisting>
</example>
<para>
@@ -266,7 +356,34 @@
<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"> <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 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">
+
+ <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>
@@ -275,7 +392,23 @@
<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"> <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 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">
+
+ <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>
@@ -297,7 +430,19 @@
<example>
<title>components.xml</title>
-<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.1.xsd http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.1.xsd"> <core:init jndi-pattern="@jndiPattern@"/> </components>]]>
+<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">
+
+ <core:init jndi-pattern="@jndiPattern@"/>
+
+</components>]]>
</programlisting>
</example>
<para>
@@ -313,7 +458,39 @@
<example>
<title>web.xml</title>
-<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"> <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> <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> <session-config> <session-tim!
eout>10</session-timeout> </session-config> </web-app>]]>
+<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">
+
+ <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>
+
+ <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>
+
+ <session-config>
+ <session-timeout>10</session-timeout>
+ </session-config>
+
+</web-app>]]>
</programlisting>
</example>
<para>
@@ -329,7 +506,19 @@
<example>
<title>faces-config.xml</title>
-<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"> <application> <view-handler>com.sun.facelets.FaceletViewHandler</view-handler> </application> </faces-config>]]>
+<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">
+
+ <application>
+ <view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
+ </application>
+
+</faces-config>]]>
</programlisting>
</example>
<para>
@@ -349,7 +538,28 @@
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"> <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> </ejb-jar>]]>
+<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">
+
+ <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>
+
+</ejb-jar>]]>
</programlisting>
</section>
@@ -359,7 +569,23 @@
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"> <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 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">
+
+ <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>
@@ -371,7 +597,33 @@
<example id="registration-application-xml">
<title>registration application</title>
-<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"> <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> </application>]]>
+<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">
+
+ <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>
+
+</application>]]>
</programlisting>
</example>
<para>
@@ -434,7 +686,69 @@
<example>
<title>Message.java</title>
-<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 role="JAVA"><![CDATA[@Entity
+ at Name("message")
+ at 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>
@@ -453,7 +767,44 @@
<!-- 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") .getResult!
List(); } 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 corresponding to the clicked link. </para> </callout> <callout arearefs="messages-out"> <para> The <l!
iteral>@Out</literal> annotation then exposes the selected val!
ue direc
tly 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 <lit!
eral>findMessages()</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>
-<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><![CDATA[@Stateful
+ at Scope(SESSION)
+ at 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>
<orderedlist>
<listitem>
@@ -513,7 +864,14 @@
<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 role="JAVA"><![CDATA[@Local
+public interface MessageManager
+{
+ public void findMessages();
+ public void select();
+ public void delete();
+ public void destroy();
+}]]>
</programlisting>
</example>
<para>
@@ -529,7 +887,50 @@
<example>
<title>messages.jsp</title>
-<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"> <h:outputText value="Read"/> </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"> <h:outputText value="Date/Time"/> </f:fa!
cet> <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 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">
+ <h:outputText value="Read"/>
+ </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">
+ <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>
@@ -572,7 +973,22 @@
<!-- 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"> <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><![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"/>
+
+</process-definition>]]>
</programlisting>
<orderedlist>
<listitem>
@@ -623,7 +1039,30 @@
<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 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>
@@ -635,7 +1074,24 @@
<example>
<title>login.jsp</title>
-<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 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>
<para>
@@ -644,7 +1100,28 @@
<!-- 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><![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>
<orderedlist>
<listitem>
@@ -676,7 +1153,71 @@
<example>
<title>todo.jsp</title>
-<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}"> <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 ty!
pe="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"/> </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> <h:column> <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 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}">
+ <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>
+ </h:column>
+ <h:column>
+ <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>
+ <h:column>
+ <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>
@@ -688,14 +1229,49 @@
<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 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 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> </h:column> <h:column> <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 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>
+</h:column>
+<h:column>
+ <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>
<para>
@@ -706,7 +1282,9 @@
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 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><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:
@@ -718,7 +1296,12 @@
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 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>
@@ -767,7 +1350,54 @@
<!-- 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 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.1.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> <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> <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> <page name="win" view-id="/win.jspx"> <redirect/> <end-conversation/> </page> <page name="lose" view-id="/lose.jspx"> <redirect/> <end-conversation/> </page> </pageflow-definition>]]>
+<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"
+ 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>
+
+ <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>
+
+ <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>
+
+ <page name="win" view-id="/win.jspx">
+ <redirect/>
+ <end-conversation/>
+ </page>
+
+ <page name="lose" view-id="/lose.jspx">
+ <redirect/>
+ <end-conversation/>
+ </page>
+
+</pageflow-definition>]]>
</programlisting>
<orderedlist>
<listitem>
@@ -813,7 +1443,76 @@
<example>
<title>numberGuess.jspx</title>
-<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" xmlns:s="http://jboss.com/products/seam/taglib" xmlns="http://www.w3.org/1999/xhtml" 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"/> <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"> <div> <h:messages globalOnly="true"/> <h:outputText value="Higher!" rendered="#{numberGuess.rand!
omNumber 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> 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:selectOneR!
adio val
ue="#{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> </h:form> </f:view> </body> </html> </jsp:root>]]>
+<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"
+ xmlns:s="http://jboss.com/products/seam/taglib"
+ xmlns="http://www.w3.org/1999/xhtml"
+ 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"/>
+ <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">
+
+ <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>
+ 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>
+
+ </h:form>
+ </f:view>
+ </body>
+ </html>
+</jsp:root>]]>
</programlisting>
</example>
<para>
@@ -825,7 +1524,33 @@
<example>
<title>win.jspx</title>
-<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" 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"/> <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> </html> </jsp:root> ]]>
+<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"
+ 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"/>
+ <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>
+ </html>
+</jsp:root>
+]]>
</programlisting>
</example>
<para>
@@ -837,7 +1562,109 @@
<!-- 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") @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==m!
axGuesses; } public int getRemainingGuesses() { return maxGuesses-guessCount; } public void setMaxGuesses(int maxGuesses) { this.maxGuesses = maxGuesses; } public int getMaxGuesses() { return maxGuesses; } 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>![CDATA[@Name("numberGuess")
+ at 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;
+ }
+
+ public int getRemainingGuesses() {
+ return maxGuesses-guessCount;
+ }
+
+ public void setMaxGuesses(int maxGuesses) {
+ this.maxGuesses = maxGuesses;
+ }
+
+ public int getMaxGuesses() {
+ return maxGuesses;
+ }
+
+ 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>
<orderedlist>
<listitem>
@@ -854,7 +1681,17 @@
<example>
<title>pages.xml</title>
-<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.1.xsd"> <page view-id="/numberGuess.jspx"> <begin-conversation join="true" pageflow="numberGuess"/> </page> </pages> ]]>
+<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">
+
+ <page view-id="/numberGuess.jspx">
+ <begin-conversation join="true" pageflow="numberGuess"/>
+ </page>
+
+</pages>
+]]>
</programlisting>
</example>
<para>
@@ -1056,7 +1893,79 @@
<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 @Name("hotelSearch") @Scope(ScopeType.SESSION) @Restrict("#{identity.loggedIn}") 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}") .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><![CDATA[@Stateful
+ at Name("hotelSearch")
+ at Scope(ScopeType.SESSION)
+ at Restrict("#{identity.loggedIn}")
+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}")
+ .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>
<orderedlist>
<listitem>
@@ -1088,7 +1997,74 @@
<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> <h1>Search Hotels</h1> <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" itemVa!
lue="20"/> </h:selectOneMenu> </fieldset> </h:form> </div> <a:outputPanel id="searchResults"> <div class="section"> <h:outputText value="No Hotels Found" 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:dataTable> <s:link !
value="More results" action="#{hotelSearch.nextPage}" rendered!
="#{hote
lSearch.nextPageAvailable}"/> </div> </a:outputPanel> ]]>
+<programlisting><![CDATA[<div class="section">
+
+ <span class="errors">
+ <h:messages globalOnly="true"/>
+ </span>
+
+ <h1>Search Hotels</h1>
+
+ <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>
+ </fieldset>
+ </h:form>
+
+</div>
+
+<a:outputPanel id="searchResults">
+ <div class="section">
+ <h:outputText value="No Hotels Found"
+ 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:dataTable>
+ <s:link value="More results" action="#{hotelSearch.nextPage}"
+ rendered="#{hotelSearch.nextPageAvailable}"/>
+ </div>
+</a:outputPanel> ]]>
</programlisting>
<orderedlist>
<listitem>
@@ -1126,7 +2102,93 @@
<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 @Name("hotelBooking") @Restrict("#{identity.loggedIn}") 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><![CDATA[@Stateful
+ at Name("hotelBooking")
+ at Restrict("#{identity.loggedIn}")
+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>
<orderedlist>
<listitem>
@@ -1225,7 +2287,74 @@
<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 @Name("roomPreference") @Restrict("#{identity.loggedIn}") public class RoomPreferenceAction implements RoomPreference { @Logger private Log log; @In private Hotel hotel; @In private Booking booking; @DataModel(value="availableRooms") private List<Room> availableRooms; @DataModelSelection(value="availableRooms") private Room roomSelection; @In(required=false, value="roomSelection") @Out(required=false, value="roomSelection") private Room room; @Factory("availableRooms") public void loadAvailableRooms() { availableRooms = hotel.getAvailableRooms(booking.getCheckinDate(), booking.getCheckoutDate()); log.info("Retrieved #0 available rooms", availableRooms.size()); } public BigDecimal getExpectedPrice() { log.info("Retrieving price for room #0", roomSelection.getName()); return booking.getTotal(roomSelection); } @Begin(nested=true) public String selectPreference() { log.info("Room selected"); this.room = this.roomSelection; return "pay!
ment"; } public String requestConfirmation() { // all validations are performed through the s:validateAll, so checks are already // performed log.info("Request confirmation from user"); return "confirm"; } @End(beforeRedirect=true) public String cancel() { log.info("ending conversation"); return "cancel"; } @Destroy @Remove public void destroy() {} } ]]>
+<programlisting><![CDATA[@Stateful
+ at Name("roomPreference")
+ at Restrict("#{identity.loggedIn}")
+public class RoomPreferenceAction implements RoomPreference
+{
+
+ @Logger
+ private Log log;
+
+ @In private Hotel hotel;
+
+ @In private Booking booking;
+
+ @DataModel(value="availableRooms")
+ private List<Room> availableRooms;
+
+ @DataModelSelection(value="availableRooms")
+ private Room roomSelection;
+
+ @In(required=false, value="roomSelection")
+ @Out(required=false, value="roomSelection")
+ private Room room;
+
+ @Factory("availableRooms")
+ public void loadAvailableRooms()
+ {
+ availableRooms = hotel.getAvailableRooms(booking.getCheckinDate(), booking.getCheckoutDate());
+ log.info("Retrieved #0 available rooms", availableRooms.size());
+ }
+
+ public BigDecimal getExpectedPrice()
+ {
+ log.info("Retrieving price for room #0", roomSelection.getName());
+
+ return booking.getTotal(roomSelection);
+ }
+
+ @Begin(nested=true)
+ public String selectPreference()
+ {
+ log.info("Room selected");
+
+ this.room = this.roomSelection;
+
+ return "payment";
+ }
+
+ public String requestConfirmation()
+ {
+ // all validations are performed through the s:validateAll, so checks are already
+ // performed
+ log.info("Request confirmation from user");
+
+ return "confirm";
+ }
+
+ @End(beforeRedirect=true)
+ public String cancel()
+ {
+ log.info("ending conversation");
+
+ return "cancel";
+ }
+
+ @Destroy @Remove
+ public void destroy() {}
+}
+]]>
</programlisting>
<orderedlist>
<listitem>
@@ -1257,7 +2386,57 @@
<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> </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.descr!
iption} </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><![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>
+</div>
+]]>
</programlisting>
<orderedlist>
<listitem>
@@ -1284,7 +2463,101 @@
<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 @Name("hotelBooking") @Restrict("#{identity.loggedIn}") 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><![CDATA[@Stateful
+ at Name("hotelBooking")
+ at Restrict("#{identity.loggedIn}")
+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>
<orderedlist>
<listitem>
@@ -1377,7 +2650,32 @@
<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> </div> </h:column> </h:dataTable>]]>
+<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>
+ </div>
+ </h:column>
+</h:dataTable>]]>
</programlisting>
</example>
<para>
@@ -1386,7 +2684,23 @@
<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; @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><![CDATA[@Name("blog")
+ at Scope(ScopeType.STATELESS)
+ at AutoCreate
+public class BlogService
+{
+
+ @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>
<orderedlist>
<listitem>
@@ -1415,20 +2729,36 @@
<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 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 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 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>:
@@ -1436,7 +2766,16 @@
<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}"/> </page> ... </pages>]]>
+<programlisting role="XML"><![CDATA[<pages>
+ <page view-id="/search.xhtml">
+ <rewrite pattern="/search/{searchPattern}"/>
+ <rewrite pattern="/search"/>
+
+ <param name="searchPattern" value="#{searchService.searchPattern}"/>
+
+ </page>
+ ...
+</pages>]]>
</programlisting>
</example>
<para>
@@ -1455,13 +2794,76 @@
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> </h:column> </h:dataTable>]]>
+<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>
+ </h:column>
+</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; 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(); } 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); } catch (ParseException e) { return null; } return entityManager.createFullTextQuery(luceneQuery, BlogEntry.class) .setMaxResults(100) !
.getResultList(); } } public String getSearchPattern() { return searchPattern; } public void setSearchPattern(String searchPattern) { this.searchPattern = searchPattern; } } ]]>
+<programlisting role="JAVA"><![CDATA[@Name("searchService")
+public class SearchService
+{
+
+ @In
+ private FullTextEntityManager entityManager;
+
+ 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();
+ }
+ 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);
+ }
+ catch (ParseException e)
+ {
+ return null;
+ }
+
+ return entityManager.createFullTextQuery(luceneQuery, BlogEntry.class)
+ .setMaxResults(100)
+ .getResultList();
+ }
+ }
+
+ public String getSearchPattern()
+ {
+ return searchPattern;
+ }
+
+ public void setSearchPattern(String searchPattern)
+ {
+ this.searchPattern = searchPattern;
+ }
+
+}
+]]>
</programlisting>
</section>
@@ -1479,13 +2881,58 @@
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; @Out BlogEntry blogEntry; public void loadBlogEntry(String id) throws EntryNotFoundException { blogEntry = blog.getBlogEntry(id); if (blogEntry==null) throw new EntryNotFoundException(id); } }]]>
+<programlisting role="JAVA"><![CDATA[@Name("entryAction")
+ at Scope(STATELESS)
+public class EntryAction
+{
+ @In Blog blog;
+
+ @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> ... <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="/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> </pages>]]>
+<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="/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>
+
+</pages>]]>
</programlisting>
<note>
<para>
@@ -1496,22 +2943,62 @@
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 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 role="JAVA"><![CDATA[@ApplicationException(rollback=true)
+ at 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") @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 role="JAVA"><![CDATA[@Name("entryAction")
+ at 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 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.
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Validation.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Validation.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Validation.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -8,7 +8,25 @@
In plain JSF, validation is defined in the view:
</para>
-<programlisting role="XHTML"><![CDATA[<h:form> <h:messages/> <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> <h:commandButton/> </h:form>]]>
+<programlisting role="XHTML"><![CDATA[<h:form>
+ <h:messages/>
+
+ <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>
+
+ <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.
@@ -17,19 +35,65 @@
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 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>
<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; } @NotNull @ZipCode public String getZip() { return zip; } public void setZip(String z) { zip = z; } }]]>
+<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; }
+
+ @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><s:validate></literal> to validate against the constraint defined on the model object.
</para>
-<programlisting role="XHTML"><![CDATA[<h:form> <h:messages/> <div> Country: <h:inputText value="#{location.country}" required="true"> <s:validate/> </h:inputText> </div> <div> Zip code: <h:inputText value="#{location.zip}" required="true"> <s:validate/> </h:inputText> </div> <h:commandButton/> </h:form>]]>
+<programlisting role="XHTML"><![CDATA[<h:form>
+ <h:messages/>
+
+ <div>
+ Country:
+ <h:inputText value="#{location.country}" required="true">
+ <s:validate/>
+ </h:inputText>
+ </div>
+
+ <div>
+ Zip code:
+ <h:inputText value="#{location.zip}" required="true">
+ <s:validate/>
+ </h:inputText>
+ </div>
+
+ <h:commandButton/>
+
+</h:form>]]>
</programlisting>
<note>
<para>
@@ -43,7 +107,27 @@
The design is better, but not much less verbose than our initial design. Now, we will use <literal><s:validateAll></literal>:
</para>
-<programlisting role="XHTML"><![CDATA[<h:form> <h:messages/> <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 role="XHTML"><![CDATA[<h:form>
+
+ <h:messages/>
+
+ <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 adds an <literal><s:validate></literal> to every input in the form. In a large form, this can save a lot of typing.
@@ -67,31 +151,122 @@
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> <span class="#{invalid?'error':''}"> <h:graphicImage value="/img/error.gif" rendered="#{invalid}"/> <s:validateAll> <ui:insert/> </s:validateAll> </span> <s:message styleClass="error"/> </div> </ui:composition>]]>
+<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':''}">
+ <h:graphicImage value="/img/error.gif" rendered="#{invalid}"/>
+ <s:validateAll>
+ <ui:insert/>
+ </s:validateAll>
+ </span>
+
+ <s:message styleClass="error"/>
+
+ </div>
+
+</ui:composition>]]>
</programlisting>
<para>
We can include this template for each of our form fields by using <literal><s:decorate></literal>:
</para>
-<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"/> </s:decorate> <s:decorate template="edit.xhtml"> <ui:define name="label">Zip code:</ui:define> <h:inputText value="#{location.zip}" required="true"/> </s:decorate> <h:commandButton/> </h:form>]]>
+<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"/>
+ </s:decorate>
+
+ <s:decorate template="edit.xhtml">
+ <ui:define name="label">Zip code:</ui:define>
+ <h:inputText value="#{location.zip}" required="true"/>
+ </s:decorate>
+
+ <h:commandButton/>
+
+</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"/> <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"/> </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"/> </h:inputText> </s:decorate> <h:commandButton/> </h:form>]]>
+<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"/>
+ </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"/>
+ </h:inputText>
+ </s:decorate>
+
+ <h:commandButton/>
+
+</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"/> <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> </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> </s:decorate> <h:commandButton/> </h:form>]]>
+<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>
+ </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>
+ </s:decorate>
+
+ <h:commandButton/>
+
+</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 @NotNull @Length(max=6) @ZipCode(message="#{messages['location.zipCode.invalid']}") public String getZip() { return zip; } public void setZip(String z) { zip = z; } }]]>
+<programlisting role="JAVA"><![CDATA[public class Location {
+ 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}
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Webservices.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Webservices.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Webservices.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -16,7 +16,23 @@
<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 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>
</section>
@@ -26,7 +42,16 @@
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> </soapenv:Header> <soapenv:Body> <seam:confirmAuction/> </soapenv:Body> </soapenv:Envelope> ]]>
+<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>
+ </soapenv:Header>
+ <soapenv:Body>
+ <seam:confirmAuction/>
+ </soapenv:Body>
+</soapenv: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.
@@ -35,7 +60,15 @@
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> </env:Header> <env:Body> <confirmAuctionResponse xmlns="http://seambay.example.seam.jboss.org/"/> </env:Body> </env:Envelope> ]]>
+<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>
+ </env:Header>
+ <env:Body>
+ <confirmAuctionResponse xmlns="http://seambay.example.seam.jboss.org/"/>
+ </env:Body>
+</env:Envelope>
+ ]]>
</programlisting>
<para>
Note that the response message contains the same <literal>conversationId</literal> element as the request.
@@ -66,7 +99,21 @@
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(); } // snip }]]>
+<programlisting role="JAVA"><![CDATA[@Stateless
+ at 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();
+ }
+
+ // 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.
@@ -81,20 +128,33 @@
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 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 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>
+ <!--<section>
<title>RESTful HTTP webservices with RESTEasy</title>
<para>
Seam integrates the RESTEasy implementation of the JAX-RS specification (JSR 311). You can decide which of the following features are integrated with your Seam application:
@@ -248,6 +308,6 @@
</section>
</section>
-
+ -->
</chapter>
Modified: projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Xml.xml
===================================================================
--- projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Xml.xml 2009-08-23 23:51:08 UTC (rev 92717)
+++ projects/docs/enterprise/5.0/Seam_Reference_Guide/en-US/Xml.xml 2009-08-24 00:58:29 UTC (rev 92718)
@@ -106,55 +106,120 @@
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:managed-persistence-context name="accountingDatabase" persistence-unit-jndi-name="java:/accountingEntityManagerFactory"/> </components>]]>
+<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:managed-persistence-context name="accountingDatabase"
+ persistence-unit-jndi-name="java:/accountingEntityManagerFactory"/>
+
+</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 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>
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"/>
+<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"/>
+
+</components>]]>
</programlisting>
-<programlisting role="XML"></components>]]> <![CDATA[<components> <component name="productDatabase" scope="session" class="org.jboss.seam.persistence.ManagedPersistenceContext"> <property name="persistenceUnitJndiName">java:/productEntityManagerFactory</ property> </component> </components>]]>
+<programlisting role="XML"><![CDATA[<components>
+
+ <component name="productDatabase"
+ scope="session"
+ class="org.jboss.seam.persistence.ManagedPersistenceContext">
+ <property name="persistenceUnitJndiName">java:/productEntityManagerFactory</property>
+ </component>
+
+</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"/> </components>]]>
+<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"/>
+
+</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> </components>]]>
+<programlisting role="XML"><![CDATA[<components>
+
+ <component name="productDatabase"
+ auto-create="true"
+ class="org.jboss.seam.persistence.ManagedPersistenceContext">
+ <property name="persistenceUnitJndiName">java:/productEntityManagerFactory</property>
+ </component>
+
+</components>]]>
</programlisting>
<para>
The <literal><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 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 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 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><factory></literal> declaration:
</para>
-<programlisting role="XML"><![CDATA[<components> <factory name="session" value="#{entityManager.delegate}" scope="STATELESS" auto-create="true"/> </components>]]>
+<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.)
@@ -170,7 +235,12 @@
<literal><components></literal> 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 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>
<literal><component></literal> only lets you configure one component, but is less verbose:
@@ -192,7 +262,11 @@
Properties of string, primitive or primitive wrapper type are configured as follows:
</para>
-<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><![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:
@@ -201,16 +275,34 @@
<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 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 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 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, 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.
@@ -219,7 +311,13 @@
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 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 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.
@@ -228,13 +326,18 @@
<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 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 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:
@@ -253,7 +356,16 @@
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.1.xsd"> <component class="org.jboss.seam.core.init"> <property name="debug">true</property> <property name="jndiPattern">@jndiPattern@</property> </component> </components>]]>
+<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">
+
+ <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 code is verbose. More importantly, the component and attribute names cannot be validated at development time.
@@ -262,7 +374,17 @@
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.1.xsd http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.1.xsd"> <core:init debug="true" jndi-pattern="@jndiPattern@"/> </components>]]>
+<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">
+
+ <core:init debug="true" jndi-pattern="@jndiPattern@"/>
+
+</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.
@@ -280,19 +402,55 @@
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 name="newPayment" payee="Somebody" account="#{selectedAccount}" payment-date="#{currentDatetime}" created-date="#{currentDatetime}" /> ... </components>]]>
+<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 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" 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 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 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 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><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 role="JAVA"><![CDATA[package org.jboss.seam.example.seampay;
+...
+ at Name("paymentHome")
+public class PaymentController
+ extends EntityHome<Payment>
+{
+ ...
+}]]> { ... }]]>
</programlisting>
<para>
The element name is the hyphenated form of the component name. The attributes of the element are the hyphenated forms of the property names.
@@ -301,7 +459,14 @@
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; ... @Entity public class Payment implements Serializable { ... }]]>
+<programlisting role="JAVA"><![CDATA[package org.jboss.seam.example.seampay;
+...
+ at Entity
+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.
@@ -312,62 +477,62 @@
<itemizedlist>
<listitem>
<para>
- components — <literal>http://jboss.com/products/seam/components</literal>
+ components — <literal>http://jboss.com/products/seam/components</literal>
</para>
</listitem>
<listitem>
<para>
- core — <literal>http://jboss.com/products/seam/core</literal>
+ core — <literal>http://jboss.com/products/seam/core</literal>
</para>
</listitem>
<listitem>
<para>
- drools — <literal>http://jboss.com/products/seam/drools</literal>
+ drools — <literal>http://jboss.com/products/seam/drools</literal>
</para>
</listitem>
<listitem>
<para>
- framework — <literal>http://jboss.com/products/seam/framework</literal>
+ framework — <literal>http://jboss.com/products/seam/framework</literal>
</para>
</listitem>
<listitem>
<para>
- jms — <literal>http://jboss.com/products/seam/jms</literal>
+ jms — <literal>http://jboss.com/products/seam/jms</literal>
</para>
</listitem>
<listitem>
<para>
- remoting — <literal>http://jboss.com/products/seam/remoting</literal>
+ remoting — <literal>http://jboss.com/products/seam/remoting</literal>
</para>
</listitem>
<listitem>
<para>
- theme — <literal>http://jboss.com/products/seam/theme</literal>
+ theme — <literal>http://jboss.com/products/seam/theme</literal>
</para>
</listitem>
<listitem>
<para>
- security — <literal>http://jboss.com/products/seam/security</literal>
+ security — <literal>http://jboss.com/products/seam/security</literal>
</para>
</listitem>
<listitem>
<para>
- mail — <literal>http://jboss.com/products/seam/mail</literal>
+ mail — <literal>http://jboss.com/products/seam/mail</literal>
</para>
</listitem>
<listitem>
<para>
- web — <literal>http://jboss.com/products/seam/web</literal>
+ web — <literal>http://jboss.com/products/seam/web</literal>
</para>
</listitem>
<listitem>
<para>
- pdf — <literal>http://jboss.com/products/seam/pdf</literal>
+ pdf — <literal>http://jboss.com/products/seam/pdf</literal>
</para>
</listitem>
<listitem>
<para>
- spring — <literal>http://jboss.com/products/seam/spring</literal>
+ spring — <literal>http://jboss.com/products/seam/spring</literal>
</para>
</listitem>
</itemizedlist>
More information about the jboss-cvs-commits
mailing list