OSDN Git Service

Migrating from the deprecated oss-parent to the Nexus Staging Maven Plugin.
[spring-ext/ozacc-mail.git] / xdocs / index.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <document>
3
4         <properties>
5                 <title>ozacc-mail library</title>
6                 <author email="info@ozacc.com">Tomohiro Otsuka</author>
7         </properties>
8
9         <body>
10
11                 <section name="ozacc-mail library">
12                         <p>ozacc-mail libraryは、Spring FrameworkやSeasar2といったDIコンテナに組み込んで使用できるメール送信ライブラリです。DIコンテナ上での使用を想定していますが、DIコンテナ環境外での使用も可能です。</p>
13                 </section>
14
15                 <section name="システム条件">
16                         <p>JDK 1.4以上の環境でご使用ください。<br />また、次のJARファイルをクラスパスに含めてください。<br />
17                                 各ライブラリは、ozacc-mail libraryの配布ファイルには含まれていませんので、<a href="dependencies.html">Dependenciesページ</a>を参考に各自で取得してください。</p>
18                         
19                         <ul>
20                                 <li>JavaMail 1.3.1 (mail.jar) [必須]</li>
21                                 <li>JavaBeans Activation Framework(JAF) 1.0.2 (activation.jar) [必須]</li>
22                                 <li>Jakarta Commons Logging 1.0.4 [必須]<p /></li>
23                                 
24                                 <li>JDOM 1.0 [<code>com.ozacc.mail.impl.JDomXMLMailBuilder</code>を使用する場合]</li>
25                                 <li>Jakarta Velocity 1.4 [<code>com.ozacc.mail.impl.XMLVelocityMailBuilder</code>、<code>com.ozacc.mail.impl.JDomXMLMailBuilder</code>を使用する場合]</li>
26                                 <li>Jakarta Commons Collection 1.4 [<code>com.ozacc.mail.impl.XMLVelocityMailBuilder</code>、<code>com.ozacc.mail.impl.JDomXMLMailBuilder</code>を使用する場合]</li>
27                         </ul>
28                 </section>
29                 
30                 <section name="ダウンロード">
31                         <p>次のページからozacc-mail libraryの最新リリースをダウンロードできます。<br /><a href="http://sourceforge.jp/projects/spring-ext/">http://sourceforge.jp/projects/spring-ext/</a></p>
32                         <p>またMaven用のリモートレポジトリも用意しています。URLは「<code>http://spring-ext.sourceforge.jp/maven/</code>」です。このURLを<code>maven.repo.remote</code>プロパティに設定してください。<code>groupId</code>、<code>artifactId</code>は共に「<code>ozacc-mail</code>」です。</p>
33                 </section>
34                 
35                 <section name="ライセンス">
36                         <p><a href="http://www.opensource.org/licenses/lgpl-license.html">GNU Library or "Lesser" Public License</a> (LGPL).</p>
37         </section>
38                 
39                 <section name="APIドキュメント">
40                         <p><a href="apidocs/index.html">JavaDoc API</a></p>
41         </section>
42                 
43                 <section name="SendMail 使用方法 with Spring">
44                         <p><code>SendMail</code>は、JavaMail APIをラップし、メール送信のための至極シンプルなインターフェースを提供しています。提供しているメソッド名はたった一つ、<code>send()</code>です。メールデータを表す<code>com.ozacc.mail.Mail</code>インスタンスか、JavaMailの<code>MimeMessage</code>インスタンスを引数に指定すると、それを送信します。(これらの配列も指定可能です。)</p>
45                         
46                         <p><code>SendMail(SendMailImpl).send()</code>メソッドは、スレッドセーフな設計になっていますが、呼び出すスレッドの数だけSMTPサーバに接続します。通常の使用では問題にならないはずですが、メールサーバやその設定によっては注意が必要です。</p>
47                                 
48                         <p><code>SendMail</code>の使用方法を、Springと連携させる場合を例にとって説明します。</p>
49                         
50                         <p>▼applicationContext.xmlでのBean定義</p>
51                         <source>&lt;beans&gt;
52     &lt;bean id="sendMail" class="com.ozacc.mail.impl.SendMailImpl"&gt;
53         &lt;!-- SMTPサーバ --&gt;
54         &lt;property name="host"&gt;&lt;value&gt;smtp.example.com&lt;/value&gt;&lt;/property&gt;
55     &lt;/bean&gt;
56 &lt;/beans&gt;</source>
57                         
58                         <p>▼Javaソース</p>
59                         <source>// Mailインスタンスの生成
60 Mail mail = new Mail();
61 mail.setFrom("shop@example.com", "XXXオンラインショップ");
62 mail.addTo("misaki@foo.com", "伊東美咲さま");
63 mail.addBcc("order@example.com");
64 mail.setSubject("ご注文の確認");
65 mail.setText("お買い上げありがとうございました。\n\nご注文明細・・・");
66
67 // SendMailインスタンスの取得
68 SendMail sendMail = (SendMail)applicationContext.getBean("sendMail");
69
70 // メールの送信
71 sendMail.send(mail);</source>
72                         
73                         <p><code>sendMail.send(mail)</code>で、何らかの原因で送信に失敗すると、<code>com.ozacc.mail.MailException</code>がスローされます。<code>MailException</code>は非チェック例外なので、プログラムの要求に応じてキャッチしてください。</p>
74                         
75                 </section>
76
77                 <section name="MailBuilder 使用方法 with Spring">
78                 
79                         <p><code>MailBuilder</code>を使用すると、ファイルに記述されたメールデータから<code>Mail</code>インスタンスを生成できます。<br />さらに、<code>MailBuilder</code>インターフェースを継承した<code>VelocityMailBuilder</code>を使用すると、<code>Velocity</code>と連携して動的にメールデータを生成し、そのデータからMailインスタンスを生成できます。</p>
80                         
81                         <p>現バージョンでは、XML形式のメールデータを扱う<code>XMLMailBuilderImpl</code>クラスが提供されています。ここではその使用方法を、Springと連携させる場合を例にとって説明します。</p>
82                         
83                         <p>▼applicationContext.xmlでのBean定義</p>
84                         <source>&lt;beans&gt;
85     &lt;bean id="sendMail" class="com.ozacc.mail.impl.SendMailImpl"&gt;
86         &lt;property name="host"&gt;&lt;value&gt;smtp.example.com&lt;/value&gt;&lt;/property&gt;
87     &lt;/bean&gt;
88
89     &lt;bean id="mailBuilder" class="com.ozacc.mail.impl.XMLMailBuilderImpl" /&gt;
90 &lt;/beans&gt;</source>
91
92                         <p>▼Javaソース</p>
93                         <source>// MailBuilderインスタンスの取得
94 MailBuilder mailBuilder = (MailBuilder)applicationContext.getBean("mailBuilder");
95
96 // メールデータXMLファイルのパス (クラスパス上)
97 String path = "/com/example/mail/mail-template.xml";
98
99 // Mailインスタンスを生成
100 Mail mail = mailBuilder.buildMail(path);
101
102 // SendMailインスタンスの取得
103 SendMail sendMail = (SendMail)applicationContext.getBean("sendMail");
104
105 // メールの送信
106 sendMail.send(mail);</source>
107
108                         <p>▼mail-template.xml</p>
109                         <source>&lt;?xml version="1.0" encoding="utf-8" ?&gt;
110 &lt;!DOCTYPE mail PUBLIC "-//OZACC//DTD MAIL//EN" "http://www.ozacc.com/library/dtd/ozacc-mail.dtd"&gt;
111
112 &lt;mail&gt;
113
114     &lt;returnPath email="return@example.com" /&gt;
115
116     &lt;from email="from@example.com" name="差出人" /&gt;
117
118     &lt;recipients&gt;
119         &lt;to email="to1@example.com" name="宛先1" /&gt;
120         &lt;cc email="cc1@example.com" name="CC1" /&gt;
121         &lt;bcc email="bcc@example.com" /&gt;
122         &lt;cc email="cc2@example.com" /&gt;
123         &lt;to email="to2@example.com" /&gt;
124     &lt;/recipients&gt;
125
126     &lt;replyTo email="reply@example.com" /&gt;
127
128     &lt;!-- subject(件名)の前後のホワイトスペース(半角スペース、タブ、改行)は削除されます。 --&gt;
129     &lt;subject&gt;
130         件名
131     &lt;/subject&gt;
132
133     &lt;!-- body(本文)の前後のホワイトスペース(半角スペース、タブ、改行)は削除されます。 --&gt;
134     &lt;body&gt;
135         本文
136     &lt;/body&gt;
137
138 &lt;/mail&gt;</source>
139
140                 <p>DTDで定義されているように、ルート要素<code>&lt;mail&gt;</code>以外の全要素はオプションです。<br />
141                         例えば<code>&lt;from&gt;</code>要素だけ含んだXMLからは、<code>from</code>プロパティだけセットされた<ocde>Mail</ocde>インスタンスが生成されます。</p>
142
143                 <p>Velocityとの連携については、テストケース(<code>src/test/com/ozacc/mail/impl/XMLVelocityMailBuilderImplTest</code>)を参照してください。</p>
144
145                 </section>
146                 
147                 <section name="XMLMailFactoryBean 使用方法">
148                 
149                 <p><code>XMLMailFactoryBean</code>はSpringと連携している場合にのみ使用可能です。</p>
150
151                 <p>上述した<code>MailBuilder</code>を使ってXMLメールデータから<code>Mail</code>インスタンスを生成する場合、XMLファイルのロケーションを示すパスがソース内にハードコーディングされています。一般的にはアプリケーション側で、<code>MailBuilder</code>のインスタンスとXMLファイルのロケーションパスをプロパティとして保持するクラスを作り、DIコンテナでプロパティを設定するようにします。<br />
152                 Springを使用している場合、このようなクラスを作らずともXMLファイルのロケーションパスをソースから追い出し、コンテナ上でMailインスタンスを生成させることができます。</p>
153                 
154                 <p>▼applicationContext.xmlでのBean定義</p>
155                 <source>&lt;beans&gt;
156     &lt;bean id="sendMail" class="com.ozacc.mail.impl.SendMailImpl"&gt;
157         &lt;property name="host"&gt;&lt;value&gt;smtp.example.com&lt;/value&gt;&lt;/property&gt;
158     &lt;/bean&gt;
159
160     &lt;bean id="mail" class="com.ozacc.mail.spring.XMLMailFactoryBean"&gt;
161         &lt;!-- メールデータXMLファイルのパス (クラスパス上) --&gt;
162         &lt;property name="classPath"&gt;&lt;value&gt;/com/example/mail/mail-template.xml&lt;/value&gt;&lt;/property&gt;
163     &lt;/bean&gt;
164 &lt;/beans&gt;</source>
165
166                 <p>▼Javaソース</p>
167                 <source>// Mailインスタンスの生成、取得
168 Mail mail = (Mail)applicationContext.getBean("mail");
169
170 // SendMailインスタンスの取得
171 SendMail sendMail = (SendMail)applicationContext.getBean("sendMail");
172
173 // メールの送信
174 sendMail.send(mail);</source>
175
176                 <p><code>XMLMailFactoryBean</code>から生成される<code>Mail</code>インスタンスは、<code>prototype</code>です。つまりシングルトンではなく、呼び出すたびに新しい<code>Mail</code>インスタンスが生成されます。何かの理由で<code>Mail</code>インスタンスをシングルトンにしたい場合は、<code>XMLMailFactoryBean</code>の<code>singlton</code>プロパティに<code>true</code>をセットするだけです。</p>
177                 
178                 <p><code>XMLMailFactoryBean</code>では、Velocityと連携させて<code>Mail</code>インスタンスを生成することはできません。</p>
179                 </section>
180                 
181                 <section name="変更履歴">
182                         <p>1.1.2
183                                 <ul>
184                                 <li><code>VelocityMailBuilder</code>がテンプレートメールデータのキャッシュをサポートしました。</li>
185                                 </ul>
186                         </p>
187                         <p>1.1.1
188                                 <ul>
189                                 <li><code>XMLVelocityMailBuilderImpl</code>がXMLメールデータを読み込む際に、<code>&lt;![CDATA[]]&gt;</code>タグを削除しないように修正。</li>
190                                 </ul>
191                         </p>
192                         <p>1.1 rc2
193                                 <ul>
194                                 <li><code>SendMailImpl</code>と<code>SendMailProImpl</code>クラスに<code>setMessageId(String)</code>メソッドを追加。<code>com.ozacc.mail.impl.OMLMimeMessage</code>クラスを追加。Message-IDヘッダのドメイン部分がカスタマイズ可能に。</li>
195                                 <li><code>com.ozacc.mail.impl.DTDEntityResolver</code>クラスを追加。ネットワークアクセスなしでDTDを参照できるようになった。</li>
196                                 <li>本文がHTMLテキストだけの場合に生成される<code>MimeMessage</code>をマルチパートからシングルパートに修正。</li>
197                                 </ul>
198                         </p>
199                         <p>1.1 rc1
200                                 <ul>
201                                 <li><code>MultipartMail</code>クラスを<code>Mail</code>クラスに統合。</li>
202                                 <li>添付ファイルとして<code>InputStream</code>と<code>URL</code>インスタンスを指定できるメソッドを追加。</li>
203                                 <li><code>com.ozacc.mail.mock.EqualityCheck</code>クラスを追加。</li>
204                                 </ul>
205                         </p>
206                         <p>1.1 beta1
207                                 <ul>
208                                 <li><code>com.ozacc.mail.MultipartMail</code>クラスを追加。</li>
209                                 <li><code>XMLMailBuilderImpl</code>、<code>XMLVelocityMailBuilderImpl</code>が読み込むXMLで&lt;![CDATA[]]&gt;が利用できるように修正。</li>
210                                 <li><code>MimeMessageBuilder</code>が<code>MultipartMail</code>インスタンスを判別して、マルチパート対応の<code>MimeMessage</code>を生成できるように修正。</li>
211                                 <li><code>ozacc-mail.dtd</code>に&lt;html&gt;要素定義を追加。</li>
212                                 </ul>
213                         </p>
214                         <p>1.0.3
215                                 <ul>
216                                 <li><code>com.ozacc.mail.impl.VelocityLogSystem</code>クラスを追加。<code>XMLVelocityMailBuilderImpl</code>と<code>JDomXMLMailBuilder</code>で使用されいてるVelocityのログメッセージをcommons-logging経由で出力します。</li>
217                                 <li><del><code>XMLVelocityMailBuilderImpl</code>クラスを修正。<code>buildMail(File, VelocityContext)</code>、<code>buildMail(String, VelocityContext)</code>メソッドで読み込まれるXMLファイルのコメントに、VTL(Velocity Template Language)を記述できるようになった。</del></li>
218                                 </ul>
219                         </p>
220                         <p>1.0.2
221                                 <ul>
222                                 <li><code>Cp932</code>クラスを用いて、文字化け懸念のある記号(全角のハイフンやチルダ等)を予めJISエンコードするように修正。</li>
223                                 <li><code>Mail</code>クラスに<code>clearTo(), clearCc(), clearBcc()</code>メソッドを追加。</li>
224                                 <li><code>Mail</code>クラスと<code>MockMail</code>クラスにコピーコンストラクタを追加。</li>
225                                 </ul>
226                         </p>
227                         <p>1.0.1
228                                 <ul>
229                                 <li><code>com.ozacc.mail.impl.XMLMailBuilderImpl</code>クラスを追加。</li>
230                                 <li><code>com.ozacc.mail.impl.XMLVelocityMailBuilderImpl</code>クラスを追加。</li>
231                                 </ul>
232                         </p>
233         </section>
234                 
235                 <section name="メールデータXMLの全要素">
236                         <source>&lt;?xml version="1.0" encoding="utf-8" ?&gt;
237 &lt;!DOCTYPE mail PUBLIC "-//OZACC//DTD MAIL//EN" "http://www.ozacc.com/library/dtd/ozacc-mail.dtd"&gt;
238
239 &lt;mail&gt;
240     
241     &lt;!-- Return-Path (?) --&gt;
242     &lt;!-- [attribute] email メールアドレス (必須) --&gt;
243     &lt;returnPath email="return@example.com" /&gt;
244
245     &lt;!-- 差出人 (?) --&gt;
246     &lt;!-- [attribute] email メールアドレス (必須) --&gt;
247     &lt;!-- [attribute] name 差出人名 (オプション) --&gt;
248     &lt;from email="from@example.com" name="差出人名" /&gt;
249
250     &lt;!-- 送信先 (?) --&gt;
251     &lt;recipients&gt;
252         &lt;!-- Toアドレス (*) --&gt;
253         &lt;!-- [attribute] email メールアドレス (必須) --&gt;
254         &lt;!-- [attribute] name 宛名 (オプション) --&gt;
255         &lt;to email="to@example.com" name="宛名" /&gt;
256         
257         &lt;!-- Ccアドレス (*) --&gt;
258         &lt;!-- [attribute] email メールアドレス (必須) --&gt;
259         &lt;!-- [attribute] name 宛名 (オプション) --&gt;
260         &lt;cc email="cc@example.com" name="宛名" /&gt;
261         
262         &lt;!-- Bccアドレス (*) --&gt;
263         &lt;!-- [attribute] email メールアドレス (必須) --&gt;
264         &lt;bcc email="bcc@example.com" /&gt;
265     &lt;/recipients&gt;
266
267     &lt;!-- 返信先 (?) --&gt;
268     &lt;!-- [attribute] email メールアドレス (必須) --&gt;
269     &lt;replyTo email="reply@example.com" /&gt;
270
271     &lt;!-- 件名 (?) --&gt;
272     &lt;subject&gt;&lt;![CDATA[
273         件名
274     ]]&gt;&lt;/subject&gt;
275
276     &lt;!-- 本文 (?) --&gt;
277     &lt;body&gt;&lt;![CDATA[
278         本文
279     ]]&gt;&lt;/body&gt;
280     
281     &lt;!-- HTMLメールの本文 (?) --&gt;
282     &lt;html&gt;&lt;![CDATA[
283         HTML
284     ]]&gt;&lt;/html&gt;
285
286 &lt;/mail&gt;</source>
287                 </section>
288         
289         </body>
290 </document>