SeamFramework.orgCommunity Documentation

Chapter 30. Seam annotations

30.1. Annotations for component definition
30.2. Annotations for bijection
30.3. Annotations for component lifecycle methods
30.4. Annotations for context demarcation
30.5. Annotations for use with Seam JavaBean components in a J2EE environment
30.6. Annotations for exceptions
30.7. Annotations for Seam Remoting
30.8. Annotations for Seam interceptors
30.9. Annotations for asynchronicity
30.10. Annotations for use with JSF
30.10.1. Annotations for use with dataTable
30.11. Meta-annotations for databinding
30.12. Annotations for packaging
30.13. Annotations for integrating with the servlet container

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.

@Roles
@Roles({

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

Allows specification of multiple additional roles.

@BypassInterceptors
@BypassInterceptors

Disables Seam all interceptors on a particular component or method of a component.

@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

Specifies that a conversation scope component is conversational, meaning that no method of the component may be called unless a long-running conversation is active.

@PerNestedConversation
@PerNestedConversation

Limits the scope of a CONVERSATION-scoped component to just the parent conversation in which it was instantiated. The component instance will not be visible to nested child conversations, which will get their own instance.

Warning: this is ill-defined, since it implies that a component will be visible for some part of a request cycle, and invisible after that. It is not recommended that applications use this feature!

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

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.

@Scope(SESSION) @Startup

Specifies that a session scope component is started immediately at session creation time.

@Install
@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.bpm.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 (in ascending order):

@Synchronized
@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
@ReadOnly

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

@AutoCreate
@AutoCreate

Specifies that a component will be automatically created, even if the client does not specify create=true.

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.

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

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.

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

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

  • flushMode — set the flush mode of any Seam-managed Hibernate sessions or JPA persistence contexts that are created during this conversation.

  • pageflow — a process definition name of a jBPM process definition deployed via org.jboss.seam.bpm.jbpm.pageflowDefinitions.

@End
@End

Specifies that a long-running conversation ends when this method returns a non-null outcome without exception.

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

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

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

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

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

@Transition
@Transition("cancel")

Marks a method as signalling a transition in the current jBPM process instance whenever the method returns a non-null result.

Seam provides an annotation that lets you force a rollback of the JTA transaction for certain action listener outcomes.

These annotations are mostly useful for JavaBean Seam components. If you use EJB 3.0 components, you should use the standard Java EE5 annotation.

These annotations let you specify how Seam should handle an exception that propagates out of a Seam component.

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.

The following annotations are used to declare an asynchronous method, for example:

@Asynchronous public void scheduleAlert(Alert alert, @Expiration Date date) { ... }
@Asynchronous public Timer scheduleAlerts(Alert alert, 

   @Expiration Date date, 
   @IntervalDuration long interval) { ... }

The following annotations make working with JSF easier.

The following annotations make it easy to implement clickable lists backed by a stateful session bean. They appear on attributes.

@DataModel
@DataModel("variableName")

Outjects a property 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
@DataModelSelection

Injects the selected value from the JSF DataModel (this is the element of the underlying collection, or the map value). If only one @DataModel attribute is defined for a component, the selected value from that DataModel will be injected. Otherwise, the component name of each @DataModel must be specified in the value attribute for each @DataModelSelection.

If PAGE scope is specified on the associated @DataModel, then, in addition to the DataModel Selection being injected, the associated DataModel will also be injected. In this case, if the property annotated with @DataModel is a getter method, then a setter method for the property must also be part of the Business API of the containing Seam 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). If only one @DataModel attribute is defined for a component, the selected value from that DataModel will be injected. Otherwise, the component name of each @DataModel must be specified in the value attribute for each @DataModelSelectionIndex.

These meta-annotations make it possible to implement similar functionality to @DataModel and @DataModelSelection for other datastructures apart from lists.

This annotation provides a mechanism for declaring information about a set of components that are packaged together. It can be applied to any Java package.

These annotations allow you to integrate your Seam components with the servlet container.