001/*
002 * Copyright (c) 2009 The openGion Project.
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 *     http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND,
013 * either express or implied. See the License for the specific language
014 * governing permissions and limitations under the License.
015 */
016package org.opengion.fukurou.mail;
017
018import jakarta.mail.internet.InternetAddress;
019import jakarta.mail.internet.MimeMessage;
020
021/**
022 * MailCharset は、E-Mail 送信時のエンコードに応じた処理を行う為の、
023 * インターフェースです。
024 *
025 * E-Mail で日本語を送信する場合、ISO-2022-JP(JISコード)化して、7bit で
026 * エンコードして送信する必要がありますが、Windows系の特殊文字や、unicodeと
027 * 文字のマッピングが異なる文字などが、文字化けします。
028 * 対応方法としては、
029 * 『１．Windows-31J/UTF-8 + 8bit 送信』
030 * 『２．ISO-2022-JP に独自変換 + 7bit 送信』
031 * の方法があります。
032 * 今回、この２つの方法について、それぞれサブクラス化を行い、処理できるように
033 * したのが、このインターフェース、および、サブクラスです。
034 *
035 * 『１．Windows-31J/UTF-8 + 8bit 送信』の方法は、通常の JavaMail API に準拠して
036 * <del>6.3.8.0 (2015/09/11) 処理を行う、Mail_Windows31J_Charset サブクラスで実装しています。</del>
037 * 処理を行う、Mail_8bit_Charset サブクラスで実装しています。
038 * 古いメイラーおよび、古いメールサーバーではメール転送できない為、
039 * この方式は、社内で使用する場合のみに、利用できますが、主としてWindows系の
040 * 社内システムにおいては、こちらの方が、なにかとトラブルは少ないと思います。
041 *
042 * 『２．ISO-2022-JP に独自変換 + 7bit 送信』の実装は、
043 * JAVA PRESS Vol.37 (http://www.gihyo.co.jp/magazines/javapress)の
044 * 【特集1】 決定版！ サーバサイドJavaの日本語処理
045 *  第3章：JavaMailの日本語処理プログラミング……木下信
046 *“マルチプラットフォーム”な日本語メール送信術 完全解説
047 * でのサンプルアプリケーション
048 * http://www.gihyo.co.jp/book/2004/225371/download/toku1_3.zip
049 * を、使用して、Mail_ISO2022JP_Charset サブクラスで実装しています。
050 *
051 * これらのサブクラスは、MailCharsetFactory ファクトリクラスより、作成されます。
052 * その場合、引数のキャラクタセット名は、Windows-31J、MS932、UTF-8 か、それ以外となっています。
053 * それ以外が指定された場合は、ISO-2022-JP を使用します。
054 *
055 * @version  4.0
056 * @author   Kazuhiko Hasegawa
057 * @since    JDK5.0,
058 */
059public interface MailCharset {
060
061        /**
062         * テキストをセットします。
063         * Part#setText() の代わりにこちらを使うようにします。
064         *
065         * ※ 内部で、MessagingException が発生した場合は、RuntimeException に変換されて throw されます。
066         *
067         * @param mimeMsg MimeMessage最大取り込み件数
068         * @param text    設定するテキスト
069         */
070        void setTextContent( MimeMessage mimeMsg, String text ) ;
071
072        /**
073         * 日本語を含むヘッダ用テキストを生成します。
074         * 変換結果は ASCII なので、これをそのまま setSubject や InternetAddress
075         * のパラメタとして使用してください。
076         *
077         * ※ 内部で、UnsupportedEncodingException が発生した場合は、RuntimeException に変換されて throw されます。
078         *
079         * @param text    設定するテキスト
080         *
081         * @return      日本語を含むヘッダ用テキスト
082         */
083        String encodeWord( String text ) ;
084
085        /**
086         * 日本語を含むアドレスを生成します。
087         * personal に、日本語が含まれると想定しています。
088         * サブクラスで、日本語処理を行う場合の方法は、それぞれ異なります。
089         *
090         * ※ 内部で、UnsupportedEncodingException が発生した場合は、RuntimeException に変換されて throw されます。
091         *
092         * @param address    アドレス部分
093         * @param personal   日本語の説明部分
094         *
095         * @return      日本語を含むアドレス
096         */
097        InternetAddress getAddress( String address,String personal ) ;
098
099        /**
100         * Content-Transfer-Encoding を指定する場合の ビット数を返します。
101         *
102         * Windows系は、8bit / ISO-2022-JP 系は、7bit になります。
103         *
104         * @return      ビット数
105         */
106        String getBit() ;
107}