Interface StringTemplate
StringTemplate
is a preview API of the Java platform.
StringTemplate
PREVIEW 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. StringTemplate
PREVIEW 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.
StringTemplate
PREVIEW 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 StringTemplate
PREVIEW, 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 StringTemplate
PREVIEW 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}";
StringTemplate
PREVIEW 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 StringTemplate
PREVIEW. 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);
process(Processor)
method, in conjunction with
the RAW
processor, may be used to defer processing of a
StringTemplate
PREVIEW.
StringTemplate st = RAW."\{x} + \{y} = \{x + y}";
...other steps...
String result = st.process(STR);
of(String)
and
of(List, List)
can be used to construct a StringTemplate
PREVIEW.- Implementation Note:
- Implementations of
StringTemplate
PREVIEW must minimally implement the methodsfragments()
andvalues()
. Instances ofStringTemplate
PREVIEW are considered immutable. To preserve the semantics of string templates and text block templates, the list returned byfragments()
must be one element larger than the list returned byvalues()
. - See Java Language Specification:
-
15.8.6 Process Template Expressions
- Since:
- 21
- See Also:
-
Nested Class Summary
Modifier and TypeInterfaceDescriptionstatic interface
StringTemplate.ProcessorPREVIEW<R,
E extends Throwable> Preview.This interface describes the methods provided by a generalized string template processor. -
Field Summary
Modifier and TypeFieldDescriptionThisStringTemplate.Processor
PREVIEW instance is conventionally used to indicate that the processing of theStringTemplate
PREVIEW is to be deferred to a later time.static final StringTemplate.ProcessorPREVIEW
<String, RuntimeException> ThisStringTemplate.Processor
PREVIEW instance is conventionally used for the string interpolation of a suppliedStringTemplate
PREVIEW. -
Method Summary
Modifier and TypeMethodDescriptionstatic StringTemplatePREVIEW
combine
(StringTemplatePREVIEW... stringTemplates) static StringTemplatePREVIEW
combine
(List<StringTemplatePREVIEW> stringTemplates) Returns a list of fragment literals for thisStringTemplate
PREVIEW.default String
Returns the string interpolation of the fragments and values for thisStringTemplate
PREVIEW.static String
interpolate
(List<String> fragments, List<?> values) Creates a string that interleaves the elements of values between the elements of fragments.static StringTemplatePREVIEW
Returns aStringTemplate
PREVIEW as if constructed by invokingStringTemplate.of(List.of(string), List.of())
.static StringTemplatePREVIEW
Returns a StringTemplate with the given fragments and values.default <R,
E extends Throwable>
Rprocess
(StringTemplate.ProcessorPREVIEW<? extends R, ? extends E> processor) Returns the result of applying the specified processor to thisStringTemplate
PREVIEW.static String
toString
(StringTemplatePREVIEW stringTemplate) Produces a diagnostic string that describes the fragments and values of the suppliedStringTemplate
PREVIEW.values()
Returns a list of embedded expression results for thisStringTemplate
PREVIEW.
-
Field Details
-
STR
ThisStringTemplate.Processor
PREVIEW instance is conventionally used for the string interpolation of a suppliedStringTemplate
PREVIEW.For better visibility and when practical, it is recommended that users use the
STR
processor instead of invoking theinterpolate()
method. Example:int x = 10; int y = 20; String result = STR."\{x} + \{y} = \{x + y}";
result
will be"10 + 20 = 30"
. This is produced by the interleaving concatenation of fragments and values from the suppliedStringTemplate
PREVIEW. To accommodate concatenation, values are converted to strings as if invokingString.valueOf(Object)
.- API Note:
STR
is statically imported implicitly into every Java compilation unit.
-
RAW
ThisStringTemplate.Processor
PREVIEW instance is conventionally used to indicate that the processing of theStringTemplate
PREVIEW is to be deferred to a later time. Deferred processing can be resumed by invoking theprocess(Processor)
orStringTemplate.Processor.process(StringTemplate)
PREVIEW methods.import static java.lang.StringTemplate.RAW; ... StringTemplate st = RAW."\{x} + \{y} = \{x + y}"; ...other steps... String result = STR.process(st);
-
-
Method Details
-
fragments
Returns a list of fragment literals for thisStringTemplate
PREVIEW. 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 toList.of("The student ", " is in ", "'s classroom.")
- Implementation Requirements:
- the list returned is immutable
- Returns:
- list of string fragments
-
values
Returns a list of embedded expression results for thisStringTemplate
PREVIEW. 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 toList.of(student, teacher)
- Implementation Requirements:
- the list returned is immutable
- Returns:
- list of expression values
-
interpolate
Returns the string interpolation of the fragments and values for thisStringTemplate
PREVIEW.- API Note:
- For better visibility and when practical, it is recommended to use the
STR
processor instead of invoking theinterpolate()
method.String student = "Mary"; String teacher = "Johnson"; StringTemplate st = RAW."The student \{student} is in \{teacher}'s classroom."; String result = st.interpolate();
result
will be"The student Mary is in Johnson's classroom."
. This is produced by the interleaving concatenation of fragments and values from the suppliedStringTemplate
PREVIEW. To accommodate concatenation, values are converted to strings as if invokingString.valueOf(Object)
. - Implementation Requirements:
- The default implementation returns the result of invoking
StringTemplate.interpolate(this.fragments(), this.values())
. - Returns:
- interpolation of this
StringTemplate
PREVIEW
-
process
default <R,E extends Throwable> R process(StringTemplate.ProcessorPREVIEW<? extends R, ? extends E> processor) throws EReturns the result of applying the specified processor to thisStringTemplate
PREVIEW. 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);
result1
andresult2
.- 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
- theStringTemplate.Processor
PREVIEW instance to process- Returns:
- constructed object of type
R
- Throws:
E
- exception thrown by the template processor when validation failsNullPointerException
- if processor is null
-
toString
Produces a diagnostic string that describes the fragments and values of the suppliedStringTemplate
PREVIEW.- Parameters:
stringTemplate
- theStringTemplate
PREVIEW to represent- Returns:
- diagnostic string representing the supplied string template
- Throws:
NullPointerException
- if stringTemplate is null
-
of
Returns aStringTemplate
PREVIEW as if constructed by invokingStringTemplate.of(List.of(string), List.of())
. That is, aStringTemplate
PREVIEW with one fragment and no values.- Parameters:
string
- single string fragment- Returns:
- StringTemplate composed from string
- Throws:
NullPointerException
- if string is null
-
of
Returns a StringTemplate with the given fragments and values.- Implementation Requirements:
- The
fragments
list size must be one more that thevalues
list size. - Implementation Note:
- Contents of both lists are copied to construct immutable lists.
- Parameters:
fragments
- list of string fragmentsvalues
- list of expression values- Returns:
- StringTemplate composed from string
- Throws:
IllegalArgumentException
- if fragments list size is not one more than values list sizeNullPointerException
- if fragments is null or values is null or if any fragment is null.
-
interpolate
Creates a string that interleaves the elements of values between the elements of fragments. To accommodate interpolation, values are converted to strings as if invokingString.valueOf(Object)
.- Parameters:
fragments
- list of String fragmentsvalues
- list of expression values- Returns:
- String interpolation of fragments and values
- Throws:
IllegalArgumentException
- if fragments list size is not one more than values list sizeNullPointerException
- fragments or values is null or if any of the fragments is null
-
combine
Combine zero or moreStringTemplates
PREVIEW into a singleStringTemplate
PREVIEW.StringTemplate st = StringTemplate.combine(RAW."\{a}", RAW."\{b}", RAW."\{c}"); assert st.interpolate().equals(STR."\{a}\{b}\{c}");
StringTemplates
PREVIEW are combined end to end with the last fragment from eachStringTemplate
PREVIEW 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");
"c"
from the first string is juxtaposed with the first character"x"
of the second string. The same would be true of combiningStringTemplates
PREVIEW.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"));
StringTemplate
PREVIEW with n+1 fragments and n values, where n is the total of number of values across all the suppliedStringTemplates
PREVIEW.- Implementation Note:
- If zero
StringTemplate
PREVIEW arguments are provided then aStringTemplate
PREVIEW with an empty fragment and no values is returned, as if invokingStringTemplate.of("")
. If only oneStringTemplate
PREVIEW argument is provided then it is returned unchanged. - Parameters:
stringTemplates
- zero or moreStringTemplate
PREVIEW- Returns:
- combined
StringTemplate
PREVIEW - Throws:
NullPointerException
- if stringTemplates is null or if any of thestringTemplates
are null
-
combine
Combine a list ofStringTemplates
PREVIEW into a singleStringTemplate
PREVIEW.StringTemplate st = StringTemplate.combine(List.of(RAW."\{a}", RAW."\{b}", RAW."\{c}")); assert st.interpolate().equals(STR."\{a}\{b}\{c}");
StringTemplates
PREVIEW are combined end to end with the last fragment from eachStringTemplate
PREVIEW 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");
"c"
from the first string is juxtaposed with the first character"x"
of the second string. The same would be true of combiningStringTemplates
PREVIEW.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"));
StringTemplate
PREVIEW with n+1 fragments and n values, where n is the total of number of values across all the suppliedStringTemplates
PREVIEW.- Implementation Note:
- If
stringTemplates.size() == 0
then aStringTemplate
PREVIEW with an empty fragment and no values is returned, as if invokingStringTemplate.of("")
. IfstringTemplates.size() == 1
then the first element of the list is returned unchanged. - Parameters:
stringTemplates
- list ofStringTemplate
PREVIEW- Returns:
- combined
StringTemplate
PREVIEW - Throws:
NullPointerException
- if stringTemplates is null or if any of the its elements are null
-
StringTemplate
when preview features are enabled.