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

Seam上下文是由框架创建和销毁的。应用程序不能通过显式的Java API调用来控制上下文划分。上下文通常是隐含的。然而，在某些情况下，上下文可以通过annotation（注解）划分。

基本的Seam上下文有:

你可能在servlet及相关规范中已经见过其中一些上下文了，但其中有两个可能从未见过：conversation context（业务对话上下文），和 business process context（业务流程上下文）。 在Web应用程序中，状态管理如此凌乱和容易出错的原因就是，内置的三个上下文（request, session 和application）从业务逻辑的角度来看不是很有意义。 例如，用户登录session的构建，对应用实际的工作流程来说就是相当随意的。 因此，大部分的Seam组件被限定在业务会话或者业务流程上下文中，因为这些上下文从应用的角度来说最有意义。

让我们按顺序来考察每个context（上下文）。

User user = (User) Contexts.getSessionContext().get("user");

Contexts.getSessionContext().set("user", user);

Seam组件是POJO（Plain Old Java Objects）。特别地，他们是JavaBean或者EJB 3.0 enterprise bean。Seam并不强求组件是EJB，甚至可以不使用EJB 3.0兼容的容器，Seam在设计的时候处处考虑对EJB 3.0的支持，并且包含对EJB 3.0的深度整合。

@Stateless
@Interceptors(SeamInterceptor.class)
public class LoginAction implements Login {
    ...
}

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

@Name("loginAction")
@Stateless
public class LoginAction implements Login {
    ...
}

@Name("com.jboss.myapp.loginAction")
@Stateless
@Interceptors(SeamInterceptor.class)
public class LoginAction implements Login {
    ...
}

<h:commandButton type="submit" value="Login"
                 action="#{com.jboss.myapp.loginAction.login}"/>

<factory name="loginAction" scope="STATELESS" value="#{com.jboss.myapp.loginAction}"/>

@Name("user")
@Entity
@Scope(SESSION)
public class User {
    ...
}

@Name("user")
@Entity
@Scope(CONVERSATION)
@Role(name="currentUser", scope=SESSION)
public class User {
    ...
}

@Name("user")
@Entity
@Scope(CONVERSATION)
@Roles({@Role(name="currentUser", scope=SESSION),
        @Role(name="tempUser", scope=EVENT)})
public class User {
    ...
}

FacesMessages.instance().add("Welcome back, #{user.name}!");

Dependency injection（依赖注入） 和 inversion of control（控制反转） 现在对大多数Java 开发者来说都是熟悉的概念了。依赖注入允许一个组件通过容器“注入”另一个组件到一个setter方法或者实例变量的方式，来获得被“注入”组件的引用(reference)。我们之前看过的所有依赖注入的实现，注入发生在组件创建的时候，在此后实例的整个生命周期中不再改变。对无状态组件，这么做是有道理的。从客户端的角度来看，特定种类的无状态组件的所有实例都是可以替换的。另一方面，Seam着重处理有状态组件。此时传统的依赖注入不再是非常有效了。Seam引入了 bijection（双向注入） 这个名词，用来作为注入的广义概括。和injection（单向注入）对比，bijection是：

基本上，通过设置实例变量是需要注入、反向注入、还是二者皆是，双向注入让你将上下文变量映射到组件实例变量。当然，我们使用注解来设置双向注入。

@In 注解指明应该注入值，可能是注入实例变量：

@Name("loginAction")
@Stateless
public class LoginAction implements Login {
    @In User user;
    ...
}

或者注入setter方法：

@Name("loginAction")
@Stateless
public class LoginAction implements Login {
    User user;

    @In
    public void setUser(User user) {
        this.user=user;
    }

    ...
}

默认情况下，针对被注入的属性或者实例变量名， Seam会对所有的上下文进行优先级搜索。 如果你希望明确指定上下文变量名，可以这样写：@In("currentUser")。

如果没有组件实例绑定到具名的上下文变量，你可能希望Seam创建一个，你可以指定 @In(create=true)。 如果值是可选的（可以为null），请指定 @In(required=false)。

对于某些组件，到处指定 @In(create=true) 是很繁琐的。 你可以注解整个组件为 @AutoCreate，它就会在任何需要的时候自动创建，不需要明确的指定 create=true。

你还可以注入表达式的值：

@Name("loginAction")
@Stateless
public class LoginAction implements Login {
    @In("#{user.username}") String username;
    ...
}

（在下一章，有更多的关于组件生命周期和注射的内容。）

@Out 注解指定了某个属性需要对外注入，可能是从实例变量：

@Name("loginAction")
@Stateless
public class LoginAction implements Login {
    @Out User user;
    ...
}

或者从某个getter方法：

@Name("loginAction")
@Stateless
@Interceptors(SeamInterceptor.class)
public class LoginAction implements Login {
    User user;

    @Out
    public User getUser() {
        return user;
    }

    ...
}

属性可以既是被注入的，也可以对外注入：

@Name("loginAction")
@Stateless
public class LoginAction implements Login {
    @In @Out User user;
    ...
}

