Chapter 28. Built-in Seam components

This chapter describes Seam's built-in components, and their configuration properties. The built-in components will be created even if they are not listed in your components.xml file, but if you need to override default properties or specify more than one component of a certain type, components.xml is used.

Note that you can replace any of the built in components with your own implementations simply by specifying the name of one of the built in components on your own class using @Name.

Note also that even though all the built in components use a qualified name, most of them are aliased to unqualified names by default. These aliases specify auto-create="true", so you do not need to use create=true when injecting built-in components by their unqualified name.

28.1. Context injection components

The first set of built in components exist purely to support injection of various contextual objects. For example, the following component instance variable would have the Seam session context object injected:

@In private Context sessionContext;
org.jboss.seam.core.contexts

Component that provides access to Seam Context objects, for example org.jboss.seam.core.contexts.sessionContext['user'].

org.jboss.seam.faces.facesContext

Manager component for the FacesContext context object (not a true Seam context)

All of these components are always installed.

28.2. Utility components

These components are merely useful.

org.jboss.seam.faces.facesMessages

Allows faces success messages to propagate across a browser redirect.

  • add(FacesMessage facesMessage) — add a faces message, which will be displayed during the next render response phase that occurs in the current conversation.

  • add(String messageTemplate) — add a faces message, rendered from the given message template which may contain EL expressions.

  • add(Severity severity, String messageTemplate) — add a faces message, rendered from the given message template which may contain EL expressions.

  • addFromResourceBundle(String key) — add a faces message, rendered from a message template defined in the Seam resource bundle which may contain EL expressions.

  • addFromResourceBundle(Severity severity, String key) — add a faces message, rendered from a message template defined in the Seam resource bundle which may contain EL expressions.

  • clear() — clear all messages.

org.jboss.seam.faces.redirect

A convenient API for performing redirects with parameters (this is especially useful for bookmarkable search results screens).

  • redirect.viewId — the JSF view id to redirect to.

  • redirect.conversationPropagationEnabled — determines whether the conversation will propagate across the redirect.

  • redirect.parameters — a map of request parameter name to value, to be passed in the redirect request.

  • execute() — perform the redirect immediately.

  • captureCurrentRequest() — stores the view id and request parameters of the current GET request (in the conversation context), for later use by calling execute().

org.jboss.seam.faces.httpError

A convenient API for sending HTTP errors.

org.jboss.seam.core.events

An API for raising events that can be observed via @Observer methods, or method bindings in components.xml.

  • raiseEvent(String type) — raise an event of a particular type and distribute to all observers.

  • raiseAsynchronousEvent(String type) — raise an event to be processed asynchronously by the EJB3 timer service.

  • raiseTimedEvent(String type, ....) — schedule an event to be processed asynchronously by the EJB3 timer service.

  • addListener(String type, String methodBinding) — add an observer for a particular event type.

org.jboss.seam.core.interpolator

An API for interpolating the values of JSF EL expressions in Strings.

  • interpolate(String template) — scan the template for JSF EL expressions of the form #{...} and replace them with their evaluated values.

org.jboss.seam.core.expressions

An API for creating value and method bindings.

  • createValueBinding(String expression) — create a value binding object.

  • createMethodBinding(String expression) — create a method binding object.

org.jboss.seam.core.pojoCache

Manager component for a JBoss Cache PojoCache instance.

  • pojoCache.cfgResourceName — the name of the configuration file. Default to treecache.xml.

All of these components are always installed.

28.3. Components for internationalization and themes

The next group of components make it easy to build internationalized user interfaces using Seam.

org.jboss.seam.core.locale

The Seam locale.

org.jboss.seam.international.timezone

The Seam timezone. The timezone is session scoped.

org.jboss.seam.core.resourceBundle

The Seam resource bundle. The resource bundle is stateless. The Seam resource bundle performs a depth-first search for keys in a list of Java resource bundles.

org.jboss.seam.core.resourceLoader

