seam组件注解

编写Seam应用程序时需要使用大量的注解。Seam让我们使用注解获得声明式编程风格。大部分注解由EJB3.0规范定义。数据验证通过Hibernate Validator包定义。最后，Seam定义了它自己的注解集合，这就是我们这一章将要描述的。

所有这些注解在 org.jboss.seam.annotations包中定义。

27.1. 用于定义组件的注解

我们要看的第一组注解让我们定义一个Seam组件。这些注解在组件（component）类中出现。

@Name

@Name("componentName")

为一个类定义一个Seam组件。所有Seam组件都需要该注解。

@Scope

@Scope(ScopeType.CONVERSATION)

定义默认的组件上下文。可以定义的值由 ScopeType枚举：EVENT, PAGE, CONVERSATION, SESSION,BUSINESS_PROCESS, APPLICATION, STATELESS。

当范围没有显式定义时，默认的范围取决于组件类型。 对于无状态会话bean，默认是 STATELESS。 对于Entity Bean和Stateful Session Bean，默认是CONVERSATION。 对于JavaBean，默认是 EVENT。

@Role

@Role(name="roleName", scope=ScopeType.SESSION)

允许一个Seam组件绑定多个上下文变量。 @Name/@Scope 注解定义一个“默认角色”。每一个 @Role 注解定一个附加角色。

• name — 上下文变量的名字。

• scope —上下文变量的作用域。当没有显式定义作用域时，和上面一样默认取决于组件类型。

@Roles

@Roles({        @Role(name="user", scope=ScopeType.CONVERSATION),        @Role(name="currentUser", scope=ScopeType.SESSION)    })

允许指定多个额外角色。

@BypassInterceptors

@BypassInterceptors

取消在特定组件或者一个组件方法上的所有拦截器。

@JndiName

@JndiName("my/jndi/name")

Seam查找EJB组件的JNDI名。 如果没有显式指定JNDI名，Seam将使用由 org.jboss.seam.core.init.jndiPattern 指定的JNDI模式。

@Conversational

@Conversational

声明一个对话作用域组件是对话式的，亦即只有长期运行的对话处于活动状态时，组件中的方法才可以被调用。

@Startup

@Scope(APPLICATION) @Startup(depends="org.jboss.seam.bpm.jbpm")

指定某个ApplicationScope的组件在初始化时立即启动。它主要用于特别的内置组件，用于引导象JNDI，数据源等等关键性的设施。

@Scope(SESSION) @Startup

指定某个Session Scope的组件在Session建立时立即启动。

• depends —依赖于，指定必须在此之前启动的命名组件（如果已安装）。

@Install

@Install(false)

指定组件是否应该被默认安装。没有@Install注解则表明该组件应该被安装。

@Install(dependencies="org.jboss.seam.bpm.jbpm")

如果所指定的依赖组件被安装，那么该组件才安装。

@Install(genericDependencies=ManagedQueueSender.class)

如果所指定的类的某个实现组件被安装，那么该组件才安装。当无法确定依赖组件的唯一公开名字时，这就有用了。

@Install(classDependencies="org.hibernate.Session")

如果所指定的类在classpath中，那么该组件才安装。

@Install(precedence=BUILT_IN)

指定组件的优先级别。如果具有相同名字的多个组件存在，具有高优先级的才被安装。定义的优先级是（递增排序）：

• BUILT_IN — 所有内置的Seam组件的优先级别

• FRAMEWORK — 用于扩展Seam的框架组件的优先级别

• APPLICATION — 应用程序的组件优先级别（默认优先级）

• DEPLOYMENT — 在特定部署中重载应用程序组件的组件优先级别

• MOCK — 在测试时mock对象使用的优先级别

@Synchronized

@Synchronized(timeout=1000)

如果组件被多个客户端并发访问，Seam应该串行化请求。如果一个请求在给定时间段内没有得到组件的锁，将抛出一个例外。

@ReadOnly

@ReadOnly

声明JavaBean组件或者组件方法在调用结束时不要求状态复制。

@AutoCreate

@AutoCreate

声明组件将被自动建立，即使客户端不定义 create=true。

27.2. 用于双向注入的注解

下面两个注解控制双向注入。这些属性用于组件实例变量或者属性访问方法中。

@In

@In

在每次组件调用开始时，从上下文变量注入此组件属性。如果上下文变量是null，那么一个异常将被抛出。

@In(required=false)

在每次组件调用开始时，从上下文变量注入此组件属性。上下文变量可为null。

@In(create=true)

在每次组件调用开始时，从上下文变量注入此组件属性。如果上下文变量为null，那么Seam实例化这个组件。

@In(value="contextVariableName")

显式指定上下文变量的名字，而不再使用注解定义的实例变量名。

