Project Documentation
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>