# Package javax.el

Provides the API for the Unified Expression Language 3.0

See: Description

Interface Summary
Interface | Description
--- | ---
ELContextListener | The listener interface for receiving notification when an `ELContext` is created.

Class Summary
Class | Description
--- | ---
ArrayELResolver | Defines property resolution behavior on arrays.
BeanELResolver | Defines property resolution behavior on objects using the JavaBeans component architecture.
BeanNameELResolver | An `ELResolver` for resolving user or container managed beans.
BeanNameResolver | Resolves a bean by its known name.
CompositeELResolver | Maintains an ordered composite list of child `ELResolver`s.
ELClass | A runtime representation of a Class in the EL expressions.
ELContext | Context information for expression parsing and evaluation.
ELContextEvent | An event which indicates that an `ELContext` has been created.
ELManager | Manages EL parsing and evaluation environment.
ELProcessor | Provides an API for using EL in a stand-alone environment.
ELResolver | Enables customization of variable, property, method call, and type conversion resolution behavior for EL expression evaluation.
EvaluationListener | The listener interface for receiving notification when an EL expression is evaluated.
Expression | Base class for the expression subclasses `ValueExpression` and `MethodExpression`, implementing characteristics common to both.
ExpressionFactory | Provides an implementation for creating and evaluating EL expressions.
FunctionMapper | The interface to a map between EL function names and methods.
ImportHandler | Handles imports of class names and package names.
LambdaExpression | Encapsulates a parameterized `ValueExpression`.
ListELResolver | Defines property resolution behavior on instances of `List`.
MapELResolver | Defines property resolution behavior on instances of `Map`.
MethodExpression | An `Expression` that refers to a method on an object.
MethodInfo | Holds information about a method that a `MethodExpression` evaluated to.
ResourceBundleELResolver | Defines property resolution behavior on instances of `ResourceBundle`.
StandardELContext | A standard ELContext suitable for use in a stand alone environment.
StaticFieldELResolver | An `ELResolver` for resolving static fields, enum constants and static methods.
TypeConverter | A convenient class for writing an ELResolver to do custom type conversions.
ValueExpression | An `Expression` that can get or set a value.
ValueReference | This encapsulates a base model object and one of its properties.
VariableMapper | The interface to a map between EL variables and the EL expressions they are associated with.

Exception Summary
Exception | Description
--- | ---
ELException | Represents any of the exception conditions that can arise during expression evaluation.
MethodNotFoundException | Thrown when a method could not be found while evaluating a `MethodExpression`.
PropertyNotFoundException | Thrown when a property could not be found while evaluating a `ValueExpression` or `MethodExpression`.
PropertyNotWritableException | Thrown when a property could not be written to while setting the value on a `ValueExpression`.

## Package javax.el Description

Provides the API for the Unified Expression Language 3.0

The Expression Language (EL) is a simple language originally designed to satisfy the specific needs of web application developers. It has evloved into its own specification intended for general use inside and outside of the web containers.

This package contains the classes and interfaces that describe and define the programmatic access to the Expression Language engine. The API is logically partitioned as follows:

- EL Context
- Expression Objects
- Creation of Expressions
- Evaluation of Expressions
- Evaluation Listeners
- Resolution of Model Objects and their Properties
- EL Functions
- EL Variables
- EL in Stand-alone environment

### EL Context

An important goal of the EL is to ensure it can be used in a variety of environments. It must therefore provide enough flexibility to adapt to the specific requirements of the environment where it is being used.

Class `ELContext` is what links the EL with the specific environment where it is being used. It provides the mechanism through which all relevant context for creating or evaluating an expression is specified.

When EL used in a web container, the creation of `ELContext` objects is controlled through the underlying technology. For example, in JSP, the `JspContext.getELContext()` factory method is used. In an stand-alone environment, a default `StandardELContext` is provided.

Some technologies provide the ability to add an `ELContextListener` so that applications and frameworks can ensure their own context objects are attached to any newly created `ELContext`.

### Expression Objects

At the core of the Expression Language is the notion of an expression that gets parsed according to the grammar defined by the Expression Language.

There are two types of expressions defined by the EL: value expressions and method expressions. A `ValueExpression` such as `"${customer.name}"` can be used either as an rvalue (return the value associated with property `name` of the model object `customer`) or as an lvalue (set the value of the property `name` of the model object `customer`).

A `MethodExpression` such as `"${handler.process}"` makes it possible to invoke a method (`process`) on a specific model object (`handler`).