The resource loader provides access to application resources and resource bundles.

  • resourceLoader.bundleNames — the names of the Java resource bundles to search when the Seam resource bundle is used. Default to messages.

org.jboss.seam.international.localeSelector

Supports selection of the locale either at configuration time, or by the user at runtime.

  • select() — select the specified locale.

  • localeSelector.locale — the actual java.util.Locale.

  • localeSelector.localeString — the stringified representation of the locale.

  • localeSelector.language — the language for the specified locale.

  • localeSelector.country — the country for the specified locale.

  • localeSelector.variant — the variant for the specified locale.

  • localeSelector.supportedLocales — a list of SelectItems representing the supported locales listed in jsf-config.xml.

  • localeSelector.cookieEnabled — specifies that the locale selection should be persisted via a cookie.

org.jboss.seam.international.timezoneSelector

Supports selection of the timezone either at configuration time, or by the user at runtime.

  • select() — select the specified locale.

  • timezoneSelector.timezone — the actual java.util.TimeZone.

  • timezoneSelector.timeZoneId — the stringified representation of the timezone.

  • timezoneSelector.cookieEnabled — specifies that the timezone selection should be persisted via a cookie.

org.jboss.seam.international.messages

A map containing internationalized messages rendered from message templates defined in the Seam resource bundle.

org.jboss.seam.theme.themeSelector

Supports selection of the theme either at configuration time, or by the user at runtime.

  • select() — select the specified theme.

  • theme.availableThemes — the list of defined themes.

  • themeSelector.theme — the selected theme.

  • themeSelector.themes — a list of SelectItems representing the defined themes.

  • themeSelector.cookieEnabled — specifies that the theme selection should be persisted via a cookie.

org.jboss.seam.theme.theme

A map containing theme entries.

All of these components are always installed.

28.4. Components for controlling conversations

The next group of components allow control of conversations by the application or user interface.

org.jboss.seam.core.conversation

API for application control of attributes of the current Seam conversation.

  • getId() — returns the current conversation id

  • isNested() — is the current conversation a nested conversation?

  • isLongRunning() — is the current conversation a long-running conversation?

  • getId() — returns the current conversation id

  • getParentId() — returns the conversation id of the parent conversation

  • getRootId() — returns the conversation id of the root conversation

  • setTimeout(int timeout) — sets the timeout for the current conversation

  • setViewId(String outcome) — sets the view id to be used when switching back to the current conversation from the conversation switcher, conversation list, or breadcrumbs.

  • setDescription(String description) — sets the description of the current conversation to be displayed in the conversation switcher, conversation list, or breadcrumbs.

  • redirect() — redirect to the last well-defined view id for this conversation (useful after login challenges).

  • leave() — exit the scope of this conversation, without actually ending the conversation.

  • begin() — begin a long-running conversation (equivalent to @Begin).

  • beginPageflow(String pageflowName) — begin a long-running conversation with a pageflow (equivalent to @Begin(pageflow="...")).

  • end() — end a long-running conversation (equivalent to @End).

  • pop() — pop the conversation stack, returning to the parent conversation.

  • root() — return to the root conversation of the conversation stack.

  • changeFlushMode(FlushModeType flushMode) — change the flush mode of the conversation.

org.jboss.seam.core.conversationList

Manager component for the conversation list.

org.jboss.seam.core.conversationStack

Manager component for the conversation stack (breadcrumbs).

org.jboss.seam.faces.switcher

The conversation switcher.

All of these components are always installed.

28.5. jBPM-related components

These components are for use with jBPM.

org.jboss.seam.pageflow.pageflow

API control of Seam pageflows.

  • isInProcess() — returns true if there is currently a pageflow in process

  • getProcessInstance() — returns jBPM ProcessInstance for the current pageflow

  • begin(String pageflowName) — begin a pageflow in the context of the current conversation

  • reposition(String nodeName) — reposition the current pageflow to a particular node

