Seam FrameworkCommunity Documentation
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.
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.
The following set of components are provided to supplement JSF.
org.jboss.seam.faces.dateConverter
Provides a default JSF converter for properties of type
java.util.Date.
This converter is automatically registered with JSF. It is provided to save a developer from having to specify a DateTimeConverter on an input field or page parameter. By default, it assumes the type to be a date (as opposed to a time or date plus time) and uses the short input style adjusted to the Locale of the user. For Locale.US, the input pattern is mm/DD/yy. However, to comply with Y2K, the year is changed from two digits to four (e.g., mm/DD/yyyy).
It's possible to override the input pattern globally using component configuration. Consult the JavaDoc for this class to see examples.
org.jboss.seam.faces.facesMessagesAllows 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.redirectA 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.httpErrorA convenient API for sending HTTP errors.
org.jboss.seam.ui.renderStampStoreA component (session-scoped by default) responsible for maintaining a collection of render stamps. A render stamp is an indicator as to whether a form which was rendered has been submitted. This store is useful when the client-side state saving method of JSF is being used because it puts the determination of whether a form has been posted in the control of the server rather than in the component tree which is maintained on the client.
To unbind this check from the session (which is one of the main design goals of client-side state saving) an implementation must be provided that stores the render stamps in the application (valid as long as the application is running) or the database (valid across server restarts).
maxSize — The maximum number of stamps
to be kept in the store. Default: 100
These components are installed when the class javax.faces.context.FacesContext
is available on the classpath.
These components are merely useful.
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.interpolatorAn 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.expressionsAn 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.
The next group of components make it easy to build internationalized user interfaces using Seam.
org.jboss.seam.core.localeThe Seam locale.
org.jboss.seam.international.timezoneThe Seam timezone. The timezone is session scoped.
org.jboss.seam.core.resourceBundleThe 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.resourceLoaderThe 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.localeSelectorSupports 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.timezoneSelectorSupports 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.messagesA map containing internationalized messages rendered from message templates defined in the Seam resource bundle.
org.jboss.seam.theme.themeSelectorSupports 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.themeA map containing theme entries.
All of these components are always installed.
The next group of components allow control of conversations by the application or user interface.
org.jboss.seam.core.conversationAPI 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.conversationListManager component for the conversation list.
org.jboss.seam.core.conversationStackManager component for the conversation stack (breadcrumbs).
org.jboss.seam.faces.switcherThe conversation switcher.
All of these components are always installed.
These components are for use with jBPM.
org.jboss.seam.pageflow.pageflowAPI 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.actorAPI 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.transitionAPI 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.businessProcessAPI 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.taskInstanceListManager component for the jBPM task list.
org.jboss.seam.bpm.pooledTaskInstanceListManager component for the jBPM pooled task list.
org.jboss.seam.bpm.taskInstanceListForTypeManager component for the jBPM task lists.
org.jboss.seam.bpm.pooledTaskAction handler for pooled task assignment.
org.jboss.seam.bpm.processInstanceFinderManager for the process instance task list.
org.jboss.seam.bpm.processInstanceListThe process instance task list.
All of these components are installed whenever the component
org.jboss.seam.bpm.jbpm is installed.
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']}"/>.
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 .
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.
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.initInitialization 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. This should be set to false when in production. You may see
errors if the system is placed under any load and debug is enabled.
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.managerInternal 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.core.manager.defaultFlushMode —
set the flush mode set by default on any Seam Managed Persistence Context.
By default AUTO.
org.jboss.seam.navigation.pagesInternal 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.conversationEntriesInternal session-scoped component recording the active long-running conversations between requests.
org.jboss.seam.faces.facesPageInternal page-scoped component recording the conversation context associated with a page.
org.jboss.seam.persistence.persistenceContextsInternal component recording the persistence contexts which were used in the current conversation.
org.jboss.seam.jms.queueConnection
Manages a JMS QueueConnection. Installed whenever
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 TopicPublisher is installed.
org.jboss.seam.jms.topicConnection.topicConnectionFactoryJndiName
— the JNDI name of a JMS TopicConnectionFactory. Default
to UIL2ConnectionFactory
org.jboss.seam.persistence.persistenceProviderAbstraction layer for non-standardized features of JPA provider.
org.jboss.seam.core.validators
Caches instances of Hibernate Validator ClassValidator.
org.jboss.seam.faces.validationAllows the application to determine whether validation failed or was successful.
org.jboss.seam.debug.introspectorSupport for the Seam Debug Page.
org.jboss.seam.debug.contextsSupport for the Seam Debug Page.
org.jboss.seam.exception.exceptionsInternal component for exception handling.
org.jboss.seam.transaction.transactionAPI for controlling transactions and abstracting the underlying transaction management implementation behind a JTA-compatible interface.
org.jboss.seam.faces.safeActionsDecides if an action expression in an incoming URL is safe. This is done by checking that the action expression exists in the view.
These components don't fit into
org.jboss.seam.async.dispatcherDispatcher stateless session bean for asynchronous methods.
org.jboss.seam.core.imageImage manipulation and interrogation.
org.jboss.seam.core.pojoCacheManager component for a PojoCache instance.
org.jboss.seam.core.uiComponentManages a map of UIComponents keyed by component id.
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.
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>.
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.
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>.
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.
org.jboss.seam.jms.ManagedQueueSender
Manager component for an event scoped managed JMS QueueSender.
<managedQueueSender>.queueJndiName — the JNDI name of the JMS queue.
org.jboss.seam.jms.ManagedTopicPublisher
Manager component for an event scoped managed JMS TopicPublisher.
<managedTopicPublisher>.topicJndiName — the JNDI name of the JMS topic.
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.
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.
org.jboss.seam.framework.EntityHomeorg.jboss.seam.framework.HibernateEntityHomeorg.jboss.seam.framework.EntityQueryorg.jboss.seam.framework.HibernateEntityQuery