In version 2.2 and later, either type of EL expression can represent a method invocation, such as `${trader.buy("JAVA")}`, where the arugments to the method invocation are specified in the expression.

All expression classes extend the base class `Expression`, making them serializable and forcing them to implement `equals()` and `hashCode()`. Morevover, each method on these expression classes that actually evaluates an expression receives a parameter of class `ELContext`, which provides the context required to evaluate the expression.

### Creation of Expressions

An expression is created through the `ExpressionFactory` class. The factory provides two creation methods; one for each type of expression supported by the EL.

To create an expression, one must provide an `ELContext`, a string representing the expression, and the expected type (`ValueExpression`) or signature (`MethodExpression`). The `ELContext` provides the context necessary to parse an expression. Specifically, if the expression uses an EL function (for example `${fn:toUpperCase(customer.name)}`) or an EL variable, then `FunctionMapper` and `VariableMapper` objects must be available within the `ELContext` so that EL functions and EL variables are properly mapped.

### Evaluation of Expressions

The creation and the evaluation of an expression are done in two separate steps. At the evaluation of an expression, the `ELContext` provides the context necessary to support property and method resolution for modal objects.

A deferred expression is one that is created but not immediately evaluated. In a JSF request processing life cycle, EL expressions are typically created in the tree building phase and evaluated in the rendering phrase.

Adding parameters to a `ValueExpression` further enhances the power of deferred expressions. The `LambdaExpression` encapsulates such a construct. A `LambdaExpression` can be invoked by supplying the actual parameters at evaluation. It plays an important role in the support for collections operators.

### Evaluation Listeners

By registering `EvaluationListener`s in ELContext, a user can receive notifications during the EL expression evaluations. There are three events that trigger the notification:

- Before evaluation
- After evaluation
- When (base, property) is resolved

### Resolution of Model Objects and their Properties

Through the `ELResolver` base class, the EL features a pluggable mechanism to resolve model object references as well as properties and method invocations of these objects.

The EL API provides implementations of `ELResolver` supporting property resolution for common data types which include arrays (`ArrayELResolver`), JavaBeans (`BeanELResolver`), `List`s (`ListELResolver`), `Map`s (`MapELResolver`), and `ResourceBundle`s (`ResourceBundleELResolver`).

Tools can easily obtain more information about resolvable model objects and their resolvable properties by calling method `getFeatureDescriptors` on the `ELResolver`. This method exposes objects of type `java.beans.FeatureDescriptor`, providing all information of interest on top-level model objects as well as their properties.

### EL Functions

If an EL expression uses a function (for example `${fn:toUpperCase(customer.name)}`), then a `FunctionMapper` object must also be specified within the `ELContext`. The `FunctionMapper` is responsible to map `${prefix:name()}` style functions to static methods that can execute the specified functions.

### EL Variables

Just like `FunctionMapper` provides a flexible mechanism to add functions to the EL, `VariableMapper` provides a flexible mechanism to support the notion of EL variables.

An EL variable does not directly refer to a model object that can then be resolved by an `ELResolver`. Instead, it refers to an EL expression. The evaluation of that EL expression gives the EL variable its value.

For example, in the following code snippet

> `<h:inputText value="#{handler.customer.name}"/>`

`handler` refers to a model object that can be resolved by an EL Resolver.

However, in this other example:

>     <c:forEach var="item" items="#{model.list}">
>        <h:inputText value="#{item.name}"/>
>     </c:forEach>

`item` is an EL variable because it does not refer directly to a model object. Instead, it refers to another EL expression, namely a specific item in the collection referred to by the EL expression `#{model.list}`.

Assuming that there are three elements in `${model.list}`, this means that for each invocation of `<h:inputText>`, the following information about `item` must be preserved in the `VariableMapper`:

> first invocation: `item` maps to first element in `${model.list}`
> second invocation: `item` maps to second element in `${model.list}`
> third invocation: `item` maps to third element in `${model.list}`

`VariableMapper` provides the mechanisms required to allow the mapping of an EL variable to the EL expression from which it gets its value.

### EL in Stand-alone environment

EL 3.0 includes APIs for using EL in a stand-alone environment.

`ELProcessor` provides simple APIs for the direct evaluations of expressions. It also makes it easy to define functions, set variables, and define a beans locally.

`ELManager` provides a lower level APIs for managing the EL parsing and evaluation environment. It contains a default ELContext `StandardELContext`.

``