Seam - 语境相关的组件 [满江红20080327]

本教程假定你已下载JBoss AS 4.0.5并安装了EJB 3.0 profile（请使用JBoss AS安装器）。你也得下载一份Seam并解压到工作目录上。

各示例的目录结构仿效以下形式：

注册示例是个极其普通的应用，它可让新用户在数据库中保存自己的用户名，真实的姓名及密码。 此示例并不想一下子就把Seam的所有的酷功能全部秀出。然而， 它演示了EJB3 会话Bean作为JSF动作监听器及Seam的基本配置的使用方法。

或许你对EJB 3.0还不太熟悉，因此我们会对示例的慢慢深入说明。

此示例的首页显示了一个非常简单的表单，它有三个输入字段。试着在表单上填写内容并提交，一旦输入数据被提交后就会在数据库中保存一个user对象。

1.2.1. 了解代码

本示例由两个JSP页面，一个实体Bean及无状态的会话Bean来实现。

让我们看一下代码，就从最“底层”的实体Bean开始吧。

1.2.1.1. 实体Bean：User.java

我们需要EJB 实体Bean来保存用户数据。这个类通过注解声明性地定义了 persistence 及 validation 属性。它也需要一些额外的注解来将这个类定义为Seam的组件。

Example 1.1. 

@Entity                                                                                  (1)
@Name("user")                                                                            (2)
@Scope(SESSION)                                                                          (3)
@Table(name="users")                                                                     (4)
public class User implements Serializable
{
   private static final long serialVersionUID = 1881413500711441951L;

   private String username;                                                              (5)
   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() {}                                                                      (6)

   @NotNull @Length(min=5, max=15)                                                       (7)
   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)                                                   (8)
   public String getUsername()
   {
      return username;
   }

   public void setUsername(String username)
   {
      this.username = username;
   }

}

(1)	EJB3标准注解 @Entity 表明了 User 类是个实体Bean.
(2)	Seam组件需要一个 组件名称，此名称由注解 @Name来指定。此名称必须在Seam应用内唯一。当JSF用一个与组件同名的名称去请求Seam来解析上下文变量， 且该上下文变量尚未定义（null）时，Seam就将实例化那个组件，并将新实例绑定给上下文变量。 在此例中，Seam将在JSF第一次遇到名为 user 的变量时实例化 User。
(3)	每当Seam实例化一个组件时，它就将始化后的实例绑定给组件中 默认上下文 的上下文变量。默认的上下文由 @Scope注解指定。 User Bean是个会话作用域的组件。
(4)	EJB标准注解@Table 表明了将 User 类映射到 users 表上。
(5)	name、 password 及 username 都是实体Bean的持久化属性。所有的持久化属性都定义了访问方法。当JSF渲染输出及更新模型值阶段时需要调用该组件的这些方法。
(6)	EJB和Seam都要求有空的构造器。
(7)	@NotNull 和 @Length 注解是Hibernate Validator框架的组成部份， Seam集成了Hibernate Validator并让你用它来作为数据校验（尽管你可能并不使用Hibernate作为持久化层）。
(8)	标准EJB注解 @Id 表明了实体Bean的主键属性。

这个例子中最值得注意的是 @Name 和 @Scope 注解，它们确立了这个类是Seam的组件。

接下来我们将看到 User 类字段在更新模型值阶段时直接被绑定给JSF组件并由JSF操作， 在此并不需要冗余的胶水代码来在JSP页面与实体Bean域模型间来回拷贝数据。

然而，实体Bean不应该进行事务管理或数据库访问。故此，我们无法将此组件作为JSF动作监听器，因而需要会话Bean。

1.2.1.2. 无状态会话Bean：RegisterAction.java

在Seam应用中大都采用会话Bean来作为JSF动作监听器（当然我们也可选择JavaBean）。

在我们的应用程序中确实存在一个JSF动作和一个会话Bean方法。在此示例中，只有一个JSF动作，并且我们使用会话Bean方法与之相关联并使用无状态Bean，这是由于所有与动作相关的状态都保存在 User Bean中。

这是示例中比较有趣的代码部份：

Example 1.2. 

@Stateless                                                                               (1)
@Name("register")
public class RegisterAction implements Register
{

   @In                                                                                   (2)
   private User user;

   @PersistenceContext                                                                   (3)
   private EntityManager em;

   @Logger                                                                               (4)
   private Log log;

   public String register()                                                              (5)
   {
      List existing = em.createQuery(
         "select username from User where username=#{user.username}")                    (6)
         .getResultList();

      if (existing.size()==0)
      {
         em.persist(user);
         log.info("Registered new user #{user.username}");                               (7)
         return "/registered.jsp";                                                       (8)
      }
      else
      {
         FacesMessages.instance().add("User #{user.username} already exists");           (9)
         return null;
      }
   }

}

(1)	EJB标准注解 @Stateless 将这个类标记为无状态的会话Bean。
(2)	注解 @In将Bean的一个属性标记为由Seam来注入。 在此例中，此属性由名为 user 的上下文变量注入（实例的变量名）。
(3)	EJB标准注解 @PersistenceContext 用来注入EJB实体管理器。
(4)	Seam的 @Logger 注解用来注入组件的 Log 实例。
(5)	动作监听器方法使用标准的EJB3 EntityManager API来与数据库交互，并返回JSF的输出结果。 请注意，由于这是个会话Bean，因此当 register() 方法被调用时事务就会自动开始，并在结束时提交（commit）。
(6)	请注意Seam让你在EJB-QL中使用JSF EL表达式。因此可在标准JPA Query 对象上调用普通的JPA setParameter() 方法，这样岂不妙哉？
(7)	Log API为显示模板化的日志消息提供了便利。
(8)	多个JSF动作监听器方法返回一个字符串值的输出，它决定了接下来应显示的页面内容。 空输出（或返回值为空的动作监听器方法）重新显示上一页的内容。 在普通的JSF中，用JSF的导航规则（navigation rule） 来决定输出结果的JSF视图id是很常用的。 这种间接性对于复杂的应用是非常有用的，值得去实践。但是，对于象示例这样简单的的应用，Seam让你使用JSF视图id作为输出结果，以减少对导航规则的需求。请注意，当你用视图id作为输出结果时，Seam总会执行一次浏览器的重定向。
(9)	Seam提供了大量的 内置组件（built-in components） 来协助解决那些经常遇到的问题。 用 FacesMessages 组件就可很容易地来显示模板化的错误或成功的消息。 内置的Seam组件还可由注入或通过调用 instance() 方法来获取。

这次我们并没有显式指定 @Scope，若没有显式指定时，每个Seam 组件类型就使用其默认的作用域。对于无状态的会话Bean， 其默认的作用域就是无状态的上下文。实际上 所有的 无状态的会话Bean都属于无状态的上下文。

会话Bean的动作监听器在此小应用中履行了业务和持久化逻辑。在更复杂的应用中，我们可能要将代码分层并重构持久化逻辑层成 专用数据存取组件，这很容易做到。但请注意Sean并不强制你在应用分层时使用某种特定的分层策略。

此外，也请注意我们的SessionBean会同步访问与web请求相关联的上下文（比如在 User 对象中的表单的值），状态会被保持在事务型的资源里（EntityManager 对象）。 这是对传统J2EE的体系结构的突破。再次说明，如果你习惯于传统J2EE的分层，也可以在你的Seam应用实行。但是对于许多的应用，这是明显的没有必要 。

1.2.1.3. 会话Bean的本地接口：Register.java

很自然，我们的会话Bean需要一个本地接口。

Example 1.3. 

@Local
public interface Register
{
   public String register();
}

所有的Java代码就这些了，现在去看一下部署描述文件。

1.2.1.4. Seam组件部署描述文件：components.xml

如果你此前曾接触过许多的Java框架，你就会习惯于将所有的组件类放在某种XML文件中来声明，那些文件就会随着项目的不断成熟而不断加大到最终到不可收拾的地步。 对于Seam应用，你尽可放心，因为它并不要求应用组件都要有相应的XML。大部份的Seam应用要求非常少量的XML即可，且XML文件大小不会随着项目的增大而快速增长。

无论如何，若能为 某些 组件（特别是Seam内置组件）提供某些 外部配置往往是有用的。这样一来，我们就有几个选择， 但最灵活的选择还是使用位于 WEB-INF 目录下的 components.xml 配置文件。 我们将用 components.xml 文件来演示Seam怎样在JNDI中找到EJB组件:

Example 1.4. 

<components xmlns="http://jboss.com/products/seam/components"
            xmlns:core="http://jboss.com/products/seam/core">
     <core:init jndi-pattern="@jndiPattern@"/>
</components>

此代码配置了Seam内置组件 org.jboss.seam.core.init 的 jndiPattern 属性。这里需要奇怪的@符号是因为ANT脚本会在部署应用时将正确的JNDI语法在标记处自动填补

1.2.1.5. Web部署描述文件：web.xml

我们将以WAR的形式来部署此小应用的表示层，因此需要web部署描述文件。

Example 1.5. 

<?xml version="1.0" encoding="UTF-8"?>
<web-app version="2.5"
    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">

    <!-- Seam -->

    <listener>
        <listener-class>org.jboss.seam.servlet.SeamListener</listener-class>
    </listener>

    <!-- MyFaces -->

    <listener>
        <listener-class>
            org.apache.myfaces.webapp.StartupServletContextListener
        </listener-class>
    </listener>

    <context-param>
        <param-name>javax.faces.STATE_SAVING_METHOD</param-name>
        <param-value>client</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>

    <!-- Faces Servlet Mapping -->
    <servlet-mapping>
        <servlet-name>Faces Servlet</servlet-name>
        <url-pattern>*.seam</url-pattern>
    </servlet-mapping>

</web-app>

此 web.xml 文件配置了Seam和JSF。所有Seam应用中的配置与此处的配置基本相同。

1.2.1.6. JSF配置：faces-config.xml

绝大多数的Seam应用将JSF来作为表示层。因而我们通常需要 faces-config.xml。SEAM将用Facelet定义视图表现层，所以我们需要告诉JSF用Facelet作为它的模板引擎。

Example 1.6. 

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE faces-config
PUBLIC "-//Sun Microsystems, Inc.//DTD JavaServer Faces Config 1.0//EN"
                            "http://java.sun.com/dtd/web-facesconfig_1_0.dtd">
<faces-config>

    <!-- A phase listener is needed by all Seam applications -->

    <lifecycle>
        <phase-listener>org.jboss.seam.jsf.SeamPhaseListener</phase-listener>
    </lifecycle>

</faces-config>

注意我们不需要申明任何JSF managed Bean！因为我们所有的managed Bean都是通过经过注释的Seam组件。所以在Seam的应用中，faces-config.xml比原始的JSF更少用到。

实际上，一旦你把所有的基本描述文件配置完毕，你所需写的 唯一类型的 XML文件就是导航规则及可能的jBPM流程定义。对于Seam而言， 流程（process flow） 及 配置数据 是唯一真正属于需要XML定义的。

在此简单的示例中，因为我们将视图页面的ID嵌入到Action代码中，所以我们甚至都不需要定义导航规则。

1.2.1.7. EJB部署描述文件：ejb-jar.xml

ejb-jar.xml 文件将 SeamInterceptor 绑定到压缩包中所有的会话Bean上，以此实现了Seam与EJB3的整合。

<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>

1.2.1.8. EJB持久化部署描述文件：persistence.xml

persistence.xml 文件告诉EJB的持久化层在哪找到数据源，该文件也含有一些厂商特定的设定。此例在程序启动时自动创建数据库Schema。

<?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>

1.2.1.9. 视图：register.xhtml 和 registered.xhtml

对于Seam应用的视图可由任意支持JSF的技术来实现。在此例中，我们使用了JSP，因为大多数的开发人员都很熟悉， 且这里并没有其它太多的要求。（我们建议你在实际开发中使用Facelets）。

Example 1.7. 

