モジュール java.base
パッケージ java.lang

インタフェースStringTemplate

public interface StringTemplate
StringTemplateは、JavaプラットフォームのプレビューAPIです。
プレビュー機能が有効な場合のみ、プログラムでStringTemplateを使用できます。
プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
StringTemplatePREVIEWは、テンプレート式内の文字列テンプレートまたはテキスト・ブロック・テンプレートの実行時表現です。

Javaプログラムのソース・コードでは、文字列テンプレートまたはテキスト・ブロック・テンプレートに、「フラグメント・リテラル」および「埋込み式」のインタリーブ後継が含まれます。 fragments()メソッドはフラグメント・リテラルを返し、values()メソッドは埋込み式を評価した結果を返します。 StringTemplatePREVIEWでは、埋込み式自体のソース・コードへのアクセスは提供されません。文字列テンプレートまたはテキスト・ブロック・テンプレートのコンパイル時表現ではありません。

StringTemplatePREVIEWは主にテンプレート・プロセッサと組み合せて使用され、文字列またはその他の意味のある値を生成します。 テンプレート式の評価では、最初にテンプレート式の右側を表すStringTemplatePREVIEWのインスタンスが生成され、次にテンプレート式によって指定されたテンプレート・プロセッサにインスタンスが渡されます。

たとえば、次のコードには、テンプレート・プロセッサRAWを使用するテンプレート式が含まれています。テンプレート・プロセッサRAWでは、渡されたStringTemplatePREVIEWが単に生成されます: 

int x = 10;
int y = 20;
StringTemplate st = RAW."\{x} + \{y} = \{x + y}";
List<String> fragments = st.fragments();
List<Object> values = st.values();
fragmentsは、空の最初と最後のフラグメントを含むList.of("", " + ", " = ", "")と同等です。valuesは、List.of(10, 20, 30)と同等です。

次のコードには、同じテンプレートを使用するテンプレート式が含まれていますが、テンプレート・プロセッサSTRは異なります: 

int x = 10;
int y = 20;
String s = STR."\{x} + \{y} = \{x + y}";
テンプレート式が評価されると、StringTemplatePREVIEWのインスタンスが生成され、前述のようにfragments()およびvalues()から同じリストが返されます。 STRテンプレート・プロセッサは、これらのリストを使用して補間された文字列を生成します。 sの値は、"10 + 20 = 30"と同等です。

interpolate()メソッドは、StringTemplatePREVIEWの文字列補間を実行する直接的な方法を提供します。 テンプレート・プロセッサでは、次のコード・パターンを使用できます: 

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)メソッドをRAWプロセッサと組み合せて使用すると、StringTemplatePREVIEWの処理を遅延できます。 
StringTemplate st = RAW."\{x} + \{y} = \{x + y}";
...other steps...
String result = st.process(STR);
ファクトリ・メソッドof(String)およびof(List, List)を使用して、StringTemplatePREVIEWを構築できます。

実装上のノート:
StringTemplatePREVIEWの実装では、fragments()およびvalues()メソッドを最小限に実装する必要があります。 StringTemplatePREVIEWのインスタンスは不変とみなされます。 文字列テンプレートおよびテキスト・ブロック・テンプレートのセマンティクスを保持するには、fragments()によって返されるリストは、values()によって返されるリストより大きい1つの要素である必要があります。
Java言語仕様を参照してください:
「15.8.6 テンプレート式の処理」
導入されたバージョン:
21
関連項目:

  • フィールド詳細

  • メソッドの詳細

    • fragments

      List<String> fragments()
      このStringTemplatePREVIEWのフラグメント・リテラルのリストを返します。 フラグメント・リテラルは、ソース・コードの各埋込み式の前の文字シーケンスと、最後の埋込み式の後の文字シーケンスです。 埋込み式がテンプレートの先頭または末尾に表示される場合、または2つの埋込み式がテンプレート内で直接隣り合っている場合、このような文字シーケンスは長さゼロになることがあります。 この例では: 
      String student = "Mary";
