ozacc-mail libraryは、Spring FrameworkやSeasar2といったDIコンテナに組み込んで使用できるメール送信ライブラリです。DIコンテナ上での使用を想定していますが、DIコンテナ環境外での使用も可能です。
JDK 1.4以上の環境でご使用ください。
また、次のJARファイルをクラスパスに含めてください。
各ライブラリは、ozacc-mail libraryの配布ファイルには含まれていませんので、Dependenciesページを参考に各自で取得してください。
com.ozacc.mail.impl.JDomXMLMailBuilder
を使用する場合]com.ozacc.mail.impl.XMLVelocityMailBuilder
、com.ozacc.mail.impl.JDomXMLMailBuilder
を使用する場合]com.ozacc.mail.impl.XMLVelocityMailBuilder
、com.ozacc.mail.impl.JDomXMLMailBuilder
を使用する場合]次のページからozacc-mail libraryの最新リリースをダウンロードできます。
http://sourceforge.jp/projects/spring-ext/
またMaven用のリモートレポジトリも用意しています。URLは「http://spring-ext.sourceforge.jp/maven/
」です。このURLをmaven.repo.remote
プロパティに設定してください。groupId
、artifactId
は共に「ozacc-mail
」です。
SendMail
は、JavaMail APIをラップし、メール送信のための至極シンプルなインターフェースを提供しています。提供しているメソッド名はたった一つ、send()
です。メールデータを表すcom.ozacc.mail.Mail
インスタンスか、JavaMailのMimeMessage
インスタンスを引数に指定すると、それを送信します。(これらの配列も指定可能です。)
SendMail(SendMailImpl).send()
メソッドは、スレッドセーフな設計になっていますが、呼び出すスレッドの数だけSMTPサーバに接続します。通常の使用では問題にならないはずですが、メールサーバやその設定によっては注意が必要です。
SendMail
の使用方法を、Springと連携させる場合を例にとって説明します。
▼applicationContext.xmlでのBean定義
<beans> <bean id="sendMail" class="com.ozacc.mail.impl.SendMailImpl"> <!-- SMTPサーバ --> <property name="host"><value>smtp.example.com</value></property> </bean> </beans>
▼Javaソース
// Mailインスタンスの生成 Mail mail = new Mail(); mail.setFrom("shop@example.com", "XXXオンラインショップ"); mail.addTo("misaki@foo.com", "伊東美咲さま"); mail.addBcc("order@example.com"); mail.setSubject("ご注文の確認"); mail.setText("お買い上げありがとうございました。\n\nご注文明細・・・"); // SendMailインスタンスの取得 SendMail sendMail = (SendMail)applicationContext.getBean("sendMail"); // メールの送信 sendMail.send(mail);
sendMail.send(mail)
で、何らかの原因で送信に失敗すると、com.ozacc.mail.MailException
がスローされます。MailException
は非チェック例外なので、プログラムの要求に応じてキャッチしてください。
MailBuilder
を使用すると、ファイルに記述されたメールデータからMail
インスタンスを生成できます。
さらに、MailBuilder
インターフェースを継承したVelocityMailBuilder
を使用すると、Velocity
と連携して動的にメールデータを生成し、そのデータからMailインスタンスを生成できます。
現バージョンでは、XML形式のメールデータを扱うXMLMailBuilderImpl
クラスが提供されています。ここではその使用方法を、Springと連携させる場合を例にとって説明します。
▼applicationContext.xmlでのBean定義
<beans> <bean id="sendMail" class="com.ozacc.mail.impl.SendMailImpl"> <property name="host"><value>smtp.example.com</value></property> </bean> <bean id="mailBuilder" class="com.ozacc.mail.impl.XMLMailBuilderImpl" /> </beans>
▼Javaソース
// MailBuilderインスタンスの取得 MailBuilder mailBuilder = (MailBuilder)applicationContext.getBean("mailBuilder"); // メールデータXMLファイルのパス (クラスパス上) String path = "/com/example/mail/mail-template.xml"; // Mailインスタンスを生成 Mail mail = mailBuilder.buildMail(path); // SendMailインスタンスの取得 SendMail sendMail = (SendMail)applicationContext.getBean("sendMail"); // メールの送信 sendMail.send(mail);
▼mail-template.xml
<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE mail PUBLIC "-//OZACC//DTD MAIL//EN" "http://www.ozacc.com/library/dtd/ozacc-mail.dtd"> <mail> <returnPath email="return@example.com" /> <from email="from@example.com" name="差出人" /> <recipients> <to email="to1@example.com" name="宛先1" /> <cc email="cc1@example.com" name="CC1" /> <bcc email="bcc@example.com" /> <cc email="cc2@example.com" /> <to email="to2@example.com" /> </recipients> <replyTo email="reply@example.com" /> <!-- subject(件名)の前後のホワイトスペース(半角スペース、タブ、改行)は削除されます。 --> <subject> 件名 </subject> <!-- body(本文)の前後のホワイトスペース(半角スペース、タブ、改行)は削除されます。 --> <body> 本文 </body> </mail>
DTDで定義されているように、ルート要素<mail>
以外の全要素はオプションです。
例えば<from>
要素だけ含んだXMLからは、from
プロパティだけセットされた
Velocityとの連携については、テストケース(src/test/com/ozacc/mail/impl/XMLVelocityMailBuilderImplTest
)を参照してください。
XMLMailFactoryBean
はSpringと連携している場合にのみ使用可能です。
上述したMailBuilder
を使ってXMLメールデータからMail
インスタンスを生成する場合、XMLファイルのロケーションを示すパスがソース内にハードコーディングされています。一般的にはアプリケーション側で、MailBuilder
のインスタンスとXMLファイルのロケーションパスをプロパティとして保持するクラスを作り、DIコンテナでプロパティを設定するようにします。
Springを使用している場合、このようなクラスを作らずともXMLファイルのロケーションパスをソースから追い出し、コンテナ上でMailインスタンスを生成させることができます。
▼applicationContext.xmlでのBean定義
<beans> <bean id="sendMail" class="com.ozacc.mail.impl.SendMailImpl"> <property name="host"><value>smtp.example.com</value></property> </bean> <bean id="mail" class="com.ozacc.mail.spring.XMLMailFactoryBean"> <!-- メールデータXMLファイルのパス (クラスパス上) --> <property name="classPath"><value>/com/example/mail/mail-template.xml</value></property> </bean> </beans>
▼Javaソース
// Mailインスタンスの生成、取得 Mail mail = (Mail)applicationContext.getBean("mail"); // SendMailインスタンスの取得 SendMail sendMail = (SendMail)applicationContext.getBean("sendMail"); // メールの送信 sendMail.send(mail);
XMLMailFactoryBean
から生成されるMail
インスタンスは、prototype
です。つまりシングルトンではなく、呼び出すたびに新しいMail
インスタンスが生成されます。何かの理由でMail
インスタンスをシングルトンにしたい場合は、XMLMailFactoryBean
のsinglton
プロパティにtrue
をセットするだけです。
XMLMailFactoryBean
では、Velocityと連携させてMail
インスタンスを生成することはできません。
1.1.4
SendMailImpl
、SendMailProImpl
クラスを修正。Mail
クラスのtoString()
メソッドを、Reply-Toアドレスも出力するように修正。1.1.3
com.ozacc.mail.impl.AbstractXMLMailBuilder
、com.ozacc.mail.impl.OMLMimeMessage
、com.ozacc.mail.impl.DTDEntityResolver
、com.ozacc.mail.impl.VelocityLogSystem
をpublicなクラスに変更。com.ozacc.mail.impl
パッケージ内のいくつかのクラスで、プロパティやメソッドのアクセス制限をprivateをprotectedに変更。MockSendMail
で、Fromアドレスを比較するように修正。また、ToやFromアドレスのメールアドレスと名前の両方を比較するように修正。1.1.2
VelocityMailBuilder
がテンプレートメールデータのキャッシュをサポートしました。1.1.1
XMLVelocityMailBuilderImpl
がXMLメールデータを読み込む際に、<![CDATA[]]>
タグを削除しないように修正。1.1 rc2
SendMailImpl
とSendMailProImpl
クラスにsetMessageId(String)
メソッドを追加。com.ozacc.mail.impl.OMLMimeMessage
クラスを追加。Message-IDヘッダのドメイン部分がカスタマイズ可能に。com.ozacc.mail.impl.DTDEntityResolver
クラスを追加。ネットワークアクセスなしでDTDを参照できるようになった。MimeMessage
をマルチパートからシングルパートに修正。1.1 rc1
MultipartMail
クラスをMail
クラスに統合。InputStream
とURL
インスタンスを指定できるメソッドを追加。com.ozacc.mail.mock.EqualityCheck
クラスを追加。1.1 beta1
com.ozacc.mail.MultipartMail
クラスを追加。XMLMailBuilderImpl
、XMLVelocityMailBuilderImpl
が読み込むXMLで<![CDATA[]]>が利用できるように修正。MimeMessageBuilder
がMultipartMail
インスタンスを判別して、マルチパート対応のMimeMessage
を生成できるように修正。ozacc-mail.dtd
に<html>要素定義を追加。1.0.3
com.ozacc.mail.impl.VelocityLogSystem
クラスを追加。XMLVelocityMailBuilderImpl
とJDomXMLMailBuilder
で使用されいてるVelocityのログメッセージをcommons-logging経由で出力します。XMLVelocityMailBuilderImpl
クラスを修正。buildMail(File, VelocityContext)
、buildMail(String, VelocityContext)
メソッドで読み込まれるXMLファイルのコメントに、VTL(Velocity Template Language)を記述できるようになった。1.0.2
Cp932
クラスを用いて、文字化け懸念のある記号(全角のハイフンやチルダ等)を予めJISエンコードするように修正。Mail
クラスにclearTo(), clearCc(), clearBcc()
メソッドを追加。Mail
クラスとMockMail
クラスにコピーコンストラクタを追加。1.0.1
com.ozacc.mail.impl.XMLMailBuilderImpl
クラスを追加。com.ozacc.mail.impl.XMLVelocityMailBuilderImpl
クラスを追加。<?xml version="1.0" encoding="utf-8" ?> <!DOCTYPE mail PUBLIC "-//OZACC//DTD MAIL//EN" "http://www.ozacc.com/library/dtd/ozacc-mail.dtd"> <mail> <!-- Return-Path (?) --> <!-- [attribute] email メールアドレス (必須) --> <returnPath email="return@example.com" /> <!-- 差出人 (?) --> <!-- [attribute] email メールアドレス (必須) --> <!-- [attribute] name 差出人名 (オプション) --> <from email="from@example.com" name="差出人名" /> <!-- 送信先 (?) --> <recipients> <!-- Toアドレス (*) --> <!-- [attribute] email メールアドレス (必須) --> <!-- [attribute] name 宛名 (オプション) --> <to email="to@example.com" name="宛名" /> <!-- Ccアドレス (*) --> <!-- [attribute] email メールアドレス (必須) --> <!-- [attribute] name 宛名 (オプション) --> <cc email="cc@example.com" name="宛名" /> <!-- Bccアドレス (*) --> <!-- [attribute] email メールアドレス (必須) --> <bcc email="bcc@example.com" /> </recipients> <!-- 返信先 (?) --> <!-- [attribute] email メールアドレス (必須) --> <replyTo email="reply@example.com" /> <!-- 件名 (?) --> <subject><![CDATA[ 件名 ]]></subject> <!-- 本文 (?) --> <body><![CDATA[ 本文 ]]></body> <!-- HTMLメールの本文 (?) --> <html><![CDATA[ HTML ]]></html> </mail>