Expression Language

The Expression Language (EL) is a small expression language with its own specification, Jakarta Expression Language. It is used by Jakarta Faces, Jakarta Server Pages, Jakarta Tags, CDI and Bean Validation messages, and it can also be used stand-alone from Java SE. The Faces specification does not redefine the language; its chapter on the Expression Language describes only how Faces plugs into it. That chapter states that nearly every attribute and property of a component can have a value expression associated with it, and that many properties such as action, actionListener, validator and valueChangeListener can be defined by a method expression pointing at a public method.

The Jakarta EE Tutorial summarises what the language does: it reads application data from beans, various data structures and implicit objects; writes data such as user input to beans; invokes public and static methods; performs arithmetic, boolean and string operations; and constructs and operates on collections.

The pieces involved are few, and the rest of the page keeps returning to them.

Source: Jakarta Faces 4.1 specification, chapter 5: Expression Language Facility and Jakarta EE Tutorial: Jakarta Expression Language

The language has two delimiters. The Jakarta EE Tutorial defines them like this:

Faces has a multi-phase lifecycle in which components are decoded, converted, validated and updated in a fixed order, so it needs deferral. The Tutorial states that Faces uses mostly deferred expressions, and that a deferred expression may be an lvalue (it can be assigned to) while an immediate one never assigns anything.

A value expression yields a value. It is an rvalue when it can only be read, and an lvalue when it also names a target that can be assigned: a bean property, a map entry, an array or list element, or a scoped attribute. The expression #{catalogueBean.query} is both. When the page is rendered, it is read as an rvalue and shown as the default value of the text field. When the form is submitted, it is evaluated as an lvalue and the converted and validated value is pushed into the bean through setQuery. An expression that contains an operator, such as #{a + b}, or a method call with a result, such as #{catalogueBean.books.size()}, is only an rvalue; using it as the value of an input component fails at update time with a PropertyNotWritableException.

Source: Jakarta Faces 4.1 specification, 5.1.1 Value Expressions Overview

A method expression identifies a public method and is evaluated by invoking it. It has the same syntax as an lvalue expression, so #{catalogueBean.select} and #{catalogueBean['select']} mean the same. Because a method may be invoked in different phases, method expressions always use the deferred syntax #{}. They can only be used in attributes, and in one of two forms: a single expression, or a literal. The literal form exists for action, where action="success" is a method expression that simply returns the string "success" as the navigation outcome.

The signature that the method must have depends on the attribute. The Faces specification fixes some of them, and the others were tested on Mojarra 4.1.17.

The specification adds that these expressions are wrapped by jakarta.faces.event.MethodExpressionActionListener, jakarta.faces.validator.MethodExpressionValidator and jakarta.faces.event.MethodExpressionValueChangeListener so that they behave exactly like the equivalent Java class. An attribute that accepts a method expression can be set programmatically with a MethodExpression obtained from the ExpressionFactory, covered later on this page.

A method expression is looked up by name and parameter count and type, so an overloaded or misspelled method fails when it is used, not when the view is built. With a bean that only had select(Book) and select(long), the expression action="#{catalogueBean.select}" failed on the postback with Method not found: ...CatalogueBean...select(), because no method without parameters existed.

Source: Jakarta Faces 4.1 specification, 5.2 MethodExpressions