<%@ 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>Register New User</title>
 </head>
 <body>
  <f:view>
   <h:form>
     <table border="0">
       <s:validateAll>
         <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>
       </s:validateAll>
     </table>
     <h:messages/>
     <h:commandButton type="submit" value="Register" action="#{register.register}"/>
   </h:form>
  </f:view>
 </body>
</html>

这里的 <s:validateAll>标签是Seam特有的。 该JSF组件告诉JSF让它用实体Bean中所指定的Hibernat验证器注解来验证所有包含输入的字段。

Example 1.8. 

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h" %>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f" %>
<html>
 <head>
  <title>Successfully Registered New User</title>
 </head>
 <body>
  <f:view>
    Welcome, <h:outputText value="#{user.name}"/>,
    you are successfully registered as <h:outputText value="#{user.username}"/>.
  </f:view>
 </body>
</html>

这是个极其普通的使用JSF组件的JSP页面，与Seam毫无相干。

1.2.1.10. EAR部署描述文件：application.xml

最后，因为我们的应用是要部署成EAR的，因此我们也需要部署描述文件。

Example 1.9. 

<?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>
        <java>jboss-seam.jar</java>
    </module>
    <module>
        <java>el-api.jar</java>
    </module>
    <module>
        <java>el-ri.jar</java>
    </module>

</application>

此部署描述文件联接了EAR中的所有模块，并把Web应用绑定到此应用的首页 /seam-registration。

至此，我们了解了整个应用中 所有的 部署描述文件！

在几乎所有的在线应用中都免不了将搜索结果显示成可点击的列表。 因此Sean在JSF层之上提供了特殊的功能，使得我们很容易用EJB-QL或HQL来查询数据并用JSF <h:dataTable> 将查询结果显示成可点击的列表。我们将在接下的例子中演示这一功能。

@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;
   }

}

@Stateful
@Scope(SESSION)
@Name("messageManager")
public class MessageManagerBean implements Serializable, MessageManager
{

   @DataModel                                                                            (1)
   private List<Message> messageList;

   @DataModelSelection                                                                   (2)
   @Out(required=false)                                                                  (3)
   private Message message;

   @PersistenceContext(type=EXTENDED)                                                    (4)
   private EntityManager em;

   @Factory("messageList")                                                               (5)
   public void findMessages()
   {
      messageList = em.createQuery("from Message msg order by msg.datetime desc").getResultList();
   }

   public void select()                                                                  (6)
   {
      message.setRead(true);
   }

   public void delete()                                                                  (7)
   {
      messageList.remove(message);
      em.remove(message);
      message=null;
   }

   @Remove @Destroy                                                                      (8)
   public void destroy() {}

}

@Local
public interface MessageManager
{
   public void findMessages();
   public void select();
   public void delete();
   public void destroy();
}

<%@ 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.text2}"/></div>
   </h:form>
  </f:view>
 </body>
</html>

jBPM提供了先进的工作流程和任务管理的功能。为了体验一下jBPM是如何与Seam集成在一起工作的，在此将给你一个简单的管理“待办事项列表”的应用。由于管理任务列表等功能是jBPM的核心功能，所以在此例中只用了很少的Java代码。

1.4.1. 理解代码

这个例子的核心是jBPM的流程定义（process definition）。此外，还有两个JSP页面和两个简单的JavaBeans（由于他们不用访问数据库，或有其它事务相关的行为，因此并没有用会话Bean）。让我们先从流程定义开始：

Example 1.13. 

<process-definition name="todo">

   <start-state name="start">                                                            (1)
      <transition to="todo"/>
   </start-state>

   <task-node name="todo">                                                               (2)
      <task name="todo" description="#{todoList.description}">                           (3)
         <assignment actor-id="#{actor.id}"/>                                            (4)
      </task>
      <transition to="done"/>
   </task-node>

   <end-state name="done"/>                                                              (5)

</process-definition>

(1)	节点 <start-state> 代表流程的逻辑开始。一旦流程开始时，它就立即转入 todo节点。
(2)	<task-node> 节点代表 等待状态，就是在执行业务流程暂停时，等待一个或多个未完成的任务。
(3)	<task> 元素定义了用户需要完成的任务。 由于在这个节点只有定义了一个任务，当它完成，或恢复执行时我们就转入结束状态。 此任务从Seam中名为 todolist 的组件（JavaBeans之一）获得任务description。
(4)	任务在创建时就会被分配给一个用户或一组用户时。在此示例中，任务是分配给当前用户，该用户从一个内置的名为 actor 的Seam组件中获得。任何Seam组件都可用来执行任务指派。
(5)	<end-state>节点定义业务流程的逻辑结束。当执行到达这个节点时，流程实例就要被销毁。

如果我们用jBossIDE所提供的流程定义编辑器来查看此流程定义，那它就会是这样：

这个文档将我们的 业务流程 定义成节点图。 这可能是最常见的业务流程：只有一个 任务 被执行，当这项任务完成之后，业务流程就结束了。

第一个JavaBean处理登入界面 login.jsp。 它的工作就是用 actor 组件初始化jBPM用户id（在实际的应用中，它也需要验证用户。）

Example 1.14. 

@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";
   }
}

在此我们使用了 @In 来将actor属性值注入到Seam内置的 Actor 组件。

JSP页面本身并没有什么特别之处：

Example 1.15. 

<%@ 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>

第二个JavaBean负责启动业务流程实例及结束任务。

Example 1.16. 

@Name("todoList")
public class TodoList {

   private String description;

   public String getDescription()                                                        (1)
   {
      return description;
   }

   public void setDescription(String description) {
      this.description = description;
   }

   @CreateProcess(definition="todo")                                                     (2)
   public void createTodo() {}

   @StartTask @EndTask                                                                   (3)
   public void done() {}

}

(1)	description属性从JSP页接受用户输入，并将它暴露给流程定义，这样就可让Seam来设定任务的descrption。
(2)	Seam的 @CreateProcess 注解为指定名称的流程定义创建了一个新的jBPM流程实例。
(3)	Seam的 @StartTask 注解用来启动任务，@EndTask 用来结束任务，并允许恢复执行业务流程。

在实际的应用中，@StartTask 及 @EndTask 不会出现在同一个方法中，因为为了完成任务，通常用应用中有许多工作要做。

最后，该应用的主要内容在 todo.jsp 中：

Example 1.17. 

<%@ 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>

让我们对此逐一加以说明。

该JSP页面将从Seam内置组件 taskInstanceList 获得的任务渲染成任务列表，此列表在JSF表单内被定义。

<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>

列表中的每个元素就是一个jBPM类 taskinstance 的实例。 以下代码简单地展示了列表中每一任务的有趣特性。为了让用户能更改description、priority及due date的值，我们使用了输入控件。

<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>

该按钮通过调用被注解为 @StartTask @EndTask 的动作方法来结束任务。它把任务id作为请求参数传给Seam：

<h:column>
    <s:button value="Done" action="#{todoList.done}" taskInstance="#{task}"/>
</h:column>

（请注意，这是在使用Seam seam-ui.jar 包中的JSF <s:button> 控件。）

这个按钮是用来更新任务属性。当提交表单时，Seam和jBPM将直接更改任务的持久化，不需要任何的动作监听器方法：

<h:commandButton value="Update Items" action="update"/>

第二个表单通过调用注解为 @CreateProcess的动作方法来创建新的项目（item）。

<h:form id="new">
    <div>
        <h:inputText value="#{todoList.description}"/>
        <h:commandButton value="Create New Item" action="#{todoList.createTodo}"/>
    </div>
</h:form>

这个例子还需要另外几个文件，但它们只是标准的jBPM和Seam配置并不是很有趣。

对有相对自由（特别）导航的Seam应用程序而言，JSF/Seam导航规则是定义页面流的一个完美的方法。 而对于那些带有更多约束的导航，特别是带状态的用户界面而言，导航规则反而使得系统流程变得难以理解。 要理解整个流程，你需要从视图页面、动作和导航规则里一点点把它拼出来。

Seam允许你使用一个jPDL流程定义来定义页面流。下面这个简单的猜数字范例将演示这一切是如何实现的。

1.5.1. 理解代码

这个例子由一个JavaBean、三个JSP页面和一个jPDL页面流定义组成。让我们从页面流开始：

Example 1.18. 

<pageflow-definition name="numberGuess">

   <start-page name="displayGuess" view-id="/numberGuess.jsp">
      <redirect/>
      <transition name="guess" to="evaluateGuess">
          <action expression="#{numberGuess.guess}" />
      </transition>                                                                      (1)
   </start-page>                                                                         (2)
                                                                                         (3)
   <decision name="evaluateGuess" expression="#{numberGuess.correctGuess}">
      <transition name="true" to="win"/>
      <transition name="false" to="evaluateRemainingGuesses"/>
   </decision>                                                                           (4)

   <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>

(1)	<page>元素定义了一个等待状态，在该状态中系统显示一个JSF视图等待用户输入。 view-id与简单JSF导航规则中的view id一样。 redirect属性告诉Seam在导航到页面时使用post-then-redirect。(这会带来友好的浏览器URL。)
(2)	<transition> 元素命名了一个JSF输出。当一个JSF动作导致那个输出时会触发转换。 在任何jBPM转换动作调用后，执行会进行到页面流程图的下一个节点。
(3)	一个转换动作 <action> 就像JSF动作，不同的就是它只发生在一个jBPM转换发生时。 转换动作能调用任何Seam组件。
(4)	<decision> 节点用来划分页面流，通过计算JSF EL表达式决定要执行的下一个节点。

这个页面流在JBossIDE页面流编辑器里看上去是这个样子的：

看过了页面流，现在再来理解剩下的程序就变得十分简单了!

这是应用程序的主页面numberGuess.jspx：

Example 1.19. 

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<html>
<head>
<title>Guess a number...</title>
</head>
<body>
<h1>Guess a number...</h1>
<f:view>
    <h:form>
        <h:outputText value="Higher!" rendered="#{numberGuess.randomNumber>numberGuess.currentGuess}" />
        <h:outputText value="Lower!" rendered="#{numberGuess.randomNumber<numberGuess.currentGuess}" />
        <br />
        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.
        <br />
        Your guess:
        <h:inputText value="#{numberGuess.currentGuess}" id="guess" required="true">
            <f:validateLongRange
                maximum="#{numberGuess.biggest}"
                minimum="#{numberGuess.smallest}"/>
        </h:inputText>
        <h:commandButton type="submit" value="Guess" action="guess" />
        <br/>
        <h:message for="guess" style="color: red"/>
    </h:form>
</f:view>
</body>
</html>

请注意名为 guess 的命令按钮是如何进行转换而不是直接调用一个动作的。

win.jspx 页面的内容是可想而知的：

Example 1.20. 

<%@ taglib uri="http://java.sun.com/jsf/html" prefix="h"%>
<%@ taglib uri="http://java.sun.com/jsf/core" prefix="f"%>
<html>
<head>
<title>You won!</title>
</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.
    Would you like to <a href="numberGuess.seam">play again</a>?
  </f:view>
</body>
</html>

lose.jsp 也差不多（我就不重复复制/粘贴了）。最后，JavaBean Seam组件是这样的：

Example 1.21. 

@Name("numberGuess")
@Scope(ScopeType.CONVERSATION)
public class NumberGuess {

   private int randomNumber;
   private Integer currentGuess;
   private int biggest;
   private int smallest;
   private int guessCount;
   private int maxGuesses;

   @Create                                                                               (1)
   @Begin(pageflow="numberGuess")                                                        (2)
   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;
   }
}

(1)	一开始，JSP页面请求一个 numberGuess 组件，Seam会为该组件创建一个新的实例，并调用 @Create 方法，允许组件初始化自己。
(2)	@Begin 注解启动了一个Seam 业务会话(conversation) （稍后详细说明），并指定业务会话页面流所要使用的页面流定义。

如你所见，这个Seam组件是纯业务逻辑的！它不需要知道任何关于用户交互的东西。这点使得组件更易被复用。

DVD商店程序演示了如何在任务管理和页面流中使用jBPM。

用户界面应用jPDL页面流实现了搜索和购物车功能。

管理员界面使用jBPM来管理订单的审批和送货周期。业务流程可以通过选择不同的流程定义实现动态改变。

