Seam には email の送信およびテンプレート作成用のオプションコンポーネントが含まれるようになります。
Email のサポートは jboss-seam-mail.jar により提供されます。 この JAR にはメールの作成に使用されるメール JSF コントロールおよび mailSession 管理コンポーネントが含まれます。
examples/mail プロジェクトには実行可能なデモ用 email サポートのサンプルが含まれています。 正しいパッケージ化の方法を行い、 また現在サポートされている主要な機能を実際に示すサンプルがいくつか含まれています。
Seam Mail を使うためにテンプレート作成用の新しい言語を丸ごと学ぶ必要はありません — email は単純に 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="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>Peter</p>
</m:body>
</m:message><m:message> タグはメッセージ全体を包み、 Seam に email のレンダリングを開始するよう指示します。 <m:message> タグ内では、 メッセージの送信元の設定に <m:from> タグ、 送信者の指定に <m:to> タグ (通常のfacelet 内にいるのでそれに応じた EL の使用方法に注意してください)、 また <m:subject> タグを使用します。
<m:body> は email のボディを包みます。 HTML 正規タグをボディ内や JSF コンポーネント内に使用することができます。
これで email テンプレートのできあがりです。 送信方法についてですが、 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());
}
}たとえば、 無効な email アドレスを入力すると例外が投げられ、 その例外がキャッチされてユーザーに表示されます。
Seam では email へのファイル添付が容易になっています。 ファイルを操作する際に使用される標準 java タイプのほとんどに対応しています。
jboss-seam-mail.jar に email 送信をしたい場合、
<m:attachment value="/WEB-INF/lib/jboss-seam-mail.jar"/>
Seam はファイルをクラスパスからロードして、 email にそのファイルを添付します。 デフォルトでは、 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>今日では、 ほとんどのメールユーザーは HTML に対応しているなか、 HTML に対応していないユーザーもいます。 このため、 email のボディに代替となるプレーンテキストを追加することができます。
<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>email を複数の送信者グループに送信する必要があることも少なくありません (ユーザーグループなど 。 受信者メールタグはすべて <ui:repeat> 内に配置することができます。
<ui:repeat value="#{allUsers} var="user">
<m:to name="#{user.firstname} #{user.lastname}" address="#{user.emailAddress}" />
</ui:repeat>ただし、 若干異なる内容のメッセージを各受信hさに送信する必要がある場合もあります (パスワードのリセットなど)。 最適な方法としては、 メッセージ全体を <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>Seam は国際化メッセージの送信に対応しています。 デフォルトでは、 JSF で提供されるエンコーディングが使用されますが、 テンプレートで上書きすることができます。
<m:message charset="UTF-8"> ... </m:message>
ボディ、 件名、 そして受信者名と送信者名はコード化されます。 テンプレートのエンコーディングを設定して facelets が正しい文字セットをページ解析に使用するよう確認する必要があります。
<?xml version="1.0" encoding="UTF-8"?>
その他のヘッダを email に追加したいことがあります。 Seam が対応しているものがいくつかあります (項16.4. 「タグ」 を参照)。 たとえば、 email の重要度を設定することができます。
<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) を使用して email を受信することができます。 Seam は mail-ra.rar の改良バージョンと共に JBoss AS で配信されます。 改良点が JBoss AS のリリースバージョンに参入するまでのあいだ、 デフォルトの rar を Seam で配信されるものに置き換えることを推奨します。
次のように設定することができます。
@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 内で動作しますが、 永続コンテキストにはアクセスしないでください。
デフォルトの mail-ra.rar についての詳細は http://wiki.jboss.org/wiki/Wiki.jsp?page=InboundJavaMail をご覧ください。 Seam と共に配信されているバージョンには、 JavaMail のデバッグ機能を有効にする debug プロパティ、 使用している MDB へのメッセージ配信が正常に完了すると POP3 メールボックスをフラッシュする機能を無効にする flush プロパティ (デフォルトでは ture)、 デフォルトの TCP ポートを上書きする port プロパティも含まれています。 これに対する api は今後 JBoss AS に加えられる変更に準じて変わる可能性があるので注意してください。
JBoss AS を使用していない場合は mail-ra.rar を使用することができます (メールディレクトリ内の Seam に含まれている)。 または、 同様のアダプタを含む独自のアプリケーションサーバーを思考しても構いません。
アプリケーションに Email サポートを含ませるには、 WEB-INF/lib ディレクトリ内に jboss-seam-mail.jar を含ませます。 JBoss AS を使用している場合は、 Seam の email サポートを使用するのに特別な設定は必要ありません。 これ以外は、 JavaMail API があるか、 JavaMail API が実装されているか (JBoss AS で使用される API と impl は lib/mail.jar として seam と共に配信される)、 Java Activation Framework のコピーがあるか (lib/activation.jar として seam と共に配信される) を確認する必要があります。
Seam Email モジュールにはビューテクノロジーとして Facelets を使用する必要があります。 ライブラリの今後のバージョンでは JSP の使用にも対応する可能性があります。 また、 seam-ui パッケージの使用も必要となります。
mailSession コンポーネントは JavaMail を使って「実際の」 SMTP サーバーと交信します。
JEE 環境で作業している、 または Seam 設定の Session を使用できる場合、 JavaMail Session が JNDI ルックアップから使用できる可能性があります。
mailSession コンポーネントのプロパティについての詳細は 項23.8. 「メール関連のコンポーネント」 で説明されています。
JBossAS deploy/mail-service.xml は JNDI にバインドする JavaMail セッションを設定します。 デフォルトのサービス設定は使用しているネットワークに応じて変更が必要となります。 サービスについての詳細は http://wiki.jboss.org/wiki/Wiki.jsp?page=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 にバウンドするメールセッションを取得するよう指示します。
メールセッションは components.xml から設定することができます。 ここで Seam に smtp サーバーとして smtp.example.com を使用するよう指示します。
<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>Email は http://jboss.com/products/seam/mail 名前スペース内でタグを使って生成されます。 ドキュメントには常にメッセージのルートに message タグがあるはずです。 メッセージタグは Seam による email 生成の準備を行います。
facelets の標準テンプレート作成タグは通常通りに使用できます。 ボディ内では、 外部リソース (スタイルシート、 javascript) にアクセスを必要としない JSF タグを使用できます。
メールメッセージのルートタグ
importance — low (低)、 normal (中)、 high (高) のいずれかになります。 デフォルトでは normal (中) になり、 これがメールメッセージの重要度を設定します。
precedence — メッセージの優先度を設定します (例、 bulk)。
requestReadReceipt — デフォルトでは false です。 設定されると、 受信通知のリクエストが追加されて From: のアドレスに受信通知が送信されます。
urlBase — 設定されると、 その値が requestContextPath の先頭に追加され email 内で <h:graphicImage> などのコンポーネントを使用できるようになります。
email の From: アドレスを設定します。 1 email に対して次のうちいずれか 1 つのみ使用できます。
name — email の送信元の名前です。
address — email の送信元の email アドレスです。
email の Reply-to: アドレスを設定します。 1 email に対して次のうちいずれか 1 つのみ使用できます。
address — email の送信元の email アドレスです。
email に受信者を追加します。 受信者が複数の場合は複数の <m:to> タグを使用します。 このタグは <ui:repeat>. などの繰り返しタグ内に配置しても安全です。
name — 受信者の名前です。
address — 受信者の email アドレスです。
email に CC の受信者を追加します。 CC が複数の場合は複数の <m:cc> タグを使用します。 このタグは <ui:repeat> などの繰り返しタグ内に配置しても安全です。
name — 受信者の名前です。
address — 受信者の email アドレスです。
email に BCC の受信者を追加します。 BCC が複数の場合は複数の <m:bcc> タグを使用します。 このタグは <ui:repeat> などの繰り返しタグ内に配置しても安全です。
name — 受信者の名前です。
address — 受信者の email アドレスです。
email にヘッダを追加します (例、 X-Sent-From: JBoss Seam)。
name — 追加するヘッダ名です (例、 X-Sent-From)。
value — 追加するヘッダ値です (例、 JBoss Seam)。
email に添付を追加します。
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> タグを含んでいるなら、 記述されるドキュメントが生成されて email に添付されます。 fileName が指定されなければなりません。
このタグがその他の JSF タグをを含んでいると、 HTML ドキュメントがそこから生成されて email に添付されます。 fileName が指定されていなければなりません。
fileName — 添付するファイルに使用するファイル名を指定します。
contentType — 添付されるファイルの MIME タイプを指定します。
email の件名を設定します。
email のボディを設定します。 HTML email が生成される場合に html に対応していない受け取り側に提供する代替テキストを含む alternative ファセットをサポートしています。
type — plain に設定するとプレーンテキストの email が生成されます。 これ以外は HTML email が生成されます。