Chapter 10. Seam annotations - JBoss Seam 1.0.1 正式版英文参考手册
When you write a Seam application, you'll use a lot of annotations. Seam lets you use annotations to achieve a declarative style of programming. Most of the annotations you'll use are defined by the EJB 3.0 specification. The annotations for data validation are defined by the Hibernate Validator package. Finally, Seam defines its own set of annotations, which we'll describe in this chapter.
All of these annotations are defined in the package org.jboss.seam.annotations.
The first group of annotations lets you define a Seam component. These annotations appear on the component class.
- @Name
@Name("componentName")Defines the Seam component name for a class. This annotation is required for all Seam components.
- @Scope
@Scope(ScopeType.CONVERSATION)
Defines the default context of the component. The possible values are defined by the ScopeType enumeration: EVENT, PAGE, CONVERSATION, SESSION, BUSINESS_PROCESS, APPLICATION, STATELESS.
When no scope is explicitly specified, the default depends upon the component type. For stateless session beans, the default is STATELESS. For entity beans and stateful session beans, the default is CONVERSATION. For JavaBeans, the default is EVENT.
- @Role
@Role(name="roleName", scope=ScopeType.SESSION)
Allows a Seam component to be bound to multiple contexts variables. The @Name/@Scope annotations define a "default role". Each @Role annotation defines an additional role.
name — the context variable name.
scope — the context variable scope. When no scope is explicitly specified, the default depends upon the component type, as above.
- @Roles
@Roles({ @Role(name="user", scope=ScopeType.CONVERSATION), @Role(name="currentUser", scope=ScopeType.SESSION) })Allows specification of multiple additional roles.
- @Intercept
@Intercept(InterceptionType.ALWAYS)
Determines when Seam interceptors are active. The possible values are defined by the InterceptionType enumeration: ALWAYS, INVOKE_APPLICATION, NEVER.
When no interception type is explicitly specified, the default depends upon the component type. For entity beans, the default is NEVER. For session beans and JavaBeans, the default is INVOKE_APPLICATION (interception only enabled during the JSF invoke application phase).
- @JndiName
@JndiName("my/jndi/name")Specifies the JNDI name that Seam will use to look up the EJB component. If no JNDI name is explicitly specified, Seam will use the JNDI pattern specified by org.jboss.seam.core.init.jndiPattern.
- @Conversational
@Conversational(ifNotBegunOutcome="error")
Specifies that a conversation scope component is conversational, meaning that no method of the component can be called unless a long-running conversation started by this component is active (unless the method would begin a new long-running conversation).
ifNotBegunOutcome — specifies a JSF outcome for the action when the component is invoked and no long-running conversation is active.
- @Startup
@Startup(depends={"org.jboss.core.jndi", "org.jboss.core.jta"})Specifies that an application scope component is started immediately at initialization time. This is mainly used for certain built-in components that bootstrap critical infrastructure such as JNDI, datasources, etc.
@Startup
Specifies that a session scope component is started immediately at session creation time.
depends — specifies that the named components must be started first, if they are installed.
The next two annotations control bijection. These attributes occur on component instance variables or property accessor methods.
- @In
@In
Specifies that a component attribute is to be injected from a context variable at the beginning of each component invocation. If the context variable is null, an exception will be thrown.
@In(required=false)
Specifies that a component attribute is to be injected from a context variable at the beginning of each component invocation. The context variable may be null.
@In(create=true)
Specifies that a component attribute is to be injected from a context variable at the beginning of each component invocation. If the context variable is null, an instance of the component is instantiated by Seam.
@In(value="contextVariableName")
Specifies the name of the context variable explicitly, instead of using the annotated instance variable name.
@In(value="#{customer.addresses['shipping']}")Specifies that a component attribute is to be injected by evaluating a JSF EL expression at the beginning of each component invocation.
value — specifies the name of the context variable. Default to the name of the component attribute. Alternatively, specifies a JSF EL expression, surrounded by #{...}.
create — specifies that Seam should instantiate the component with the same name as the context variable if the context variable is undefined (null) in all contexts. Default to false.
required — specifies Seam should throw an exception if the context variable is undefined in all contexts.
- @Out
@Out
Specifies that a component attribute that is a Seam component is to be outjected to a context variable at the end of the invocation. If the attribute is null, an exception is thrown.
@Out(required=false)
Specifies that a component attribute that is a Seam component is to be outjected to a context variable at the end of the invocation. The attribute may be null.
@Out(scope=ScopeType.SESSION)
Specifies that a component attribute that is not a Seam component is to be outjected to a specific scope at the end of the invocation.
@Out(value="contextVariableName")
Specifies the name of the context variable explicitly, instead of using the annotated instance variable name.
value — specifies the name of the context variable. Default to the name of the component attribute.
required — specifies Seam should throw an exception if the component attribute is null during outjection.
Note that it is quite common for these annotations to occur together, for example:
@In(create=true) @Out private User currentUser;
The next annotation supports the manager component pattern, where a Seam component that manages the lifecycle of an instance of some other class that is to be injected. It appears on a component getter method.
The next annotation supports the factory component pattern, where a Seam component is responsible for initializing the value of a context variable. This is especially useful for initializing any state needed for rendering the response to a non-faces request. It appears on a component method.
This annotation lets you inject a Log:
The last annotation lets you inject a request parameter value:
These annotations allow a component to react to its own lifecycle events. They occur on methods of the component. There may be only one of each per component class.
- @Create
@Create
Specifies that the method should be called when an instance of the component is instantiated by Seam. Note that create methods are only supported for JavaBeans and stateful session beans.
- @Destroy
@Destroy
Specifies that the method should be called when the context ends and its context variables are destroyed. Note that create methods are only supported for JavaBeans and stateful session beans.
Note that all stateful session bean components must define a method annotated @Destroy @Remove in order to guarantee destruction of the stateful bean when a context ends.
Destroy methods should be used only for cleanup. Seam catches, logs and swallows any exception that propagates out of a destroy method.
- @Observer
@Observer("somethingChanged")Specifies that the method should be called when a component-driven event of the specified type occurs.
These annotations provide declarative conversation demarcation. They appear on methods of Seam components, usually action listener methods.
Every web request has a conversation context associated with it. Most of these conversations end at the end of the request. If you want a conversation that span multiple requests, you must "promote" the current conversation to a long-running conversation by calling a method marked with @Begin.
- @Begin
@Begin
Specifies that a long-running conversation begins when this method returns a non-null outcome without exception.
@Begin(ifOutcome={"success", "continue"})Specifies that a long-running conversation begins when this action listener method returns with one of the given outcomes.
@Begin(join=true)
Specifies that if a long-running conversation is already in progress, the conversation context is simply propagated.
@Begin(nested=true)
Specifies that if a long-running conversation is already in progress, a new nested conversation context begins. The nested conversation will end when the next @End is encountered, and the outer conversation will resume. It is perfectly legal for multiple nested conversations to exist concurrently in the same outer conversation.
@Begin(pageflow="process definition name")
Specifies a jBPM process definition name that defines the pageflow for this conversation.
ifOutcome — specifies the JSF outcome or outcomes that result in a new long-running conversation context.
join — determines the behavior when a long-running conversation is already in progress. If true, the context is propagated. If false, an exception is thrown. Default to false. This setting is ignored when nested=true is specified
nested — specifies that a nested conversation should be started if a long-running conversation is already in progress.
pageflow — a process definition name of a jBPM process definition deployed via org.jboss.seam.core.jbpm.pageflowDefinitions.
- @End
@End
Specifies that a long-running conversation ends when this method returns a non-null outcome without exception.
@End(ifOutcome={"success", "error"}, evenIfException={SomeException.class, OtherException.class})Specifies that a long-running conversation ends when this action listener method returns with one of the given outcomes or throws one of the specified classes of exception.
ifOutcome — specifies the JSF outcome or outcomes that result in the end of the current long-running conversation.
- @StartTask
@StartTask(taskIdParameter="taskId")
"Starts" a jBPM task. Specifies that a long-running conversation begins when this method returns a non-null outcome without exception. This conversation is associated with the jBPM task specified in the named request parameter. Within the context of this conversation, a business process context is also defined, for the business process instance of the task instance.
The jBPM TaskInstance will be available in a request context variable named taskInstance. The jPBM ProcessInstance will be available in a request context variable named processInstance. (Of course, these objects are available for injection via @In.)
taskIdParameter — the name of a request parameter which holds the id of the task. Default to "taskId", which is also the default used by the Seam taskList JSF component.
- @BeginTask
@BeginTask(taskIdParameter="taskId")
Resumes work on an incomplete jBPM task. Specifies that a long-running conversation begins when this method returns a non-null outcome without exception. This conversation is associated with the jBPM task specified in the named request parameter. Within the context of this conversation, a business process context is also defined, for the business process instance of the task instance.
The jBPM TaskInstance will be available in a request context variable named taskInstance. The jPBM ProcessInstance will be available in a request context variable named processInstance.
taskIdParameter — the name of a request parameter which holds the id of the task. Default to "taskId", which is also the default used by the Seam taskList JSF component.
- @EndTask
@EndTask
"Ends" a jBPM task. Specifies that a long-running conversation ends when this method returns a non-null outcome, and that the current task is complete. Triggers a jBPM transition. The actual transition triggered will be the default transition unless the application has called Transition.setName() on the built-in component named transition.
@EndTask(transition="transitionName")
Triggers the given jBPM transition.
@EndTask(ifOutcome={"success", "continue"})Specifies that the task ends when this method returns one of the listed outcomes.
- @CreateProcess
@CreateProcess(definition="process definition name")
Creates a new jBPM process instance when the method returns a non-null outcome without exception. The ProcessInstance object will be available in a context variable named processInstance.
definition — the name of the jBPM process definition deployed via org.jboss.seam.core.jbpm.processDefinitions.
- @ResumeProcess
@ResumeProcess(processIdParameter="processId")
Re-enters the scope of an existing jBPM process instance when the method returns a non-null outcome without exception. The ProcessInstance object will be available in a context variable named processInstance.
processIdParameter — the name a request parameter holding the process id. Default to "processId".
Seam provides an annotation that lets you force a rollback of the JTA transaction for certain action listener outcomes.
- @Rollback
@Rollback(ifOutcome={"failure", "not-found"})If the outcome of the method matches any of the listed outcomes, or if no outcomes are listed, set the transaction to rollback only when the method completes.
ifOutcome — the JSF outcomes that cause a transaction rollback (no outcomes is interpreted to mean any outcome).
- @Transactional
@Transactional
Specifies that a JavaBean component should have a similar transactional behavior to the default behavior of a session bean component. ie. method invocations should take place in a transaction, and if no transaction exists when the method is called, a transaction will be started just for that method. This annotation may be applied at either class or method level.
Seam applications usually use the standard EJB3 annotations for all other transaction demarcation needs.
This annotation triggers Hibernate Validator. It appears on a method of a Seam component, almost always an action listener method.
Please refer to the documentation for the Hibernate Annotations package for information about the annotations defined by the Hibernate Validator framework.
- @IfInvalid
@IfInvalid(outcome="invalid", refreshEntities=true)
Specifies that Hibernate Validator should validate the component before the method is invoked. If the invocation fails, the specified outcome will be returned, and the validation failure messages returned by Hibernate Validator will be added to the FacesContext. Otherwise, the invocation will proceed.
outcome — the JSF outcome when validation fails.
refreshEntities — specifies that any invalid entity in the managed state should be refreshed from the database when validation fails. Default to false. (Useful with extended persistence contexts.)
Seam Remoting requires that the local interface of a session bean be annotated with the following annotation:
The following annotations appear on Seam interceptor classes.
Please refer to the documentation for the EJB 3.0 specification for information about the annotations required for EJB interceptor definition.
- @Around
@Around({SomeInterceptor.class, OtherInterceptor.class})Specifies that this interceptor is positioned higher in the stack than the given interceptors.
- @Within
@Within({SomeInterceptor.class, OtherInterceptor.class})Specifies that this interceptor is positioned deeper in the stack than the given interceptors.
The following annotations make it easy to implement clickable lists backed by a stateful session bean. They appear on attributes.
- @DataModel
@DataModel("variableName")Exposes an attribute of type List, Map, Set or Object[] as a JSF DataModel into the scope of the owning component (or the EVENT scope if the owning component is STATELESS). In the case of Map, each row of the DataModel is a Map.Entry.
value — name of the conversation context variable. Default to the attribute name.
scope — if scope=ScopeType.PAGE is explicitly specified, the DataModel will be kept in the PAGE context.
- @DataModelSelection
@DataModelSelection
Injects the selected value from the JSF DataModel (this is the element of the underlying collection, or the map value).
value — name of the conversation context variable. Not needed if there is exactly one @DataModel in the component.
- @DataModelSelectionIndex
@DataModelSelectionIndex
Exposes the selection index of the JSF DataModel as an attribute of the component (this is the row number of the underlying collection, or the map key).
value — name of the conversation context variable. Not needed if there is exactly one @DataModel in the component.
These meta-annotations make it possible to implement similar functionality to @DataModel and @DataModelSelection for other datastructures apart from lists.