Класс MessageFormat

public class MessageFormat extends Format

Примечание по реализации:

В эталонной реализации ограничение для ArgumentIndex составляет 10 000.

Показано, как значения FormatType и FormatStyle соответствуют экземплярам Format

Тип формата	Стиль формата	Создаваемый подформат
(нет)	(нет)	null
number	(нет)	NumberFormat.getInstance(getLocale())
	integer	NumberFormat.getIntegerInstance(getLocale())
	currency	NumberFormat.getCurrencyInstance(getLocale())
	percent	NumberFormat.getPercentInstance(getLocale())
	compact_short	NumberFormat.getCompactNumberInstance(getLocale(), NumberFormat.Style.SHORT)
	compact_long	NumberFormat.getCompactNumberInstance(getLocale(), NumberFormat.Style.LONG)
	SubformatPattern	new DecimalFormat(subformatPattern, DecimalFormatSymbols.getInstance(getLocale()))
dtf_date	(нет)	DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM).withLocale(getLocale())
	short	DateTimeFormatter.ofLocalizedDate(FormatStyle.SHORT).withLocale(getLocale())
	medium	DateTimeFormatter.ofLocalizedDate(FormatStyle.MEDIUM).withLocale(getLocale())
	long	DateTimeFormatter.ofLocalizedDate(FormatStyle.LONG).withLocale(getLocale())
	full	DateTimeFormatter.ofLocalizedDate(FormatStyle.FULL).withLocale(getLocale())
	SubformatPattern	DateTimeFormatter.ofPattern(subformatPattern, getLocale())
dtf_time	(нет)	DateTimeFormatter.ofLocalizedTime(FormatStyle.MEDIUM).withLocale(getLocale())
	short	DateTimeFormatter.ofLocalizedTime(FormatStyle.SHORT).withLocale(getLocale())
	medium	DateTimeFormatter.ofLocalizedTime(FormatStyle.MEDIUM).withLocale(getLocale())
	long	DateTimeFormatter.ofLocalizedTime(FormatStyle.LONG).withLocale(getLocale())
	full	DateTimeFormatter.ofLocalizedTime(FormatStyle.FULL).withLocale(getLocale())
	SubformatPattern	DateTimeFormatter.ofPattern(subformatPattern, getLocale())
dtf_datetime	(нет)	DateTimeFormatter.ofLocalizedDateTime(FormatStyle.MEDIUM).withLocale(getLocale())
	short	DateTimeFormatter.ofLocalizedDateTime(FormatStyle.SHORT).withLocale(getLocale())
	medium	DateTimeFormatter.ofLocalizedDateTime(FormatStyle.MEDIUM).withLocale(getLocale())
	long	DateTimeFormatter.ofLocalizedDateTime(FormatStyle.LONG).withLocale(getLocale())
	full	DateTimeFormatter.ofLocalizedDateTime(FormatStyle.FULL).withLocale(getLocale())
	SubformatPattern	DateTimeFormatter.ofPattern(subformatPattern, getLocale())
pre-defined DateTimeFormatter(s)	(нет)	pre-defined DateTimeFormatter(s) используются как FormatType: BASIC_ISO_DATE, ISO_LOCAL_DATE, ISO_OFFSET_DATE, ISO_DATE, ISO_LOCAL_TIME, ISO_OFFSET_TIME, ISO_TIME, ISO_LOCAL_DATE_TIME, ISO_OFFSET_DATE_TIME, ISO_ZONED_DATE_TIME, ISO_DATE_TIME, ISO_ORDINAL_DATE, ISO_WEEK_DATE, ISO_INSTANT, RFC_1123_DATE_TIME
date	(нет)	DateFormat.getDateInstance(DateFormat.DEFAULT, getLocale())
	short	DateFormat.getDateInstance(DateFormat.SHORT, getLocale())
	medium	DateFormat.getDateInstance(DateFormat.MEDIUM, getLocale())
	long	DateFormat.getDateInstance(DateFormat.LONG, getLocale())
	full	DateFormat.getDateInstance(DateFormat.FULL, getLocale())
	SubformatPattern	new SimpleDateFormat(subformatPattern, getLocale())
time	(нет)	DateFormat.getTimeInstance(DateFormat.DEFAULT, getLocale())
	short	DateFormat.getTimeInstance(DateFormat.SHORT, getLocale())
	medium	DateFormat.getTimeInstance(DateFormat.MEDIUM, getLocale())
	long	DateFormat.getTimeInstance(DateFormat.LONG, getLocale())
	full	DateFormat.getTimeInstance(DateFormat.FULL, getLocale())
	SubformatPattern	new SimpleDateFormat(subformatPattern, getLocale())
choice	SubformatPattern	new ChoiceFormat(subformatPattern)
list	(нет)	ListFormat.getInstance(getLocale(), ListFormat.Type.STANDARD, ListFormat.Style.FULL)
	or	ListFormat.getInstance(getLocale(), ListFormat.Type.OR, ListFormat.Style.FULL)
	unit	ListFormat.getInstance(getLocale(), ListFormat.Type.UNIT, ListFormat.Style.FULL)

Правила экранирования в шаблонах

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

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

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

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

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

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

Сведения об использовании

Следующий пример демонстрирует общее использование 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 GregorianCalendar(2053, Calendar.JULY, 3, 12, 30).getTime(), event);

result возвращает следующий результат:

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

Для более сложных шаблонов можно использовать ChoiceFormat вместе с MessageFormat, чтобы корректно выбирать формы единственного и множественного числа:

MessageFormat msgFmt = new MessageFormat("The disk \"{0}\" contains {1,choice,0#no files|1#one file|1< {1,number,integer} files}.");
Object[] args = {"MyDisk", fileCount};
String result = msgFmt.format(args);

result с различными значениями fileCount возвращает следующий результат:

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

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

Форматирование даты и времени

MessageFormat предоставляет шаблоны, поддерживающие форматировщики даты и времени из пакетов java.time.format и java.text. Рассмотрим следующие три примера с датой 16.11.2023:

1) FormatType даты с FormatStyle полным,

Object[] arg = {new GregorianCalendar(2023, Calendar.NOVEMBER, 16).getTime()};
var fmt = new MessageFormat("The date was {0,date,full}");
fmt.format(arg); // returns "The date was Thursday, November 16, 2023"

2) FormatType dtf_date с FormatStyle полным,

Object[] arg = {LocalDate.of(2023, 11, 16)};
var fmt = new MessageFormat("The date was {0,dtf_date,full}");
fmt.format(arg); // returns "The date was Thursday, November 16, 2023"

3) FormatType ISO_LOCAL_DATE,

Object[] arg = {LocalDate.of(2023, 11, 16)};
var fmt = new MessageFormat("The date was {0,ISO_LOCAL_DATE}");
fmt.format(arg); // returns "The date was 2023-11-16"

Разбор

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

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

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

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

Начиная с версии:

1.1

См. также:

• Locale
• Format
• NumberFormat
• DecimalFormat
• DecimalFormatSymbols
• ChoiceFormat
• DateFormat
• SimpleDateFormat
• DateTimeFormatter
• Сериализованная форма