第21章. Email

现在Seam包含一个用于模板和发送邮件的可选组件。

Email支持由jboss-seam-mail.jar提供。这个jar包含用来构建邮件的邮件 JSF控件和mailSession（邮件会话）管理组件。

examples/mail项目包含一个关于操作邮件支持的例子。它演示了正确的打包，并且包含了一些演示当前支持的关键功能的例子。

你可以使用Seam的集成测试环境测试你的邮件。见章节 35.3.4,“集成测试Seam邮件”

21.1.创建一个消息

你不需要为了使用Seam邮件而学习全部的新模板语言----一个邮件仅仅是一个facelet！

 

<m:message xmlns="http://www.w3.org/1999/xhtml"

 

    xmlns:m="http://jboss.com/products/seam/mail"

 

    xmlns:h="http://java.sun.com/jsf/html">

 

      <m:from name="Peter" address="[e-mail]" />

 

    <m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>

 

    <m:subject>Try out Seam!</m:subject>

 

    

    <m:body>

 

        <p><h:outputText value="Dear #{person.firstname}" />,</p>

 

        <p>You can try out Seam by visiting 

 

        <a href="http://labs.jboss.com/jbossseam">http://labs.jboss.com/jbossseam</a>.</p>

 

        <p>Regards,</p>

 

        <p>Pete</p>

 

    </m:body>

 

    

</m:message>

 

<m:message>标签打包了整个消息，告诉Seam开始渲染一封邮件。在<m:message>标签内部我们使用一个<m:from>标签来设置消息来自谁，一个<m:to>标签来指定发件人（注意我们如何象我们在普通facelet中使用EL）和一个<m:subject>标签。

<m:body>标签打包了电子邮件的主体。你可以在主体中使用标准的HTML标签就和JSF组件中使用一样。

所以，现在你已经有了你的邮件模板，你要如何发送它？好的，在渲染m:message结束时，mailSession被调用来发送邮件，所以你要做的全部是请求Seam渲染视图：

@In(create=true)

 

private Renderer renderer;

   

public void send() {

 

    try {

 

       renderer.render("/simple.xhtml");

 

       facesMessages.add("Email sent successfully");

 

   } 

 

   catch (Exception e) {

 

       facesMessages.add("Email sending failed: " + e.getMessage());

 

   }

 

}

假如，例如，你输入了一个无效的电子邮件地址，那么一个异常将会被抛出，它被捕获并随后显示给用户。

21.1.1. 附件

Seam使电子邮件添加附件变得容易。在处理文件时，它支持被使用的大多数标准java类型。

如果你想要邮寄jboss-seam-mail.jar：

 

<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar"/>

 

Seam会从类路径加载文件，并附加它到邮件。 默认时，它会以jboss-seam-mail.jar被附加；如果你要想它以其它名字，你只能增加fileName 属性：

<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar" fileName="this-is-so-cool.jar"/>

 

你也可以系上一个java.io.File, 一个 java.net.URL:

 

<m:attachment value="#{numbers}"/>

 

或者一个 byte[] 或者一个java.io.InputStream:

 

<m:attachment value="#{person.photo}" contentType="image/png"/>

 

你会注意到，对一个byte[] 和一个java.io.InputStream ，你需要指定附加的MIME类型 (与信息没有作为文件的一部分被携带一样).

并且它会更好， 你可以系上Seam产生的PDF, 或者标准的JSF视图， 只用<m:attachment> 包裹你将使用的普通标签：

 

<m:attachment fileName="tiny.pdf">

 

    <p:document>                                                      

        A very tiny PDF                                                                                             

    </p:document>

 

</m:attachment>

 

如果你想系上一组文件（例如从一个数据库加载一组图片），你只需用一个<ui:repeat>:

<ui:repeat value="#{people}" var="person">

 

    <m:attachment value="#{person.photo}" contentType="image/jpeg"   fileName="#{person.firstname}_#{person.lastname}.jpg"/>

 

</ui:repeat>

 

如果你想在线显示你所系上的图象：

 

