[seam-commits] Seam SVN: r9654 - trunk/doc/Seam_Reference_Guide/en-US.
seam-commits at lists.jboss.org
seam-commits at lists.jboss.org
Wed Nov 26 00:33:20 EST 2008
Author: dan.j.allen
Date: 2008-11-26 00:33:20 -0500 (Wed, 26 Nov 2008)
New Revision: 9654
Modified:
trunk/doc/Seam_Reference_Guide/en-US/Tutorial.xml
trunk/doc/Seam_Reference_Guide/en-US/Xml.xml
Log:
cleanup tutorial
Modified: trunk/doc/Seam_Reference_Guide/en-US/Tutorial.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/Tutorial.xml 2008-11-26 04:54:19 UTC (rev 9653)
+++ trunk/doc/Seam_Reference_Guide/en-US/Tutorial.xml 2008-11-26 05:33:20 UTC (rev 9654)
@@ -273,8 +273,7 @@
entity bean domain model. </para>
<para> However, entity beans shouldn't do transaction management or database access. So we can't use
this component as a JSF action listener. For that we need a session bean. </para>
-
-
+
</section>
<section>
@@ -306,7 +305,6 @@
@Name("register")
public class RegisterAction implements Register
{
-
@In
private User user;
@@ -319,7 +317,7 @@
public String register()
{
List existing = em.createQuery(
- "select username from User where username=#{user.username}")
+ "select username from User where username = #{user.username}")
.getResultList();
if (existing.size()==0)
@@ -370,7 +368,8 @@
the standard JPA <literal>Query</literal> object. Nice, huh? </para>
</callout>
<callout arearefs="registration-log">
- <para> The <literal>Log</literal> API lets us easily display templated log messages.
+ <para> The <literal>Log</literal> API lets us easily display templated log messages which
+ can also make use of JSF EL expressions.
</para>
</callout>
<callout arearefs="registration-outcome">
@@ -388,8 +387,10 @@
<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. Built-in Seam components may be
- obtained by injection, or by calling an <literal>instance()</literal> method.
+ display templated error or success messages. (As of Seam 2.1, you can use
+ <literal>StatusMessages</literal> instead to remove the semantic dependency on JSF).
+ Built-in Seam components may be obtained by injection, or by calling the
+ <literal>instance()</literal> method on the class of the built-in component.
</para>
</callout>
</calloutlist>
@@ -411,7 +412,7 @@
used the Seam application framework controllers, we would have eliminated all of our
application code. However, then we wouldn't have had much of an application to explain.
</para>
-
+
</section>
<section>
@@ -441,11 +442,11 @@
<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">
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
- xmlns:s="http://jboss.com/products/seam/taglib"
- xmlns:h="http://java.sun.com/jsf/html"
- xmlns:f="http://java.sun.com/jsf/core">
+ xmlns:s="http://jboss.com/products/seam/taglib"
+ xmlns:h="http://java.sun.com/jsf/html"
+ xmlns:f="http://java.sun.com/jsf/core">
<head>
<title>Register New User</title>
@@ -477,26 +478,25 @@
<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">
+ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml"
- xmlns:f="http://java.sun.com/jsf/core">
+ xmlns:f="http://java.sun.com/jsf/core">
- <head>
- <title>Successfully Registered New User</title>
- </head>
- <body>
- <f:view>
- Welcome, #{user.name}, you are successfully registered as #{user.username}.
- </f:view>
- </body>
+ <head>
+ <title>Successfully Registered New User</title>
+ </head>
+ <body>
+ <f:view>
+ Welcome, #{user.name}, you are successfully registered as #{user.username}.
+ </f:view>
+ </body>
</html>
]]></programlisting>
</example>
- <para> This is a simple Facelets page using some embedded EL. There is nothing specific to Seam
- here. </para>
+ <para> This is a simple Facelets page using some inline EL. There's nothing specific to Seam here. </para>
</section>
@@ -526,16 +526,23 @@
<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">
+ 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@"/>
+ <core:init jndi-pattern="@jndiPattern@"/>
</components>]]></programlisting></example>
<para> This code configures a property named <literal>jndiPattern</literal> of a built-in Seam component
named <literal>org.jboss.seam.core.init</literal>. The funny <literal>@</literal> symbols are
- there because our Ant build script puts the correct JNDI pattern in when we deploy the application.</para>
+ there because our Ant build script puts the correct JNDI pattern in when we deploy the application,
+ which it reads from the components.properties file. You learn more about how this process works in
+ <xref linkend="xml.descriptor"/>.</para>
</section>
@@ -547,23 +554,16 @@
<example>
<title>web.xml</title>
<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<web-app version="2.5"
- xmlns="http://java.sun.com/xml/ns/javaee"
+<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">
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/javaee
+ http://java.sun.com/xml/ns/javaee/web-app_2_5.xsd"
+ version="2.5">
- <!-- Seam -->
-
<listener>
<listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
</listener>
-
- <!-- JSF -->
-
- <listener>
- <listener-class>com.sun.faces.config.ConfigureListener</listener-class>
- </listener>
<context-param>
<param-name>javax.faces.DEFAULT_SUFFIX</param-name>
@@ -603,12 +603,13 @@
<example>
<title>faces-config.xml</title>
<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
-<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 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">
- <!-- Facelets support -->
<application>
<view-handler>com.sun.facelets.FaceletViewHandler</view-handler>
</application>
@@ -619,11 +620,12 @@
<para> Note that we don't need
any JSF managed bean declarations! Our managed beans are annotated Seam components. In Seam applications,
- the <literal>faces-config.xml</literal> is used much less often than in plain JSF. </para>
+ the <literal>faces-config.xml</literal> is used much less often than in plain JSF. Here, we are simply
+ using it to enable Facelets as the view handler instead of JSP.</para>
<para> In fact, once you have all the basic descriptors set up, the <emphasis>only</emphasis> XML you
need to write as you add new functionality to a Seam application is orchestration: navigation rules
- or jBPM process definitions. Seam takes the view that <emphasis>process flow</emphasis> and
+ or jBPM process definitions. Seam's stand is that <emphasis>process flow</emphasis> and
<emphasis>configuration data</emphasis> are the only things that truly belong in XML. </para>
<para> In this simple example, we don't even need a navigation rule, since we decided to embed the view
@@ -637,24 +639,26 @@
<para> The <literal>ejb-jar.xml</literal> file integrates Seam with EJB3, by attaching the
<literal>SeamInterceptor</literal> to all session beans in the archive. </para>
- <programlisting role="XML"><![CDATA[<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">
+ <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>
+ <interceptors>
+ <interceptor>
+ <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
+ </interceptor>
+ </interceptors>
- <assembly-descriptor>
- <interceptor-binding>
- <ejb-name>*</ejb-name>
- <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
- </interceptor-binding>
- </assembly-descriptor>
+ <assembly-descriptor>
+ <interceptor-binding>
+ <ejb-name>*</ejb-name>
+ <interceptor-class>org.jboss.seam.ejb.SeamInterceptor</interceptor-class>
+ </interceptor-binding>
+ </assembly-descriptor>
</ejb-jar>]]></programlisting>
@@ -669,17 +673,18 @@
<programlisting role="XML"><![CDATA[<?xml version="1.0" encoding="UTF-8"?>
<persistence xmlns="http://java.sun.com/xml/ns/persistence"
- xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
- xsi:schemaLocation="http://java.sun.com/xml/ns/persistence
- http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
- version="1.0">
+ xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
+ xsi:schemaLocation="
+ http://java.sun.com/xml/ns/persistence
+ http://java.sun.com/xml/ns/persistence/persistence_1_0.xsd"
+ version="1.0">
- <persistence-unit name="userDatabase">
- <provider>org.hibernate.ejb.HibernatePersistence</provider>
- <jta-data-source>java:/DefaultDS</jta-data-source>
- <properties>
- <property name="hibernate.hbm2ddl.auto" value="create-drop"/>
- </properties>
+ <persistence-unit 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>
@@ -694,10 +699,11 @@
<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">
+ 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>
@@ -738,11 +744,12 @@
<para> The form input values are now validated against the Hibernate Validator constraints specified on the
<literal>User</literal> entity. If the constraints are violated, JSF redisplays the page. Otherwise,
JSF binds the form input values to properties of the <literal>User</literal> entity bean. </para>
- <para> Next, JSF asks Seam to resolve the variable named <literal>register</literal>. Seam finds the
- <literal>RegisterAction</literal> stateless session bean in the stateless context and returns it.
- JSF invokes the <literal>register()</literal> action listener method. </para>
- <para> Seam intercepts the method call and injects the <literal>User</literal> entity from the Seam session
- context, before continuing the invocation. </para>
+ <para> Next, JSF asks Seam to resolve the variable named <literal>register</literal>. Seam uses the JNDI
+ pattern mentioned earlier to locate the stateless session bean, wraps it as a Seam component, and
+ returns it. Seam then presents this component to JSF and JSF invokes the <literal>register()</literal>
+ action listener method.</para>
+ <para> But Seam is not done yet. Seam intercepts the method call and injects the <literal>User</literal>
+ entity from the Seam session context, before allowing the invocation to continue. </para>
<para> The <literal>register()</literal> method checks if a user with the entered username already exists.
If so, an error message is queued with the <literal>FacesMessages</literal> component, and a null
outcome is returned, causing a page redisplay. The <literal>FacesMessages</literal> component
@@ -799,43 +806,53 @@
private Date datetime;
@Id @GeneratedValue
- public Long getId() {
+ public Long getId()
+ {
return id;
}
- public void setId(Long id) {
+ public void setId(Long id)
+ {
this.id = id;
}
@NotNull @Length(max=100)
- public String getTitle() {
+ public String getTitle()
+ {
return title;
}
- public void setTitle(String title) {
+ public void setTitle(String title)
+ {
this.title = title;
}
@NotNull @Lob
- public String getText() {
+ public String getText()
+ {
return text;
}
- public void setText(String text) {
+ public void setText(String text)
+ {
this.text = text;
}
@NotNull
- public boolean isRead() {
+ public boolean isRead()
+ {
return read;
}
- public void setRead(boolean read) {
+ public void setRead(boolean read)
+ {
this.read = read;
}
@NotNull
@Basic @Temporal(TemporalType.TIMESTAMP)
- public Date getDatetime() {
+ public Date getDatetime()
+ {
return datetime;
}
- public void setDatetime(Date datetime) {
+ public void setDatetime(Date datetime)
+ {
this.datetime = datetime;
}
@@ -879,7 +896,6 @@
@Name("messageManager")
public class MessageManagerBean implements Serializable, MessageManager
{
-
@DataModel
private List<Message> messageList;
@@ -1190,18 +1206,20 @@
<example>
<title>Login.java</title>
<programlisting role="JAVA"><![CDATA[@Name("login")
-public class Login {
-
+public class Login
+{
@In
private Actor actor;
private String user;
- public String getUser() {
+ public String getUser()
+ {
return user;
}
- public void setUser(String user) {
+ public void setUser(String user)
+ {
this.user = user;
}
@@ -1254,8 +1272,8 @@
<area id="todo-task-annotations" coords="18"/>
</areaspec>
<programlisting><![CDATA[@Name("todoList")
-public class TodoList {
-
+public class TodoList
+{
private String description;
public String getDescription()
@@ -1263,7 +1281,8 @@
return description;
}
- public void setDescription(String description) {
+ public void setDescription(String description)
+ {
this.description = description;
}
@@ -1642,17 +1661,17 @@
<body>
<h1>Guess a number...</h1>
<f:view>
- <h:form styleClass="niceform">
-
- <div>
- <h:messages globalOnly="true"/>
- <h:outputText value="Higher!"
- rendered="#{numberGuess.randomNumber gt numberGuess.currentGuess}"/>
- <h:outputText value="Lower!"
- rendered="#{numberGuess.randomNumber lt numberGuess.currentGuess}"/>
- </div>
-
- <div>
+ <h: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
@@ -1678,16 +1697,16 @@
rendered="#{(numberGuess.biggest-numberGuess.smallest) le 4}">
<s:selectItems value="#{numberGuess.possibilities}" var="i" label="#{i}"/>
</h:selectOneRadio>
- <h:commandButton value="Guess" action="guess"/>
+ <h:commandButton value="Guess" action="guess"/>
<s:button value="Cheat" view="/confirm.jspx"/>
<s:button value="Give up" action="giveup"/>
- </div>
-
- <div>
+ </div>
+
+ <div>
<h:message for="inputGuess" style="color: red"/>
</div>
- </h:form>
+ </h:form>
</f:view>
</body>
</html>
@@ -2259,15 +2278,15 @@
<h1>Search Hotels</h1>
- <h:form id="searchCriteria">
- <fieldset>
- <h:inputText id="searchString" value="#{hotelSearch.searchString}"
+ <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}"
+ <a:commandButton id="findHotels" value="Find Hotels" action="#{hotelSearch.find}"
reRender="searchResults"/>
 
<a:status>
@@ -2275,7 +2294,7 @@
<h:graphicImage value="/img/spinner.gif"/>
</f:facet>
</a:status>
- <br/>
+ <br/>
<h:outputLabel for="pageSize">Maximum results:</h:outputLabel> 
<h:selectOneMenu value="#{hotelSearch.pageSize}" id="pageSize">
<f:selectItem itemLabel="5" itemValue="5"/>
@@ -2542,63 +2561,63 @@
</section>
- <section id="nestedbooking">
- <title>Nested conversations: extending the Hotel Booking example</title>
-
- <section>
- <title>Introduction</title>
-
- <para>Long-running conversations make it simple to maintain consistency of state in an application
+ <section id="nestedbooking">
+ <title>Nested conversations: extending the Hotel Booking example</title>
+
+ <section>
+ <title>Introduction</title>
+
+ <para>Long-running conversations make it simple to maintain consistency of state in an application
even in the face of multi-window operation and back-buttoning. Unfortunately, simply beginning and ending a
long-running conversation is not always enough. Depending on the requirements of the application, inconsistencies
between what the user's expectations and the reality of the application’s state can still result.</para>
- <para>The nested booking application extends the features of the hotel booking application to incorporate
+ <para>The nested booking application extends the features of the hotel booking application to incorporate
the selection of rooms. Each hotel has available rooms with descriptions for a user to select from. This requires
the addition of a room selection page in the hotel reservation flow.</para>
-
- <mediaobject>
- <imageobject role="fo">
- <imagedata fileref="images/nested-booking.png" align="center" scalefit="1"/>
- </imageobject>
- <imageobject role="html">
- <imagedata fileref="images/nested-booking.png" align="center"/>
- </imageobject>
- </mediaobject>
- <para>The user now has the option to select any available room to be included in the booking. As with the
+ <mediaobject>
+ <imageobject role="fo">
+ <imagedata fileref="images/nested-booking.png" align="center" scalefit="1"/>
+ </imageobject>
+ <imageobject role="html">
+ <imagedata fileref="images/nested-booking.png" align="center"/>
+ </imageobject>
+ </mediaobject>
+
+ <para>The user now has the option to select any available room to be included in the booking. As with the
hotel booking application we saw previously, this can lead to issues with state consistency. As with storing state
in the <varname>HTTPSession</varname>, if a conversation variable changes it affects all windows operating within
the same conversation context.</para>
- <para>To demonstrate this, let’s suppose the user clones the room selection screen in a new window. The
+ <para>To demonstrate this, let’s suppose the user clones the room selection screen in a new window. The
user then selects the <emphasis>Wonderful Room</emphasis> and proceeds to the confirmation screen. To see just how much
it would cost to live the high-life, the user returns to the original window, selects the <emphasis>Fantastic
Suite</emphasis> for booking, and again proceeds to confirmation. After reviewing the total cost, the user decides
that practicality wins out and returns to the window showing <emphasis>Wonderful Room</emphasis> to confirm.</para>
- <para>In this scenario, if we simply store all state in the conversation, we are not protected from
+ <para>In this scenario, if we simply store all state in the conversation, we are not protected from
multi-window operation within the same conversation. Nested conversations allow us to achieve correct behavior even
when context can vary within the same conversation.</para>
- </section>
-
- <section>
- <title>Understanding Nested Conversations</title>
-
- <para>Now let's see how the nested booking example extends the behavior of the hotel booking application through
+ </section>
+
+ <section>
+ <title>Understanding Nested Conversations</title>
+
+ <para>Now let's see how the nested booking example extends the behavior of the hotel booking application through
use of nested conversations. Again, we can read the class from top to bottom, as if it were a story.</para>
- <example>
- <title>RoomPreferenceAction.java</title>
- <!-- Can't use code hightlighting with callouts -->
- <programlistingco>
- <areaspec>
- <area id="nested-booking-load-rooms" coords="25"/>
- <area id="nested-booking-nested-conversation" coords="38"/>
- <area id="nested-booking-select-preference" coords="43"/>
- <area id="nested-booking-end-annotation" coords="58"/>
- </areaspec>
- <programlisting><![CDATA[@Stateful
+ <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
@@ -2663,142 +2682,142 @@
}
@Destroy @Remove
- public void destroy() {}
+ public void destroy() {}
}
]]></programlisting>
- <calloutlist>
- <callout arearefs="nested-booking-load-rooms">
- <para> The <varname>hotel</varname> instance is injected from the conversation context. The hotel
- is loaded through an <emphasis>extended persistence context</emphasis> so that the entity
- remains managed throughout the conversation. This allows us to lazily load the
- <varname>availableRooms</varname> through an <varname>@Factory</varname> method by
- simply walking the assocation.
- </para>
- </callout>
- <callout arearefs="nested-booking-nested-conversation">
- <para> When <link linkend="begin-annotation">
- <literal>@Begin(nested=true)</literal>
- </link> is encountered, a nested conversation is pushed onto the conversation stack. When
- executing within a nested conversation, components still have access to all outer conversation
- state, but setting any values in the nested conversation’s state container does not affect
- the outer conversation. In addition, nested conversations can exist concurrently stacked on the
- same outer conversation, allowing independent state for each.</para>
- </callout>
- <callout arearefs="nested-booking-select-preference">
- <para>The <varname>roomSelection</varname> is outjected to the conversation based on the
- <varname>@DataModelSelection</varname>. Note that because the nested conversation has an
- independent context, the <varname>roomSelection</varname> is only set into the new nested
- conversation. Should the user select a different preference in another window or tab a new
- nested conversation would be started.</para>
- </callout>
- <callout arearefs="nested-booking-end-annotation">
- <para> The <link linkend="end-annotation">
- <literal>@End</literal>
- </link> annotation pops the conversation stack and resumes the outer conversation. The
- <varname>roomSelection</varname> is destroyed along with the conversation context.</para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
+ <calloutlist>
+ <callout arearefs="nested-booking-load-rooms">
+ <para> The <varname>hotel</varname> instance is injected from the conversation context. The hotel
+ is loaded through an <emphasis>extended persistence context</emphasis> so that the entity
+ remains managed throughout the conversation. This allows us to lazily load the
+ <varname>availableRooms</varname> through an <varname>@Factory</varname> method by
+ simply walking the assocation.
+ </para>
+ </callout>
+ <callout arearefs="nested-booking-nested-conversation">
+ <para> When <link linkend="begin-annotation">
+ <literal>@Begin(nested=true)</literal>
+ </link> is encountered, a nested conversation is pushed onto the conversation stack. When
+ executing within a nested conversation, components still have access to all outer conversation
+ state, but setting any values in the nested conversation’s state container does not affect
+ the outer conversation. In addition, nested conversations can exist concurrently stacked on the
+ same outer conversation, allowing independent state for each.</para>
+ </callout>
+ <callout arearefs="nested-booking-select-preference">
+ <para>The <varname>roomSelection</varname> is outjected to the conversation based on the
+ <varname>@DataModelSelection</varname>. Note that because the nested conversation has an
+ independent context, the <varname>roomSelection</varname> is only set into the new nested
+ conversation. Should the user select a different preference in another window or tab a new
+ nested conversation would be started.</para>
+ </callout>
+ <callout arearefs="nested-booking-end-annotation">
+ <para> The <link linkend="end-annotation">
+ <literal>@End</literal>
+ </link> annotation pops the conversation stack and resumes the outer conversation. The
+ <varname>roomSelection</varname> is destroyed along with the conversation context.</para>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+ </example>
- <para>When we being a nested conversation it is pushed onto the conversation stack. In the <varname>nestedbooking</varname>
+ <para>When we being a nested conversation it is pushed onto the conversation stack. In the <varname>nestedbooking</varname>
example, the conversation stack consists of the outer long-running conversation (the booking) and each of the nested conversations (room
selections).</para>
- <example>
- <title>rooms.xhtml</title>
- <!-- Can't use code hightlighting with callouts -->
- <programlistingco>
- <areaspec>
- <area id="nested-booking-available-rooms" coords="19"/>
- <area id="nested-booking-selection-action" coords="36"/>
- <area id="nested-booking-cancel-action" coords="45"/>
- </areaspec>
- <programlisting><![CDATA[<div class="section">
- <h1>Room Preference</h1>
+ <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.description}
- </h:column>
- <h:column>
- <f:facet name="header">Per Night</f:facet>
- <h:outputText value="#{room.price}">
- <f:convertNumber type="currency" currencySymbol="$"/>
- </h:outputText>
- </h:column>
- <h:column>
- <f:facet name="header">Action</f:facet>
- <h:commandLink id="selectRoomPreference"
- action="#{roomPreference.selectPreference}">Select</h:commandLink>
- </h:column>
- </h:dataTable>
- </div>
- <div class="entry">
- <div class="label"> </div>
- <div class="input">
- <s:button id="cancel" value="Revise Dates" view="/book.xhtml"/>
- </div>
- </div>
- </h:form>
+ <h:form id="room_selections_form">
+ <div class="section">
+ <h:outputText styleClass="output"
+ value="No rooms available for the dates selected: "
+ rendered="#{availableRooms != null and availableRooms.rowCount == 0}"/>
+ <h:outputText styleClass="output"
+ value="Rooms available for the dates selected: "
+ rendered="#{availableRooms != null and availableRooms.rowCount > 0}"/>
+
+ <h:outputText styleClass="output" value="#{booking.checkinDate}"/> -
+ <h:outputText styleClass="output" value="#{booking.checkoutDate}"/>
+
+ <br/><br/>
+
+ <h:dataTable value="#{availableRooms}" var="room"
+ rendered="#{availableRooms.rowCount > 0}">
+ <h:column>
+ <f:facet name="header">Name</f:facet>
+ #{room.name}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Description</f:facet>
+ #{room.description}
+ </h:column>
+ <h:column>
+ <f:facet name="header">Per Night</f:facet>
+ <h:outputText value="#{room.price}">
+ <f:convertNumber type="currency" currencySymbol="$"/>
+ </h:outputText>
+ </h:column>
+ <h:column>
+ <f:facet name="header">Action</f:facet>
+ <h:commandLink id="selectRoomPreference"
+ action="#{roomPreference.selectPreference}">Select</h:commandLink>
+ </h:column>
+ </h:dataTable>
+ </div>
+ <div class="entry">
+ <div class="label"> </div>
+ <div class="input">
+ <s:button id="cancel" value="Revise Dates" view="/book.xhtml"/>
+ </div>
+ </div>
+ </h:form>
</div>
]]></programlisting>
- <calloutlist>
- <callout arearefs="nested-booking-available-rooms">
- <para>When requested from EL, the <varname>#{availableRooms}</varname> are loaded by the <varname>@Factory</varname>
+ <calloutlist>
+ <callout arearefs="nested-booking-available-rooms">
+ <para>When requested from EL, the <varname>#{availableRooms}</varname> are loaded by the <varname>@Factory</varname>
method defined in <varname>RoomPreferenceAction</varname>. The <varname>@Factory</varname> method will only be executed once to load the values
into the current context as a <link linkend="datamodel-annotation">
<varname>@DataModel</varname>
</link> instance.</para>
- </callout>
- <callout arearefs="nested-booking-selection-action">
- <para>Invoking the <varname>#{roomPreference.selectPreference}</varname> action results in the row being selected
+ </callout>
+ <callout arearefs="nested-booking-selection-action">
+ <para>Invoking the <varname>#{roomPreference.selectPreference}</varname> action results in the row being selected
and set into the <varname>@DataModelSelection</varname>. This value is then outjected to the nested conversation context.</para>
- </callout>
- <callout arearefs="nested-booking-cancel-action">
- <para>Revising the dates simply returns to the <varname>/book.xhtml</varname>. Note that we have not yet nested
+ </callout>
+ <callout arearefs="nested-booking-cancel-action">
+ <para>Revising the dates simply returns to the <varname>/book.xhtml</varname>. Note that we have not yet nested
a conversation (no room preference has been selected), so the current conversation can simply be resumed. The <varname><s:button></varname>
component simply propagates the current conversation when displaying the <varname>/book.xhtml</varname> view.</para>
- </callout>
- </calloutlist>
- </programlistingco>
- </example>
+ </callout>
+ </calloutlist>
+ </programlistingco>
+ </example>
- <para>Now that we have seen how to nest a conversation, let's see how we can confirm the booking once a room has been selected. This
+ <para>Now that we have seen how to nest a conversation, let's see how we can confirm the booking once a room has been selected. This
can be achieved by simply extending the behavior of the <varname>HotelBookingAction</varname>.</para>
-
- <example>
- <title>HotelBookingAction.java</title>
- <!-- Can't use code hightlighting with callouts -->
- <programlistingco>
- <areaspec>
- <area id="nested-booking-end-root" coords="77"/>
- <area id="nested-booking-confirm" coords="82"/>
- <area id="nested-booking-cancel" coords="89" />
- </areaspec>
- <programlisting><![CDATA[@Stateful
+
+ <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
@@ -2896,7 +2915,7 @@
<calloutlist>
<callout arearefs="nested-booking-end-root">
<para>Annotating an action with <link linkend="end-annotation">
- <varname>@End(root=true)</varname>
+ <varname>@End(root=true)</varname>
</link> ends the root conversation which effectively destroys the entire conversation stack.
When any conversation is ended, it's nested conversations are ended as well. As the root is
the conversation that started it all, this is a simple way to destroy and release all state
@@ -2911,7 +2930,7 @@
</callout>
<callout arearefs="nested-booking-cancel">
<para>By simply annotating the cancellation action with <link linkend="end-annotation">
- <varname>@End(root=true, beforeRedirect=true)</varname>
+ <varname>@End(root=true, beforeRedirect=true)</varname>
</link>
we can easily destroy and release all state associated with the
workspace prior to redirecting the user back to the hotel selection view.</para>
@@ -2923,9 +2942,9 @@
<para>Feel free to deploy the application, open many windows or tabs and attempt combinations of various hotels with
various room preferences. Confirming a booking always results in the correct hotel and room preference thanks to the nested
conversation model.</para>
- </section>
- </section>
-
+ </section>
+ </section>
+
<section id="dvdstore">
<title>A complete application featuring Seam and jBPM: the DVD Store example</title>
@@ -3110,7 +3129,7 @@
automatically redirects to the view id when the form is submitted. Alternatively, we could have defined
a navigation rule like this: </para>
- <programlisting role="XML"><![CDATA[<navigation-rule>
+ <programlisting role="XML"><![CDATA[<navigation-rule>
<navigation-case>
<from-outcome>searchResults</from-outcome>
<to-view-id>/search.xhtml</to-view-id>
@@ -3121,7 +3140,7 @@
<para> Then the form would have looked like this: </para>
- <programlisting role="XHTML"><![CDATA[<div id="search">
+ <programlisting role="XHTML"><![CDATA[<div id="search">
<h:form>
<h:inputText value="#{searchAction.searchPattern}"/>
<h:commandButton value="Search" action="searchResults"/>
@@ -3138,7 +3157,7 @@
Both are defined in <literal>WEB-INF/pages.xml</literal>: </para>
<example>
<title></title>
- <programlisting role="XML"><![CDATA[<pages>
+ <programlisting role="XML"><![CDATA[<pages>
<page view-id="/search.xhtml">
<rewrite pattern="/search/{searchPattern}"/>
<rewrite pattern="/search"/>
@@ -3179,7 +3198,7 @@
<para> The redirect takes us to the <literal>search.xhtml</literal> page: </para>
- <programlisting role="XHTML"><![CDATA[<h:dataTable value="#{searchResults}" var="blogEntry">
+ <programlisting role="XHTML"><![CDATA[<h:dataTable value="#{searchResults}" var="blogEntry">
<h:column>
<div>
<s:link view="/entry.xhtml" propagation="none" value="#{blogEntry.title}">
@@ -3197,7 +3216,7 @@
<para> Which again uses "pull"-style MVC to retrieve the actual search results using
Hibernate Search.</para>
- <programlisting role="JAVA"><![CDATA[@Name("searchService")
+ <programlisting role="JAVA"><![CDATA[@Name("searchService")
public class SearchService
{
@@ -3264,7 +3283,7 @@
<para> The <literal>entryAction</literal> component works much like an action class in a traditional
push-MVC action-oriented framework like Struts: </para>
- <programlisting role="JAVA"><![CDATA[@Name("entryAction")
+ <programlisting role="JAVA"><![CDATA[@Name("entryAction")
@Scope(STATELESS)
public class EntryAction
{
@@ -3283,7 +3302,7 @@
<para> Page actions are also declared in <literal>pages.xml</literal>: </para>
- <programlisting role="XML"><![CDATA[<pages>
+ <programlisting role="XML"><![CDATA[<pages>
...
<page view-id="/entry.xhtml">
@@ -3346,7 +3365,7 @@
<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
Modified: trunk/doc/Seam_Reference_Guide/en-US/Xml.xml
===================================================================
--- trunk/doc/Seam_Reference_Guide/en-US/Xml.xml 2008-11-26 04:54:19 UTC (rev 9653)
+++ trunk/doc/Seam_Reference_Guide/en-US/Xml.xml 2008-11-26 05:33:20 UTC (rev 9654)
@@ -1,3 +1,6 @@
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN" "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd">
+
<chapter id="xml">
<title>Configuring Seam components</title>
@@ -11,7 +14,7 @@
properties file or in <literal>web.xml</literal>, and configuration via <literal>components.xml</literal>.
</para>
- <sect1>
+ <section>
<title>Configuring components via property settings</title>
<para>
Seam components may be provided with configuration properties either via servlet context parameters,
@@ -32,9 +35,9 @@
component named <literal>org.jboss.seam.core.manager</literal> with a setter method named
<literal>setConversationTimeout()</literal>.)
</para>
- </sect1>
+ </section>
- <sect1>
+ <section id="xml.descriptor">
<title>Configuring components via <literal>components.xml</literal></title>
<para>
@@ -241,9 +244,9 @@
(at development time). You'll see this approach used in the Seam examples.
</para>
- </sect1>
+ </section>
- <sect1>
+ <section>
<title>Fine-grained configuration files</title>
<para>
If you have a large number of components that need to be configured in XML, it makes much more sense
@@ -282,9 +285,9 @@
Alternatively, you may put configuration for all classes in the <literal>com.helloworld</literal>
package in <literal>com/helloworld/components.xml</literal>.
</para>
- </sect1>
+ </section>
- <sect1>
+ <section>
<title>Configurable property types</title>
<para>
Properties of string, primitive or primitive wrapper type may be configured just as you would expect:
@@ -397,9 +400,9 @@
entire initial value must be a single EL expression.
</para>
- </sect1>
+ </section>
- <sect1>
+ <section>
<title>Using XML Namespaces</title>
<para>
Throughout the examples, there have been two competing ways of declaring components: with and without
@@ -586,7 +589,7 @@
</itemizedlist>
- </sect1>
+ </section>
</chapter>
More information about the seam-commits
mailing list