org.jboss.seam.bpm.actor

API for application control of attributes of the jBPM actor associated with the current session.

  • setId(String actorId) — sets the jBPM actor id of the current user.

  • getGroupActorIds() — returns a Set to which jBPM actor ids for the current users groups may be added.

org.jboss.seam.bpm.transition

API for application control of the jBPM transition for the current task.

  • setName(String transitionName) — sets the jBPM transition name to be used when the current task is ended via @EndTask.

org.jboss.seam.bpm.businessProcess

API for programmatic control of the association between the conversation and business process.

  • businessProcess.taskId — the id of the task associated with the current conversation.

  • businessProcess.processId — the id of the process associated with the current conversation.

  • businessProcess.hasCurrentTask() — is a task instance associated with the current conversation?

  • businessProcess.hasCurrentProcess() — is a process instance associated with the current conversation.

  • createProcess(String name) — create an instance of the named process definition and associate it with the current conversation.

  • startTask() — start the task associated with the current conversation.

  • endTask(String transitionName) — end the task associated with the current conversation.

  • resumeTask(Long id) — associate the task with the given id with the current conversation.

  • resumeProcess(Long id) — associate the process with the given id with the current conversation.

  • transition(String transitionName) — trigger the transition.

org.jboss.seam.bpm.taskInstance

Manager component for the jBPM TaskInstance.

org.jboss.seam.bpm.processInstance

Manager component for the jBPM ProcessInstance.

org.jboss.seam.bpm.jbpmContext

Manager component for an event-scoped JbpmContext.

org.jboss.seam.bpm.taskInstanceList

Manager component for the jBPM task list.

org.jboss.seam.bpm.pooledTaskInstanceList

Manager component for the jBPM pooled task list.

org.jboss.seam.bpm.taskInstanceListForType

Manager component for the jBPM task lists.

org.jboss.seam.bpm.pooledTask

Action handler for pooled task assignment.

org.jboss.seam.bpm.processInstanceFinder

Manager for the process instance task list.

org.jboss.seam.bpm.processInstanceList

The process instance task list.

All of these components are installed whenever the component org.jboss.seam.bpm.jbpm is installed.

28.6. Security-related components

These components relate to web-tier security.

org.jboss.seam.web.userPrincipal

Manager component for the current user Principal.

org.jboss.seam.web.isUserInRole

Allows JSF pages to choose to render a control, depending upon the roles available to the current principal. <h:commandButton value="edit" rendered="#{isUserInRole['admin']}"/>.

28.7. JMS-related components

These components are for use with managed TopicPublishers and QueueSenders (see below).

org.jboss.seam.jms.queueSession

Manager component for a JMS QueueSession .

org.jboss.seam.jms.topicSession

Manager component for a JMS TopicSession .

28.8. Mail-related components

These components are for use with Seam's Email support

org.jboss.seam.mail.mailSession

Manager component for a JavaMail Session. The session can be either looked up in the JNDI context (by setting the sessionJndiName property) or it can created from the configuration options in which case the host is mandatory.

  • org.jboss.seam.mail.mailSession.host — the hostname of the SMTP server to use

  • org.jboss.seam.mail.mailSession.port — the port of the SMTP server to use

  • org.jboss.seam.mail.mailSession.username — the username to use to connect to the SMTP server.

  • org.jboss.seam.mail.mailSession.password — the password to use to connect to the SMTP server

  • org.jboss.seam.mail.mailSession.debug — enable JavaMail debugging (very verbose)

  • org.jboss.seam.mail.mailSession.ssl — enable SSL connection to SMTP (will default to port 465)

    org.jboss.seam.mail.mailSession.tls — by default true, enable TLS support in the mail session

  • org.jboss.seam.mail.mailSession.sessionJndiName — name under which a javax.mail.Session is bound to JNDI. If supplied, all other properties will be ignored.

28.9. Infrastructural components

These components provide critical platform infrastructure. You can install a component which isn't installed by default by setting install="true" on the component in components.xml.

org.jboss.seam.core.init

Initialization settings for Seam. Always installed.

  • org.jboss.seam.core.init.jndiPattern — the JNDI pattern used for looking up session beans

  • org.jboss.seam.core.init.debug — enable Seam debug mode

  • org.jboss.seam.core.init.clientSideConversations — if set to true, Seam will save conversation context variables in the client instead of in the HttpSession.

  • org.jboss.seam.core.init.userTransactionName — the JNDI name to use when looking up the JTA UserTransaction object.

org.jboss.seam.core.manager

Internal component for Seam page and conversation context management. Always installed.

  • org.jboss.seam.core.manager.conversationTimeout — the conversation context timeout in milliseconds.

  • org.jboss.seam.core.manager.concurrentRequestTimeout — maximum wait time for a thread attempting to gain a lock on the long-running conversation context.

  • org.jboss.seam.core.manager.conversationIdParameter — the request parameter used to propagate the conversation id, default to conversationId.

  • org.jboss.seam.core.manager.conversationIsLongRunningParameter — the request parameter used to propagate information about whether the conversation is long-running, default to conversationIsLongRunning.

org.jboss.seam.navigation.pages

Internal component for Seam workspace management. Always installed.

  • org.jboss.seam.navigation.pages.noConversationViewId — global setting for the view id to redirect to when a conversation entry is not found on the server side.

  • org.jboss.seam.navigation.pages.loginViewId — global setting for the view id to redirect to when an unauthenticated user tries to access a protected view.

  • org.jboss.seam.navigation.pages.httpPort — global setting for the port to use when the http scheme is requested.

  • org.jboss.seam.navigation.pages.httpsPort — global setting for the port to use when the https scheme is requested.

  • org.jboss.seam.navigation.pages.resources — a list of resources to search for pages.xml style resources. Defaults to WEB-INF/pages.xml.

org.jboss.seam.bpm.jbpm

Bootstraps a JbpmConfiguration. Install as class org.jboss.seam.bpm.Jbpm.

  • org.jboss.seam.bpm.jbpm.processDefinitions — a list of resource names of jPDL files to be used for orchestration of business processes.

  • org.jboss.seam.bpm.jbpm.pageflowDefinitions — a list of resource names of jPDL files to be used for orchestration of conversation page flows.

org.jboss.seam.core.conversationEntries

Internal session-scoped component recording the active long-running conversations between requests.

org.jboss.seam.faces.facesPage

Internal page-scoped component recording the conversation context associated with a page.

org.jboss.seam.persistence.persistenceContexts

Internal component recording the persistence contexts which were used in the current conversation.

org.jboss.seam.jms.queueConnection

Manages a JMS QueueConnection. Installed whenever managed managed QueueSender is installed.

  • org.jboss.seam.jms.queueConnection.queueConnectionFactoryJndiName — the JNDI name of a JMS QueueConnectionFactory. Default to UIL2ConnectionFactory

org.jboss.seam.jms.topicConnection

Manages a JMS TopicConnection. Installed whenever managed managed TopicPublisher is installed.

  • org.jboss.seam.jms.topicConnection.topicConnectionFactoryJndiName — the JNDI name of a JMS TopicConnectionFactory. Default to UIL2ConnectionFactory

org.jboss.seam.persistence.persistenceProvider

Abstraction layer for non-standardized features of JPA provider.

org.jboss.seam.core.validators

Caches instances of Hibernate Validator ClassValidator.

org.jboss.seam.faces.validation

Allows the application to determine whether validation failed or was successful.

org.jboss.seam.debug.introspector

Support for the Seam Debug Page.

org.jboss.seam.debug.contexts

Support for the Seam Debug Page.

org.jboss.seam.exception.exceptions

Internal component for exception handling.

org.jboss.seam.transaction.transaction