The literals are true and false, integers and floating-point numbers as in Java, strings in single or double quotes (with \", \' and \\ escapes), and null. The operators of the language, from the highest precedence to the lowest, are:

The reserved words, which cannot be used as identifiers, are and, or, not, eq, ne, lt, gt, le, ge, true, false, null, instanceof, empty, div and mod. A bean named empty or a property named div cannot be reached with the dot notation; use the bracket form.

The words matter in XHTML because a Facelets view is an XML document. In an attribute value a bare < or && makes the file not well-formed. Use the word operators (lt, le, and, …​) or the escaped forms; both were tested:

The following results were evaluated with the Tomcat 11.0.26 EL 6.0 implementation (books is the Bookshelf catalogue, book its first element).

Assignment = and the semicolon ; exist so that lambda expressions can be given a name and called, which is covered in the next section; they are not a way to set a bean property from the view, and an assignment never replaces a value binding.

Source: Jakarta EE Tutorial: Operators and Jakarta Expression Language 6.0

An identifier that is not a bean name may be an implicit object, a name that Faces makes available in every expression. The Faces specification lists them in a table together with their scope. Since Faces 4.0 these objects are supplied through CDI (section 5.6.2 of the specification states that they must be resolved using CDI), which is why a Faces application that has no CDI container does not work in 4.x.

Source: Jakarta Faces 4.1 specification, 5.6.2.1 Implicit Objects for Facelets and Programmatic Access

Some of them are used constantly, and a few results were captured from the test page (a GET of index.xhtml?q=hi):

Notes on specific objects:

A top-level identifier, catalogueBean in #{catalogueBean.books}, can refer to one of the following, according to the Tutorial: a lambda parameter, an EL variable, a managed bean, an implicit object, or a class with static fields and methods.

EL variables are created by tags. They are plain names that exist only inside the tag that declares them:

Managed beans are CDI beans. A bean annotated @Named is available under the name given by the annotation, or, if the annotation has no value, under the class name with its first letter in lower case: CatalogueBean becomes catalogueBean. CDI is the only managed-bean facility in Faces 4.x. The old @ManagedBean annotation of Faces 2.x, deprecated in 2.3, was removed in 4.0, and so were faces-config.xml <managed-bean> entries and @ManagedProperty from javax.faces.bean. Books written for Faces 1.x and 2.x use them throughout.

An unknown name is not an error when it is only read, and is an error when it is a target. In the test, with no bean named nosuchbean:

A misspelled property of a known bean, #{catalogueBean.titel}, failed at once with Property [titel] not found on type [org.example.bookshelf.web.CatalogueBean]. In the Development project stage Mojarra shows both messages in its error page, with the view and the file position of the failing attribute.

A CDI bean name is resolved by the CDI container’s own ELResolver, which is described in the resolver section below. Tomcat needs Weld (or another CDI container) for this to work at all. The Tomcat and Weld page covers it.

Source: Jakarta EE Tutorial: Referencing Objects

The Expression Language since version 3.0 (Java EE 7) can build collections, define lambda expressions and run operations on streams, so some filtering that was once written in a bean can be written in the view. These results were all tested on the Bookshelf catalogue.

The Expression Language can read the static fields of a class and call its static methods: Boolean.FALSE, Integer.MAX_VALUE. The class is named without its package. By default only java.lang is imported, which is why these two work in a view without any setup (tested: false and 2147483647). Other classes have to be imported into the ELContext before an expression can name them. Outside Faces, with the stand-alone ELProcessor, this is done in Java with importClass, importStatic or importPackage, and then DayOfWeek.MONDAY, Math.max(3,4) and Collections.emptyList() all evaluate (tested).

Inside a Facelets view there is no import tag for the language itself. Faces 2.3 added the tag f:importConstants for the common case: constants. It is placed in the f:metadata element of a view, and it exposes all the public static final fields of a class, interface or enum as a map.

The page printed 5, bk-, BORROWED for #{Status.BORROWED}, and true for the comparison above. The tag has two attributes, as documented in the tag library documentation:

The map key is the name of the constant field, and the value is the constant, so #{Limits.MAX_LOANS} and #{Limits['MAX_LOANS']} are the same. The tag works for enums too; an enum constant is a static field. A convenient effect is that comparing against an enum constant needs no string: #{book.status == Status.BORROWED} rather than #{book.status == 'BORROWED'}. Both worked in the test because the EL coerces the string to the enum constant, but the first form fails at once if the constant is renamed, whereas the second one only compares to a string that no longer exists.

Compared with older approaches, f:importConstants replaces a bean that exposes constants through a getter, which Faces 1.x and 2.x books recommend, and OmniFaces' o:importConstants that did the same before 2.3. The restriction to f:metadata is a known limitation: the Faces 5.0 milestone page, which is upcoming work and not current behaviour, lists the issue "importConstants should be allowed everywhere, not only in f:metadata" (issue 1466). With the 4.1 tag, keep the f:importConstants elements inside the f:metadata of the view; in a template that means the metadata slot described on the templating page. The OmniFaces tag of the same name is covered on the OmniFaces page.

Source: Jakarta Faces 4.1 VDL documentation: f:importConstants

Every segment of an expression is resolved by an ELResolver. The Faces specification gives the example of <h:outputText value="#{user.address.street}"/>: the resolver chain is called three times, once for user, once for the property address of the result and once for street. The first call has a null base and the property user; the later ones have the previous result as base. Each resolver in the chain gets a chance. When one resolves the segment, it calls context.setPropertyResolved(true) and returns the value; when it does not recognise the segment it leaves the flag alone, and the next resolver is tried.

The chain Faces builds for Facelets and for programmatic access, in the order the specification adds the resolvers, is:

The specification describes each of them.

The consequences of this order explain several common surprises:

The ELResolver for the Faces side is also returned from FacesContext.getELContext().getELResolver() and Application.getELResolver(), and the CDI container maintains one top-level resolver, BeanManager.getELResolver(), in which a Faces-specific resolver is added. Resolvers have the lifetime of the application. A conformant implementation may arrange them differently internally as long as the behaviour is the same.

In Faces 4.x the expression #{catalogueBean.books} is resolved by CDI. A bean class carries @Named and a scope annotation from jakarta.enterprise.context (@RequestScoped, @SessionScoped, @ApplicationScoped, @ConversationScoped) or jakarta.faces.view.ViewScoped, as the beans page explains. The container then makes the bean available by name to the Expression Language. What matters for expressions:

On a Jakarta EE server this is already set up. On Tomcat, Faces needs a CDI container (Weld) and a beans.xml; without CDI, Mojarra 4.1 fails at startup with a ClassNotFoundException for its CDI-aware bean manager. The Tomcat and Weld page explains the setup.

Source: Jakarta Faces 4.1 specification, 5.6 CDI Integration and Jakarta CDI 4.1 specification

A bean, converter or phase listener sometimes needs to evaluate an expression in code, or to attach an expression to a component it creates. Faces gives three entry points.

The following bean was run on Mojarra 4.1.17. Its evaluate action reads an expression, builds a value expression and checks whether it is read-only, and builds and invokes a method expression; the page shows the stored text.

After a click the output was 1.4.0||false|null: the version from the resolver of the previous section, the empty query, a writable expression and a null outcome. The work is done in an action method on purpose. An earlier variant of this bean did the same evaluations inside getResult(), which was itself reached through the expression #{evalBean.result}, and it failed on Mojarra 4.1.17 with Tomcat 11.0.26 with ELResolver did not handle type: [null] with property of [result], because the nested evaluations ran in the middle of the outer one on the same ELContext. Evaluate expressions from action methods, listeners and lifecycle callbacks, not from a getter that the view itself calls through an expression.

Because the FacesContext can be injected in Faces 4.x (@Inject FacesContext, one of the injectable Faces objects in the specification), a bean does not need FacesContext.getCurrentInstance(). The ELContext is created lazily on the first call to getELContext(); it has the same lifetime as the FacesContext, and when it is created Faces puts the FacesContext into it, which is how resolvers reach the context, and notifies the registered `ELContextListener`s.

The evaluation exceptions are jakarta.el.ELException and its subclasses PropertyNotFoundException (the property or a bean name does not exist), MethodNotFoundException (no such public method) and PropertyNotWritableException (the target is read-only).

Source: Jakarta Faces 4.1 API: Application and Jakarta Faces 4.1 specification, 5.3.1 ELContext and 5.5 Current Expression Evaluation APIs

The whole page below uses the beans and model types shown earlier and the Facelets features of this page. It is a catalogue with a search box, a list with a per-row action and a short statistics line.

Source: Jakarta EE Tutorial: Examples of EL Expressions

The Expression Language is a specification of its own, with its own release for each Jakarta EE release. The Expression Language column for 4.0, 5.0 and 6.0 comes from the release pages and from the change appendix of the Jakarta Expression Language 6.0 specification, and the 1.2 row from the specification’s historical note. For the releases before 3.0 no Jakarta release page exists, so those rows name no EL version number. The Faces column states what Faces did with each release.

Source: Jakarta Expression Language 6.0, 5.0 and 4.0 release pages, and the Faces 5.0 milestone page

The two Faces books that treat the language, in particular JavaServer Faces 2.0: The Complete Reference by Ed Burns and Chris Schalk, describe the Expression Language as it was in Faces 1.2 and 2.0 (EL 1.2 and 2.1). Most of it is still correct for value expressions, method expressions, the scopes and the implicit objects. What is out of date: