Skip to content

Latest commit

 

History

History
1048 lines (774 loc) · 37.8 KB

ExpressionLanguageFacility.adoc

File metadata and controls

1048 lines (774 loc) · 37.8 KB

Expression Language Facility

In the descriptions of the standard user interface component model, it was noted that all attributes, and nearly all properties can have a value expression associated with them (see ValueExpression properties). In addition, many properties, such as action, actionListener, validator, and valueChangeListener can be defined by a method expression pointing at a public method in some class to be executed. This chapter describes the mechanisms and APIs that Jakarta Faces utilizes in order to evaluate value expressions and method expressions.

Jakarta Faces relies on Jakarta Expression Language as described by version 4.0 of the Jakarta Expression Language specification. Please consult that document for complete details about the Expression Language.

This chapter will focus exclusively on how Jakarta Faces leverages and integrates with Jakarta Expression Language. It does not describe how Jakarta Expression Language operates.

Value Expressions

Overview

To support binding of attribute and property of values to dynamically calculated results, the name of the attribute or property can be associated with a value expression using the setValueExpression() method. Whenever the dynamically calculated result of evaluating the expression is required, the getValue() method of the ValueExpression is called, which returns the evaluated result. Such expressions can be used, for example, to dynamically calculate a component value to be displayed:

<h:outputText value="#{customer.name}" />

which, when this page is rendered, will retrieve the bean stored under the “customer” key, then acquire the name property from that bean and render it.

Besides the component value itself, value expressions can be used to dynamically compute attributes and properties. The following example checks a boolean property manager on the current user bean (presumably representing the logged-in user) to determine whether the salary property of an employee should be displayed or not:

<h:outputText rendered="#{user.manager}" value="#{employee.salary}" />

which sets the rendered property of the component to false if the user is not a manager, and therefore causes this component to render nothing.

The Jakarta Expression Language has a powerful set of coercion rules that automatically convert the type of the value to the appropriate type. These rules occasionally rely on the JavaBeans PropertyEditor facility to perform this conversion. Note that this conversion is entirely separate from normal Jakarta Faces Conversion.

Value expressions can also be used to set a value from the user into the item obtained by evaluating the expression. For example:

<h:inputText value="#{employee.number}" />

When the page is rendered, the expression is evaluated as an r-value and the result is displayed as the default value in the text field. When the page is submitted, the expression is evaluated as an l-value, and the value entered by the user (subject to conversion and validation as usual) is pushed into the expression.

Value Expression Syntax and Semantics

Please see Section 1.2 of the Jakarta Expression Language Specification, Version 4.0 or higher for the complete specification of ValueExpression syntax and semantics.

MethodExpressions

Method expressions are a very similar to value expressions, but rather than supporting the dynamic retrieval and setting of properties, method expressions support the invocation (i.e. execution) of an arbitrary public method of an arbitrary object, passing a specified set of parameters, and returning the result from the called method (if any). They may be used in any phase of the request processing lifecycle; the standard Jakarta Faces components and framework employ them (encapsulated in a MethodExpression object) at the following times:

  • During Apply Request Values or Invoke Application phase (depending upon the state of the immediate property), components that implement the ActionSource behavioral interface (see ActionSource) utilize MethodExpressions as follows:

    • If the actionExpression property is specified, it must be a MethodExpression expression that identifies an Application Action method (see Application Actions) that takes no parameters and returns a String.

    • It’s possible to have a method expression act as an ActionListener by using the classs MethodExpressionActionListener to wrap a method expression and calling the addActionListener() method on the ActionSource. The method expression wrapped inside the MethodExpressionActionListener must identify a public method that accepts an ActionEvent (see Event Classes) instance, and has a return type of void. The called method has exactly the same responsibilities as the processAction() method of an ActionListener instance (see Listener Classes) that was built in to a separate Java class.

  • During the Apply Request Values or Process Validations phase (depending upon the state of the immediate property), components that implement EditableValueHolder (such as UIInput and its subclasses) components (see EditableValueHolder) utilize method expressions as follows:

    • The user can use the MethodExpressionValidator class to wrap a method expression that identifies a public method that accepts a FacesContext instance and a UIComponent instance, and an Object containing the value to be validated, and has a return type of void. This MethodExpressionValidator instance can then be added as a normal Validator using the EditableValueHolder.addValidator() method. The called method has exactly the same responsibilities as the validate() method of a Validator instance (see Validator Classes) that was built in to a separate Java class.

    • The user can use the MethodExpressionValueChangeListener class to wrap a method expression that identifies a public method that accepts a ValueChangeEvent (see Event Classes) instance, and has a return type of void. This MethodExpressionValueChangeListener instance can then be added as a normal ValueChangeListener using EditableValueHolder.addValueChangeListener(). The called method has exactly the same responsibilities as the processValueChange() method of a ValueChangeListener instance (see Listener Classes) that was built in to a separate Java class.

