ozacc-mail library

ozacc-mail libraryは、Spring FrameworkやSeasar2といったDIコンテナに組み込んで使用できるメール送信ライブラリです。DIコンテナ上での使用を想定していますが、DIコンテナ環境外での使用も可能です。

システム条件

JDK 1.4以上の環境でご使用ください。

また、次のJARファイルをクラスパスに含めてください。

各ライブラリは、ozacc-mail libraryの配布ファイルには含まれていませんので、Dependenciesページを参考に各自で取得してください。

  • JavaMail 1.3.2 (mail.jar) [必須]
  • JavaBeans Activation Framework(JAF) 1.0.2 (activation.jar) [必須]
  • Jakarta Commons Logging 1.0.4 [必須]

  • JDOM 1.0 [com.ozacc.mail.impl.JDomXMLMailBuilderを使用する場合]
  • Jakarta Velocity 1.4 [com.ozacc.mail.impl.XMLVelocityMailBuildercom.ozacc.mail.impl.JDomXMLMailBuilderを使用する場合]
  • Jakarta Commons Collection 1.4 [com.ozacc.mail.impl.XMLVelocityMailBuildercom.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プロパティに設定してください。groupIdartifactIdは共に「ozacc-mail」です。

APIドキュメント

JavaDoc API

SendMail 使用方法 with Spring

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 使用方法 with Spring

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プロパティだけセットされたMailインスタンスが生成されます。

Velocityとの連携については、テストケース(src/test/com/ozacc/mail/impl/XMLVelocityMailBuilderImplTest)を参照してください。

XMLMailFactoryBean 使用方法

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インスタンスをシングルトンにしたい場合は、XMLMailFactoryBeansingltonプロパティにtrueをセットするだけです。

XMLMailFactoryBeanでは、Velocityと連携させてMailインスタンスを生成することはできません。

変更履歴

1.1.4

  • SMTPサーバへの接続タイムアウトを設定できるようにSendMailImplSendMailProImplクラスを修正。
  • MailクラスのtoString()メソッドを、Reply-Toアドレスも出力するように修正。

1.1.3

  • JavaMailのバージョンを1.3.2に。1.3.1のままでも全て機能します。
  • com.ozacc.mail.impl.AbstractXMLMailBuildercom.ozacc.mail.impl.OMLMimeMessagecom.ozacc.mail.impl.DTDEntityResolvercom.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

  • SendMailImplSendMailProImplクラスにsetMessageId(String)メソッドを追加。com.ozacc.mail.impl.OMLMimeMessageクラスを追加。Message-IDヘッダのドメイン部分がカスタマイズ可能に。
  • com.ozacc.mail.impl.DTDEntityResolverクラスを追加。ネットワークアクセスなしでDTDを参照できるようになった。
  • 本文がHTMLテキストだけの場合に生成されるMimeMessageをマルチパートからシングルパートに修正。

1.1 rc1

  • MultipartMailクラスをMailクラスに統合。
  • 添付ファイルとしてInputStreamURLインスタンスを指定できるメソッドを追加。
  • com.ozacc.mail.mock.EqualityCheckクラスを追加。

1.1 beta1

  • com.ozacc.mail.MultipartMailクラスを追加。
  • XMLMailBuilderImplXMLVelocityMailBuilderImplが読み込むXMLで<![CDATA[]]>が利用できるように修正。
  • MimeMessageBuilderMultipartMailインスタンスを判別して、マルチパート対応のMimeMessageを生成できるように修正。
  • ozacc-mail.dtdに<html>要素定義を追加。

1.0.3

  • com.ozacc.mail.impl.VelocityLogSystemクラスを追加。XMLVelocityMailBuilderImplJDomXMLMailBuilderで使用されいてる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の全要素

<?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>