Skip to main content

[el-spec commits] [el-spec~source-code:50] Update javadocs for EDR.

  • From: kchung@...
  • To: commits@...
  • Subject: [el-spec commits] [el-spec~source-code:50] Update javadocs for EDR.
  • Date: Wed, 7 Mar 2012 17:54:28 +0000

Project:    el-spec
Repository: source-code
Revision:   50
Author:     kchung
Date:       2012-03-07 17:54:26 UTC
Link:       

Log Message:
------------
Update javadocs for EDR.



Revisions:
----------
50


Modified Paths:
---------------
trunk/api/src/main/java/javax/el/ELManager.java
trunk/api/src/main/java/javax/el/ELClass.java
trunk/api/src/main/java/javax/el/ExpressionFactory.java
trunk/api/src/main/java/javax/el/StandardELContext.java
trunk/api/src/main/java/javax/el/package.html
trunk/api/src/main/java/javax/el/ELProcessor.java
trunk/api/src/main/java/javax/el/BeanELResolver.java
trunk/api/src/main/java/javax/el/ImportHandler.java
trunk/api/src/main/java/javax/el/BeanNameResolver.java
trunk/api/src/main/java/javax/el/LambdaExpression.java
trunk/api/src/main/java/javax/el/EvaluationListener.java
trunk/api/src/main/java/javax/el/MapELResolver.java
trunk/api/src/main/java/javax/el/BeanNameELResolver.java
trunk/api/src/main/java/javax/el/ELContext.java
trunk/api/src/main/java/javax/el/StaticFieldELResolver.java


Diffs:
------
Index: trunk/api/src/main/java/javax/el/LambdaExpression.java
===================================================================
--- trunk/api/src/main/java/javax/el/LambdaExpression.java      (revision 49)
+++ trunk/api/src/main/java/javax/el/LambdaExpression.java      (revision 50)
@@ -5,9 +5,25 @@
 import java.util.HashMap;
 import java.util.ArrayList;
 