MethodExpression Syntax and Semantics

The exact syntax and semantics of MethodExpression are the domain of the Jakarta Expression Language. Please see Section 1.2.1.2 of the Jakarta Expression Language Specification, Version 4.0 or higher.

Jakarta Faces Managed Classes and Jakarta EE Annotations

The following Jakarta Faces artifacts must be injectable.

Jakarta Faces Artifacts Eligible for Injection
  • jakarta.faces.application.ApplicationFactory

  • jakarta.faces.application.NavigationHandler

  • jakarta.faces.application.ResourceHandler

  • jakarta.faces.application.StateManager

  • jakarta.faces.component.visit.VisitContextFactory

  • jakarta.faces.context.ExceptionHandlerFactory

  • jakarta.faces.context.ExternalContextFactory

  • jakarta.faces.context.FacesContextFactory

  • jakarta.faces.context.PartialViewContextFactory

  • jakarta.faces.event.ActionListener

  • jakarta.faces.event.SystemEventListener

  • jakarta.faces.lifecycle.ClientWindowFactory

  • jakarta.faces.lifecycle.LifecycleFactory

  • jakarta.faces.event.PhaseListener

  • jakarta.faces.render.RenderKitFactory

  • jakarta.faces.view.ViewDeclarationLanguageFactory

  • jakarta.faces.view.facelets.FaceletCacheFactory

  • jakarta.faces.view.facelets.TagHandlerDelegateFactory

Please consult the Jakarta EE Specification for complete details of this feature. Here is a summary of the Jakarta EE annotations one may use in a artifact from the preceding table.

  • @jakarta.inject.Inject

  • @jakarta.inject.Named

  • @jakarta.inject.Qualifier

  • @jakarta.inject.Scope

  • @jakarta.inject.Singleton

  • @jakarta.enterprise.context.ApplicationScoped

  • @jakarta.enterprise.context.ConversationScoped

  • @jakarta.enterprise.context.Dependent

  • @jakarta.enterprise.context.RequestScoped

  • @jakarta.enterprise.context.SessionScoped

  • @jakarta.annotation.Resource

  • @jakarta.annotation.Resources

  • @jakarta.ejb.EJB

  • @jakarta.ejb.EJBs

  • @jakarta.xml.ws.WebServiceRef

  • @jakarta.xml.ws.WebServiceRefs

  • @jakarta.persistence.PersistenceContext

  • @jakarta.persistence.PersistenceContexts

  • @jakarta.persistence.PersistenceUnit

  • @jakarta.persistence.PersistenceUnits

How Faces Leverages the Expression Language

This section is non-normative and covers the major players in the Jakarta Expression Language and how they relate to Jakarta Faces. The number one goal in this version of the Jakarta Faces specification is to export the concepts behind the Jakarta Faces EL into the Jakarta Expression Language, and then rely on those facilities to get the work done. Readers interested in how to implement the Jakarta Expression Language itself must consult the Jakarta Expression Language Spec document.

ELContext

The ELContext is a handy little “holder” object that gets passed all around the Jakarta Expression Language API. It has two purposes.

  • To allow technologies that use the Jakarta Expression Language, such as Jakarta Faces, Jakarta Server Pages and Jakarta Tags, to store any context information specific to that technology so it can be leveraged during expression evaluation. For example the expression “#{view.viewId}” is specific to Jakarta Faces. It means, “find the UIViewRoot instance for the current view, and return its viewId”. The Jakarta Expression Language doesn’t know about the “view” implicit object or what a UIViewRoot is, but Jakarta Faces does. The Jakarta Expression Language has plugin points that will get called to resolve “view”, but to do so, Jakarta Faces needs access to the FacesContext from within the callstack of Expression Language evaluation. Therefore, the ELContext comes to the rescue, having been populated with the FacesContext earlier in the request processing lifecycle.

  • To allow the pluggable resolver to tell the Jakarta Expression Language that it did, in fact, resolve a property and that further resolvers must not be consulted. This is done by setting the “propertyResolved” property to true.

