JEP 430: String Templates (Preview)

Owner	Jim Laskey
Type	Feature
Scope	SE
Status	Candidate
Component	specification / language
Discussion	amber dash dev at openjdk dot org
Effort	M
Duration	M
Reviewed by	Alex Buckley, Maurizio Cimadamore
Created	2021/09/17 13:41
Updated	2022/09/20 18:03
Issue	8273943

Summary

Enhance the Java programming language with string templates, which are similar to string literals but contain embedded expressions. A string template is interpreted at run time by replacing each expression with the result of evaluating that expression, possibly after further validation and transformation. This is a preview language feature and API.

Goals

Simplify the writing of Java programs by making it easy to express strings that include values computed at run time.
Enhance the readability of strings that mix text and expressions, whether they fit on a single source line (string literals) or span several source lines (text blocks).
Improve the security of Java programs that compose strings from user-provided values and pass them to other systems (e.g., building queries for databases) by supporting validation and transformation of both the template and the values of its embedded expressions.
Retain flexibility by allowing Java libraries to define the formatting syntax used in string templates.
Simplify the use of APIs that accept strings written in non-Java languages (e.g., SQL, XML, and JSON).

Non-Goals

It is not a goal to introduce syntactic sugar for Java's string concatenation operator (+), since that would circumvent the goal of validation.
It is not a goal to deprecate or remove the StringBuilder and StringBuffer classes, which have traditionally been used for complex or programmatic string composition.

Motivation

Developers routinely compose strings from a combination of literal text and expressions. Java provides several mechanisms for string composition, though unfortunately all have drawbacks.

String concatenation with the + operator produces hard-to-read code:
```
String s = x + " plus " + y + " equals " + (x + y);
```

StringBuilder is verbose:

String s = new StringBuilder()
               .append(x)
               .append(" plus ")
               .append(y)
               .append(" equals ")
               .append(x + y);

String::format and String::formatted separate the format string from the parameters, inviting arity and type mismatches:

String s = String.format("%2$d plus %1$d equals %3$d", x, y, x + y);
  String t = "%2$d plus %1$d equals %3$d".formatted(x, y, x + y);

java.text.MessageFormat requires too much ceremony and uses an unfamiliar syntax in the format string:

MessageFormat mf = new MessageFormat("{0} plus {1} equals {2}");
  String s = mf.format(x, y, x + y);

String interpolation

Many programming languages offer string interpolation as an alternative to string concatenation. Typically, this takes the form of a string literal that contains embedded expressions as well as literal text. Embedding expressions in situ means that readers can easily discern the intended result. At run time, the embedded expressions are replaced with their (stringified) values — the values are said to be interpolated into the string. Here are some examples of interpolation in other languages:

JavaScript     `${x} plus ${y} equals ${x + y}`
C#             $"{x} plus {y} equals {x + y}"
Visual Basic   $"{x} plus {y} equals {x + y}"
Scala          f"$x%d plus $y%d equals ${x + y}%d"
Python         f"{x} plus {y} equals {x + y}"
Ruby           "#{x} plus #{y} equals #{x + y}"
Groovy         "$x plus $y equals ${x + y}"
Kotlin         "$x plus $y equals ${x + y}"
Swift          "\(x) plus \(y) equals \(x + y)"

Some of these languages enable interpolation for all string literals while others require interpolation to be enabled when desired, for example by prefixing the literal's opening delimiter with $ or f. The syntax of embedded expressions also varies but often involves characters such as $ or { }, which means that those characters cannot appear literally unless they are escaped.

Not only is interpolation more convenient than concatenation when writing code, it also offers greater clarity when reading code. The clarity is especially striking with larger strings. For example, in JavaScript:

const title = "My Web Page";
const text  = "Hello, world";

var html = `<html>
              <head>
                <title>${title}</title>
              </head>
              <body>
                <p>${text}</p>
              </body>
            </html>`;

String interpolation is dangerous

Unfortunately, the convenience of interpolation has a downside: It is easy to construct strings that will be interpreted by other systems but which are dangerously incorrect in those systems.

Strings that hold SQL statements, HTML/XML documents, JSON snippets, shell scripts, and natural-language text all need to be validated and sanitized according to domain-specific rules. Since the Java programming language cannot possibly enforce all such rules, it is up to developers using interpolation to validate and sanitize. Typically, this means remembering to wrap embedded expressions in calls to escape or validate methods, and relying on IDEs or static analysis tools to help to validate the literal text.

