パッケージ jakarta.el

クラス ExpressionFactory

java.lang.ObjectSE
jakarta.el.ExpressionFactory
public abstract class ExpressionFactory extends ObjectSE
Jakarta Expression Language 式を作成および評価するための実装を提供します。

Jakarta Expression Language 式言語を実装するクラスは、この抽象クラスを介して機能を公開します。実装は次の機能をサポートします。

  • 後で評価するために、String を ValueExpression または MethodExpression インスタンスに解析します。
  • クエリ演算子の ELResolver を実装します
  • デフォルトの型強制を提供します

newInstance() メソッドを使用して、実装のインスタンスを取得できます。Jakarta Server Pages や Jakarta Faces などのテクノロジは、ファクトリメソッドを介して実装へのアクセスを提供します。

createValueExpression(jakarta.el.ELContext, java.lang.String, java.lang.Class<?>) メソッドは、値に評価される式を解析するために使用されます（l 値と r 値の両方がサポートされています）。createMethodExpression(jakarta.el.ELContext, java.lang.String, java.lang.Class<?>, java.lang.Class<?>[]) メソッドは、オブジェクトのメソッドへの参照に評価される式を解析するために使用されます。

モデルオブジェクトの解決は、評価時に、ValueExpression または MethodExpression に渡される ELContext に関連付けられた ELResolver を介して実行されます。

ELContext オブジェクトは、式の解析時に使用される FunctionMapper および VariableMapper へのアクセスも提供します。Jakarta Expression Language 関数と変数のマッピングは解析時に実行され、結果は式にバインドされます。ELContext、FunctionMapper、VariableMapper は将来の使用のために保管されず、Serializable である必要はありません。

createValueExpression および createMethodExpression メソッドはスレッドセーフでなければなりません。つまり、複数のスレッドが同じ ExpressionFactory オブジェクトでこれらのメソッドを同時に呼び出す可能性があります。一時的な状態に依存する場合、実装はアクセスを同期する必要があります。ただし、実装では、各 ExpressionFactory 型のオブジェクトが 1 つだけインスタンス化されると想定しないでください。グローバルキャッシングは静的である必要があります。

ExpressionFactory は、expression パラメーターの次の型の入力を処理できる必要があります。

  • ${} 区切り文字を使用する単一の式（例: "${employee.lastName}"）。
  • #{} 区切り文字を使用する単一の式（例: "#{employee.lastName}"）。
  • ${} または #{} 区切り文字を含まないリテラルテキスト（例: "John Doe"）。
  • 同じ区切り文字を使用する複数の式（例: "${employee.firstName}${employee.lastName}" または "#{employee.firstName}#{employee.lastName}"）。
  • 同じ区切り文字を使用したリテラルテキストと式の混在（例: "Name: ${employee.firstName} ${employee.lastName}"）。

次の型の入力は無効であり、ELException がスローされる原因となる必要があります。

  • 異なる区切り文字を使用する複数の式（例: "${employee.firstName}#{employee.lastName}"）。
  • 異なる区切り文字を使用した混合リテラルテキストと式（例: "Name: ${employee.firstName} #{employee.lastName}"）。