TODO

见dvdstore目录。

Hibernate预订系统是之前客房预订系统的另一个版本，它使用Hibernate和JavaBeans代替了会话Bean实现持久化。

TODO

见hibernate目录。

Seam可以很方便地实现在服务器端保存状态的应用程序。 然而，服务器端状态在有些情况下并不合适，特别是对那些用来提供内容的功能。 针对这类问题，我们常需要让用户能够收藏页面，有一个相对无状态的服务器，这样一来能够在任何时间通过书签来访问那些被收藏的页面。 Blog范例演示了如何用Seam来实现一个RESTful的应用程序。应用程序中的每个页面都能被收藏，包括搜索结果页面。

Blog范例演示了“拉”风格（"pull"-style）的MVC，它不使用动作监听器方法来获取数据和为视图准备数据，而是视图在被显示时从组件中拉数据。

<h:dataTable value="#{blog.recentBlogEntries}" var="blogEntry" rows="3">
   <h:column>
      <div class="blogEntry">
         <h3>#{blogEntry.title}</h3>
         <div>
            <h:outputText escape="false"
                  value="#{blogEntry.excerpt==null ? blogEntry.body : blogEntry.excerpt}"/>
         </div>
         <p>
            <h:outputLink value="entry.seam" rendered="#{blogEntry.excerpt!=null}">
               <f:param name="blogEntryId" value="#{blogEntry.id}"/>
               Read more...
            </h:outputLink>
         </p>
         <p>
            [Posted on
            <h:outputText value="#{blogEntry.date}">
               <f:convertDateTime timeZone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
            </h:outputText>]
            &#160;
            <h:outputLink value="entry.seam">[Link]
               <f:param name="blogEntryId" value="#{blogEntry.id}"/>
            </h:outputLink>
         </p>
      </div>
   </h:column>
</h:dataTable>

@Name("blog")
@Scope(ScopeType.STATELESS)
public class BlogService
{

   @In                                                                                   (1)
   private EntityManager entityManager;

   @Unwrap                                                                               (2)
   public Blog getBlog()
   {
      return (Blog) entityManager.createQuery("from Blog b left join fetch b.blogEntries")
            .setHint("org.hibernate.cacheable", true)
            .getSingleResult();
   }

}

<div id="search">
   <h:form>
      <h:inputText value="#{searchAction.searchPattern}"/>
      <h:commandButton value="Search" action="/search.xhtml"/>
   </h:form>
</div>

<navigation-rule>
   <navigation-case>
      <from-outcome>searchResults</from-outcome>
      <to-view-id>/search.xhtml</to-view-id>
      <redirect/>
   </navigation-case>
</navigation-rule>

<div id="search">
   <h:form>
      <h:inputText value="#{searchAction.searchPattern}"/>
      <h:commandButton value="Search" action="searchResults"/>
   </h:form>
</div>

<pages>
   <page view-id="/search.xhtml">
      <param name="searchPattern" value="#{searchService.searchPattern}"/>
   </page>
   ...
</pages>

<h:dataTable value="#{searchResults}" var="blogEntry">
   <h:column>
      <div>
         <h:outputLink value="entry.seam">
            <f:param name="blogEntryId" value="#{blogEntry.id}"/>
            #{blogEntry.title}
         </h:outputLink>
         posted on
         <h:outputText value="#{blogEntry.date}">
            <f:convertDateTime timeZone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
         </h:outputText>
      </div>
   </h:column>
</h:dataTable>

@Name("searchService")
public class SearchService
{

   @In
   private EntityManager entityManager;

   private String searchPattern;

   @Factory("searchResults")
   public List<BlogEntry> getSearchResults()
   {
      if (searchPattern==null)
      {
         return null;
      }
      else
      {
         return entityManager.createQuery("select be from BlogEntry be where lower(be.title) like :searchPattern or lower(be.body) like :searchPattern order by be.date desc")
               .setParameter( "searchPattern", getSqlSearchPattern() )
               .setMaxResults(100)
               .getResultList();
      }
   }

   private String getSqlSearchPattern()
   {
      return searchPattern==null ? "" : '%' + searchPattern.toLowerCase().replace('*', '%').replace('?', '_') + '%';
   }

   public String getSearchPattern()
   {
      return searchPattern;
   }

   public void setSearchPattern(String searchPattern)
   {
      this.searchPattern = searchPattern;
   }

}

@Name("entryAction")
@Scope(STATELESS)
public class EntryAction
{
   @In(create=true)
   private Blog blog;

   @Out
   private BlogEntry blogEntry;

   public void loadBlogEntry(String id) throws EntryNotFoundException
   {
      blogEntry = blog.getBlogEntry(id);
      if (blogEntry==null) throw new EntryNotFoundException(id);
   }

}

<pages>
   ...

   <page view-id="/entry.xhtml" action="#{entryAction.loadBlogEntry(blogEntry.id)}">
      <param name="blogEntryId" value="#{blogEntry.id}"/>
   </page>

   <page view-id="/post.xhtml" action="#{loginAction.challenge}"/>

   <page view-id="*" action="#{blog.hitCount.hit}"/>

</pages>

<div class="blogEntry">
   <h3>#{blogEntry.title}</h3>
   <div>
      <h:outputText escape="false" value="#{blogEntry.body}"/>
   </div>
   <p>
      [Posted on&#160;
      <h:outputText value="#{blogEntry.date}">
         <f:convertDateTime timezone="#{blog.timeZone}" locale="#{blog.locale}" type="both"/>
      </h:outputText>]
   </p>
</div>

@ApplicationException(rollback=true)
@HttpError(errorCode=HttpServletResponse.SC_NOT_FOUND)
public class EntryNotFoundException extends Exception
{
   EntryNotFoundException(String id)
   {
      super("entry not found: " + id);
   }
}

@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);
   }

}

<pages>
   ...

   <page view-id="/entry.xhtml" action="#{entryAction.loadBlogEntry}">
      <param name="blogEntryId" value="#{blogEntry.id}"/>
   </page>

   ...
</pages>

请确保已安装了JDK 5或者JDK6，JBoss AS 4.2和Ant 1.6，以及较新版的Eclipse、JBoss IDE和TestNG的Eclipse 插件。 在Eclipse的JBoss Server View中将JBoss安装路径添加进去。然后以debug模式启动JBoss，并在弹出式命令窗口中进入Seam的目录。

JBoss很好地支持WAR和EAR的热重部署，但麻烦的是，由于在JVM中存在着多个Bug，在开发进程中多次的重部署EAR是常见的事，但这最终会耗尽PermGen 空间（Permanent Generation Space）。 因此建议你在开发的过程中加大perm gen空间。若你是在JBoss IDE中运行JBoss，那你就可以在服务器运行配置中的VM arguments进行配置，建议依此修改：

-Xms512m -Xmx1024m -XX:PermSize=256m -XX:MaxPermSize=512

如果你没有那么多的可用内存，你只好用我们推荐的最小内存了：

-Xms256m -Xmx512m -XX:PermSize=128m -XX:MaxPermSize=256

若是在命令行模式中运行JBoss，那你就要在 bin/run.conf 文件中对JVM选项作修改了。

当然，我们可以先不理会这些。当你在开发中第一次碰到 OutOfMemoryException 异常时再回过头来作此修改。

首先，我们需要根据现有的开发环境对seam-gen进行配置：JBoss AS安装目录、Eclipse workspace及数据库连接。这些都很容易，只要敲入：

cd jboss-seam-2.0.x
seam setup

根据弹出的提示输入开发环境的相关信息:

C:\Projects\jboss-seam>seam setup
Buildfile: build.xml

setup:
    [echo] Welcome to seam-gen :-)
    [input] Enter your Java project workspace [C:/Projects]

    [input] Enter your JBoss home directory [C:/Program Files/jboss-4.2.0.GA]

    [input] Enter the project name [myproject]
helloworld
    [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]
org.jboss.helloworld
    [input] Enter the Java package name for your entity beans [org.jboss.helloworld]

    [input] Enter the Java package name for your test cases [org.jboss.helloworld.test]

    [input] What kind of database are you using? [hsql] (hsql,mysql,oracle,postgres,mssql,db2,sybase,)
mysql
    [input] Enter the Hibernate dialect for your database [org.hibernate.dialect.MySQLDialect]

    [input] Enter the filesystem path to the JDBC driver jar [lib/hsqldb.jar]
../../mysql-connector.jar
    [input] Enter JDBC driver class for your database [com.mysql.jdbc.Driver]

    [input] Enter the JDBC URL for your database [jdbc:mysql:///test]

    [input] Enter database username [sa]
gavin
    [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
[propertyfile] Creating new property file: C:\Projects\jboss-seam\seam-gen\build.properties
     [echo] Installing JDBC driver jar to JBoss server
     [echo] Type 'seam new-project' to create the new project

BUILD SUCCESSFUL
Total time: 1 minute 17 seconds
C:\Projects\jboss-seam>

该工具提供了相应的默认值，因此你可以直接按Enter键。

最重要的是你要对EAR部署还是WAR部署进行选择。EAR项目支持EJB 3.0 并需要Java EE 5。而WAR包不支持EJB 3.0，但可在J2EE环境中部署。 另外WAR也更较简单，便于理解。假若你已安装了EJB3 profile，那你就用ear好了，否则，就只好用 war。 在此假设我们选择了EAR部署，当然此教程也适用于WAR部署。

如果你手上有现成的数据模型，请确保你已输入现有数据库的表名。

这些设置保存在 seam-gen/build.properties 文件中，但你可通过运行 seam setup 来再次修改。

现在我们就可以在Eclipse workspace目录中创建一个新的项目，只需输入：

seam new-project

C:\Projects\jboss-seam>seam new-project
Buildfile: build.xml

validate-workspace:

validate-project:

copy-lib:
     [echo] Copying project jars ...
     [copy] Copying 58 files to C:\Projects\helloworld\lib
     [copy] Copying 9 files to C:\Projects\helloworld\embedded-ejb

file-copy-war:

file-copy-ear:
     [echo] Copying resources needed for EAR deployment to the C:\Projects\helloworld/resources directory...

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>

这组操作复制了Seam jar文件及相应的jar文件与JDBC驱动jar到新建的Eclipse项目中，并生成了所需的源文件及其配置文件、一个模板文件和样式文件，及相应的Eclipse元数据及Ant构建脚本。 只要你依此操作 New -> Project... -> General -> Project -> Next，输入Project name （此例为helloworld），并接着点击 Finish，就可将Eclipse项目自动部署到JBoss AS分解式的（exploded）目录结构中，请不要在新项目向导中选择 Java Project。

若Eclipse中的默认的JDK不是Java SE 5 或Java SE 6，你就得通过 Project -> Properties -> Java Compiler 来选择与Java SE 5 兼容的JDK。

另外，可在Eclipse之外输入 seam explode 来部署项目。

在 http://localhost:8080/helloworld 中查看此应用的首页。 view/home.xhtml 是个使用 view/layout/template.xhtml 模板生成的Facelets 页面，试着在Eclipse中编辑此页面或该模板，并在浏览器中刷新页面，立即看到结果。

别被在项目目录中的如此多的XML配置文件给吓晕了。那都是些标准的Java EE的东西，它们只需生成一次就不用再去理会了。 在所有的Seam项目中，90%的配置内容都是一样的（这些可由seam-gen来帮我们完成）。

新生成的项目包含了三个数据库及持久化配置文件。jboss-beans.xml、persistence-test.xml 及 import-test.sql 文件是用在当TestNG对HSQLDB进行单元测试时。 在 import-test.sql 中的数据库Schema及其测试数据总是在测试前就已转入数据库中。 myproject-dev-ds.xml、persistence-dev.xml 及 import-dev.sql 文件是在部署应用到开发数据库时使用的。 数据库schema是否可在部署时自动导出，取决于你是否在设置seam-gen环境时配置了已存在的数据库。 myproject-prod-ds.xml、persistence-prod.xml 及 import-prod.sql 文件是在部署应用到生产数据库时使用的。在部署时数据库schema并不自动导出。

若你熟知传统的action-style Web框架，你或许想知道在Java中如何来创建无状态action方法的简单Web页面。如果你输入：

seam new-action

则Seam将弹出一些信息并为你的项目生成新的Facelets页面及Seam组件。

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\action\org\jboss\helloworld
     [copy] Copying 1 file to C:\Projects\helloworld\src\action\org\jboss\helloworld
     [copy] Copying 1 file to C:\Projects\helloworld\src\action\org\jboss\helloworld\test
     [copy] Copying 1 file to C:\Projects\helloworld\src\action\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>

新增Seam组件后，我们需要重启分解式目录部署（exploded directory deployment）。 输入seam restart，或在Eclipse中已生成项目的 build.xml 中运行 restart target就可完成。 另一种方式是在Eclipse中通过编辑 resources/META-INF/application.xml 文件来强制重启。 请注意，在每次修改应用程序时并不需要重启JBoss。

试着在浏览器中输入 http://localhost:8080/helloworld/ping.seam 地址并点击按钮，看看发生了什么。 在项目的 src 目录中可看到完成此动作的源代码。 试着在 ping() 方法中设置个断点，再次点击按钮，又发生了什么？

最后，在测试包中找到 PingTest.xml 文件，并用Eclipse的TestNG插件来运行测试。 此外，还可用 seam test 或生成的build文件中的 test target来运行测试。

下一步就是来创建表单了。请输入：

seam new-form

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\com\hello
     [copy] Copying 1 file to C:\Projects\hello\src\com\hello
     [copy] Copying 1 file to C:\Projects\hello\src\com\hello\test
     [copy] Copying 1 file to C:\Projects\hello\view
     [copy] Copying 1 file to C:\Projects\hello\src\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>

再次重启应用程序，并在浏览器中输入 http://localhost:8080/helloworld/hello.seam 就可看到结果了。 接着看下所生成的代码，并运行测试。试着给表单加入一些字段及Seam组件（记着在每次更改Java代码时重新部署）。

在数据库中手工创建一些表。（如果你需要切换不同的数据库，只需再次运行 seam setup 即可。）现请输入：

seam generate-entities

接着重新部署，并在浏览器中输入 http://localhost:8080/helloworld 就可看到结果了。 你可以试着浏览数据库，编辑现有的对象，并创建新的对象。如果你看下所生成的代码，你可能会对如此简单的代码感到惊讶。 让开发人员，尤其是那些不甘于受Seam-gen摆布的开发人员，简单地手工编写数据访问代码，是Seam的设计目标之一。

最后，我们想知道能否用标准的Java EE包来部署应用。首先，通过运行 seam unexplode 来移走分解式目录（exploded directory)。 在命令行中输入 seam deploy 或运行生成的Build脚本文件中的 deploy target就可完成EAR的部署，用 seam undeploy 命令或运行 undeploy 目标可卸下EAR。

默认情况下，应用程序会用 dev profile 来部署，EAR将包含persistence-dev.xml及import-dev.sql文件，myproject-dev-ds.xml 文件也会被部署。 通过输入以下的命令你就可以更改profile, 并可使用 prod profile：

seam -Dprofile=prod deploy

你甚至可以给你的应用程序定义新的部署profile，只需在项目中加入合适的文件， 例如：persistence-staging.xml、import-staging.sql 及 myproject-staging-ds.xml — 并选择使用了 -Dprofile=staging 名字的profile。

将Seam应用部署成exploded目录的好处是，你能在开发时得到增量热部署的支持。 你只需在 components.xml 中添加这一行来启用Seam和Facelet中的debug模式即可:

<core:init debug="true"/>

这样一来，重新部署以下文件时就不一定要完全地重启web应用了：

若想对Java代码进行变更，就需要完全的应用重启。 （在JBoss中，对于EAR部署，这需要用touch命令改变顶层的部署描述文件：对于EAR部署，则是application.xml，而对于WAR部署，则是web.xml 。）

但你真正想加快编辑/编译/测试的流程，Seam支持对JavaBean组件进行增量式重部署。 为了用上此功能，你必须把JavaBean组件部署到 WEB-INF/dev 目录中，以便它们能被特殊的Seam类加载器加载，而不是WAR或EAR类加载器。

请注意以下的限制：

如果你用Seam-gen创建WAR项目，增量热部署对于src/action目录下的类是直接可用的，但是对于EAR项目不行。

Seam 2.0是针对JavaServer Faces 1.2开发的，所以我们推荐在JBoss 4.2下使用Seam，因为它包含了JSF 1.2参考实现。 然而仍然有办法在Jboss 4.0下使用Seam。需要两个步骤：安装启用了EJB3的Jboss 4.0版本并且把MyFaces替换为JSF1.2参考实现。 你完成这两个步骤后，Seam2.0就可以在JBoss 4.0下部署了。

我们目前为止所看到的例子仅仅使用非常简单的对话模型，它遵循以下这些规则：

Seam透明地在JSF postback以及重定向redirect时传递对话上下文。 如果你不需要做任何特殊的事情，使用 “non-faces request” （例如GET请求）就不会传递对话上下文，并且它会在一个新的临时对话中被处理。这通常（但并非总是）是我们期望的一种行为。

如果你希望在“non-faces request”中传递Seam对话，就需要显式地将Seam的 conversation id 编写为一个request参数：

<a href="main.jsf?conversationId=#{conversation.id}">Continue</a>

或者更JSF的做法是：

<h:outputLink value="main.jsf">
    <f:param name="conversationId" value="#{conversation.id}"/>
    <h:outputText value="Continue"/>
</h:outputLink>

如果你使用Seam标签库，就等同于：

<h:outputLink value="main.jsf">
    <s:conversationId/>
    <h:outputText value="Continue"/>
</h:outputLink>

如果你不想给一个postback传播会话上下文，可以使用一个类似的小窍门：

<h:commandLink action="main" value="Exit">
    <f:param name="conversationPropagation" value="none"/>
</h:commandLink>

如果你使用Seam标签库，则等同于：

<h:commandLink action="main" value="Exit">
    <s:conversationPropagation type="none"/>
</h:commandLink>

注意不使用对话上下文传播与结束对话绝对不是同一回事。

请求参数 conversationPropagation，或者 <s:conversationPropagation> 标签甚至都可以用来开始和结束对话，或者开始一个嵌套对话。

<h:commandLink action="main" value="Exit">
    <s:conversationPropagation type="end"/>
</h:commandLink>

<h:commandLink action="main" value="Select Child">
    <s:conversationPropagation type="nested"/>
</h:commandLink>

<h:commandLink action="main" value="Select Hotel">
    <s:conversationPropagation type="begin"/>
</h:commandLink>

<h:commandLink action="main" value="Select Hotel">
    <s:conversationPropagation type="join"/>
</h:commandLink>

这种会话模型可以非常容易地创建基于多窗口操作的应用系统。对于许多应用程序来说，这已经足够了。 但是另外一些复杂的应用程序还会需要以下额外需求中的一点或两点。

嵌套对话是通过在一个现有对话的范围内调用一个名为 @Begin(nested=true) 的方法进行创建的。 嵌套对话有它自己的对话上下文，还可以只读地访问外部对话的上下文（它可以读取外部对话的上下文变量，但是不可以写）。 随后当遇到 @End 时，嵌套对话会被销毁，并且外部对话会弹出会话堆栈继续运行。 理论上，对话可以嵌套到任意层深。

某个用户活动（工作区管理，或返回按钮）可以在内部对话结束之前就恢复外部对话。 在这种情况下，一个外部对话就有可能同时拥有多个嵌套对话。 如果外部对话在嵌套对话之前就被结束，Seam将会把嵌套对话和外部对话一起销毁掉。

对话可以被认为是一个 连续的状态 。 嵌套对话允许应用程序在不同的用户交互点捕捉一致连续的状态，因此必须确保在返回按钮以及工作区管理的面上有真正的正确行为。

TODO：说明当你点击返回按钮时嵌套对话如何防止错误发生的一个例子。

通常，如果一个组件存在于当前嵌套对话的父对话中，嵌套对话会使用同一个实例。 少数情况下，在每个嵌套对话中都使用不同的实例会很有用，以便存在于父对话中的组件实例对其子对话是不可见的。 你可以通过给这个组件注解 @PerNestedConversation 来实现。

JSF并没有定义任何类型的action监听器，这种监听器会在通过非JSF请求“non-faces request”访问页面的时候被触发（例如，一个HTTP GET请求）。 这种触发会发生在当用户用书签保存了这个页面，或者在我们通过 <h:outputLink> 访问页面的时候。

有时候，我们希望在访问页面的时候立即开始一个对话。 由于没有JSF action方法，我们不能以寻常的通过用 @Begin 标注action的方式来解决这个问题，

当页面需要把一些状态抓取到上下文变量中时，另一个问题也就随之产生了。我们已经看到有两种方法可以解决这个问题。 如果这个状态是Seam组件所持有的，我们就可以通过 @Create 方法来抓取。 如果不是，我们就可以为这个上下文变量定义一个 @Factory 方法。

如果以上两种办法都不适合你，Seam还允许你在 pages.xml 文件中定义一个 page action 。

<pages>
    <page view-id="/messageList.jsp" action="#{messageManager.list}"/>
    ...
</pages>

这个action方法在开始渲染响应阶段的时候被调用，即在页面就要被渲染的任何时候。 如果页面action返回一个非空的值，Seam将会根据Seam导航规则处理任何合适的JSF，可能导致渲染另外一个完全不同的页面。

如果你在渲染页面之前想要做的 仅仅 是开始一个对话，那你可以使用一个内建的action方法，它正好具备这种功能：

<pages>
    <page view-id="/messageList.jsp" action="#{conversation.begin}"/>
    ...
</pages>

注意你也可以从JSF控制器中调用内建的action来开始一个对话，同样地，你可以使用 #{conversation.end} 来结束一个对话。

如果你想要更多的控制，以加入现有的对话或开始一个嵌套对话，开始一个页面流或者开始一个原子的对话，你应该使用 <begin-conversation> 元素。

<pages>
    <page view-id="/messageList.jsp">
       <begin-conversation nested="true" pageflow="AddItem"/>
    <page>
    ...
</pages>

<end-conversation>元素也可以结束一个对话。

<pages>
    <page view-id="/home.jsp">
       <end-conversation/>
    <page>
    ...
</pages>

为了解决第一个问题，我们现在有五种选择：

JSF命令链始终通过JavaScript来执行一个表单提交，它打破了浏览器的“在新窗口中打开”或者“在新标签中打开”这种特点。 在普通的JSF中，如果你需要这项功能，就需要使用 <h:outputLink>。 但是 <h:outputLink> 标签有两大限制。

Seam提供了一个 page action 的概念来帮助解决第一个问题，但是这对于第二个问题却无能为力。 我们 可以 利用REST的方法传递请求参数以及重新查询服务端的选中对象来解决这个问题。 在某些情况下——例如Seam博客上范例应用程序那样——这实际上最好的方法。REST风格支持书签，因为它不需要服务器端的状态。 在其他那些我们不需要关心书签的情况下，使用 @DataModel 以及 @DataModelSelection 就很方便也很透明！

为了填补这项缺失的功能，也为了使对话传播的管理变得更加简单，Seam提供 <s:link> 这样一个JSF标签。

这个连接可以仅指定JSF视图的id：

<s:link view="/login.xhtml" value="Login"/>

或者，它可以指定一个action方法（在这种情况下action的输出将会决定结果页面）：

<s:link action="#{login.logout}" value="Logout"/>

如果你把JSF视图id和action方法这 两者 都指定的话，“视图”将会被使用， 除非action方法返回一个非空的结果：

<s:link view="/loggedOut.xhtml"  action="#{login.logout}" value="Logout"/>

这个连接自动地利用内部的 <h:dataTable> 传播 DataModel 的所选行。

<s:link view="/hotel.xhtml" action="#{hotelSearch.selectHotel}" value="#{hotel.name}"/>

你可以不指定现有对话的范围：

<s:link view="/main.xhtml" propagation="none"/>

你可以开始、结束或者嵌套对话：

<s:link action="#{issueEditor.viewComment}" propagation="nest"/>

如果一个连接开始了一个对话，你甚至可以指定一个要使用的页面流：

<s:link action="#{documentEditor.getDocument}" propagation="begin"
        pageflow="EditDocument"/>

如果使用jBPM任务列表，那么你可以使用 taskInstance 属性：

<s:link action="#{documentApproval.approveOrReject}" taskInstance="#{task}"/>

（请见DVD Store演示的应用程序中针对以上用法的范例。）

最后，如果你希望“链接”被渲染成为一个按钮，就使用 <s:button>：

<s:button action="#{login.logout}" value="Logout"/>

给用户显示一条action执行成功或者失败的消息是相当常见的功能。为此使用JSF的 FacesMessage 是非常方便的。 不幸的是，成功的action通常需要一个浏览器重定向。这使得在普通的JSF中显示成功信息变得相当困难。

内建的会话范围的Seam组件 facesMessages 解决了这个问题。 （你必须安装Seam重定向过滤器。）

@Name("editDocumentAction")
@Stateless
public class EditDocumentBean implements EditDocument {
    @In EntityManager em;
    @In Document document;
    @In FacesMessages facesMessages;

    public String update() {
        em.merge(document);
        facesMessages.add("Document updated");
    }
}

对于当前的会话来说，任何加入到 facesMessages 的消息都正好用在下一个渲染阶段中。 甚至当没有“长时间运行”对话的时候也会奏效，因为Seam甚至在重定向过程中保留了临时对话。

你甚至可以在faces message概述中包含JSF EL表达式：

facesMessages.add("Document #{document.title} was updated");

你可以按照通常的方式显示消息，例如：

<h:messages globalOnly="true"/>

通常情况下，Seam会给每个对话产生一个无意义且唯一的id。你可以在你开始一个对话的时候定制id的值。

这个特性可以用来定制会话id生成算法，像这样：

@Begin(id="#{myConversationIdGenerator.nextId}")
public void editHotel() { ... }

或者它可以用来分配一个有意义的对话id：

@Begin(id="hotel#{hotel.id}")
public String editHotel() { ... }

@Begin(id="hotel#{hotelsDataModel.rowData.id}")
public String selectHotel() { ... }

@Begin(id="entry#{params['blogId']}")
public String viewBlogEntry() { ... }

@BeginTask(id="task#{taskInstance.id}")
public String approveDocument() { ... }

毫无疑问，每当选中一家特殊的酒店、一篇特殊的博客或者一项特殊的任务时，这些例子都会产生一个相同的对话id。 那么，如果一相新对话开始时已经存在一个包含相同对话id的对话时，会发生什么情况呢？ 嗯，Seam竟然会发现现有的对话，并重定向到该对话，而不去再次运行 @Begin 方法。 这个特性会帮助我们控制在使用工作区管理时创建的多个工作区。

工作区管理指的是可以在一个单独的窗口中"切换"多个对话的能力。 Seam在Java代码级别完全透明地管理工作区。为了启用工作区管理，你所需要做的全部事情如下：

<pages>
    <page view-id="/main.xhtml">Search hotels: #{hotelBooking.searchString}</page>
    <page view-id="/hotel.xhtml">View hotel: #{hotel.name}</page>
    <page view-id="/book.xhtml">Book hotel: #{hotel.name}</page>
    <page view-id="/confirm.xhtml">Confirm: #{booking.description}</page>
</pages>

<pageflow-definition name="shopping">

   <start-state name="start">
      <transition to="browse"/>
   </start-state>

   <page name="browse" view-id="/browse.xhtml">
      <description>DVD Search: #{search.searchPattern}</description>
      <transition to="browse"/>
      <transition name="checkout" to="checkout"/>
   </page>

   <page name="checkout" view-id="/checkout.xhtml">
      <description>Purchase: $#{cart.total}</description>
      <transition to="checkout"/>
      <transition name="complete" to="complete"/>
   </page>

   <page name="complete" view-id="/complete.xhtml">
      <end-conversation />
   </page>

</pageflow-definition>

6.7.3. 对话转换器

在你的JSP或facelets页面中包含以下代码片断，以获得使你可以转换到任何当前对话或者应用程序的任何其他页面的一个下拉菜单：

<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"/>

In this example, we have a menu that includes an item for each conversation, together with two additional items that let the user begin a new conversation. 在这个例子中，我们有一菜单，它为每一个对话都包含了一个条目，另外还有两个让用户开始新对话的条目。

Only conversations with a description will be included in the drop-down menu.

6.7.4. 对话列表

除了对话列表会显示成为一个表格以外，它与对话转换器非常相似：

<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>

我们设想你想要根据你自己的应用程序去定制这个。

只有带有描述的对话才会被包含在列表中。

注意对话列表允许用户销毁工作区。

6.7.5. 导航控件

导航控件在使用嵌套对话模式的应用程序中很有用。导航控件是当前对话堆栈中对话链接的一个列表。

<ui:repeat value="#{conversationStack}" var="entry">
    <h:outputText value=" | "/>
    <h:commandLink value="#{entry.description}" action="#{entry.select}"/>
</ui:repeat

对话组件有一个小小的限制：它们不能够被用来保存对JSF组件的绑定。 （除非绝对必要，否则我们通常不喜欢使用JSF的这个特性，因为它创建了从应用程序逻辑到视图的强依赖关系。） 在一个postback请求中，组件绑定会在视图恢复阶段中且在Seam对话上下文恢复之前被更新。

为了解决这个问题，使用一个事件范围的组件来保存组件绑定，并将它注入到需要它的对话范围组件中。

@Name("grid")
@Scope(ScopeType.EVENT)
public class Grid
{
    private HtmlPanelGrid htmlPanelGrid;

    // getters and setters
    ...
}

@Name("gridEditor")
@Scope(ScopeType.CONVERSATION)
public class GridEditor
{
    @In(required=false)
    private Grid grid;

    ...
}

另外一种选择是，你可以通过隐式的 uiComponent 句柄来访问JSF组件树。 下面这个例子访问在迭代中支持数据表的 UIData 组件的 getRowIndex() ，它打印当前的行数：

<h:dataTable id="lineItemTable" var="lineItem" value="#{orderHome.lineItems}">
   <h:column>
      Row: #{uiComponent['lineItemTable'].rowIndex}
   </h:column>
   ...
</h:dataTable>

在这个map中，可以得到JSF UI组件和它们的客户标识符。

在 ??? 中可以找到Seam组件并发调用的全部讨论。 在这里，我们要讨论是常见的一种并发情形，在这种情形下，你会遇到从AJAX请求中访问对话组件的并发—。 我们就要讨论一个Ajax客户端库应该提供用来控制源自客户端的事件的选项—，并看看RickFaces为你提供的选项。

对话组件实际上并不允许真正的并发访问，因此Seam会给每一个请求排一个队列并依次处理它们。这样允许每个请求都以一种特定的方式被执行。 但是，简单的队列不是那么强大—首先，由于某些原因，如果一个方法需要非常长的时间来完成，并且每次生成一个错误的请求时就一次又一次的反复运行（潜在拒绝服务攻击的可能）。 其次,AJAX经常被用于给用户提供快速的状态更新，因此持续地长时间运行该动作并没有什么用处。

因此Seam给action事件排队等待一段时间（并发的请求超时）； 如果不能及时处理事件，它就会创建一个临时的对话并且给用户打印一条信息，让他们了解情况。 所以不要给服务器发送泛滥的AJAX事件，这是非常重要的。

我们可以在components.xml文件中给并发的请求超时设置一个合理的超时默认值（ms）。

<core:manager concurrent-request-timeout="500" />

到目前为止，我们已经讨论了同步的AJAX请求—— 客户端告诉服务器发生了一个事件，然后根据返回值来重新渲染局部页面。 当AJAX请求是轻量级时，采用这种方法就相当好（这些方法的调用也简单，如：计算一列数字的总和）。 但是当我们需要做复杂的计算时我们应该怎么做呢？

对于大量的计算我们应当使用真正的异步（基于轮询“Poll”的）方法 — 客户端发送一个AJAX请求到服务器，这使得一个action在服务器端被异步地执行（因此立即就会响应客户端）；然后客户端会在服务器中查询更新。 当你运行一个长时间运行的操作时它很有用，因为每一个action都可以执行是非常重要的（你不会希望某些action由于重复或者超时而被丢弃）。

我们应如何来设计对话的AJAX应用程序呢？

首先，你需要决定是否想使用更简单的“同步”请方式，或者是否想要利用“Poll风格”的方法。

如果你要使用“同步”请求的方法，那么你需要评估一下你的AJAX请求需要多长时间才可以结束——它是不是比并发请求超时值要短？ 如果不是，你也许要修改这个方法的并发请求超时时间（如上所述）。 接下来你或许需要在客户端给请求排一个队，防止请求全部涌入服务器。 如果这是一个经常发生的事件（例如，按钮按下和输入域的onblur），并且立即更新客户端又不是优先需要考虑的情况，你就应该在客户端设置一个请求延时。 当消耗完你的请求延时的时候，该事件中的操作也会在服务器段排成一个队列。

最后，客户端库可能会提供一个选项，它可以放弃最近未完成的重复请求。 对这个选项你需要很谨慎，因为在服务端没能放弃未完成的请求时，这个选项可能导致请求全部涌入服务器端。

使用“Poll风格”的设计比较不需要细调。 你只要给你的action方法 @Asynchronous 进行标注，并确定一个查询时间间隔就可以了：

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;
}

