@Deprecated public class MessageFormatter extends Object
MessageFormatterIn ICU4J, the MessageFormatter class is the next iteration of MessageFormat.
This new version will build on the lessons learned from using MessageFormat for 25 years
in various environments, when used directly or as a base for other public APIs.
The effort to design a succesor to MessageFormat will result in a specification
referred to as MessageFormat 2.0.
The reasoning for this effort is shared in the
“Why
MessageFormat needs a successor” document.
MessageFormat 2.0 will be more modular and easier to port and backport. It will also provide extension points via interfaces to allow users to supply new formatters and selectors without having to modify the specification. ICU will eventually include support for new formatters, such as intervals, relative time, lists, measurement units, personal names, and more, as well as the ability for users to supply their own custom implementations. These will potentially support use cases like grammatical gender, inflection, markup regimes (such as those require for text-to-speech), and other complex message management needs.
The MessageFormat Working Group, which develops the new data model, semantics, and syntax, is hosted on GitHub. The current specification for the syntax and data model can be found here.
This technical preview implements enough functions for MessageFormatter to be useful in many situations,
but the final set of functions and the parameters accepted by those functions is not yet finalized.
import static org.junit.Assert.assertEquals;
import java.util.Date;
import java.util.HashMap;
import java.util.Locale;
import java.util.Map;
import com.ibm.icu.message2.MessageFormatter;
@Test
public void test() {
final Locale enGb = Locale.forLanguageTag("en-GB");
Map arguments = new HashMap<>();
arguments.put("name", "John");
arguments.put("exp", new Date(2023 - 1900, 2, 27, 19, 42, 51)); // March 27, 2023, 7:42:51 PM
MessageFormatter mf2 = MessageFormatter.builder()
.setPattern("Hello {$name}, your card expires on {$exp :datetime year=numeric month=short day=numeric weekday=short}!")
.setLocale(enGb)
.build();
assertEquals(
"Hello John, your card expires on Mon, 27 Mar 2023!",
mf2.formatToString(arguments));
}
| Code to set runtime value for placeholder | Examples of placeholder in message pattern |
|---|---|
arguments.put("name", "John") |
{$name} |
arguments.put("exp", new Date(…)) |
{$exp :datetime skeleton=year=numeric month=short day=numeric weekday=short} {$exp :datetime dateStyle=full} |
arguments.put("val", 3.141592653) |
{$val} {$val :number minimumFractionDigits=5} |
| No argument for fixed values known at build time | {|123456789.531| :number} |
@Test
public void testSelection() {
final String message = ".match {$count :number}\n"
+ " 1 {{You have one notification.}}\n"
+ " * {{You have {$count} notifications.}}\n";
final Locale enGb = Locale.forLanguageTag("en-GB");
Map arguments = new HashMap<>();
MessageFormatter mf2 = MessageFormatter.builder()
.setPattern(message)
.setLocale(enGb)
.build();
arguments.put("count", 1);
assertEquals(
"You have one notification.",
mf2.formatToString(arguments));
arguments.put("count", 42);
assertEquals(
"You have 42 notifications.",
mf2.formatToString(arguments));
}
The tech preview implementation comes with formatters for numbers (:number),
date / time (:datetime, :date, :time),
plural selectors (:number with options for plural and ordinal selection),
and general selector (:string),
very similar to what MessageFormat offers.
The ICU test code
covers most features, and has examples of how to make custom placeholder formatters;
you can look for classes that implement com.ibm.icu.message2.FormatterFactory
(they are named Custom*Test.java).
The complete list of valid options for each function, and how they infulence the results, can be found at here.
| Modifier and Type | Class and Description |
|---|---|
static class |
MessageFormatter.Builder
Deprecated.
This API is for technology preview only.
|
static class |
MessageFormatter.ErrorHandlingBehavior
Deprecated.
This API is for technology preview only.
|
| Modifier and Type | Method and Description |
|---|---|
static MessageFormatter.Builder |
builder()
Deprecated.
This API is for technology preview only.
|
FormattedMessage |
format(Map<String,Object> arguments)
Deprecated.
This API is for technology preview only.
|
String |
formatToString(Map<String,Object> arguments)
Deprecated.
This API is for technology preview only.
|
MFDataModel.Message |
getDataModel()
Deprecated.
This API is for technology preview only.
|
MessageFormatter.ErrorHandlingBehavior |
getErrorHandlingBehavior()
Deprecated.
This API is for technology preview only.
|
Locale |
getLocale()
Deprecated.
This API is for technology preview only.
|
String |
getPattern()
Deprecated.
This API is for technology preview only.
|
@Deprecated public static MessageFormatter.Builder builder()
@Deprecated public Locale getLocale()
MessageFormatter.@Deprecated public MessageFormatter.ErrorHandlingBehavior getErrorHandlingBehavior()
MessageFormatter.ErrorHandlingBehavior to use when encountering errors in
the current MessageFormatter.@Deprecated public String getPattern()
MessageFormatter.
If the MessageFormatter was created from an MFDataModel
the this string is generated from that model.
@Deprecated public MFDataModel.Message getDataModel()
This data model is similar to the functionality we have today
in MessagePatternUtil maybe even a bit more higher level.
We can also imagine a model where one parses the string syntax, takes the data model,
modifies it, and then uses that modified model to create a MessageFormatter.
@Deprecated public String formatToString(Map<String,Object> arguments)
arguments - a map of objects to be formatted and substituted.IllegalArgumentException - when something goes wrong
(for example wrong argument type, or null arguments, etc.)@Deprecated public FormattedMessage format(Map<String,Object> arguments)
arguments - a map of objects to be formatted and substituted.FormattedMessage class representing the message with parameters replaced.Copyright © 2016 Unicode, Inc. and others.