ozacc-mail library

##### Project Documentation

- About ozacc-mail library
- Project Info
- Project Reports
- Development Process

## ozacc-mail library

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

## システム条件

JDK 1.4以上の環境でご使用ください。
また、次のJARファイルをクラスパスに含めてください。
各ライブラリは、ozacc-mail libraryの配布ファイルには含まれていませんので、Dependenciesページを参考に各自で取得してください。

- JavaMail 1.3.1 (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.XMLVelocityMailBuilder`、`com.ozacc.mail.impl.JDomXMLMailBuilder`を使用する場合]
- Jakarta Commons Collection 1.4 [`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`」です。

## ライセンス

GNU Library or "Lesser" Public License (LGPL).

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

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

## 変更履歴

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を参照できるようになった。
- 本文がHTMLテキストだけの場合に生成される`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の全要素

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