Chapter 11. Built-in Seam components - JBoss Seam 1.0.1 正式版英文参考手册
This chapter describes Seam's built-in components, and their configuration properties.
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;
- eventContext
Manager component for the event context object
- pageContext
Manager component for the page context object
- conversationContext
Manager component for the conversation context object
- sessionContext
Manager component for the session context object
- applicationContext
Manager component for the appication context object
- businessProcessContext
Manager component for the business process context object
- statelessContext
Manager component for the stateless context object
- facesContext
Manager component for the FacesContext context object (not a true Seam context)
All of these components are always installed.
These components are merely useful.
- 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.
- redirect
A convenient API for performing redirects with paramaters (this is especially useful for bookmarkable search results screens).
redirect.viewId — the JSF view id to redirect to.
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().
- httpError
A convenient API for sending HTTP errors.
- events
An API for raising events that can be observed via @Observer methods, or method bindings in WEB-INF/events.xml.
raiseEvent(String type) — raise an event of a particular type and distribute to all observers.
addListener(String type, String methodBinding) — add an observer for a particular event type.
- 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.
- pojoCache
Manager component for a JBoss Cache PojoCache instance.
pojoCache.cfgResourceName — the name of the configuration file. Default to treecache.xml.
- uiComponent
Allows access to a JSF UIComponent by its id from the EL. For example, we can write @In("#{uiComponent['myForm:address'].value}").
All of these components are always installed.
The next group of components make it easy to build internationalized user interfaces using Seam.
- locale
The Seam locale. The locale is session scoped.
- resourceBundle
The Seam resource bundle. The resource bundle is session scoped.
resourceBundle.bundleName — the name of the bundle. Default to messages.
- 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.
- messages
A map containing internationalized messages rendered from message templates defined in the Seam resource bundle.
All of these components are always installed.
The next group of components allow control of conversations by the application or user interface.
- conversation
API for application control of attributes of the current Seam 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).
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.
- conversationList
Manager component for the conversation list.
- conversationStack
Manager component for the conversation stack (breadcrumbs).
- switcher
The conversation switcher.
All of these components are always installed.
These components are for use with jBPM.
- 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.
- 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.
- taskInstance
Manager component for the jBPM TaskInstance.
- processInstance
Manager component for the jBPM ProcessInstance.
- jbpmContext
Manager component for an event-scoped JbpmContext.
- taskInstanceList
Manager component for the jBPM task list.
- pooledTaskInstanceList
Manager component for the jBPM pooled task list.
- taskInstanceListForType
Manager component for the jBPM task lists.
- pooledTask
Action handler for pooled task assignment.
All of these components are installed whenever the component org.jboss.seam.core.jbpm is installed.
These components relate to web-tier security.
- userPrincipal
Manager component for the current user Principal.
- 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).
- queueSession
Manager component for a JMS QueueSession .
- topicSession
Manager component for a JMS TopicSession .
These components provide critical platform infrastructure. You can install a component by including its class name in the org.jboss.seam.core.init.componentClasses configuration property.
- org.jboss.seam.core.init
Initialization settings for Seam. Always installed.
org.jboss.seam.core.init.componentClasses — a list of class names of Seam components to be installed. (The class name, not the component name!)
org.jboss.seam.core.init.managedPersistenceContexts — a list of component names of Seam managed persistence contexts to be installed.
org.jboss.seam.core.init.managedSessions — a list of component names of Seam managed Hibernate sessions to be installed.
org.jboss.seam.core.init.jbpmSessionFactoryName — the name of the jBPM session factory
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.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.process
Internal component for Seam process management. Installed whenever org.jboss.seam.core.jbpm is installed.
- org.jboss.seam.core.pageflow
Internal component for Seam pageflow management. Installed whenever org.jboss.seam.core.jbpm is installed.
- org.jboss.seam.core.pages
Internal component for Seam workspace management. Always installed.
- org.jboss.seam.core.ejb
Bootstraps the JBoss Embeddable EJB3 container. Install as class org.jboss.seam.core.Ejb. This is useful when using Seam with EJB components outside the context of a Java EE 5 application server.
The basic Embedded EJB configuration is defined in jboss-embedded-beans.xml. Additional microcontainer configuration (for example, extra datasources) may be specified by jboss-beans.xml or META-INF/jboss-beans.xml in the classpath.
- org.jboss.seam.core.microcontainer
Bootstraps the JBoss microcontainer. Install as class org.jboss.seam.core.Microcontainer. This is useful when using Seam with Hibernate and no EJB components outside the context of a Java EE application server. The microcontainer can provide a partial EE environment with JNDI, JTA, a JCA datasource and Hibernate.
The microcontainer configuration may be specified by jboss-beans.xml or META-INF/jboss-beans.xml in the classpath.
- org.jboss.seam.core.hibernate
Bootstraps a Hibernate SessionFactory. Install as class org.jboss.seam.core.Hibernate. This is most useful when using Seam with Hibernate inside a Java EE application server.
org.jboss.seam.core.hibernate.cfgResourceName — the path to the configuration file. Default to hibernate.cfg.xml.
See the API JavaDoc for further configuration properties.
- org.jboss.seam.core.jbpm
Bootstraps a JbpmConfiguration. Install as class org.jboss.seam.core.Jbpm.
org.jboss.seam.core.jbpm.processDefinitions — a list of resource names of jPDL files to be used for orchestration of business processes.
org.jboss.seam.core.jbpm.pageflowDefinitions — a list of resource names of jPDL files to be used for orchestration of conversation page flows.
- 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.debug.introspector
Support for the Seam Debug Page.
- org.jboss.seam.debug.contexts
Support for the Seam Debug Page.
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.core.ManagedPersistenceContext">
<property name="persistenceUnitJndiName">java:/comp/emf/bookingPersistence</property>
</component>
<component name="userDatabase"
class="org.jboss.seam.core.ManagedPersistenceContext">
<property name="persistenceUnitJndiName">java:/comp/emf/userPersistence</property>
</component>The Seam component names are bookingDatabase and userDatabase.
- <managedPersistenceContext>
Manager component for a conversation scoped managed EntityManager with an extended persistence context. Installed via org.jboss.seam.core.init.managedPersistenceContexts.
<managedPersistenceContext>.persistenceUnitJndiName — the JNDI name of the entity manager factory, default to java:/<managedPersistenceContext>.
- <managedSession>
Manager component for a conversation scoped managed Hibernate Session. Installed via org.jboss.seam.core.init.managedSessions.
<managedSession>.sessionFactoryJndiName — the JNDI name of the session factory, default to java:/<managedSession>.
- <managedQueueSender>
Manager component for an event scoped managed JMS QueueSender. Installed via org.jboss.seam.core.init.managedQueueSenders.
<managedQueueSender>.queueJndiName — the JNDI name of the JMS queue.
- <managedTopicPublisher>
Manager component for an event scoped managed JMS TopicPublisher. Installed via org.jboss.seam.core.init.managedTopicPublishers.
<managedTopicPublisher>.topicJndiName — the JNDI name of the JMS topic.