You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
285 lines
12 KiB
285 lines
12 KiB
5 years ago
|
<!--
|
||
|
|
|
||
|
|
DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER.
|
||
|
|
|
||
|
|
Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved.
|
||
|
|
|
||
|
|
The contents of this file are subject to the terms of either the GNU
|
||
|
|
General Public License Version 2 only ("GPL") or the Common Development
|
||
|
|
and Distribution License("CDDL") (collectively, the "License"). You
|
||
|
|
may not use this file except in compliance with the License. You can
|
||
|
|
obtain a copy of the License at
|
||
|
|
https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html
|
||
|
|
or packager/legal/LICENSE.txt. See the License for the specific
|
||
|
|
language governing permissions and limitations under the License.
|
||
|
|
|
||
|
|
When distributing the software, include this License Header Notice in each
|
||
|
|
file and include the License file at packager/legal/LICENSE.txt.
|
||
|
|
|
||
|
|
GPL Classpath Exception:
|
||
|
|
Oracle designates this particular file as subject to the "Classpath"
|
||
|
|
exception as provided by Oracle in the GPL Version 2 section of the License
|
||
|
|
file that accompanied this code.
|
||
|
|
|
||
|
|
Modifications:
|
||
|
|
If applicable, add the following below the License Header, with the fields
|
||
|
|
enclosed by brackets [] replaced by your own identifying information:
|
||
|
|
"Portions Copyright [year] [name of copyright owner]"
|
||
|
|
|
||
|
|
Contributor(s):
|
||
|
|
If you wish your version of this file to be governed by only the CDDL or
|
||
|
|
only the GPL Version 2, indicate your decision by adding "[Contributor]
|
||
|
|
elects to include this software in this distribution under the [CDDL or GPL
|
||
|
|
Version 2] license." If you don't indicate a single choice of license, a
|
||
|
|
recipient has the option to distribute your version of this file under
|
||
|
|
either the CDDL, the GPL Version 2 or to extend the choice of license to
|
||
|
|
its licensees as provided above. However, if you add GPL Version 2 code
|
||
|
|
and therefore, elected the GPL Version 2 license, then the option applies
|
||
|
|
only if the new code is made subject to such option by the copyright
|
||
|
|
holder.
|
||
|
|
|
||
|
|
|
||
|
|
This file incorporates work covered by the following copyright and
|
||
|
|
permission notice:
|
||
|
|
|
||
|
|
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 the <strong>Unified Expression Language 3.0</strong>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>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:
|
||
|
|
|
||
|
|
<ul>
|
||
|
|
<li><a href="#Context">EL 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">EL Functions</a></li>
|
||
|
|
<li><a href="#Variables">EL Variables</a></li>
|
||
|
|
<li><a href="#Standalone">EL in Stand-alone environment</li>
|
||
|
|
</ul>
|
||
|
|
|
||
|
|
<h3><a name="Context">EL Context</a></h3>
|
||
|
|
|
||
|
|
<p>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.</p>
|
||
|
|
|
||
|
|
<p>Class {@link javax.el.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.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>When EL used in a web container, the creation of <code>ELContext
|
||
|
|
</code> objects is controlled through the underlying technology.
|
||
|
|
For example, in JSP, the
|
||
|
|
<code>JspContext.getELContext()</code> factory method is used. In an
|
||
|
|
stand-alone environment, a default {@link javax.el.StandardELContext} is
|
||
|
|
provided.</p>
|
||
|
|
|
||
|
|
<p>Some technologies provide the ability to add an {@link javax.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 the EL: <i>value expressions</i>
|
||
|
|
and <i>method expressions</i>. A {@link javax.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 javax.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 EL expression can represent a method
|
||
|
|
invocation, such as <code>${trader.buy("JAVA")}</code>, where the arugments to
|
||
|
|
the method invocation are specified in the expression.</p>
|
||
|
|
|
||
|
|
<p>All expression classes extend the base class {@link javax.el.Expression}, making them
|
||
|
|
serializable and forcing them to implement <code>equals()</code> and
|
||
|
|
<code>hashCode()</code>. Morevover, each method on these expression classes
|
||
|
|
that actually evaluates an expression receives a parameter
|
||
|
|
of class {@link javax.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 javax.el.ExpressionFactory} class.
|
||
|
|
The factory provides two creation methods; one for each type of expression
|
||
|
|
supported by the EL.</p>
|
||
|
|
|
||
|
|
<p>To create an expression, one must provide an {@link javax.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 an EL function
|
||
|
|
(for example <code>${fn:toUpperCase(customer.name)}</code>) or an
|
||
|
|
EL variable, then
|
||
|
|
{@link javax.el.FunctionMapper} and {@link javax.el.VariableMapper}
|
||
|
|
objects must be available within the <code>ELContext</code> so that EL functions and
|
||
|
|
EL 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 javax.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 JSF request processing life cycle, EL 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 javax.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 javax.el.EvaluationListener}s in ELContext, a user can
|
||
|
|
receive notifications during the EL 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 javax.el.ELResolver} base class, the EL
|
||
|
|
features a pluggable mechanism
|
||
|
|
to resolve model object references as well as properties and method
|
||
|
|
invocations of these objects.</p>
|
||
|
|
|
||
|
|
<p>The EL API provides implementations of <code>ELResolver</code> supporting
|
||
|
|
property resolution for common data types which include
|
||
|
|
arrays ({@link javax.el.ArrayELResolver}), JavaBeans ({@link javax.el.BeanELResolver}), <code>List</code>s ({@link javax.el.ListELResolver}),
|
||
|
|
<code>Map</code>s ({@link javax.el.MapELResolver}), and <code>ResourceBundle</code>s ({@link javax.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">EL Functions</a></h3>
|
||
|
|
|
||
|
|
<p>If an EL expression uses a function
|
||
|
|
(for example <code>${fn:toUpperCase(customer.name)}</code>), then a
|
||
|
|
{@link javax.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">EL Variables</a></h3>
|
||
|
|
|
||
|
|
<p>Just like {@link javax.el.FunctionMapper} provides
|
||
|
|
a flexible mechanism to add functions to the EL, {@link javax.el.VariableMapper}
|
||
|
|
provides a flexible mechanism to support the notion of
|
||
|
|
<strong>EL variables</strong>.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<p>
|
||
|
|
An EL variable does not directly refer to a model object that can then
|
||
|
|
be resolved by an <code>ELResolver</code>. Instead, it refers to an EL
|
||
|
|
expression. The evaluation of that EL expression gives the EL 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 an EL 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 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
|
||
|
|
<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 javax.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 an EL variable to the EL expression from which it gets its value.
|
||
|
|
</p>
|
||
|
|
|
||
|
|
<h3><a name="Standalone">EL in Stand-alone environment</a></h3>
|
||
|
|
<p>EL 3.0 includes APIs for using EL in a stand-alone environment.</p>
|
||
|
|
<p>{@link javax.el.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.</p>
|
||
|
|
|
||
|
|
<p>{@link javax.el.ELManager} provides a lower level APIs for managing the EL
|
||
|
|
parsing and evaluation environment. It contains a default ELContext
|
||
|
|
{@link javax.el.StandardELContext}.</p>
|
||
|
|
|
||
|
|
</body>
|
||
|
|
</html>
|
||
|
|
|