在Seam中定义页面流有两种方法:

非常简单的应用程序只需要无状态的导航模型。非常复杂的应用程序则应该在不同的场合结合使用这两种模型。每种模型各有优缺点。

7.1.1. 两种导航模型

无状态的模型定义一种映射，把事件的一组命名的逻辑结果直接映射到视图的结果页面。导航规则除了记录哪个页面是事件来源之外不会保留任何状态。 这意味着Action监听方法有时必须进行一些页面流转的处理，因为只有它们能访问到应用程序的当前状态。

下面是一个使用JSF导航规则定义页面流的例子：

<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>

同一个例子，下面使用Seam导航规则定义:

<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>

如果你觉得导航规则过于繁琐，可以在Action监听方法里直接返回View的id。

public String guess() {
    if (guess==randomNumber) return "/win.jsp";
    if (++guessCount==maxGuesses) return "/lose.jsp";
    return null;
}

注意这会导致一个重定向，甚至可以指定要在重定向中使用的一些参数。

public String search() {
    return "/searchResults.jsp?searchPattern=#{searchAction.searchPattern}";
}

有状态模型在一组具名的、合乎逻辑的应用状态之间定义一组重定向。 在这种模型中，可以完全使用jPDL页面流定义来表示任意用户的交互流程，并在编写Action监听方法完全不必知道用户的交互流程。

下面是一个使用jPDL定义页面流的例子：

<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>

这里我们马上注意到了两件事：

• JSF/Seam导航规则 更加 简单。（然而，隐藏在后面的Java代码会相当复杂。）

• jPDL让用户交互的过程立刻变得直接易懂，我们甚至不需要考虑JSP或Java代码。

另外，有状态模型更加 受约束 。对于每一种逻辑状态（页面流中的每一步）而言，都存在一组受限的可能转到其他状态的重定向。 而无状态模型则是一种 实时的 模型，它适用于相对不受约束的、形式自由的导航，在这种情况下，由用户决定他／她下一步想重定向到哪里，而不是应用程序。

有状态和无状态导航之间的差别与传统的模态和非模态交互视图之间的差别很类似。 现在，Seam应用程序通常不是模态的，简单地说 －－ 的确，使用对话的一个主要原因就是避免应用程序中的模态行为！ 然而，在一个具体对话的级别里Seam应用程序可以是（甚至经常是）模态的。 众所周知，应该尽可能地避免模态行为；预知用户想要做事的顺序是非常困难的！然而，毫无疑问，有状态模型也是需要的。