或者：

@Name("loginAction")
@Stateless
public class LoginAction implements Login {
    User user;

    @In
    public void setUser(User user) {
        this.user=user;
    }

    @Out
    public User getUser() {
        return user;
    }

    ...
}

Session Bean和实体Bean Seam组件支持所有通用的EJB3.0生命周期回调（@PostConstruct, @PreDestroy, 等等）。但是Seam也同样支持JavaBean组件使用任意的这些回调。然而，一但这些注解在J2EE环境中失效，Seam定义了两个附加组件完成生命周期回调，这等同于 @PostConstruct 和 @PreDestroy.

@Create 方法在Seam实例化一个组件后被调用。组件只可以定义一个 @Create 方法。

@Destroy 方法在Seam组件被绑定的上下文结束时被调用。组件只可以定义一个 @Destroy 方法。

另外，有状态Session Bean组件 必须 定义一个无参并注解为 @Remove 的方法。这个方法在上下文结束时被Seam调用。

最后，相关的注解还有 @Startup，它可以用在任何Application或者Session范围的组件上。 @Startup 注解告诉Seam在上下文开始的时候立刻初始化组件，而不是在被客户访问的时候才创建。 控制startup组件的初始化顺序通过指定 @Startup(depends={....}) 进行。

@Install 注解让你控制组件的条件装载，允许随着不同的部署情形而改变。例如：

@Install 通过让你指定 precedence（优先级） 和 dependencies（依赖） 来运作。

组件的优先级是一个数字，当在classpath中存在多个同组件名的类的时候，seam依靠它来决定安装哪个组件。 Seam会选取优先级数字最大的。有一些预定义的优先级值：（按升序排列）：

假设我们有一个组件，名为 messageSender ，和一个JMS队列交互。

@Name("messageSender")
public class MessageSender {
    public void sendMessage() {
        //do something with JMS
    }
}

在我们的单元测试中，我们并没有JMS队列可用，因此我们需要stub这个方法。我们会创建一个 mock 组件，在单元测试运行时放在classpath中，但绝不会在部署应用程序时出现。

@Name("messageSender")
@Install(precedence=MOCK)
public class MockMessageSender extends MessageSender {
    public void sendMessage() {
        //do nothing!
    }
}

当seam在classpath中发现多个组件时，precedence 帮助Seam决定使用哪个版本。

如果我们能精确控制使用 classpath中存在的类，是很美妙的。 但是如果我在编写一个可重用的框架，具有很多依赖条件，我不希望用那么多的jar来肢解框架。 我希望通过已经安装了哪些了组件，以及classpath中存在哪些组件，来决定安装组件。 @Install 注解也控制这一功能。Seam内部使用这一机制来控制很多内部组件的条件安装。虽然你可能不会在你的程序中使用它。

面对下面的代码，谁都会被搞得七窍生烟：

private static final Log log = LogFactory.getLog(CreateOrderAction.class);

public Order createOrder(User user, Product product, int quantity) {
    if ( log.isDebugEnabled() ) {
        log.debug("Creating new order for user: " + user.username() +
            " product: " + product.name()
            + " quantity: " + quantity);
    }
    return new Order(user, product, quantity);
}

难以想象为何简单的log信息会被搞得如此之复杂。用于log的代码函数比用于实际业务逻辑的还要多！很惊讶,Java社区10年内都没有对此加以改变。

Seam提供了可以显著简化上述代码的logging API：

@Logger private Log log;

public Order createOrder(User user, Product product, int quantity) {
    log.debug("Creating new order for user: #0 product: #1 quantity: #2", user.username(), product.name(), quantity);
    return new Order(user, product, quantity);
}

是否把 log 变量声明为static并不重要，它都可以工作，除非是Entity Bean组件，需要把 log 声明为静态的。

注意你并不需要繁杂的 if ( log.isDebugEnabled() ) 保卫语句，因为字符串相加操作是在 debug() 方法 内部 发生的。也请注意通常不需要显式指定log类型，因为Seam知道哪个组件正在注入 Log。

假设 User 和 Product 是当前上下文中可用的Seam组件，写起来更加简便：

@Logger private Log log;

public Order createOrder(User user, Product product, int quantity) {
    log.debug("Creating new order for user: #{user.username} product: #{product.name} quantity: #0", quantity);
    return new Order(user, product, quantity);
}

Seam loging自动选择发送结果到log4j或者JDK logging。如果log4j在classpath中，Seam会使用它，否则，Seam会使用JDK logging.

很多应用服务器的 HttpSession 集群实现都有问题，对绑定到Session的可变对象状态的改变只有在明确调用 setAttribute() 的时候才会被复制。 这是Bug的一个源头，这些Bug难以在开发阶段有效找出，因为它们只会在应用服务器失效切换的时候才会被发现。 而且，实际的复制信息包含了绑定到Session的所有序列化对象图，这是低效的。

