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
>
メールのテンプレート作成例では、 Facelets テンプレートは Seam メールタグで正しく動作することを示しています。
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"/>
これ以外に <m:header> タグを使ってメッセージにあらゆるヘッダーを追加することができます。
<m:header name="X-Sent-From" value="JBoss Seam"/>
EJBを使用している場合はMDB(Message Driven Bean, メッセージ駆動型Bean)をメールの受信に使用する事ができます。 JBossはJCAアダプター— mail-ra.rar —を提供していますが、JBoss ASと共に提供されているバージョンのJCAアダプターはいくつかの制約があります(またバージョンによっては提供されていない場合があります)。 このため、Seamと共に配布しているmail-ra.rarを使用する事を推奨します(Seam配布ファイルの extras/ 下のディレクトリにあります)。 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)が呼ばれています。 MDBの中ではほとんどのSeamのアノテーションを使用可能ですが、MDBの中でpersistence contextにアクセスしてはいけません。
http://www.jboss.org/community/wiki/InboundJavaMail に mail-ra.rar に関する情報がありますのでさらに詳細が知りたい場合にはそちらを参照してください。
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の配布ファイルに同梱)が利用可能であることを確認してください。
Seam Email モジュールにはビューテクノロジーとして Facelets を使用する必要があります。 ライブラリの今後のバージョンでは JSP の使用にも対応する可能性があります。 付け加えて、 seam-ui パッケージの使用も必要となります。
mailSessionコンポーネントはSMTPサーバと通信するときにJavaMailを使用しています。
JEE 環境で作業している、 または Seam 設定のSessionオブジェクトを使用できる場合、 JNDI ルックアップからjavaMailのSessionオブジェクトが使用できます。
mailSessionコンポーネントのプロパティの詳細は項32.9. 「メール関連のコンポーネント」を参照してください。
JBossAS deploy/mail-service.xml は JNDI にバインドする JavaMail セッションを設定します。 デフォルトのサービス設定は使用しているネットワークに応じて変更が必要となります。 サービスについての詳細は http://www.jboss.org/community/wiki/JavaMail で説明されています。
<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が指定されていることが必要です。
値属性が省略される場合、
このタグがその他の <p:document> タグをを含んでいると、 HTML ドキュメントがそこから生成されて email に添付されます。 fileName が指定されていなければなりません。
このタグがその他の JSF タグをを含んでいると、 HTML ドキュメントがそこから生成されて email に添付されます。 fileName が指定されていなければなりません。
fileName — 添付ファイルのファイル名の指定
contentType —添付ファイルのMIMEタイプの指定
メールのタイトルの設定
メールの本文の設定。 alternativeファセットによりHTMLメールを作成する際、htmlメールをサポートしていないメールリーダのために、テキスト版を含めることができます。
type — plainと設定してあれば、プレーンテキストのメールを生成しますが、それ以外ではHTMLメールを生成します。