java.text
クラス MessageFormat

java.lang.Object
  |
  +--java.text.Format
        |
        +--java.text.MessageFormat

すべての実装インタフェース:

Cloneable, Serializable

public class MessageFormat

extends Format

MessageFormat は、連結されたメッセージを、言語に依存しない方法で構築するためのものです。エンドユーザ用に表示するメッセージは、この方法で構築してください。

MessageFormat は、1 組のオブジェクトをフォーマットし、フォーマットした文字列をパターンの適切な場所に挿入します。

注: MessageFormat が他の Format クラスと異なる点は、MessageFormat オブジェクトを (MessageFormat スタイルのファクトリメソッドではなく) そのコンストラクタの 1 つで作成するということです。MessageFormat ではロケールに対して複雑なセットアップが必要ないので、ファクトリメソッドは必要ありません。実際、MessageFormat に、ロケール固有の動作は一切実装されていません。

この使用例を次に示します。

 Object[] arguments = {
     new Integer(7),
     new Date(System.currentTimeMillis()),
     "a disturbance in the Force"
 };

 String result = MessageFormat.format(
     "At {1,time} on {1,date}, there was {2} on planet {0,number,integer}.",
     arguments);

 output: At 12:30 PM on Jul 3, 2053, there was a disturbance
           in the Force on planet 7.

 

一般に、メッセージフォーマットはリソースから与えられ、引数は実行時に動的に設定されます。

例 2:

 Object[] testArgs = {new Long(3), "MyDisk"};

 MessageFormat form = new MessageFormat(
     "The disk \"{1}\" contains {0} file(s).");

 System.out.println(form.format(testArgs));

 // output, with different testArgs
 output: The disk "MyDisk" contains 0 file(s).
 output: The disk "MyDisk" contains 1 file(s).
 output: The disk "MyDisk" contains 1,273 file(s).
 

このパターンは次の形式です

 messageFormatPattern := string ( "{" messageFormatElement "}" string )*

 messageFormatElement := argument { "," elementFormat }

 elementFormat := "time" { "," datetimeStyle }
                | "date" { "," datetimeStyle }
                | "number" { "," numberStyle }
                | "choice" { "," choiceStyle }

 datetimeStyle := "short"
                  | "medium"
                  | "long"
                  | "full"
                  | dateFormatPattern

 numberStyle := "currency"
               | "percent"
               | "integer"
               | numberFormatPattern

 choiceStyle := choiceFormatPattern
 

elementFormat がない場合、引数は文字列でなければなりません (この文字列が使用される)。dateTimeStyle も numberStyle もないと、デフォルトのフォーマットが使用されます (NumberFormat.getInstance、DateFormat.getTimeInstance、DateFormat.getInstance など)。