導入:
Jakarta Server Pages 2.1

  • コンストラクターの詳細

    • ExpressionFactory

      public ExpressionFactory()

  • 方法の詳細

    • newInstance

      public static ExpressionFactory newInstance()
      ExpressionFactory の新しいインスタンスを作成します。このメソッドは、次の順序付きルックアップ手順を使用して、ロードする ExpressionFactory 実装クラスを決定します。
      • Services API を使用します (JAR 仕様で詳しく説明されています)。
      • JRE ディレクトリのプロパティファイル "lib/el.properties" を使用します。このファイルが存在し、 java.util.Properties.load(InputStream) メソッドで読み取り可能であり、キーが "jakarta.el.ExpressionFactory" であるエントリが含まれている場合、そのエントリの値が実装クラスの名前として使用されます。
      • jakarta.el.ExpressionFactory システムプロパティを使用します。この名前のシステムプロパティが定義されている場合、その値は実装クラスの名前として使用されます。
      • プラットフォームのデフォルト実装を使用します。
      戻り値:
      新しい ExpressionFactory インスタンス

    • newInstance

      public static ExpressionFactory newInstance(PropertiesSE properties)
      オプションのプロパティを使用して、ExpressionFactory の新しいインスタンスを作成します。

      このメソッドは、newInstance() で使用されるものと同じルックアップ手順を使用します。

      引数 properties が null でなく、実装に java.util.Properties 型の単一パラメーターを持つコンストラクターが含まれている場合、コンストラクターを使用してインスタンスが作成されます。

      プロパティはオプションであり、実装では無視できます。

      プロパティの名前は "jakarta.el." で始まる必要があります

      以下は、プロパティの推奨される名前です。

      • jakarta.el.cacheSize
      パラメーター:
      properties - 実装に渡されるプロパティ。null の場合、プロパティはありません。
      戻り値:
      新しい ExpressionFactory インスタンス

    • createValueExpression

      public abstract ValueExpression createValueExpression(ELContext context, StringSE expression, ClassSE<?> expectedType)
      後で評価するために、式を ValueExpression に解析します。値を参照する式には、このメソッドを使用します。

      このメソッドは、式の構文検証を実行する必要があります。そうすることでエラーを検出した場合、ELException を発生させる必要があります。

      パラメーター:
      context - 式の解析に使用される Jakarta Expression Language コンテキスト。ELContext に格納されている FunctionMapper と VariableMapper は、式で見つかった関数と変数を解決するために使用されます。それらは null である可能性があり、その場合、関数または変数はこの式ではサポートされません。返されるオブジェクトは、提供された FunctionMapper および VariableMapper インスタンスのマッピングが ExpressionFactory.createValueExpression() の呼び出しと ValueExpression のメソッドの間で変更されるかどうかに関係なく、同じ関数を呼び出し、同じ変数マッピングにアクセスする必要があります。Jakarta Expression Language 内では、${} 構文と #{} 構文は同じように扱われることに注意してください。これには、式の作成時の VariableMapper および FunctionMapper の使用が含まれます。式に #{} 構文と ${} 構文のどちらが使用されているかに関係なく、それぞれが null でない場合に呼び出されます。
      expression - 解析する式
      expectedType - 式の結果の型は、評価後に強制変換されます。
      戻り値:
      解析された式
      例外:
      NullPointerExceptionSE - expectedType が null の場合にスローされます。
      ELException - 提供された式に構文エラーがある場合にスローされます。

    • createValueExpression

      public abstract ValueExpression createValueExpression(ObjectSE instance, ClassSE<?> expectedType)
      オブジェクトインスタンスをラップする ValueExpression を作成します。

      このメソッドは、任意のオブジェクトを ValueExpression として渡すために使用できます。ラッパー ValueExpression は読み取り専用であり、オプションで強制変換された getValue() メソッドを介してラップされたオブジェクトを返します。

      パラメーター:
      instance - ラップされるオブジェクトインスタンス。
      expectedType - 式の結果の型は、評価後に強制変換されます。Object.class の場合、強制はありません。
      戻り値:
      オブジェクトインスタンスをラップする ValueExpression
      例外:
      NullPointerExceptionSE - expectedType が null の場合にスローされます。

    • createMethodExpression

      public abstract MethodExpression createMethodExpression(ELContext context, StringSE expression, ClassSE<?> expectedReturnType, ClassSE<?>[] expectedParamTypes)
      後で評価するために、式を MethodExpression に解析します。メソッドを参照する式には、このメソッドを使用します。

      式が文字列リテラルの場合、MethodExpression  が作成され、呼び出されると、expectedReturnType に強制変換された文字列リテラルが返されます。expectedReturnType が void の場合、または文字列リテラルを expectedReturnType に強制変換するとエラーが発生する場合は、ELException がスローされます (「1.16 型変換」セクションを参照)。

      このメソッドは、式の構文検証を実行する必要があります。そうすることでエラーを検出した場合、ELException を発生させる必要があります。

      パラメーター:
      context - 式の解析に使用される Jakarta Expression Language コンテキスト。ELContext に格納されている FunctionMapper と VariableMapper は、式で見つかった関数と変数を解決するために使用されます。それらは null である可能性があり、その場合、関数または変数はこの式ではサポートされません。返されるオブジェクトは、提供された FunctionMapper および VariableMapper インスタンスのマッピングが ExpressionFactory.createMethodExpression() の呼び出しと MethodExpression のメソッドの間で変更されるかどうかに関係なく、同じ関数を呼び出し、同じ変数マッピングにアクセスする必要があります。EL 内では、${} 構文と #{} 構文は同じように扱われることに注意してください。これには、式の作成時の VariableMapper および FunctionMapper の使用が含まれます。式に #{} 構文と ${} 構文のどちらが使用されているかに関係なく、それぞれが null でない場合に呼び出されます。
      expression - 解析する式
      expectedReturnType - 検出されるメソッドの期待戻り値の型。式を評価した後、MethodExpression は、実際のメソッドの戻り値の型がこの型と一致することを確認する必要があります。null の値を渡すと、呼び出し元は戻り値の型が何であるかを気にせず、チェックが無効になります。
      expectedParamTypes - 検出されるメソッドに予想されるパラメーター型。パラメーターが予期されていない場合は、要素のない配列である必要があります。メソッドが Jakarta Expression Language 式の引数で指定されていない限り、null を渡すことは不正です。この場合、これらの引数はメソッドの選択に使用され、このパラメーターは無視されます。
      戻り値:
      解析された式
      例外:
      ELException - 提供された式に構文エラーがある場合にスローされます。
      NullPointerExceptionSE - paramTypes が null の場合。

    • coerceToType

      public abstract <T> T coerceToType(ObjectSE obj, ClassSE<T> targetType)
      Jakarta Expression Language 型変換規則に従って、オブジェクトを特定の型に強制変換します。ELResolver でのカスタム型変換は考慮されません。

      変換ルールの適用によってエラーが発生した場合、ELException がスローされます。

      パラメーター:
      obj - 強制するオブジェクト。
      targetType - 強制のターゲット型。
      戻り値:
      targetType に強制されたオブジェクト
      例外:
      ELException - 変換ルールの適用によってエラーが発生した場合にスローされます。

    • getStreamELResolver

      public ELResolver getStreamELResolver()
      コレクション内の操作を実装する ELResolver を取得します。

      この ELResolver は、base が Collection または Map であり、property が操作の名前である場合に、ペア（base、property）でのメソッド呼び出しを解決します。

      これらの演算子、それらの引数、戻り値の詳細な説明については、仕様書を参照してください。

      戻り値:
      クエリ演算子を実装する ELResolver。
      導入:
      Jakarta Expression Language 3.0

    • getInitFunctionMap

      public MapSE<StringSE,MethodSE> getInitFunctionMap()
      事前構成された関数マッピングを含む関数マップを取得します。
      戻り値:
      関数の初期マップ。存在しない場合は null。
      導入:
      Jakarta Expression Language 3.0