-/*
- * A Lambda expression in EL is a ValueExpression with parameters.  This 
class
- * encapsulats such information.
+/**
+ * <p>Encapsulates a parameterized {@link ValueExpression}.</p>
+ *
+ * <p>A <code>LambdaExpression</code> is a representation of the EL Lambda
+ * expression syntax.  It consists of a list of the formal parameters and a
+ * body, represented by a {@link ValueExpression}.
+ * The body can be any valid <code>Expression</code>, including another
+ * <code>LambdaExpression</code>.</p>
+ * A <code>LambdaExpression</code> is created when an EL expression 
containing
+ * a Lambda expression is evaluated.</p>
+ * <p>A <code>LambdaExpression</code> can be invoked by calling
+ * {@link LambdaExpression#invoke}, with
+ * an {@link javax.el.ELContext} and a list of the actual arguments.  The
+ * evaluation of the <code>ValueExpression</code> in the body uses the
+ * {@link ELContext} to resolve references to the parameters.
+ * The result of the evaluation is returned.</p as the
+ * @see ELContext#getLambdaArgument
+ * @see ELContext#enterLambdaScope
+ * @see ELContext#exitLambdaScope
  */
 
 public class LambdaExpression {
@@ -15,26 +31,34 @@
     private List<String> formalParameters = new ArrayList<String>();
     private ValueExpression expression;
 
+    /**
+     * Creates a new LambdaExpression.
+     * @param formalParameters The list of String representing the formal
+     *        parameters.
+     * @param expression The <code>ValueExpression</code> representing the
+     *        body.
+     */
     public LambdaExpression (List<String> formalParameters,
                              ValueExpression expression) {
         this.formalParameters = formalParameters;
         this.expression = expression;
     }
 
-    /*
+    /**
      * Retrieves the formal parameters of the Lambda expression
-     * @return The list of the parameters
+     * @return The list of the parameter names.
      */
     public List<String> getFormalParameters() {
         return this.formalParameters;
     }
 
-    /*
-     * <p>Invoke the Lambda expression.  The supplied arguments are matched, 
in
+    /**
+     * Invoke the encapsulated Lambda expression.
+     * <p> The supplied arguments are matched, in
      * the same order, to the formal parameters.  If there are more arguments
      * than the formal parameters, the extra arguments are ignored.  If there
-     * are less arguments than the formal parameters, an ELException
-     * is thrown.</p>
+     * are less arguments than the formal parameters, an
+     * <code>ELException</code> is thrown.</p>
      *
      * <p>The actual Lambda arguments are added to the ELContext and are
      * available during the evaluation of the Lambda expression.  They are
@@ -43,6 +67,7 @@
      * @param elContext The ELContext used for the evaluation of the 
expression
      * @param args The arguments for the Lambda expression
      * @return The result of invoking the Lambda expression
+     * @throws ELException if not enough arguments are provided
      */
     public Object invoke(ELContext elContext, Object... args) 
             throws ELException {
@@ -50,7 +75,6 @@
         Map<String, Object> lambdaArgs = new HashMap<String, Object>();
         for (String fParam: formalParameters) {
             if (i >= args.length) {
-                // XXX
                 throw new ELException("Expected Argument " + fParam +
                             " missing in Lambda Expression");
             }
Index: trunk/api/src/main/java/javax/el/BeanELResolver.java
===================================================================
--- trunk/api/src/main/java/javax/el/BeanELResolver.java        (revision 49)
+++ trunk/api/src/main/java/javax/el/BeanELResolver.java        (revision 50)
@@ -121,7 +121,7 @@
     /*
      * Defines a property for a bean.
      */
-    protected final static class BeanProperty {
+    final static class BeanProperty {
 
         private Method readMethod;
         private Method writeMethod;
@@ -154,7 +154,7 @@
     /*
      * Defines the properties for a bean.
      */
-    protected final static class BeanProperties {
+    final static class BeanProperties {
 
         private final Map<String, BeanProperty> propertyMap =
             new HashMap<String, BeanProperty>();
Index: trunk/api/src/main/java/javax/el/BeanNameELResolver.java
===================================================================
--- trunk/api/src/main/java/javax/el/BeanNameELResolver.java    (revision 49)
+++ trunk/api/src/main/java/javax/el/BeanNameELResolver.java    (revision 50)
@@ -3,9 +3,23 @@
 import java.util.Iterator;
 import java.beans.FeatureDescriptor;
 
-/*
- * An ELResolver for resolving user or container managed beans.
- *
+/**
+ * <p>An <code>ELResolver</code> for resolving user or container managed 
beans.</p>
+ * <p>A {@link BeanNameResolver} is required for its proper operation.
+ * The following example creates an <code>ELResolver</code> that 
+ * reoslves the name "bean" to an instance of MyBean.
+ * <blockquote>
+ * <pre>
+ * ELResovler elr = new BeanNameELResolver(new BeanNameResolver {
+ *    public Object getBean(String beanName) {
+ *       if ("bean".equals(beanName))
+ *          return new MyBean();
+ *       return null;
+ *    }
+ * });
+ * </pre>
+ * </blockquote>
+ * </p>
  * @since EL 3.0
  */
 public class BeanNameELResolver extends ELResolver {
@@ -14,7 +28,7 @@
 
     /**
      * Constructor
-     * @param beanNameResolver The beanNameResolver that resolve a bena name.
+     * @param beanNameResolver The {@link BeanNameResolver} that resolves a 
bean name.
      */
     public BeanNameELResolver(BeanNameResolver beanNameResolver) {
         this.beanNameResolver = beanNameResolver;
@@ -90,6 +104,10 @@
         }
 
         if (base == null && property instanceof String) {
+            if (beanNameResolver.isReadOnly((String) property)) {
+                throw new PropertyNotWritableException("The bean " +
+                    property + " is not writable.");
+            }
             Object bean = beanNameResolver.getBean((String) property);
             if (bean != null) {
                 context.setPropertyResolved(true);
Index: trunk/api/src/main/java/javax/el/EvaluationListener.java
===================================================================
--- trunk/api/src/main/java/javax/el/EvaluationListener.java    (revision 49)
+++ trunk/api/src/main/java/javax/el/EvaluationListener.java    (revision 50)
@@ -1,6 +1,13 @@
 package javax.el;
 
-interface EvaluationListener extends java.util.EventListener {
+/**
+ * The listener interface for receiving notification when an
+ * EL expression is evaluated.
+ *
+ * @see EvaluationEvent
+ * @since EL 3.0
+ */
+public interface EvaluationListener extends java.util.EventListener {
 
     /**
      * Receives notification before an EL expression is evaluated
@@ -8,7 +15,7 @@
     void beforeEvaluation(EvaluationEvent ee);
 
     /**
-     * Receives notification before an EL expression is evaluated
+     * Receives notification after an EL expression is evaluated
      */
     void afterEvaluation(EvaluationEvent ee);
 
Index: trunk/api/src/main/java/javax/el/StandardELContext.java
===================================================================
--- trunk/api/src/main/java/javax/el/StandardELContext.java     (revision 49)
+++ trunk/api/src/main/java/javax/el/StandardELContext.java     (revision 50)
@@ -4,8 +4,8 @@
 import java.util.HashMap;
 import java.lang.reflect.Method;
 
-/*
- * A stadard ELContext suitable for use in stand alone EL.
+/**
+ * A stadard ELContext suitable for use in a stand alone environment.
  * This class provides a default implementation of an ELResolver, 
FunctionMapper
  * and a VariableMapper.  
  *
@@ -26,7 +26,7 @@
     private CompositeELResolver customResolvers;
 
     /*
-     * The optional ELResolver implementing the query operators.
+     * The ELResolver implementing the query operators.
      */
     private ELResolver queryOperatorELResolver;
 
@@ -63,14 +63,17 @@
     private Map<String, Object> beans = new HashMap<String, Object>();
 
     /**
-     * Default Constructor
+     * Construct a default ELContext for a stand-alone environment.
+     * @param queryOperatorELResolver The ELResolver for implementing the
+     *     LINQ query operators.  A null indicates that the implementation
+     *     is not supported
      */
     public StandardELContext(ELResolver queryOperatorELResolver) {
         this.queryOperatorELResolver = queryOperatorELResolver;
     }
 
     /**
-     * Construct a StandardELContext from another ELContext
+     * Construct a StandardELContext from another ELContext.
      * @param context The ELContext that acts as a delegate in most cases
      */
     public StandardELContext(ELContext context) {
@@ -107,8 +110,22 @@
     }
 
     /**
-     * Construct (if needed) and return a default ELResolver
-     * Retrieves the <code>ELResolver</code> associated with this context.
+     * Construct (if needed) and return a default ELResolver.
+     * <p>Retrieves the <code>ELResolver</code> associated with this context.
+     * This is a <code>CompositeELResover</code> consists of an ordered list 
of
+     * <code>ELResolver</code>s.
+     * <ol>
+     * <li>A {@link BeanNameELResolver} for beans defined locally</li>
+     * <li>Any custom <code>ELResolver</code>s</li>
+     * <li>An <code>ELResolver</code> implementing the Linq query 
operators</li>
+     * <li>A {@link StaticFieldELResolver} for resolving static fields</li>
+     * <li>A {@link MapELResolver} for resolving Map properties</li>
+     * <li>A {@link ResourceBundleELResolver} for resolving ResourceBundle 
properties</li>
+     * <li>A {@link ListELResolver} for resolving List properties</li>
+     * <li>An {@link ArrayELResolver} for resolving array properties</li>
+     * <li>A {@link BeanELResolver} for resolving bean properties</li>
+     * </ol>
+     * </p>
      * @return The ELResolver for this context.
      */
     @Override
@@ -144,7 +161,7 @@
     }
 
     /**
-     * Construct (if need) and return an ImportHandler {
+     * Construct (if need) and return an ImportHandler
      */
     public ImportHandler getImportHandler() {
         if (importHandler == null) {
@@ -157,7 +174,7 @@
      * Get the local bean repository
      * @return the bean repository
      */
-    public Map<String, Object> getBeans() {
+    Map<String, Object> getBeans() {
         return beans;
     } 
 
@@ -198,7 +215,7 @@
     }
 
     /**
-     * Construct (if needed) and return a default TypeConverter() {
+     * Construct (if needed) and return a default TypeConverter.
      */
     @Override
     public TypeConverter getTypeConverter() {
Index: trunk/api/src/main/java/javax/el/ELClass.java
===================================================================
--- trunk/api/src/main/java/javax/el/ELClass.java       (revision 49)
+++ trunk/api/src/main/java/javax/el/ELClass.java       (revision 50)
@@ -1,8 +1,11 @@
 package javax.el;
 
 /**
- * A runtime representation of the sytax T(full-class-Name).  Used only in
- * StaticFieldELResolver.
+ * <p>A runtime representation of the sytax <code>T(full-class-Name)</code>
+ * that encapsulates the name of the specified class.</p>
+ * 
+ * <p>This class is used only in {@link StaticFieldELResolver} and will
+ * probably only be of interest to EL implementors, and not EL users.
  *
  * @since EL 3.0
  */
@@ -13,14 +16,14 @@
 
     /**
      * Constructor
-     * @param className The name of the class specified in T(...).
+     * @param className The name of the class specified in 
<code>T(...)</code>.
      */
     public ELClass(String className) {
         this.className = className;
     }
 
     /**
-     * Return the class name for the specified class.
+     * Returns the class name for the specified class.
      * @return The class name for the specified class.
      */
     public String getClassName() {
Index: trunk/api/src/main/java/javax/el/ELProcessor.java
===================================================================
--- trunk/api/src/main/java/javax/el/ELProcessor.java   (revision 49)
+++ trunk/api/src/main/java/javax/el/ELProcessor.java   (revision 50)
@@ -3,26 +3,52 @@
 import java.lang.reflect.Method;
 
 /**
- * This class provides an API for using EL stand-alone, outside of a web
- * container.  It provides a direct and simple interface for creating and
- * evaluating EL expressions, while hiding low level details from the users.
- * This API is not indenpendent from the EL 2.2 API, but rather builds
- * on top of it.  
+ * <p>Provides an API for using EL in a stand-alone environment.</p>
  * 
- * This API operates on a level higher that those provided in EL 2.2, in that
- * it hides implementation details (such as ELResolver and ValueExpression)
- * from the users.
+ * <p>This class provides a direct and simple interface for
+ * <ul>
+ *   <li>Evaluating EL expressions.</li>
+ *   <li>Assigning values to beans or setting a bean property.</li>
+ *   <li>Setting a {@link ValueExpression} to a EL variable.</li>
+ *   <li>Defining a static mathod as an EL function.</li>
+ *   <li>Defining an object instance as an EL name.
+ * </ul>
+ * 
+ * <p>This API is not a replacement for the APIs in EL 2.2.  Containers that
+ * maintains EL environments can continue to do so, without using this 
API.</p>
+ * 
+ * <p>For EL users who want to manipulate EL environments, like adding custom
+ * {@link ELResolver}s, {@link ELManager} can be used.</p>
  *
- * The EL processing environment is handled by the use of ELManager.
+ * <h3>Scope and Life Cycle</h3>
+ * <p>Since it maintains the state of the EL environments,
+ * <code>ELProcessor</code> is not thread safe.  In the simplest case,
+ * an instance can be created and destroyed before and after evaluating
+ * EL expressions.  In a more realistic usage, an instance of
+ * <code>ELProcessor</code> can be created and the initialized by an
+ * administrator, and passed to multiple users, on a read-only basis.</p>
  *
- * The EL expressions allowed in the methods getValue, setValue, and 
- * setVariable are limited to non-composite expressions, i.e. expressions
- * of the form ${...} or #{...}.  Also, it is not necessary (in fact not
+ * <h3>Automatic Bracketing of Expressions</h3>
+ * <p>A note about the EL expressions strings used in the class.  The strings
+ * allowed in the methods {@link ELProcessor#getValue},
+ * {@link ELProcessor#setValue}, and {@link ELProcessor#setVariable} are
+ * limited to non-composite expressions, i.e. expressions
+ * of the form ${...} or #{...} only.  Also, it is not necessary (in fact not
  * allowed) to bracket the expression strings with ${ or #{ and } in these
  * methods: they will be automatically bracketed.  This reduces the visual
- * cluster, without lost of functionalities (thanks to the addition of the
+ * cluster, without any lost of functionalities (thanks to the addition of 
the
  * concatenation operator).
  *
+ * <h3>Example</h3>
+ * The following code snippet illustrates the use of ELProcessor to define
+ * a bean and evaluate its property.
+ * <blockquote>
+ * <pre>
+ *   ELProcessor elp = new ELProcessor();
+ *   elp.defineBean("employee", new Employee("Charlie Brown"));
+ *   String name = elp.eval("employee.name");
+ * </pre>
+ * </blockquote>
  * @since EL 3.0
  */
 
@@ -39,17 +65,17 @@
         return elManager;
     }
 
-    /*
-     * Evaluate an EL expression, without coercion.
+    /**
+     * Evaluates an EL expression.
      * @param expression The EL expression to be evaluated.
      * @return The result of the expression evaluation.
      */
-    public Object getValue(String expression) {
+    public Object eval(String expression) {
         return getValue(expression, Object.class);
     }
 
-    /*
-     * Evaluate an EL expression, with coercion.
+    /**
+     * Evaluates an EL expression, and coerces the result to the specified 
type.
      * @param expression The EL expression to be evaluated.
      * @param exprectedType Specifies the type that the resultant evaluation
      *        will be coerced to.
@@ -62,10 +88,13 @@
         return exp.getValue(elManager.getELContext());
     }
 
-    /*
-     * Evaluates the expression, and sets the result to the provided value.
-     * @param expression The expression, to be evaluated.  
-     * @param value The new value to be set.
+    /**
+     * Sets an expression with a new value. 
+     * The target expression is evaluated, up to the last property 
resolution,
+     * and the resultant (base, property) pair is set to the provided value.
+     *
+     * @param expression The target expression
+     * @param value The new value to set.
      * @throws PropertyNotFoundException if one of the property
      *     resolutions failed because a specified variable or property
      *     does not exist or is not readable.
@@ -85,10 +114,11 @@
     }
 
     /**
-     * Assign an EL expression to an EL variable, without evaluation, and
-     * replace any previously assign expression to the same variable.
-     * The assignment for the variable is removed if
-     * the expression is <code>null</code>.
+     * Assign an EL expression to an EL variable.  The expression is parsed,
+     * but not evaluated, and the parsed expression is mapped to the EL
+     * variable in the local variable map.
+     * Any previously assigned expression to the same variable will be 
replaced.
+     * If the expression is <code>null</code>, the variable will be removed.
      * @param var The name of the variable.
      * @param expression The EL expression to be assigned to the variable.
      */
@@ -99,25 +129,26 @@
         elManager.setVariable(var, exp);
     }
 
-    /*
-     * Define an EL function.
-     * @param function The name of the function, with optional namespace 
prefix
-     *    (e.g. "func" or "ns:func").  Can be null or empty (""), in which 
case
-     *    the method name is used as the function name.
-     * @param className The name of the Java class that implements the 
function
+    /**
+     * Define an EL function in the local function mapper.
+     * @param prefix The namespace for the function or "" for no namesapce.
+     * @param function The name of the function.
+     *    If empty (""), the method name is used as the function name.
+     * @param className The full Java class name that implements the 
function.
      * @param method The name (specified without parenthesis) or the 
signature 
-     *    (as in the Java Language Spec) of the method that implements the
-     *    function.  If the name (e.g. "sum") is given, the first declared
+     *    (as in the Java Language Spec) of the static method that implements
+     *    the function.  If the name (e.g. "sum") is given, the first 
declared
      *    method in class that matches the name is selected.  If the 
signature
      *    (e.g. "int sum(int, int)" ) is given, then the declared method
      *    with the signature is selected.
      *    
+     * @throws NullPointerException if any of the arguements is null.
      * @throws ClassNoFoundException if the specified class does not exists.
      * @throws NoSuchMethodException if the method (with or without the
      *    signature) is not a declared method of the class, or if the method
      *    signature is not valid.
      */
-    public void defineFunction(String function,
+    public void defineFunction(String prefix, String function,
                                String className,
                                String method)
             throws ClassNotFoundException, NoSuchMethodException {
@@ -158,25 +189,34 @@
             }
             meth = klass.getDeclaredMethod(methodName, paramTypes);
         }
-        elManager.mapFunction(function, meth);
+        if (function.equals("")) {
+            function = method;
+        }
+        elManager.mapFunction(prefix, function, meth);
     }
 
     /**
-     * Define an EL function
-     * @param function The name of the function, with optional namespace 
prefix
-     *    (e.g. "func" or "ns:func").  Can be null or empty (""), in which 
case
-     *    the method name is used as the function name.
-     * @param method The java.lang.reflect.Method instance of the method that
-     *    implements the function.
+     * Define an EL function in the local function mapper.
+     * @param prefix The namespace for the function or "" for no namesapce.
+     * @param function The name of the function.
+     *    If empty (""), the method name is used as the function name.
+     * @param method The <code>java.lang.reflect.Method</code> instance of
+     *    the method that implements the function.
+     * @throws NullPointerException if any of the arguements is null.
      */
-    public void defineFunction(String function, Method method) {
-        elManager.mapFunction(function, method);
+    public void defineFunction(String prefix, String function, Method 
method) {
+        if (function.equals("")) {
+            function = method.getName();
+       }
+        elManager.mapFunction(prefix, function, method);
     }
 
     /**
-     * Define a bean in a local bean repository
+     * Define a bean in a local bean repository, hiding other beans of the
+     * same name.  
      * @param name The name of the bean
-     * @param bean The bean instance to be defined
+     * @param bean The bean instance to be defined.  If <code>null</code>,
+     *   the name will be removed from the local bean repository.
      */
     public void defineBean(String name, Object bean) {
         elManager.defineBean(name, bean);
Index: trunk/api/src/main/java/javax/el/ELContext.java
===================================================================
--- trunk/api/src/main/java/javax/el/ELContext.java     (revision 49)
+++ trunk/api/src/main/java/javax/el/ELContext.java     (revision 50)
@@ -67,23 +67,25 @@
 import java.util.EventListener;
 
 /**
- * Context information for expression evaluation.
+ * Context information for expression parsing and evaluation.
  *
- * <p>To evaluate an {@link Expression}, an <code>ELContext</code> must be
- * provided.  The <code>ELContext</code> holds:
+ * <p>To parse or evaluate an {@link Expression}, an <code>ELContext</code>
+ * must be provided.  The <code>ELContext</code> holds:
  * <ul>
+ *   <li>a reference to {@link FunctionMapper} that will be used
+ *       to resolve EL Functions.  This is used only in parsing.</li>
+ *   <li>a reference to {@link VariableMapper} that will be used
+ *       to resolve EL Variables.  This is used only in parsing.</li>
  *   <li>a reference to the base {@link ELResolver} that will be consulted
  *       to resolve model objects and their properties</li>
- *   <li>a reference to {@link ImportHandler} that will be consulted to
- *       to resolve classes that has been imported</li>
- *   <li>a reference to {@link FunctionMapper} that will be used
- *       to resolve EL Functions.
- *   <li>a reference to {@link VariableMapper} that will be used
- *       to resolve EL Variables.
  *   <li>a collection of all the relevant context objects for use by 
  *       <code>ELResolver</code>s</li>
  *   <li>state information during the evaluation of an expression, such as
  *       whether a property has been resolved yet</li>
+ *   <li>a reference to {@link ImportHandler} that will be consulted to
+ *       to resolve classes that have been imported</li>
+ *   <li>a reference to the arguments for the active {@link 
LambdaExpression}s</li>
+ *   <li>a reference to the list of registered listeners</li>
  * </ul></p>
  *
  * <p>The collection of context objects is necessary because each 
@@ -92,13 +94,18 @@
  * {@link javax.servlet.jsp.JspContext} and a
  * {@link javax.faces.context.FacesContext}, respectively.</p>
  *
- * <p>Creation of <code>ELContext</code> objects is controlled through 
+ * <p>When 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.
  * Some technologies provide the ability to add an {@link ELContextListener}
  * so that applications and frameworks can ensure their own context objects
  * are attached to any newly created <code>ELContext</code>.</p>
  *
+ * <p>When used in a stand-alone environment, {@link StandardELContext}
+ * provides a default <code>ELContext</code>, which is managed and be 
modified
+ * by {@link ELManager}.
+ *
  * <p>Because it stores state during expression evaluation, an 
  * <code>ELContext</code> object is not thread-safe.  Care should be taken
  * to never share an <code>ELContext</code> instance between two or more 
@@ -109,8 +116,11 @@
  * @see ELResolver
  * @see FunctionMapper
  * @see VariableMapper
+ * @see ImportHandler
+ * @see LambdaExpression
+ * @see StandardELContext
  * @see javax.servlet.jsp.JspContext
- * @since JSP 2.1
+ * @since EL 2.1 and EL 3.0
  */
 public abstract class ELContext {
 
@@ -250,7 +260,7 @@
     }
 
     /**
-     * Set the <code>Locale</code> for this instance.  This method may be 
+     * Sets the <code>Locale</code> for this instance.  This method may be 
      * called by the party creating the instance, such as JavaServer
      * Faces or JSP, to enable the EL implementation to provide localized
      * messages to the user.  If no <code>Locale</code> is set, the 
implementation
@@ -306,7 +316,7 @@
     }
 
     /**
-     * Retrieve the Lambda argument associated with a formal parameter.
+     * Retrieves the Lambda argument associated with a formal parameter.
      * If the Lambda expression is nested within other Lambda expressions, 
the
      * arguments for the current Lambda expression is first searched, and if
      * not found, the arguments for the immediate nesting Lambda expression
@@ -333,7 +343,7 @@
     }
 
     /**
-     * Install a Lambda argument map, in preparation for the evaluation
+     * Installs a Lambda argument map, in preparation for the evaluation
      * of a Lambda expression.  The arguments in the map will be in scope
      * during the evaluation of the Lambda expression.
      * @param args The Lambda arguments map
@@ -347,8 +357,9 @@
     }
 
     /**
-     * Exit the Lambda expression evaluation. The Lambda argument map that
+     * Exits the Lambda expression evaluation. The Lambda argument map that
      * was previously installed is removed.
+     * @since EL 3.0
      */
     public void exitLambdaScope() {
         if (lambdaArgs != null) {
Index: trunk/api/src/main/java/javax/el/ImportHandler.java
===================================================================
--- trunk/api/src/main/java/javax/el/ImportHandler.java (revision 49)
+++ trunk/api/src/main/java/javax/el/ImportHandler.java (revision 50)
@@ -8,8 +8,8 @@
 /**
  * Handles imports of class names and package names.  An imported package
  * name implicitly imports all the classes in the package.  A class that has
- * been imported can be used without its package name in the syntax element
- * T(name).  The name is resolved to its full (package and class) name
+ * been imported can be used without its package name.
+ * The name is resolved to its full (package and class) name
  * at evaluation time.
  */
 public class ImportHandler {
Index: trunk/api/src/main/java/javax/el/package.html
===================================================================
--- trunk/api/src/main/java/javax/el/package.html       (revision 49)
+++ trunk/api/src/main/java/javax/el/package.html       (revision 50)
@@ -61,21 +61,15 @@
 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
 <head>
-<!--
-FIXME insert copyright
--->
 </head>
 
 <body bgcolor="white">
-Provides the API for the <strong>Unified Expression Language 2.2</strong>
-used by the JSP 2.2 and JSF 2.0 technologies.
+Provides the API for the <strong>Unified Expression Language 3.0</strong>
 
-<p>The Expression Language (EL) is a simple language designed to satisfy
-the specific needs of web application developers. It is currently defined
-in its own specification document within the JavaServer Pages (tm) (JSP) 
-2.2 specification, but does not have any dependencies on any portion 
-of the JSP 2.2 specification. It is intended for general use outside of
-the JSP and JSF specifications as well.</p>
+<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
@@ -85,9 +79,11 @@
   <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="#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>
@@ -104,9 +100,12 @@
 evaluating an expression is specified.
 </p>
 
-<p>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.</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 environemt, 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
@@ -129,7 +128,7 @@
 <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, either type of EL expression can represent a method
+<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 mothod invocation are specified in the expression.</p>
 
@@ -140,7 +139,6 @@
 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.
@@ -159,20 +157,40 @@
 {@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.
-</p>
 
+<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}
+encapsutae 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 LINQ query operators.</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 of these 
objects.</p>
+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>In version 3.0, EL also supports the
+<a href=" http://msdn.microsoft.com/en-us/library/bb394939.aspx";
+LINQ query operators</a> by implementing an ELResolver that resolves methods
+calls to this operators.</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
@@ -244,6 +262,16 @@
 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-aline environment.</p>
+<p>{@link javax.el.ELProcessor} provides simple APIs for the direct
+evluations 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>
 
Index: trunk/api/src/main/java/javax/el/MapELResolver.java
===================================================================
--- trunk/api/src/main/java/javax/el/MapELResolver.java (revision 49)
+++ trunk/api/src/main/java/javax/el/MapELResolver.java (revision 50)
@@ -379,7 +379,9 @@
                 descriptor.setExpert(false);
                 descriptor.setHidden(false);
                 descriptor.setPreferred(true);
-                descriptor.setValue("type", key==null? null: key.getClass());
+                if (key != null) {
+                    descriptor.setValue("type", key.getClass());
+                }
                 descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE);
                 list.add(descriptor);
             }
Index: trunk/api/src/main/java/javax/el/ExpressionFactory.java
===================================================================
--- trunk/api/src/main/java/javax/el/ExpressionFactory.java     (revision 49)
+++ trunk/api/src/main/java/javax/el/ExpressionFactory.java     (revision 50)
@@ -58,13 +58,24 @@
 
 package javax.el;
 
+import java.util.Properties;
+
 /**
- * Parses a <code>String</code> into a {@link ValueExpression} or
- * {@link MethodExpression} instance for later evaluation.
+ * Provides an implementation for creating and evaluating EL expressions.
  *
  * <p>Classes that implement the EL expression language expose their
- * functionality via this abstract class.
- * The {@link #newInstance} method can be used to obtain an
+ * functionality via this abstract class.  An implementation supports the
+ * following functionalities.
+ * <ul>
+ *   <li>
+ *     Parses a <code>String</code> into a {@link ValueExpression} or
+ *     {@link MethodExpression} instance for later evaluation.
+ *   </li>
+ *   <li>Implements an <code>ELResolver</code> for query operators</li>
+ *   <li>Provides a default type coercion</li>
+ * </ul>
+ * </p>
+ * <p>The {@link #newInstance} method can be used to obtain an
  * instance of the implementation.
  * Technologies such as
  * JavaServer Pages and JavaServer Faces provide access to an
@@ -75,10 +86,6 @@
  * The {@link #createMethodExpression} method is used to parse expressions
  * that evaluate to a reference to a method on an object.</p>
  *
- * <p>Unlike previous incarnations of this API, there is no way to parse
- * and evaluate an expression in one single step. The expression needs to 
first
- * be parsed, and then evaluated.</p>
- *
  * <p>Resolution of model objects is performed at evaluation time, via the
  * {@link ELResolver} associated with the {@link ELContext} passed to
  * the <code>ValueExpression</code> or <code>MethodExpression</code>.</p>
@@ -130,8 +137,6 @@
  * @since JSP 2.1
  */
 
-import java.util.Properties;
-
 public abstract class ExpressionFactory {
     
     /**
@@ -328,23 +333,26 @@
             Class<?> targetType);
     
     /**
-     * Retrieves an ELResolver that implements the Query Operators in
-     * LINQ, .NET Language Integrated Query.  For detail, see
-     * http://msdn.microsoft.com/en-us/library/bb394939.aspx
-     * See also EL.x.x for details about how to use these operators in EL.
+     * Retrieves an ELResolver that implements the Query Operators
+     * as described in Chapter 2 of the specification.
      *
-     * This ELResolver relosves the method invocation on (base, property)
-     * when base is an Iterable and property is the name of the operator,
-     * so they acts like built-in methods of Iterables.
-     * See EL.x.x for detailed descriptions on the arguments types, and the
-     * return values of these operators.
+     * <p>This ELResolver relsoves the method invocation on the pair
+     * (<code>base</code>, <code>property</code>) when <code>base</code> is
+     * an <code>Iterable</code> and <code>property</code> is the name of the
+     * operator.  Therefore, the operators behave like built-in methods of
+     * <code>Iterable</code>s.</p>
+     * <p>See EL.2 for detailed descriptions of these operators, the
+     * arguments, and the return values.</p>
      *
-     * @Returns The ELResolver that implements the Query Operators.  If null,
-     *     the query operators are not support by this implementation.
+     * @return The <code>ELResolver</code> that implements the Query 
Operators.
+     *    If <code>null</code>, the query operators are not support by this
+     *    implementation.
      *
      * @since EL 3.0
      */
-    public abstract ELResolver getQueryOperatorELResolver();
+    public ELResolver getQueryOperatorELResolver() {
+        return null;
+    }
 }
 
 
Index: trunk/api/src/main/java/javax/el/BeanNameResolver.java
===================================================================
--- trunk/api/src/main/java/javax/el/BeanNameResolver.java      (revision 49)
+++ trunk/api/src/main/java/javax/el/BeanNameResolver.java      (revision 50)
@@ -1,15 +1,17 @@
 package javax.el;
 
-/*
+/**
+ * Resolves a bean by its known name.
  * This class can be extended to return a bean object given its name,
  * or to set a value to an existing bean.
+ * @see BeanNameELResolver
  *
  * @since EL 3.0
  */
-abstract class BeanNameResolver {
-    /*
-     * Return the bean known by its name
-     * @param beanName The name of the bean
+public abstract class BeanNameResolver {
+    /**
+     * Returns the bean known by its name.
+     * @param beanName The name of the bean.
      * @return The bean with the given name.  A <code>null</code> indicates
      *     that a bean with the given name is not found.
      */
@@ -17,8 +19,8 @@
         return null;
     }
 
-    /*
-     * Set a value to an existing bean of the given name.
+    /**
+     * Sets a value to an existing bean of the given name.
      * @param beanName The name of the bean
      * @param value The new bean for the given name.
      * @throws PropertyNotWritableException if setting a new bean for the 
given
@@ -29,10 +31,10 @@
         throw new PropertyNotWritableException();
     }
 
-    /*
+    /**
      * Indicates if the bean of the given name is read-only or writable
      * @param beanName The name of the bean
-     * @return <code>true </code> if a new bean can be set for the given 
name.
+     * @return <code>true</code> if a new bean can be set for the given name.
      *    <code>false</code> otherwise.
      */
     public boolean isReadOnly(String beanName) {
Index: trunk/api/src/main/java/javax/el/ELManager.java
===================================================================
--- trunk/api/src/main/java/javax/el/ELManager.java     (revision 49)
+++ trunk/api/src/main/java/javax/el/ELManager.java     (revision 50)
@@ -2,14 +2,11 @@
 
 import java.lang.reflect.Method;
 
-/*
- * Manages EL parsing and evaluation enviroment.  The ELManager maintains an
- * instance of ELContext and ExpressionFactory, for parsing and evaluating EL
- * expressions.  Both can be replaced.
+/**
+ * <p>Manages EL parsing and evaluation enviroment.  The ELManager maintains 
an
+ * instance of ExpressionFactory and StandardELContext, for
+ * parsing and evaluating EL expressions.</p>
  *
- * The ELManager manages the EL vironment and handles adding an ELResolver,
- * defining a function, and setting of a variable.
- *
  * @since EL 3.0
  */
 public class ELManager {
@@ -18,7 +15,8 @@
     private StandardELContext elContext;
 
     /**
-     * Return the ExpressionFactory instance used for EL evaluations
+     * Return the ExpressionFactory instance used for EL evaluations.  If
+     * there is currently no ExpressionFactory, an instance is created.
      * @return The ExpressionFactory
      */
     public ExpressionFactory getExpressionFactory() {
@@ -30,6 +28,9 @@
 
     /**
      * Return the ELContext used for parsing and evaluating EL expressions.
+     * If there is currently no ELContext, a default instance of
+     * StandardELContext is returned.
+     *
      * @return The ELContext used for parsing and evaluating EL expressions..
      */
     public StandardELContext getELContext() {
@@ -42,7 +43,8 @@
 
     /**
      * Set the ELContext used for parsing and evaluating EL expressions.
-     * The supplied EL will not be modified, except for the context object 
map.
+     * The supplied ELContext will not be modified, except for the context
+     * object map.
      * @param context The new ELContext.
      * @return The previous ELContext, null if none.
      */
@@ -54,8 +56,9 @@
 
     /**
      * Register a BeanNameResolver.
-     * Implicitly adds a BeanNameELResolver to the list of ELResolvers
-     * Once reigstered, it cannot be removed.
+     * Construct a BeanNameELResolver with the BeanNameResolver and add it
+     * to the list of ELResolvers.
+     * Once reigstered, the BeanNameResolver cannot be removed.
      * @param bnr The BeanNameResolver to be registered.
      */
     public void addBeanNameResolver(BeanNameResolver bnr) {
@@ -63,36 +66,32 @@
     }
 
     /**
-     * Add an user defined ELResolver to the currect list of ELResolvers
-     * Can be called multiple times with additive effect.
+     * Add an user defined ELResolver to the list of ELResolvers.
+     * Can be called multiple times.  The new ELResolver is
+     * placed ahead of the default ELResolvers.  The list of the ELResolvers
+     * added this way are ordered chronologically.
+     * 
      * @param elr The ELResolver to be added to the list of ELResolvers in
      *     ELContext.
+     * @see StandardELResolver#addELResolver
      */
     public void addELResolver(ELResolver elr) {
         getELContext().addELResolver(elr);
     }
 
     /**
-     * Maps a static method to an EL function
-     * @param function The name of the function
+     * Maps a static method to an EL function.
+     * @param prefix The namespace of the functions, can be "".
+     * @param function The name of the function.  
      * @param meth The static method to be invoked when the function is used.
      */
-    public void mapFunction(String function, Method meth) {
-        int i = function.indexOf(':');
-        String prefix, localName;
-        if (i < 0) {
-            prefix = "";
-            localName = function;
-        } else {
-            prefix = function.substring(0, i);
-            localName = function.substring(i+1);
-        }
-        getELContext().getFunctionMapper().mapFunction(prefix, localName, 
meth);
+    public void mapFunction(String prefix, String function, Method meth) {
+        getELContext().getFunctionMapper().mapFunction(prefix, function, 
meth);
     }
 
     /** 
      * Assign a ValueExpression to an EL variable, replacing
-     * any previously assignment to the same variable.
+     * any previous assignment to the same variable.
      * The assignment for the variable is removed if
      * the expression is <code>null</code>.
      *
@@ -105,7 +104,8 @@
     }
 
     /**
-     * Import a class.
+     * Import a class.  The imported class must be loadable from the
+     * classloader, at class resolution time.
      * @param className The full class name of the class to be imported
      * @throws ELException if the name is not a full class name.
      */
@@ -114,7 +114,10 @@
     }
 
     /**
-     * Import all the classes in a package.
+     * Import a package.  At the class resolution time, the imported package
+     * name will be used to construct the full class name, which will then be
+     * used to load the class.  Inherently, this is less efficient than
+     * importing a class.
      * @param packageName The package name to be imported
      */
     public void importPackage(String packageName) {
@@ -144,7 +147,8 @@
     }
 
     /**
-     * Register a listener.
+     * Register a listener.  Used only for {@link EvaluationListener}s in
+     * 3.0, but possibly to used for other listeners.
      *
      * @param listener The listener to be added.
      */
Index: trunk/api/src/main/java/javax/el/StaticFieldELResolver.java
===================================================================
--- trunk/api/src/main/java/javax/el/StaticFieldELResolver.java (revision 49)
+++ trunk/api/src/main/java/javax/el/StaticFieldELResolver.java (revision 50)
@@ -8,29 +8,35 @@
 
 import java.beans.FeatureDescriptor;
 
-/*
- * An ELResolver for resolving static fields (including enum constants) and 
- * methods.  Also handles constructor call as a special case.
+/**
+ * <p>An {@link ELResolver} for resolving static fields, enum constants and 
+ * methods.  Also handles constructor calls as a special case.</p>
+ * <p>The resolver handles base objects of the type {@link ELClass}, which
+ * is usually generated by an EL implementation.</p>
  *
+ * @see ELClass
  * @since EL 3.0
  */
 public class StaticFieldELResolver extends ELResolver {
 
     /**
-     * If the base object is an instance of <code>ELClass</code>and the
+     * <p>Returns the value of a static field.</p>
+     * <p>If the base object is an instance of <code>ELClass</code> and the
      * property is String, the
      * <code>propertyResolved</code> property of the <code>ELContext</code>
      * object must be set to <code>true</code> by this resolver, before
      * returning. If this property is not <code>true</code> after this
      * method is called, the caller should ignore the return value.</p>
      *
-     * If the property is the string "class", return the java.lang.Class 
-     * instance of the class specified in ELClass.
+     * <p>If the property is the string "class", return the
+     * <code>java.lang.Class</code> instance of the class specified in
+     * <code>ELClass</code>.
      * If the property is a public static field of class specified in
-     * ELClass, return the value of the static field.  A Enum constant is a
-     * public static field of a Enum object, and is a special case of this.
+     * <code>ELClass</code>, return the value of the static field.
+     * A Enum constant is a
+     * public static field of an Enum object, and is a special case of this.
      * @param context The context of this evaluation.
-     * @param base <code>null</code>
+     * @param base An <code>ELClass</code>.
      * @param property The string "class", or a static field name.
      * @return If the <code>propertyResolved</code> property of
      *     <code>ELContext</code> was set to <code>true</code>, then the 
Class
@@ -72,26 +78,17 @@
     }
 
     /**
-     * If the base object is an instance of <code>ELClass</code>and the
-     * property is String, the
-     * <code>propertyResolved</code> property of the <code>ELContext</code>
-     * object must be set to <code>true</code> by this resolver, before
-     * returning. If this property is not <code>true</code> after this
-     * method is called, the caller should ignore the return value.</p>
-     *
-     * If the property string is a public static and non-final field of the
-     * class specified in ELClass, the field is set to the given value.
+     * <p> Attempts to write to a static field.</p>
+     * <p>If the base object is an instance of <code>ELClass</code>and the
+     * property is String, a <code>PropertyNotWritableException</code>
+     * will always be thrown, because writing to a static field is not
+     * allowed.
      * @param context The context of this evaluation.
-     * @param base <code>null</code>
+     * @param base An <code>ELClass</code>
      * @param property The name of the field
      * @param value The value to set the field of the class to.
      * @throws NullPointerException if context is <code>null</code>
-     * @throws PropertyNotWritableException if field is not a public static
-     *         non-final filed of the class, or if the field is inacessible.
-     * @throws ELException if an exception was thrown while attempting to
-     *     set the bean with the given name.  The thrown exception
-     *     must be included as the cause property of this exception, if
-     *     available.
+     * @throws PropertyNotWritableException
      */
     @Override
     public void setValue(ELContext context, Object base, Object property,
@@ -102,17 +99,6 @@
         if (base instanceof ELClass  && property instanceof String) {
             Class<?> klass = getClassClass(context, (ELClass)base);
             String fieldName = (String) property;
-            try {
-                context.setPropertyResolved(true);
-                Field field = klass.getField(fieldName);
-                int mod = field.getModifiers();
-                if (Modifier.isPublic(mod) && Modifier.isStatic(mod) &&
-                        ! Modifier.isFinal(mod)) {
-                    field.set(null, value);
-                }
-            } catch (NoSuchFieldException ex) {
-            } catch (IllegalAccessException ex) {
-            }
             throw new PropertyNotWritableException(
                         ELUtil.getExceptionMessageString(context,
                             "staticFieldWriteErr
[truncated due to length]



[el-spec commits] [el-spec~source-code:50] Update javadocs for EDR.

kchung 03/07/2012
 
 
Close
loading
Please Confirm
Close