EE4J 10.0.0 · jakarta.el

Provides the API for Jakarta Expression Language 5.0

Jakarta Expression Language is a simple language originally designed to satisfy the specific needs of web application developers. It has evolved 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 Jakarta Expression Language engine. The API is logically partitioned as follows:

Jakarta Expression Language Context

An important goal of Jakarta Expression Language 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 jakarta.el.ELContext is what links the Jakarta Expression Language 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 Jakarta Expression Language is used in a web container, the creation of ELContext objects is controlled through the underlying technology. For example, in Jakarta Server Pages, the JspContext.getELContext() factory method is used. In an stand-alone environment, a default jakarta.el.StandardELContext is provided.

Some technologies provide the ability to add an jakarta.el.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 Jakarta Expression Language: value expressions and method expressions. A jakarta.el.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 jakarta.el.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 Jakarta Expression Language expression can represent a method invocation, such as ${trader.buy("JAVA")}, where the arguments to the method invocation are specified in the expression.

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

Creation of Expressions

An expression is created through the jakarta.el.ExpressionFactory class. The factory provides two creation methods; one for each type of expression supported by Jakarta Expression Language.

To create an expression, one must provide an jakarta.el.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 a Jakarta Expression Language function (for example ${fn:toUpperCase(customer.name)}) or a Jakarta Expression Language variable, then jakarta.el.FunctionMapper and jakarta.el.VariableMapper objects must be available within the ELContext so that Jakarta Expression Language functions and Jakarta Expression Language 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 jakarta.el.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 Jakarta Faces request processing life cycle, Jakarta Expression Language 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 jakarta.el.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 jakarta.el.EvaluationListeners in ELContext, a user can receive notifications during the Jakarta Expression Language 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 jakarta.el.ELResolver base class, Jakarta Expression Language features a pluggable mechanism to resolve model object references as well as properties and method invocations of these objects.

The Jakarta Expression Language API provides implementations of ELResolver supporting property resolution for common data types which include arrays (jakarta.el.ArrayELResolver), JavaBeans (jakarta.el.BeanELResolver), Lists (jakarta.el.ListELResolver), Maps (jakarta.el.MapELResolver), and ResourceBundles (jakarta.el.ResourceBundleELResolver).

Jakarta Expression Language Functions

If a Jakarta Expression Language expression uses a function (for example ${fn:toUpperCase(customer.name)}), then a jakarta.el.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.

Jakarta Expression Language Variables

Just like jakarta.el.FunctionMapper provides a flexible mechanism to add functions to Jakarta Expression Language, jakarta.el.VariableMapper provides a flexible mechanism to support the notion of Jakarta Expression Language variables.

A Jakarta Expression Language variable does not directly refer to a model object that can then be resolved by an ELResolver. Instead, it refers to a Jakarta Expression Language expression. The evaluation of that Jakarta Expression Language expression gives the Jakarta Expression Language 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 a Jakarta Expression Language Resolver.

However, in this other example:

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

item is a Jakarta Expression Language variable because it does not refer directly to a model object. Instead, it refers to another Jakarta Expression Language expression, namely a specific item in the collection referred to by the Jakarta Expression Language 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 jakarta.el.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 a Jakarta Expression Language variable to the Jakarta Expression Language expression from which it gets its value.

Jakarta Expression Language in Stand-alone environment

Jakarta Expression Language 5.0 includes APIs for using Jakarta Expression Language in a stand-alone environment.

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

jakarta.el.ELManager provides lower level APIs for managing the Jakarta Expression Language parsing and evaluation environment. It contains a default ELContext jakarta.el.StandardELContext.

Modifier and Type	Interface and Description
public interface	ELContextListener The listener interface for receiving notification when an `ELContext` is created.

Class Summary

Modifier and Type	Class and Description
public class	ArrayELResolver Defines property resolution behavior on arrays.
public class	BeanELResolver Defines property resolution behavior on objects using the JavaBeans component architecture.
public class	BeanNameELResolver An `ELResolver` for resolving user or container managed beans.
public abstract class	BeanNameResolver Resolves a bean by its known name.
public class	CompositeELResolver Maintains an ordered composite list of child `ELResolver`s.
public class	ELClass A runtime representation of a Class in the Jakarta Expression Language expressions.
public abstract class	ELContext Context information for expression parsing and evaluation.
public class	ELContextEvent An event which indicates that an `ELContext` has been created.
public class	ELException Represents any of the exception conditions that can arise during expression evaluation.
public class	ELManager Manages Jakarta Expression Language parsing and evaluation environment.
public class	ELProcessor Provides an API for using Jakarta Expression Language in a stand-alone environment.
public abstract class	ELResolver Enables customization of variable, property, method call, and type conversion resolution behavior for Jakarta Expression Language expression evaluation.
pack-priv class	ELUtil Utility methods for this portion of the Jakarta Expression Language implementation Methods on this class use a Map instance stored in ThreadLocal storage to minimize the performance impact on operations that take place multiple times on a single Thread.
public abstract class	EvaluationListener The listener interface for receiving notification when a Jakarta Expression Language expression is evaluated.
public abstract class	Expression Base class for the expression subclasses `ValueExpression` and `MethodExpression`, implementing characteristics common to both.
public abstract class	ExpressionFactory Provides an implementation for creating and evaluating Jakarta Expression Language expressions.
pack-priv class	FactoryFinder
public abstract class	FunctionMapper The interface to a map between Jakarta Expression Language function names and methods.
public class	ImportHandler Handles imports of class names and package names.
public class	LambdaExpression Encapsulates a parameterized `ValueExpression`.
public class	ListELResolver Defines property resolution behavior on instances of `java.util.List`.
public class	MapELResolver Defines property resolution behavior on instances of `java.util.Map`.
public abstract class	MethodExpression An `Expression` that refers to a method on an object.
public class	MethodInfo Holds information about a method that a `MethodExpression` evaluated to.
public class	MethodNotFoundException Thrown when a method could not be found while evaluating a `MethodExpression`.
public class	MethodReference Provides information about the method to which a method expression resolves.
public class	PropertyNotFoundException Thrown when a property could not be found while evaluating a `ValueExpression` or `MethodExpression`.
public class	PropertyNotWritableException Thrown when a property could not be written to while setting the value on a `ValueExpression`.
public class	ResourceBundleELResolver Defines property resolution behavior on instances of `java.util.ResourceBundle`.
public class	StandardELContext A standard ELContext suitable for use in a stand alone environment.
public class	StaticFieldELResolver An `ELResolver` for resolving static fields, enum constants and static methods.
public abstract class	TypeConverter A convenient class for writing an ELResolver to do custom type conversions.
public abstract class	ValueExpression An `Expression` that can get or set a value.
public class	ValueReference This encapsulates a base model object and one of its properties.
public abstract class	VariableMapper The interface to a map between Jakarta Expression Language variables and the Jakarta Expression Language expressions they are associated with.

Package jakarta.el