文字列で単一引用符を使うと、必要に応じて中括弧 ({) を引用することができます。本来の単一引用符は '' で表します。messageFormatElement の中では、引用符は除去されません。たとえば、{1,number,$'#',##} と指定すると、ハッシュ記号 (#) が引用された数値フォーマットが生成されます。結果は、「$#31,45」のようになります。

パターンを使用する場合、引用されていない括弧があれば、それらは一致しなければなりません。つまり、「ab {0} de」と「ab '}' de」は正しいのですが、「ab {0'}'de」と「ab } de」は正しくありません。

この引数は 0 から 9 の数字です。この数字は、フォーマットする配列で指定される引数の数に対応します。

列の中に使用されない引数があってもかまいません。引数が足りなかったり、指定されたフォーマットに対する正しいクラスのものでないと、ParseException がスローされます。format はまず、その引数に対し、Format オブジェクトが setFormats メソッドで指定されているかどうかをチェックします。指定されていれば、format はその Format オブジェクトを使って、その引数をフォーマットします。指定されていなければ、引数はそのオブジェクトの型に基づいてフォーマットされます。引数が Number であれば、format は NumberFormat.getInstance を使って引数をフォーマットします。引数が Date であれば、format は DateFormat.getDateTimeInstance を使って引数をフォーマットします。それ以外の場合は、toString メソッドを使用します。

さらに複雑なパターンの場合、ChoiceFormat を使って次のように出力を得ることもできます。

 MessageFormat form = new MessageFormat("The disk \"{1}\" contains {0}.");
 double[] filelimits = {0,1,2};
 String[] filepart = {"no files","one file","{0,number} files"};
 ChoiceFormat fileform = new ChoiceFormat(filelimits, filepart);
 form.setFormat(1,fileform); // NOT zero, see below

 Object[] testArgs = {new Long(12373), "MyDisk"};

 System.out.println(form.format(testArgs));

 // output, with different testArgs
 output: The disk "MyDisk" contains no files.
 output: The disk "MyDisk" contains one file.
 output: The disk "MyDisk" contains 1,273 files.
 

これは、上の例のようにプログラム的に行うか、次のようにパターン (詳細は、ChoiceFormat を参照) を使って行うことができます。

 form.applyPattern(
    "There {0,choice,0#are no files|1#is one file|1#are {0,number,integer} files}.");
 

注: 前述のように、MessageFormat の ChoiceFormat で生成される文字列は、特別に処理されます。複数の { を使ってサブフォーマットを表し、繰り返しを行います。MessageFormat と ChoiceFormat を両方とも (文字列パターンではなく) プログラム的に作成する場合には、再帰的に繰り返すフォーマットを作成しないように注意してください。永久ループになります。

注: フォーマットは、文字列における変数の順に従って数えられます。これは、引数の数え方と同じではありません。たとえば、abc{2}def{3}ghi{0}... の場合、

• format0 は最初の変数 {2} に作用します。
• format1 は 2 つ目の変数 {3} に作用します。
• format2 は 3 つ目の変数 {0} に作用します。
• 以下、同様です。

1 つの引数が文字列内で複数回解析されると、最後に一致するものが解析の最終結果になります。次に例を示します。

 MessageFormat mf = new MessageFormat("{0,number,#.##}, {0,number,#.#}");
 Object[] objs = {new Double(3.1415)};
 String result = mf.format( objs );
 // result now equals "3.14, 3.1"
 objs = null;
 objs = mf.parse(result, new ParsePosition(0));
 // objs now equals {new Double(3.1)}
 

同様に、同じ引数が複数回出てくるパターンを使って MessageFormat オブジェクトを解析すると、最後に一致するものが返されます。次に例を示します。

 MessageFormat mf = new MessageFormat("{0}, {0}, {0}");
 String forParsing = "x, y, z";
 Object[] objs = mf.parse(forParsing, new ParsePosition(0));
 // result now equals {new String("z")}
 

setLocale に続けて applyPattern (場合によっては setFormat も) を使うと、異なるロケールで MessageFormat を初期化し直すことができます。

関連項目:

Locale, Format, NumberFormat, DecimalFormat, ChoiceFormat, 直列化された形式

コンストラクタの概要

MessageFormat(String pattern)
指定されたパターンで構築します。

メソッドの概要

void	applyPattern(String newPattern) パターンを設定します。
Object	clone() Cloneable をオーバーライドします。
boolean	equals(Object obj) 2 つのメッセージフォーマットオブジェクトの間の等号比較です。
StringBuffer	format(Object[] source, StringBuffer result, FieldPosition ignore) フォーマットされたオブジェクトとともにパターンを返します。
StringBuffer	format(Object source, StringBuffer result, FieldPosition ignore) フォーマットされたオブジェクトとともにパターンを返します。
static String	format(String pattern, Object[] arguments) 簡易ルーチンです。
Format[]	getFormats() setFormats で設定されたフォーマットを取得します。
Locale	getLocale() ロケールを取得します。
int	hashCode() メッセージフォーマットオブジェクトのハッシュコードを生成します。
Object[]	parse(String source) 文字列を解析します。
Object[]	parse(String source, ParsePosition status) 文字列を解析します。
Object	parseObject(String text, ParsePosition status) 文字列を解析します。
void	setFormat(int variable, Format newFormat) 変数に使うフォーマットをパターンに設定します。
void	setFormats(Format[] newFormats) パラメータで使用するフォーマットを設定します。
void	setLocale(Locale theLocale) 指定されたパターンで構築し、引数に対してそのパターンでフォーマットします。
String	toPattern() パターンを取得します。

クラス java.text.Format から継承したメソッド

format, parseObject

クラス java.lang.Object から継承したメソッド

finalize, getClass, notify, notifyAll, toString, wait, wait, wait

コンストラクタの詳細

MessageFormat

public MessageFormat(String pattern)

指定されたパターンで構築します。

関連項目:

applyPattern(java.lang.String)

メソッドの詳細

setLocale

public void setLocale(Locale theLocale)

指定されたパターンで構築し、引数に対してそのパターンでフォーマットします。

getLocale

public Locale getLocale()

ロケールを取得します。このロケールは、デフォルトの数値や日付のフォーマット情報を取得するために使用します。

applyPattern

public void applyPattern(String newPattern)

パターンを設定します。クラスの説明を参照してください。

toPattern

public String toPattern()

パターンを取得します。クラスの説明を参照してください。

setFormats

public void setFormats(Format[] newFormats)

パラメータで使用するフォーマットを設定します。フォーマットの番号付けについては、クラスの説明を参照してください。

setFormat

public void setFormat(int variable,
                      Format newFormat)

変数に使うフォーマットをパターンに設定します。

パラメータ:

variable - フォーマット内の変数を示すゼロから始まる番号。これは引数の個数ではない。variable が範囲外にある場合は ArrayIndexOutOfBoundsException がスローされる

newFormat - 指定された変数に使うフォーマット

getFormats

public Format[] getFormats()

setFormats で設定されたフォーマットを取得します。フォーマットの番号付けについては、クラスの説明を参照してください。

format

public final StringBuffer format(Object[] source,
                                 StringBuffer result,
                                 FieldPosition ignore)

フォーマットされたオブジェクトとともにパターンを返します。ソースが null の場合は元のパターンが返されます。ソースが null オブジェクトを保持する場合は、フォーマットされた結果によって各引数が文字列 null に置き換えられます。

パラメータ:

source - フォーマットするかまたは置き換えるオブジェクトからなる配列

result - テキストが追加される位置

ignore - 有用でない状態が返される

format

public static String format(String pattern,
                            Object[] arguments)

簡易ルーチンです。MessageFormat の明示的な生成は回避されますが、将来最適化を行うことはできません。

format

public final StringBuffer format(Object source,
                                 StringBuffer result,
                                 FieldPosition ignore)

フォーマットされたオブジェクトとともにパターンを返します。ソースが null の場合は元のパターンが返されます。ソースが null オブジェクトを保持する場合は、フォーマットされた結果によって各引数が文字列 null に置き換えられます。

オーバーライド:

クラス Format 内の format

パラメータ:

source - フォーマットするかまたは置き換えるオブジェクトからなる配列

result - テキストが追加される位置

ignore - 有用でない状態が返される

parse

public Object[] parse(String source,
                      ParsePosition status)

文字列を解析します。

注意: 解析はさまざまな状況により、うまく動作しないことがあります。たとえば、次のような場合です。

• 引数の 1 つがパターンにない
• 大きな数字が "many" にフォーマットされるような choice フォーマットなどで、引数のフォーマットが情報を失う
• 繰り返しをまだ処理しない (置き換える文字列に {n} 個の参照がある場合)
• 解析の一部があいまいなとき、一致 (または正しい一致) が必ずしも見つからない。たとえば、パターン "{1},{2}" を文字列引数 {"a,b", "c"} で使用する場合は、"a,b,c" とフォーマットされる。その結果が解析されると、{"a", "b,c"} が返される
• 1 つの引数が文字列内で複数回解析されると、あとの解析が優位になる

解析が失敗したときは、ParsePosition.getErrorIndex() を使って文字列のどこで解析が失敗したかを調べます。返されるエラーインデックスは、文字列の比較対象であるサブパターンの開始オフセットです。たとえば、解析文字列 "AAA {0} BBB" がパターン "AAD {0} BBB" と比較されている場合、エラーインデックスは 0 です。エラーが発生すると、このメソッドへの呼び出しが null を返します。ソースが null の場合、空の配列を返します。

parse

public Object[] parse(String source)
               throws ParseException

文字列を解析します。繰り返しはまだ処理しません (置き換える文字列に {n} 個の参照がある場合)。

例外:

ParseException - 文字列が解析できない場合

parseObject

public Object parseObject(String text,
                          ParsePosition status)

文字列を解析します。繰り返しはまだ処理しません (置き換える文字列に %n 個の参照がある場合)。

オーバーライド:

クラス Format 内の parseObject

クラス java.text.Format からコピーされたタグ:

パラメータ:

status - 入力 - 出力パラメータ

このメソッドを呼び出す前に、ソースにおいて解析を開始するオフセットを、status.index に設定する必要があります。呼び出したあと、status.index は、解析されたテキストの終わりにあります。エラーがあるとインデックスは変更されません。

解析の際、先行のスペースは破棄されます (解析が正常な場合)。後ろのスペースは元のままです。

例: 「_12_xy」(_ はスペースを表す) を解析して数字を見つけると (インデックス == 0)、結果は数字 12 で、status.index が 3 に更新されます (2 つ目のスペースの前)。2 回目の解析では、「xy」が数字ではないので、結果は ParseException になり、status.index は 3 のままです。

一般にサブクラスでは特定の解析メソッドが提供されますが、それらによってさまざまな型の値が返されます。メソッドは戻り型にオーバーロードすることができないので、これらは一般に parse と呼ばれます。一方、この多相性のあるメソッドは、常に parseObject と呼ばれます。状態を取らない解析メソッドは、必要なフォーマットのテキストが開始位置になければ、ParseException をスローする必要があります。

戻り値:

文字列から解析されたオブジェクト。エラーの場合は null を返す

関連項目:

ParsePosition

clone

public Object clone()

Cloneable をオーバーライドします。

オーバーライド:

クラス Format 内の clone

クラス java.lang.Object からコピーされたタグ:

戻り値:

このインスタンスの複製

例外:

CloneNotSupportedException - オブジェクトのクラスが Cloneable インタフェースをサポートしていない場合。clone メソッドをオーバーライドしたサブクラスも、インスタンスを複製できないことを示すためにこの例外をスローすることがある

OutOfMemoryError - 十分なメモリがない場合

関連項目:

Cloneable

equals

public boolean equals(Object obj)

2 つのメッセージフォーマットオブジェクトの間の等号比較です。

オーバーライド:

クラス Object 内の equals

クラス java.lang.Object からコピーされたタグ:

パラメータ:

obj - 比較対象の参照オブジェクト

戻り値:

obj 引数に指定されたオブジェクトとこのオブジェクトが等しい場合は true、そうでない場合は false

関連項目:

Boolean.hashCode(), Hashtable

hashCode

public int hashCode()

メッセージフォーマットオブジェクトのハッシュコードを生成します。

オーバーライド:

クラス Object 内の hashCode

クラス java.lang.Object からコピーされたタグ:

戻り値:

このオブジェクトのハッシュコード値

関連項目:

Object.equals(java.lang.Object), Hashtable