String teacher = "Johnson";
StringTemplate st = RAW."The student \{student} is in \{teacher}'s classroom.";
List<String> fragments = st.fragments();
      fragmentsはList.of("The student ", " is in ", "'s classroom.")と同等です
      実装要件:
      返されるリストは不変です
      戻り値:
      文字列フラグメントのリスト

    • values

      List<Object> values()
      このStringTemplatePREVIEWの埋込み式の結果のリストを返します。 この例では: 
      String student = "Mary";
String teacher = "Johnson";
StringTemplate st = RAW."The student \{student} is in \{teacher}'s classroom.";
List<Object> values = st.values();
      valuesはList.of(student, teacher)と同等です
      実装要件:
      返されるリストは不変です
      戻り値:
      式の値のリスト

    • interpolate

      default String interpolate()
      このStringTemplatePREVIEWのフラグメントおよび値の文字列補間を返します。
      APIのノート:
      可視性を高めるため、実際的な場合は、interpolate()メソッドを起動するかわりにSTRプロセッサを使用することをお薦めします。 
      String student = "Mary";
String teacher = "Johnson";
StringTemplate st = RAW."The student \{student} is in \{teacher}'s classroom.";
String result = st.interpolate();
      前述の例では、resultの値は"The student Mary is in Johnson's classroom."になります。 これは、指定されたStringTemplatePREVIEWからのフラグメントと値のインターリーブ連結によって生成されます。 連結に対応するために、値はString.valueOf(Object)を呼び出すかのように文字列に変換されます。
      実装要件:
      デフォルトの実装では、StringTemplate.interpolate(this.fragments(), this.values())の呼出しの結果が返されます。
      戻り値:
      このStringTemplatePREVIEWの補間

    • process

      default <R, E extends Throwable> R process(StringTemplate.ProcessorPREVIEW<? extends R,? extends E> processor) throws E
      指定されたプロセッサをこのStringTemplatePREVIEWに適用した結果を返します。 このメソッドは、文字列テンプレート式の代替として使用できます。 たとえば、 
      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とresult2の両方で同等の結果が生成されます。
      実装要件:
      デフォルトの実装では、processor.process(this)の呼出しの結果が返されます。 呼出しで例外がスローされた場合、例外は呼出し元に転送されます。
      型パラメータ:
      R - プロセッサのプロセス結果タイプ。
      E - 例外スロー・タイプ。
      パラメータ:
      processor - 処理するStringTemplate.ProcessorPREVIEWインスタンス
      戻り値:
      R型の構築されたオブジェクト
      例外:
      E - 検証が失敗したときにテンプレート・プロセッサによってスローされた例外
      NullPointerException - プロセッサがnullの場合

    • toString

      static String toString(StringTemplatePREVIEW stringTemplate)
      指定されたStringTemplatePREVIEWのフラグメントおよび値を説明する診断文字列を生成します。
      パラメータ:
      stringTemplate - 表すStringTemplatePREVIEW
      戻り値:
      指定された文字列テンプレートを表す診断文字列
      例外:
      NullPointerException - stringTemplateがnullの場合

    • of

      static StringTemplatePREVIEW of(String string)
      StringTemplatePREVIEWをStringTemplate.of(List.of(string), List.of())を呼び出すことによって構築されたかのように返します。 つまり、StringTemplatePREVIEWには1つのフラグメントがあり、値はありません。
      パラメータ:
      string - 単一文字列フラグメント
      戻り値:
      文字列から構成されるStringTemplate
      例外:
      NullPointerException - 文字列がnullの場合

    • of

      static StringTemplatePREVIEW of(List<String> fragments, List<?> values)
      指定されたフラグメントおよび値を持つStringTemplateを返します。
      実装要件:
      fragmentsリスト・サイズは、valuesリスト・サイズより1つ大きくする必要があります。
      実装上のノート:
      両方のリストの内容がコピーされ、不変リストが作成されます。
      パラメータ:
      fragments - 文字列フラグメントのリスト
      values - 式の値のリスト
      戻り値:
      文字列から構成されるStringTemplate
      例外:
      IllegalArgumentException - フラグメント・リスト・サイズが値リスト・サイズより大きくない場合
      NullPointerException - フラグメントがnullの場合、または値がnullの場合、またはフラグメントがnullの場合。

    • interpolate

      static String interpolate(List<String> fragments, List<?> values)
      フラグメントの要素間で値の要素をインターリーブする文字列を作成します。 補間に対応するために、値はString.valueOf(Object)を呼び出すかのように文字列に変換されます。
      パラメータ:
      fragments - 文字列フラグメントのリスト
      values - 式の値のリスト
      戻り値:
      フラグメントと値の文字列補間
      例外:
      IllegalArgumentException - フラグメント・リスト・サイズが値リスト・サイズより大きくない場合
      NullPointerException - フラグメントまたは値がnullであるか、フラグメントのいずれかがnullの場合

    • combine

      static StringTemplatePREVIEW combine(StringTemplatePREVIEW... stringTemplates)
      0個以上のStringTemplatesPREVIEWを1つのStringTemplatePREVIEWに結合します。 
      StringTemplate st = StringTemplate.combine(RAW."\{a}", RAW."\{b}", RAW."\{c}");
