Chapter 28. 内置Seam组件

这一章节描述了Seam的内置组件和配置属性。即使你的 components.xml 文件没有列出,内部组件仍然会被创立。 但是如果你想覆盖掉默认的属性配置或者对某一类型的组件指定若干不同的组件,components.xml 就会派上用场了。

你可以简单地通过在独立的类里使用 @Name 注解指定内置组件的名字的方式来替代任何一个内置组件。

另外,即使所有的构建组件都使用全名,但他们大部分在缺省情况下都有简化了的别名。 这些别名指定 auto-create="true",所以,当你使用简化名来注入内置组件时,你不需要用 create=true

28.1. 上下文注入组件

第一个内建的组件集存在完全支持不同的上下文对象的注入。例如,下列各项组件实例变量将会注入Seam会话上下文对象:

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

用以获取各种Seam上下文对象,例如 org.jboss.seam.core.contexts.sessionContext['user']

org.jboss.seam.faces.facesContext

FacesContext 的上下文管理组件(不是一个真的Seam上下文)

所有的这些组件通常都已被自动安装。

28.2. 工具组件

这些组件非常有用。

org.jboss.seam.faces.facesMessages

允许faces的成功消息跨越浏览器的重定向。

  • add(FacesMessage facesMessage) — 增加一个faces消息,这将会在当前对话的下一个渲染响应阶段显示出来。

  • add(String messageTemplate) —增加一个faces消息,这个消息从那些可能包含EL表达式的消息模板来渲染。

  • add(Severity severity, String messageTemplate) — 增加一个faces消息,这个消息从那些可能包含EL表达式的消息模板来渲染。

  • addFromResourceBundle(String key) — 增加一个faces消息,这个消息从在Seam资源包中定义的消息模板来渲染。该消息模板可能包含EL表达式。

  • addFromResourceBundle(Severity severity, String key) — 增加一个faces消息,这个消息从在Seam资源包中定义的消息模板来渲染。该消息模板可能包含EL表达式。

  • clear() — 清除所有的消息。

org.jboss.seam.faces.redirect

一个简便的可以实现带参数重定向的API。它对把搜索结果储存作书签特别有用。

  • redirect.viewId — 用于重定向的JSF视图ID。

  • redirect.conversationPropagationEnabled — 确定对话是否会跨越重定向。

  • redirect.parameters — 一个含有请求参数键值的映射表,用来在重定向间传递。

  • execute() — 立即执行重定向。

  • captureCurrentRequest() — 存储视图ID和当前GET请求的请求参数(在对话上下文中),要想访问这些参数需要调用 execute()

org.jboss.seam.faces.httpError

一个简便的发送HTTP错误的API。

org.jboss.seam.core.events

一个用于唤起事件的API。 这些事件可以通过被 @Observer 方法或者绑定 components.xml 的方法观察。

  • raiseEvent(String type) — 唤起一个特殊类型的事件,并分发到所有的观察者。

  • raiseAsynchronousEvent(String type) — 唤起一个事件,该事件可以被EJB3记时服务异步处理。

  • raiseTimedEvent(String type, ....) — 计划一个事件,该事件可以被EJB3记时服务异步处理。

  • addListener(String type, String methodBinding) — 为某一特定事件类型增加一个观察者。

org.jboss.seam.core.interpolator

一个用于替换字符串形式的JSF EL表达式的API。

  • interpolate(String template) — 浏览JSF EL表达式形式 #{...}的模板和取代他们的计算值。

org.jboss.seam.core.expressions

一个用于创造值和方法绑定的API。

  • createValueBinding(String expression) — 创造值绑定对象

  • createMethodBinding(String expression) — 创造方法绑定对象

org.jboss.seam.core.pojoCache

JBoss 缓存PojoCache 实例管理组件

  • pojoCache.cfgResourceName — 配置文件的名字。默认到 treecache.xml

所有这些组件通常都已被自动安装。

28.3. 组件的国际化和主题

这一组的组件,让通过使用Seam来创建国际化用户接口变得更容易。