当然，EJB 有状态Session Bean必须进行自动dirty checking，并进行可变状态的复制，并且EJB 容器也应该引入优化，例如属性级别的复制。 但不幸的是，并非所有的Seam用户都有这么好的运气，他们的环境可能并不支持EJB 3.0。 因此，对于Session和Conversation范围内的JavaBean和Entity Bean组件，在Web容器的Session集群之上，Seam提供了额外的集群安全的状态管理层。

对于Session或Conversation范围的JavaBean组件，每次组件被引用程序调用的时候，Seam自动通过调用一次 setAttribute() 来触发复制。当然，对大部分是读操作的组件来说，这效率不高。你可以通过实现 org.jboss.seam.core.Mutable 接口来控制这一行为。或者扩展 org.jboss.seam.core.AbstractMutable，在组件内实现自己的dirty-checking逻辑。例如，

@Name("account")
public class Account extends AbstractMutable
{
    private BigDecimal balance;

    public void setBalance(BigDecimal balance)
    {
        setDirty(this.balance, balance);
        this.balance = balance;
    }

    public BigDecimal getBalance()
    {
        return balance;
    }

    ...

}

或者，你可以使用 @ReadOnly 注解来达到类似的效果：

@Name("account")
public class Account
{
    private BigDecimal balance;

    public void setBalance(BigDecimal balance)
    {
        this.balance = balance;
    }

    @ReadOnly
    public BigDecimal getBalance()
    {
        return balance;
    }

    ...

}

对Session或Conversation范围的Entity Bean组件，在每次被请求的时候Seam自动通过一次 setAttribute() 调用来触发复制，除非（对话范围的）实体和一个Seam管理的持久化上下文相关联，此时无需复制。这一策略不是最高效的，因此Session或Conversation范围的Entity Bean应该小心使用。你总是可以编写有状态的Session Bean或者JavaBean组件来“管理”Entity Bean实例。例如，

@Stateful
@Name("account")
public class AccountManager extends AbstractMutable
{
    private Account account; // an entity bean

    @Unwrap
    public void getAccount()
    {
        return account;
    }

    ...

}

注意,对于 EntityHome 类，Seam应用框架提供了一个非常好的例子来说明如何使用Seam组件来管理实体Bean的实例.

我们经常需要与非Seam组件的对象打交道。但是我们仍然希望把它们通过 @In 注入我们的组件，并在值和方法表达式中使用它们。 有时候，我们甚至需要把它们绑定到Seam 上下文的生命周期里（例如@Destroy）。 所以Seam上下文可以容纳非Seam组件的对象，并且Seam提供了一些很好的特性，这些特性使得我们与绑定到上下文里的非组件对象打交道更加容易。

factory component pattern（工厂组件模式）让Seam组件作为非组件对象的构造器。 当上下文变量被引用，但是没有值被绑定到它时，会调用一个factory method（工厂方法）。 我们通过@Factory注解来定义工厂方法。 工厂方法把一个值绑定到上述上下文变量，并且决定被绑定的值的范围。有两种工厂方法。第一种返回一个值，Seam会把它绑定到上下文里：

@Factory(scope=CONVERSATION)
public List<Customer> getCustomerList() {
    return ... ;
} 

第二种方法返回 void，它自己把值绑定到上下文变量：

@DataModel List<Customer> customerList;

@Factory("customerList")
public void initCustomerList() {
    customerList = ...  ;
} 

两种情况下，当我们引用 customerList 上下文变量，而其值为null时，工厂方法被调用，然后对这个值生命周期的其他部分就无法操纵了。 更加强大的模式是 manager component pattern（管理者组件模式）。 在这种情况下，有一个Seam组件绑定到上下文变量，它管理着上下文变量的值，对客户端不可见。

管理者组件可以是任何组件，它需要一个 @Unwrap 方法。 该方法返回对客户端可见的值，每次 上下文变量被引用的时候都会被调用。

@Name("customerList")
@Scope(CONVERSATION)
public class CustomerListManager
{
    ...

    @Unwrap
    public List<Customer> getCustomerList() {
        return ... ;
    }
}

当你有一个对象并需要对其组件的生命周期更多的控制时，管理组件模式就显得尤其有用。 例如，如果你有一个重量级的对象，当上下文结束时你想对其进行清除操作，你可以@Unwrap对象，并在管理组件的 @Destroy 方法中执行清除操作。

@Name("hens")
@Scope(APPLICATION)
public class HenHouse {

    Set<Hen> hens;

    @In(required=false) Hen hen;

    @Unwrap
    public List<Hen> getHens() {
        if (hens == null) {
            // Setup our hens
        }
        return hens;
    }

    @Observer({"chickBorn", "chickenBoughtAtMarket"})
    public addHen() {
        hens.add(hen);
    }

    @Observer("chickenSoldAtMarket")
    public removeHen() {
        hens.remove(hen);
    }

    @Observer("foxGetsIn")
    public removeAllHens() {
        hens.clear();
    }
    ...
} 

这里，被管理的组件观察那些改变在下面的对象的事件。组件自己管理这些动作，并且由于对象在每一次访问中都被解开，所以这里提供了一个统一的视图。

