Seam FrameworkCommunity Documentation
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 Bean Validation standard. 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.
@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.
depends — specifies that the
named components must be started first, if they are
installed.
@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 installed 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 precedence values are (in ascending order):
BUILT_IN — Precedence of all
built-in Seam components
FRAMEWORK — Precedence to use
for components of frameworks which extend Seam
APPLICATION — Precedence of
application components (the default precedence)
DEPLOYMENT — Precedence to use
for components which override application components in
a particular deployment
MOCK — Precedence for mock
objects used in testing
@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.
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 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.
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; a Seam component 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; 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.
@Factory
@Factory("processInstance") public void createProcessInstance() { ... }
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) public ProcessInstance createProcessInstance() { ... }
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).
value — specifies the name of
the context variable. If the method is a getter method,
default to the JavaBeans property name.
scope — specifies the scope
that Seam should bind the returned value to. Only
meaningful for factory methods which return a value.
autoCreate — specifies that
this factory method should be automatically called
whenever the variable is asked for, even if
@In does not specify
create=true.
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 destroy methods are only supported for JavaBeans and stateful session beans.
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.
@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.
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.
beforeRedirect — by default,
the conversation will not actually be destroyed until
after any redirect has occurred. Setting
beforeRedirect=true specifies that
the conversation should be destroyed at the end of
the current request, and that the redirect will be
processed in a new temporary conversation context.
root — by default,
ending a nested conversation simply pops the conversation
stack and resumes the outer conversation. Setting
root=true specifies that the root
conversation should be destroyed which effectively destroys
the entire conversation stack. If the conversation is not
nested, the current conversation is simply ended.
@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.
The jBPM TaskInstance will be
available in a request context variable named
taskInstance. The jBPM
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.
flushMode — set the flush
mode of any Seam-managed Hibernate sessions or JPA
persistence contexts that are created during this
conversation.
@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.
The jBPM org.jbpm.taskmgmt.exe.TaskInstance
will be available in a request context variable named
taskInstance. The jBPM
org.jbpm.graph.exe.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.
flushMode — set the flush
mode of any Seam-managed Hibernate sessions or JPA
persistence contexts that are created during this
conversation.
@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.
transition — the name of the
jBPM transition to be triggered when ending the task.
Defaults to the default transition.
beforeRedirect — by default,
the conversation will not actually be destroyed until
after any redirect has occurred. Setting
beforeRedirect=true specifies that
the conversation should be destroyed at the end of
the current request, and that the redirect will be
processed in a new temporary conversation context.
@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.bpm.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".
@Transition
@Transition("cancel")
Marks a method as signaling 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.
@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.
Do not use this annotation on EJB 3.0 components,
use @TransactionAttribute!
@ApplicationException
@ApplicationException
Synonym for javax.ejb.ApplicationException, for use in a pre Java EE 5 environment. Applied to an exception to denote that it is an application exception and should be reported to the client directly(i.e., unwrapped).
Do not use this annotation on EJB 3.0 components,
use @javax.ejb.ApplicationException
instead.
rollback — by default
false, if true
this exception should set the transaction to rollback
only
end — by default
false, if true this
exception should end the current long-running
conversation
@Interceptors
@Interceptors({DVDInterceptor, CDInterceptor})
Synonym for javax.interceptors.Interceptors, for use in a pre Java EE 5 environment. Note that this may only be used as a meta-annotation. Declares an ordered list of interceptors for a class or method.
Do not use this annotations on EJB 3.0 components,
use @javax.interceptor.Interceptors
instead.
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.
@Redirect
@Redirect(viewId="error.jsp")
Specifies that the annotated exception causes a browser redirect to a specified view id.
viewId — specifies the JSF view
id to redirect to. You can use EL here.
message — a message to be
displayed, default to the exception message.
end — specifies that the
long-running conversation should end, default to
false.
@HttpError
@HttpError(errorCode=404)
Specifies that the annotated exception causes a HTTP error to be sent.
errorCode — the HTTP error
code, default to 500.
message — a message to be sent
with the HTTP error, default to the exception message.
end — specifies that the
long-running conversation should end, default to
false.
Seam Remoting requires that the local interface of a session bean be annotated with the following annotation:
@WebRemote
@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 Chapter 26, Remoting chapter for more
details).
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.
@Interceptor
@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.
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) { ... }
@Asynchronous
@Asynchronous
Specifies that the method call is processed asynchronously.
@Duration
@Duration
Specifies that a parameter of the asynchronous call is the duration before the call is processed (or first processed for recurring calls).
@Expiration
@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
@IntervalDuration
Specifies that an asynchronous method call recurs, and that the annotation parameter is duration between recurrences.
The following annotations make working with JSF easier.
@Converter
Allows a Seam component to act as a JSF converter. The
annotated class must be a Seam component, and must
implement javax.faces.convert.Converter.
id — the JSF converter id.
Defaults to the component name.
forClass — if specified,
register this component as the default converter for
a type.
@Validator
Allows a Seam component to act as a JSF validator. The
annotated class must be a Seam component, and must
implement javax.faces.validator.Validator.
id — the JSF validator id.
Defaults to the component name.
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.
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). 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.
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). 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.
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.
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.
@Namespace
@Namespace(value="http://jboss.org/schema/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.org/schema/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 init that is
associated with this namespace would be understood to actually
refer to a component named
org.jboss.seam.core.init.
These annotations allow you to integrate your Seam components with the servlet container.
@Filter
Use the Seam component (which implements
javax.servlet.Filter) annotated with
@Filter as a servlet filter. It will be
executed by Seam's master filter.
@Filter(around={"seamComponent", "otherSeamComponent"})
Specifies that this filter is positioned higher in the stack than the given filters.
@Filter(within={"seamComponent", "otherSeamComponent"})
Specifies that this filter is positioned deeper in the stack than the given filters.