org.jboss.seam.core.locale

Seam locale(本地化)。

org.jboss.seam.international.timezone

Seam时间区域。时间区域是会话范围。

org.jboss.seam.core.resourceBundle

Seam资源绑定。它在stateless范围。执行深度优先查询,查询键值在一系列的JAVA资源包中。

org.jboss.seam.core.resourceLoader

资源加载器提供对应用资源和资源包的访问。

  • resourceLoader.bundleNames — 被搜索的Java资源包的包名,在Seam资源绑定被使用的情形下,默认到 messages

org.jboss.seam.international.localeSelector

支持locale(本地化)选择,不仅在配置时,也可以在用户运行时。

  • select() — 选择指定的locale。

  • localeSelector.locale — 当前的 java.util.Locale

  • localeSelector.localeString — locale(本地化)字符串化的表达。

  • localeSelector.language — 指定locale语言。

  • localeSelector.country — 指定locale国家。

  • localeSelector.variant — 指定locale变量。

  • localeSelector.supportedLocales — 一个 SelectItems 的列表,表示被支持的locales。它们在 jsf-config.xml 中列出。

  • localeSelector.cookieEnabled — 指定locale(本地)的选择结果必须通过浏览器来保留。

org.jboss.seam.international.timezoneSelector

支持时间区域选择,不仅在配置时,也可以在用户运行时。

  • select() — 选择明确的locale(本地)。

  • timezoneSelector.timezone — 当前的 java.util.TimeZone

  • timezoneSelector.timeZoneId — 时间区域的字符串化表达。

  • timezoneSelector.cookieEnabled — 指明时间区域的选择结果必须通过浏览器来保留。

org.jboss.seam.international.messages

一个包含从消息模板中获取的国际化消息的映射表。消息模板定义在Seam资源包中。

org.jboss.seam.theme.themeSelector

支持主题选择,不仅在配置时,也可以在用户运行时。

  • select() — 选择明确的主题。

  • theme.availableThemes — 一系列的已定义的主题列表。

  • themeSelector.theme — 已选择的主题。

  • themeSelector.themes — 一个SelectItems 的列表,描述了已定义的主题。

  • themeSelector.cookieEnabled — 指明主题的选择结果必须通过浏览器来保留。

org.jboss.seam.theme.theme

一个包含主题实体的映射表。

所有这些组件通常都已被自动安装。

28.4. 控制对话组件

这一组组件,允许通过应用程序或用户界面来控制对话。

org.jboss.seam.core.conversation

用于对当前Seam对话的属性进行应用控制的API。

  • getId() — 返回当前对话的ID

  • isNested() — 当前对话是否嵌套在其它对话中?

  • isLongRunning() — 当前对话是否是长时间运行?

  • getId() — 返回当前对话的ID

  • getParentId() — 返回父对话的对话ID

  • getRootId() — 返回根对话的对话ID

  • setTimeout(int timeout) — 设置当前对话的失效时间

  • setViewId(String outcome) —在通过对话切换器、对话列表或breadcrumbs切换当前对话时,设置视图ID。

  • setDescription(String description) — 设置当前对话的说明。该说明被用来显示在对话切换器、对话列表或breadcrumbs中。

  • redirect() — 重定向到当前对话中最后一个明确定义的视图ID(登录后有用)。

  • leave() — 退出对话的范围,但实际上没有结束这次对话。

  • begin() — 开始长时间运行的对话(等同于@Begin)。

  • beginPageflow(String pageflowName) — 协同页面流,开始一个长时间运行的对话(等同于@Begin(pageflow="..."))。

  • end() — 结束长时间运行的对话(等同于 @End)。

  • pop() — 弹出对话堆栈,返回到父对话。

  • root() — 返回到对话堆栈的根对话。

  • changeFlushMode(FlushModeType flushMode) — 改变对话的刷新模式。

org.jboss.seam.core.conversationList

对话列表的管理组件。

org.jboss.seam.core.conversationStack

对话堆栈(breadcrumbs)的管理组件。

