Chapter 29. Seam annotations

Seam uses annotations to achieve a declarative style of programming. Most annotations are defined by the Enterprise JavaBean 3.0 (EJB3) specification, and the annotations used in data validation are defined by the Hibernate Validator package. However, Seam also defines its own set of annotations, which are described in this chapter.
All of these annotations are defined in the org.jboss.seam.annotations package.

29.1. Annotations for component definition

This group of annotations is used to 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, or STATELESS.
When no scope is explicitly specified, the default varies with 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 context variables. The @Name and @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 you to specify multiple additional roles.
@BypassInterceptors 
@BypassInterceptors
Disables all Seam interceptors on a particular component or component method.
@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 the parent conversation in which it was instantiated. The component instance will not be visible to nested child conversations, which will operate within their own instances.

Warning

This is not a recommended application feature. It implies that a component will be visible only for a specific part of a request cycle.
@Startup 
@Scope(APPLICATION) @Startup(depends="org.jboss.seam.bpm.jbpm")
Specifies that an application-scoped component will start immediately at initialization time. This is used for built-in components that bootstrap critical infrastructure, such as JNDI, datasources, etc. 
@Scope(SESSION) @Startup
Specifies that a session-scoped component will start immediately at session creation time.
  • depends — specifies that the named components must be started first, if they are installed.
@Install 
@Install(false)
Specifies that a component should not be installed by default. (If you do not specify this annotation, the component will 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 a required dependency does not have a single well-known name. 
@Install(classDependencies="org.hibernate.Session")
Specifies that a component should only be installed if the named class is included on 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.