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

クラスStringConcatFactory

java.lang.Object
java.lang.invoke.StringConcatFactory
public final class StringConcatFactory extends Object

String連結メソッドの作成を容易にするメソッド。これは、既知の型の既知の数の引数を効率的に連結するために使用でき、型の適応後や引数の部分評価後にも使用できます。 これらのメソッドは、通常、Javaプログラミング言語の「文字列連結」機能をサポートするために、 invokedynamicコール・サイトの「ブートストラップ法」として使用されます。

提供された MethodHandleで指定された動作への間接アクセスは、2つのフェーズを経て順番に進みます:

  1. リンケージ。このクラスのメソッドが呼び出されたときに発生します。 これらは、引数として、連結された引数の数と型を記述するメソッド型、およびオプションで文字列recipeと、文字列連結に参加する定数を取ります。 受け入れられるレシピ・シェイプの詳細は、後述します。 リンケージには、想定される連結動作を実装する新しいクラスが動的にロードされる場合があります。 CallSiteは、正確な連結メソッドを指すMethodHandleを保持します。 連結メソッドは、異なるCallSite間で共有できます。たとえば、リンケージ・メソッドによって純粋な関数として生成される場合です。
  2. 「呼び出し」は、生成された連結メソッドが正確な動的引数とともに呼び出されたときに発生します。 これは、単一の連結メソッドで何度も発生する可能性があります。 動作 MethodHandleによって参照されるメソッドは、MethodHandle.invoke(Object...)のように、起動時に提供される静的引数および追加の動的引数を使用して呼び出されます。

このクラスは、2つの形式のリンケージ・メソッド: 動的引数のみを使用する単純バージョン(makeConcat(java.lang.invoke.MethodHandles.Lookup, String, MethodType))および拡張バージョン(定数引数の取得の高度な形式を使用するmakeConcatWithConstants(java.lang.invoke.MethodHandles.Lookup, String, MethodType, String, Object...))。 高度な戦略では、実行時に存在する文字列連結メソッドのシェイプの数を分解する代わりに、呼び出しバイトコードが大幅に改善される可能性があります。これらのシェイプには一定の静的引数も含まれるためです。

APIのノート:

JVMの制限があります(クラス・ファイル構造制約): 255個を超えるスロットではメソッドをコールできません。 これにより、ブートストラップ・メソッドに渡すことができる静的引数および動的引数の数が制限されます。 MethodHandleコンビネータを使用する可能性のある連結方法があるため、時間的な結果を取得するには、パラメータ・リストにいくつかの空のスロットを予約する必要があります。 このため、このファクトリのブートストラップ・メソッドは200を超える引数スロットを受け入れません。 200個を超える引数スロットを連結で必要とするユーザーは、大きい連結を小さい式で分割することが期待されます。