The complete specification for ELResolver may be found in Chapter 2 of the Jakarta Expression Language Specification, Version 4.0.

Lifetime, Ownership and Cardinality

An ELContext instance is created the first time getELContext() is called on the FacesContext for this request. Please see ELContext for details. Its lifetime ends the same time the FacesContext’s lifetime ends. The FacesContext maintains the owning reference to the ELContext. There is at most one ELContext per FacesContext.

Properties
Name Access Type Description

ELResolver

RO

jakarta.el.ELResolver

Return the ELResolver instance described in Faces ELResolver for Facelets and Programmatic Access

propertyResolved

RW

boolean

Set by an ELResolver implementation if it successfully resolved a property. See ELResolver for how this property is used.

Methods

Here is a subset of the methods that are relevant to Jakarta Faces.

public Object getContext(Class key);
void putContext(Class key, Object contextInstance);
...

As mentioned in ELContext, the putContext() method is called, passing the current FacesContext instance the first time the system asks the FacesContext for its ELContext. The getContext() method will be called by any ELResolver instances that need to access the FacesContext to perform their resolution.

Events

The creation of an ELContext instance precipitates the emission of an ELContextEvent from the FacesContext that created it. Please see ELContext for details.

ELResolver

Faces 1.1 used the VariableResolver and PropertyResolver classes as the workhorses of expression evaluation. The Unified API has the ELResolver instead. The ELResolver concept is the heart of the Jakarta Expression Language. When an expression is evaluated, the ELResolver is responsible for resolving each segment in the expression. For example, in rendering the component behind the tag “<h:outputText value="#{user.address.street}" />” the ELResolver is called three times. Once to resolve “user”, again to resolve the “address” property of user, and finally, to resolve the “street” property of “address”. The complete specification for ELResolver may be found in Chapter 2 of the Jakarta Expression Language Specification, Version 4.0 or higher.

As described in more detail in ELResolver Instance Provided by Faces, Faces must provide an implementation of ELResolver. During the course of evaluation of an expression, a variety of sources must be considered to help resolve each segment of the expression. These sources are linked in a chain-like fashion. Each link in the chain has the opportunity to resolve the current segment. If it does so, it must set the “propertyResolved” property on the ELContext, to true. If not, it must not modify the value of the “propertyResolved” property. If the “propertyResolved” property is not set to true the return value from the ELResolver method is ignored by the system.

Lifetime, Ownership, and Cardinality

ELResolver instances have application lifetime and scope. The CDI container maintains one top level ELResolver (into which a Faces specific ELResolver is added) accessible from BeanManager.getELResolver(). This ELResolver instance is also used from the Jakarta Faces VDL. Faces maintains one ELResolver accessible from FacesContext.getELContext().getELResolver() and Application.getELResolver().

Properties

ELResolver has no proper JavaBeans properties

Methods

Here is a subset of the methods that are relevant to Faces.

public Object getValue(ELContext context, Object base, Object property);
void setValue(ELContext context,
    Object base, Object property, Object value);
...

getValue() looks at the argument base and tries to return the value of the property named by the argument property. For example, if base is a JavaBean, property would be the name of the JavaBeans property, and the resolver would end up calling the getter for that property.

setValue() looks at the argument base and tries to set the argument value into the property named by the argument property. For example, if base is a JavaBean, property would be the name of the JavaBeans property, and the resolver would end up calling the setter for that property.

There are other methods, such as isReadOnly() that are beyond the scope of this document, but described completely in the Jakarta Expression Language Specification.

Events

ELResolver precipitates no events.

ExpressionFactory

The Jakarta Expression Language owns the ExpressionFactory class. It is a factory for ValueExpression and MethodExpression instances.