这两种模型之间的最大不同是后退按钮行为。

<page view-id="/checkout.xhtml" 
        no-conversation-view-id="/main.xhtml"/>

<page name="checkout" 
        view-id="/checkout.xhtml" 
        back="enabled">
    <redirect/>
    <transition to="checkout"/>
    <transition name="complete" to="complete"/>
</page>

<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>

一个业务流程由一系列定义良好的任务组成，这些任务必须由用户或是软件系统遵照一系列定义良好的规则来完成，这些规则规定了 谁 可以执行任务，什么时候 应该执行。 Seam对jBPM的整合使得给用户显示任务列表以及使用户管理他们的任务变得简单。 Seam还使应用程序在 BUSINESS_PROCESS 的上下文中存储与业务流程相关的状态，通过jBPM变量来持久化这个状态。

一个简单的业务流程定义看起来跟页面流定义非常相似（是同一种类型的东西），不同的是用 <task-node> 节点替换了 <page> 节点。在一个长运行期的业务流程中，等待状态表示系统正在等待用户登录并执行任务。

<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>

我们很有可能在一个项目中同时使用jPDL业务流程定义和jPDL页面流程定义。 如果这样，他们二者的关系是：一个业务流程中的 <task> 对应一个完整的页面流 <pageflow-definition>。

Seam是从Hibernate团队试图生成典型的无状态Java应用架构的挫折中成长起来的。 上一代Java应用程序的无状态特性让Hibernate团队饱受挫折，Seam吸取了他们的经验。 Seam的状态管理架构最早是用来解决持久化冲突相关问题的，特别是 乐观事务处理 相关的问题。可扩展的在线应用经常使用乐观事务。 一个原子(database/JTA)级的事务不应该跨用户交互，除非系统设计时就是只支撑很少量的并发客户端。 但几乎所有涉及到的工作都是先将数据展现给用户，没多久后更新这个数据。所以Hibernate是依据支持一种跨乐观事务的持久化上下文的思想设计的。

不幸的是这个先于Seam和EJB3.0出现的所谓“无状态”架构并不对乐观事务进行支持。而相反，这些架构提供对于原子事务级的持久化上下文的支持。 这当然给用户带来了很多麻烦，这也是用户抱怨排名第一的Hibernate的 LazyInitializationException 问题的原因。 我们需要的是在应用层构建对于乐观事务的支持。

EJB3.0认识到了此问题，并且也引入了有状态组件（有状态会话bean）的思想，它使用一个 扩展持久化上下文来跟踪组件的生命周期。 这是该问题的部分解决方案（对它自身而言也是一个有用的构想），然而还有两个问题：

Seam通过提供对话(Conversation)和对话期间的有状态Session Bean组件来解决第一个问题（大多数会话实际上在数据层支持乐观事务）。 这对于很多不需要传递持久化上下文的简单应用（比如Seam的订阅演示程序）已经足够了。 对于更复杂的在每一个对话中的有很多松耦合组件的应用来说，组件间传播持久化上下文就成为一个重要的问题了。 所以Seam扩展了EJB 3.0的持久化上下文管理模型，以此来提供对话作用域的扩展持久化上下文。

EJB会话Bean有声明式事务管理功能。当Bean被调用时，EJB容器能够透明地开始一个事务，在调用结束时关闭此事务。 如果我们写了一个作为JSF动作监听器的会话Bean方法，我们就可以在一个事务内处理所有与此action相关的工作，并且当我们完成此动作处理时事务必须被提交或回滚。 这是一个很棒的功能，在很多Seam应用程序中这是必需的。

但是，此方法还是有问题。Seam应用可能无法在对会话Bean的一次方法调用请求中完成所有的数据访问。

每个请求的事务量越多，当我们的应用处理大量并发请求时越可能碰到原子和隔离问题。当然，所有的写操作要在一个事务中执行。

Hibernate用户开发了 "Open Session in View" 模式来解决该问题。 在Hibernate社区，"Open Session in View"曾经非常重要，这是因为像Spring这样的框架使用了事务作用域持久化上下文。 所以当未获得的关联被访问时渲染视图将引起 LazyInitializationException 异常。

这个模式通常作为一个跨越整个请求的事务来实现。 此实现方式会有几个问题，其中最严重的是只有我们提交了事务才能确认它成功完成——但在"Open Session in View"的事务提交时，视图已经完全渲染了，甚至渲染好的应答可能已经刷新到客户端。我们怎样才能通知用户他们的事务已失败呢？

Seam在解决"Open Session in View"问题时，也解决了事务隔离和关联获取问题。该方案有有两个部分：

下一节，我们将会告诉你如何安装一个会话作用域的持久化上下文。但首先我们需要你知道如何启用Seam事务管理。 注意你可以脱离Seam的事务管理来使用会话作用域持久化上下文。当你不使用Seam管理的持久化上下文时，你也有很多使用Seam事务管理的理由。 然而这两种功能被设计为一起使用的，一起使用时效果最好。

即使你使用EJB 3.0容器管理事务上下文，Seam事务管理也是很有用的。如果你在Java EE 5环境外使用Seam，或者在任何你想使用Seam管理的持久化上下文时，它同样很有用的。

<core:init transaction-management-enabled="false"/>

<transaction:no-transaction />

<transaction:entity-transaction entity-manager="#{entityManager}"/>

<transaction:hibernate-transaction session="#{hiberanteSession}"/>

<transaction:no-transaction />

如果你是在Java EE 5环境外使用Seam，你不能依靠容器来为你管理持久化上下文生命周期。 即使在Java EE 5 环境中，你可能有一个很多松耦合组件在会话作用域内相互协作的复杂应用，这种情况下你可能发现在组件间传递持久化上下文既困难又容易出错。

在任何一种情况下，你都需要在你的组件中使用一个 受管持久化上下文（在JPA中）或者一个 受管会话（Hibernate中）。一个Seam管理的持久化上下文是在会话上下文中管理一个 EntityManager 实例或者 Session 实例的内置Seam组件。你可以使用 @In 注入它。

Seam管理的持久化上下文在集群环境中尤其有效。EJB 3.0规范中不允许容器使用容器管理的扩展持久化上下文，Seam能够对此进行优化。 Seam支持扩展持久化上下文的透明故障恢复，而无需在节点间复制持久化上下文状态。（我们希望在EJB规范的下个版本中修复此漏洞。）

<persistence:managed-persistence-context name="bookingDatabase"
                                  auto-create="true"
                   persistence-unit-jndi-name="java:/EntityManagerFactories/bookingData"/>

<property name="jboss.entity.manager.factory.jndi.name"
          value="java:/EntityManagerFactories/bookingData"/>

@In EntityManager bookingDatabase;

<persistence:hibernate-session-factory name="hibernateSessionFactory"/>

<persistence:managed-hibernate-session name="bookingDatabase"
                                auto-create="true"
                  session-factory-jndi-name="java:/bookingSessionFactory"/>

<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>

@In Session bookingDatabase;

@In EntityManager em; //a Seam-managed persistence context

@Begin(flushMode=MANUAL)
public void beginClaimWizard() {
    claim = em.find(Claim.class, claimId);
}

public void addPartyToClaim() {
    Party party = ....;
    claim.addParty(party);
}

@End
public void commitClaim() {
    em.flush();
}

<begin-conversation flush-mode="MANUAL" />

EntityManager 接口能让你通过使用 getDelegate() 方法访问某个厂商特定的API。 很自然地，最让人感兴趣的厂商是Hibernate，其最强大的代理接口是 org.hibernate.Session。 你不必再用别的东西，相信我，我没有任何偏见。

不管你使用Hibernate（明智！）还是其他的东西（受虐狂，或者说不太聪明），你当然想在你的Seam组件中经常使用代理。下面是一个方法：

@In EntityManager entityManager;

@Create
public void init() {
    ( (Session) entityManager.getDelegate() ).enableFilter("currentVersions");
}

但类型转化毫无疑问是Java语言中最难看的语法。因此大家都应尽可能避免使用它们。这有另一个获得代理的方法。 首先将下列语句加到 components.xml 文件中：

<factory name="session"
         scope="STATELESS"
         auto-create="true"
         value="#{entityManager.delegate}"/>

现在我们可以直接注入此会话：

@In Session session;

@Create
public void init() {
    session.enableFilter("currentVersions");
}

无论你使用一个Seam管理的持久化上下文还是用 @PersistenceContext 注入一个容器管理的持久化上下文。 Seam都代理 EntityManager 或者 Session 对象，这使你能在查询语句中安全有效地使用EL表达式。例如这个例子：

User user = em.createQuery("from User where username=#{user.username}")
         .getSingleResult();

和下面等价：

User user = em.createQuery("from User where username=:username")
         .setParameter("username", user.getUsername())
         .getSingleResult();

当然你不要写成下面这样：

User user = em.createQuery("from User where username=" + user.getUsername()) //BAD!
         .getSingleResult();

（这在遭受SQL注入攻击时会变得低效且不堪一击。）

Hibernate最酷最独特的功能就是 过滤器（filter）。过滤器能让你提供一个数据库中数据的受限视图。 但是应该有一个将过滤器合并到Seam应用中的简便方法，让它和Seam应用框架能工作得很好。

Seam管理的持久化上下文可以定义一系列的过滤器，这些过滤器在一个 EntityManager 或者 Hibernate Session 被创建时启用。（当然，它们只能在Hibernate做持久化底层时使用）

<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">
    <core:filters>
        <value>#{regionFilter}</value>
        <value>#{currentFilter}</value>
    </core:filters>
</persistence:managed-persistence-context>

Groovy是一个基于Java虚拟机的敏捷动态语言，它融合了从Python，Ruby和Smalltalk等语言中的诸多特性。Groovy的强大体现在两个方面：

TODO: 再写一个Groovy语法的快速入门

这个没有什么可多说的，Groovy对象就是Java对象，你可以使用Groovy编写任何Seam组件或者Java类并部署它们。 你也可以在一个应用中混合使用Groovy和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})"
        }
    }

@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])
    }
}

部署Groovy类与部署Java类非常相像。（令人惊讶的是，不需要编写或者遵循某个3个字母的规范以支持多国语言组件框架）。

JBoss Seam拥有超越标准部署的能力，就是在开发时重新部署JavaBean Seam组件类而不必重启应用程序，这在开发／测试周期中节省了很多时间。 在 .groovy 文件被部署时，Seam对GroovyBean Seam 组件也提供了同样的热部署支持。

有两种不同的方法使用Seam Application Framework所提供的组件。第一种方法是像处理其他种类的Seam内置组件一样，在 components.xml 中安装和配置组件的实例。 举例来说，下列 components.xml 中的片段安装了一个能够为 Person 实体执行基本的CRUD（创建(Create)、读取(Retrieve) 、更新(Update)和删除(Delete)）操作的组件：

<framework:entity-home name="personHome"
                       entity-class="eg.Person"
                       entity-manager="#{personDatabase}">
    <framework:id>#{param.personId}</framework:id>
</framework:entity-home>

如果上面的代码按你的口味来说太像“用XML编程”，你可以改为使用扩展：

@Stateful
@Name("personHome")
public class PersonHome extends EntityHome<Person> implements LocalPersonHome {
    @RequestParameter String personId;
    @In EntityManager personDatabase;

    public Object getId() { return personId; }
    public EntityManager getEntityManager() { return personDatabase; }

}

第二种方法有一个很大的优点：你能够方便地添加额外的功能，覆盖内置的功能（框架的类都精心设计以便于扩展和定制）。

第二个优点是：如果你喜欢的话，你的类可以是有状态会话Bean（这不是必须的，也可以是普通的JavaBean组件，如果你喜欢的话）。如果你正在使用JBoss AS，你需要使用4.2.2.GA或更高的版本。

目前，Seam应用框架提供了四个内置的组件：用于CRUD操作的 EntityHome 和 HibernateEntityHome 以及用于查询的 EntityQuery 和 HibernateEntityQuery。

你得编写Home和Query组件，它们能在session、event或conversation作用范围中运行，至于选择哪个scope取决于你所希望在你的应用程序中使用的状态模型。