Seam组件的配置属性可以通过两种方式得到：通过servlet context参数，或者通过位于classpath下的 seam.properties 属性文件进行。

可配置的Seam组件必须为可配置的属性暴露JavaBean风格的属性setter方法。例如，一个名为 com.jboss.myapp.settings 的Seam组件拥有一个名为 setLocale() 的setter方法，我们就可以在 seam.properties 文件中提供一个名为 com.jboss.myapp.settings.locale 的属性，或者作为一个servlet context参数， 这样，一旦该组件被实例化，Seam将自动为这个名为 locale 的属性注入相应的值。

Seam本身的配置也采用了相同的机制。例如，要设置对话超时，我们可以在 web.xml 或者 seam.properties 中为 org.jboss.seam.core.manager.conversationTimeout 提供一个值。 （在Seam内置的组件 org.jboss.seam.core.manager 中，已经包含了一个名为 setConversationTimeout() 的setter方法。）

components.xml 文件的功能要比属性设置的更强大一些。它让你：

components.xml 文件可以出现在下面三个不同地方中的任何一处：

通常情况下，当Seam部署扫描器在包含 seam.properties 文件或者 META-INF/components.xml 文件的文件夹中识别到一个包含 @Name 注解的类时， Seam将安装载该组件。（除非这个组件具有一个 @Install 注解，表示它不应该被默认安装。） components.xml 文件让我们去处理那些需要覆盖注解的特殊情况。

例如，下面的 components.xml 文件安装了jBPM:

<components xmlns="http://jboss.com/products/seam/components"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xmlns:bpm="http://jboss.com/products/seam/bpm">
    <bpm:jbpm/>
</components>

这个例子实现了相同的功能：

<components>
    <component class="org.jboss.seam.bpm.Jbpm"/>
</components>

这个例子安装并配置了Seam管理的两个不同的持久化上下文:

<components xmlns="http://jboss.com/products/seam/components"
            xmlns:persistence="http://jboss.com/products/seam/persistence"

    <persistence:managed-persistence-context name="customerDatabase"
                       persistence-unit-jndi-name="java:/customerEntityManagerFactory"/>

    <persistence:managed-persistence-context name="accountingDatabase"
                       persistence-unit-jndi-name="java:/accountingEntityManagerFactory"/>

</components>

这个例子也一样:

<components>
    <component name="customerDatabase"
              class="org.jboss.seam.persistence.ManagedPersistenceContext">
        <property name="persistenceUnitJndiName">java:/customerEntityManagerFactory</property>
    </component>

    <component name="accountingDatabase"
              class="org.jboss.seam.persistence.ManagedPersistenceContext">
        <property name="persistenceUnitJndiName">java:/accountingEntityManagerFactory</property>
    </component>
</components>

这个例子创建了一个Seam管理的session范围持久化上下文（这在实际项目中并不推荐使用）

<components xmlns="http://jboss.com/products/seam/components"
            xmlns:persistence="http://jboss.com/products/seam/persistence"

  <persistence:managed-persistence-context name="productDatabase"
                                          scope="session"
                     persistence-unit-jndi-name="java:/productEntityManagerFactory"/>

</components>

<components>

    <component name="productDatabase"
              scope="session"
              class="org.jboss.seam.persistence.ManagedPersistenceContext">
        <property name="persistenceUnitJndiName">java:/productEntityManagerFactory</property>
    </component>

</components>

通常会给像持久化上下文这样的基础结构对象使用 auto-create 选项， 它能在你使用 @In 注解时，不必显式地指定 create=true。

<components xmlns="http://jboss.com/products/seam/components"
            xmlns:persistence="http://jboss.com/products/seam/persistence"

  <persistence:managed-persistence-context name="productDatabase"
                                    auto-create="true"
                     persistence-unit-jndi-name="java:/productEntityManagerFactory"/>

</components>

<components>

    <component name="productDatabase"
        auto-create="true"
              class="org.jboss.seam.persistence.ManagedPersistenceContext">
        <property name="persistenceUnitJndiName">java:/productEntityManagerFactory</property>
    </component>

</components>

<factory> 声明让你指定一个值或者方法来绑定一个表达式，当它第一次被引用时，将被执行用来初始化一个context变量的值。

<components>

    <factory name="contact" method="#{contactManager.loadContact}" scope="CONVERSATION"/>

</components>

你也可以为Seam组件创建一个别名（第二个名字），就像这样：

<components>

    <factory name="user" value="#{actor}" scope="STATELESS"/>

</components>

你甚至可以给常用的表达式定义别名：

<components>

    <factory name="contact" value="#{contactManager.contact}" scope="STATELESS"/>

</components>

auto-create="true" 用在 <factory> 声明中尤其常见。

<components>

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

</components>

我们在部署或者测试期间，有时候想要通过略微的改动，来重用同一个 components.xml文件。 Seam允许你在 components.xml 文件中使用 @wildcard@ 形式的通配符， 这些通配符可以在部署的时候被Ant构建脚本替换，也可以在开发时通过在classpath中提供一个名为 components.properties 的文件进行替换。 你会在Seam的示例程序中找到这个用法。

