Класс 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}", а не FormatElement. Сама одинарная кавычка должна быть представлена двумя одинарными кавычками '' внутри строки. Например, строка шаблона "'{''}'" интерпретируется как последовательность '{ (начало кавычек и левая фигурная скобка), '' (одинарная кавычка) и }' (правая фигурная скобка и конец кавычек), а не '{' и '}' (заключенные в кавычки левая и правая фигурные скобки): представляющая строку "{'}", а не "{}".

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

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

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

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

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

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

Значения FormatType и FormatStyle используются для создания экземпляра Format для элемента формата. В следующей таблице показано, как значения сопоставляются с экземплярами Format. Комбинации, не показанные в таблице, являются недопустимыми. SubformatPattern должен быть допустимой строкой шаблона для используемого подкласса 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 = {Long.valueOf(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 = {Long.valueOf(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 = {Double.valueOf(3.1415)};
String result = mf.format( objs );
// result now equals "3.14, 3.1"
objs = mf.parse(result, new ParsePosition(0));
// objs now equals {Double.valueOf(3.1)}

Аналогично, при разборе с помощью объекта MessageFormat с шаблонами, содержащими несколько вхождений одного и того же аргумента, будет возвращено последнее совпадение. Например,

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

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

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