api/src/main/java/jakarta/el/package.html - third_party/jakartaee/expression-language - Git at Google

 <!--

     Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
     Copyright 2004 The Apache Software Foundation

     Licensed under the Apache License, Version 2.0 (the "License");
     you may not use this file except in compliance with the License.
     You may obtain a copy of the License at

         http://www.apache.org/licenses/LICENSE-2.0

     Unless required by applicable law or agreed to in writing, software
     distributed under the License is distributed on an "AS IS" BASIS,
     WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
     See the License for the specific language governing permissions and
     limitations under the License.

 -->

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
 </head>

 <body bgcolor="white">
 Provides the API for <strong>Jakarta Expression Language 4.0</strong>

 <p>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.</p>

 <p>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:

 <ul>
   <li><a href="#Context">Jakarta Expression Language Context</a></li>
   <li><a href="#ExpressionObjects">Expression Objects</a></li>
   <li><a href="#ExpressionCreation">Creation of Expressions</a></li>
   <li><a href="#ExpressionEvaluation">Evaluation of Expressions</a></li>
   <li><a href="#EvaluationListener">Evaluation Listeners</a></li>
   <li><a href="#Resolver">Resolution of Model Objects and their Properties</a></li>
   <li><a href="#Functions">Jakarta Expression Language Functions</a></li>
   <li><a href="#Variables">Jakarta Expression Language Variables</a></li>
   <li><a href="#Standalone">Jakarta Expression Language in Stand-alone environment</a></li>
 </ul>

 <h3><a name="Context">Jakarta Expression Language Context</a></h3>

 <p>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.</p>

 <p>Class {@link 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.
 </p>

 <p>When Jakarta Expression Language is used in a web container, the creation of <code>ELContext
 </code> objects is controlled through the underlying technology.
 For example, in Jakarta Server Pages, the
  <code>JspContext.getELContext()</code> factory method is used.  In an
 stand-alone environment, a default {@link jakarta.el.StandardELContext} is
 provided.</p>

  <p>Some technologies provide the ability to add an {@link jakarta.el.ELContextListener}
  so that applications and frameworks can ensure their own context objects
  are attached to any newly created <code>ELContext</code>.</p>

 <h3><a name="ExpressionObjects">Expression Objects</a></h3>

 <p>At the core of the Expression Language is the notion of an <i>expression</i>
 that gets parsed according to the grammar defined by the Expression Language.</p>

 <p>There are two types of expressions defined by Jakarta Expression Language: <i>value expressions</i>
 and <i>method expressions</i>. A {@link jakarta.el.ValueExpression} such as
 <code>"${customer.name}"</code> can be used either
 as an <i>rvalue</i> (return the value associated with property <code>name</code>
 of the model object <code>customer</code>) or as an <i>lvalue</i>
 (set the value of the property <code>name</code> of the model object
 <code>customer</code>).</p>

 <p>A {@link jakarta.el.MethodExpression} such as
 <code>"${handler.process}"</code> makes it possible to invoke a method
 (<code>process</code>) on a specific model object (<code>handler</code>).</p>

 <p>In version 2.2 and later, either type of Jakarta Expression Language expression can represent a method
 invocation, such as <code>${trader.buy("JAVA")}</code>, where the arguments to
 the method invocation are specified in the expression.</p>

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

 <h3><a name="ExpressionCreation">Creation of Expressions</a></h3>

 <p>An expression is created through the {@link jakarta.el.ExpressionFactory} class.
 The factory provides two creation methods; one for each type of expression
  supported by Jakarta Expression Language.</p>

 <p>To create an expression, one must provide an {@link jakarta.el.ELContext},
 a string representing
 the expression, and the expected type (<code>ValueExpression</code>) or signature
 (<code>MethodExpression</code>).

 The <code>ELContext</code> provides the context necessary to parse an expression.
 Specifically, if the expression uses a Jakarta Expression Language function
 (for example <code>${fn:toUpperCase(customer.name)}</code>) or a Jakarta Expression Language
 variable, then {@link jakarta.el.FunctionMapper} and {@link jakarta.el.VariableMapper}
 objects must be available within the <code>ELContext</code> so that Jakarta Expression Language
 functions and Jakarta Expression Language variables are properly mapped.

 <h3><a name="ExpressionEvaluation">Evaluation of Expressions</a></h3>
 <p>The creation and the evaluation of an expression are done in two separate
 steps.  At the evaluation of an expression, the {@link jakarta.el.ELContext}
 provides the context necessary to support property and method resolution
 for modal objects.</p>

 <p>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.</p>

 <p>Adding parameters to a <code>ValueExpression</code> further enhances the
 power of deferred expressions.  The {@link jakarta.el.LambdaExpression}
 encapsulates such a construct.  A <code>LambdaExpression</code> can be
 invoked by supplying the actual parameters at evaluation.  It plays
 an important role in the support for collections operators.</p>

 <h3><a name="EvaluationListener">Evaluation Listeners</a></h3>
 <p>By registering {@link jakarta.el.EvaluationListener}s in ELContext, a user can
 receive notifications during the Jakarta Expression Language expression evaluations.
 There are three events that trigger the notification:
 <ul>
   <li>Before evaluation</li>
   <li>After evaluation</li>
   <li>When (base, property) is resolved</li>
 </ul></p>

 <h3><a name="Resolver">Resolution of Model Objects and their Properties</a></h3>

 <p>Through the {@link 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.</p>

 <p>The Jakarta Expression Language API provides implementations of <code>ELResolver</code> supporting
 property resolution for common data types which include arrays
 ({@link jakarta.el.ArrayELResolver}), JavaBeans ({@link jakarta.el.BeanELResolver}),
 <code>List</code>s ({@link jakarta.el.ListELResolver}),
 <code>Map</code>s ({@link jakarta.el.MapELResolver}), and
 <code>ResourceBundle</code>s ({@link jakarta.el.ResourceBundleELResolver}).</p>

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

 <h3><a name="Functions">Jakarta Expression Language Functions</a></h3>

 <p>If a Jakarta Expression Language expression uses a function
 (for example <code>${fn:toUpperCase(customer.name)}</code>), then a
 {@link jakarta.el.FunctionMapper} object must also be specified within
 the <code>ELContext</code>.

 The <code>FunctionMapper</code> is responsible to map
  <code>${prefix:name()}</code> style functions to
 static methods that can execute the specified functions.
 </p>

 <h3><a name="Variables">Jakarta Expression Language Variables</a></h3>

 <p>Just like {@link jakarta.el.FunctionMapper} provides
 a flexible mechanism to add functions to Jakarta Expression Language,
 {@link jakarta.el.VariableMapper} provides a flexible mechanism to support the notion of
 <strong>Jakarta Expression Language variables</strong>.
 </p>

 <p>
 A Jakarta Expression Language variable does not directly refer to a model object that can then
 be resolved by an <code>ELResolver</code>. 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.
 </p>

 <p>
 For example, in the following code snippet
 <blockquote>
   <code>&lt;h:inputText value="#{handler.customer.name}"/&gt;</code>
 </blockquote>

 <code>handler</code> refers to a model object that can be resolved by a Jakarta Expression Language Resolver.
 </p>
 <p>
 However, in this other example:
 <blockquote>
 <pre>
 &lt;c:forEach var="item" items="#{model.list}"&gt;
    &lt;h:inputText value="#{item.name}"/&gt;
 &lt;/c:forEach&gt;
 </pre>
 </blockquote>

 <code>item</code> 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
 <code>#{model.list}</code>.
 </p>

 <p>
 Assuming that there are three elements in <code>${model.list}</code>, this means
 that for each invocation of <code>&lt;h:inputText&gt;</code>, the following information
 about <code>item</code> must be preserved in the {@link jakarta.el.VariableMapper}:
 <blockquote>
     first invocation: <code>item</code> maps to first element in <code>${model.list}</code><br>
     second invocation: <code>item</code> maps to second element in <code>${model.list}</code><br>
     third invocation: <code>item</code> maps to third element in <code>${model.list}</code><br>
 </blockquote>
 <p>
 <code>VariableMapper</code> 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.
 </p>

 <h3><a name="Standalone">Jakarta Expression Language in Stand-alone environment</a></h3>
 <p>Jakarta Expression Language 4.0 includes APIs for using Jakarta Expression Language in a stand-alone environment.</p>
 <p>{@link 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.</p>

 <p>{@link jakarta.el.ELManager} provides lower level APIs for managing the Jakarta Expression Language
 parsing and evaluation environment.  It contains a default ELContext {@link jakarta.el.StandardELContext}.</p>

 </body>
 </html>
	<!--

	Copyright (c) 1997, 2020 Oracle and/or its affiliates. All rights reserved.
	Copyright 2004 The Apache Software Foundation

	Licensed under the Apache License, Version 2.0 (the "License");
	you may not use this file except in compliance with the License.
	You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.

	-->

	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<html>
	<head>
	</head>

	<body bgcolor="white">
	Provides the API for <strong>Jakarta Expression Language 4.0</strong>

	<p>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.</p>

	<p>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:

	<ul>
	<li><a href="#Context">Jakarta Expression Language Context</a></li>
	<li><a href="#ExpressionObjects">Expression Objects</a></li>
	<li><a href="#ExpressionCreation">Creation of Expressions</a></li>
	<li><a href="#ExpressionEvaluation">Evaluation of Expressions</a></li>
	<li><a href="#EvaluationListener">Evaluation Listeners</a></li>
	<li><a href="#Resolver">Resolution of Model Objects and their Properties</a></li>
	<li><a href="#Functions">Jakarta Expression Language Functions</a></li>
	<li><a href="#Variables">Jakarta Expression Language Variables</a></li>
	<li><a href="#Standalone">Jakarta Expression Language in Stand-alone environment</a></li>
	</ul>

	<h3><a name="Context">Jakarta Expression Language Context</a></h3>

	<p>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.</p>

	<p>Class {@link 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.
	</p>

	<p>When Jakarta Expression Language is used in a web container, the creation of <code>ELContext
	</code> objects is controlled through the underlying technology.
	For example, in Jakarta Server Pages, the
	<code>JspContext.getELContext()</code> factory method is used. In an
	stand-alone environment, a default {@link jakarta.el.StandardELContext} is
	provided.</p>

	<p>Some technologies provide the ability to add an {@link jakarta.el.ELContextListener}
	so that applications and frameworks can ensure their own context objects
	are attached to any newly created <code>ELContext</code>.</p>

	<h3><a name="ExpressionObjects">Expression Objects</a></h3>

	<p>At the core of the Expression Language is the notion of an <i>expression</i>
	that gets parsed according to the grammar defined by the Expression Language.</p>

	<p>There are two types of expressions defined by Jakarta Expression Language: <i>value expressions</i>
	and <i>method expressions</i>. A {@link jakarta.el.ValueExpression} such as
	<code>"${customer.name}"</code> can be used either
	as an <i>rvalue</i> (return the value associated with property <code>name</code>
	of the model object <code>customer</code>) or as an <i>lvalue</i>
	(set the value of the property <code>name</code> of the model object
	<code>customer</code>).</p>

	<p>A {@link jakarta.el.MethodExpression} such as
	<code>"${handler.process}"</code> makes it possible to invoke a method
	(<code>process</code>) on a specific model object (<code>handler</code>).</p>

	<p>In version 2.2 and later, either type of Jakarta Expression Language expression can represent a method
	invocation, such as <code>${trader.buy("JAVA")}</code>, where the arguments to
	the method invocation are specified in the expression.</p>

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

	<h3><a name="ExpressionCreation">Creation of Expressions</a></h3>

	<p>An expression is created through the {@link jakarta.el.ExpressionFactory} class.
	The factory provides two creation methods; one for each type of expression
	supported by Jakarta Expression Language.</p>

	<p>To create an expression, one must provide an {@link jakarta.el.ELContext},
	a string representing
	the expression, and the expected type (<code>ValueExpression</code>) or signature
	(<code>MethodExpression</code>).

	The <code>ELContext</code> provides the context necessary to parse an expression.
	Specifically, if the expression uses a Jakarta Expression Language function
	(for example <code>${fn:toUpperCase(customer.name)}</code>) or a Jakarta Expression Language
	variable, then {@link jakarta.el.FunctionMapper} and {@link jakarta.el.VariableMapper}
	objects must be available within the <code>ELContext</code> so that Jakarta Expression Language
	functions and Jakarta Expression Language variables are properly mapped.

	<h3><a name="ExpressionEvaluation">Evaluation of Expressions</a></h3>
	<p>The creation and the evaluation of an expression are done in two separate
	steps. At the evaluation of an expression, the {@link jakarta.el.ELContext}
	provides the context necessary to support property and method resolution
	for modal objects.</p>

	<p>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.</p>

	<p>Adding parameters to a <code>ValueExpression</code> further enhances the
	power of deferred expressions. The {@link jakarta.el.LambdaExpression}
	encapsulates such a construct. A <code>LambdaExpression</code> can be
	invoked by supplying the actual parameters at evaluation. It plays
	an important role in the support for collections operators.</p>

	<h3><a name="EvaluationListener">Evaluation Listeners</a></h3>
	<p>By registering {@link jakarta.el.EvaluationListener}s in ELContext, a user can
	receive notifications during the Jakarta Expression Language expression evaluations.
	There are three events that trigger the notification:
	<ul>
	<li>Before evaluation</li>
	<li>After evaluation</li>
	<li>When (base, property) is resolved</li>
	</ul></p>

	<h3><a name="Resolver">Resolution of Model Objects and their Properties</a></h3>

	<p>Through the {@link 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.</p>

	<p>The Jakarta Expression Language API provides implementations of <code>ELResolver</code> supporting
	property resolution for common data types which include arrays
	({@link jakarta.el.ArrayELResolver}), JavaBeans ({@link jakarta.el.BeanELResolver}),
	<code>List</code>s ({@link jakarta.el.ListELResolver}),
	<code>Map</code>s ({@link jakarta.el.MapELResolver}), and
	<code>ResourceBundle</code>s ({@link jakarta.el.ResourceBundleELResolver}).</p>

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

	<h3><a name="Functions">Jakarta Expression Language Functions</a></h3>

	<p>If a Jakarta Expression Language expression uses a function
	(for example <code>${fn:toUpperCase(customer.name)}</code>), then a
	{@link jakarta.el.FunctionMapper} object must also be specified within
	the <code>ELContext</code>.

	The <code>FunctionMapper</code> is responsible to map
	<code>${prefix:name()}</code> style functions to
	static methods that can execute the specified functions.
	</p>

	<h3><a name="Variables">Jakarta Expression Language Variables</a></h3>

	<p>Just like {@link jakarta.el.FunctionMapper} provides
	a flexible mechanism to add functions to Jakarta Expression Language,
	{@link jakarta.el.VariableMapper} provides a flexible mechanism to support the notion of
	<strong>Jakarta Expression Language variables</strong>.
	</p>

	<p>
	A Jakarta Expression Language variable does not directly refer to a model object that can then
	be resolved by an <code>ELResolver</code>. 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.
	</p>

	<p>
	For example, in the following code snippet
	<blockquote>
	<code><h:inputText value="#{handler.customer.name}"/></code>
	</blockquote>

	<code>handler</code> refers to a model object that can be resolved by a Jakarta Expression Language Resolver.
	</p>
	<p>
	However, in this other example:
	<blockquote>
	<pre>
	<c:forEach var="item" items="#{model.list}">
	<h:inputText value="#{item.name}"/>
	</c:forEach>
	</pre>
	</blockquote>

	<code>item</code> 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
	<code>#{model.list}</code>.
	</p>

	<p>
	Assuming that there are three elements in <code>${model.list}</code>, this means
	that for each invocation of <code><h:inputText></code>, the following information
	about <code>item</code> must be preserved in the {@link jakarta.el.VariableMapper}:
	<blockquote>
	first invocation: <code>item</code> maps to first element in <code>${model.list}</code><br>
	second invocation: <code>item</code> maps to second element in <code>${model.list}</code><br>
	third invocation: <code>item</code> maps to third element in <code>${model.list}</code><br>
	</blockquote>
	<p>
	<code>VariableMapper</code> 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.
	</p>

	<h3><a name="Standalone">Jakarta Expression Language in Stand-alone environment</a></h3>
	<p>Jakarta Expression Language 4.0 includes APIs for using Jakarta Expression Language in a stand-alone environment.</p>
	<p>{@link 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.</p>

	<p>{@link jakarta.el.ELManager} provides lower level APIs for managing the Jakarta Expression Language
	parsing and evaluation environment. It contains a default ELContext {@link jakarta.el.StandardELContext}.</p>

	</body>
	</html>