如果你有大量的组件需要在XML中进行配置，那么就很有必要将 components.xml 文件中的内容分散到多个文件中去。 Seam允许你把类（例如名为 com.helloworld.Hello ）的配置放到一个资源中（名为 com/helloworld/Hello.component.xml）。 （你对这种模式可能很熟悉，因为它与我们在Hibernate中使用的相同）。 文件的根元素应该是 <components> 或者 <component> 。

第一个选项允许你在一个文件中定义多个组件：

<components>
    <component class="com.helloworld.Hello" name="hello">
        <property name="name">#{user.name}</property>
    </component>
    <factory name="message" value="#{hello.message}"/>
</components>

第二个选项只允许你定义或者配置单个组件，不过麻烦会少一点：

<component name="hello">
    <property name="name">#{user.name}</property>
</component>

在第二个选项中，类名与组件定义所在的文件是一致的。

你还可以选择将所有类的配置都放在 com/helloworld/components.xml 的 com.helloworld 包中。

String的属性、基本类型以及基本类型的包装类型可以像我们期望的那样进行配置：

org.jboss.seam.core.manager.conversationTimeout 60000

<core:manager conversation-timeout="60000"/>

<component name="org.jboss.seam.core.manager">
    <property name="conversationTimeout">60000</property>
</component>

也支持由String或者基本类型构成的数组、Set和List：

org.jboss.seam.bpm.jbpm.processDefinitions order.jpdl.xml, return.jpdl.xml, inventory.jpdl.xml

<bpm:jbpm>
    <bpm:process-definitions>
        <value>order.jpdl.xml</value>
        <value>return.jpdl.xml</value>
        <value>inventory.jpdl.xml</value>
    </bpm:process-definitions>
</bpm:jbpm>

<component name="org.jboss.seam.bpm.jbpm">
    <property name="processDefinitions">
        <value>order.jpdl.xml</value>
        <value>return.jpdl.xml</value>
        <value>inventory.jpdl.xml</value>
    </property>
</component>

甚至也支持那些包含String值为键、String或者基本类型值的Map：

<component name="issueEditor">
    <property name="issueStatuses">
        <key>open</key> <value>open issue</value>
        <key>resolved</key> <value>issue resolved by developer</value>
        <key>closed</key> <value>resolution accepted by user</value>
    </property>
</component>

最后，你可以利用值绑定表达式来将所有的组件装配起来。 注意这与使用 @In 注解进行注入非常不同，因为它是在组件初始化而不是被调用时起作用的。 因而它与传统的IoC容器例如JSF或者Spring所提供的依赖注入功能非常非常类似。

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

<component name="policyPricingWorkingMemory"
          class="org.jboss.seam.drools.ManagedWorkingMemory">
    <property name="ruleBase">#{policyPricingRules}</property>
</component>

纵观整个示例，有两种完全不同的声明组件的方式：使用或者不使用XML命名空间。 下面的示例展示了一个典型的 components.xml 文件，它没有使用命名空间，而是使用Seam Components DTD：

<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://jboss.com/products/seam/components"
            xsi:schemaLocation="http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.0.xsd">

    <component class="org.jboss.seam.core.init">
        <property name="debug">true</property>
        <property name="jndiPattern">@jndiPattern@</property>
    </component>

</components>

正如你所见，这样的配置有点繁琐。更糟的是，这些组件和属性的名称在开发时是无法被校验的。

使用命名空间的配置看起来像这样：

<?xml version="1.0" encoding="UTF-8"?>
<components xmlns="http://jboss.com/products/seam/components"
            xmlns:core="http://jboss.com/products/seam/core"
            xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
            xsi:schemaLocation=
                "http://jboss.com/products/seam/core http://jboss.com/products/seam/core-2.0.xsd
                 http://jboss.com/products/seam/components http://jboss.com/products/seam/components-2.0.xsd">

    <core:init debug="true" jndi-pattern="@jndiPattern@"/>

</components>

虽然Schema的声明很繁琐，不过实际的XML内容是清晰而简单易懂的。 Schema提供了关于每个可用组件和属性的详细信息，这使得XML编辑器可以发挥其自动完成的功效。 所以，使用命名空间的元素使生成和维护正确的 components.xml 文件都变得更加简单。

现在，这种方式对于Seam内建的组件工作得很好，但是对于用户自定义的组件又如何呢? 这里有两种选择：第一种，Seam支持两种模型的混合使用，允许使用普通的 <component> 声明来配置用户自定义的组件，同时也使用命名空间来配置内置组件。 不过更好的方法是，Seam允许你快速地为你自己的组件声明命名空间。

任何Java包都可以通过用 @Namespace 注解该包，而与XML命名空间而关联起来。 （包级别的注解是在一个名为 package-info.java 的文件中声明的，该文件处于包的同级目录下）。 下面是一个来自seampay演示的例子:

@Namespace(value="http://jboss.com/products/seam/examples/seampay")
package org.jboss.seam.example.seampay;