Seam应用框架仅在Seam管理的持久化上下文中工作。默认情况下，这些组件会寻找一个叫做 entityManager 的持久化上下文。

Home对象对特定的实体类提供持久化操作，假设我们有个可靠的 Person 类：

@Entity
public class Person {
    @Id private Long id;
    private String firstName;
    private String lastName;
    private Country nationality;

    //getters and setters...
}

我们可以通过配置定义一个 personHome 组件：

<framework:entity-home name="personHome" entity-class="eg.Person" />

也可以通过类的扩展

@Name("personHome")
public class PersonHome extends EntityHome<Person> {}

Home对象提供了如下的操作：persist()、remove()、update() 和 getInstance()。 在你能够调用 remove() 或 update() 操作之前，你必须首先使用 setId() 方法定义你感兴趣的对象的标识符。

我们可以直接从一个JSF页面使用一个Home，如下例：

<h1>Create Person</h1>
<h:form>
    <div>First name: <h:inputText value="#{personHome.instance.firstName}"/></div>
    <div>Last name: <h:inputText value="#{personHome.instance.lastName}"/></div>
    <div>
        <h:commandButton value="Create Person" action="#{personHome.persist}"/>
    </div>
</h:form>

通常，只用person 指明person漂亮得多，所以在 components.xml 中添加一行语句来实现。

<factory name="person"
         value="#{personHome.instance}"/>

<framework:entity-home name="personHome"
                       entity-class="eg.Person" />

（如果我们使用配置的方法。） 或者，我们可以通过向 PersonHome 中添加一个 @Factory 方法来实现：

@Name("personHome")
public class PersonHome extends EntityHome<Person> {

    @Factory("person")
    public Person initPerson() { return getInstance(); }

}

（如果我们使用类扩展的方法） 这个修改使我们的JSF页面简化如下：

<h1>Create Person</h1>
<h:form>
    <div>First name: <h:inputText value="#{person.firstName}"/></div>
    <div>Last name: <h:inputText value="#{person.lastName}"/></div>
    <div>
        <h:commandButton value="Create Person" action="#{personHome.persist}"/>
    </div>
</h:form>

好，这就可以用来创建新的 Person 实体了。是的，这就是所需的全部代码！现在，如果我们想显示，更新，删除数据库中已经存在的 Person 实体，我们需要将实体标识符传递给 PersonHome。页面参数是一种非常好的实现方式：

<pages>
    <page view-id="/editPerson.jsp">
        <param name="personId" value="#{personHome.id}"/>
    </page>
</pages>

现在，我们可以向JSF页面中增加其他的操作：

<h1>
    <h:outputText rendered="#{!personHome.managed}" value="Create Person"/>
    <h:outputText rendered="#{personHome.managed}" value="Edit Person"/>
</h1>
<h:form>
    <div>First name: <h:inputText value="#{person.firstName}"/></div>
    <div>Last name: <h:inputText value="#{person.lastName}"/></div>
    <div>
        <h:commandButton value="Create Person" action="#{personHome.persist}" rendered="#{!personHome.managed}"/>
        <h:commandButton value="Update Person" action="#{personHome.update}" rendered="#{personHome.managed}"/>
        <h:commandButton value="Delete Person" action="#{personHome.remove}" rendered="#{personHome.managed}"/>
    </div>
</h:form>

当我们没有带任何请求参数链接到该页面时，会显示"Create Person"页面，当我们为 personId 这个请求参数设定一个值时，会显示“Edit Person”页面。

假设我们需要创建一些 Person 实体，并且初始化这些人的国籍。我们可以通过配置很轻松地完成：

<factory name="person"
         value="#{personHome.instance}"/>

<framework:entity-home name="personHome"
                       entity-class="eg.Person"
                       new-instance="#{newPerson}"/>

<component name="newPerson"
           class="eg.Person">
    <property name="nationality">#{country}</property>
</component>

也可以通过扩展类

@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);
    }

}

当然，Country 是一个被其它的Home对象管理的对象，比如说，CountryHome。

为了增加更多复杂的操作（联合管理等等），我们可以向 PersonHome 中添加方法。

@Name("personHome")
public class PersonHome extends EntityHome<Person> {

    @In Country country;

    @Factory("person")
    public Person initPerson() { return getInstance(); }

    protected Person createInstance() {
        return new Person(country);
    }

    public void migrate()
    {
        getInstance().setCountry(country);
        update();
    }

}

当事务成功之后（调用 persist()、update() 或 remove() 成功后），Home对象会发出一个 org.jboss.seam.afterTransactionSuccess 事件。 通过监听这一事件，我们可以在底层实体改变后，刷新查询。 如果我们只需要在特定的实体保存、修改或删除后刷新特定查询，我们可以监视 org.jboss.seam.afterTransactionSuccess.<name> 事件（<name> 是实体的名字）。

当一个操作成功时，Home对象可以自动地显示Faces信息，我们可以再一次通过配置来定制信息。

<factory name="person"
         value="#{personHome.instance}"/>

<framework:entity-home name="personHome"
                       entity-class="eg.Person"
                       new-instance="#{newPerson}">
    <framework:created-message>New person #{person.firstName} #{person.lastName} created</framework:created-message>
    <framework:deleted-message>Person #{person.firstName} #{person.lastName} deleted</framework:deleted-message>
    <framework:updated-message>Person #{person.firstName} #{person.lastName} updated</framework:updated-message>
</framework:entity-home>

<component name="newPerson"
           class="eg.Person">
    <property name="nationality">#{country}</property>
</component>

或者扩展：

@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 "New person #{person.firstName} #{person.lastName} created"; }
    protected String getUpdatedMessage() { return "Person #{person.firstName} #{person.lastName} updated"; }
    protected String getDeletedMessage() { return "Person #{person.firstName} #{person.lastName} deleted"; }

}

但是指定信息最好的方法是把信息置于Seam所知的resource bundle中（在默认情况下，这个bundle叫做 messages ）。

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

这样方便进行国际化，从表现层的角度考虑也保持了代码和配置的整洁。

最后一步是使用 <s:validateAll> 和 <s:decorate> 向页面中添加验证功能，我会把这个留给你们自己去实现。

如果我们需要数据库中所有 Person 实例的列表，我们可以使用Query对象，例如：

<framework:entity-query name="people"
                        ejbql="select p from Person p"/>

我们可以从一个JSF页面中使用它：

<h1>List of people</h1>
<h:dataTable value="#{people.resultList}" var="person">
    <h:column>
        <s:link view="/editPerson.jsp" value="#{person.firstName} #{person.lastName}">
            <f:param name="personId" value="#{person.id}"/>
        </s:link>
    </h:column>
</h:dataTable>

我们可能需要支持分页：

<framework:entity-query name="people"
                        ejbql="select p from Person p"
                        order="lastName"
                        max-results="20"/>

我们可以使用page参数来决定被显示的页面

<pages>
    <page view-id="/searchPerson.jsp">
        <param name="firstResult" value="#{people.firstResult}"/>
    </page>
</pages>

用于分页的JSF代码可能有点冗长，但仍然是便于管理的：

<h1>Search for people</h1>
<h:dataTable value="#{people.resultList}" var="person">
    <h:column>
        <s:link view="/editPerson.jsp" value="#{person.firstName} #{person.lastName}">
            <f:param name="personId" value="#{person.id}"/>
        </s:link>
    </h:column>
</h:dataTable>

<s:link view="/search.xhtml" rendered="#{people.previousExists}" value="First Page">
    <f:param name="firstResult" value="0"/>
</s:link>

<s:link view="/search.xhtml" rendered="#{people.previousExists}" value="Previous Page">
    <f:param name="firstResult" value="#{people.previousFirstResult}"/>
</s:link>

<s:link view="/search.xhtml" rendered="#{people.nextExists}" value="Next Page">
    <f:param name="firstResult" value="#{people.nextFirstResult}"/>
</s:link>

<s:link view="/search.xhtml" rendered="#{people.nextExists}" value="Last Page">
    <f:param name="firstResult" value="#{people.lastFirstResult}"/>
</s:link>

真实的搜索界面能够通过让用户输入一系列的可选的搜索标准来缩小返回的结果列表。Query对象通过让你指定可选的“约束”来支持这个重要的用例。

<component name="examplePerson" class="Person"/>

