Module java.base
Package java.lang

Interface StringTemplate

public interface StringTemplate
StringTemplate is a preview API of the Java platform.
Programs can only use StringTemplate when preview features are enabled.
Preview features may be removed in a future release, or upgraded to permanent features of the Java platform.
StringTemplatePREVIEW is the run-time representation of a string template or text block template in a template expression.

In the source code of a Java program, a string template or text block template contains an interleaved succession of fragment literals and embedded expressions. The fragments() method returns the fragment literals, and the values() method returns the results of evaluating the embedded expressions. StringTemplatePREVIEW does not provide access to the source code of the embedded expressions themselves; it is not a compile-time representation of a string template or text block template.

StringTemplatePREVIEW is primarily used in conjunction with a template processor to produce a string or other meaningful value. Evaluation of a template expression first produces an instance of StringTemplatePREVIEW, representing the right hand side of the template expression, and then passes the instance to the template processor given by the template expression.

For example, the following code contains a template expression that uses the template processor RAW, which simply yields the StringTemplatePREVIEW passed to it: 

int x = 10;
int y = 20;
StringTemplate st = RAW."\{x} + \{y} = \{x + y}";
List<String> fragments = st.fragments();
List<Object> values = st.values();
fragments will be equivalent to List.of("", " + ", " = ", ""), which includes the empty first and last fragments. values will be the equivalent of List.of(10, 20, 30).

The following code contains a template expression with the same template but with a different template processor, STR: 

int x = 10;
int y = 20;
String s = STR."\{x} + \{y} = \{x + y}";
When the template expression is evaluated, an instance of StringTemplatePREVIEW is produced that returns the same lists from fragments() and values() as shown above. The STR template processor uses these lists to yield an interpolated string. The value of s will be equivalent to "10 + 20 = 30".

The interpolate() method provides a direct way to perform string interpolation of a StringTemplatePREVIEW. Template processors can use the following code pattern: 

List<String> fragments = st.fragments();
List<Object> values    = st.values();
... check or manipulate the fragments and/or values ...
String result = StringTemplate.interpolate(fragments, values);
The process(Processor) method, in conjunction with the RAW processor, may be used to defer processing of a StringTemplatePREVIEW. 
StringTemplate st = RAW."\{x} + \{y} = \{x + y}";
...other steps...
String result = st.process(STR);
The factory methods of(String) and of(List, List) can be used to construct a StringTemplatePREVIEW.
Implementation Note:
Implementations of StringTemplatePREVIEW must minimally implement the methods fragments() and values(). Instances of StringTemplatePREVIEW are considered immutable. To preserve the semantics of string templates and text block templates, the list returned by fragments() must be one element larger than the list returned by values().
See Java Language Specification:
15.8.6 Process Template Expressions
Since:
21
See Also:

  • Field Details

  • Method Details

    • fragments

      List<String> fragments()
      Returns a list of fragment literals for this StringTemplatePREVIEW. The fragment literals are the character sequences preceding each of the embedded expressions in source code, plus the character sequence following the last embedded expression. Such character sequences may be zero-length if an embedded expression appears at the beginning or end of a template, or if two embedded expressions are directly adjacent in a template. In the example: 
      String student = "Mary";
String teacher = "Johnson";
StringTemplate st = RAW."The student \{student} is in \{teacher}'s classroom.";
List<String> fragments = st.fragments();
      fragments will be equivalent to List.of("The student ", " is in ", "'s classroom.")
      Implementation Requirements:
      the list returned is immutable
      Returns:
      list of string fragments

    • values

      List<Object> values()
      Returns a list of embedded expression results for this StringTemplatePREVIEW. In the example: 
      String student = "Mary";
String teacher = "Johnson";
StringTemplate st = RAW."The student \{student} is in \{teacher}'s classroom.";
List<Object> values = st.values();
      values will be equivalent to List.of(student, teacher)
      Implementation Requirements:
      the list returned is immutable
      Returns:
      list of expression values

    • interpolate

      default String interpolate()
      Returns the string interpolation of the fragments and values for this StringTemplatePREVIEW.
      API Note:
      For better visibility and when practical, it is recommended to use the STR processor instead of invoking the interpolate() method. 
      String student = "Mary";
String teacher = "Johnson";
StringTemplate st = RAW."The student \{student} is in \{teacher}'s classroom.";
String result = st.interpolate();
      In the above example, the value of result will be "The student Mary is in Johnson's classroom.". This is produced by the interleaving concatenation of fragments and values from the supplied StringTemplatePREVIEW. To accommodate concatenation, values are converted to strings as if invoking String.valueOf(Object).
      Implementation Requirements:
      The default implementation returns the result of invoking StringTemplate.interpolate(this.fragments(), this.values()).
      Returns:
      interpolation of this StringTemplatePREVIEW

    • process

      default <R, E extends Throwable> R process(StringTemplate.ProcessorPREVIEW<? extends R,? extends E> processor) throws E
      Returns the result of applying the specified processor to this StringTemplatePREVIEW. This method can be used as an alternative to string template expressions. For example, 
      String student = "Mary";
String teacher = "Johnson";
String result1 = STR."The student \{student} is in \{teacher}'s classroom.";
String result2 = RAW."The student \{student} is in \{teacher}'s classroom.".process(STR);
      Produces an equivalent result for both result1 and result2.
      Implementation Requirements:
      The default implementation returns the result of invoking processor.process(this). If the invocation throws an exception that exception is forwarded to the caller.
      Type Parameters:
      R - Processor's process result type.
      E - Exception thrown type.
      Parameters:
      processor - the StringTemplate.ProcessorPREVIEW instance to process
      Returns:
      constructed object of type R
      Throws:
      E - exception thrown by the template processor when validation fails
      NullPointerException - if processor is null

    • toString

      static String toString(StringTemplatePREVIEW stringTemplate)
      Produces a diagnostic string that describes the fragments and values of the supplied StringTemplatePREVIEW.
      Parameters:
      stringTemplate - the StringTemplatePREVIEW to represent
      Returns:
      diagnostic string representing the supplied string template
      Throws:
      NullPointerException - if stringTemplate is null

    • of

      static StringTemplatePREVIEW of(String string)
      Returns a StringTemplatePREVIEW as if constructed by invoking StringTemplate.of(List.of(string), List.of()). That is, a StringTemplatePREVIEW with one fragment and no values.
      Parameters:
      string - single string fragment
      Returns:
      StringTemplate composed from string
      Throws:
      NullPointerException - if string is null

    • of

      static StringTemplatePREVIEW of(List<String> fragments, List<?> values)
      Returns a StringTemplate with the given fragments and values.
      Implementation Requirements:
      The fragments list size must be one more that the values list size.
      Implementation Note:
      Contents of both lists are copied to construct immutable lists.
      Parameters:
      fragments - list of string fragments
      values - list of expression values
      Returns:
      StringTemplate composed from string
      Throws:
      IllegalArgumentException - if fragments list size is not one more than values list size
      NullPointerException - if fragments is null or values is null or if any fragment is null.

    • interpolate

      static String interpolate(List<String> fragments, List<?> values)
      Creates a string that interleaves the elements of values between the elements of fragments. To accommodate interpolation, values are converted to strings as if invoking String.valueOf(Object).
      Parameters:
      fragments - list of String fragments
      values - list of expression values
      Returns:
      String interpolation of fragments and values
      Throws:
      IllegalArgumentException - if fragments list size is not one more than values list size
      NullPointerException - fragments or values is null or if any of the fragments is null

    • combine

      static StringTemplatePREVIEW combine(StringTemplatePREVIEW... stringTemplates)
      Combine zero or more StringTemplatesPREVIEW into a single StringTemplatePREVIEW. 
      StringTemplate st = StringTemplate.combine(RAW."\{a}", RAW."\{b}", RAW."\{c}");
