Класс 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 = {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")}
 

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

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