Lifetime, Ownership, and Cardinality

ExpressionFactory instances are application scoped. The Application object maintains the ExpressionFactory instance used by Faces (See Acquiring ExpressionFactory Instance). The ELManager object maintains the ExpressionFactory used by the Jakarta Expression Language (and therefore by the Jakarta Faces VDL). It is permissible for both of these access methods to yield the same java object instance.

Properties

ExpressionFactory has no properties.

Methods
public MethodExpression createMethodExpression(ELContext context,
    String expression, FunctionMapper fnMapper, Class[] paramTypes);
public ValueExpression createValueExpression(ELContext context,
    String expression, Class expectedType, FunctionMapper fnMapper);

These methods take the human readable expression string, such as "#{user.address.street}" and return an object oriented representation of the expression. Which method one calls depends on what kind of expression you need. The Faces Application class has convenience methods specific to Faces needs for these concepts, please see Programmatically Evaluating Expressions .

Events

ExpressionFactory precipitates no events.

ELResolver Instance Provided by Faces

This section provides details on what an implementation of the Jakarta Faces specification must do to support the Jakarta Expression Language for usage in a Jakarta Faces application.

ELResolver mentions that a Faces implementation must provide an implementation of ELResolver. This ELResolver, let’s call it the Faces ELResolver for Facelets and Programmatic Access, is used by Facelets markup pages, and is returned from FacesContext.getELContext().getELResolver() and Application.getELResolver(), and is used to resolve expressions that appear programmatically. See the javadocs for jakarta.el.ELResolver for the specification and method semantics for each method in ELResolver. The remainder of this section lists the implementation requirements for this resolver.

ELResolvers from application configuration resources

The <el-resolver> element in the application configuration resources will contain the fully qualified classname to a class with a public no-arg constructor that implements jakarta.el.ELResolver. These are added to the Faces ELResolver for Facelets and Programmatic Access in the order in which they occur in the application configuration resources.

ELResolvers from Application.addELResolver()

Any such resolvers are considered at this point in the Faces ELResolver for Facelets and Programmatic Access in the order in which they were added.

Faces ELResolver for Facelets and Programmatic Access

This section documents the requirements for the second ELResolver mentioned in ELResolver Instances Provided by Faces, the one that is used for Facelets and for programmatic expression evaluation from Faces java code.

The implementation for the ELResolver for Programmatic Access is described as a set of ELResolvers inside of a CompositeELResolver instance, but any implementation strategy is permissible as long as the semantics are preserved. .

This diagram shows the set of ELResolver instances that must be added to the ELResolver for Programmatic Access. This instance must be returned from Application.getELResolver() and FacesContext.getELContext().getELResolver(). It also shows the order in which they must be added.

ELResolver for Facelets and Programmatic Access

ELResolver chain

The semantics of each ELResolver are given below, either in tables that describe what must be done to implement each particular method on ELResolver, in prose when such a table is inappropriate, or as a reference to another section where the semantics are exactly the same.

faces.CompositeComponentAttributesELResolver

This ELResolver makes it so expressions that refer to the attributes of a composite component get correctly evaluated. For example, the expression #{cc.attrs.usernameLabel} says, “find the current composite component, call its getAttributes() method, within the returned Map look up the value under the key “usernameLable”. If the value is a ValueExpression, call getValue() on it and the result is returned as the evaluation of the expression. Otherwise, if the value is not a ValueExpression the value itself is returned as the evaluation of the expression.”

Table 1. Composite Component Attributes ELResolver
ELResolver method implementation requirements

getValue

If base is non-null, is an instance of UIComponent, is a composite component, and property is non-null and is equal to the string “attrs”, return a Map implementation with the following characteristics.

Wrap the attributes map of the composite component and delegate all calls to the composite component attributes map with the following exceptions:

get(), put(), and containsKey() are required to be supported.

get(): if the result of calling get() on the component attributes map is null, and a default value was declared in the composite component metadata, the value will be a ValueExpression. Evaluate it and return it. Otherwise, simply return the value from the component attributes map.

put(): Call getValueExpression() on the component. If this returns non-null, call setValue() on it, passing the value argument as the last argument. Otherwise, simply call through to put on the component attributes map.

