Класс MessageFormat

MessageFormat предоставляет способ создания склеенных сообщений в языконейтральной форме. Используйте это для построения сообщений, отображаемых конечным пользователям.

MessageFormat принимает набор объектов, форматирует их, а затем вставляет отформатированные строки в шаблон в соответствующих местах.

Примечание: MessageFormat отличается от других Format классов тем, что вы создаете объект MessageFormat с помощью одного из его конструкторов (а не с помощью фабричного метода в стиле getInstance). Фабричные методы не нужны, потому что сам MessageFormat не реализует поведение, зависящее от локали. Любое поведение, зависящее от локали, определяется шаблоном, который вы предоставляете, а также подформатами, используемыми для вставленных аргументов.

Шаблоны и их интерпретация

MessageFormatPattern:
        String
        MessageFormatPattern FormatElement String

FormatElement:
        { ArgumentIndex }
        { ArgumentIndex , FormatType }
        { ArgumentIndex , FormatType , FormatStyle }

FormatType: one of
        number date time choice

FormatStyle:
        short
        medium
        long
        full
        integer
        currency
        percent
        SubformatPattern

Внутри строки пара одинарных кавычек может использоваться для цитирования произвольных символов, кроме одинарных кавычек. Например, строка шаблона "'{0}'" представляет строку "{0}", а не элемент формата. Сама одинарная кавычка должна быть представлена двойными одинарными кавычками '' в течение всей строки. Например, строка шаблона "'{''}'" интерпретируется как последовательность '{ (начало цитирования и левая фигурная скобка), '' (одинарная кавычка) и }' (правая фигурная скобка и конец цитирования), а не '{' и '}' (цитируемые левая и правая фигурные скобки): представляющие строку "{'}", а не "{}".

Подшаблон интерпретируется соответствующим подформатом, и применяются правила шаблона, зависящие от подформата. Например, строка шаблона "{1,number,$'#',##}" (Подшаблон с подчеркиванием) создаст формат числа с процитированным знаком фунта, с результатом, таким как: "$#31,45". Обратитесь к документации каждого класса Format для получения подробной информации.

Любая несовпадающая кавычка обрабатывается как закрытая в конце данного шаблона. Например, строка шаблона "'{0}" обрабатывается как шаблон "'{0}'".

Любые фигурные скобки внутри нецитируемого шаблона должны быть сбалансированы. Например, "ab {0} de" и "ab '}' de" являются допустимыми шаблонами, но "ab {0'}' de", "ab } de" и "''{''" не являются.

Предупреждение:

Правила использования кавычек в шаблонах формата сообщений, к сожалению, оказались несколько запутанными. В частности, не всегда очевидно локализаторам, нужно ли удваивать одинарные кавычки или нет. Убедитесь, что вы информируете локализаторов о правилах и сообщите им (например, с помощью комментариев в исходных файлах ресурсов), какие строки будут обрабатываться MessageFormat. Обратите внимание, что локализаторам может потребоваться использовать одинарные кавычки в переведенных строках, где оригинальная версия их не имеет.

Значение ИндексАргумента — это целое неотрицательное число, записанное с помощью цифр '0' по '9', и оно представляет собой индекс в массиве arguments , переданном методам format или массив результата, возвращаемый методами parse.

Значения ТипФормата и СтильФормата используются для создания экземпляра Format для элемента формата. В следующей таблице показано, как значения сопоставляются с экземплярами Format. Комбинации, не представленные в таблице, недопустимы. Подшаблон должен быть допустимой строкой шаблона для класса Format используемого.

Информация об использовании

Вот несколько примеров использования. В реальных международных программах шаблон формата сообщений и другие статические строки, конечно, будут получены из ресурсов пакетов. Другие параметры будут динамически определены во время выполнения.

Первый пример использует статический метод MessageFormat.format, который внутри создает MessageFormat для одноразового использования:

int planet = 7;
String event = "a disturbance in the Force";

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

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

Следующий пример создает экземпляр MessageFormat , который можно использовать многократно:

int fileCount = 1273;
String diskName = "MyDisk";
Object[] testArgs = {new Long(fileCount), diskName};

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

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

The disk "MyDisk" contains 0 file(s).
The disk "MyDisk" contains 1 file(s).
The disk "MyDisk" contains 1,273 file(s).

Для более сложных шаблонов вы можете использовать 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.setFormatByArgumentIndex(0, fileform);

int fileCount = 1273;
String diskName = "MyDisk";
Object[] testArgs = {new Long(fileCount), diskName};

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

The disk "MyDisk" contains no files.
The disk "MyDisk" contains one file.
The disk "MyDisk" contains 1,273 files.

Вы можете создать ChoiceFormat программно, как в примере выше, или с помощью шаблона. Смотрите ChoiceFormat для получения дополнительной информации.

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

Примечание: Как мы видим выше, строка, созданная ChoiceFormat в MessageFormat , обрабатывается как специальная; случаи '{' используются для обозначения подформатов и вызывают рекурсию. Если вы создаете как MessageFormat , так и ChoiceFormat программно (вместо использования строчных шаблонов), будьте осторожны, чтобы не создать формат, который вызовет рекурсию на самом себе, что приведет к бесконечной петле.

Когда один аргумент анализируется более одного раза в строке, последняя совпавшая будет конечным результатом анализа. Например,

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")}

Синхронизация

Форматы сообщений не синхронизированы. Рекомендуется создавать отдельные экземпляры форматов для каждого потока. Если несколько потоков обращаются к формату одновременно, необходимо обеспечить внешнюю синхронизацию.

Конструкторы

MessageFormat

public MessageFormat(String pattern)

Создаёт MessageFormat для локали по умолчанию FORMAT и указанного шаблона. Конструктор сначала задаёт локаль, затем анализирует шаблон и создаёт список подформатов для элементов форматирования, содержащихся в нём. Шаблоны и их интерпретация описаны в описании класса.

Параметры:

pattern - шаблон для этого формата сообщений

Исключения:

IllegalArgumentException - если шаблон некорректен

MessageFormat

public MessageFormat(String pattern,
                     Locale locale)

Создаёт MessageFormat для указанной локали и шаблона. Конструктор сначала задаёт локаль, затем анализирует шаблон и создаёт список подформатов для элементов форматирования, содержащихся в нём. Шаблоны и их интерпретация описаны в описании класса.

Параметры:

pattern - шаблон для этого формата сообщений

locale - локаль для этого формата сообщений

Исключения:

IllegalArgumentException - если шаблон некорректен

С:

1.4

Методы

setLocale

public void setLocale(Locale locale)

Устанавливает локаль, используемую при создании или сравнении подформатов. Это влияет на последующие вызовы

• методов applyPattern и toPattern, если элементы форматирования указывают тип формата и, следовательно, подформаты создаются в методе applyPattern, а также
• методов format и formatToCharacterIterator, если элементы форматирования не указывают тип формата и, следовательно, подформаты создаются в методах форматирования.

Параметры:

locale - локаль, используемая при создании или сравнении подформатов

getLocale

public Locale getLocale()

Получает локаль, используемую при создании или сравнении подформатов.

Возвращает:

используемая локаль при создании или сравнении подформатов

applyPattern

public void applyPattern(String pattern)

Устанавливает шаблон, используемый этим форматом сообщений. Метод анализирует шаблон и создаёт список подформатов для элементов форматирования, содержащихся в нём. Шаблоны и их интерпретация описаны в описании класса.

Параметры:

pattern - шаблон для этого формата сообщений

Исключения:

IllegalArgumentException - если шаблон некорректен

toPattern

public String toPattern()

Возвращает шаблон, представляющий текущее состояние формата сообщений. Строка создаётся из внутренней информации и, следовательно, не обязательно равна ранее применённому шаблону.

Возвращает:

шаблон, представляющий текущее состояние формата сообщений

setFormatsByArgumentIndex

public void setFormatsByArgumentIndex(Format[] newFormats)

Параметры:

newFormats - новые форматы для использования

Исключения:

NullPointerException - если newFormats равно null

С:

1.4

setFormats

public void setFormats(Format[] newFormats)

Параметры:

newFormats - новые форматы для использования

Исключения:

NullPointerException - если newFormats равно null

setFormatByArgumentIndex

public void setFormatByArgumentIndex(int argumentIndex,
                                     Format newFormat)

Параметры:

argumentIndex - индекс аргумента, для которого использовать новый формат

newFormat - новый формат для использования

С:

1.4

setFormat

public void setFormat(int formatElementIndex,
                      Format newFormat)

Параметры:

formatElementIndex - индекс элемента форматирования в шаблоне

newFormat - формат для использования для указанного элемента форматирования

Исключения:

ArrayIndexOutOfBoundsException - если formatElementIndex равен или больше числа элементов форматирования в строке шаблона

getFormatsByArgumentIndex

public Format[] getFormatsByArgumentIndex()

Возвращает:

форматы, используемые для аргументов в шаблоне

С:

1.4

getFormats

public Format[] getFormats()

Возвращает:

форматы, используемые для элементов форматирования в шаблоне

format

public final StringBuffer format(Object[] arguments,
                                 StringBuffer result,
                                 FieldPosition pos)

Параметры:

arguments - массив объектов для форматирования и подстановки.

result - место для добавления текста.

pos - При вводе: поле выравнивания, если необходимо. При выводе: смещения поля выравнивания.

Возвращает:

буфер строки, переданный как result, с добавленным отформатированным текстом

Исключение:

IllegalArgumentException - если аргумент в массиве arguments не соответствует типу, ожидаемому элементом(ами) форматирования, использующими его.

format

public static String format(String pattern,
                            Object... arguments)

Создаёт MessageFormat с заданным шаблоном и использует его для форматирования заданных аргументов. Это эквивалентно

(new MessageFormat(pattern)).format(arguments, new StringBuffer(), null).toString()

Параметры:

pattern - строка шаблона

arguments - объект(ы) для форматирования

Возвращает:

отформатированная строка

Исключение:

IllegalArgumentException - если шаблон некорректен, или если аргумент в массиве arguments не соответствует типу, ожидаемому элементом(ами) форматирования, использующими его.

format

public final StringBuffer format(Object arguments,
                                 StringBuffer result,
                                 FieldPosition pos)

Форматирует массив объектов и добавляет шаблон MessageFormat, с элементами форматирования, заменёнными отформатированными объектами, в предоставленный буфер StringBuffer. Это эквивалентно

format((Object[]) arguments, result, pos)

Определено в:

format в классе Format

Параметры:

arguments - массив объектов для форматирования и подстановки.

result - место для добавления текста.

pos - При вводе: поле выравнивания, если необходимо. При выводе: смещения поля выравнивания.

Возвращает:

буфер строки, переданный как toAppendTo, с добавленным отформатированным текстом

Исключение:

IllegalArgumentException - если аргумент в массиве arguments не соответствует типу, ожидаемому элементом(ами) форматирования, использующими его.

formatToCharacterIterator

public AttributedCharacterIterator formatToCharacterIterator(Object arguments)

format(arguments, new StringBuffer(), null).toString()

Переопределяет:

formatToCharacterIterator в классе Format

Параметры:

arguments - массив объектов для форматирования и подстановки.

Возвращает:

AttributedCharacterIterator, описывающий отформатированное значение.

Исключение:

NullPointerException - если arguments равно null.

IllegalArgumentException - если аргумент в массиве arguments не соответствует типу, ожидаемому элементом(ами) форматирования, использующими его.

С:

1.4

parse

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

Параметры:

source - строка для разбора

pos - позиция разбора

Возвращает:

массив разбора объектов

parse

public Object[] parse(String source)
               throws ParseException

Параметры:

source - Строка, начало которой должно быть разобрано.

Возвращает:

массив Object объектов, разобранных из строки.

Исключение:

ParseException - если начало указанной строки не может быть разобрано.

parseObject

public Object parseObject(String source,
                          ParsePosition pos)

Определено в:

parseObject в классе Format

Параметры:

source - Строка, часть которой должна быть разобрана.

pos - Объект ParsePosition с информацией об индексе и индексе ошибки, как описано выше.

Возвращает:

массив Object объектов, разобранных из строки. В случае ошибки возвращает null.

Исключение:

NullPointerException - если pos равно null.

clone

public Object clone()

Создаёт и возвращает копию этого объекта.

Переопределяет:

clone в классе Format

Возвращает:

клон этого экземпляра.

См. также:

Cloneable

equals

public boolean equals(Object obj)

Сравнение на равенство двух объектов формата сообщения

Переопределяет:

equals в классе Object

Параметры:

obj - объект-ссылка для сравнения.

Возвращает:

true если этот объект такой же, как аргумент obj; false в противном случае.

См. также:

Object.hashCode(), HashMap

hashCode

public int hashCode()

Генерирует код хэширования для объекта формата сообщения.

Переопределяет:

hashCode в классе Object

Возвращает:

значение хэша для этого объекта.

См. также:

Object.equals(java.lang.Object), System.identityHashCode(java.lang.Object)