import org.jboss.seam.annotations.Namespace;

这样，你就可以在 components.xml 中使用命名空间的方式了！现在，你可以这么写：

<components xmlns="http://jboss.com/products/seam/components"
            xmlns:pay="http://jboss.com/products/seam/examples/seampay"
            ... >

    <pay:payment-home new-instance="#{newPayment}"
                      created-message="Created a new payment to #{newPayment.payee}" />

    <pay:payment name="newPayment"
                 payee="Somebody"
                 account="#{selectedAccount}"
                 payment-date="#{currentDatetime}"
                 created-date="#{currentDatetime}" />
     ...
</components>

或者：

<components xmlns="http://jboss.com/products/seam/components"
            xmlns:pay="http://jboss.com/products/seam/examples/seampay"
            ... >

    <pay:payment-home>
        <pay:new-instance>"#{newPayment}"</pay:new-instance>
        <pay:created-message>Created a new payment to #{newPayment.payee}</pay:created-message>
    </pay:payment-home>

    <pay:payment name="newPayment">
        <pay:payee>Somebody"</pay:payee>
        <pay:account>#{selectedAccount}</pay:account>
        <pay:payment-date>#{currentDatetime}</pay:payment-date>
        <pay:created-date>#{currentDatetime}</pay:created-date>
     </pay:payment>
     ...
</components>

这些示例展示了命名空间元素的两种使用模式。 在第一个声明中，<pay:payment-home> 指向 paymentHome 组件。

package org.jboss.seam.example.seampay;
...
@Name("paymentHome")
public class PaymentController
    extends EntityHome<Payment>
{
    ...
}

元素的名称是连字符号（-）形式的组件名称。元素的属性是连字符号（-）形式的属性名称。

在第二个声明中，<pay:payment> 元素指向 org.jboss.seam.example.seampay 包中的 Payment 类。 在这个例子中，Payment 是一个被定义成Seam组件的实体。

package org.jboss.seam.example.seampay;
...
@Entity
public class Payment
    implements Serializable
{
    ...
}

如果我们需要用户自定义组件的验证和自动完成功能，我们就需要一个Schema。 目前Seam还无法提供为一组组件自动生成Schema的机制，所以你必需手工生成。标准Seam包的Schema定义可以当作示范。

以下是Seam所使用的命名空间:

Seam组件模型是为使用 事件驱动的应用程序 而开发的，特别是在一个细粒度的事件模型里进行细粒度的松耦合组件的开发。 Seam的事件有几种类型，大部分是我们已经见过的：

所有这些不同种类的事件都通过绑定了表达式的JSF EL方法映射到Seam组件去。JSF事件是在JSF模板中定义的：

<h:commandButton value="Click me!" action="#{helloWorld.sayHello}"/>

对于jBPM的转换事件，是在jBPM过程定义或页面流定义中指定的：

<start-page name="hello" view-id="/hello.jsp">
    <transition to="hello">
        <action expression="#{helloWorld.sayHello}"/>
    </transition>
</start-page>

你可以在其他地方找到更多关于JSF事件和jBPM事件的信息。我们现在主要关注由Seam定义的两种新增类型的事件上。

<pages>
    <page view-id="/hello.jsp" action="#{helloWorld.sayHello}"/>
</pages>

<pages>
    <page view-id="/hello/*" action="#{helloWorld.sayHello}"/>
</pages>

TODO: translate struts action into page action

<pages>
    <page view-id="/hello.jsp">
        <action execute="#{helloWorld.sayHello}" if="#{not validation.failed}"/>
        <action execute="#{hitCount.increment}"/>
    </page>
</pages>

<pages>
      <page view-id="/hello.jsp" action="#{helloWorld.sayHello}">
          <param name="firstName" value="#{person.firstName}"/>
          <param name="lastName" value="#{person.lastName}"/>
      </page>
  </pages>

<pages>
      <page view-id="/hello.jsp" action="#{helloWorld.sayHello}">
          <param name="firstName" />
          <param name="lastName" />
      </page>
  </pages>

<pages>
    <page view-id="/calculator.jsp" action="#{calculator.calculate}">
        <param name="x" value="#{calculator.lhs}"/>
        <param name="y" value="#{calculator.rhs}"/>
        <param name="op" converterId="com.my.calculator.OperatorConverter" value="#{calculator.op}"/>
    </page>
</pages>

<pages>
    <page view-id="/calculator.jsp" action="#{calculator.calculate}">
        <param name="x" value="#{calculator.lhs}"/>
        <param name="y" value="#{calculator.rhs}"/>
        <param name="op" converter="#{operatorConverter}" value="#{calculator.op}"/>
    </page>
</pages>

<pages>
    <page view-id="/blog.xhtml">
        <param name="date"
               value="#{blog.date}"
               validatorId="com.my.blog.PastDate"
               required="true"/>
    </page>
</pages>

<pages>
    <page view-id="/blog.xhtml">
        <param name="date"
               value="#{blog.date}"
               validator="#{pastDateValidator}"
               required="true"/>
    </page>
</pages>

<navigation-rule>
    <from-view-id>/editDocument.xhtml</from-view-id>

    <navigation-case>
        <from-action>#{documentEditor.update}</from-action>
        <from-outcome>success</from-outcome>
        <to-view-id>/viewDocument.xhtml</to-view-id>
        <redirect/>
    </navigation-case>

</navigation-rule>

<page view-id="/editDocument.xhtml">

    <navigation from-action="#{documentEditor.update}">
        <rule if-outcome="success">
            <redirect view-id="/viewDocument.xhtml"/>
        </rule>
    </navigation>

</page>

<page view-id="/editDocument.xhtml">

    <navigation from-action="#{documentEditor.update}"
                   evaluate="#{documentEditor.errors.size}">
        <rule if-outcome="0">
            <redirect view-id="/viewDocument.xhtml"/>
        </rule>
    </navigation>

</page>

<page view-id="/editDocument.xhtml">

    <navigation from-action="#{documentEditor.update}">
        <rule if="#{documentEditor.errors.empty}">
            <redirect view-id="/viewDocument.xhtml"/>
        </rule>
    </navigation>

</page>

<page view-id="/editDocument.xhtml">

    <navigation from-action="#{documentEditor.update}">
        <rule if="#{documentEditor.errors.empty}">
            <end-conversation/>
            <redirect view-id="/viewDocument.xhtml"/>
        </rule>
    </navigation>

</page>

<page view-id="/editDocument.xhtml">

    <navigation from-action="#{documentEditor.update}">
        <rule if="#{documentEditor.errors.empty}">
            <end-conversation/>
            <redirect view-id="/viewDocument.xhtml">
                <param name="documentId" value="#{documentEditor.documentId}"/>
            </redirect>
        </rule>
    </navigation>

</page>

<page view-id="/editDocument.xhtml">

    <navigation from-action="#{documentEditor.update}">
        <rule>
            <render view-id="/viewDocument.xhtml"/>
        </rule>
    </navigation>

</page>

<page view-id="/editDocument.xhtml">

    <navigation from-action="#{documentEditor.update}">
        <render view-id="/viewDocument.xhtml"/>
    </navigation>

</page>

<page view-id="/editDocument.xhtml">

    <navigation if-outcome="success">
        <redirect view-id="/#{userAgent}/displayDocument.xhtml"/>
    </navigation>

</page>

<page action="#{calculator.calculate}">
    <param name="x" value="#{calculator.lhs}"/>
    <param name="y" value="#{calculator.rhs}"/>
    <param name="op" converter="#{operatorConverter}" value="#{calculator.op}"/>
</page>

<components>
    <event type="hello">
        <action execute="#{helloListener.sayHelloBack}"/>
        <action execute="#{logger.logHello}"/>
    </event>
</components>

@Name("helloWorld")
public class HelloWorld {
    public void sayHello() {
        FacesMessages.instance().add("Hello World!");
        Events.instance().raiseEvent("hello");
    }
}

@Name("helloWorld")
public class HelloWorld {
    @RaiseEvent("hello")
    public void sayHello() {
        FacesMessages.instance().add("Hello World!");
    }
}

@Name("helloListener")
public class HelloListener {
    public void sayHelloBack() {
        FacesMessages.instance().add("Hello to you too!");
    }
}

@Name("helloListener")
public class HelloListener {
    @Observer("hello")
    public void sayHelloBack() {
        FacesMessages.instance().add("Hello to you too!");
    }
}

@Name("helloWorld")
public class HelloWorld {
    private String name;
    public void sayHello() {
        FacesMessages.instance().add("Hello World, my name is #0.", name);
        Events.instance().raiseEvent("hello", name);
    }
}

@Name("helloListener")
public class HelloListener {
    @Observer("hello")
    public void sayHelloBack(String name) {
        FacesMessages.instance().add("Hello #0!", name);
    }
}

EJB 3.0为会话Bean组件引入了一个标准的拦截器模型。 要往Bean里添加拦截器，你需要写一个类，该类有一个被注解过的方法 @AroundInvoke，并用 @Interceptors 来注解这个Bean以指定拦截器类的名称。 例如，下面的拦截器检查用户是否在允许调用动作监听器方法之前登录：

public class LoggedInInterceptor {

   @AroundInvoke
   public Object checkLoggedIn(InvocationContext invocation) throws Exception {

      boolean isLoggedIn = Contexts.getSessionContext().get("loggedIn")!=null;
      if (isLoggedIn) {
         //the user is already logged in
         return invocation.proceed();
      }
      else {
         //the user is not logged in, fwd to login page
         return "login";
      }
   }

}

要把这个拦截器应用到一个作为动作监听器的会话Bean上，我们必须注解这个会话Bean @Interceptors(LoggedInInterceptor.class)。 这个注解有点丑陋。在EJB 3.0中，Seam通过允许将 @Interceptors 作为元注解使用，而依赖于拦截器框架。 在我们的例子中，将创建一个 @LoggedIn 注解，如下所示：

@Target(TYPE)
@Retention(RUNTIME)
@Interceptors(LoggedInInterceptor.class)
public @interface LoggedIn {}

现在，我们可以简单地用 @LoggedIn 来注解我们的动作监听器Bean以应用拦截器。

@Stateless
@Name("changePasswordAction")
@LoggedIn
@Interceptors(SeamInterceptor.class)
public class ChangePasswordAction implements ChangePassword {

    ...

    public String changePassword() { ... }

}

如果拦截器的顺序很重要（通常是这样），你可以将 @Interceptor 注解添加到你的拦截器类，来指定拦截器的部分顺序

@Interceptor(around={BijectionInterceptor.class,
                     ValidationInterceptor.class,
                     ConversationInterceptor.class},
             within=RemoveInterceptor.class)
public class LoggedInInterceptor
{
    ...
}

你甚至可以有一个“客户端”的拦截器，运行关于任何EJB3的内置功能：

@Interceptor(type=CLIENT)
public class LoggedInInterceptor
{
    ...
}

EJB拦截器是有状态的，有着和它们所拦截组件相同的生命周期。 对哪些不需要维护状态的拦截器而言，Seam通过指定 @Interceptor(stateless=true) 让你获得性能优化。

Seam的很多功能是作为一套内置的Seam拦截器来实现的，包括前面例子里提到的拦截器。 你没有必要通过注解你的组件来明确指定这些拦截器；它们为所有的可注解Seam组件而存在。

你甚至可以在JavaBean组件中使用Seam拦截器，不仅仅只有EJB3 Bean能用它们！

EJB定义拦截器，不仅为了业务方法（用@AroundInvoke），也为了生命周期方法 @PostConstruct，@PreDestroy，@PrePassivate 和 @PostActive。 Seam支持组件和拦截器中所有这些生命周期方法，不仅仅支持EJB3 Bean，也支持JavaBean组件（除了@PreDestroy 对JavaBean组件而言没有意义之外）。

JSF在异常处理方面的能力有限得令人吃惊。 作为解决这个问题的部分权宜之计，Seam让你定义如何通过注解这个异常类来处理异常的特殊类，或者在XML文件中声明这个异常类。 这个工具是想要和EJB3.0标准的 @ApplicationException 的注解组合在一起，这个注解指定了这个异常是否应该导致一个事务回滚。

<filter>
    <filter-name>Seam Filter</filter-name>
    <filter-class>org.jboss.seam.servlet.SeamFilter</filter-class>
</filter>

<filter-mapping>
    <filter-name>Seam Filter</filter-name>
    <url-pattern>*.seam</url-pattern>
</filter-mapping>

@HttpError(errorCode=404)
public class ApplicationException extends Exception { ... }

@Redirect(viewId="/failure.xhtml", end=true)
@ApplicationException(rollback=true)
public class UnrecoverableApplicationException extends RuntimeException { ... }

@Redirect(viewId="/error.xhtml", message="Unexpected error")
public class SystemException extends RuntimeException { ... }

<pages>

   <exception class="javax.persistence.EntityNotFoundException">
      <http-error error-code="404"/>
   </exception>

   <exception class="javax.persistence.PersistenceException">
      <end-conversation/>
      <redirect view-id="/error.xhtml">
          <message>数据库访问失败 Database access failed</message>
      </redirect>
   </exception>

   <exception>
      <end-conversation/>
      <redirect view-id="/error.xhtml">
          <message>意外的失败 Unexpected failure</message>
      </redirect>
   </exception>

</pages>

...
throw new AuthorizationException("You are not allowed to do this!");

<pages>

    <exception class="org.jboss.seam.security.AuthorizationException">
        <end-conversation/>
        <redirect view-id="/error.xhtml">
            <message severity="WARN">#{org.jboss.seam.handledException.message}</message>
        </redirect>
    </exception>

</pages>

<exception class="javax.persistence.EntityNotFoundException">
   <redirect view-id="/error.xhtml">
      <message>Not found</message>
   </redirect>
</exception>

<exception class="javax.persistence.OptimisticLockException">
   <end-conversation/>
   <redirect view-id="/error.xhtml">
      <message>另一个用户修改了相同的数据，请重试 Another user changed the same data, please try again</message>
   </redirect>
</exception>

<exception class="org.jboss.seam.framework.EntityNotFoundException">
   <redirect view-id="/error.xhtml">
      <message>Not found</message>
   </redirect>
</exception>

<exception class="org.jboss.seam.security.AuthorizationException">
   <redirect>
      <message>You don't have permission to do this</message>
   </redirect>
</exception>

<exception class="org.jboss.seam.security.NotLoggedInException">
   <redirect view-id="/login.xhtml">
      <message>Please log in first</message>
   </redirect>
</exception>

<exception class="javax.faces.application.ViewExpiredException">
   <redirect view-id="/error.xhtml">
      <message>您的会话已经超时，请重试 Your session has timed out, please try again</message>
   </redirect>
</exception>