containsKey(): If the attributes map contains the key, return true. Otherwise, if a default value has been declared for the attribute, return true. Otherwise, return false.

The Map implementation must also implement the interface

jakarta.faces.el.CompositeComponentExpressionHolder.

Otherwise, take no action.

getType

If the base argument to getType() is not an instance of the composite component attributes map or the property argument to getType() is not an instance of java.lang.String, return null. Otherwise, check the top level component’s ValueExpression collection for an expression under the name given by the property argument to getType(). If the expression exists, call getType() on the expression. If the property argument to getType() is not empty, search the composite component’s metadata for a declared type on a <cc:attribute> whose name matches the property argument to getType(). If the expression and the metadata both yield results, the metadata takes precedence ONLY if it provides a narrower result than does the expression, i.e. expression type is assignable from metadata type. If the metadata result does take precedence, call ELContext.setPropertyResolved(true). Otherwise, return whichever result was available, or null.

setValue

Take no action.

isReadOnly

Take no action and return true.

getFeatureDescriptors

Take no action.

getCommonPropertyType

Return String.class

el.CompositeELResolver

As indicated in ELResolver for Facelets and Programmatic Access, following the faces.CompositeComponentAttributesELResolver, the semantics obtained by adding a CompositeELResolver must be inserted here. This ELResolver contains the following ELResolvers, described in the referenced sections.

faces.ResourceELResolver

This Resource ELResolver for Facelets and Programmatic Access resolver is a means by which Resource instances are encoded into a faces request such that a subsequent faces resource request from the browser can be satisfied using the ResourceHandler as described in Resource Handling.

Table 2. ResourceELResolver
ELResorver method implementation requirements

getValue

If base and property are not null, and base is an instance of ResourceHandler (as will be the case with an expression such as #{resource['jakarta.faces:faces.js']}, perform the following. (Note: This is possible due to the ImplicitObjectELResolver returning the ResourceHandler, see Implicit Objects for Facelets and Programmatic Access)

  • If property does not contain a colon character ‘:’, treat property as the resourceName and pass property to ResourceHandler.createResource(resourceName).

  • If property contains a single colon character ‘:’, treat the content before the ‘:’ as the libraryName and the content after the ‘:’ as the resourceName and pass both to ResourceHandler.createResource(resourceName, libraryName). If the value of libraryName is the literal string “this” (without the quotes), discover the library name of the current resource (or the contract name of the current resource, the two are mutually exclusive) and replace “this” with that library name (or contract name) before calling ResourceHandler.createResource(). In the case of resource library contracts, libraryName will actually be the contract name.

  • If property contains more than one colon character ‘:’, throw a localized ELException, including property.

If one of the above steps results in the creation of a non-null Resource instance, call ELContext.setPropertyResolved(true). Call the getRequestPath() method on the Resource instance, pass the result through ExternalContext.encodeResourceUrl() and return the result.

getType

Return null. This resolver only performs lookups.

setValue

Take no action.

isReadOnly

Return false in all cases.

getFeatureDescriptors

Return null.

getCommonPropertyType

If base is non-null, return null.

If base is null, return Object.class.

el.ResourceBundleELResolver

This entry in the chain must have the semantics the same as the class jakarta.el.ResourceBundleELResolver. The default implementation just includes an instance of this resolver in the chain.

faces.ResourceBundleELResolver

This Resource Bundle ELResolver for Facelets and Programmatic Access is the means by which resource bundles defined in the application configuration resources are called into play during Expression Language resolution.

Table 3. ResourceBundleELResolver
ELResorver method implementation requirements

getValue

If base is non-null, return null.

If base is null and property is null, throw PropertyNotFoundException.

If base is null and property is a String equal to the value of the <var> element of one of the <resource-bundle>'s in the application configuration resources, use the Locale of the current UIViewRoot and the base-name of the resource-bundle to load the ResourceBundle. Call setPropertyResolved(true). Return the ResourceBundle. Otherwise, return null.

getType

If base is non-null, return null.

If base is null and property is null, throw PropertyNotFoundException.

If base is null and property is a String equal to the value of the <var> element of one of the <resource-bundle>'s in the application configuration resources, call setPropertyResolved(true) and return ResourceBundle.class.

setValue

If base is null and property is null, throw PropertyNotFoundException.

If base is null and property is a String equal to the value of the <var> element of one of the <resource-bundle>'s in the application configuration resources throw jakarta.el.PropertyNotWriteable, since ResourceBundles are read-only.

isReadOnly

If base is non-null, return null.

If base is false and property is null, throw PropertyNotFoundException.

If base is null and property is a String equal to the value of the <var> element of one of the <resource-bundle>'s in the application configuration resources, call setPropertyResolved(true) on the argument ELContext and return true.

Otherwise return false;

getFeatureDescriptors

If base is non-null, return null.

If base is null, return an Iterator containing java.beans.FeatureDescriptor instances, one for each <resource-bundle> in the <application> element. It is required that all of these FeatureDescriptor instances set Boolean.TRUE as the value of the ELResolver.RESOLVABLE_AT_DESIGN_TIME attribute. The name of the FeatureDescriptor must be the var element of the <resource-bundle>. The displayName of the FeatureDescriptor must be the display-name of the <resource-bundle>. ResourceBundle.class must be stored as the value of the ELResolver.TYPE attribute. The shortDescription must be a suitable description depending on the implementation. The expert and hidden properties must be false. The preferred property must be true.

getCommonPropertyType

If base is non-null, return null.

If base is null, return string.Class.

Stream, StaticField, Map, List, Array, and Bean ELResolvers

These ELResolver instances are provided by the Jakarta Expression Language API and must be added in the following order:

  1. The return from ExpressionFactory.getStreamELResolver()

  2. jakarta.el.StaticFieldELResolver

  3. jakarta.el.MapELResolver

  4. jakarta.el.ListELResolver

  5. jakarta.el.ArrayELResolver

  6. jakarta.el.BeanELResolver

These actual ELResolver instances must be added. It is not compliant to simply add other resolvers that preserve these semantics.

faces.ScopedAttributeELResolver

This Scoped Attribute ELResolver for Facelets and Programmatic Access is responsible for doing the scoped lookup that makes it possible for expressions to pick up anything stored in the request, session, or application scopes by name.

Table 4. Scoped Attribute ELResolver
ELResorver method implementation requirements

getValue

If base is non-null, return null.

If base is null and property is null, throw PropertyNotFoundException.

Use the argument property as the key in a call to externalContext.getRequestMap().get(). If this returns non-null, call setPropertyResolved(true) on the argument ELContext and return the value.

Use the argument property as the key in a call to facesContext.getViewRoot().getViewMap().get() (accounting for the potential for null returns safely). If this returns non-null, call setPropertyResolved(true) on the argument ELContext and return the value.

Use the argument property as the key in a call to externalContext.getSessionMap().get(). If this returns non-null, call setPropertyResolved(true) on the argument ELContext and return the value.

Use the argument property as the key in a call to externalContext.getApplicationMap().get(). If this returns non-null, call setPropertyResolved(true) on the argument ELContext and return the value.

Otherwise call setPropertyResloved(true) and return null;

getType

If base is non-null, return null.

If base is null and property is null, throw PropertyNotFoundException.

Otherwise, setPropertyResolved(true) and return Object.class to indicate that any type is permissable to pass to a call to setValue().

setValue

If base is non-null, return null.

If base is null and property is null, throw PropertyNotFoundException.

Consult the Maps for the request, session, and application, in order, looking for an entry under the key property. If found, replace that entry with argument value. If not found, call externalContext.getRequestMap().put(property, value).

Call setPropertyResolved(true) and return;

isReadOnly

If base is false, setPropertyResolved(true) return false;

Otherwise, return false;

getFeatureDescriptors

If base is non-null, return null.

If base is null, return an Iterator of java.beans.FeatureDescriptor instances for all attributes in all scopes. The FeatureDescriptor name and shortName is the name of the scoped attribute. The actual runtime type of the attribute must be stored as the value of the ELResolver.TYPE attribute. Boolean.TRUE must be set as the value of the ELResolver.RESOLVABLE_AT_DESIGN_TIME attribute. The shortDescription must be a suitable description depending on the implementation. The expert and hidden properties must be false. The preferred property must be true.

getCommonPropertyType

If base is non-null, return null.

If base is null return String.class.

Current Expression Evaluation APIs

ELResolver

Please see ELResolver for more details.

ValueExpression

It is the main object oriented abstraction for an Expression Language expression that results in a value either being retrieved or set. Please see Chapter 2 of the Jakarta Expression Language Specification, Version 4.0 or higher.

MethodExpression

It is the main object oriented abstraction for an Expression Language expression that results in a method being invoked. Please see Chapter 2 of the Jakarta Expression Language Specification, Version 4.0 or higher.

Expression Evaluation Exceptions

Four exception classes are defined to report errors related to the evaluation of value exceptions:

  • jakarta.el.ELException (which extends java.lang.Exception)—used to report a problem evaluating a value exception dynamically.

  • MethodNotFoundException (which extends jakarta.el.ELException)—used to report that a requested public method does not exist in the context of evaluation of a method expression.

  • jakarta.el.PropertyNotFoundException (which extends jakarta.el.ELException)—used to report that a requested property does not exist in the context of evaluation of a value expression.

  • jakarta.el.PropertyNotWriteableException (which extends jakarta.el.ELException)—used to indicate that the requested property could not be written to when evaluating the expression.

CDI Integration

Jakarta Faces must run in a container that supports CDI version 3.0 or higher. This requirement allows CDI to provide all the functionality of the managed bean facility in a better integrated way with the rest of the Jakarta EE platform. Delegating these features to CDI allows them to evolve independently of Jakarta Faces. The remainder of this section specifies some details of CDI integration pertinent to Jakarta Faces.

Jakarta Faces Objects Valid for @Inject Injection

It must be possible to inject the following Jakarta Faces objects into other objects using @Inject.

Maps Returned by Various Jakarta Faces Accessors

The annotations in package jakarta.faces.annotation are used to cause @Inject injection of the corresponding Map into a field. Generics may be used.

Jakarta Faces Objects

It must be possible to @Inject the following Jakarta Faces and Jakarta EE objects into CDI beans.

  • jakarta.faces.application.ResourceHandler

  • jakarta.faces.context.ExternalContext

  • jakarta.faces.context.FacesContext

  • jakarta.faces.context.Flash

  • jakarta.servlet.http.HttpSession

Support for Injection into Jakarta Faces Managed Objects

It must be possible to use @Inject when specifying the following kinds of Jakarta Faces managed objects.

  • Validators declared with @jakarta.faces.validator.FacesValidator(managed=true)

  • Converters declared with @jakarta.faces.convert.FacesConverter(managed=true)

  • FacesBehaviors declared with @jakarta.faces.component.behavior.FacesBehavior(managed=true)

Expression Language Resolution

The Implicit Objects for Facelets and Programmatic must be resolved using CDI

Implicit Objects for Facelets and Programmatic Access

The following Implicit Objects for Facelets and Programmatic Access must be resolved using CDI.

Table 5. Implicit Objects for Programmatic Access
implicitObject source scope

facesContext

FacesContext.getCurrentInstance()

request

externalContext

facesContext.getExternalContext()

request

application

externalContext.getContext()

application

applicationScope

externalContext.getApplicationMap()

application

cc

UIComponent.getCurrentCompositeComponent(facesContext)

dependent

cookie

externalContext.getRequestCookieMap()

request

component

UIComponent.getCurrentComponent(facesContext)

dependent

flash

externalContext.getFlash()

request

flow

facesContext.getApplication().getFlowHandler().getCurrentFlow()

flow

flowScope

facesContext.getApplication().getFlowHandler().getCurrentFlowScope()

flow

header

externalContext.getRequestHeaderMap()

request

headerValues

externalContext.getRequestHeaderValuesMap()

request

initParam

externalContext.getInitParameterMap()

application

param

externalContext.getRequestParameterMap()

request

paramValues

externalContext.getRequestParameterValuesMap()

request

request

externalContext.getRequest()

request

requestScope

externalContext.getRequestMap()

request

resource

facesContext.getApplication().getResourceHandler()

request

session

externalContext.getSession()

session

sessionScope

externalContext.getSessionMap()

session

view

facesContext.getViewRoot()

request

viewScope

facesContext.getViewRoot().getViewMap()

request