Chapter 20. Seam annotations - JBoss Seam 1.1.6 正式版英文参考手册

@Name("componentName")

Defines the Seam component name for a class. This annotation is required for all Seam components.

@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(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.

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

Allows specification of multiple additional roles.

@Intercept(InterceptionType.ALWAYS)

Determines when Seam interceptors are active. The possible values are defined by the InterceptionType enumeration: ALWAYS, AFTER_RESTORE_VIEW, AFTER_UPDATE_MODEL_VALUES, 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, message driven beans and JavaBeans, the default is ALWAYS.

@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(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).

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

@Install(false)

Specifies whether or not a component should be installed by default. The lack of an @Install annotation indicates a component should be installed.

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

Specifies that a component should only be stalled if the components listed as dependencies are also installed.

@Install(genericDependencies=ManagedQueueSender.class)

Specifies that a component should only be installed if a component that is implemented by a certain class is installed. This is useful when the dependency doesn't have a single well-known name.

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

Specifies that a component should only be installed if the named class is in the classpath.

@Install(precedence=BUILT_IN)

Specifies the precedence of the component. If multiple components with the same name exist, the one with the higher precedence will be installed. The defined precendence values are:

@Synchronized(timeout=1000)

Specifies that a component is accessed concurrently by multiple clients, and that Seam should serialize requests. If a request is not able to obtain its lock on the component in the given timeout period, an exception will be raised.

@ReadOnly

Specifies that a JavaBean component or component method does not require state replication at the end of the invocation.

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

@Out

Specifies that a component attribute that is a Seam component is to be outjected to its 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 its 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 type is to be outjected to a specific scope at the end of the invocation.

Alternatively, if no scope is explicitly specified, the scope of the component with the @Out attribute is used (or the EVENT scope if the component is stateless).

@Out(value="contextVariableName")

Specifies the name of the context variable explicitly, instead of using the annotated instance variable name.

@Unwrap

Specifies that the object returned by the annotated getter method is the thing that is injected instead of the component instance itself.

@Factory("processInstance")

Specifies that the method of the component is used to initialize the value of the named context variable, when the context variable has no value. This style is used with methods that return void.

@Factory("processInstance", scope=CONVERSATION)

Specifies that the method returns a value that Seam should use to initialize the value of the named context variable, when the context variable has no value. This style is used with methods that return a value. If no scope is explicitly specified, the scope of the component with the @Factory method is used (unless the component is stateless, in which case the EVENT context is used).

@Logger("categoryName")

Specifies that a component field is to be injected with an instance of org.jboss.seam.log.Log.

@RequestParameter("parameterName")

Specifies that a component attribute is to be injected with the value of a request parameter. Basic type conversions are performed automatically.

@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

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("somethingChanged")

Specifies that the method should be called when a component-driven event of the specified type occurs.

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

Specifies that the method should be called when an event of the specified type occurs but that an instance should not be created if one doesn't exist. If an instance does not exist and create is false, the event will not be observed. The default value for create is true.

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

@Begin(flushMode=FlushModeType.MANUAL)

Specify the flush mode of any Seam-managed persistence contexts. flushMode=FlushModeType.MANUAL supports the use of atomic conversations where all write operations are queued in the conversation context until an explicit call to flush() (which usually occurs at the end of the conversation).

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

@StartTask

"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.)

@BeginTask

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.

@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(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.

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

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

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

@Redirect(viewId="error.jsp")

Specifies that the annotated exception causes a browser redirect to a specified view id.

@HttpError(errorCode=404)

Specifies that the annotated exception causes a HTTP error to be sent.

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

@WebRemote(exclude="path.to.exclude")

Indicates that the annotated method may be called from client-side JavaScript. The exclude property is optional and allows objects to be excluded from the result's object graph (see the Remoting chapter for more details).

@Interceptor(stateless=true)

Specifies that this interceptor is stateless and Seam may optimize replication.

@Interceptor(type=CLIENT)

Specifies that this interceptor is a "client-side" interceptor that is called before the EJB container.

@Interceptor(around={SomeInterceptor.class, OtherInterceptor.class})

Specifies that this interceptor is positioned higher in the stack than the given interceptors.

@Interceptor(within={SomeInterceptor.class, OtherInterceptor.class})

Specifies that this interceptor is positioned deeper in the stack than the given interceptors.

@Asynchronous

Specifies that the method call is processed asynchronously.

@Duration

Specifies that a parameter of the asynchronous call is the duration before the call is processed (or first processed for recurring calls).

@Expiration

Specifies that a parameter of the asynchronous call is the datetime at which the call is processed (or first processed for recurring calls).

@IntervalDuration

Specifies that an asynchronous method call recurs, and that the annotationed parameter is duration between recurrences.

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

@DataModelSelection

Injects the selected value from the JSF DataModel (this is the element of the underlying collection, or the map value).

@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).

@DataBinderClass(DataModelBinder.class)

Specifies that an annotation is a databinding annotation.

@DataSelectorClass(DataModelSelector.class)

Specifies that an annotation is a dataselection annotation.

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

Specifies that components in the current package are associated with the given namespace. The declared namespace can be used as an XML namespace in a components.xml file to simplify application configuration.

@Namespace(value="http://jboss.com/products/seam/core", prefix="org.jboss.seam.core")

Specifies a namespace to associate with a given package. Additionally, it specifies a component name prefix to be applied to component names specified in the XML file. For example, an XML element named microcontainer that is associated with this namespace would be understood to actually refere to a component named org.jboss.seam.core.microcontainer.