<framework:entity-query name="people"
                        ejbql="select p from Person p"
                        order="lastName"
                        max-results="20">
    <framework:restrictions>
        <value>lower(firstName) like lower( concat(#{examplePerson.firstName},'%') )</value>
        <value>lower(lastName) like lower( concat(#{examplePerson.lastName},'%') )</value>
    </framework:restrictions>
</framework:entity-query>

注意“example”对象的使用。

<h1>Search for people</h1>
<h:form>
    <div>First name: <h:inputText value="#{examplePerson.firstName}"/></div>
    <div>Last name: <h:inputText value="#{examplePerson.lastName}"/></div>
    <div><h:commandButton value="Search" action="/search.jsp"/></div>
</h:form>

<h:dataTable value="#{people.resultList}" var="person">
    <h:column>
        <s:link view="/editPerson.jsp" value="#{person.firstName} #{person.lastName}">
            <f:param name="personId" value="#{person.id}"/>
        </s:link>
    </h:column>
</h:dataTable>

在底层实体发生改变后，可以通过监听 org.jboss.seam.afterTransactionSuccess 事件来刷新查询：

<event type="org.jboss.seam.afterTransactionSuccess">
    <action execute="#{people.refresh}" />
</event>

或者，在发生持久化、更新或者删除时，通过 PersonHome 来刷新查询：

<event type="org.jboss.seam.afterTransactionSuccess.Person">
    <action execute="#{people.refresh}" />
</event>

这个部分所有的例子都是通过配置来体现重用的，但是，对Query对象通过扩展来进行重用也是可行的。

Controller 类以及它的子类 EntityController，HibernateEntityController 和 BusinessProcessController 是Seam Application Framework的可选部分。 这些类只是提供了一些访问常用内置组件及这些组件方法的便利手段，它们能够减少一些键盘输入量，也为探索Seam内置丰富功能的初学者提供了一个非常好的跳板。

例如，这就是Seam注册实例中的 RegisterAction：

@Stateless
@Name("register")
public class RegisterAction extends EntityController implements Register
{

   @In private User user;

   public String register()
   {
      List existing = createQuery("select u.username from User u where u.username=:username")
         .setParameter("username", user.getUsername())
         .getResultList();

      if ( existing.size()==0 )
      {
         persist(user);
         info("Registered new user #{user.username}");
         return "/registered.jspx";
      }
      else
      {
         addFacesMessage("User #{user.username} already exists");
         return null;
      }
   }

}

正如你所看到的一样，这不是什么惊世骇俗的提高...

第一步是使一个 org.drools.RuleBase 的实例在Seam的上下文变量中可用。 基于测试目的，Seam提供了一个内置组件用来编译来自class搜索路径的一组静态规则。你可以通过 components.xml 文件安装此组件:

<drools:rule-base name="policyPricingRules">
    <drools:rule-files>
        <value>policyPricingRules</value>
    </drools:rule-files>
</drools:rule-base>

这个组件编译来自一组 .drl 文件中的规则并在Seam的 APPLICATION 上下文 中缓存一个 org.drools.RuleBase 实例。需要注意的是这和在规则驱动的应用程序中需要安装多个规则库很相似。

如果你想要使用Drools DSL，你还需要指定DSL定义：

<drools:rule-base name="policyPricingRules" dsl-file="policyPricing.dsl">
    <drools:rule-files>
        <value>policyPricingRules</value>
    </drools:rule-files>
</drools:rule-base>

在大多数规则驱动的应用程序中，规则需要是可被动态部署的，所以一个生产环境应用程序会需要用Drools规则代理来管理规则库。 规则代理可以连接一个Drools规则服务器（BRMS）或者热部署来自本地文件仓库的规则包。规则代理管理的规则库也在 components.xml 中配置:

<drools:rule-agent name="insuranceRules"
                    configurationFile="/WEB-INF/deployedrules.properties" />

属性文件包含有规则代理RulesAgent所特有的属性。这里是一个来自Drools范例发型中的配置文件例子。

newInstance=true
url=http://localhost:8080/drools-jbrms/org.drools.brms.JBRMS/package/org.acme.insurance/fmeyer
localCacheDir=/Users/fernandomeyer/projects/jbossrules/drools-examples/drools-examples-brms/cache
poll=30
name=insuranceconfig

绕过配置文件，直接配置组件的选项也是可行的。

<drools:rule-agent name="insuranceRules"
                   url="http://localhost:8080/drools-jbrms/org.drools.brms.JBRMS/package/org.acme.insurance/fmeyer"
                   local-cache-dir="/Users/fernandomeyer/projects/jbossrules/drools-examples/drools-examples-brms/cache"
                   poll="30"
                   configuration-name="insuranceconfig" />

接下来，我们需要使 org.drools.WorkingMemory 实例对每个对话都可用。 （每个 WorkingMemory 累积与当前对话相关的fact。）

<drools:managed-working-memory name="policyPricingWorkingMemory" auto-create="true" rule-base="#{policyPricingRules}"/>

请注意，我们通过 ruleBase 配置属性给了 policyPricingWorkingMemory 一个指回规则库的引用。

现在可以将我们的 WorkingMemory 注入进任意的Seam组件中了，进行判断并执行规则：

@In WorkingMemory policyPricingWorkingMemory;

@In Policy policy;
@In Customer customer;

public void pricePolicy() throws FactException
{
    policyPricingWorkingMemory.assertObject(policy);
    policyPricingWorkingMemory.assertObject(customer);
    policyPricingWorkingMemory.fireAllRules();
}

你甚至可以用一个规则库来充当jBPM动作处理器、决定处理器或者分配器—无论是在页面流或者业务流程定义中。

<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>

<assertObjects> 元素指定了用来返回要被作为fact设给 WorkingMemory 的对象或者对象集合的EL表达式。

除此之外，Seam还支持在jBPM任务分配中使用Drools：

<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>

这些对象作为Drools global提供给规则，即jBPM Assignable 对象（assignable）和Seam Decision对象（decision）。 处理决定的规则应该调用 decision.setOutcome("result") 来决定结果。执行分配的规则要调用 Assignable 设置参与者id。

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

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

每一个用户登录会话都有一个相关的 java.util.Locale 实例（以名为 locale 的组件形式提供给应用程序）。 一般情况下，不需要做任何特别的配置设置locale，Seam 委托JSF来判断当前的活动locale：

通过Seam的以下几个配置属性来手工设置locale也是你 可能的： org.jboss.seam.international.localeSelector.language、 org.jboss.seam.international.localeSelector.country和 org.jboss.seam.international.localeSelector.variant，但是并不推荐这种做法。

然而，允许用户通过应用程序的用户界面来手工设置locale也是很有益处的。Seam提供了内置的功能来覆盖通过上述算法决定的locale。你所要做的只是 在JSP或Facelet的Form中增加以下代码段：

<h:selectOneMenu value="#{localeSelector.language}">
    <f:selectItem itemLabel="English" itemValue="en"/>
    <f:selectItem itemLabel="Deutsch" itemValue="de"/>
    <f:selectItem itemLabel="Francais" itemValue="fr"/>
</h:selectOneMenu>
<h:commandButton action="#{localeSelector.select}" value="#{messages['ChangeLanguage']}"/>

或者，如果你想要一个 faces-config.xml 支持的所有locale的列表，就用：

<h:selectOneMenu value="#{localeSelector.localeString}">
    <f:selectItems value="#{localeSelector.supportedLocales}"/>
</h:selectOneMenu>
<h:commandButton action="#{localeSelector.select}" value="#{messages['ChangeLanguage']}"/>

当在下拉列表中选择一项，并按下按钮后，随后会话中Seam和JSF的locale就被刷新了。

JSF 通过使用 <f:loadBundle /> 来支持用户界面标签和描述文本的国际化。这个方法同样可以用在Seam应用程序中。 或者，可以利用Seam的 messages 组件用内嵌的EL表达式来显示模板标签。

Hello=Hello

Hello=G'day

<core:resource-loader>
    <core:bundle-names>
        <value>mycompany_messages</value>
        <value>standard_messages</value>       
    </core:bundle-names>
</core:resource-loader>

<page view-id="/welcome/hello.jsp" bundle="HelloMessages"/>

<h:outputText value="#{messages['Hello']}"/>

<h:outputText value="#{messages.Hello}"/>

Hello=Hello, #{user.firstName} #{user.lastName}

Hello=G'day, #{user.firstName}

@In private Map<String, String> messages;

@In("#{messages['Hello']}") private String helloMessage;

@Name("hello")
@Stateless
public class HelloBean implements Hello {
    @In FacesMessages facesMessages;
    
    public String sayIt() {
        facesMessages.addFromResourceBundle("Hello");
    }
}

Seam中还有一个session范围的 java.util.Timezone 实例，叫做 org.jboss.seam.international.timezone， 和一个名为 org.jboss.seam.international.timezoneSelector 的用于设置时区的组件。默认情况下，时区取服务器的默认时区。 不幸的是，JSF规范中讲所有的日期和时间都假设是UTC 的，并且显示为UTC，除非使用 <f:convertDateTime> 明确地为其指定时区。 这是一个非常不方便的默认行为。

Seam覆写了这个行为，默认所有的日期和时间都是Seam的时区。另外，Seam提供了 <s:convertDateTime> 标签，用来处理Seam 时区的转化。

Seam应用程序可以很方便地改变皮肤。Theme API和本地化API非常相似，但是它们二者的关注点截然不同，一些应用同时支持本地化和主题。

首先，配置所支持的主题集合：

<theme:theme-selector cookie-enabled="true">
    <theme:available-themes>
        <value>default</value>
        <value>accessible</value>
        <value>printable</value>
    </theme:available-themes>
</theme:theme-selector>

注意，第一个是默认的主题。

主题定义在一个和该主题同名的属性文件中。例如，default 主题定义在default.properties中。 default.properties可能是这样定义的：

css ../screen.css
template /template.xhtml

通常主题资源包的内容是CSS样式或图片的路径和facelet模板（不像本地化资源包那样通常是文本）。

现在我们可以在JSP或者Facelet页面中使用这些内容了。例如，一个Facelet页的风格可以这样：

<link href="#{theme.css}" rel="stylesheet" type="text/css" />

或者，当页面定义在一个子目录中时可以这样：

<link href="#{facesContext.externalContext.requestContextPath}#{theme.css}" 
    rel="stylesheet" type="text/css" />

最强大的是，Facelet让我们通过 <ui:composition> 把模板主题化:

<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}">

正如locale选择器一样，有一个内置的主题选择器允许用户在各主题间自由地切换：

<h:selectOneMenu value="#{themeSelector.theme}">
    <f:selectItems value="#{themeSelector.themes}"/>
</h:selectOneMenu>
<h:commandButton action="#{themeSelector.select}" value="Select Theme"/>

locale选择器、主题选择器和时区选择器全都支持持久化，把参数保存到cookie中。仅需要在components.xml中设置 cookie-enabled 配置属性：

<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"/>

下面是个简单的例子：

It's easy to make *bold text*, /italic text/, |monospace|,
~deleted text~, super^scripts^ or _underlines_.

如果我们用 <s:formattedText/> 来显示它，会产生下面的HTML：

<p>
It's easy to make <b>bold text</b>, <i>italic text</i>, <tt>monospace</tt>
<del>deleted text</del>, super<sup>scripts</sup> or <u>underlines</u>.
</p>

可以用一个空行来表示新的段落，用 + 来表示一个标题：

+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.

（请注意简单的换行是被忽略的，你需要一个额外的空行把文本换行到一个新的段落中。）下面就是HTML的结果：

<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>

用 # 字符来建立有序的列表。至于无序的列表就用 = 字符：

An ordered list:

#first item
#second item
#and even the /third/ item

An unordered list:

=an item
=another item

<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>

引用的部分应该用双引号括起来：

The other guy said:

"Nyeah nyeah-nee
/nyeah/ nyeah!"

But what do you think he means by "nyeah-nee"?

<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>

像 *、| 和 # 这样的特殊字符， 和诸如 <、> 和 & 之类的HTML字符可以用来 \ 来转义：

You can write down equations like 2\*3\=6 and HTML tags
like \<body\> using the escape character: \\.

<p>
You can write down equations like 2*3=6 and HTML tags
like &lt;body&gt; using the escape character: \.
</p>

代码段可以用倒单引号（`）括起来：

My code doesn't work:

`for (int i=0; i<100; i--)
{
    doSomething();
}`

Any ideas?

<p>
My code doesn't work:
</p>

<pre>for (int i=0; i&lt;100; i--)
{
    doSomething();
}</pre>

<p>
Any ideas?
</p>

请注意行间的空格会转码（大部分的空格都会被格式化成文本形式，实际上有很多的特定字符都是代码或者标签）。因此你可以写成：

This is a |<tag attribute="value"/>| example.

在这里面的空格没有转换成任何的字符。下面你不能通过任何方式来格式化行间的空格文本（斜体字，下划线等等）。

可以用下面的语法来建立一个链接：

Go to the Seam website at [=>http://jboss.com/products/seam].

如果你想指定链接的文本，也可以这样：

Go to [the Seam website=>http://jboss.com/products/seam].

对于高级用户，甚至可以自定义Seam Text解析器，让它诠释这个语法书写的Wiki词汇。

文本可能会包含一个HTML的有限子集（不用担心，这个子集可以抵御跨站脚本攻击）。这在建立链接时很有用：

You might want to link to <a href="http://jboss.com/products/seam">something
cool</a>, or even include an image: <img src="/logo.jpg"/>

建立表格时也一样：

<table>
    <tr><td>First name:</td><td>Gavin</td></tr>
    <tr><td>Last name:</td><td>King</td></tr>
</table>

如果你想的话你还能做得更多！

iText支持由 jboss-seam-pdf.jar 提供。 这个JAR包中含有用来构造可以渲染成PDF的视图的iText JSF控件和把把渲染好的文档提供给用户的DocumentStore组件。 为了在你的应用程序中包括PDF支持，要把 jboss-seam-pdf.jar 和iText JAR 文件一起放在你的 WEB-INF/lib 路径下。 要使用Seam的iText支持就只是这样，无需更多的配置了。

Seam iText模块需要使用Facelets作为视图技术。这个库的未来版本也可能支持使用JSP。此外，这个模块还需要用到seam-ui包。

工程 examples/itext 包含了一个PDF支持实践的例子。 这个例子示范了正确的部署包，它包含一些例子，用来示范目前支持PDF生成的关键特性。

<p:document xmlns:p="http://jboss.com/products/seam/pdf">
  The document goes here.文档指向这里。
</p:document>

<p:paragraph alignment="justify">
    This is a simple document.  It isn't very fancy. 这是一个简单的文档，它不是很常用。
</p:paragraph>

<p:paragraph>
    The item costs 显示一件商品的价格<p:text value="#{product.price}">
        <f:convertNumber type="currency" currencySymbol="$"/>
    </p:text>
</p:paragraph>

<p:font family="courier" style="bold" size="24">
    <p:paragraph>My Title</p:paragraph>
</p:font>

<p:newPage />

<p:image value="/jboss.jpg" />

<p:image value="#{images.chart}" />

<p:listItem><p:anchor reference="#reason1">Reason 1</p:anchor></p:listItem>
...
<p:paragraph>
    <p:anchor name="reason1">It's the quickest way to get "rich"</p:anchor>
    ...
</p:paragraph>

<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>

<p:footer borderWidthTop="1" borderColorTop="blue"
          borderWidthBottom="0" alignment="center">
    Why Seam? [<p:pageNumber />]
</p:footer>

<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> 

<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>

<p:list style="numbered">
  <ui:repeat value="#{documents}" var="doc">
    <p:listItem>#{doc.name}</p:listItem>
  </ui:repeat>
</p:list>

...

<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>