API for controlling transactions and abstracting the underlying transaction management implementation behind a JTA-compatible interface.

org.jboss.seam.faces.safeActions

Decides if an action expression in an incoming URL is safe. This is done by checking that the action expression exists in the view.

28.10. Miscellaneous components

These components don't fit into

org.jboss.seam.async.dispatcher

Dispatcher stateless session bean for asynchronous methods.

org.jboss.seam.core.image

Image manipulation and interrogation.

org.jboss.seam.core.pojoCache

Manager component for a PojoCache instance.

org.jboss.seam.core.uiComponent

Manages a map of UIComponents keyed by component id.

28.11. Special components

Certain special Seam component classes are installable multiple times under names specified in the Seam configuration. For example, the following lines in components.xml install and configure two Seam components:

<component name="bookingDatabase"
          class="org.jboss.seam.persistence.ManagedPersistenceContext">
    <property name="persistenceUnitJndiName">java:/comp/emf/bookingPersistence</property>
</component>

<component name="userDatabase"
          class="org.jboss.seam.persistence.ManagedPersistenceContext">
    <property name="persistenceUnitJndiName">java:/comp/emf/userPersistence</property>
</component>

The Seam component names are bookingDatabase and userDatabase.

<entityManager>, org.jboss.seam.persistence.ManagedPersistenceContext

Manager component for a conversation scoped managed EntityManager with an extended persistence context.

  • <entityManager>.entityManagerFactory — a value binding expression that evaluates to an instance of EntityManagerFactory.

    <entityManager>.persistenceUnitJndiName — the JNDI name of the entity manager factory, default to java:/<managedPersistenceContext>.

<entityManagerFactory>, org.jboss.seam.persistence.EntityManagerFactory

Manages a JPA EntityManagerFactory. This is most useful when using JPA outside of an EJB 3.0 supporting environment.

  • entityManagerFactory.persistenceUnitName — the name of the persistence unit.

See the API JavaDoc for further configuration properties.

<session>, org.jboss.seam.persistence.ManagedSession

Manager component for a conversation scoped managed Hibernate Session.

  • <session>.sessionFactory — a value binding expression that evaluates to an instance of SessionFactory.

    <session>.sessionFactoryJndiName — the JNDI name of the session factory, default to java:/<managedSession>.

<sessionFactory>, org.jboss.seam.persistence.HibernateSessionFactory

Manages a Hibernate SessionFactory.

  • <sessionFactory>.cfgResourceName — the path to the configuration file. Default to hibernate.cfg.xml.

See the API JavaDoc for further configuration properties.

<managedQueueSender>, org.jboss.seam.jms.ManagedQueueSender

Manager component for an event scoped managed JMS QueueSender.

  • <managedQueueSender>.queueJndiName — the JNDI name of the JMS queue.

<managedTopicPublisher>, org.jboss.seam.jms.ManagedTopicPublisher

Manager component for an event scoped managed JMS TopicPublisher.

  • <managedTopicPublisher>.topicJndiName — the JNDI name of the JMS topic.

<managedWorkingMemory>, org.jboss.seam.drools.ManagedWorkingMemory

Manager component for a conversation scoped managed Drools WorkingMemory.

  • <managedWorkingMemory>.ruleBase — a value expression that evaluates to an instance of RuleBase.

<ruleBase>, org.jboss.seam.drools.RuleBase

Manager component for an application scoped Drools RuleBase. Note that this is not really intended for production usage, since it does not support dynamic installation of new rules.

  • <ruleBase>.ruleFiles — a list of files containing Drools rules.

    <ruleBase>.dslFile — a Drools DSL definition.

<entityHome>, org.jboss.seam.framework.EntityHome
<hibernateEntityHome>, org.jboss.seam.framework.HibernateEntityHome
<entityQuery>, org.jboss.seam.framework.EntityQuery
<hibernateEntityQuery>, org.jboss.seam.framework.HibernateEntityQuery