<m:attachment 

 

    value="#{person.photo}" 

 

    contentType="image/jpeg" 

 

    fileName="#{person.firstname}_#{person.lastname}.jpg" 

 

    status="personPhoto" 

 

    disposition="inline" />

 

<img src="cid:#{personPhoto.contentId}" />

 

你可能疑惑cid:#{...}是做什么的。 好的，IETF通过设置它作为你图象的src来指定这个，在试图查找图象（Content-ID必须匹配）时，附件会被看到。— 魔术啊!

在试图访问状态对象前，你必须声明附件。

21.1.2. HTML/Text 可选部分

 

现今的大多数邮件阅读器支持HTML，而有些并不支持，所以你能添加一个纯文本选项到你的电子邮件主体

 

<m:body>

 

    <f:facet name="alternative">Sorry, your email reader can't show  our fancy email, 

 

please go to http://labs.jboss.com/jbossseam to explore Seam.</f:facet>

 

</m:body>

 

21.1.3. 多个收件人

你经常会想要发送一个电子邮件到一群收件人（例如你的用户）。所有的收件人邮件标签都要被放置在<ui:repeat>标签内。

 

<ui:repeat value="#{allUsers} var="user">

 

           <m:to name="#{user.firstname} #{user.lastname}"   address="#{user.emailAddress}" />

 

</ui:repeat>

 

21.1.4. 多个消息

然而，有时，你需要发送一个稍有不同的消息到每个收件人（例如，密码重设）。做这个的最好方法就是把消息整个的放到<ui:repeat>标签中：

 

<ui:repeat value="#{people}" var="p">

 

    <m:message>

 

               <m:from name="#{person.firstname} #{person.lastname}">#{person.address}</m:from>

 

        <m:to name="#{p.firstname}">#{p.address}</m:to>

 

            ...

 

    </m:message>

 

</ui:repeat>

 

21.1.5. 模板

邮件模板例子显示了仅对Seam邮件标签起作用的facelets模板。

我们的template.xhtml包含:

 

<m:message>

 

   <m:from name="Seam" address="[e-mail]" />

 

   <m:to name="#{person.firstname} #{person.lastname}">#{person.address}</m:to>

 

   <m:subject>#{subject}</m:subject>

 

   <m:body>

 

       <html>

 

           <body>

 

               <ui:insert name="body">This is the default body, specified by the template.</ui:insert>

 

           </body>

 

       </html>

 

   </m:body>

 

</m:message>

 

我们的template.xhtml包含:

 

<ui:param name="subject" value="Templating with Seam Mail"/>

 

<ui:define name="body">

 

    <p>This example demonstrates that you can easily use <i>facelets templating</i> in email!</p>

 

</ui:define>

 

你也可以在你的电子邮件中使用 facelets源标签，然而你必须用jar放它们在WEB-INF/lib ——当使用Seam Mail时，从web.xml 引用.taglib.xml是不可靠的。 (如果你同步发送你的邮件， Seam Mail无法访问完整的JSF或Servlet上下文， 所以不知道web.xml配置参数)。

如果你在发送邮件时需要做更多Facelets 或JSF的配置，你需要覆盖Renderer 组件并做配置编程——只为高级用户!

21.1.6. 国际化

Seam 支持发送国际化邮件。在默认时下，使用JSF提供的编码，但这可以用模板覆盖：

 

<m:message charset="UTF-8">

 

   ...

 

</m:message>

 

主体、主题 和接收人(和发送人) 名字会被编码。你需要确保facelets使用了正确的字符集解析你的页面，通过设置模板的编码 ：

 

<?xml version="1.0" encoding="UTF-8"?>

 

21.1.7.其它标题

有时你将想要添加其它标题到你的电子邮件上。Seam提供了对此的一些支持(见21.5章：“标签“)。例如，我们可以设置电子邮件的重要性，并询问一个收条：

 

<m:message xmlns:m="http://jboss.com/products/seam/mail"

 

    importance="low"

 

    requestReadReceipt="true"/>

 

另外，你可以使用<m:header>标签增加一些标题到消息：

 