assert st.interpolate().equals(STR."\{a}\{b}\{c}");
      StringTemplatesPREVIEWのフラグメント・リストは、各StringTemplatePREVIEWの最後のフラグメントと最後に結合され、次の最初のフラグメントと連結されます。 示すために、2つの文字列をとり、次のように結合しました: 
      String s1 = "abc";
String s2 = "xyz";
String sc = s1 + s2;
assert Objects.equals(sc, "abcxyz");
      最初の文字列の最後の文字"c"は、2番目の文字列の最初の文字"x"と結合されます。 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"));
      値リストは単純に連結され、単一の値リストが生成されます。 この結果は、n+1フラグメントおよびn値を持つ整形式のStringTemplatePREVIEWになります。ここで、nは、指定されたすべてのStringTemplatesPREVIEWの値の合計数です。
      実装上のノート:
      StringTemplatePREVIEW引数がゼロの場合、StringTemplate.of("")を呼び出す場合と同様に、空のフラグメントを含むStringTemplatePREVIEWが返されず、値は返されません。 StringTemplatePREVIEW引数を1つのみ指定した場合、その引数は変更されずに返されます。
      パラメータ:
      stringTemplates - ゼロ以上のStringTemplatePREVIEW
      戻り値:
      結合StringTemplatePREVIEW
      例外:
      NullPointerException - stringTemplatesがnullの場合、またはstringTemplatesのいずれかがnullの場合

    • combine

      static StringTemplatePREVIEW combine(List<StringTemplatePREVIEW> stringTemplates)
      StringTemplatesPREVIEWのリストを1つのStringTemplatePREVIEWに結合します。 
      StringTemplate st = StringTemplate.combine(List.of(RAW."\{a}", RAW."\{b}", RAW."\{c}"));
assert st.interpolate().equals(STR."\{a}\{b}\{c}");
      StringTemplatesPREVIEWのフラグメント・リストは、各StringTemplatePREVIEWの最後のフラグメントと最後に結合され、次の最初のフラグメントと連結されます。 示すために、2つの文字列をとり、次のように結合しました: 
      String s1 = "abc";
String s2 = "xyz";
String sc = s1 + s2;
assert Objects.equals(sc, "abcxyz");
      最初の文字列の最後の文字"c"は、2番目の文字列の最初の文字"x"と結合されます。 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"));
      値リストは単純に連結され、単一の値リストが生成されます。 この結果は、n+1フラグメントおよびn値を持つ整形式のStringTemplatePREVIEWになります。ここで、nは、指定されたすべてのStringTemplatesPREVIEWの値の合計数です。
      実装上のノート:
      stringTemplates.size() == 0の場合、StringTemplate.of("")を呼び出すかのように、空のフラグメントを持ち、値が戻されないStringTemplatePREVIEWが返されます。 stringTemplates.size() == 1の場合、リストの最初の要素は変更されずに返されます。
      パラメータ:
      stringTemplates - StringTemplatePREVIEWのリスト
      戻り値:
      結合StringTemplatePREVIEW
      例外:
      NullPointerException - stringTemplatesがnullの場合、またはその要素のいずれかがnullの場合