org.jboss.seam.faces.switcher

对话切换器。

所有这些组件通常都已被自动安装。

28.5. 与jBPM相关的组件

这些组件要和jBPM一起使用。

org.jboss.seam.pageflow.pageflow

用于控制Seam页面流的API。

  • IsInProcess()如果在进程中有一个页面流,则返回 true

  • getProcessInstance() — 为当前页面流返回jBPM ProcessInstance (流程实例)

  • begin(String pageflowName) — 在当前对话的上下文中开始一个页面流

  • reposition(String nodeName) — 为当前页面流复位到一个指定的节点

org.jboss.seam.bpm.actor

用于与当前Session相关的jBPM的角色属性的应用控制的API

  • setId(String actorId) — 设置当前用户的jBPM角色标识。

  • getGroupActorIds() — 返回一个更多的当前用户群的jBPM角色标识部分Set

org.jboss.seam.bpm.transition

用于当前任务的jBPM转换的应用控制的API。

  • setName(String transitionName) — 当当前任务以 @EndTask 结束时,设置jBPM临时名字来使用。

org.jboss.seam.bpm.businessProcess

用于对话与业务处理之间联系的程序控制的API。

  • businessProcess.taskId — 与当前对话相关的任务标识。

  • businessProcess.processId —与当前对话相关的过程标识。

  • businessProcess.hasCurrentTask() — 是否是一个与当前对话相关的任务实例?

  • businessProcess.hasCurrentProcess() —是否是一个与当前对话相关的过程实例?

  • createProcess(String name) — 创建一个命名过程定义的实例,并与当前对话相关。

  • startTask() — 启动与当前对话相关的任务。

  • endTask(String transitionName) — 结束与当前对话相关的任务。

  • resumeTask(Long id) — 结合当前对话和指定标识的任务。

  • resumeProcess(Long id) —结合当前对话和指定标识的过程。

  • transition(String transitionName) — 触发临时过程。

org.jboss.seam.bpm.taskInstance

jBPM TaskInstance 的管理组件。

org.jboss.seam.bpm.processInstance

jBPM ProcessInstance (流程实例)的管理组件。

org.jboss.seam.bpm.jBPMContext

事件范围 jBPMContext 的管理组件。

org.jboss.seam.bpm.taskInstanceList

jBPM任务列表的管理组件。

org.jboss.seam.bpm.pooledTaskInstanceList

jBPM池任务列表的管理组件。

org.jboss.seam.bpm.taskInstanceListForType

jBPM任务列表的管理组件。

org.jboss.seam.bpm.pooledTask

用于池任务安排的行为操作。

org.jboss.seam.bpm.processInstanceFinder

过程实例任务列表管理者。

org.jboss.seam.bpm.processInstanceList

过程实例任务列表。

无论 org.jboss.seam.core.jBPM这个组件是否已安装,所有以上组件都会被自动安装。

28.6. 与安全相关的组件

这些组件都与Web层安全有关。

org.jboss.seam.web.userPrincipal

当前用户(本人)Principal的管理组件。

org.jboss.seam.web.isUserInRole

使JSF页面可以根据当前用户拥有的角色来选择渲染某一控制。 <h:commandButton value="edit" rendered="#{isUserInRole['admin']}"/>

28.7. 与JMS相关的组件

这些组件用于管理 TopicPublishers (主题发布者)和 QueueSenders (队列发送者)(见下文)。

org.jboss.seam.jms.queueSession

JMS QueueSession 的管理组件。

org.jboss.seam.jms.topicSession

JMS TopicSession 的管理组件。

28.8. 与邮件相关的组件

这些组件与Seam的邮件支持一起被使用。

org.jboss.seam.mail.mailSession

JavaMail Session 的管理组件。 Session或者可以从JNDI上下文中获取(通过设定 sessionJndiName属性),或者可以根据配置选项来创建。 如果是创建,host 必须被设定。

  • org.jboss.seam.mail.mailSession.host — 使用SMTP服务的主机名

  • org.jboss.seam.mail.mailSession.port — 使用SMTP服务的端口

  • org.jboss.seam.mail.mailSession.username — 用于连接到SMTP服务的用户名。

  • org.jboss.seam.mail.mailSession.password — 用于来连接到SMTP服务的密码。

  • org.jboss.seam.mail.mailSession.debug — 开启JavaMail debug模式。(非常详细)

  • org.jboss.seam.mail.mailSession.ssl — 开启到SMTP的SSL连接(默认端口465)

    org.jboss.seam.mail.mailSession.tls — 默认为true,决定是否开启在邮件会话中的TLS支持

  • org.jboss.seam.mail.mailSession.sessionJndiName — 在JNDI之内的javax.mail.Session的名字,如果它被提供,所有其它属性都将被忽略。

28.9. 基础组件

这些组件提供了关键的平台基础设施。你可以通过在 components.xml 文件中设定 install="true" 来安装一个默认情形下未被安装的组件。

org.jboss.seam.core.init

为Seam提供了初始化设置,总是自动被安装。

  • org.jboss.seam.core.init.jndiPattern — JNDI模式用于寻找会话Bean。

  • org.jboss.seam.core.init.debug — 打开 Seam 调试模式。

  • org.jboss.seam.core.init.clientSideConversations — 如果设为 true,Seam将会在客户端而不是在 HttpSession 中保存对话上下文变量。

  • org.jboss.seam.core.init.userTransactionName — 当寻找JTA UserTransaction 对象时,使用JNDI命名。

org.jboss.seam.core.manager

内在的组件用于Seam页和对话上下文管理,总是自动被安装。

  • org.jboss.seam.core.manager.conversationTimeout — 对话上下文的超时时间,单位为微秒。

  • org.jboss.seam.core.manager.concurrentRequestTimeout — 当一个线程试图在长时间的对话上下文中得到一个锁时的最大等待时间。

  • org.jboss.seam.core.manager.conversationIdParameter — 用于传送对话ID的请求参数,默认为 conversationId

  • org.jboss.seam.core.manager.conversationIsLongRunningParameter — 用于传送是否是长时间对话的请求参数,默认是长时间对话:conversationIsLongRunning

org.jboss.seam.navigation.pages

内部组件用于Seam工作平台管理,总是自动被安装。

  • org.jboss.seam.core.pages.noConversationViewId — 当对话在服务端没有被找到时,将重定向到视图的ID(全局设定)。

  • org.jboss.seam.navigation.pages.loginViewId — 当非授权用户试图访问一个受保护的页面时,将重定向到视图的ID(全局设定)。

  • org.jboss.seam.navigation.pages.httpPort — http配置请求所使用的端口(全局设定)。

  • org.jboss.seam.navigation.pages.httpsPort — https配置请求所使用的端口(全局设定)。

  • org.jboss.seam.navigation.pages.resources — 一个用来搜索 pages.xml 样式资源的列表。默认为 WEB-INF/pages.xml

org.jboss.seam.bpm.jBPM

引导 jBPMConfiguration (jBPM配置)。安装相应的类为 org.jboss.seam.bpm.jBPM

  • org.jboss.seam.core.jBPM.processDefinitions — 一系列的jPDL文件的资源列表,用于业务进程的协调(orchestration)。

  • org.jboss.seam.core.jBPM.pageflowDefinitions — 一系列的jPDL 文件的资源列表,用于对话页面流的定义(orchestration)。

org.jboss.seam.core.conversationEntries

内在的Session范围的组件,用于在各请求间记录活动的长时间对话。

org.jboss.seam.faces.facesPage

内在的页范围的组件,用于记录一页当中相关的对话上下文。

org.jboss.seam.persistence.persistenceContexts

内在组件,用以记录当前对话中的持久层上下文。

org.jboss.seam.jms.queueConnection

管理一个JMS QueueConnection(队列连接)。 当管理的 QueueSender(队列发送者)被安装的时候,它也被安装。

  • org.jboss.seam.jms.queueConnection.queueConnectionFactoryJndiName — JMS QueueConnectionFactory(队列连接工厂)的JNDI名称,默认为 UIL2ConnectionFactory

org.jboss.seam.jms.topicConnection

管理一个JMS TopicConnection (主题连接)。 当管理的 TopicPublisher 被安装的时候,它也被安装。

  • org.jboss.seam.jms.topicConnection.topicConnectionFactoryJndiName — 一个JMS TopicConnectionFactory (主题连接工厂)的JNDI名称,默认为 UIL2ConnectionFactory

org.jboss.seam.persistence.persistenceProvider

抽象层,对于JPA提供者的非标准化特性。

org.jboss.seam.core.validators

缓存Hibernate Validator实例 ClassValidator

org.jboss.seam.faces.validation

被应用程序用来判断验证是否成功。

org.jboss.seam.debug.introspector

支持Seam调试页面。

org.jboss.seam.debug.contexts

支持Seam调试页面。

org.jboss.seam.exception.exceptions

用以处理异常的内部组件。

org.jboss.seam.transaction.transaction

通过一个与JTA兼容的接口,用以控制事务和对底层事务管理提供抽象的API。

org.jboss.seam.faces.safeActions

通过检查视图中的操作表达式(action expression),判断在进来的URL里的操作表达式是否安全。

28.10. 杂项组件

这些组件无法归类。

org.jboss.seam.async.dispatcher

为异步方法调度无状态会话Bean。

org.jboss.seam.core.image

用以图像处理。

org.jboss.seam.core.pojoCache

PojoCache实例的管理组件。

org.jboss.seam.core.uiComponent

管理一个以Component ID为键值的UIComponents的映射表。

28.11. 特殊组件

当在Seam配置中指定了名字,某些特殊的Seam组件类可安装多次。 例如,接下来配置在components.xml下的几行,安装和配置了两个Seam组件:

<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>

这两个Seam组件是 bookingDatabaseuserDatabase

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

对话范围的受管 EntityManager 的管理组件。 该 EntityManager 有一个扩展的持久层上下文。

  • <entityManager>.entityManagerFactory — 一个值绑定表达式,该表达式的值为一个 EntityManagerFactory 的实例。

    <entityManager>.persistenceUnitJndiName — 实体管理者工厂的JNDI名称,默认为 java:/<managedPersistenceContext>

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

管理一个JPA EntityManagerFactory(实体管理者工厂)。当不在EJB3.0支持的环境下,特别有用。

  • entityManagerFactory.persistenceUnitName — 持久单元的名称。

可参考API JavaDoc,得到更多的配置属性信息。

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

管理者组件,用于在对话范围内管理Hibernate Session

  • <session>.sessionFactory — 一个值绑定表达式,其值为一个 SessionFactory 的实例。

    <session>.sessionFactoryJndiName — Session 工厂的JNDI名称,默认为 java:/<managedSession>

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

管理Hibernate SessionFactory(会话工厂)。

  • <sessionFactory>.cfgResourceName — 配置文件的路径,默认为 hibernate.cfg.xml

可参考API JavaDoc,得到更多的配置属性信息。

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

管理者组件,用于在事件范围内管理JMS QueueSender(队列发送者)。

  • <managedQueueSender>.queueJndiName — JMS队列的JNDI名称。

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

管理者组件,用于在事件范围内管理JMS TopicPublisher(主题发布者)。

  • <managedTopicPublisher>.topicJndiName — JMS主题的JNDI名称。

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

管理者组件,用于管理对话范围内的一个受管Drools WorkingMemory

  • <managedWorkingMemory>.ruleBase — 值表达式,其值为一个 RuleBase 的实例。

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

管理者组件,用于应用程序范围内的Drools RuleBase(基本规则)。 需要注意的是,这不是真正用于生产使用,因为它不支持新规则的动态安装。

  • <ruleBase>.ruleFiles — 一系列包含(Drools)规则的文件列表。

    <ruleBase>.dslFile — (Drools)DSL定义。

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