Interpolation is especially dangerous for SQL statements because it can lead to injection attacks. For example, consider this hypothetical Java code with the embedded expression ${name}:

String query = "SELECT * FROM Person p WHERE p.last_name = '${name}'";
ResultSet rs = connection.createStatement().executeQuery(query);

If name had the troublesome value

Smith' OR p.last_name <> 'Smith

then the query string would be

SELECT * FROM Person p WHERE p.last_name = 'Smith' OR p.last_name <> 'Smith'

and the code would select all rows, potentially exposing confidential information. Composing a query string with simple-minded interpolation is just as unsafe as composing it with traditional concatenation:

String query = "SELECT * FROM Person p WHERE p.last_name = '" + name + "'";

Can we do better?

For Java, we would like to have a string composition feature that achieves the clarity of interpolation but achieves a safer result out-of-the-box, perhaps trading off a small amount of convenience to gain a large amount of safety.

For example, when composing SQL statements any quotes in the values of embedded expressions must be escaped, and the string overall must have balanced quotes. Given the troublesome value of name shown above, the query that should be composed is a safe one:

SELECT * FROM Person p WHERE p.last_name = '\'Smith\' OR p.last_name <> \'Smith\''

Almost every use of string interpolation involves structuring the string to fit some kind of template: A SQL statement usually follows the template SELECT ... FROM ... WHERE ..., an HTML document follows <html> ... </html>, and even a message in a natural language follows a template that intersperses dynamic values (e.g., a username) amongst literal text. Each kind of template has rules for validation and transformation, such as "escape all quotes" for SQL statements, "allow only legal character entities" for HTML documents, and "localize to the language configured in the OS" for natural-language messages.

Ideally a string's template could be expressed directly in the code, as if annotating the string, and the Java runtime would apply template-specific rules to the string automatically. The result would be SQL statements with escaped quotes, HTML documents with no illegal entities, and boilerplate-free message localization. Composing a string from a template would relieve developers of having to laboriously escape each embedded expression, call validate() on the whole string, or use java.util.ResourceBundle to look up a localized string.

For another example, a developer might construct a string denoting a JSON document and then feed it to a JSON parser in order to obtain a strongly-typed JSONObject:

String name    = "Joan Smith";
String phone   = "555-123-4567";
String address = "1 Maple Drive, Anytown";
String json = """
    {
        "name":    "%s",
        "phone":   "%s",
        "address": "%s"
    }
    """.formatted(name, phone, address);

JSONObject doc = JSON.parse(json);
... doc.entrySet().stream().map(...) ...

Ideally the JSON structure of the string could be expressed directly in the code, and the Java runtime would transform the string into a JSONObject automatically. The manual detour through the parser would not be necessary.

In summary, we could improve the readability and reliability of almost every Java program if we had a first-class, template-based mechanism for composing strings. Such a feature would offer the benefits of interpolation, as seen in other programming languages, but would be less prone to introducing security vulnerabilities. It would also reduce the ceremony of working with libraries that take complex input as strings.

Description

A string template expression is a new kind of expression in the Java programming language. A string template expression can perform string interpolation, but is also programmable in a way that helps developers compose strings safely and efficiently. In addition, a string template expression is not limited to composing strings — it can turn structured text into any kind of object.

Syntactically, a string template expression resembles a string literal with a prefix. There is a string template expression on the second line of this code:

String name = "Joan";
String info = STR."My name is \{name}";
assert info.equals("My name is Joan");   // true

The string template expression STR."My name is \{name}" consists of:

A template processor (STR);
A dot character (U+002E), as seen in other kinds of expressions; and
A template ("My name is \{name}") which contains an embedded expression (\{name}).

When a string template expression is evaluated at run time, its template processor combines the literal text in the template with the values of the embedded expressions in order to produce a result. The result of the template processor, and thus the result of evaluating the string template expression, is often a String — though not always.

The `STR` template processor

STR is a template processor defined in the Java library. It performs string interpolation by replacing each embedded expression in the template with the (stringified) value of that expression. The result of evaluating a string template expression which uses STR is a String; e.g., "My name is Joan".

In everyday conversation, developers are likely to use the term "string template" when referring to either a string template expression or the template within a particular string template expression. This informal usage is reasonable as long as the template processor of a particular string template expression is not mixed up with the template of the same string template expression.

