第31章. Seam内建组件

第31章.  Seam内建组件

本章描述Seam内建组件和它们的配置属性。即使内建组件没有列在你的components.xml 文件中，你仍可创建它们，但是如果你需要覆盖默认属性或指定某种类型的组件多于一个，就要使用components.xml。

 

注意你可以用你自己的实现替换所有内建组件，只需简单地在你自己的类上使用@Name指定内建组件的一个名字就行了。

 

31.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上下文）

 

所有这些组件已被安装。

 

31.2. 与JSF相关的组件

 

下面提供的组件组是对JSF的补充。

 

org.jboss.seam.faces.dateConverter

为java.util.Date 类型的属性提供一个默认的JSF转换器。

 

这个转换器自动注册JSF。 提供它，免去了开发者不得不在输入字段或页面参数上指定DateTimeConverter。在默认时，它假定为日期型（而不是时间或日期+时间），并且使用已调整为用户区域的短输入样式。对US区域，输入模式采用mm/DD/yy 。然而，为了千年虫的原因，年份从两位数改为四位数。(如, mm/DD/yyyy)。

 

利用组件配置完全覆盖输入模式是可以的。想了解这个类的例子请参考JavaDoc。

 

org.jboss.seam.faces.facesMessages

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

·   add(FacesMessage facesMessage) — 增加一个faces消息，它会在发生在当前对话中的下一个渲染响应阶段（render response phase）期间被显示。

·   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.ui.renderStampStore

一个组件（默认为会话作用域），负责管理渲染标志(render stamps)集合。 一个渲染标志是一个批示器，标志一个被渲染的表单是否已被提交。当使用客户边状态的JSF保存方法时，这个库很有用，因为它已判定是否一个表单已经被传递到服务器的控件中，而不是在客户端管理的组件树上。

 

为了从会话中撤消这个检查（这是客户边状态保存的主要设计目的之一），必须提供一个实现，在应用程序（只有应用程序运行时有效）或数据库中（跨越服务器重启有效）存储渲染标志。

·   maxSize — 保存在库的最大标志数。默认为： 100

 

 当类javax.faces.context.FacesContext在类路径中是可用时，这些组件都会被安装。

 

31.3. 实用工具组件

 

这些组件很实用。

 

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 Cache PojoCache 实例的管理器组件。

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

 

所有这些组件已被安装。

 

31.4. 用于国际化和主题的组件

 

下面这组组件使用Seam构建国际化用户界面变得容易。

 

org.jboss.seam.core.locale

Seam本地化。

 

org.jboss.seam.international.timezone

Seam时区。 Timezone是会话作用域的。

 

org.jboss.seam.core.resourceBundle

Seam资源包。资源包是无状态的。Seam资源包对在Java资源包的列表中的关键字执行一个深度优先（depth-first）搜索。

 

org.jboss.seam.core.resourceLoader

资源加载器用来获取应用程序的资源和资源包。

·   resourceLoader.bundleNames —当使用Seam资源包时，用于搜索的Java资源包名。默认为messages。

 

org.jboss.seam.international.localeSelector

在配置时或在用户运行时，支持本地化选择。

·   select() — 选择指定的地区。

·   localeSelector.locale — 实际的java.util.Locale.

·   localeSelector.localeString — 地区的字符串化表示。

·   localeSelector.language — 指定地区的语言

·   localeSelector.country — 指定地区的国家。

·   localeSelector.variant — 用于指定地区的变量。

·   localeSelector.supportedLocales — 一个SelectItems列表，表示在jsf-config.xml中被列出来的支持的地区。

·   localeSelector.cookieEnabled — 指定应通过cookie存留地区选择。

 

org.jboss.seam.international.timezoneSelector

在配置时或在用户运行时，支持时区（timezone）选择。

·   select() — 选择指定的时区。

·   timezoneSelector.timezone — 实际的java.util.TimeZone.

·   timezoneSelector.timeZoneId —时区的字符串化表示。