<m:header name="X-Sent-From" value="JBoss Seam"/>

 

21.2. 接收邮件

如果你在使用EJB，那么你就能用一个MDB（消息驱动bean）来接收电子邮件。JBoss提供一个JCA适配器—mail-ra.rar—但是随JBossAS发布的版本有一定的局限（在一些版本中没有捆绑），因此我们推荐使用随Seam发布mail-ra.rar（它在Seam包中的extras/ directory目录下）。mail-ra.rar应该被放置在$JBOSS_HOME/server/default/deploy目录下；如果你使用的JBoss AS的版本已经有了这个文件，代替它。

你可以象这样配置它：

@MessageDriven(activationConfig={

 

    @ActivationConfigProperty(propertyName="mailServer", propertyValue="localhost"),

 

    @ActivationConfigProperty(propertyName="mailFolder", propertyValue="INBOX"),

 

    @ActivationConfigProperty(propertyName="storeProtocol", propertyValue="pop3"),

 

    @ActivationConfigProperty(propertyName="userName", propertyValue="seam"),

 

    @ActivationConfigProperty(propertyName="password", propertyValue="seam")

 

})

 

@ResourceAdapter("mail-ra.rar")

 

@Name("mailListener")

 

public class MailListenerMDB implements MailListener {

 

 

    @In(create=true)

 

    private OrderProcessor orderProcessor;

 

 

    public void onMessage(Message message) {

 

       // Process the message

 

       orderProcessor.process(message.getSubject());

 

    }

 

   

 

}

每一个收到的消息都将导致 onMessage(Message message) 被调用。 大多数Seam的注释将会在MDB内部运行，但是你不能访问持久上下文。

在http://www.jboss.org/community/docs/DOC-10032你可以查找到mail-ra.rar的在更多信息

如果你没有使用JBoss AS ，你仍然可以使用mail-ra.rar ，或者你能在你的应用程序服务器上找到一个相似的适配器。

21.3. 配置

为使你的应用程序中包含电子邮件支持，应包含jboss-seam-mail.jar在 WEB-INF/lib 目录中。 如果你在使用JBoss AS，对使用Seam的邮件支持不需要做更多的配置。否则，你需要确保你有JavaMail API、一个JavaMail API表示的实现（JBoss AS中使用的API和impl随Seam的lib/mail.jar包一起发布）和一个Java Activation Framework的拷贝（随Seam的 lib/activation.jar 包一起发布）。

 

注意：Seam的Email模块需要使用Facelets作为视图技术。在将来库版本中也可能会支持JSP。另外，它需要使用seam-ui包。

mailSession 组件使用JavaMail与“真实的”SMTP服务器通讯。

21.3.1. mailSession

如果你工作在JEE环境工作，可以用一个JNDI查找得到可用的JavaMail Session，或者你也可以使用Seam已配置的Session。

有关mailSession组件属性的详细描述见第31.8 节 “与邮件相关的组件”。

 

21.3.1.1. 用 JBoss AS的JNDI查找

JBossAS deploy/mail-service.xml配置了一个捆绑到JNDI的JavaMail session。 对你的网络可能会需要修改默认的服务配置。描述服务的详情见 http://www.jboss.org/community/docs/DOC-11056 。

 

<components xmlns="http://jboss.com/products/seam/components"

 

    xmlns:core="http://jboss.com/products/seam/core"

    xmlns:mail="http://jboss.com/products/seam/mail">

 

          <mail:mail-session session-jndi-name="java:/Mail"/>

 

    

</components>

这里我们告诉Seam从JNDI得到捆绑到java:/Mail的邮件Session。

 

21.3.1.2. Seam 配置 Session

一个邮件session可以通过 components.xml被配置。 这里我们告诉Seam 使用smtp.example.com作为smtp服务器:

 

<components xmlns="http://jboss.com/products/seam/components"

 

    xmlns:core="http://jboss.com/products/seam/core"

    xmlns:mail="http://jboss.com/products/seam/mail">

 

   

    <mail:mail-session host="smtp.example.com"/>

 

  

