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: