SeamFramework.orgCommunity Documentation
Seam には 電子メールの送信およびテンプレート作成用のオプションコンポーネントが含まれるようになります。
電子メールのサポートは jboss-seam-mail.jar により提供されます。 この JAR にはメールの作成に使用されるメール JSF コントロールおよび mailSession 管理コンポーネントが含まれます。
examples/mail プロジェクトには実行可能なデモ用電子メールサポートのサンプルが含まれています。 正しいパッケージングの方法を行い、 また現在サポートされている主要な機能を実際に示すサンプルがいくつか含まれています。
Seamの統合テスト環境で電子メールの動作をテストする事ができます。 項37.3.4. 「Seamメールの統合テスト」参照
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());
}
}
たとえば、 無効な電子メールアドレスを入力すると例外が投げられ、 その例外がキャッチされてユーザーに表示されます。
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"で指定したオブジェクトにアクセスする前に、添付することをを宣言しなければいけません。
現在ではほとんどのメールリーダーが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
>
複数の受信者が属するグループに対して電子メールを送信したい場合には、すべての受信者のメールタグを繰り返しタグ<ui:repeat>の中に置くことができます。
<ui:repeat value="#{allUsers} var="user">
<m:to name="#{user.firstname} #{user.lastname}" address="#{user.emailAddress}" />
</ui:repeat
>
ただし、 若干異なる内容のメッセージを各受信者に送信する必要がある場合もあります (パスワードのリセットなど)。 最適な方法としては、 メッセージ全体を <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
>
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の設定をさらにしておきたい場合には、レンダラーコンポーネントをオーバーライドして、プログラムで設定するようにします。-上級ユーザー用。
Seam は国際化メッセージの送信に対応しています。 デフォルトでは、 JSF で提供されるエンコーディングが使用されますが、 テンプレートで上書きすることができます。
<m:message charset="UTF-8">
...
</m:message
>
本文、タイトルと受信者名はエンコードされます。 テンプレートのエンコーディングを設定して、Faceletsがメールを指定したページをパースする際に正しい文字セットを確実に指定する事が必要になります。
<?xml version="1.0" encoding="UTF-8"?>
場合により、前述以外のヘッダー情報を追加したい場合があると思いますが、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"/>
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 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.
次のように設定することができます。
@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を使用する事はできますし、お使いのアプリケーションサーバーが同様の機能を提供しているはずです。
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を使用しています。
JEE 環境で作業している、 または Seam 設定のSessionオブジェクトを使用できる場合、 JNDI ルックアップからjavaMailのSessionオブジェクトが使用できます。
mailSessionコンポーネントのプロパティの詳細は項32.9. 「メール関連のコンポーネント」を参照してください。
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を取得するよう指示します。
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
>
Meldwareをメールサーバとして使用したSeamのメールの例です(buni.orgより)。 MeldwareはSMTP, POP3, IMAP、webmail、共有カレンダー、グラフィカルな管理ツールを提供するグループウェアで、JEEアプリケーションとして書かれているので、Seamアプリケーションと共にJBoss ASにデプロイする事ができます。
Seamと共に配布されているMeldwareのバージョンは開発用のバージョンでメールボックス、ユーザー、メールアドレス(アライアス)等がアプリケーションがデプロイされる度に新規に作られます。 製品にMeldwareを使用するのでしたら、buni.orgから最新のバージョンをダウンロードしてインストールしてください。
電子メールは http://jboss.com/products/seam/mail の名前空間内でタグを使って生成されます。 ドキュメントには常にメッセージのルートに message タグがあるはずです。 メッセージタグは Seam による電子メール生成の準備を行います。
Faceletsの標準のテンプレートタグは、そのまま使う事ができます。 また、本文の中ではすべてのJSFタグを使う事ができます(もし、スタイルシートやJavascript等で外部のリソースへのアクセスが必要であればurlBaseを設定してください。
メールメッセージのルートタグ
importance —メールの重要度の設定(low,normal,high)。デフォルトはnormalです
precedence —メッセージの順序を設定します(例:バルク)
requestReadReceipt —デフォルトでfalseに設定されています。 trueに設定すると、メールの受け取りをFrom: アドレスに送信の要求を追加します。
urlBase — 設定されているurlBaseがrequestContextPathの前に置かれ、メール中に <h:graphicImage>のようにコンポーネントを使用する事を可能にします。
messageId — メッセージIDを明示的に設定します。
メール発信者のアドレス(From:)の設定。一つのメールに対して一つ設定できます。
name —メール発信者の名前
address — メール発信者のメールアドレス
メールの返信用のアドレス(Reply-to:)の設定。 一つのメールに対して一つのアドレスを設定する事ができます。
address — メール発信者のメールアドレス
電子メール に受信者を追加します。 受信者が複数の場合は複数の <m:to> タグを使用します。 このタグは <ui:repeat>. などの繰り返しタグ内に問題なく配置できます。
name — 受信者の名前
address — 受信者のメールアドレス
email に CC の受信者を追加します。 CC が複数の場合は複数の <m:cc> タグを使用します。 このタグは <ui:repeat> などの繰り返しタグ内に問題なく配置できます。
name — 受信者の名前
address — 受信者のメールアドレス
email に BCC の受信者を追加します。 BCC が複数の場合は複数の <m:bcc> タグを使用します。 このタグは <ui:repeat> などの繰り返しタグ内に問題なく配置できます。
name — 受信者の名前
address — 受信者のメールアドレス
メールへのヘッダー情報の追加(例:X-Sent-From: JBoss Seam)
name — 追加するヘッダーの名前 (e.g. X-Sent-From).
value —ヘッダーに追加する値(例:JBoss Seam)
電子メール に添付を追加します。
value — 添付ファイル:
String —Stringはクラスパス内のファイルへのパスと解釈されます。
java.io.File —EL式はFile オブジェクトを参照する事ができます。
java.net.URL — EL式はURLオブジェクトを参照する事ができます
java.io.InputStream — EL式はInputStreamを参照する事ができます。この場合、fileNameとcontentTypeが設定されていることが必要です。
byte[]— EL式は byte[].を参照する事ができます。この場合、fileNameとcontentTypeが指定されていることが必要です。
値属性が省略される場合、
If this tag contains a <p:document> tag, the document described will be generated and attached to the email. A fileName should be specified.
If this tag contains other JSF tags a HTML document will be generated from them and attached to the email. A fileName should be specified.
fileName — 添付ファイルのファイル名の指定
contentType —添付ファイルのMIMEタイプの指定
メールのタイトルの設定
メールの本文の設定。 alternativeファセットによりHTMLメールを作成する際、htmlメールをサポートしていないメールリーダのために、テキスト版を含めることができます。
type — plainと設定してあれば、プレーンテキストのメールを生成しますが、それ以外ではHTMLメールを生成します。