</components>

 

21.4. Meldware

Seam的邮件例子使用Meldware (来处 buni.org) 作为邮件服务器。 Meldware 是一个组件包，提供SMTP、 POP3、 IMAP、 网页邮件、共享日历和一个图形界面的管理员工具；它以JEE应用程序方式编写，所以可以与你的Seam应用程序一起被布置到JBoss AS。

警告：随Seam发布的Meldware版本 (需要下载) 是为开发特别量身定制的——每一次应用部署时，邮箱、用户和别名（电子邮件地址）被创建。 如果你想在产品中使用Meldware，你应该从buni.org安装最新的版本。

21.5. 标签

使用http://jboss.com/products/seam/mail 命名空间的标签生成邮件。文档在消息的根部总是有message标签。消息标签准备让Seam生成一个电子邮件。

facelets的标准模板标签可以象往常一样使用。在主体内部你可以使用 JSF标签； 如果它需要访问外部资源(样式表, javascript)，那么一定要设置urlBase。

<m:message>

邮件消息的根标签

• importance — 低、正常或高。默认是正常，这是设置邮件消息重要性。
• precedence — 设置消息的优先级（例如：bulk）
• requestReadReceipt —默认为false，如果设置，一个阅读回执请求将会以发到 From: address方式的阅读回执被添加。
• urlBase — 如果设置，此值预先考虑requestContextPath，其允许你在你的邮件中使用如 <h:graphicImage> 的组件。
• messageId —明确设置Message-ID

<m:from>

• 为邮件设置来源地址。 每个电子邮件你只能设置一个。
• name — 电子邮件应来自的名字。
• address —电子邮件应来自的电子邮件地址。

<m:replyTo>

为电子邮件设置回复地址。每个电子邮件你只能设置一个。

• address —电子邮件应来自的电子邮件地址。

<m:to>

添加一个收件人到邮件。 对多个收件人使用多个<m:to> 标签。这个标签可以被安全的放置在如<ui:repeat>的迭代器标签中。

• name — 收件人名字。
• address —收件人的电子邮件地址。

<m:cc>

添加抄送人到邮件。有多个抄送人时使用多个<m:cc>标签。这个标签可以被安全的放置在如<ui:repeat>的迭代器标签中。

• name — 收件人的名字。
• address — 收件人的邮件地址。

<m:bcc>

添加一个秘文抄送人到邮件。有多个秘文抄送人时使用多个的<m:bcc>标签。 这个标签可以被安全的放置在如<ui:repeat>的迭代器标签中。

• name — 收件人的名字。
• address — 收件人的邮件地址。

<m:header>

向邮件添加一个头（例如：X-Sent-From: JBoss Seam）。

• name — 要添加的头的名字（例如：X-Sent-From）。
• value — 要添加的头的值（例如：JBoss Seam）。

<m:attachment>

添加一个附件到邮件。

• value — 要添加的附件：

o      String —一个 String作为在classpath中文件的路径被解释。

o      java.io.File —一个引用 File 对象的EL表达式。

o      java.net.URL — 一个引用URL对象的EL表达式。

o      java.io.InputStream — 一个引用 InputStream的EL表达式。 这种情况下，fileName 和 contentType 都必须指定。

o      byte[] — 一个引用 byte[] 的EL表达式。 这种情况下，fileName 和 contentType 都必须指定。

如果值属性被省略：

o      如果这个标签包含一个 <p:document> 标签，这个被描述的文档将会被生成并且附加到邮件上。 fileName 应该被指定。

o      如果这个标签包含其它的JSF标签，将会根据它们生成HTML文档并附加到邮件。fileName应该被指定。

• fileName — 对使用的附件指定文件名。
• contentType —指定附件的MIME类型。

<m:subject>

设置邮件的主题。

<m:body>

设置邮件主体。支持 alternative facet，如果生成的一个HTML邮件可能包含对一个不支持html的阅读器而言的可选文本。

• type — 如果设为 plain，那么会生成一份简单文本邮件，否则将会生成一份HTML邮件。