@In(value="#{customer.addresses['shipping']}")

在每次组件调用开始时，用一个JSF EL表达式的计算结果来注入组件属性。

• value — 指定上下文变量名。默认是组件属性名。可选地，指定一个JSFEL表达式，放在 #{...} 符号中。

• create —指定若上下文变量名在所有上下文中均未定义，Seam应该创建一个组件作为上下文变量，名字即为所要求的名字。默认为false。

• required —指定若上下文变量名在所有上下文中均未定义，Seam应抛出异常。

@Out

@Out

在调用结束后注射出Seam组件属性到上下文变量。若属性为null，则抛出一个异常。

@Out(required=false)

在调用结束后注射出Seam组件属性到上下文变量。属性可以为null。

@Out(scope=ScopeType.SESSION)

在调用结束后注射出非Seam组件属性到指定scope。

或者，若没有明确指定scope，则使用此 @Out属性所属组件的scope。（如果此组件是无状态的，则使用 EVENTscope。）

@Out(value="contextVariableName")

显式指定上下文变量名，而非使用注解中指定的实例变量名。

• value — 指定上下文变量名。默认为组件属性名。

• required —指定若注射出时组件属性为null，Seam应抛出异常。

注意一起使用这些注解相当常见，例如：

@In(create=true) @Out private User currentUser;

下一个注解支持 管理器组件（managercomponent）模式，在该模式中一个Seam组件管理一些其他将被注入的class实例的生命周期。它在组件的getter方法中出现。

@Unwrap

@Unwrap

指定注解的getter方法返回的对象是被注入的，而非组件实例本身。

下一个注解支持 工厂组件（factorycomponent） 模式，在该模式中，一个Seam组件负责初始化上下文变量值。如果出现非faces的request，在渲染response的时候，它用于初始化所需要的状态特别有用。它出现在组件方法中。

@Factory

@Factory("processInstance") public void createProcessInstance() { ... }

说明当上下文变量没有值时，此组件的方法被用来初始化上下文变量值。它用于返回值是 void 的方法。

@Factory("processInstance", scope=CONVERSATION) public ProcessInstance createProcessInstance() { ... }

声明方法返回一个值，当上下文变量没有值时Seam应使用此值初始化命名上下文变量值。它用于返回一个值的方法。若没有指明scope，则使用 @Factory方法所在组件的scope（除非组件是无状态的，则使用 EVENT 上下文）。

• value —指定上下文变量值。若为getter方法，默认为JavaBean属性名。

• scope —指定Seam应绑定返回值的作用域。仅针对于返回一个值的工厂方法有意义。

• autoCreate —无论什么时候请求变量，此工厂方法将自动被调用，即使@In未指定create=true。

下面的注解让你注入一个 日志（Log）：

@Logger

@Logger("categoryName")

使用 org.jboss.seam.log.Log的实例注入一个组件字段。对于Entity Bean，该字段必须声明为static。

• value — 指定日志category。默认是组件类名。

最后一个注解让你注入一个request参数值：

@RequestParameter

@RequestParameter("parameterName")

将request的参数值注入组件属性。基本类型的转化被自动地完成。

• value —指定request参数名。默认为组件属性名。

27.3. 关于组件生命周期方法的注解

这些注解允许组件响应它自己的生命周期事件。它们作用于组件方法。对每个组件class来说，每种注解只允许出现一次。

@Create

@Create

当组件实例被Seam初始化时，该方法应被调用。注意仅有JavaBean和Stateful SessionBean支持create方法。

@Destroy

@Destroy

当上下文结束和它的上下文变量销毁时，该方法应被调用。注意仅有JavaBean和Stateful SessionBean支持destroy方法。

Destroy方法应仅仅用于清理工作。Seam会捕捉、记录，然后消灭destroy方法传播的任何异常。

@Observer

@Observer("somethingChanged")

指定当特定类型的component-driven（组件驱动）事件发生时，该方法应被调用。

@Observer(value="somethingChanged",create=false)

当指定类型的一个事件发生时，该方法应被调用，但若实例都不存在，则不创建实例。若实例不存在并且create是false，事件将不会觉察到。create的默认值是true。

27.4. 用于声明上下文的注解

这些注解提供声明式对话分界（declarative conversationdemarcation）。它们在Seam组件方法中使用，通常是动作监听器方法（Action Listener Method）。

每个Web请求有一个对话上下文和它关联。这些对话的大多数在请求结束时结束。如果你想要一个对话跨越多个请求，你必须通过调用标志为@Begin 的方法来“提升”当然的对话为一个长期运行的对话（long-running conversation）。

@Begin

@Begin

当此方法无异常的返回一个非空结果时，一个长期运行的对话开始。

@Begin(join=true)

若已经处于长期运行对话中，简单的延续此对话上下文。

@Begin(nested=true)

若已经处于长期运行对话中，一个新的被 嵌套（nested） 对话上下文开始。 该被嵌套的对话在遇到下一个@End时结束，并且外部上下文将恢复。在同一个外部对话中同时嵌套多个对话是完全合法的。

@Begin(pageflow="process definition name")

指定该对话的页面流（pageflow）的jBPM进程定义名。

@Begin(flushMode=FlushModeType.MANUAL)

指定任何Seam管理的持久上下文的flush模式。flushMode=FlushModeType.MANUAL 支持 原子对话（atomicconversations），这里所有写操作在会话上下文进入队列，直到显式调用 flush()（调用通常发生在对话结束时）。

• join — 定义当长期对话已经存在时的行为。 若是true，传播上下文。若为 false，抛出一个异常。默认为false。当指定 nested=true 时，将忽略该设置。

• nested —当长期对话已经存在时，一个嵌套对话应该建立。

• flushMode —设置任何在此会话期间创建的，被Seam管理的Hibernate Session或JPA持久上下文的flush模式。

• pageflow — 由 org.jboss.seam.bpm.jbpm.pageflowDefinitions部署的一个jBPM处理的进程定义名。

@End

@End

当这个方法无异常的返回一个非空输出时，长期对话结束。

• beforeRedirect —默认情况下，若有重定向，直到所有的重定向结束后，对话才会被真正destory。 设置beforeRedirect=true指定该对话应在当前request结束时就结束，并且在一个新的临时对话上下文中处理重定向。

@StartTask

@StartTask

"开始"一个jBPM任务。当此方法无异常的返回一个非空输出时，长期运行对话开始。此对话同在某个request具名参数中被指定的jBMP任务相关联。在该会话上下文中，还定义了一个业务流程上下文（business process context），用作任务实例的业务流程实例。

jBPM的 TaskInstance 在request context中以taskInstance 的名字作为变量出现。 jPBM的 ProcessInstance 在request context中以 processInstance 的名字作为变量出现。（当然，这些对象也可用于通过 @In 注入。）

• taskIdParameter — 保存有taskid的request参数的名字。 默认为"taskId"，同时也是SeamtaskList JSF component使用的默认值。

• flushMode —设置任何在此对话期间创建的，被Seam管理的Hibernate Session或JPA持久上下文的flush模式。

@BeginTask

@BeginTask

恢复一个未完成的jBMP任务。当此方法无异常的返回一个非空值时，长时间运行的对话开始。此对话同在某个request参数中指定的jBMP任务相关联。在该对话上下文中，还定义了一个业务流程上下文（business process context），用作任务实例的业务流程实例。

jBPM的 org.jbpm.taskmgmt.exe.TaskInstance 在requestcontext中以 taskInstance 的名字作为变量出现。 jBPM的org.jbpm.graph.exe.ProcessInstance在request context中以 processInstance的名字作为变量出现。

• taskIdParameter — 保存有taskid的request参数的名字。 默认为"taskId"，同时也是SeamtaskList JSF component使用的默认值。

• flushMode —设置任何在此会话期间创建的，被Seam管理的Hibernate Session或JPA持久上下文的flush模式。

@EndTask

@EndTask

"结束"一个jBPM任务。当此方法无异常返回一个非空输出时，结束长时间运行的会话。触发一个jBMP流转（transition）。 若没有调用 transition 内置组件的Transition.setName()方法，实际被触发的将是默认的transition。

@EndTask(transition="transitionName")

触发给定jBPM流转。

• transition —当任务结束时触发的jBPM流转名。默认为默认的流转transition。

• beforeRedirect —默认情况下，若有重定向，直到所有的重定向结束后，会话才会被真正destory。 设置 beforeRedirect=true指定该会话应在当前request结束时就结束，并且在一个新的临时会话上下文中处理重定向。

@CreateProcess

@CreateProcess(definition="process definition name")

当方法无异常返回一个非空输出时，建立一个新的jBPM流程实例。 ProcessInstance 对象在上下文中以 processInstance 的名字作为一个变量出现。

• definition — 通过 org.jboss.seam.bpm.jbpm.processDefinitions 部署的jBPM流程定义的名字。

@ResumeProcess

@ResumeProcess(processIdParameter="processId")

当方法无异常返回一个非空输出时，重新进入一个已存的jBPM 流程实例的context。ProcessInstance 对象在上下文中以 processInstance 的名字作为一个变量出现。

• processIdParameter —保存有该流程id的request参数名。默认是 "processId".

@Transition

@Transition("cancel")

当此方法返回一个非空结果时，向在当前jBPM流程实例中发送一个流转信号。