javax.el

## Class ExpressionFactory

- java.lang.Object
- - javax.el.ExpressionFactory

-     public abstract class ExpressionFactory
      extends Object

  Provides an implementation for creating and evaluating EL expressions.

  Classes that implement the EL expression language expose their functionality via this abstract class. An implementation supports the following functionalities.

  - Parses a `String` into a `ValueExpression` or `MethodExpression` instance for later evaluation.
  - Implements an `ELResolver` for query operators
  - Provides a default type coercion

  The `newInstance()` method can be used to obtain an instance of the implementation. Technologies such as JavaServer Pages and JavaServer Faces provide access to an implementation via factory methods.

  The `createValueExpression(javax.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(javax.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. EL 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:

  - Single expressions using the `${}` delimiter (e.g. `"${employee.lastName}"`).
  - Single expressions using the `#{}` delimiter (e.g. `"#{employee.lastName}"`).
  - Literal text containing no `${}` or `#{}` delimiters (e.g. `"John Doe"`).
  - Multiple expressions using the same delimiter (e.g. `"${employee.firstName}${employee.lastName}"` or `"#{employee.firstName}#{employee.lastName}"`).
  - Mixed literal text and expressions using the same delimiter (e.g. `"Name: ${employee.firstName} ${employee.lastName}"`).

  The following types of input are illegal and must cause an `ELException` to be thrown:

  - Multiple expressions using different delimiters (e.g. `"${employee.firstName}#{employee.lastName}"`).
  - Mixed literal text and expressions using different delimiters(e.g. `"Name: ${employee.firstName} #{employee.lastName}"`).
  Since:
    JSP 2.1

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ExpressionFactory()`

  - ### Method Summary

    Methods
    Modifier and Type | Method and Description
    --- | ---
    `abstract Object` | `coerceToType(Object obj, Class<?> targetType)` Coerces an object to a specific type according to the EL type conversion rules.
    `abstract MethodExpression` | `createMethodExpression(ELContext context, String expression, Class<?> expectedReturnType, Class<?>[] expectedParamTypes)` Parses an expression into a `MethodExpression` for later evaluation.
    `abstract ValueExpression` | `createValueExpression(ELContext context, String expression, Class<?> expectedType)` Parses an expression into a `ValueExpression` for later evaluation.
    `abstract ValueExpression` | `createValueExpression(Object instance, Class<?> expectedType)` Creates a ValueExpression that wraps an object instance.
    `Map<String,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(Properties properties)` Create a new instance of a `ExpressionFactory`, with optional properties.

    - ### Methods inherited from class java.lang.Object

      `clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait`

- - ### Constructor Detail

    - #### ExpressionFactory

          public ExpressionFactory()

  - ### Method Detail

    - #### newInstance

          public static ExpressionFactory newInstance()

      Creates a new instance of a `ExpressionFactory`. This method uses the following ordered lookup procedure to determine the `ExpressionFactory` implementation class to load:
      - Use the Services API (as detailed in the JAR specification). If a resource with the name of `META-INF/services/javax.el.ExpressionFactory` exists, then its first line, if present, is used as the UTF-8 encoded name of the implementation class.
      - Use the properties file "lib/el.properties" in the JRE directory. If this file exists and it is readable by the `java.util.Properties.load(InputStream)` method, and it contains an entry whose key is "javax.el.ExpressionFactory", then the value of that entry is used as the name of the implementation class.
      - Use the `javax.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.
      - Use a platform default implementation.

    - #### newInstance

          public static ExpressionFactory newInstance(Properties properties)

      Create a new instance of a `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 "javax.el."

      The following are some suggested names for properties.

      - javax.el.cacheSize
      Parameters:
        `properties` - Properties passed to the implementation. If null, then no properties.

    - #### createValueExpression

          public abstract ValueExpression createValueExpression(ELContext context,
                                              String expression,
                                              Class<?> expectedType)

      Parses an expression into a `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`.

      Parameters:
        `context` - The EL 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 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 parse
        `expectedType` - The type the result of the expression will be coerced to after evaluation.
      Returns:
        The parsed expression
      Throws:
        `NullPointerException` - Thrown if expectedType is null.
        `ELException` - Thrown if there are syntactical errors in the provided expression.

    - #### createValueExpression

          public abstract ValueExpression createValueExpression(Object instance,
                                              Class<?> expectedType)

      Creates a ValueExpression that wraps an object instance. 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.
      Parameters:
        `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,
      Throws:
        `NullPointerException` - Thrown if expectedType is null.

    - #### createMethodExpression

          public abstract MethodExpression createMethodExpression(ELContext context,
                                                String expression,
                                                Class<?> expectedReturnType,
                                                Class<?>[] expectedParamTypes)

      Parses an expression into a `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`.

      Parameters:
        `context` - The EL 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 parse
        `expectedReturnType` - 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 arugments in the EL expression, in which case these arguments are used for method selection, and this parameter is ignored.
      Returns:
        The parsed expression
      Throws:
        `ELException` - Thrown if there are syntactical errors in the provided expression.
        `NullPointerException` - if paramTypes is `null`.

    - #### coerceToType

          public abstract Object coerceToType(Object obj,
                            Class<?> targetType)

      Coerces an object to a specific type according to the EL type conversion rules. The custom type conversions in the `ELResolver`s are not considered.

      An `ELException` is thrown if an error results from applying the conversion rules.

      Parameters:
        `obj` - The object to coerce.
        `targetType` - The target type for the coercion.
      Throws:
        `ELException` - thrown if an error results from applying the conversion rules.

    - #### getStreamELResolver

          public ELResolver getStreamELResolver()

      Retrieves an ELResolver that implements the operations in collections.

      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 EL.2 for detailed descriptions of these operators, their arguments, and return values.

      Returns:
        The `ELResolver` that implements the Query Operators.
      Since:
        EL 3.0

    - #### getInitFunctionMap

          public Map<String,Method> getInitFunctionMap()

      Retrieve a function map containing a pre-configured function mapping.
      Returns:
        A initial map for functions, null if there is none.
      Since:
        EL 3.0

Copyright © 1996-2013, Oracle and/or its affiliates. All Rights Reserved. Use is subject to license terms.