導入されたバージョン:
9

  • フィールド詳細

    • MAX_INDY_CONCAT_ARG_SLOTS

      public static final int MAX_INDY_CONCAT_ARG_SLOTS
      MAX_INDY_CONCAT_ARG_SLOTSは、JavaプラットフォームのプレビューAPIです。
      プレビュー機能が有効な場合のみ、プログラムでMAX_INDY_CONCAT_ARG_SLOTSを使用できます。
      プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
      String Concatコールの引数スロットの最大数。 インディ・コールで処理できる引数スロットの最大数は253ですが、これらのスロットをすべて使用しないため、MethodHandleコンビネータを使用する戦略で引数を使用できます。
      導入されたバージョン:
      21

  • メソッドの詳細

    • makeConcat

      public static CallSite makeConcat(MethodHandles.Lookup lookup, String name, MethodType concatType) throws StringConcatException
      最適化された文字列連結メソッドの作成を容易にします。このメソッドを使用すると、既知の型の引数(型の適応後や引数の部分評価後など)を効率的に連結できます。 通常は、Javaプログラミング言語の「文字列連結」機能をサポートするために、 invokedynamicコール・サイトの「ブートストラップ法」として使用されます。

      このメソッドから返されたCallSiteのターゲットが呼び出されると、文字列連結の結果が返され、連結用の入力としてリンケージ・メソッドに渡されたすべての関数引数が取得されます。 ターゲット・シグネチャはconcatTypeで与えられます。 受け入れ対象:

      • ゼロの入力では、連結結果は空の文字列になります。
      • 1つの入力を連結すると、JLS 5.1.11 "文字列変換"に従って単一の入力が変換されます。それ以外の場合は、
      • 2つ以上の入力の場合、JLS 15.18.1 "文字列連結演算子+"に記載されている要件に従って入力が連結されます。 入力は、JLS 5.1.11 "文字列変換"に従って変換され、左から右に組み合されます。

      リンケージ引数は次のことを前提とします。

      • concatType、CallSiteのシグネチャを記述

      さらに、次のリンケージ不変条件を保持する必要があります。

      • concatTypeのパラメータ・スロットの数が200以下です
      • concatTypeの戻り値の型はStringから代入可能です。

      パラメータ:
      lookup - コール元のアクセシビリティ権限を持つルックアップ・コンテキストを表します。 特に、参照コンテキストには「完全な権限アクセス」が必要です。 invokedynamicで使用されるときは、これはVMによって自動的にスタックされます。
      name - 実装するメソッドの名前。 この名前は任意であり、このリンク・メソッドには意味がありません。 invokedynamicで使用されるときは、これはInvokeDynamic構造のNameAndTypeによって提供され、VMによって自動的にスタックされます。
      concatType - CallSiteの予想されるシグネチャ。 パラメータ型は、連結引数の型を表します。戻り値の型は常にStringから割り当て可能です。 invokedynamicで使用されるときは、これは InvokeDynamic構造のNameAndTypeによって提供され、VMによって自動的にスタックされます。
      戻り値:
      指定されたconcatTypeで記述された動的な連結引数を使用して、文字列連結の実行にターゲットを使用できるCallSite。
      例外:
      StringConcatException - ここで説明されているリンケージ不変条件のいずれかに違反があるか、ルックアップ・コンテキストにプライベート・アクセス権限がない場合。
      NullPointerException - 受信引数のいずれかがnullの場合。 これは、bootstrapメソッドがinvokedynamicを使用してコールされた場合には発生しません。
      Java言語仕様を参照してください:
      5.1.11 文字列変換
      15.18.1文字列連結演算子+

    • makeConcatWithConstants

      public static CallSite makeConcatWithConstants(MethodHandles.Lookup lookup, String name, MethodType concatType, String recipe, Object... constants) throws StringConcatException
      最適化された文字列連結メソッドの作成を容易にします。このメソッドを使用すると、既知の型の引数(型の適応後や引数の部分評価後など)を効率的に連結できます。 通常は、Javaプログラミング言語の「文字列連結」機能をサポートするために、 invokedynamicコール・サイトの「ブートストラップ法」として使用されます。

      このメソッドから返されたCallSiteのターゲットが呼び出されると、文字列連結の結果が返され、連結用の入力としてリンケージ・メソッドに渡されるすべての関数引数および定数が使用されます。 ターゲット・シグネチャは、concatTypeで指定され、定数は含まれません。 受け入れ対象:

      • ゼロの入力では、連結結果は空の文字列になります。
      • 1つの入力を連結すると、JLS 5.1.11 "文字列変換"に従って単一の入力が変換されます。それ以外の場合は、
      • 2つ以上の入力の場合、JLS 15.18.1 "文字列連結演算子+"に記載されている要件に従って入力が連結されます。 入力は、JLS 5.1.11 "文字列変換"に従って変換され、左から右に組み合されます。

      連結recipeは、引数および定数から連結文字列を構築する方法の文字列の説明です。 レシピは左から右に処理され、各文字は連結への入力を表します。 レシピ文字の意味:

      • \1 (Unicodeポイント0001): 普通の議論。 この入力は動的引数を介して渡され、連結メソッドの起動時に提供されます。 この入力はnullにできます。
      • \2 (Unicodeポイント0002): 定数。 この入力は静的ブートストラップ引数を介して渡されます。 この定数は、定数プールで表現できる任意の値です。 必要に応じて、ファクトリはtoStringをコールして、1回かぎりの文字列変換を実行します。
      • その他のchar値: 単一の文字定数。

      リンケージ引数は次のことを前提とします。

      • concatType、CallSiteのシグネチャを記述
      • recipe、文字列のレシピを記述
      • constants、定数の可変配列

      さらに、次のリンケージ不変条件を保持する必要があります。

      • concatTypeのパラメータ・スロットの数が200以下です
      • concatTypeのパラメータ数は、recipeの\1タグ数と同じです
      • concatTypeの戻り値の型はStringから代入可能で、返されるMethodHandleの戻り値の型と一致
      • constantsの要素の数は、recipeの\2タグの数と同じです

      APIのノート:
      コード・ジェネレータには、文字列連結式で定数文字列オペランドSを処理する3つの異なる方法があります。 まず、Sは参照(ldcを使用して)として実体化でき、通常の引数(レシピ'\1')として渡されます。 または、Sを定数プールに格納し、定数(レシピ'\2')として渡すことができます。 最後に、Sにレシピ・タグ文字('\1', '\2')が含まれていない場合、Sはレシピ自体に補間され、その結果にその文字が挿入されます。
      パラメータ:
      lookup - コール元のアクセシビリティ権限を持つルックアップ・コンテキストを表します。 特に、参照コンテキストには「完全な権限アクセス」が必要です。 invokedynamicで使用されるときは、これはVMによって自動的にスタックされます。
      name - 実装するメソッドの名前。 この名前は任意であり、このリンク・メソッドには意味がありません。 invokedynamicで使用されるときは、これはInvokeDynamic構造のNameAndTypeによって提供され、VMによって自動的にスタックされます。
      concatType - CallSiteの予想されるシグネチャ。 パラメータ型は、動的連結引数の型を表します。戻り値の型は常にStringから割り当て可能です。 invokedynamicで使用されるときは、これはInvokeDynamic構造の NameAndTypeによって提供され、VMによって自動的にスタックされます。
      recipe - 前述の連結レシピ。
      constants - リンケージ・メソッドに渡される定数を表すvarargパラメータ。
      戻り値:
      指定されたconcatTypeで記述された動的な連結引数を使用して、文字列連結の実行にターゲットを使用できるCallSite。
      例外:
      StringConcatException - ここで説明されているリンケージ不変条件のいずれかに違反があるか、ルックアップ・コンテキストにプライベート・アクセス権限がない場合。
      NullPointerException - 受信引数のいずれかがnullの場合、またはrecipeの定数がnullの場合。 これは、bootstrapメソッドがinvokedynamicを使用してコールされた場合には発生しません。
      Java言語仕様を参照してください:
      5.1.11 文字列変換
      15.18.1文字列連結演算子+

    • makeConcatWithTemplate

      public static MethodHandle makeConcatWithTemplate(List<String> fragments, List<Class<?>> ptypes) throws StringConcatException
      makeConcatWithTemplateは、JavaプラットフォームのプレビューAPIです。
      プレビュー機能が有効な場合のみ、プログラムでmakeConcatWithTemplateを使用できます。
      プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
      StringTemplatePREVIEW連結を容易にするための簡略化された連結メソッド。 このメソッドは、フラグメントと値をインターリーブする単一の連結メソッドを返します。fragment|value|fragment|value|...|value|fragment。 フラグメントの数は、ptypesの数以上である必要があります。 ptypesで使用されるスロットの合計数は、MAX_INDY_CONCAT_ARG_SLOTSPREVIEW以下である必要があります。
      パラメータ:
      fragments - 文字列フラグメントのリスト
      ptypes - 式タイプのリスト
      戻り値:
      連結用のMethodHandle
      例外:
      StringConcatException - いずれかのリンク不変が違反している場合。
      NullPointerException - 受信引数のいずれかがnullの場合。
      IllegalArgumentException - 値スロットの数がMAX_INDY_CONCAT_ARG_SLOTSPREVIEWを超える場合。
      導入されたバージョン:
      21

    • makeConcatWithTemplateCluster

      public static List<MethodHandle> makeConcatWithTemplateCluster(List<String> fragments, List<Class<?>> ptypes, int maxSlots) throws StringConcatException
      makeConcatWithTemplateClusterは、JavaプラットフォームのプレビューAPIです。
      プレビュー機能が有効な場合のみ、プログラムでmakeConcatWithTemplateClusterを使用できます。
      プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
      このメソッドは、MethodHandleごとに必要なスロット数に基づいて、大きな連結を個別のMethodHandlesに分割します。 最初のMethodHandle以降の各Stringスロットには、前のMethodHandleの結果用に追加のStringスロットがあります。makeConcatWithTemplate(java.util.List<java.lang.String>, java.util.List<java.lang.Class<?>>)PREVIEWは、MethodHandlesの構成に使用されます。 ptypesで使用されているスロットの合計数はopen endです。 ただし、結合の合計が255スロット制限を超えないように、MethodHandlesを組み合わせる場合は注意が必要です。
      パラメータ:
      fragments - 文字列フラグメントのリスト
      ptypes - 式タイプのリスト
      maxSlots - MethodHandleごとのスロットの最大数。
      戻り値:
      MethodHandlesのリスト
      例外:
      IllegalArgumentException - maxSlotsが1からMAX_INDY_CONCAT_ARG_SLOTSの間でない場合。
      StringConcatException - いずれかのリンク不変が違反している場合。
      NullPointerException - 受信引数のいずれかがnullの場合。
      IllegalArgumentException - 値スロットの数がMAX_INDY_CONCAT_ARG_SLOTSPREVIEWを超える場合。
      導入されたバージョン:
      21

    • makeConcatWithTemplateGetters

      public static MethodHandle makeConcatWithTemplateGetters(List<String> fragments, List<MethodHandle> getters, int maxSlots) throws StringConcatException
      makeConcatWithTemplateGettersは、JavaプラットフォームのプレビューAPIです。
      プレビュー機能が有効な場合のみ、プログラムでmakeConcatWithTemplateGettersを使用できます。
      プレビュー機能は、今後のリリースで削除するか、Javaプラットフォームの永続機能にアップグレードすることができます。
      このメソッドは、指定されたgetterの受信側である1つの入力を予期するMethodHandleを作成します。 このメソッドは、makeConcatWithTemplateCluster(java.util.List<java.lang.String>, java.util.List<java.lang.Class<?>>, int)PREVIEWを使用して中間MethodHandlesを作成します。
      パラメータ:
      fragments - 文字列フラグメントのリスト
      getters - getterのリストMethodHandles
      maxSlots - クラスタ内のMethodHandleあたりの最大スロット数。
      戻り値:
      連結用のMethodHandle
      例外:
      IllegalArgumentException - maxSlotsが1からMAX_INDY_CONCAT_ARG_SLOTSの間にない場合、またはgetterが同じ引数タイプを使用しない場合
      StringConcatException - いずれかのリンケージ不変条件に違反している場合
      NullPointerException - 着信引数のいずれかがnullの場合
      IllegalArgumentException - 値スロットの数がMAX_INDY_CONCAT_ARG_SLOTSPREVIEWを超える場合。
      導入されたバージョン:
      21