编写Seam应用程序时需要使用大量的注解。Seam让我们使用注解获得声明式编程风格。大部分注解由EJB3.0规范定义。 数据验证通过Hibernate Validator包定义。最后,Seam定义了它自己的注解集合,这就是我们这一章将要描述的。
所有这些注解在 org.jboss.seam.annotations 包中定义。
我们要看的第一组注解让我们定义一个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")
指定某个Application Scope的组件在初始化时立即启动。它主要用于特别的内置组件,用于引导象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。
下面两个注解控制双向注入。这些属性用于组件实例变量或者属性访问方法中。
-
@In
-
@In
在每次组件调用开始时,从上下文变量注入此组件属性。如果上下文变量是null,那么一个异常将被抛出。
@In(required=false)
在每次组件调用开始时,从上下文变量注入此组件属性。上下文变量可为null。
@In(create=true)
在每次组件调用开始时,从上下文变量注入此组件属性。如果上下文变量为null,那么Seam实例化这个组件。
@In(value="contextVariableName")
显式指定上下文变量的名字,而不再使用注解定义的实例变量名。
@In(value="#{customer.addresses['shipping']}")
在每次组件调用开始时,用一个JSF EL表达式的计算结果来注入组件属性。
-
value — 指定上下文变量名。默认是组件属性名。可选地,指定一个JSF EL表达式,放在 #{...} 符号中。
-
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;
下一个注解支持 管理器组件(manager component) 模式,在该模式中一个Seam组件管理一些其他将被注入的class实例的生命周期。它在组件的getter方法中出现。
下一个注解支持 工厂组件(factory component) 模式,在该模式中,一个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):
最后一个注解让你注入一个request参数值:
这些注解允许组件响应它自己的生命周期事件。它们作用于组件方法。对每个组件class来说,每种注解只允许出现一次。
-
@Create
-
@Create
当组件实例被Seam初始化时,该方法应被调用。注意仅有JavaBean和Stateful Session Bean支持create方法。
@Destroy
-
@Destroy
当上下文结束和它的上下文变量销毁时,该方法应被调用。注意仅有JavaBean和Stateful Session Bean支持destroy方法。
Destroy方法应仅仅用于清理工作。Seam 会捕捉、记录,然后消灭destroy方法传播的任何异常。
@Observer
-
@Observer("somethingChanged")
指定当特定类型的component-driven(组件驱动)事件发生时,该方法应被调用。
@Observer(value="somethingChanged",create=false)
当指定类型的一个事件发生时,该方法应被调用,但若实例都不存在,则不创建实例。 若实例不存在并且create是false,事件将不会觉察到。create的默认值是true。
这些注解提供声明式对话分界(declarative conversation demarcation)。它们在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 支持 原子对话(atomic conversations),这里所有写操作在会话上下文进入队列,直到显式调用 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 — 保存有task id的request参数的名字。 默认为"taskId",同时也是Seam taskList JSF component使用的默认值。
-
flushMode — 设置任何在此对话期间创建的,被Seam管理的Hibernate Session或JPA持久上下文的flush模式。
@BeginTask
-
-
@BeginTask
恢复一个未完成的jBMP任务。当此方法无异常的返回一个非空值时,长时间运行的对话开始。此对话同在某个request参数中指定的jBMP任务相关联。 在该对话上下文中,还定义了一个业务流程上下文(business process context),用作任务实例的业务流程实例。
jBPM的 org.jbpm.taskmgmt.exe.TaskInstance 在request context中以 taskInstance 的名字作为变量出现。 jBPM的 org.jbpm.graph.exe.ProcessInstance 在request context中以 processInstance 的名字作为变量出现。
-
taskIdParameter — 保存有task id的request参数的名字。 默认为"taskId",同时也是Seam taskList 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流程实例中发送一个流转信号。