public 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.StringTemplate
PREVIEW must minimally implement the methods fragments()
and values()
. Instances of StringTemplate
PREVIEW 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()
.Modifier and Type | Interface | Description |
---|---|---|
static interface |
StringTemplate.ProcessorPREVIEW<R, |
Preview. This interface describes the methods provided by a generalized string template processor. |
Modifier and Type | Field | Description |
---|---|---|
static final StringTemplate.ProcessorPREVIEW |
RAW |
This StringTemplate.Processor PREVIEW instance is conventionally used to indicate that the processing of the StringTemplate PREVIEW is to be deferred to a later time. |
static final StringTemplate.ProcessorPREVIEW |
STR |
This StringTemplate.Processor PREVIEW instance is conventionally used for the string interpolation of a supplied StringTemplate PREVIEW. |
Modifier and Type | Method | Description |
---|---|---|
static StringTemplatePREVIEW |
combine |
|
static StringTemplatePREVIEW |
combine |
|
List |
fragments() |
Returns a list of fragment literals for this StringTemplate PREVIEW. |
default String |
interpolate() |
Returns the string interpolation of the fragments and values for this StringTemplate PREVIEW. |
static String |
interpolate |
Creates a string that interleaves the elements of values between the elements of fragments. |
static StringTemplatePREVIEW |
of |
Returns a StringTemplate PREVIEW as if constructed by invoking StringTemplate.of(List.of(string), List.of()) . |
static StringTemplatePREVIEW |
of |
Returns a StringTemplate with the given fragments and values. |
default <R, |
process |
Returns the result of applying the specified processor to this StringTemplate PREVIEW. |
static String |
toString |
Produces a diagnostic string that describes the fragments and values of the supplied StringTemplate PREVIEW. |
List |
values() |
Returns a list of embedded expression results for this StringTemplate PREVIEW. |
static final StringTemplate.ProcessorPREVIEW<String,RuntimeException> STR
StringTemplate.Processor
PREVIEW instance is conventionally used for the string interpolation of a supplied StringTemplate
PREVIEW. For better visibility and when practical, it is recommended that users use the STR
processor instead of invoking the interpolate()
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 supplied StringTemplate
PREVIEW. To accommodate concatenation, values are converted to strings as if invoking String.valueOf(Object)
.STR
is statically imported implicitly into every Java compilation unit.static final StringTemplate.ProcessorPREVIEW<StringTemplatePREVIEW,RuntimeException> RAW
StringTemplate.Processor
PREVIEW instance is conventionally used to indicate that the processing of the StringTemplate
PREVIEW is to be deferred to a later time. Deferred processing can be resumed by invoking the process(Processor)
or StringTemplate.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);
List<String> fragments()
StringTemplate
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 to List.of("The student ", " is in ", "'s classroom.")
List<Object> values()
StringTemplate
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 to List.of(student, teacher)
default String interpolate()
StringTemplate
PREVIEW.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();
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 StringTemplate
PREVIEW. To accommodate concatenation, values are converted to strings as if invoking String.valueOf(Object)
.StringTemplate.interpolate(this.fragments(), this.values())
.StringTemplate
PREVIEW
default <R, E extends Throwable> R process(StringTemplate.ProcessorPREVIEW<? extends R,? extends E> processor) throws E
StringTemplate
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
and result2
.processor.process(this)
. If the invocation throws an exception that exception is forwarded to the caller.R
- Processor's process result type.E
- Exception thrown type.processor
- the StringTemplate.Processor
PREVIEW instance to processR
E
- exception thrown by the template processor when validation failsNullPointerException
- if processor is nullstatic String toString(StringTemplatePREVIEW stringTemplate)
StringTemplate
PREVIEW.stringTemplate
- the StringTemplate
PREVIEW to representNullPointerException
- if stringTemplate is nullstatic StringTemplatePREVIEW of(String string)
StringTemplate
PREVIEW as if constructed by invoking StringTemplate.of(List.of(string), List.of())
. That is, a StringTemplate
PREVIEW with one fragment and no values.string
- single string fragmentNullPointerException
- if string is nullstatic StringTemplatePREVIEW of(List<String> fragments, List<?> values)
fragments
list size must be one more that the values
list size.fragments
- list of string fragmentsvalues
- list of expression valuesIllegalArgumentException
- 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.static String interpolate(List<String> fragments, List<?> values)
String.valueOf(Object)
.fragments
- list of String fragmentsvalues
- list of expression valuesIllegalArgumentException
- if fragments list size is not one more than values list sizeNullPointerException
- fragments or values is null or if any of the fragments is nullstatic StringTemplatePREVIEW combine(StringTemplatePREVIEW... stringTemplates)
StringTemplates
PREVIEW into a single StringTemplate
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 each StringTemplate
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 combining StringTemplates
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 supplied StringTemplates
PREVIEW.StringTemplate
PREVIEW arguments are provided then a StringTemplate
PREVIEW with an empty fragment and no values is returned, as if invoking StringTemplate.of("")
. If only one StringTemplate
PREVIEW argument is provided then it is returned unchanged.stringTemplates
- zero or more StringTemplate
PREVIEW
StringTemplate
PREVIEW
NullPointerException
- if stringTemplates is null or if any of the stringTemplates
are nullstatic StringTemplatePREVIEW combine(List<StringTemplatePREVIEW> stringTemplates)
StringTemplates
PREVIEW into a single StringTemplate
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 each StringTemplate
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 combining StringTemplates
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 supplied StringTemplates
PREVIEW.stringTemplates.size() == 0
then a StringTemplate
PREVIEW 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.stringTemplates
- list of StringTemplate
PREVIEW
StringTemplate
PREVIEW
NullPointerException
- if stringTemplates is null or if any of the its elements are null
© 1993, 2023, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/lang/StringTemplate.html
StringTemplate
when preview features are enabled.