OSDN Git Service

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