·   timezoneSelector.cookieEnabled —指定应通过cookie存留时区选择。

 

org.jboss.seam.international.messages

一个包含国际化消息的映射，国际化消息根据Seam资源包中定义的消息模板被渲染。

 

org.jboss.seam.theme.themeSelector

在配置时或在用户运行时，支持主题选择。

·   select() — 选择指定的主题。

·   theme.availableThemes — 被定义的主题列表。

·   themeSelector.theme — 选定的主题。

·   themeSelector.themes — 一个SelectItems列表，表示被定义的主题。

·   themeSelector.cookieEnabled —指定应通过cookie存留主题选择。

 

org.jboss.seam.theme.theme

一个包含主题条目的映射。

 

所有这些组件已被安装。

 

31.5. 用于控制对话的组件

 

下面这组组件允许应用程序或用户界面控制对话。

 

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

对话堆栈（面包屑型）的管理器组件。

 

org.jboss.seam.faces.switcher

对话切换器

 

所有这些组件已被安装。

 

31.6. 与jBPM相关的组件

 

这些组件与jBPM一起使用。

 

org.jboss.seam.pageflow.pageflow

控制Seam页面流的API。

·   isInProcess() — 如果当前有一个页面流在流程（process）中，返回true

·   getProcessInstance() —返回当前页面流的jBPM ProcessInstance（流程实例）

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

·   reposition(String nodeName) — 重新设置当前页面流到一个特殊的节点。

 

org.jboss.seam.bpm.actor

用于与当前会话相关联的jBPM 参与者（actor）的属性的应用程序控制API。

·   setId(String actorId) — 设置当前用户的jBPM 参与者（actor） id 。

·   getGroupActorIds() — 返回一个Set（集合），那个可以被增加的当前用户组的jBPM参与者ids的Set（集合）。

 

org.jboss.seam.bpm.transition

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

·   setName(String transitionName) — 设置当通过@EndTask结束当前任务时使用的jBPM转换名。

 

org.jboss.seam.bpm.businessProcess

用于对话与业务流程之间相关联的程序设计控制API

·   businessProcess.taskId — 与当前对话相关联的任务id。

·   businessProcess.processId — 与当前对话相关联的流程id。

·   businessProcess.hasCurrentTask() — 是与当前对话相关联的一个任务实例吗？

·   businessProcess.hasCurrentProcess() —是与当前对话相关联的一个流程实例吗？

·   createProcess(String name) — 创建命名流程定义的一个实例，并与当前对话相关联。

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

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

·   resumeTask(Long id) — 用给定的id让该任务与当前的对话相关联。

·   resumeProcess(Long id) —用给定的id让该流程与当前的对话相关联。

·   transition(String transitionName) — 触发转换。

 

org.jboss.seam.bpm.taskInstance

jBPM任务实例的管理器组件 。

 

org.jboss.seam.bpm.processInstance

jBPM流程实例的管理器组件。

 

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.bpm.jbpm被安装。

 

31.7. 与安全相关的组件

 

这些组件涉及到Web层安全。

 

org.jboss.seam.web.userPrincipal

当前用户Principal（当事人）的管理器组件。

 

org.jboss.seam.web.isUserInRole

允许JSF页面有选择地渲染一个控件，取决于当前的当事人的角色是否可用。<h:commandButton value="edit" rendered="#{isUserInRole['admin']}"/>。

 

31.8. 与JMS相关的组件

 

这些组件被用来与托管的TopicPublishers和QueueSenders一起使用 (见下文)。

 

org.jboss.seam.jms.queueSession

用于JMS QueueSession的管理器组件。

 

org.jboss.seam.jms.topicSession

用于JMS TopicSession的管理器组件。

 

31.9. 与Mail相关的组件

 

这些组件用来与Seam Email支持一起使用。

 

org.jboss.seam.mail.mailSession

用于JavaMail会话的管理器组件。这个会话，在JNDI上下文中 (通过设置sessionJndiName属性)可以查找它，或在主机是托管的情况下，根据配置选项创建它。