STR is a public static final field that is automatically imported in every Java source file.

Here are more examples of string template expressions that use the STR template processor. The symbol | in the left margin means that the line shows the value of the previous statement, similar to jshell.

// Embedded expressions can be strings
String firstName = "Bill";
String lastName  = "Duck";
String fullName  = STR."\{firstName} \{lastName}";
| "Bill Duck"
String sortName  = STR."\{lastName}, \{firstName}";
| "Duck, Bill"

// Embedded expressions can perform arithmetic
int x = 10, y = 20;
String s = STR."\{x} + \{y} = \{x + y}";
| "10 + 20 = 30"

// Embedded expressions can invoke methods and access fields
String s = STR."You have a \{getOfferType()} waiting for you!";
| "You have a gift waiting for you!"
String t = STR."Access at \{req.date} \{req.time} from \{req.ipAddress}";
| "Access at 2022-03-25 15:34 from 8.8.8.8"

To aid refactoring, double-quote characters can be used inside embedded expressions without escaping them as \". This means that an embedded expression can appear in a string template expression exactly as it would appear outside the string template expression, easing the switch from + to string template expressions. For example:

String filePath = "tmp.dat";
File   file     = new File(filePath);
String old = "The file " + filePath + " " + file.exists() ? "does" : "does not" + " exist";
String msg = STR."The file \{filePath} \{file.exists() ? "does" : "does not"} exist";
| "The file tmp.dat does exist" or "The file tmp.dat does not exist"

To aid readability, an embedded expression can be spread over multiple lines in the source file. (This does not introduce newlines into the result.) The value of the embedded expression is interpolated into the result at the position of the \ of the embedded expression; the template is then considered to continue on the same line as the \. For example:

String time = STR."The time is \{
    // The java.time.format package is very useful
    DateTimeFormatter
      .ofPattern("HH:mm:ss")
      .format(LocalTime.now())
} right now";
| "The time is 12:34:56 right now"

There is no limit to the number of embedded expressions in a string template expression. The embedded expressions are evaluated from left to right, just like the arguments in a method invocation expression. For example:

// Embedded expressions can be postfix increment expressions
int index = 0;
String data = STR."\{index++}, \{index++}, \{index++}, \{index++}";
| "0, 1, 2, 3"

Any Java expression can be used as an embedded expression — even a string template expression. For example:

// Embedded expression is a (nested) string template expression
String[] fruit = { "apples", "oranges", "peaches" };
String s = STR."\{fruit[0]}, \{STR."\{fruit[1]}, \{fruit[2]}"}";
| "apples, oranges, peaches"

Here, the string template expression STR."\{fruit[1]}, \{fruit[2]}" is embedded in the template of another string template expression. This code is difficult to read due to the abundance of ", \, and { } characters, so it would be better to format it for easier readability:

String s = STR."\{fruit[0]}, \{
    STR."\{fruit[1]}, \{fruit[2]}"
}";

Alternatively, since the embedded expression has no side effects, it could be refactored into a separate string template expression:

String tmp = STR."\{fruit[1]}, \{fruit[2]}";
String s = STR."\{fruit[0]}, \{tmp}";

Multi-line string template expressions

The template of a string template expression can span multiple lines of source code, using a syntax similar to that of text blocks. (We saw an embedded expression spanning multiple lines above, but the template which contained the embedded expression was logically one line.)

Here are examples of string template expressions denoting HTML text, JSON text, and a zone form, all spread over multiple lines:

String title = "My Web Page";
String text  = "Hello, world";
String html = STR."""
        <html>
          <head>
            <title>\{title}</title>
          </head>
          <body>
            <p>\{text}</p>
          </body>
        </html>
        """;
| """
| <html>
|   <head>
|     <title>My Web Page</title>
|   </head>
|   <body>
|     <p>Hello, world</p>
|   </body>
| </html>
| """

String name    = "Joan Smith";
String phone   = "555-123-4567";
String address = "1 Maple Drive, Anytown";
String json = STR."""
    {
        "name":    "\{name}",
        "phone":   "\{phone}",
        "address": "\{address}"
    }
    """;
| """
| {
|     "name":    "Joan Smith",
|     "phone":   "555-123-4567",
|     "address": "1 Maple Drive, Anytown"
| }
| """

record Rectangle(String name, double width, double height) {
    double area() {
        return width * height;
    }
}
Rectangle[] zone = new Rectangle[] {
        new Rectangle("Alfa", 17.8, 31.4),
        new Rectangle("Bravo", 9.6, 12.4),
        new Rectangle("Charlie", 7.1, 11.23),
    };
String form = STR."""
        Description  Width  Height  Area
        \{zone[0].name}  \{zone[0].width}  \{zone[0].height}     \{zone[0].area()}
        \{zone[1].name}  \{zone[1].width}  \{zone[1].height}     \{zone[1].area()}
        \{zone[2].name}  \{zone[2].width}  \{zone[2].height}     \{zone[2].area()}
        Total \{zone[0].area() + zone[1].area() + zone[2].area()}
          """;
| """
| Description  Width  Height  Area
| Alfa  17.8  31.4     558.92
| Bravo  9.6  12.4     119.03999999999999
| Charlie  7.1  11.23     79.733
| Total 757.693
| """
| """

The `FMT` template processor

FMT is another template processor defined in the Java library. FMT is like STR in that it performs interpolation, but it also interprets format specifiers which appear to the left of embedded expressions. The format specifiers are the same as those defined in java.util.Formatter. Here is the zone form example, tidied up by format specifiers in the template:

record Rectangle(String name, double width, double height) {
    double area() {
        return width * height;
    }
}
Rectangle[] zone = new Rectangle[] {
        new Rectangle("Alfa", 17.8, 31.4),
        new Rectangle("Bravo", 9.6, 12.4),
        new Rectangle("Charlie", 7.1, 11.23),
    };
String form = FMT."""
        Description     Width    Height     Area
        %-12s\{zone[0].name}  %7.2f\{zone[0].width}  %7.2f\{zone[0].height}     %7.2f\{zone[0].area()}
        %-12s\{zone[1].name}  %7.2f\{zone[1].width}  %7.2f\{zone[1].height}     %7.2f\{zone[1].area()}
        %-12s\{zone[2].name}  %7.2f\{zone[2].width}  %7.2f\{zone[2].height}     %7.2f\{zone[2].area()}
        \{" ".repeat(28)} Total %7.2f\{zone[0].area() + zone[1].area() + zone[2].area()}
          """;
| """
| Description     Width    Height     Area
| Alfa            17.80    31.40      558.92
| Bravo            9.60    12.40      119.04
| Charlie          7.10    11.23       79.73
|                              Total  757.69
| """

FMT is a public static final automatically imported in every Java source file.

String template expressions without a template processor

When an embedded expression occurs in a string literal or text block, rather than in the template of a string template expression, then the result is not a String but rather a java.lang.template.TemplatedString:

String name = "Joan";
TemplatedString ts = "My name is \{name}";

The string template expression STR."..." is a shortcut for invoking the apply method of the STR template processor. That is, the now-familiar example:

String name = "Joan";
String info = STR."My name is \{name}";

is a shortcut for:

String name = "Joan";
TemplatedString ts = "My name is \{name}";
String info = STR.apply(ts);

The design of string template expressions deliberately makes it impossible to go directly from a string literal or text block with embedded expressions to a String with the expressions' values interpolated. This prevents dangerously incorrect strings from spreading through the program. Either the string literal is used as a TemplatedString, which cannot be confused with a String, or the string literal is processed by a template processor, which has explicit responsibility for safely interpolating and validating a result, String or otherwise. Thus if a developer forgets to use a template processor such as STR or FMT then a compile-time error occurs:

String name = "Joan";
String info = "My name is \{name}";
| error: incompatible types: java.lang.template.TemplatedString cannot be converted to java.lang.String

Syntax and semantics

The template of a string template expression — that is, the "..." or """...""" to the right of the dot — appears at first glance to be either a string literal or a text block. In fact, the nature of a template depends on the presence of embedded expressions. A template of the form "..." is a string template if it contains embedded expressions; otherwise, it is a string literal. Similarly, a template of the form """...""" is a text block template if it contains embedded expressions; otherwise, it is a text block.

The four kinds of template in a string template expression are shown by its grammar, which starts at TemplateExpression:

TemplateExpression:
  TemplateProcessorExpression . Template

TemplateProcessorExpression:
  An expression of type TemplateProcessor

Template:
  StringTemplate
  TextBlockTemplate
  StringLiteral
  TextBlock

StringTemplate:
  Resembles a StringLiteral but has at least one embedded expression,
    and can be spread over multiple lines of source code

TextBlockTemplate:
  Resembles a TextBlock but has at least one embedded expression

StringLiteral:    // unchanged from JLS 3.10.5
  " {StringCharacter} "

TextBlock:    // unchanged from JLS 3.10.6
  " " " {TextBlockWhiteSpace} LineTerminator {TextBlockCharacter} " " "

The Java compiler scans the term "..." and determines whether to parse it as a StringLiteral or a StringTemplate based on the presence of embedded expressions. The compiler similarly scans the term """...""" and determines whether to parse it as a TextBlock or a TextBlockTemplate. We refer uniformly to the ... portion of these terms as the content of a string literal, string template, text block, or text block template.

We strongly encourage IDEs to visually distinguish a string template from a string literal, and a text block template from a text block. Within the content of a string template or text block template, IDEs should visually distinguish an embedded expression from literal text.

The Java programming language distinguishes string literals from string templates, and text blocks from text block templates, primarily because the type of a string template or text block template is not the familiar String. The type of a string template or text block template is TemplatedString, which is an interface, and String does not implement TemplatedString. When the template of a string template expression is a string literal or a text block, therefore, the Java compiler automatically transforms the String denoted by the template into a TemplatedString with no embedded expressions.

At run time, a string template expression is evaluated as follows:

The expression to the left of the dot is evaluated to obtain an instance of TemplateProcessor,
The expression to the right of the dot is evaluated to obtain an instance of TemplatedString, and then
The TemplatedString instance is passed to the apply method of the TemplateProcessor instance, which composes a result.

The type of a string template expression is, thus, the return type of the apply method of the TemplateProcessor instance.

The TemplatedString and TemplateProcessor APIs, along with related APIs, are declared in the new package java.lang.template.

String literals inside string template expressions

The ability to use a string literal or a text block as a template improves the flexibility of string template expressions. Developers can write string template expressions that initially have placeholder text in a string literal, such as

String s = STR."Welcome to your account";
| "Welcome to your account"

and gradually embed expressions into the text to create a string template without changing any delimiters or inserting any special prefixes:

String s = STR."Welcome, \{user.firstName()}, to your account \{user.accountNumber()}";
| "Welcome, Lisa, to your account 12345"

String templates outside string template expressions

A string template or a text block template can appear standalone, outside of a string template expression. This is what allows the earlier example, TemplatedString ts = "My name is \{name}";.

Accordingly, we modify the grammar of literals to include string templates and text block templates alongside string literals and text blocks:

Literal:
  IntegerLiteral
  ...
  StringLiteral
  TextBlock
  StringTemplate
  TextBlockTemplate

User-defined template processors

Earlier we saw the template processors STR and FMT, which make it look as if a template processor is an object accessed via a field. That is useful shorthand, but it is more accurate to say that a template processor is a class which implements the functional interface TemplateProcessor. In particular, the class implements the single abstract method of TemplateProcessor, apply, which takes a TemplatedString and returns an object. A field such as STR merely stores an instance of such a class. (The actual class whose instance is stored in STR has an apply method that performs a stateless interpolation for which a singleton instance is suitable, hence the upper-case field name.)

Developers can easily create template processors for use in string template expressions. However, before discussing how to create a template processor, it is necessary to discuss the class TemplatedString.

An instance of TemplatedString represents the string template or text block template that appears either as the template in a string template expression, or as a standalone literal. Consider this code:

int x = 10, y = 20;
TemplatedString ts = "\{x} plus \{y} equals \{x + y}";
String s = ts.toString();
| ["", " plus ", " equals ", ""](10, 20, 30)

The result is, perhaps, a surprise. Where is the interpolation of 10, 20, and 30? Recall that one of the goals of string template expressions is to provide secure string composition. Having TemplatedString::toString simply concatenate "10", " plus ", "20", " equals ", and "30" into a String would circumvent that goal. Instead, the toString method renders the two useful parts of a TemplatedString:

The text fragments, "", " plus ", " equals ", "", and
The values, 10, 20, 30.

The TemplatedString class exposes these parts directly:

TemplatedString::fragments returns a list of the text fragments coming before and after the embedded expressions in the string template or text block template:

int x = 10, y = 20;
  TemplatedString ts = "\{x} plus \{y} equals \{x + y}";
  List<String> fragments = ts.fragments();
  String result = String.join("\\{}", fragments);
  | "\{} plus \{} equals \{}"

TemplatedString::values returns a list of the values produced by evaluating the embedded expressions in the order they appear in the source code. In the current example, this is equivalent to List.of(x, y, x + y).
```
int x = 10, y = 20;
  TemplatedString ts = "\{x} plus \{y} equals \{x + y}";
  List<Object> values = ts.values();
  | [10, 20, 30]
```

The fragments() of a TemplatedString are constant across all evaluations of a string template expression, while values() is computed fresh for each evaluation. For example:

int y = 20;
for (int x = 0; x < 3; x++) {
    TemplatedString ts = "\{x} plus \{y} equals \{x + y}";
    System.out.println(ts);
}
| ["Adding ", " and ", " yields ", ""](0, 20, 20)
| ["Adding ", " and ", " yields ", ""](1, 20, 21)
| ["Adding ", " and ", " yields ", ""](2, 20, 22)

Using fragments() and values(), it is straightforward to write an interpolating template processor. For brevity, the following example does not show code that implements TemplateProcessor directly; rather, it implements a useful subinterface of TemplateProcessor, namely StringProcessor, that returns a String.

StringProcessor INTER = (TemplatedString ts) -> {
    String placeHolder = "•";
    String stencil = String.join(placeHolder, fragments);
    for (Object value : ts.values()) {
        String v = String.valueOf(value);
        stencil = stencil.replaceFirst(placeHolder, v);
    }
    return stencil;
};

int x = 10, y = 20;
String s = INTER."\{x} plus \{y} equals \{x + y}";
| 10 plus 20 equals 30

A template processor always executes at run time, never at compile time. It is not possible for a template processor to perform compile-time processing on the template. Moreover, it is not possible for a template processor to obtain, from a TemplatedString, the exact characters which appear in a template in source code; only the values of the embedded expressions are available, not the embedded expressions themselves.

Efficient template processors

We can make the interpolating template processor shown earlier more efficient by building up a result from fragments and values, taking advantage of the fact that every template represents an alternating sequence of fragments and values:

StringProcessor INTER = (TemplatedString ts) -> {
    StringBuilder sb = new StringBuilder();
    Iterator<String> fragIter = ts.fragments().iterator();
    for (Object value : ts.values()) {
        sb.append(fragIter.next());
        sb.append(value);
    }
    sb.append(fragIter.next());
    return sb.toString();
};

int x = 10, y = 20;
String s = INTER."\{x} plus \{y} equals \{x + y}";
| 10 and 20 equals 30

The auxiliary method TemplatedString::interpolate does the same thing as the code above, successively concatenating fragments and values, thus:

StringProcessor INTER = TemplatedString::interpolate;

Given that the values of embedded expressions are usually unpredictable, it is generally not worthwhile for a template processor to intern the String that it produces. For example, STR does not intern its result. However, it is straightforward to create an interning, interpolating template processor if needed:

StringProcessor INTERN = ts -> ts.interpolate().intern();

Run-time validation

All the examples so far have created template processors that implement the StringProcessor interface. Such template processors always return a String and perform no validation at run time, so string template expressions which use them will always evaluate successfully.

In contrast, a template processor that implements the TemplateProcessor interface is fully general: It may return objects of any type, not just String, and it may validate the string template and the values of embedded expressions, throwing a checked or unchecked exception if validation fails. By throwing a checked exception, the template processor forces developers who use it in string template expressions to handle invalid string composition with a try-catch statement.

The relationship between StringProcessor and TemplateProcessor is as follows:

public interface TemplateProcessor<R, E extends Throwable> {
    R apply(TemplatedString templatedString) throws E;
}

public interface SimpleProcessor<R> extends TemplateProcessor<R, RuntimeException> {}

public interface StringProcessor extends SimpleProcessor<String> {}

Note that the second type parameter of TemplateProcessor, E, is the type of the exception thrown by the apply method. A non-validating template processor will usually be declared to supply RuntimeException as the type argument for E. This allows developers to use the processor in string template expressions without try-catch statements. For convenience, TemplateProcessor has a subinterface, SimpleProcessor, which already supplies RuntimeException as the type argument.

Here is an example of a template processor, JSON. It implements SimpleProcessor<JSONObject> and therefore returns instances of JSONObject. It uses the auxiliary method TemplatedString::interpolate, shown earlier.

SimpleProcessor<JSONObject> JSON = (TemplatedString ts) -> new JSONObject(ts.interpolate());

String name    = "Joan Smith";
String phone   = "555-123-4567";
String address = "1 Maple Drive, Anytown";
JSONObject doc = JSON."""
    {
        "name":    "\{name}",
        "phone":   "\{phone}",
        "address": "\{address}"
    };
    """;

A developer who uses the JSON template processor never sees the String produced by ts.interpolate(). Moreover, since the text block template is constant, a more advanced template processor could compile the template into a JSONObject with placeholder values, cache that result, and then at each evaluation inject the field values into a fresh deep copy of that cached JSONObject. There would be no intermediate String anywhere.

A template processor that throws checked exceptions must implement TemplateProcessor directly. For example, here is a template processor that expects a JSON document to be surrounded by { }, throwing a checked exception at run time otherwise:

class JSONException extends Exception {}

TemplateProcessor<JSONObject, JSONException> JSON_VALIDATE = (TemplatedString ts) -> {
    String stripped = ts.interpolate().strip();
    if (!stripped.startsWith("{") || !stripped.endsWith("}")) {
        throws new JSONException("Missing brace");
    }
    return new JSONObject(stripped);
};

String name    = "Joan Smith";
String phone   = "555-123-4567";
String address = "1 Maple Drive, Anytown";
try {
    JSONObject doc = JSON_VALIDATE."""
        {
            "name":    "\{name}",
            "phone":   "\{phone}",
            "address": "\{address}"
        };
        """;
} catch (JSONException ex) {
    ...
}

Safely composing and executing database queries

The template processor below, QueryProcessor, first creates a query string from a string template. It then creates a PreparedStatement from that query string and sets its parameters to the values of the embedded expressions. Finally, the processor executes the PreparedStatement to obtain a ResultSet.

record QueryProcessor(Connection conn)
  implements TemplateProcessor<ResultSet, SQLException> {
    public ResultSet apply(TemplatedString ts) throws SQLException {
        // 1. Replace TemplatedString placeholders with PreparedStatement placeholders
        String query = String.join("?", ts.fragments());

        // 2. Create the PreparedStatement on the connection
        PreparedStatement ps = conn.prepareStatement(query);

        // 3. Set parameters of the PreparedStatement
        int index = 1;
        for (Object value : ts.values()) {
            switch (value) {
                case Integer i -> ps.setInt(index++, i);
                case Float f   -> ps.setFloat(index++, f);
                case Double d  -> ps.setDouble(index++, d);
                case Boolean b -> ps.setBoolean(index++, b);
                default        -> ps.setString(index++, String.valueOf(value));
            }
        }

        // 4. Execute the PreparedStatement, returning a ResultSet
        return ps.executeQuery();
    }
}

If we instantiate the QueryProcessor for a specific Connection:

TemplateProcessor<ResultSet, SQLException> DB = new QueryProcessor(...);

then instead of the unsafe, injection-attack-prone code

String query = "SELECT * FROM Person p WHERE p.last_name = '" + name + "'";
ResultSet rs = conn.createStatement().executeQuery(query);

we can write the more secure and more readable code

ResultSet rs = DB."SELECT * FROM Person p WHERE p.last_name = \{name}";

Localized formatter processors

FMT, shown earlier, is an instance of the format-aware template processor class java.util.FormatProcessor. That processor uses the default locale, but it is straightforward to create a variant for a different locale. For example, this code creates a format-aware template processor for the Thai locale, and stores it in the THAI variable:

Locale thaiLocale = Locale.forLanguageTag("th-TH-u-nu-thai");
FormatProcessor THAI = new FormatProcessor(thaiLocale);
for (int i = 1; i <= 10000; i *= 10) {
    String s = THAI."This answer is %5d\{i}";
    System.out.println(s);
}
| This answer is     ๑
| This answer is    ๑๐
| This answer is   ๑๐๐
| This answer is  ๑๐๐๐
| This answer is ๑๐๐๐๐

Simplifying message localization

Here is a template processor that simplifies working with resource bundles. For a given locale, it maps a string to a corresponding property in a resource bundle:

record LocalizationProcessor(Locale locale) implements StringProcessor {
    public String apply(TemplatedString ts) {
        ResourceBundle resource = ResourceBundle.getBundle("resources", locale);
        String stencil = String.join("_", ts.fragments());
        String msgFormat = resource.getString(stencil.replace(' ', '.'));
        return MessageFormat.format(msgFormat, ts.values().toArray());
    }
}

Assuming there is a property-file resource bundle for each locale:

# resources_en_CA.properties file
no.suitable._.found.for._(_)=\
    no suitable {0} found for {1}({2})

# resources_zh_CN.properties file
no.suitable._.found.for._(_)=\
    \u5BF9\u4E8E{1}({2}), \u627E\u4E0D\u5230\u5408\u9002\u7684{0}

# resources_jp.properties file
no.suitable._.found.for._(_)=\
    {1}\u306B\u9069\u5207\u306A{0}\u304C\u898B\u3064\u304B\u308A\u307E\u305B\u3093({2})

then a program can compose a localized string based upon the property:

var userLocale = new Locale("en", "CA");
var LOCALIZE = new LocalizationProcessor(userLocale);
...
var symbolKind = "field", name = "tax", type = "double";
System.out.println(LOCALIZE."no suitable \{symbolKind} found for \{name}(\{type})");

and the template processor will map the string to the corresponding property in the locale-appropriate resource bundle:

no suitable field found for tax(double)

If the program instead performed

var userLocale = new Locale("zh", "CN");

then the output would be:

对于tax(double), 找不到合适的field

Finally, if the program instead performed

var userLocale = new Locale("jp");

then the output would be:

taxに適切なfieldが見つかりません(double)

Alternatives

When a string template appears without a template processor then we could simply perform basic interpolation. However, this choice would violate the safety goal. It would be too tempting to construct SQL queries using interpolation, for example, and this would in the aggregate reduce the safety of Java programs. Always requiring a template processor ensures that the developer at least recognizes the possibility of domain-specific rules in a string template.
The syntax of a string template expression — with the template processor appearing first — is not strictly necessary. It would be possible to denote the template processor as an argument to TemplatedString::apply. For example:
```
String s = "The answer is %5d\{i}".apply(FMT);
```
Having the template processor appear first is preferable because the result of evaluating the string template expression is entirely dependent on the operation of the template processor.
For the syntax of embedded expressions we considered using ${...}, but that would require a tag on string templates (either a prefix or a delimiter other than ") to avoid conflicts with legacy code. We also considered \[...] and \(...), but [ ] and ( ) are likely to appear in embedded expressions; { } is less likely to appear, so visually determining the start and end of embedded expressions will be easier.
It would be possible to bake format specifiers into string templates, as done in C#:
```
var date = DateTime.Now;
Console.WriteLine($"The time is {date:HH:mm}");
```
but this would require changes to the Java Language Specification any time a new format specifier is introduced.

Risks and Assumptions

The implementation of java.util.FormatProcessor depends strongly upon java.util.Formatter, which may require a significant rewrite.

Summary

Goals

Non-Goals

Motivation

String interpolation

String interpolation is dangerous

Can we do better?

Description

The `STR` template processor

Multi-line string template expressions

The `FMT` template processor

String template expressions without a template processor

Syntax and semantics

String literals inside string template expressions

String templates outside string template expressions

User-defined template processors

Efficient template processors

Run-time validation

Safely composing and executing database queries

Localized formatter processors

Simplifying message localization

Alternatives

Risks and Assumptions

Recommend

Instagram sputters back to life just as abruptly as it went down

继天籁银发关爱基金后,腾讯或在关注老年听障公益领域再加码-品玩

With new AirPods on the way, it’s a great time to sell your old buds

百度百科召开学术委员会首期研讨会，以权威知识打造普惠大众窗口-品玩

Action Space Shaping in Deep Reinforcement Learning 阅读

Apple iOS 16.0.2 fixes iPhone 14 Pro camera issue and other bugs

How to use the HDR Calibration app on Windows 11

The New Chromecast With Google TV (HD) Is Even Cheaper Than The Original

Tesla issues recall for 1.1 million EVs due to power window problem

Interview Questions on NLP Fundamentals

About Joyk

JEP 430: String Templates (Preview)

Summary

Goals

Non-Goals

Motivation

String interpolation

String interpolation is dangerous

Can we do better?

Description

The STR template processor

Multi-line string template expressions

The FMT template processor

String template expressions without a template processor

Syntax and semantics

String literals inside string template expressions

String templates outside string template expressions

User-defined template processors

Efficient template processors

Run-time validation

Safely composing and executing database queries

Localized formatter processors

Simplifying message localization

Alternatives

Risks and Assumptions

Recommend

About Joyk

The `STR` template processor

The `FMT` template processor