assert st.interpolate().equals(STR."\{a}\{b}\{c}");
      Fragment lists from the StringTemplatesPREVIEW are combined end to end with the last fragment from each StringTemplatePREVIEW concatenated with the first fragment of the next. To demonstrate, if we were to take two strings and we combined them as follows: 
      String s1 = "abc";
String s2 = "xyz";
String sc = s1 + s2;
assert Objects.equals(sc, "abcxyz");
      the last character "c" from the first string is juxtaposed with the first character "x" of the second string. The same would be true of combining StringTemplatesPREVIEW. 
      StringTemplate st1 = RAW."a\{}b\{}c";
StringTemplate st2 = RAW."x\{}y\{}z";
StringTemplate st3 = RAW."a\{}b\{}cx\{}y\{}z";
StringTemplate stc = StringTemplate.combine(st1, st2);

assert Objects.equals(st1.fragments(), List.of("a", "b", "c"));
assert Objects.equals(st2.fragments(), List.of("x", "y", "z"));
assert Objects.equals(st3.fragments(), List.of("a", "b", "cx", "y", "z"));
assert Objects.equals(stc.fragments(), List.of("a", "b", "cx", "y", "z"));
      Values lists are simply concatenated to produce a single values list. The result is a well-formed StringTemplatePREVIEW with n+1 fragments and n values, where n is the total of number of values across all the supplied StringTemplatesPREVIEW.
      Implementation Note:
      If zero StringTemplatePREVIEW arguments are provided then a StringTemplatePREVIEW with an empty fragment and no values is returned, as if invoking StringTemplate.of("") . If only one StringTemplatePREVIEW argument is provided then it is returned unchanged.
      Parameters:
      stringTemplates - zero or more StringTemplatePREVIEW
      Returns:
      combined StringTemplatePREVIEW
      Throws:
      NullPointerException - if stringTemplates is null or if any of the stringTemplates are null

    • combine

      static StringTemplatePREVIEW combine(List<StringTemplatePREVIEW> stringTemplates)
      Combine a list of StringTemplatesPREVIEW into a single StringTemplatePREVIEW. 
      StringTemplate st = StringTemplate.combine(List.of(RAW."\{a}", RAW."\{b}", RAW."\{c}"));
assert st.interpolate().equals(STR."\{a}\{b}\{c}");
      Fragment lists from the StringTemplatesPREVIEW are combined end to end with the last fragment from each StringTemplatePREVIEW concatenated with the first fragment of the next. To demonstrate, if we were to take two strings and we combined them as follows: 
      String s1 = "abc";
String s2 = "xyz";
String sc = s1 + s2;
assert Objects.equals(sc, "abcxyz");
      the last character "c" from the first string is juxtaposed with the first character "x" of the second string. The same would be true of combining StringTemplatesPREVIEW. 
      StringTemplate st1 = RAW."a\{}b\{}c";
StringTemplate st2 = RAW."x\{}y\{}z";
StringTemplate st3 = RAW."a\{}b\{}cx\{}y\{}z";
StringTemplate stc = StringTemplate.combine(List.of(st1, st2));

assert Objects.equals(st1.fragments(), List.of("a", "b", "c"));
assert Objects.equals(st2.fragments(), List.of("x", "y", "z"));
assert Objects.equals(st3.fragments(), List.of("a", "b", "cx", "y", "z"));
assert Objects.equals(stc.fragments(), List.of("a", "b", "cx", "y", "z"));
      Values lists are simply concatenated to produce a single values list. The result is a well-formed StringTemplatePREVIEW with n+1 fragments and n values, where n is the total of number of values across all the supplied StringTemplatesPREVIEW.
      Implementation Note:
      If stringTemplates.size() == 0 then a StringTemplatePREVIEW with an empty fragment and no values is returned, as if invoking StringTemplate.of("") . If stringTemplates.size() == 1 then the first element of the list is returned unchanged.
      Parameters:
      stringTemplates - list of StringTemplatePREVIEW
      Returns:
      combined StringTemplatePREVIEW
      Throws:
      NullPointerException - if stringTemplates is null or if any of the its elements are null