public abstract class ExpressionFactory
extends java.lang.Object
Classes that implement the Jakarta Expression Language expression language expose their functionality via this abstract class. An implementation supports the following functionalities.
String into a ValueExpression or MethodExpression instance for later
evaluation.ELResolver for query operators
The newInstance() method can be used to obtain an instance of the implementation. Technologies such as
Jakarta Server Pages and Jakarta Faces provide access to an implementation via factory methods.
The createValueExpression(jakarta.el.ELContext, java.lang.String, java.lang.Class<?>) method is used to parse expressions that evaluate to values (both l-values and
r-values are supported). The createMethodExpression(jakarta.el.ELContext, java.lang.String, java.lang.Class<?>, java.lang.Class<?>[]) method is used to parse expressions that evaluate to a
reference to a method on an object.
Resolution of model objects is performed at evaluation time, via the ELResolver associated with the
ELContext passed to the ValueExpression or MethodExpression.
The ELContext object also provides access to the FunctionMapper and VariableMapper to be used when
parsing the expression. Jakarta Expression Language function and variable mapping is performed at parse-time, and the
results are bound to the expression. Therefore, the ELContext, FunctionMapper, and
VariableMapper are not stored for future use and do not have to be Serializable.
The createValueExpression and createMethodExpression methods must be thread-safe. That is,
multiple threads may call these methods on the same ExpressionFactory object simultaneously.
Implementations should synchronize access if they depend on transient state. Implementations should not, however,
assume that only one object of each ExpressionFactory type will be instantiated; global caching should
therefore be static.
The ExpressionFactory must be able to handle the following types of input for the
expression parameter:
${} delimiter (e.g. "${employee.lastName}").#{} delimiter (e.g. "#{employee.lastName}").${} or #{} delimiters (e.g. "John Doe")."${employee.firstName}${employee.lastName}" or
"#{employee.firstName}#{employee.lastName}")."Name: ${employee.firstName} ${employee.lastName}").
The following types of input are illegal and must cause an ELException to be thrown:
"${employee.firstName}#{employee.lastName}")."Name: ${employee.firstName} #{employee.lastName}").| Constructor and Description |
|---|
ExpressionFactory() |
| Modifier and Type | Method and Description |
|---|---|
abstract <T> T |
coerceToType(java.lang.Object obj,
java.lang.Class<T> targetType)
Coerces an object to a specific type according to the Jakarta Expression Language type conversion rules.
|
abstract MethodExpression |
createMethodExpression(ELContext context,
java.lang.String expression,
java.lang.Class<?> expectedReturnType,
java.lang.Class<?>[] expectedParamTypes)
Parses an expression into a
MethodExpression for later evaluation. |
abstract ValueExpression |
createValueExpression(ELContext context,
java.lang.String expression,
java.lang.Class<?> expectedType)
Parses an expression into a
ValueExpression for later evaluation. |
abstract ValueExpression |
createValueExpression(java.lang.Object instance,
java.lang.Class<?> expectedType)
Creates a ValueExpression that wraps an object instance.
|
java.util.Map<java.lang.String,java.lang.reflect.Method> |
getInitFunctionMap()
Retrieve a function map containing a pre-configured function mapping.
|
ELResolver |
getStreamELResolver()
Retrieves an ELResolver that implements the operations in collections.
|
static ExpressionFactory |
newInstance()
Creates a new instance of a
ExpressionFactory. |
static ExpressionFactory |
newInstance(java.util.Properties properties)
Create a new instance of a
ExpressionFactory, with optional properties. |
public static ExpressionFactory newInstance()
ExpressionFactory. This method uses the following ordered lookup procedure
to determine the ExpressionFactory implementation class to load:
java.util.Properties.load(InputStream) method, and it contains an entry whose key is
"jakarta.el.ExpressionFactory", then the value of that entry is used as the name of the implementation class.jakarta.el.ExpressionFactory system property. If a system property with this name is defined,
then its value is used as the name of the implementation class.ExpressionFactory instancepublic static ExpressionFactory newInstance(java.util.Properties properties)
ExpressionFactory, with optional properties.
This method uses the same lookup procedure as the one used in newInstance().
If the argument properties is not null, and if the implementation contains a constructor with a single
parameter of type java.util.Properties, then the constructor is used to create the instance.
Properties are optional and can be ignored by an implementation.
The name of a property should start with "jakarta.el."
The following are some suggested names for properties.
properties - Properties passed to the implementation. If null, then no properties.ExpressionFactory instancepublic abstract ValueExpression createValueExpression(ELContext context, java.lang.String expression, java.lang.Class<?> expectedType)
ValueExpression for later evaluation. Use this method for expressions that refer
to values.
This method should perform syntactic validation of the expression. If in doing so it detects errors, it should raise
an ELException.
context - The Jakarta Expression Language context used to parse the expression. The FunctionMapper
and VariableMapper stored in the ELContext are used to resolve functions and variables found in the
expression. They can be null, in which case functions or variables are not supported for this
expression. The object returned must invoke the same functions and access the same variable mappings regardless of
whether the mappings in the provided FunctionMapper and VariableMapper instances change
between calling ExpressionFactory.createValueExpression() and any method on
ValueExpression. Note that within Jakarta Expression Language, the ${} and #{} syntaxes are treated
identically. This includes the use of VariableMapper and FunctionMapper at expression creation time. Each is invoked
if not null, independent of whether the #{} or ${} syntax is used for the expression.expression - The expression to parseexpectedType - The type the result of the expression will be coerced to after evaluation.java.lang.NullPointerException - Thrown if expectedType is null.ELException - Thrown if there are syntactical errors in the provided expression.public abstract ValueExpression createValueExpression(java.lang.Object instance, java.lang.Class<?> expectedType)
This method can be used to pass any object as a ValueExpression. The wrapper ValueExpression is read only, and
returns the wrapped object via its getValue() method, optionally coerced.
instance - The object instance to be wrapped.expectedType - The type the result of the expression will be coerced to after evaluation. There will be no
coercion if it is Object.class,java.lang.NullPointerException - Thrown if expectedType is null.public abstract MethodExpression createMethodExpression(ELContext context, java.lang.String expression, java.lang.Class<?> expectedReturnType, java.lang.Class<?>[] expectedParamTypes)
MethodExpression for later evaluation. Use this method for expressions that refer
to methods.
If the expression is a String literal, a MethodExpression
is created, which when invoked, returns the String literal, coerced to expectedReturnType. An ELException is
thrown if expectedReturnType is void or if the coercion of the String literal to the expectedReturnType yields an
error (see Section "1.16 Type Conversion").
This method should perform syntactic validation of the expression. If in doing so it detects errors, it should raise
an ELException.
context - The Jakarta Expression Language context used to parse the expression. The FunctionMapper
and VariableMapper stored in the ELContext are used to resolve functions and variables found in the
expression. They can be null, in which case functions or variables are not supported for this
expression. The object returned must invoke the same functions and access the same variable mappings regardless of
whether the mappings in the provided FunctionMapper and VariableMapper instances change
between calling ExpressionFactory.createMethodExpression() and any method on
MethodExpression. Note that within the EL, the ${} and #{} syntaxes are treated identically. This
includes the use of VariableMapper and FunctionMapper at expression creation time. Each is invoked if not null,
independent of whether the #{} or ${} syntax is used for the expression.expression - The expression to parseexpectedReturnType - The expected return type for the method to be found. After evaluating the expression, the
MethodExpression must check that the return type of the actual method matches this type. Passing in a
value of null indicates the caller does not care what the return type is, and the check is disabled.expectedParamTypes - The expected parameter types for the method to be found. Must be an array with no elements
if there are no parameters expected. It is illegal to pass null, unless the method is specified with
arguments in the Jakarta Expression Language expression, in which case these arguments are used for method selection,
and this parameter is ignored.ELException - Thrown if there are syntactical errors in the provided expression.java.lang.NullPointerException - if paramTypes is null.public abstract <T> T coerceToType(java.lang.Object obj,
java.lang.Class<T> targetType)
ELResolvers are not considered.
An ELException is thrown if an error results from applying the conversion rules.
obj - The object to coerce.targetType - The target type for the coercion.targetTypeELException - thrown if an error results from applying the conversion rules.public ELResolver getStreamELResolver()
This ELResolver resolves the method invocation on the pair (base, property) when
base is a Collection or a Map, and property is the name of the
operation.
See the specification document for detailed descriptions of these operators, their arguments, and return values.
ELResolver that implements the Query Operators.public java.util.Map<java.lang.String,java.lang.reflect.Method> getInitFunctionMap()