javax.mail.internet
クラス MimeUtility

java.lang.Object
  上位を拡張 javax.mail.internet.MimeUtility

public final class MimeUtility
extends Object

様々な MIME 関連機能を提供するユーティリティクラスです。

MIME ヘッダを RFC 2047 に従ってエンコード及びデコードするメソッド一式があります。 そうしたヘッダの処理に関する簡単な説明を以下に示します。

RFC 822 メールヘッダは US-ASCII 文字だけを含まなければなりません。 US-ASCII 以外の文字を含むヘッダは US-ASCII 文字のみを含む様にエンコードする必要があります。 基本的に、この処理は BASE64 または QP を使用して特定の文字をエンコードする事を含みます。 詳細は RFC 2047 に説明があります。

Java において、String は (16 ビットの) Unicode 文字を含みます。 ASCII は Unicode のサブセットです (0 - 127 の範囲を占めます)。 ASCII 文字のみを含む String は既にメールで安全に使用出来ます。 String に US-ASCII 以外の文字が含まれる場合はエンコードが必要です。 この段階をより複雑にしているのは、Unicode があまり広く使用されている文字セットでない為、 まず String を別の文字セットに文字セットエンコードし、 その後に転送エンコーディングする必要がある事です。

メールで安全な String (例えば、SMTP 上の送信など) の実際のバイトを取得するには次の操作が必要です。

 
        byte[] bytes = string.getBytes("iso-8859-1");   
 
 

MimeMessage 及び MimeBodyPart 上の setHeader 及び addHeader メソッドは、 指定されたヘッダ値が US-ASCII 文字のみを含む Unicode 文字列であると仮定します。 従って、それらの呼び出し元は渡す値が US-ASCII 以外の文字を含まない事を確認しなければなりません。 このクラス内のメソッドは、この実行に役立ちます。

MimeMessage 及び MimeBodyPart 上の getHeader メソッドファミリーは、 生ヘッダ値を返します。これらは RFC 2047 に従ってエンコードされる可能性があります。 その場合、Unicode 文字列にデコードされる必要があります。 このクラス内のメソッドは、この実行に役立ちます。

Several System properties control strict conformance to the MIME spec. Note that these are not session properties but must be set globally as System properties.

The mail.mime.decodetext.strict property controls decoding of MIME encoded words. The MIME spec requires that encoded words start at the beginning of a whitespace separated word. Some mailers incorrectly include encoded words in the middle of a word. If the mail.mime.decodetext.strict System property is set to "false", an attempt will be made to decode these illegal encoded words. The default is true.

The mail.mime.encodeeol.strict property controls the choice of Content-Transfer-Encoding for MIME parts that are not of type "text". Often such parts will contain textual data for which an encoding that allows normal end of line conventions is appropriate. In rare cases, such a part will appear to contain entirely textual data, but will require an encoding that preserves CR and LF characters without change. If the mail.mime.encodeeol.strict System property is set to "true", such an encoding will be used when necessary. The default is false.

In addition, the mail.mime.charset System property can be used to specify the default MIME charset to use for encoded words and text parts that don't otherwise specify a charset. Normally, the default MIME charset is derived from the default Java charset, as specified in the file.encoding System property. Most applications will have no need to explicitly set the default MIME charset. In cases where the default MIME charset to be used for mail messages is different than the charset used for files stored on the system, this property should be set.


フィールドの概要
static int ALL
           
 
メソッドの概要
static InputStream decode(InputStream is, String encoding)
          指定された入力ストリームをデコードします。
static String decodeText(String etext)
          "構造を持たない" ヘッダ、つまり、RFC 822 で '*text' と定義されているヘッダをデコードします。
static String decodeWord(String eword)
          文字列は、RFC 2047 の "encoded-word" 構文解析規則を使用して構文解析されます。
static OutputStream encode(OutputStream os, String encoding)
          指定された出力ストリームにエンコーダをラップします。
static OutputStream encode(OutputStream os, String encoding, String filename)
          指定された出力ストリームにエンコーダをラップします。
static String encodeText(String text)
          RFC 822 "text" トークンを RFC 2047 に従ったメールに安全な形式にエンコードします。
static String encodeText(String text, String charset, String encoding)
          RFC 822 "text" トークンを RFC 2047 に従ったメールに安全な形式にエンコードします。
static String encodeWord(String word)
          RFC 822 "word" トークンを RFC 2047 に従ったメールに安全な形式にエンコードします。
static String encodeWord(String word, String charset, String encoding)
          RFC 822 "word" トークンを RFC 2047 に従ったメールに安全な形式にエンコードします。
static String fold(int used, String s)
          Fold a string at linear whitespace so that each line is no longer than 76 characters, if possible.
static String getDefaultJavaCharset()
          システムの現在のデフォルトロケールに対応するデフォルトの文字セットを取得します。
static String getEncoding(DataSource ds)
          メールで安全に使用出来る様にする為、 このデータソースの入力ストリームに適用されなければならない content-transfer-encoding を取得します。
static String javaCharset(String charset)
          MIME キャラクタセット名を有効な Java キャラクタセット名へ変換します。
static String mimeCharset(String charset)
          Java キャラクタセットを MIME キャラクタセット名へ変換します。
static String quote(String word, String specials)
          指定された特殊文字一覧の任意の文字が単語に含まれている場合に、 単語を引用するユーティリティメソッドです。
static String unfold(String s)
          Unfold a folded header.
 
クラス java.lang.Object から継承されたメソッド
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

フィールドの詳細

ALL

public static final int ALL
関連項目:
定数フィールド値
メソッドの詳細

getEncoding

public static String getEncoding(DataSource ds)
メールで安全に使用出来る様にする為、 このデータソースの入力ストリームに適用されなければならない content-transfer-encoding を取得します。

ここで使用されるアルゴリズムは次の通りです。

パラメータ:
ds - DataSource
戻り値:
エンコーディング。"7bit"、"quoted-printable"、又は "base64"

decode

public static InputStream decode(InputStream is,
                                 String encoding)
                          throws MessagingException
指定された入力ストリームをデコードします。 返される入力ストリームはデコードされた入力ストリームです。 RFC 2045 で定義されている全てのエンコーディングはここでサポートされます。 これには "base64"、"quoted-printable"、"7bit"、"8bit"、及び "binary" が含まれます。 さらに、"uuencode" もサポートされます。

パラメータ:
is - 入力ストリーム
encoding - ストリームのエンコーディング
戻り値:
デコードされた入力ストリーム
例外:
MessagingException

encode

public static OutputStream encode(OutputStream os,
                                  String encoding)
                           throws MessagingException
指定された出力ストリームにエンコーダをラップします。 RFC 2045 で定義されている全てのエンコーディングはここでサポートされます。 これには "base64"、"quoted-printable"、"7bit"、"8bit"、及び "binary" が含まれます。 さらに、"uuencode" もサポートされます。

パラメータ:
os - 出力ストリーム
encoding - ストリームのエンコーディング
戻り値:
指定されたエンコーディングを適用した出力ストリーム
例外:
MessagingException

encode

public static OutputStream encode(OutputStream os,
                                  String encoding,
                                  String filename)
                           throws MessagingException
指定された出力ストリームにエンコーダをラップします。 RFC 2045 で定義されている全てのエンコーディングはここでサポートされます。 これには "base64"、"quoted-printable"、"7bit"、"8bit"、及び "binary" が含まれます。 さらに、"uuencode" もサポートされます。 filename パラメータは "uuencode" エンコーディングと共に使用され、 エンコードされた出力に含まれます。

パラメータ:
os - 出力ストリーム
encoding - ストリームのエンコーディング
filename - エンコードされるファイルの名前 (uuencode と共にのみ使用されます)
戻り値:
指定されたエンコーディングを適用した出力ストリーム
例外:
MessagingException
導入されたバージョン:
JavaMail 1.2

encodeText

public static String encodeText(String text)
                         throws UnsupportedEncodingException
RFC 822 "text" トークンを RFC 2047 に従ったメールに安全な形式にエンコードします。

指定された Unicode 文字列は US-ASCII 以外の文字について検査されます。 文字列に US-ASCII 文字だけが含まれる場合はそのまま返されます。 文字列に US-ASCII 以外の文字が含まれる場合、 まずプラットフォームのデフォルトの文字セットを使用して文字エンコードされ、 次に B または Q エンコーディングを使用して転送エンコードされます。 結果のバイトは ASCII 文字のみを含む Unicode 文字列として返されます。

このメソッドは "構造を持たない" RFC 822 ヘッダをエンコードする為にだけ使用されなければなりません。

使用例:

 
  MimePart part = ...
  String rawvalue = "FooBar Mailer, Japanese version 1.1"
  try {
    // If we know for sure that rawvalue contains only US-ASCII 
    // characters, we can skip the encoding part
    part.setHeader("X-mailer", MimeUtility.encodeText(rawvalue));
  } catch (UnsupportedEncodingException e) {
    // encoding failure
  } catch (MessagingException me) {
   // setHeader() failure
  }
 
 

パラメータ:
text - Unicode 文字列
戻り値:
US-ASCII 文字のみを含む Unicode 文字列
例外:
UnsupportedEncodingException - エンコーディングに失敗した場合

encodeText

public static String encodeText(String text,
                                String charset,
                                String encoding)
                         throws UnsupportedEncodingException
RFC 822 "text" トークンを RFC 2047 に従ったメールに安全な形式にエンコードします。

指定された Unicode 文字列は US-ASCII 以外の文字について検査されます。 文字列に US-ASCII 文字だけが含まれる場合はそのまま返されます。 文字列に US-ASCII 以外の文字が含まれる場合、 まず指定された文字セットを使用して文字エンコードされ、 次に B または Q エンコーディングを使用して転送エンコードされます。 結果のバイトは ASCII 文字のみを含む Unicode 文字列として返されます。

このメソッドは "構造を持たない" RFC 822 ヘッダをエンコードする為にだけ使用されなければなりません。

パラメータ:
text - ヘッダ値
charset - キャラクタセット。このパラメータが null の場合、プラットフォームのデフォルトのキャラクタセットが使用されます
encoding - 使用されるエンコーディング。 現在サポートされている値は "B" 及び "Q" です。 このパラメータが null の時、 エンコードされる文字の殆どが ASCII 文字セットにある場合は "Q" エンコーディングが使用され、 そうでない場合は "B" エンコーディングが使用されます
戻り値:
US-ASCII 文字のみを含む Unicode 文字列
例外:
UnsupportedEncodingException

decodeText

public static String decodeText(String etext)
                         throws UnsupportedEncodingException
"構造を持たない" ヘッダ、つまり、RFC 822 で '*text' と定義されているヘッダをデコードします。

文字列は RFC 2047, Section 6.1.1 で規定されているアルゴリズムを使用してデコードされます。 任意のシーケンスで文字列変換に失敗すると、UnsupportedEncodingException がスローされます。 String が RFC 2047 形式でエンコードされたヘッダでない場合はそのまま返されます。

使用例:

 
  MimePart part = ...
  String rawvalue = null;
  String  value = null;
  try {
    if ((rawvalue = part.getHeader("X-mailer")[0]) != null)
      value = MimeUtility.decodeText(rawvalue);
  } catch (UnsupportedEncodingException e) {
      // Don't care
      value = rawvalue;
  } catch (MessagingException me) { }
 
  return value;
 
 

パラメータ:
etext - エンコードされている可能性のある値
例外:
UnsupportedEncodingException - キャラクタセットの変換が失敗した場合

encodeWord

public static String encodeWord(String word)
                         throws UnsupportedEncodingException
RFC 822 "word" トークンを RFC 2047 に従ったメールに安全な形式にエンコードします。

指定された Unicode 文字列は US-ASCII 以外の文字について検査されます。 文字列に US-ASCII 文字だけが含まれる場合はそのまま返されます。 文字列に US-ASCII 以外の文字が含まれる場合、 まずプラットフォームのデフォルトの文字セットを使用して文字エンコードされ、 次に B 又は Q エンコーディングを使用して転送エンコードされます。 結果のバイトは ASCII 文字のみを含む Unicode 文字列として返されます。

このメソッドは RFC 822 "phrases" を作成する時に使用される事を意図しています。 例えば、InternetAddress クラスはこれを使用して 'phrase' コンポーネントをエンコードします。

パラメータ:
word - Unicode 文字列
戻り値:
US-ASCII 文字のみを含む Unicode 文字列の配列
例外:
UnsupportedEncodingException - エンコーディングに失敗した場合

encodeWord

public static String encodeWord(String word,
                                String charset,
                                String encoding)
                         throws UnsupportedEncodingException
