第21章電子メール

Seam には電子メールの送信およびテンプレート作成用のオプションコンポーネントが含まれるようになります。

電子メールのサポートは jboss-seam-mail.jar により提供されます。この JAR にはメールの作成に使用されるメール JSF コントロールおよび mailSession 管理コンポーネントが含まれます。

examples/mail プロジェクトには実行可能なデモ用電子メールサポートのサンプルが含まれています。正しいパッケージングの方法を行い、また現在サポートされている主要な機能を実際に示すサンプルがいくつか含まれています。

Seamの統合テスト環境で電子メールの動作をテストする事ができます。項37.3.4. 「Seamメールの統合テスト」参照

21.1. メッセージを作成する

Seamの電子メール機能はFaceletsを利用して記述しているので、新たなテンプレート用の言語を学ぶ必要はありません。


<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="peter@example.com" />

    <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 に email のレンダリングを開始するよう指示します。 <m:message> タグ内では、メッセージの送信元の設定に <m:from> タグ、送信者の指定に <m:to> タグ (通常のFacelets 内にあるのでそれに応じた EL の使用方法に注意してください)、また <m:subject> タグを使用します。

<m:body> は email のボディを囲みます。 HTML 正規タグをボディ内や JSF コンポーネント内に使用することができます。

これで電子メールテンプレートのできあがりです。送信方法についてですが、 m:message のレンダリングの最後に、 mailSession が email を送信するようコールされるので、ユーザーがすべきことは 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タイプを指定する必要があることが分かると思います。

さらに便利なことに、使用する通常のタグの前後を <m:attachment> で囲むだけで Seam 生成 PDF や標準 JSF ビューを添付することができます。


<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の規則によればイメージファイルのソースにこれを指定すれば、イメージを見ようとすると添付ファイルを参照する（但し、Content-IDが一致している必要があります）とあります。

"status"で指定したオブジェクトにアクセスする前に、添付することをを宣言しなければいけません。

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. テンプレートの作成

The mail templating example shows that facelets templating just works with the Seam mail tags.

jboss.org の template.xhtml には次の内容が含まれています。


<m:message>

   <m:from name="Seam" address="do-not-reply@jboss.com" />

   <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

>

jboss.org の templating.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

>

WEB-INF/libにjarファイルを入れて置く事によりFaceletsのソースタグもメールの中で使う事ができます。 Seamのメールではweb.xmlから.taglib.xmlを参照する方法は安定性を欠いています（非同期でメールを送信する場合、SeamメールはJSFあるいはサーブレットのコンテキストすべてにアクセスするわけではないので、 web.xmlの設定パラメータを認識しません）。

メール送信時にFaceletsやJSFの設定をさらにしておきたい場合には、レンダラーコンポーネントをオーバーライドして、プログラムで設定するようにします。－上級ユーザー用。

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

Otherwise you can add any header to the message using the <m:header> tag:


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

21.2. 電子メールを受信する

If you are using EJB then you can use a MDB (Message Driven Bean) to receive email. JBoss provides a JCA adaptor — mail-ra.rar — but the version distributed with JBoss AS 4.x has a number of limitations (and isn't bundled in some versions) therefore we recommend using the mail-ra.rar distributed with Seam (it's in the extras/ directory in the Seam bundle). mail-ra.rar should be placed in $JBOSS_HOME/server/default/deploy; if the version of JBoss AS you use already has this file, replace it.

注意

JBoss AS 5.x and newer has mail-ra.rar with applied the patches, so there is no need to copy the mail-ra.rar from Seam distribution.

次のように設定することができます。

@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)が呼ばれています。 MDBの中ではほとんどのSeamのアノテーションを使用可能ですが、MDBの中でpersistence contextにアクセスしてはいけません。

You can find more information on mail-ra.rar at http://www.jboss.org/community/wiki/InboundJavaMail.

JBoss ASをアプリケーションサーバーとして使用していない場合にも、mail-ra.rarを使用する事はできますし、お使いのアプリケーションサーバーが同様の機能を提供しているはずです。

21.3. 設定

Seamアプリケーションでメールサポートをする場合には、jboss-seam-mail.jarをWEB-INF/libに配置してください。 JBoss ASをアプリケーションサーバーとして使用している場合には、Seamのメールサポートのためにこれ以上の設定は必要ありません。 JBoss AS以外を使用している場合には、JavaMailAPIがサポートされていること（JBoss ASで使用されるAPIとImplはlib/mail.jarとしてSeamの配布ファイルに同梱されています）とJava Activation Frameworkのコピー（lib/activation.jarとしてSeamの配布ファイルに同梱）が利用可能であることを確認してください。

注意

The Seam Mail module requires the use of Facelets as the view technology. Future versions of the library may also support the use of JSP. Additionally, it requires the use of the seam-ui package.

mailSessionコンポーネントはSMTPサーバと通信するときにJavaMailを使用しています。

21.3.1. `mailSession`

JEE 環境で作業している、または Seam 設定のSessionオブジェクトを使用できる場合、 JNDI ルックアップからjavaMailのSessionオブジェクトが使用できます。

mailSessionコンポーネントのプロパティの詳細は項32.9. 「メール関連のコンポーネント」を参照してください。

21.3.1.1. JBoss AS の JNDI ルックアップ

The JBossAS deploy/mail-service.xml configures a JavaMail session binding into JNDI. The default service configuration will need altering for your network. http://www.jboss.org/community/wiki/JavaMail describes the service in more detail.


<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 に送られるmailSessionを取得するよう指示します。

21.3.1.2. Seam 設定のSession

mailSessionはcomponents.xmlで設定する事ができます。ここでは、smtp.example.comによりSeamが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

Meldwareをメールサーバとして使用したSeamのメールの例です（buni.orgより）。 MeldwareはSMTP, POP3, IMAP、webmail、共有カレンダー、グラフィカルな管理ツールを提供するグループウェアで、JEEアプリケーションとして書かれているので、Seamアプリケーションと共にJBoss ASにデプロイする事ができます。

注意

Seamと共に配布されているMeldwareのバージョンは開発用のバージョンでメールボックス、ユーザー、メールアドレス（アライアス）等がアプリケーションがデプロイされる度に新規に作られます。製品にMeldwareを使用するのでしたら、buni.orgから最新のバージョンをダウンロードしてインストールしてください。