·   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调试 (非常详细)

·   org.jboss.seam.mail.mailSession.ssl — 启用 SSL连接到 SMTP (会默认到端口：465)

org.jboss.seam.mail.mailSession.tls — 默认为true，在邮件会话中启用TLS（Transport Layer Security）支持

·   org.jboss.seam.mail.mailSession.sessionJndiName — 在一个javax.mail.Session 被绑定到JNDI之下的名字。 如果提供，所有其他的属性会被忽略。

 

31.10. 基础设施组件

 

这些组件提供了关键的平台基础设施。你可以安装默认时没有被安装的组件，通过在components.xml中，在该组件上设置install="true" 来完成。

 

org.jboss.seam.core.init

初始化Seam设置。总是被安装。

·   org.jboss.seam.core.init.jndiPattern — 用来查找会话beans的JNDI模式

·   org.jboss.seam.core.init.debug — 启用Seam调试模式。当在产品期间时应设置为false。如果系统被置于启用了加载和调试的情况下，你可能看见错误消息。

·   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.core.manager.defaultFlushMode —设置刷新模式，在任何 Seam Managed Persistence Context上设置默认值。默认为AUTO。

 

org.jboss.seam.navigation.pages

Seam工作空间管理的内部组件。总是被安装。

·   org.jboss.seam.navigation.pages.noConversationViewId — 用于视图id的全局设置，在服务器边没有找到对话条目时，重定向到该视图。

·   org.jboss.seam.navigation.pages.loginViewId —用于视图id的全局设置，在一个未经授权的用户企图访问一个受保护的视图时，重定向到该视图。

·   org.jboss.seam.navigation.pages.httpPort — 用于端口的全局设置，在请求http配置时使用。

·   org.jboss.seam.navigation.pages.httpsPort —用于端口的全局设置，在请求http配置时使用。/*与上条重复了*/

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

 

org.jboss.seam.bpm.jbpm

引导一个JbpmConfiguration。做为类org.jboss.seam.bpm.Jbpm安装。

·   org.jboss.seam.bpm.jbpm.processDefinitions — 一个jPDL文件的资源名列表 ，被用于业务流程的组织。

·   org.jboss.seam.bpm.jbpm.pageflowDefinitions —一个jPDL文件的资源名列表 ，被用于对话页面流的组织。

 

org.jboss.seam.core.conversationEntries

内部会话作用域组件，用于记录在请求之间的存活的长期运行对话。

 

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 Debug Page（Seam调试页面）。

 

org.jboss.seam.debug.contexts

支持Seam Debug Page（Seam调试页面）。

 

org.jboss.seam.exception.exceptions

用于异常处理的内部组件

 

org.jboss.seam.transaction.transaction

在JTA兼容接口后面，控制事务和抽象底层事务管理实现的API

 

org.jboss.seam.faces.safeActions

判断在一个传入的URL中的一个动作表达式是否安全。通过检查在视图中的动作表达式来完成。

 

31.11. 杂组件

 

这些组件无法归类

 

org.jboss.seam.async.dispatcher

用于异步方法的分配器无状态会话bean

 

org.jboss.seam.core.image

图像处理和图像审讯。

 

org.jboss.seam.core.pojoCache

用于一个PojoCache实例的管理器组件。

 

org.jboss.seam.core.uiComponent

管理一个以组件id为键值的UIComponents的映射。

 

31.12. 特殊组件

 

在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组件名为bookingDatabase和userDatabase。

 

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

用于一个对话作用域托管的EntityManager的管理器组件， 该EntityManager有一个扩展的持久化上下文。

·   <entityManager>.entityManagerFactory — 一个值绑定表达式，求一个EntityManagerFactory实例的值。

<entityManager>.persistenceUnitJndiName — 实体管理器工厂的JNDI名，默认为java:/<managedPersistenceContext>。

 

<entityManagerFactory><span style=