RFC 822 "word" トークンを RFC 2047 に従ったメールに安全な形式にエンコードします。

指定された Unicode 文字列は US-ASCII 以外の文字について検査されます。 文字列に US-ASCII 文字だけが含まれる場合はそのまま返されます。 文字列に US-ASCII 以外の文字が含まれる場合、 まず指定された文字セットを使用して文字エンコードされ、 次に B 又は Q エンコーディングを使用して転送エンコードされます。 結果のバイトは ASCII 文字のみを含む Unicode 文字列として返されます。

パラメータ:
word - Unicode 文字列
charset - MIME キャラクタセット
encoding - 使用されるエンコーディング。 現在サポートされている値は "B" 及び "Q" です。 このパラメータが null の時、 エンコードされる文字の殆どが ASCII 文字セットにある場合は "Q" エンコーディングが使用され、 そうでない場合は "B" エンコーディングが使用されます。
戻り値:
US-ASCII 文字のみを含む Unicode 文字列
例外:
UnsupportedEncodingException - エンコーディングに失敗した場合

decodeWord

public static String decodeWord(String eword)
                         throws ParseException,
                                UnsupportedEncodingException
文字列は、RFC 2047 の "encoded-word" 構文解析規則を使用して構文解析されます。 構文解析に失敗した場合、ParseException がスローされます。 そうでない場合は、転送デコードされた後、Unicode に文字列変換されます。 文字列変換に失敗すると、UnsupportedEncodingException がスローされます。

パラメータ:
eword - エンコードされている可能性のある値
例外:
ParseException - 文字列が RFC 2047 で規定されている encoded-word でない場合
UnsupportedEncodingException - キャラクタセット変換が失敗した場合

quote

public static String quote(String word,
                           String specials)
指定された特殊文字一覧の任意の文字が単語に含まれている場合に、 単語を引用するユーティリティメソッドです。

HeaderTokenizer クラスは、 MIME と RFC 822 という 2 組の特殊区切り文字セットを定義します。

一般にこのメソッドは、RFC 822 及び MIME ヘッダフィールドの生成時に使用されます。

パラメータ:
word - 引用される単語
specials - 特殊文字のセット
戻り値:
恐らく引用される単語
関連項目:
HeaderTokenizer.MIME, HeaderTokenizer.RFC822

fold

public static String fold(int used,
                          String s)
Fold a string at linear whitespace so that each line is no longer than 76 characters, if possible. If there are more than 76 non-whitespace characters consecutively, the string is folded at the first whitespace after that sequence. The parameter used indicates how many characters have been used in the current line; it is usually the length of the header name.

Note that line breaks in the string aren't escaped; they probably should be.

パラメータ:
used - characters used in line so far
s - the string to fold
戻り値:
the folded string
導入されたバージョン:
JavaMail 1.4

unfold

public static String unfold(String s)
Unfold a folded header. Any line breaks that aren't escaped and are followed by whitespace are removed.

パラメータ:
s - the string to unfold
戻り値:
the unfolded string
導入されたバージョン:
JavaMail 1.4

javaCharset

public static String javaCharset(String charset)
MIME キャラクタセット名を有効な Java キャラクタセット名へ変換します。

パラメータ:
charset - MIME キャラクタセット名
戻り値:
Java キャラクタセット相当。 適切なマッピングが使用できない場合、渡されるキャラクタセット自体が返されます。

mimeCharset

public static String mimeCharset(String charset)
Java キャラクタセットを MIME キャラクタセット名へ変換します。

JDK の将来のバージョン (1.2 の後) はこの機能を提供する可能性がある事に注意して下さい。 その場合、このメソッドが推奨されなくなることが考えられます。

パラメータ:
charset - JDK のキャラクタセット名
戻り値:
MIME/IANA 相当。 マッピングが使用できない場合、渡されるキャラクタセット自体が返されます。
導入されたバージョン:
JavaMail 1.1

getDefaultJavaCharset

public static String getDefaultJavaCharset()
システムの現在のデフォルトロケールに対応するデフォルトの文字セットを取得します。

戻り値:
システムのデフォルトロケールのデフォルトの Java キャラクタセット (MIME キャラクタセットではない)。
導入されたバージョン:
JavaMail 1.1