[jbossweb-commits] JBossWeb SVN: r1244 - in trunk: java/javax/el and 3 other directories.

Author: remy.maucherat(a)jboss.com Date: 2009-11-05 11:28:02 -0500 (Thu, 05 Nov 2009) New Revision: 1244 Added: trunk/java/javax/el/ELUtil.java trunk/java/javax/el/FactoryFinder.java trunk/java/javax/el/PrivateMessages.properties trunk/java/javax/el/ValueReference.java trunk/java/javax/el/package.html Removed: trunk/java/javax/el/LocalStrings.properties trunk/java/javax/el/LocalStrings_es.properties Modified: trunk/build.xml trunk/java/javax/el/ArrayELResolver.java trunk/java/javax/el/BeanELResolver.java trunk/java/javax/el/CompositeELResolver.java trunk/java/javax/el/ELContext.java trunk/java/javax/el/ELContextEvent.java trunk/java/javax/el/ELContextListener.java trunk/java/javax/el/ELException.java trunk/java/javax/el/ELResolver.java trunk/java/javax/el/Expression.java trunk/java/javax/el/ExpressionFactory.java trunk/java/javax/el/FunctionMapper.java trunk/java/javax/el/ListELResolver.java trunk/java/javax/el/MapELResolver.java trunk/java/javax/el/MethodExpression.java trunk/java/javax/el/MethodInfo.java trunk/java/javax/el/MethodNotFoundException.java trunk/java/javax/el/PropertyNotFoundException.java trunk/java/javax/el/PropertyNotWritableException.java trunk/java/javax/el/ResourceBundleELResolver.java trunk/java/javax/el/ValueExpression.java trunk/java/javax/el/VariableMapper.java trunk/java/javax/servlet/jsp/ErrorData.java trunk/java/javax/servlet/jsp/HttpJspPage.java trunk/java/javax/servlet/jsp/JspApplicationContext.java trunk/java/javax/servlet/jsp/JspContext.java trunk/java/javax/servlet/jsp/JspEngineInfo.java trunk/java/javax/servlet/jsp/JspException.java trunk/java/javax/servlet/jsp/JspFactory.java trunk/java/javax/servlet/jsp/JspPage.java trunk/java/javax/servlet/jsp/JspTagException.java trunk/java/javax/servlet/jsp/JspWriter.java trunk/java/javax/servlet/jsp/PageContext.java trunk/java/javax/servlet/jsp/SkipPageException.java trunk/java/javax/servlet/jsp/el/ELException.java trunk/java/javax/servlet/jsp/el/ELParseException.java trunk/java/javax/servlet/jsp/el/Expression.java trunk/java/javax/servlet/jsp/el/ExpressionEvaluator.java trunk/java/javax/servlet/jsp/el/FunctionMapper.java trunk/java/javax/servlet/jsp/el/ImplicitObjectELResolver.java trunk/java/javax/servlet/jsp/el/ScopedAttributeELResolver.java trunk/java/javax/servlet/jsp/el/VariableResolver.java trunk/java/javax/servlet/jsp/el/package.html trunk/java/javax/servlet/jsp/package.html trunk/java/javax/servlet/jsp/tagext/BodyContent.java trunk/java/javax/servlet/jsp/tagext/BodyTag.java trunk/java/javax/servlet/jsp/tagext/BodyTagSupport.java trunk/java/javax/servlet/jsp/tagext/DynamicAttributes.java trunk/java/javax/servlet/jsp/tagext/FunctionInfo.java trunk/java/javax/servlet/jsp/tagext/IterationTag.java trunk/java/javax/servlet/jsp/tagext/JspFragment.java trunk/java/javax/servlet/jsp/tagext/JspIdConsumer.java trunk/java/javax/servlet/jsp/tagext/JspTag.java trunk/java/javax/servlet/jsp/tagext/PageData.java trunk/java/javax/servlet/jsp/tagext/SimpleTag.java trunk/java/javax/servlet/jsp/tagext/SimpleTagSupport.java trunk/java/javax/servlet/jsp/tagext/Tag.java trunk/java/javax/servlet/jsp/tagext/TagAdapter.java trunk/java/javax/servlet/jsp/tagext/TagAttributeInfo.java trunk/java/javax/servlet/jsp/tagext/TagData.java trunk/java/javax/servlet/jsp/tagext/TagExtraInfo.java trunk/java/javax/servlet/jsp/tagext/TagFileInfo.java trunk/java/javax/servlet/jsp/tagext/TagInfo.java trunk/java/javax/servlet/jsp/tagext/TagLibraryInfo.java trunk/java/javax/servlet/jsp/tagext/TagLibraryValidator.java trunk/java/javax/servlet/jsp/tagext/TagSupport.java trunk/java/javax/servlet/jsp/tagext/TagVariableInfo.java trunk/java/javax/servlet/jsp/tagext/TryCatchFinally.java trunk/java/javax/servlet/jsp/tagext/ValidationMessage.java trunk/java/javax/servlet/jsp/tagext/VariableInfo.java trunk/java/javax/servlet/jsp/tagext/package.html Log: - Update JSP and EL API. - Skip resources from JBoss JARs. Modified: trunk/build.xml =================================================================== --- trunk/build.xml 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/build.xml 2009-11-05 16:28:02 UTC (rev 1244) @@ -601,15 +601,43 @@ </fileset> </jar> - <copy file="${jasper-jdt.jar}" todir="${tomcat.jars}" /> - <copy todir="${tomcat.jars}"> - <fileset dir="${tomcat.build}/lib"> - <include name="el-api.jar"/> - <include name="jsp-api.jar"/> - <include name="servlet-api.jar"/> + <!-- Servlet 3.0 Implementation JAR File --> + <jar jarfile="${tomcat.jars}/servlet-api.jar"> + <fileset dir="${tomcat.classes}"> + <include name="javax/servlet/*" /> + <include name="javax/servlet/annotation/*" /> + <include name="javax/servlet/descriptor/*" /> + <include name="javax/servlet/http/*" /> + <!-- Javadoc and i18n exclusions --> + <exclude name="**/package.html" /> + <exclude name="**/LocalStrings_*" /> </fileset> - </copy> + </jar> + <!-- JSP 2.2 Implementation JAR File --> + <jar jarfile="${tomcat.jars}/jsp-api.jar"> + <fileset dir="${tomcat.classes}"> + <include name="javax/servlet/jsp/*" /> + <include name="javax/servlet/jsp/el/*" /> + <include name="javax/servlet/jsp/tagext/*" /> + <!-- Javadoc and i18n exclusions --> + <exclude name="**/package.html" /> + <exclude name="**/LocalStrings_*" /> + </fileset> + </jar> + + <!-- EL Implementation JAR File --> + <jar jarfile="${tomcat.jars}/el-api.jar"> + <fileset dir="${tomcat.classes}"> + <include name="javax/el/*" /> + <!-- Javadoc and i18n exclusions --> + <exclude name="**/package.html" /> + <exclude name="**/LocalStrings_*" /> + </fileset> + </jar> + + <copy file="${jasper-jdt.jar}" todir="${tomcat.jars}" /> + <!-- Create a source jar of the jbossweb/servlet classes --> <zip destfile="${tomcat.jars}/jbossweb-src.zip"> <fileset dir="${basedir}/java"> Modified: trunk/java/javax/el/ArrayELResolver.java =================================================================== --- trunk/java/javax/el/ArrayELResolver.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/ArrayELResolver.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,159 +1,382 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; -import java.beans.FeatureDescriptor; import java.lang.reflect.Array; -import java.util.Arrays; +import java.util.List; import java.util.Iterator; +import java.beans.FeatureDescriptor; +/** + * Defines property resolution behavior on arrays. + * + * <p>This resolver handles base objects that are Java language arrays. + * It accepts any object as a property and coerces that object into an + * integer index into the array. The resulting value is the value in the array + * at that index.</p> + * + * <p>This resolver can be constructed in read-only mode, which means that + * {@link #isReadOnly} will always return <code>true</code> and + * {@link #setValue} will always throw + * <code>PropertyNotWritableException</code>.</p> + * + * <p><code>ELResolver</code>s are combined together using + * {@link CompositeELResolver}s, to define rich semantics for evaluating + * an expression. See the javadocs for {@link ELResolver} for details.</p> + * + * @see CompositeELResolver + * @see ELResolver + * @since JSP 2.1 + */ public class ArrayELResolver extends ELResolver { - private final boolean readOnly; + /** + * Creates a new read/write <code>ArrayELResolver</code>. + */ + public ArrayELResolver() { + this.isReadOnly = false; + } - public ArrayELResolver() { - this.readOnly = false; - } + /** + * Creates a new <code>ArrayELResolver</code> whose read-only status is + * determined by the given parameter. + * + * @param isReadOnly <code>true</code> if this resolver cannot modify + * arrays; <code>false</code> otherwise. + */ + public ArrayELResolver(boolean isReadOnly) { + this.isReadOnly = isReadOnly; + } - public ArrayELResolver(boolean readOnly) { - this.readOnly = readOnly; - } + /** + * If the base object is an array, returns the most general acceptable type + * for a value in this array. + * + * <p>If the base is a <code>array</code>, 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> + * + * <p>Assuming the base is an <code>array</code>, this method will always + * return <code>base.getClass().getComponentType()</code>, which is + * the most general type of component that can be stored at any given + * index in the array.</p> + * + * @param context The context of this evaluation. + * @param base The array to analyze. Only bases that are Java language + * arrays are handled by this resolver. + * @param property The index of the element in the array to return the + * acceptable type for. Will be coerced into an integer, but + * otherwise ignored by this resolver. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the most general acceptable type; otherwise undefined. + * @throws PropertyNotFoundException if the given index is out of + * bounds for this array. + * @throws NullPointerException if context is <code>null</code> + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Class<?> getType(ELContext context, + Object base, + Object property) { - public Object getValue(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + if (context == null) { + throw new NullPointerException(); + } - if (base != null && base.getClass().isArray()) { - context.setPropertyResolved(true); - int idx = coerce(property); - if (idx < 0 || idx >= Array.getLength(base)) { - return null; - } else { - return Array.get(base, idx); + if (base != null && base.getClass().isArray()) { + context.setPropertyResolved(true); + int index = toInteger (property); + if (index < 0 || index >= Array.getLength(base)) { + throw new PropertyNotFoundException(); } - } + return base.getClass().getComponentType(); + } + return null; + } - return null; - } + /** + * If the base object is a Java language array, returns the value at the + * given index. The index is specified by the <code>property</code> + * argument, and coerced into an integer. If the coercion could not be + * performed, an <code>IllegalArgumentException</code> is thrown. If the + * index is out of bounds, <code>null</code> is returned. + * + * <p>If the base is a Java language array, 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> + * + * @param context The context of this evaluation. + * @param base The array to analyze. Only bases that are Java language + * arrays are handled by this resolver. + * @param property The index of the value to be returned. Will be coerced + * into an integer. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the value at the given index or <code>null</code> + * if the index was out of bounds. Otherwise, undefined. + * @throws IllegalArgumentException if the property could not be coerced + * into an integer. + * @throws NullPointerException if context is <code>null</code>. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Object getValue(ELContext context, + Object base, + Object property) { - public Class<?> getType(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + if (context == null) { + throw new NullPointerException(); + } - if (base != null && base.getClass().isArray()) { - context.setPropertyResolved(true); - int idx = coerce(property); - checkBounds(base, idx); - return base.getClass().getComponentType(); - } + if (base != null && base.getClass().isArray()) { + context.setPropertyResolved(true); + int index = toInteger (property); + if (index >= 0 && index < Array.getLength(base)) { + return Array.get(base, index); + } + } + return null; + } - return null; - } + /** + * If the base object is a Java language array, attempts to set the + * value at the given index with the given value. The index is specified + * by the <code>property</code> argument, and coerced into an integer. + * If the coercion could not be performed, an + * <code>IllegalArgumentException</code> is thrown. If the index is + * out of bounds, a <code>PropertyNotFoundException</code> is thrown. + * + * <p>If the base is a Java language array, 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 can safely assume no value was set.</p> + * + * <p>If this resolver was constructed in read-only mode, this method will + * always throw <code>PropertyNotWritableException</code>.</p> + * + * @param context The context of this evaluation. + * @param base The array to be modified. Only bases that are Java language + * arrays are handled by this resolver. + * @param property The index of the value to be set. Will be coerced + * into an integer. + * @param val The value to be set at the given index. + * @throws ClassCastException if the class of the specified element + * prevents it from being added to this array. + * @throws NullPointerException if context is <code>null</code>. + * @throws IllegalArgumentException if the property could not be coerced + * into an integer, or if some aspect of the specified element + * prevents it from being added to this array. + * @throws PropertyNotWritableException if this resolver was constructed + * in read-only mode. + * @throws PropertyNotFoundException if the given index is out of + * bounds for this array. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public void setValue(ELContext context, + Object base, + Object property, + Object val) { - public void setValue(ELContext context, Object base, Object property, - Object value) throws NullPointerException, - PropertyNotFoundException, PropertyNotWritableException, - ELException { - if (context == null) { - throw new NullPointerException(); - } + if (context == null) { + throw new NullPointerException(); + } - if (base != null && base.getClass().isArray()) { - context.setPropertyResolved(true); + if (base != null && base.getClass().isArray()) { + context.setPropertyResolved(true); + if (isReadOnly) { + throw new PropertyNotWritableException(); + } + Class<?> type = base.getClass().getComponentType(); + if (val != null && ! type.isAssignableFrom(val.getClass())) { + throw new ClassCastException(); + } + int index = toInteger (property); + if (index < 0 || index >= Array.getLength(base)) { + throw new PropertyNotFoundException(); + } + Array.set(base, index, val); + } + } - if (this.readOnly) { - throw new PropertyNotWritableException(message(context, - "resolverNotWriteable", new Object[] { base.getClass() - .getName() })); - } + /** + * If the base object is a Java language array, returns whether a call to + * {@link #setValue} will always fail. + * + * <p>If the base is a Java language array, 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> + * + * <p>If this resolver was constructed in read-only mode, this method will + * always return <code>true</code>. Otherwise, it returns + * <code>false</code>.</p> + * + * @param context The context of this evaluation. + * @param base The array to analyze. Only bases that are a Java language + * array are handled by this resolver. + * @param property The index of the element in the array to return the + * acceptable type for. Will be coerced into an integer, but + * otherwise ignored by this resolver. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>true</code> if calling the <code>setValue</code> method + * will always fail or <code>false</code> if it is possible that + * such a call may succeed; otherwise undefined. + * @throws PropertyNotFoundException if the given index is out of + * bounds for this array. + * @throws NullPointerException if context is <code>null</code> + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public boolean isReadOnly(ELContext context, + Object base, + Object property) { - int idx = coerce(property); - checkBounds(base, idx); - Array.set(base, idx, value); - } - } + if (context == null) { + throw new NullPointerException(); + } - public boolean isReadOnly(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + if (base != null && base.getClass().isArray()) { + context.setPropertyResolved(true); + int index = toInteger (property); + if (index < 0 || index >= Array.getLength(base)) { + throw new PropertyNotFoundException(); + } + } + return isReadOnly; + } - if (base != null && base.getClass().isArray()) { - context.setPropertyResolved(true); - int idx = coerce(property); - checkBounds(base, idx); - } + /** + * Always returns <code>null</code>, since there is no reason to + * iterate through set set of all integers. + * + * <p>The {@link #getCommonPropertyType} method returns sufficient + * information about what properties this resolver accepts.</p> + * + * @param context The context of this evaluation. + * @param base The array to analyze. Only bases that are a Java language + * array are handled by this resolver. + * @return <code>null</code>. + */ + public Iterator<FeatureDescriptor> getFeatureDescriptors( + ELContext context, + Object base) { + return null; + } - return this.readOnly; - } + /** + * If the base object is a Java language array, returns the most general + * type that this resolver accepts for the <code>property</code> argument. + * Otherwise, returns <code>null</code>. + * + * <p>Assuming the base is an array, this method will always return + * <code>Integer.class</code>. This is because arrays accept integers + * for their index.</p> + * + * @param context The context of this evaluation. + * @param base The array to analyze. Only bases that are a Java language + * array are handled by this resolver. + * @return <code>null</code> if base is not a Java language array; + * otherwise <code>Integer.class</code>. + */ + public Class<?> getCommonPropertyType(ELContext context, + Object base) { - public Iterator<FeatureDescriptor> getFeatureDescriptors(ELContext context, Object base) { - if (base != null && base.getClass().isArray()) { - FeatureDescriptor[] descs = new FeatureDescriptor[Array.getLength(base)]; - for (int i = 0; i < descs.length; i++) { - descs[i] = new FeatureDescriptor(); - descs[i].setDisplayName("["+i+"]"); - descs[i].setExpert(false); - descs[i].setHidden(false); - descs[i].setName(""+i); - descs[i].setPreferred(true); - descs[i].setValue(RESOLVABLE_AT_DESIGN_TIME, Boolean.FALSE); - descs[i].setValue(TYPE, Integer.class); - } - return Arrays.asList(descs).iterator(); - } - return null; - } + if (base != null && base.getClass().isArray()) { + return Integer.class; + } + return null; + } - public Class<?> getCommonPropertyType(ELContext context, Object base) { - if (base != null && base.getClass().isArray()) { - return Integer.class; - } - return null; - } + private int toInteger(Object p) { - private final static void checkBounds(Object base, int idx) { - if (idx < 0 || idx >= Array.getLength(base)) { - throw new PropertyNotFoundException( - new ArrayIndexOutOfBoundsException(idx).getMessage()); - } - } - - private final static int coerce(Object property) { - if (property instanceof Number) { - return ((Number) property).intValue(); - } - if (property instanceof Character) { - return ((Character) property).charValue(); - } - if (property instanceof Boolean) { - return (((Boolean) property).booleanValue() ? 1 : 0); - } - if (property instanceof String) { - return Integer.parseInt((String) property); + if (p instanceof Integer) { + return ((Integer) p).intValue(); } - throw new IllegalArgumentException(property != null ? property - .toString() : "null"); - } + if (p instanceof Character) { + return ((Character) p).charValue(); + } + if (p instanceof Boolean) { + return ((Boolean) p).booleanValue()? 1: 0; + } + if (p instanceof Number) { + return ((Number) p).intValue(); + } + if (p instanceof String) { + return Integer.parseInt((String) p); + } + throw new IllegalArgumentException(); + } + private boolean isReadOnly; } + Modified: trunk/java/javax/el/BeanELResolver.java =================================================================== --- trunk/java/javax/el/BeanELResolver.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/BeanELResolver.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,344 +1,743 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; +import java.lang.reflect.InvocationTargetException; +import java.lang.reflect.Method; +import java.lang.reflect.Modifier; +import java.lang.ref.SoftReference; +import java.beans.FeatureDescriptor; import java.beans.BeanInfo; -import java.beans.FeatureDescriptor; -import java.beans.IntrospectionException; import java.beans.Introspector; import java.beans.PropertyDescriptor; -import java.lang.reflect.InvocationTargetException; -import java.lang.reflect.Method; -import java.lang.reflect.Modifier; -import java.util.Arrays; -import java.util.HashMap; +import java.beans.IntrospectionException; import java.util.Iterator; +import java.util.ArrayList; import java.util.Map; -import java.util.WeakHashMap; +import java.util.HashMap; import java.util.concurrent.ConcurrentHashMap; +/** + * Defines property resolution behavior on objects using the JavaBeans + * component architecture. + * + * <p>This resolver handles base objects of any type, as long as the + * base is not <code>null</code>. It accepts any object as a property + * or method, and coerces it to a string. + * + * <p>For property resolution, the + * property string is used to find a JavaBeans compliant property on + * the base object. The value is accessed using JavaBeans getters and setters. + * </p> + * + * <p>For method resolution, the method string is the name + * of the method in the bean. The parameter types can be optionally + * specified to identify the method. If the parameter types are not + * specified, the parameter objects are used in the method resolution. + * </p> + * + * <p>This resolver can be constructed in read-only mode, which means that + * {@link #isReadOnly} will always return <code>true</code> and + * {@link #setValue} will always throw + * <code>PropertyNotWritableException</code>.</p> + * + * <p><code>ELResolver</code>s are combined together using + * {@link CompositeELResolver}s, to define rich semantics for evaluating + * an expression. See the javadocs for {@link ELResolver} for details.</p> + * + * <p>Because this resolver handles base objects of any type, it should + * be placed near the end of a composite resolver. Otherwise, it will + * claim to have resolved a property before any resolvers that come after + * it get a chance to test if they can do so as well.</p> + * + * @see CompositeELResolver + * @see ELResolver + * @since JSP 2.1 + */ public class BeanELResolver extends ELResolver { - private final boolean readOnly; + private boolean isReadOnly; - private final ConcurrentCache<String, BeanProperties> cache = new ConcurrentCache<String, BeanProperties>( - 1000); + private static final int CACHE_SIZE = 1024; + private static final ConcurrentHashMap<Class, BeanProperties> properties = + new ConcurrentHashMap<Class, BeanProperties>(CACHE_SIZE); - public BeanELResolver() { - this.readOnly = false; - } + /* + * Defines a property for a bean. + */ + protected final static class BeanProperty { - public BeanELResolver(boolean readOnly) { - this.readOnly = readOnly; + private Method readMethod; + private Method writeMethod; + private PropertyDescriptor descriptor; + + public BeanProperty(Class<?> baseClass, + PropertyDescriptor descriptor) { + this.descriptor = descriptor; + readMethod = getMethod(baseClass, descriptor.getReadMethod()); + writeMethod = getMethod(baseClass, descriptor.getWriteMethod()); + } + + public Class getPropertyType() { + return descriptor.getPropertyType(); + } + + public boolean isReadOnly() { + return getWriteMethod() == null; + } + + public Method getReadMethod() { + return readMethod; + } + + public Method getWriteMethod() { + return writeMethod; + } } + + /* + * Defines the properties for a bean. + */ + protected final static class BeanProperties { - public Object getValue(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); + private final Map<String, BeanProperty> propertyMap = + new HashMap<String, BeanProperty>(); + + public BeanProperties(Class<?> baseClass) { + PropertyDescriptor[] descriptors; + try { + BeanInfo info = Introspector.getBeanInfo(baseClass); + descriptors = info.getPropertyDescriptors(); + } catch (IntrospectionException ie) { + throw new ELException(ie); + } + for (PropertyDescriptor pd: descriptors) { + propertyMap.put(pd.getName(), + new BeanProperty(baseClass, pd)); + } } - if (base == null || property == null) { - return null; + + public BeanProperty getBeanProperty(String property) { + return propertyMap.get(property); } + } - context.setPropertyResolved(true); - Method m = this.property(context, base, property).read(context); - try { - return m.invoke(base, (Object[]) null); - } catch (IllegalAccessException e) { - throw new ELException(e); - } catch (InvocationTargetException e) { - throw new ELException(message(context, "propertyReadError", - new Object[] { base.getClass().getName(), - property.toString() }), e.getCause()); - } catch (Exception e) { - throw new ELException(e); - } + /** + * Creates a new read/write <code>BeanELResolver</code>. + */ + public BeanELResolver() { + this.isReadOnly = false; } - public Class<?> getType(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { + /** + * Creates a new <code>BeanELResolver</code> whose read-only status is + * determined by the given parameter. + * + * @param isReadOnly <code>true</code> if this resolver cannot modify + * beans; <code>false</code> otherwise. + */ + public BeanELResolver(boolean isReadOnly) { + this.isReadOnly = isReadOnly; + } + + /** + * If the base object is not <code>null</code>, returns the most + * general acceptable type that can be set on this bean property. + * + * <p>If the base is not <code>null</code>, 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> + * + * <p>The provided property will first be coerced to a <code>String</code>. + * If there is a <code>BeanInfoProperty</code> for this property and + * there were no errors retrieving it, the <code>propertyType</code> of + * the <code>propertyDescriptor</code> is returned. Otherwise, a + * <code>PropertyNotFoundException</code> is thrown.</p> + * + * @param context The context of this evaluation. + * @param base The bean to analyze. + * @param property The name of the property to analyze. Will be coerced to + * a <code>String</code>. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the most general acceptable type; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if <code>base</code> is not + * <code>null</code> and the specified property does not exist + * or is not readable. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Class<?> getType(ELContext context, + Object base, + Object property) { + if (context == null) { throw new NullPointerException(); } - if (base == null || property == null) { + + if (base == null || property == null){ return null; } + BeanProperty bp = getBeanProperty(context, base, property); context.setPropertyResolved(true); - return this.property(context, base, property).getPropertyType(); + return bp.getPropertyType(); } - public void setValue(ELContext context, Object base, Object property, - Object value) throws NullPointerException, - PropertyNotFoundException, PropertyNotWritableException, - ELException { + /** + * If the base object is not <code>null</code>, returns the current + * value of the given property on this bean. + * + * <p>If the base is not <code>null</code>, 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> + * + * <p>The provided property name will first be coerced to a + * <code>String</code>. If the property is a readable property of the + * base object, as per the JavaBeans specification, then return the + * result of the getter call. If the getter throws an exception, + * it is propagated to the caller. If the property is not found or is + * not readable, a <code>PropertyNotFoundException</code> is thrown.</p> + * + * @param context The context of this evaluation. + * @param base The bean on which to get the property. + * @param property The name of the property to get. Will be coerced to + * a <code>String</code>. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the value of the given property. Otherwise, undefined. + * @throws NullPointerException if context is <code>null</code>. + * @throws PropertyNotFoundException if <code>base</code> is not + * <code>null</code> and the specified property does not exist + * or is not readable. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Object getValue(ELContext context, + Object base, + Object property) { + if (context == null) { throw new NullPointerException(); } - if (base == null || property == null) { - return; + + if (base == null || property == null){ + return null; } - context.setPropertyResolved(true); - - if (this.readOnly) { - throw new PropertyNotWritableException(message(context, - "resolverNotWriteable", new Object[] { base.getClass() - .getName() })); + BeanProperty bp = getBeanProperty(context, base, property); + Method method = bp.getReadMethod(); + if (method == null) { + throw new PropertyNotFoundException( + ELUtil.getExceptionMessageString(context, + "propertyNotReadable", + new Object[] { base.getClass().getName(), + property.toString()})); } - Method m = this.property(context, base, property).write(context); + Object value; try { - m.invoke(base, value); - } catch (IllegalAccessException e) { - throw new ELException(e); - } catch (InvocationTargetException e) { - throw new ELException(message(context, "propertyWriteError", - new Object[] { base.getClass().getName(), - property.toString() }), e.getCause()); - } catch (Exception e) { - throw new ELException(e); + value = method.invoke(base, new Object[0]); + context.setPropertyResolved(true); + } catch (ELException ex) { + throw ex; + } catch (InvocationTargetException ite) { + throw new ELException(ite.getCause()); + } catch (Exception ex) { + throw new ELException(ex); } + return value; } - public boolean isReadOnly(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { + /** + * If the base object is not <code>null</code>, attempts to set the + * value of the given property on this bean. + * + * <p>If the base is not <code>null</code>, 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 can safely assume no value was set.</p> + * + * <p>If this resolver was constructed in read-only mode, this method will + * always throw <code>PropertyNotWritableException</code>.</p> + * + * <p>The provided property name will first be coerced to a + * <code>String</code>. If property is a writable property of + * <code>base</code> (as per the JavaBeans Specification), the setter + * method is called (passing <code>value</code>). If the property exists + * but does not have a setter, then a + * <code>PropertyNotFoundException</code> is thrown. If the property + * does not exist, a <code>PropertyNotFoundException</code> is thrown.</p> + * + * @param context The context of this evaluation. + * @param base The bean on which to set the property. + * @param property The name of the property to set. Will be coerced to + * a <code>String</code>. + * @param val The value to be associated with the specified key. + * @throws NullPointerException if context is <code>null</code>. + * @throws PropertyNotFoundException if <code>base</code> is not + * <code>null</code> and the specified property does not exist. + * @throws PropertyNotWritableException if this resolver was constructed + * in read-only mode, or if there is no setter for the property. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public void setValue(ELContext context, + Object base, + Object property, + Object val) { + if (context == null) { throw new NullPointerException(); } - if (base == null || property == null) { - return false; + + if (base == null || property == null){ + return; } - context.setPropertyResolved(true); - return this.readOnly - || this.property(context, base, property).isReadOnly(); - } + if (isReadOnly) { + throw new PropertyNotWritableException( + ELUtil.getExceptionMessageString(context, + "resolverNotwritable", + new Object[] { base.getClass().getName() })); + } - public Iterator<FeatureDescriptor> getFeatureDescriptors(ELContext context, Object base) { - if (context == null) { - throw new NullPointerException(); + BeanProperty bp = getBeanProperty(context, base, property); + Method method = bp.getWriteMethod(); + if (method == null) { + throw new PropertyNotWritableException( + ELUtil.getExceptionMessageString(context, + "propertyNotWritable", + new Object[] { base.getClass().getName(), + property.toString()})); } - if (base == null) { - return null; - } - try { - BeanInfo info = Introspector.getBeanInfo(base.getClass()); - PropertyDescriptor[] pds = info.getPropertyDescriptors(); - for (int i = 0; i < pds.length; i++) { - pds[i].setValue(RESOLVABLE_AT_DESIGN_TIME, Boolean.TRUE); - pds[i].setValue(TYPE, pds[i].getPropertyType()); + method.invoke(base, new Object[] {val}); + context.setPropertyResolved(true); + } catch (ELException ex) { + throw ex; + } catch (InvocationTargetException ite) { + throw new ELException(ite.getCause()); + } catch (Exception ex) { + if (null == val) { + val = "null"; } - return Arrays.asList((FeatureDescriptor[]) pds).iterator(); - } catch (IntrospectionException e) { - // + String message = ELUtil.getExceptionMessageString(context, + "setPropertyFailed", + new Object[] { property.toString(), + base.getClass().getName(), val }); + throw new ELException(message, ex); } + } - return null; + /** + * If the base object is not <code>null</code>, invoke the method, with + * the given parameters on this bean. The return value from the method + * is returned. + * + * <p>If the base is not <code>null</code>, 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> + * + * <p>The provided method object will first be coerced to a + * <code>String</code>. The methods in the bean is then examined and + * an attempt will be made to select one for invocation. If no suitable + * can be found, a <code>MethodNotFoundException</code> is thrown. + * + * If the given paramTypes is not <code>null</code>, select the method + * with the given name and parameter types. + * + * Else select the method with the given name that has the same number + * of parameters. If there are more than one such method, the method + * selection process is undefined. + * + * Else select the method with the given name that takes a variable + * number of arguments. + * + * Note the resolution for overloaded methods will likely be clarified + * in a future version of the spec. + * + * The provide parameters are coerced to the correcponding parameter + * types of the method, and the method is then invoked. + * + * @param context The context of this evaluation. + * @param base The bean on which to invoke the method + * @param method The simple name of the method to invoke. + * Will be coerced to a <code>String</code>. If method is + * "&lt;init&gt;"or "&lt;clinit&gt;" a MethodNotFoundException is + * thrown. + * @param paramTypes An array of Class objects identifying the + * method's formal parameter types, in declared order. + * Use an empty array if the method has no parameters. + * Can be <code>null</code>, in which case the method's formal + * parameter types are assumed to be unknown. + * @param params The parameters to pass to the method, or + * <code>null</code> if no parameters. + * @return The result of the method invocation (<code>null</code> if + * the method has a <code>void</code> return type). + * @throws MethodNotFoundException if no suitable method can be found. + * @throws ELException if an exception was thrown while performing + * (base, method) resolution. The thrown exception must be + * included as the cause property of this exception, if + * available. If the exception thrown is an + * <code>InvocationTargetException</code>, extract its + * <code>cause</code> and pass it to the + * <code>ELException</code> constructor. + * @since EL 2.2 + */ + + public Object invoke(ELContext context, + Object base, + Object method, + Class<?>[] paramTypes, + Object[] params) { + + if (base == null || method == null) { + return null; + } + Method m = findMethod(base, method.toString(), paramTypes, params); + Object ret = invokeMethod(m, base, params); + context.setPropertyResolved(true); + return ret; } - public Class<?> getCommonPropertyType(ELContext context, Object base) { + /** + * If the base object is not <code>null</code>, returns whether a call + * to {@link #setValue} will always fail. + * + * <p>If the base is not <code>null</code>, 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 can safely assume no value was set.</p> + * + * <p>If this resolver was constructed in read-only mode, this method will + * always return <code>true</code>.</p> + * + * <p>The provided property name will first be coerced to a + * <code>String</code>. If property is a writable property of + * <code>base</code>, <code>false</code> is returned. If the property is + * found but is not writable, <code>true</code> is returned. If the + * property is not found, a <code>PropertyNotFoundException</code> + * is thrown.</p> + * + * @param context The context of this evaluation. + * @param base The bean to analyze. + * @param property The name of the property to analyzed. Will be coerced to + * a <code>String</code>. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>true</code> if calling the <code>setValue</code> method + * will always fail or <code>false</code> if it is possible that + * such a call may succeed; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if <code>base</code> is not + * <code>null</code> and the specified property does not exist. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public boolean isReadOnly(ELContext context, + Object base, + Object property) { + if (context == null) { throw new NullPointerException(); } - if (base != null) { - return Object.class; + if (base == null || property == null){ + return false; } - return null; + context.setPropertyResolved(true); + if (isReadOnly) { + return true; + } + + BeanProperty bp = getBeanProperty(context, base, property); + return bp.isReadOnly(); } - protected final static class BeanProperties { - private final Map<String, BeanProperty> properties; - - private final Class<?> type; - - public BeanProperties(Class<?> type) throws ELException { - this.type = type; - this.properties = new HashMap<String, BeanProperty>(); - try { - BeanInfo info = Introspector.getBeanInfo(this.type); - PropertyDescriptor[] pds = info.getPropertyDescriptors(); - for (int i = 0; i < pds.length; i++) { - this.properties.put(pds[i].getName(), new BeanProperty( - type, pds[i])); - } - } catch (IntrospectionException ie) { - throw new ELException(ie); - } + /** + * If the base object is not <code>null</code>, returns an + * <code>Iterator</code> containing the set of JavaBeans properties + * available on the given object. Otherwise, returns <code>null</code>. + * + * <p>The <code>Iterator</code> returned must contain zero or more + * instances of {@link java.beans.FeatureDescriptor}. Each info object + * contains information about a property in the bean, as obtained by + * calling the <code>BeanInfo.getPropertyDescriptors</code> method. + * The <code>FeatureDescriptor</code> is initialized using the same + * fields as are present in the <code>PropertyDescriptor</code>, + * with the additional required named attributes "<code>type</code>" and + * "<code>resolvableAtDesignTime</code>" set as follows: + * <dl> + * <li>{@link ELResolver#TYPE} - The runtime type of the property, from + * <code>PropertyDescriptor.getPropertyType()</code>.</li> + * <li>{@link ELResolver#RESOLVABLE_AT_DESIGN_TIME} - <code>true</code>.</li> + * </dl> + * </p> + * + * @param context The context of this evaluation. + * @param base The bean to analyze. + * @return An <code>Iterator</code> containing zero or more + * <code>FeatureDescriptor</code> objects, each representing a property + * on this bean, or <code>null</code> if the <code>base</code> + * object is <code>null</code>. + */ + public Iterator<FeatureDescriptor> getFeatureDescriptors( + ELContext context, + Object base) { + if (base == null){ + return null; } - private BeanProperty get(ELContext ctx, String name) { - BeanProperty property = this.properties.get(name); - if (property == null) { - throw new PropertyNotFoundException(message(ctx, - "propertyNotFound", - new Object[] { type.getName(), name })); - } - return property; + BeanInfo info = null; + try { + info = Introspector.getBeanInfo(base.getClass()); + } catch (Exception ex) { } - - public BeanProperty getBeanProperty(String name) { - return get(null, name); + if (info == null) { + return null; } - - private Class<?> getType() { - return type; + ArrayList<FeatureDescriptor> list = new ArrayList<FeatureDescriptor>( + info.getPropertyDescriptors().length); + for (PropertyDescriptor pd: info.getPropertyDescriptors()) { + pd.setValue("type", pd.getPropertyType()); + pd.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(pd); } + return list.iterator(); } - protected final static class BeanProperty { - private final Class type; + /** + * If the base object is not <code>null</code>, returns the most + * general type that this resolver accepts for the + * <code>property</code> argument. Otherwise, returns <code>null</code>. + * + * <p>Assuming the base is not <code>null</code>, this method will always + * return <code>Object.class</code>. This is because any object is + * accepted as a key and is coerced into a string.</p> + * + * @param context The context of this evaluation. + * @param base The bean to analyze. + * @return <code>null</code> if base is <code>null</code>; otherwise + * <code>Object.class</code>. + */ + public Class<?> getCommonPropertyType(ELContext context, + Object base) { + if (base == null){ + return null; + } - private final Class owner; + return Object.class; + } - private final PropertyDescriptor descriptor; + /* + * Get a public method form a public class or interface of a given method. + * Note that if a PropertyDescriptor is obtained for a non-public class that + * implements a public interface, the read/write methods will be for the + * class, and therefore inaccessible. To correct this, a version of the + * same method must be found in a superclass or interface. + **/ - private Method read; + static private Method getMethod(Class cl, Method method) { - private Method write; - - public BeanProperty(Class<?> owner, PropertyDescriptor descriptor) { - this.owner = owner; - this.descriptor = descriptor; - this.type = descriptor.getPropertyType(); + if (method == null) { + return null; } - public Class getPropertyType() { - return this.type; + if (Modifier.isPublic (cl.getModifiers ())) { + return method; } - - public boolean isReadOnly() { - return this.write == null - && (null == (this.write = getMethod(this.owner, descriptor.getWriteMethod()))); + Class [] interfaces = cl.getInterfaces (); + for (int i = 0; i < interfaces.length; i++) { + Class c = interfaces[i]; + Method m = null; + try { + m = c.getMethod(method.getName(), method.getParameterTypes()); + c = m.getDeclaringClass(); + if ((m = getMethod(c, m)) != null) + return m; + } catch (NoSuchMethodException ex) { + } } - - public Method getWriteMethod() { - return write(null); + Class c = cl.getSuperclass(); + if (c != null) { + Method m = null; + try { + m = c.getMethod(method.getName(), method.getParameterTypes()); + c = m.getDeclaringClass(); + if ((m = getMethod(c, m)) != null) + return m; + } catch (NoSuchMethodException ex) { + } } + return null; + } - public Method getReadMethod() { - return this.read(null); + private BeanProperty getBeanProperty(ELContext context, + Object base, + Object prop) { + + String property = prop.toString(); + Class baseClass = base.getClass(); + BeanProperties bps = properties.get(baseClass); + if (bps == null) { + bps = new BeanProperties(baseClass); + properties.putIfAbsent(baseClass, bps); } + BeanProperty bp = bps.getBeanProperty(property); + if (bp == null) { + throw new PropertyNotFoundException( + ELUtil.getExceptionMessageString(context, + "propertyNotFound", + new Object[] { baseClass.getName(), + property})); + } + return bp; + } - private Method write(ELContext ctx) { - if (this.write == null) { - this.write = getMethod(this.owner, descriptor.getWriteMethod()); - if (this.write == null) { - throw new PropertyNotFoundException(message(ctx, - "propertyNotWritable", new Object[] { - type.getName(), descriptor.getName() })); - } + private void removeFromMap(Map<Class, BeanProperties> map, + ClassLoader classloader) { + Iterator<Class> iter = map.keySet().iterator(); + while (iter.hasNext()) { + Class mbeanClass = iter.next(); + if (classloader.equals(mbeanClass.getClassLoader())) { + iter.remove(); } - return this.write; } - private Method read(ELContext ctx) { - if (this.read == null) { - this.read = getMethod(this.owner, descriptor.getReadMethod()); - if (this.read == null) { - throw new PropertyNotFoundException(message(ctx, - "propertyNotReadable", new Object[] { - type.getName(), descriptor.getName() })); - } - } - return this.read; - } } - private final BeanProperty property(ELContext ctx, Object base, - Object property) { - Class<?> type = base.getClass(); - String prop = property.toString(); + /* + * This method is not part of the API, though it can be used (reflectively) + * by clients of this class to remove entries from the cache when the beans + * are being unloaded. + * + * A note about why WeakHashMap is not used. Measurements has shown + * that ConcurrentHashMap is much more scalable than synchronized + * WeakHashMap. A manual purge seems to be a good compromise. + * + * @param classloader The classLoader used to load the beans. + */ + private void purgeBeanClasses(ClassLoader classloader) { + removeFromMap(properties, classloader); + } - BeanProperties props = this.cache.get(type.getName()); - if (props == null || type != props.getType()) { - props = new BeanProperties(type); - this.cache.put(type.getName(), props); - } + private Method findMethod(Object base, String method, + Class<?>[] paramTypes, Object[] params) { - return props.get(ctx, prop); - } - - private final static Method getMethod(Class type, Method m) { - if (m == null || Modifier.isPublic(type.getModifiers())) { - return m; - } - Class[] inf = type.getInterfaces(); - Method mp = null; - for (int i = 0; i < inf.length; i++) { + Class<?>beanClass = base.getClass(); + if (paramTypes != null) { try { - mp = inf[i].getMethod(m.getName(), (Class[]) m.getParameterTypes()); - mp = getMethod(mp.getDeclaringClass(), mp); - if (mp != null) { - return mp; - } - } catch (NoSuchMethodException e) { + return beanClass.getMethod(method, paramTypes); + } catch (java.lang.NoSuchMethodException ex) { + throw new MethodNotFoundException(ex); } } - Class sup = type.getSuperclass(); - if (sup != null) { - try { - mp = sup.getMethod(m.getName(), (Class[]) m.getParameterTypes()); - mp = getMethod(mp.getDeclaringClass(), mp); - if (mp != null) { - return mp; - } - } catch (NoSuchMethodException e) { + for (Method m: base.getClass().getMethods()) { + if (m.getName().equals(method) && ( + m.isVarArgs() || + m.getParameterTypes().length==params.length)){ + return m; } } - return null; + throw new MethodNotFoundException("Method " + method + " not found"); } - - private final static class ConcurrentCache<K,V> { - private final int size; - private final Map<K,V> eden; - private final Map<K,V> longterm; - - public ConcurrentCache(int size) { - this.size = size; - this.eden = new ConcurrentHashMap<K,V>(size); - this.longterm = new WeakHashMap<K,V>(size); - } - - public V get(K key) { - V value = this.eden.get(key); - if (value == null) { - value = this.longterm.get(key); - if (value != null) { - this.eden.put(key, value); + private Object invokeMethod(Method m, Object base, Object[] params) { + + Class[] parameterTypes = m.getParameterTypes(); + Object[] parameters = null; + if (parameterTypes.length > 0) { + ExpressionFactory exprFactory = ExpressionFactory.newInstance(); + if (m.isVarArgs()) { + // TODO + } else { + parameters = new Object[parameterTypes.length]; + for (int i = 0; i < parameterTypes.length; i++) { + parameters[i] = exprFactory.coerceToType(params[i], + parameterTypes[i]); } } - return value; } - - public void put(K key, V value) { - if (this.eden.size() >= this.size) { - this.longterm.putAll(this.eden); - this.eden.clear(); - } - this.eden.put(key, value); + try { + return m.invoke(base, parameters); + } catch (IllegalAccessException iae) { + throw new ELException(iae); + } catch (InvocationTargetException ite) { + throw new ELException(ite.getCause()); } - } } + Modified: trunk/java/javax/el/CompositeELResolver.java =================================================================== --- trunk/java/javax/el/CompositeELResolver.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/CompositeELResolver.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,187 +1,596 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; +import java.util.ArrayList; +import java.util.Iterator; import java.beans.FeatureDescriptor; -import java.util.Iterator; -import java.util.NoSuchElementException; +/** + * Maintains an ordered composite list of child <code>ELResolver</code>s. + * + * <p>Though only a single <code>ELResolver</code> is associated with an + * <code>ELContext</code>, there are usually multiple resolvers considered + * for any given variable or property resolution. <code>ELResolver</code>s + * are combined together using a <code>CompositeELResolver</code>, to define + * rich semantics for evaluating an expression.</p> + * + * <p>For the {@link #getValue}, {@link #getType}, {@link #setValue} and + * {@link #isReadOnly} methods, an <code>ELResolver</code> is not + * responsible for resolving all possible (base, property) pairs. In fact, + * most resolvers will only handle a <code>base</code> of a single type. + * To indicate that a resolver has successfully resolved a particular + * (base, property) pair, it must set the <code>propertyResolved</code> + * property of the <code>ELContext</code> to <code>true</code>. If it could + * not handle the given pair, it must leave this property alone. The caller + * must ignore the return value of the method if <code>propertyResolved</code> + * is <code>false</code>.</p> + * + * <p>The <code>CompositeELResolver</code> initializes the + * <code>ELContext.propertyResolved</code> flag to <code>false</code>, and uses + * it as a stop condition for iterating through its component resolvers.</p> + * + * <p>The <code>ELContext.propertyResolved</code> flag is not used for the + * design-time methods {@link #getFeatureDescriptors} and + * {@link #getCommonPropertyType}. Instead, results are collected and + * combined from all child <code>ELResolver</code>s for these methods.</p> + * + * @see ELContext + * @see ELResolver + * @since JSP 2.1 + */ public class CompositeELResolver extends ELResolver { - private int size; + /** + * Adds the given resolver to the list of component resolvers. + * + * <p>Resolvers are consulted in the order in which they are added.</p> + * + * @param elResolver The component resolver to add. + * @throws NullPointerException If the provided resolver is + * <code>null</code>. + */ + public void add(ELResolver elResolver) { - private ELResolver[] resolvers; - - public CompositeELResolver() { - this.size = 0; - this.resolvers = new ELResolver[2]; - } - - public void add(ELResolver elResolver) { if (elResolver == null) { throw new NullPointerException(); } - - if (this.size >= this.resolvers.length) { - ELResolver[] nr = new ELResolver[this.size * 2]; - System.arraycopy(this.resolvers, 0, nr, 0, this.size); - this.resolvers = nr; - } - this.resolvers[this.size++] = elResolver; + + elResolvers.add(elResolver); } - public Object getValue(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { + /** + * Attempts to resolve the given <code>property</code> object on the given + * <code>base</code> object by querying all component resolvers. + * + * <p>If this resolver handles the given (base, property) pair, + * the <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> + * by the resolver, before returning. If this property is not + * <code>true</code> after this method is called, the caller should ignore + * the return value.</p> + * + * <p>First, <code>propertyResolved</code> is set to <code>false</code> on + * the provided <code>ELContext</code>.</p> + * + * <p>Next, for each component resolver in this composite: + * <ol> + * <li>The <code>getValue()</code> method is called, passing in + * the provided <code>context</code>, <code>base</code> and + * <code>property</code>.</li> + * <li>If the <code>ELContext</code>'s <code>propertyResolved</code> + * flag is <code>false</code> then iteration continues.</li> + * <li>Otherwise, iteration stops and no more component resolvers are + * considered. The value returned by <code>getValue()</code> is + * returned by this method.</li> + * </ol></p> + * + * <p>If none of the component resolvers were able to perform this + * operation, the value <code>null</code> is returned and the + * <code>propertyResolved</code> flag remains set to + * <code>false</code></p>. + * + * <p>Any exception thrown by component resolvers during the iteration + * is propagated to the caller of this method.</p> + * + * @param context The context of this evaluation. + * @param base The base object whose property value is to be returned, + * or <code>null</code> to resolve a top-level variable. + * @param property The property or variable to be resolved. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the result of the variable or property resolution; otherwise + * undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if the given (base, property) pair + * is handled by this <code>ELResolver</code> but the specified + * variable or property does not exist or is not readable. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Object getValue(ELContext context, + Object base, + Object property) { context.setPropertyResolved(false); - int sz = this.size; - Object result = null; - for (int i = 0; i < sz; i++) { - result = this.resolvers[i].getValue(context, base, property); + int i = 0, len = this.elResolvers.size(); + ELResolver elResolver; + Object value; + while (i < len) { + elResolver = this.elResolvers.get(i); + value = elResolver.getValue(context, base, property); if (context.isPropertyResolved()) { - return result; + return value; } - } + i++; + } return null; } - public void setValue(ELContext context, Object base, Object property, - Object value) throws NullPointerException, - PropertyNotFoundException, PropertyNotWritableException, - ELException { + /** + * Attemps to resolve and invoke the given <code>method</code> on the given + * <code>base</code> object by querying all component resolvers. + * + * <p>If this resolver handles the given (base, method) pair, + * the <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> + * by the resolver, before returning. If this property is not + * <code>true</code> after this method is called, the caller should ignore + * the return value.</p> + * + * <p>First, <code>propertyResolved</code> is set to <code>false</code> on + * the provided <code>ELContext</code>.</p> + * + * <p>Next, for each component resolver in this composite: + * <ol> + * <li>The <code>invoke()</code> method is called, passing in + * the provided <code>context</code>, <code>base</code>, + * <code>method</code>, <code>paramTypes</code>, and + * <code>params</code>.</li> + * <li>If the <code>ELContext</code>'s <code>propertyResolved</code> + * flag is <code>false</code> then iteration continues.</li> + * <li>Otherwise, iteration stops and no more component resolvers are + * considered. The value returned by <code>getValue()</code> is + * returned by this method.</li> + * </ol></p> + * + * <p>If none of the component resolvers were able to perform this + * operation, the value <code>null</code> is returned and the + * <code>propertyResolved</code> flag remains set to + * <code>false</code></p>. + * + * <p>Any exception thrown by component resolvers during the iteration + * is propagated to the caller of this method.</p> + * + * @param context The context of this evaluation. + * @param base The bean on which to invoke the method + * @param method The simple name of the method to invoke. + * Will be coerced to a <code>String</code>. If method is + * "<init>"or "<clinit>" a NoSuchMethodException is raised. + * @param paramTypes An array of Class objects identifying the + * method's formal parameter types, in declared order. + * Use an empty array if the method has no parameters. + * Can be <code>null</code>, in which case the method's formal + * parameter types are assumed to be unknown. + * @param params The parameters to pass to the method, or + * <code>null</code> if no parameters. + * @return The result of the method invocation (<code>null</code> if + * the method has a <code>void</code> return type). + * @since EL 2.2 + */ + public Object invoke(ELContext context, + Object base, + Object method, + Class<?>[] paramTypes, + Object[] params) { context.setPropertyResolved(false); - int sz = this.size; - for (int i = 0; i < sz; i++) { - this.resolvers[i].setValue(context, base, property, value); + int i = 0, len = this.elResolvers.size(); + ELResolver elResolver; + Object value; + while (i < len) { + elResolver = this.elResolvers.get(i); + value = elResolver.invoke(context, base, method, paramTypes, params); if (context.isPropertyResolved()) { - return; + return value; } + i++; } + return null; } - public boolean isReadOnly(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { + /** + * For a given <code>base</code> and <code>property</code>, attempts to + * identify the most general type that is acceptable for an object to be + * passed as the <code>value</code> parameter in a future call + * to the {@link #setValue} method. The result is obtained by + * querying all component resolvers. + * + * <p>If this resolver handles the given (base, property) pair, + * the <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> + * by the resolver, before returning. If this property is not + * <code>true</code> after this method is called, the caller should ignore + * the return value.</p> + * + * <p>First, <code>propertyResolved</code> is set to <code>false</code> on + * the provided <code>ELContext</code>.</p> + * + * <p>Next, for each component resolver in this composite: + * <ol> + * <li>The <code>getType()</code> method is called, passing in + * the provided <code>context</code>, <code>base</code> and + * <code>property</code>.</li> + * <li>If the <code>ELContext</code>'s <code>propertyResolved</code> + * flag is <code>false</code> then iteration continues.</li> + * <li>Otherwise, iteration stops and no more component resolvers are + * considered. The value returned by <code>getType()</code> is + * returned by this method.</li> + * </ol></p> + * + * <p>If none of the component resolvers were able to perform this + * operation, the value <code>null</code> is returned and the + * <code>propertyResolved</code> flag remains set to + * <code>false</code></p>. + * + * <p>Any exception thrown by component resolvers during the iteration + * is propagated to the caller of this method.</p> + * + * @param context The context of this evaluation. + * @param base The base object whose property value is to be analyzed, + * or <code>null</code> to analyze a top-level variable. + * @param property The property or variable to return the acceptable + * type for. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the most general acceptable type; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if the given (base, property) pair + * is handled by this <code>ELResolver</code> but the specified + * variable or property does not exist or is not readable. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Class<?> getType(ELContext context, + Object base, + Object property) { context.setPropertyResolved(false); - int sz = this.size; - boolean readOnly = false; - for (int i = 0; i < sz; i++) { - readOnly = this.resolvers[i].isReadOnly(context, base, property); + int i = 0, len = this.elResolvers.size(); + ELResolver elResolver; + Class<?> type; + while (i < len) { + elResolver = this.elResolvers.get(i); + type = elResolver.getType(context, base, property); if (context.isPropertyResolved()) { - return readOnly; + return type; } + i++; } - return false; + return null; } - public Iterator<FeatureDescriptor> getFeatureDescriptors(ELContext context, Object base) { - return new FeatureIterator(context, base, this.resolvers, this.size); - } - - public Class<?> getCommonPropertyType(ELContext context, Object base) { - int sz = this.size; - Class<?> commonType = null, type = null; - for (int i = 0; i < sz; i++) { - type = this.resolvers[i].getCommonPropertyType(context, base); - if (type != null - && (commonType == null || commonType.isAssignableFrom(type))) { - commonType = type; + /** + * Attempts to set the value of the given <code>property</code> + * object on the given <code>base</code> object. All component + * resolvers are asked to attempt to set the value. + * + * <p>If this resolver handles the given (base, property) pair, + * the <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> + * by the resolver, before returning. If this property is not + * <code>true</code> after this method is called, the caller can + * safely assume no value has been set.</p> + * + * <p>First, <code>propertyResolved</code> is set to <code>false</code> on + * the provided <code>ELContext</code>.</p> + * + * <p>Next, for each component resolver in this composite: + * <ol> + * <li>The <code>setValue()</code> method is called, passing in + * the provided <code>context</code>, <code>base</code>, + * <code>property</code> and <code>value</code>.</li> + * <li>If the <code>ELContext</code>'s <code>propertyResolved</code> + * flag is <code>false</code> then iteration continues.</li> + * <li>Otherwise, iteration stops and no more component resolvers are + * considered.</li> + * </ol></p> + * + * <p>If none of the component resolvers were able to perform this + * operation, the <code>propertyResolved</code> flag remains set to + * <code>false</code></p>. + * + * <p>Any exception thrown by component resolvers during the iteration + * is propagated to the caller of this method.</p> + * + * @param context The context of this evaluation. + * @param base The base object whose property value is to be set, + * or <code>null</code> to set a top-level variable. + * @param property The property or variable to be set. + * @param val The value to set the property or variable to. + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if the given (base, property) pair + * is handled by this <code>ELResolver</code> but the specified + * variable or property does not exist. + * @throws PropertyNotWritableException if the given (base, property) + * pair is handled by this <code>ELResolver</code> but the specified + * variable or property is not writable. + * @throws ELException if an exception was thrown while attempting to + * set the property or variable. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public void setValue(ELContext context, + Object base, + Object property, + Object val) { + context.setPropertyResolved(false); + int i = 0, len = this.elResolvers.size(); + ELResolver elResolver; + while (i < len) { + elResolver = this.elResolvers.get(i); + elResolver.setValue(context, base, property, val); + if (context.isPropertyResolved()) { + return; } + i++; } - return commonType; } - public Class<?> getType(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { + /** + * For a given <code>base</code> and <code>property</code>, attempts to + * determine whether a call to {@link #setValue} will always fail. The + * result is obtained by querying all component resolvers. + * + * <p>If this resolver handles the given (base, property) pair, + * the <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> + * by the resolver, before returning. If this property is not + * <code>true</code> after this method is called, the caller should ignore + * the return value.</p> + * + * <p>First, <code>propertyResolved</code> is set to <code>false</code> on + * the provided <code>ELContext</code>.</p> + * + * <p>Next, for each component resolver in this composite: + * <ol> + * <li>The <code>isReadOnly()</code> method is called, passing in + * the provided <code>context</code>, <code>base</code> and + * <code>property</code>.</li> + * <li>If the <code>ELContext</code>'s <code>propertyResolved</code> + * flag is <code>false</code> then iteration continues.</li> + * <li>Otherwise, iteration stops and no more component resolvers are + * considered. The value returned by <code>isReadOnly()</code> is + * returned by this method.</li> + * </ol></p> + * + * <p>If none of the component resolvers were able to perform this + * operation, the value <code>false</code> is returned and the + * <code>propertyResolved</code> flag remains set to + * <code>false</code></p>. + * + * <p>Any exception thrown by component resolvers during the iteration + * is propagated to the caller of this method.</p> + * + * @param context The context of this evaluation. + * @param base The base object whose property value is to be analyzed, + * or <code>null</code> to analyze a top-level variable. + * @param property The property or variable to return the read-only status + * for. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>true</code> if the property is read-only or + * <code>false</code> if not; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if the given (base, property) pair + * is handled by this <code>ELResolver</code> but the specified + * variable or property does not exist. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public boolean isReadOnly(ELContext context, + Object base, + Object property) { context.setPropertyResolved(false); - int sz = this.size; - Class<?> type; - for (int i = 0; i < sz; i++) { - type = this.resolvers[i].getType(context, base, property); + int i = 0, len = this.elResolvers.size(); + ELResolver elResolver; + boolean readOnly; + while (i < len) { + elResolver = this.elResolvers.get(i); + readOnly = elResolver.isReadOnly(context, base, property); if (context.isPropertyResolved()) { - return type; + return readOnly; } + i++; } - return null; + return false; // Does not matter } - private final static class FeatureIterator implements Iterator<FeatureDescriptor> { + /** + * Returns information about the set of variables or properties that + * can be resolved for the given <code>base</code> object. One use for + * this method is to assist tools in auto-completion. The results are + * collected from all component resolvers. + * + * <p>The <code>propertyResolved</code> property of the + * <code>ELContext</code> is not relevant to this method. + * The results of all <code>ELResolver</code>s are concatenated.</p> + * + * <p>The <code>Iterator</code> returned is an iterator over the + * collection of <code>FeatureDescriptor</code> objects returned by + * the iterators returned by each component resolver's + * <code>getFeatureDescriptors</code> method. If <code>null</code> is + * returned by a resolver, it is skipped.</p> + * + * @param context The context of this evaluation. + * @param base The base object whose set of valid properties is to + * be enumerated, or <code>null</code> to enumerate the set of + * top-level variables that this resolver can evaluate. + * @return An <code>Iterator</code> containing zero or more (possibly + * infinitely more) <code>FeatureDescriptor</code> objects, or + * <code>null</code> if this resolver does not handle the given + * <code>base</code> object or that the results are too complex to + * represent with this method + */ + public Iterator<FeatureDescriptor> getFeatureDescriptors( + ELContext context, + Object base) { + return new CompositeIterator(elResolvers.iterator(), context, base); + } - private final ELContext context; + /** + * Returns the most general type that this resolver accepts for the + * <code>property</code> argument, given a <code>base</code> object. + * One use for this method is to assist tools in auto-completion. The + * result is obtained by querying all component resolvers. + * + * <p>The <code>Class</code> returned is the most specific class that is + * a common superclass of all the classes returned by each component + * resolver's <code>getCommonPropertyType</code> method. If + * <code>null</code> is returned by a resolver, it is skipped.</p> + * + * @param context The context of this evaluation. + * @param base The base object to return the most general property + * type for, or <code>null</code> to enumerate the set of + * top-level variables that this resolver can evaluate. + * @return <code>null</code> if this <code>ELResolver</code> does not + * know how to handle the given <code>base</code> object; otherwise + * <code>Object.class</code> if any type of <code>property</code> + * is accepted; otherwise the most general <code>property</code> + * type accepted for the given <code>base</code>. + */ + public Class<?> getCommonPropertyType(ELContext context, + Object base) { + Class<?> commonPropertyType = null; + Iterator<ELResolver> iter = elResolvers.iterator(); + while (iter.hasNext()) { + ELResolver elResolver = iter.next(); + Class<?> type = elResolver.getCommonPropertyType(context, base); + if (type == null) { + // skip this EL Resolver + continue; + } else if (commonPropertyType == null) { + commonPropertyType = type; + } else if (commonPropertyType.isAssignableFrom(type)) { + continue; + } else if (type.isAssignableFrom(commonPropertyType)) { + commonPropertyType = type; + } else { + // Don't have a commonPropertyType + return null; + } + } + return commonPropertyType; + } - private final Object base; + private final ArrayList<ELResolver> elResolvers = + new ArrayList<ELResolver>(); - private final ELResolver[] resolvers; + private static class CompositeIterator + implements Iterator<FeatureDescriptor> { - private final int size; + Iterator<ELResolver> compositeIter; + Iterator<FeatureDescriptor> propertyIter; + ELContext context; + Object base; - private Iterator<FeatureDescriptor> itr; - - private int idx; - - private FeatureDescriptor next; - - public FeatureIterator(ELContext context, Object base, - ELResolver[] resolvers, int size) { + CompositeIterator(Iterator<ELResolver> iter, + ELContext context, + Object base) { + compositeIter = iter; this.context = context; this.base = base; - this.resolvers = resolvers; - this.size = size; - - this.idx = 0; - this.guaranteeIterator(); } - - private void guaranteeIterator() { - while (this.itr == null && this.idx < this.size) { - this.itr = this.resolvers[this.idx].getFeatureDescriptors( - this.context, this.base); - this.idx++; - } - } - public boolean hasNext() { - if (this.next != null) - return true; - if (this.itr != null){ - while (this.next == null && itr.hasNext()) { - this.next = itr.next(); + public boolean hasNext() { + if (propertyIter == null || !propertyIter.hasNext()) { + while (compositeIter.hasNext()) { + ELResolver elResolver = compositeIter.next(); + propertyIter = elResolver.getFeatureDescriptors( + context, base); + if (propertyIter != null) { + return propertyIter.hasNext(); + } } - } else { return false; } - if (this.next == null) { - this.itr = null; - this.guaranteeIterator(); - } - return hasNext(); + return propertyIter.hasNext(); } public FeatureDescriptor next() { - if (!hasNext()) - throw new NoSuchElementException(); - FeatureDescriptor next = this.next; - this.next = null; - return next; - + if (propertyIter == null || !propertyIter.hasNext()) { + while (compositeIter.hasNext()) { + ELResolver elResolver = compositeIter.next(); + propertyIter = elResolver.getFeatureDescriptors( + context, base); + if (propertyIter != null) { + return propertyIter.next(); + } + } + return null; + } + return propertyIter.next(); } public void remove() { throw new UnsupportedOperationException(); } } +} -} Modified: trunk/java/javax/el/ELContext.java =================================================================== --- trunk/java/javax/el/ELContext.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/ELContext.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,82 +1,258 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; import java.util.HashMap; import java.util.Locale; -import java.util.Map; /** + * Context information for expression evaluation. * + * <p>To evaluate an {@link Expression}, an <code>ELContext</code> must be + * provided. The <code>ELContext</code> holds: + * <ul> + * <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 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> + * </ul></p> + * + * <p>The collection of context objects is necessary because each + * <code>ELResolver</code> may need access to a different context object. + * For example, JSP and Faces resolvers need access to a + * {@link javax.servlet.jsp.JspContext} and a + * {@link javax.faces.context.FacesContext}, respectively.</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. + * 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>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 + * threads.</p> + * + * @see ELContextListener + * @see ELContextEvent + * @see ELResolver + * @see FunctionMapper + * @see VariableMapper + * @see javax.servlet.jsp.JspContext + * @since JSP 2.1 */ public abstract class ELContext { - private Locale locale; - - private Map<Class<?>, Object> map; - - private boolean resolved; - /** - * + * Called to indicate that a <code>ELResolver</code> has successfully + * resolved a given (base, property) pair. + * + * <p>The {@link CompositeELResolver} checks this property to determine + * whether it should consider or skip other component resolvers.</p> + * + * @see CompositeELResolver + * @param resolved true if the property has been resolved, or false if + * not. */ - public ELContext() { - this.resolved = false; + public void setPropertyResolved(boolean resolved) { + this.resolved = resolved; } - - public Object getContext(Class key) { - if (this.map == null) { - return null; + + /** + * Returns whether an {@link ELResolver} has successfully resolved a + * given (base, property) pair. + * + * <p>The {@link CompositeELResolver} checks this property to determine + * whether it should consider or skip other component resolvers.</p> + * + * @see CompositeELResolver + * @return true if the property has been resolved, or false if not. + */ + public boolean isPropertyResolved() { + return resolved; + } + + /** + * Associates a context object with this <code>ELContext</code>. + * + * <p>The <code>ELContext</code> maintains a collection of context objects + * relevant to the evaluation of an expression. These context objects + * are used by <code>ELResolver</code>s. This method is used to + * add a context object to that collection.</p> + * + * <p>By convention, the <code>contextObject</code> will be of the + * type specified by the <code>key</code>. However, this is not + * required and the key is used strictly as a unique identifier.</p> + * + * @param key The key used by an @{link ELResolver} to identify this + * context object. + * @param contextObject The context object to add to the collection. + * @throws NullPointerException if key is null or contextObject is null. + */ + public void putContext(Class key, Object contextObject) { + if((key == null) || (contextObject == null)) { + throw new NullPointerException(); } - return this.map.get(key); + map.put(key, contextObject); } - - public void putContext(Class key, Object contextObject) throws NullPointerException { - if (key == null || contextObject == null) { + + /** + * Returns the context object associated with the given key. + * + * <p>The <code>ELContext</code> maintains a collection of context objects + * relevant to the evaluation of an expression. These context objects + * are used by <code>ELResolver</code>s. This method is used to + * retrieve the context with the given key from the collection.</p> + * + * <p>By convention, the object returned will be of the type specified by + * the <code>key</code>. However, this is not required and the key is + * used strictly as a unique identifier.</p> + * + * @param key The unique identifier that was used to associate the + * context object with this <code>ELContext</code>. + * @return The context object associated with the given key, or null + * if no such context was found. + * @throws NullPointerException if key is null. + */ + public Object getContext(Class key) { + if(key == null) { throw new NullPointerException(); } - - if (this.map == null) { - this.map = new HashMap<Class<?>, Object>(); - } - - this.map.put(key, contextObject); + return map.get(key); } + + /** + * Retrieves the <code>ELResolver</code> associated with this context. + * + * <p>The <code>ELContext</code> maintains a reference to the + * <code>ELResolver</code> that will be consulted to resolve variables + * and properties during an expression evaluation. This method + * retrieves the reference to the resolver.</p> + * + * <p>Once an <code>ELContext</code> is constructed, the reference to the + * <code>ELResolver</code> associated with the context cannot be changed.</p> + * + * @return The resolver to be consulted for variable and + * property resolution during expression evaluation. + */ + public abstract ELResolver getELResolver(); - public void setPropertyResolved(boolean resolved) { - this.resolved = resolved; - } + /** + * Retrieves the <code>FunctionMapper</code> associated with this + * <code>ELContext</code>. + * + * @return The function mapper to be consulted for the resolution of + * EL functions. + */ + public abstract FunctionMapper getFunctionMapper(); - public boolean isPropertyResolved() { - return this.resolved; - } + /** + * Holds value of property locale. + */ + private Locale locale; - public abstract ELResolver getELResolver(); + /** + * Get the <code>Locale</code> stored by a previous invocation to + * {@link #setLocale}. If this method returns non <code>null</code>, + * this <code>Locale</code> must be used for all localization needs + * in the implementation. The <code>Locale</code> must not be cached + * to allow for applications that change <code>Locale</code> dynamically. + * + * @return The <code>Locale</code> in which this instance is operating. + * Used primarily for message localization. + */ - public abstract FunctionMapper getFunctionMapper(); - - public abstract VariableMapper getVariableMapper(); - public Locale getLocale() { + return this.locale; } - + + /** + * Set 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 + * must use the locale returned by <code>Locale.getDefault( )</code>. + */ public void setLocale(Locale locale) { + this.locale = locale; - } + } + + + /** + * Retrieves the <code>VariableMapper</code> associated with this + * <code>ELContext</code>. + * + * @return The variable mapper to be consulted for the resolution of + * EL variables. + */ + public abstract VariableMapper getVariableMapper(); + + private boolean resolved; + private HashMap map = new HashMap(); + + } + Modified: trunk/java/javax/el/ELContextEvent.java =================================================================== --- trunk/java/javax/el/ELContextEvent.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/ELContextEvent.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,38 +1,87 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; -import java.util.EventObject; - /** + * An event which indicates that an {@link ELContext} has been created. + * The source object is the ELContext that was created. * + * @see ELContext + * @see ELContextListener + * @since JSP 2.1 */ -public class ELContextEvent extends EventObject { +public class ELContextEvent extends java.util.EventObject { /** - * @param source + * Constructs an ELContextEvent object to indicate that an + * <code>ELContext</code> has been created. + * + * @param source the <code>ELContext</code> that was created. */ public ELContextEvent(ELContext source) { super(source); } - + + /** + * Returns the <code>ELContext</code> that was created. + * This is a type-safe equivalent of the {@link #getSource} method. + * + * @return the ELContext that was created. + */ public ELContext getELContext() { - return (ELContext) this.getSource(); + return (ELContext) getSource(); } - } Modified: trunk/java/javax/el/ELContextListener.java =================================================================== --- trunk/java/javax/el/ELContextListener.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/ELContextListener.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,28 +1,75 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; /** - * @author Jacob Hookom [jacob/hookom.net] + * The listener interface for receiving notification when an + * {@link ELContext} is created. * + * @see ELContext + * @see ELContextEvent + * @since JSP 2.1 */ public interface ELContextListener extends java.util.EventListener { - - public void contextCreated(ELContextEvent event); + /** + * Invoked when a new <code>ELContext</code> has been created. + * + * @param ece the notification event. + */ + public void contextCreated(ELContextEvent ece); + } Modified: trunk/java/javax/el/ELException.java =================================================================== --- trunk/java/javax/el/ELException.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/ELException.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,13 +1,50 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. @@ -18,49 +55,51 @@ package javax.el; /** - * Represents any of the exception conditions that can arise during expression - * evaluation. - * - * @since 2.1 + * Represents any of the exception conditions that can arise during + * expression evaluation. + * + * @since JSP 2.1 */ public class ELException extends RuntimeException { - /** - * Creates an ELException with no detail message - */ - public ELException() { - super(); - } + //------------------------------------- + /** + * Creates an <code>ELException</code> with no detail message. + */ + public ELException () { + super (); + } - /** - * Creates an ELException with the provided detail message. - * - * @param message - * the detail message - */ - public ELException(String message) { - super(message); - } + //------------------------------------- + /** + * Creates an <code>ELException</code> with the provided detail message. + * + * @param pMessage the detail message + */ + public ELException (String pMessage) { + super (pMessage); + } - /** - * Creates an ELException with the given detail message and root cause. - * - * @param message - * the detail message - * @param cause - * the originating cause of this exception - */ - public ELException(String message, Throwable cause) { - super(message, cause); - } + //------------------------------------- + /** + * Creates an <code>ELException</code> with the given cause. + * + * @param pRootCause the originating cause of this exception + */ + public ELException (Throwable pRootCause) { + super( pRootCause ); + } - /** - * Creates an ELException with the given cause - * - * @param cause - * the originating cause of this exception - */ - public ELException(Throwable cause) { - super(cause); - } + //------------------------------------- + /** + * Creates an ELException with the given detail message and root cause. + * + * @param pMessage the detail message + * @param pRootCause the originating cause of this exception + */ + public ELException (String pMessage, + Throwable pRootCause) { + super (pMessage, pRootCause); + } + } Modified: trunk/java/javax/el/ELResolver.java =================================================================== --- trunk/java/javax/el/ELResolver.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/ELResolver.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,69 +1,426 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; -import java.text.MessageFormat; import java.util.Iterator; -import java.util.Locale; -import java.util.MissingResourceException; -import java.util.ResourceBundle; +import java.beans.FeatureDescriptor; /** - * @author Jacob Hookom [jacob/hookom.net] + * Enables customization of variable, property and method call resolution + * behavior for EL expression evaluation. * + * <p>While evaluating an expression, the <code>ELResolver</code> associated + * with the {@link ELContext} is consulted to do the initial resolution of + * the first variable of an expression. It is also consulted when a + * <code>.</code> or <code>[]</code> operator is encountered. + * + * <p>For example, in the EL expression <code>${employee.lastName}</code>, + * the <code>ELResolver</code> determines what object <code>employee</code> + * refers to, and what it means to get the <code>lastName</code> property on + * that object.</p> + * + * <p>Most methods in this class accept a <code>base</code> + * and <code>property</code> parameter. In the case of variable resolution + * (e.g. determining what <code>employee</code> refers to in + * <code>${employee.lastName}</code>), the <code>base</code> parameter will + * be <code>null</code> and the <code>property</code> parameter will always + * be of type <code>String</code>. In this case, if the <code>property</code> + * is not a <code>String</code>, the behavior of the <code>ELResolver</code> + * is undefined.</p> + * + * <p>In the case of property resolution, the <code>base</code> parameter + * identifies the base object and the <code>property</code> object identifies + * the property on that base. For example, in the expression + * <code>${employee.lastName}</code>, <code>base</code> is the result of the + * variable resolution for <code>employee</code> and <code>property</code> + * is the string <code>"lastName"</code>. In the expression + * <code>${y[x]}</code>, <code>base</code> is the result of the variable + * resolution for <code>y</code> and <code>property</code> is the result of + * the variable resolution for <code>x</code>.</p> + * + * <p>In the case of method call resolution, the <code>base</code> parameter + * indentifies the base object and the <code>method</code> parameter identifies + * a method on that base. In the case of overloaded methods, the <code> + * paramTypes</code> parameter can be optionally used to identify a method. + * The <code>params</code>parameter are the parameters for the method call, + * and can also be used for resolving overloaded methods when the + * <code>paramTypes</code> parameter is not specified. + * + * <p>Though only a single <code>ELResolver</code> is associated with an + * <code>ELContext</code>, there are usually multiple resolvers considered + * for any given variable or property resolution. <code>ELResolver</code>s + * are combined together using {@link CompositeELResolver}s, to define + * rich semantics for evaluating an expression.</p> + * + * <p>For the {@link #getValue}, {@link #getType}, {@link #setValue} and + * {@link #isReadOnly} methods, an <code>ELResolver</code> is not + * responsible for resolving all possible (base, property) pairs. In fact, + * most resolvers will only handle a <code>base</code> of a single type. + * To indicate that a resolver has successfully resolved a particular + * (base, property) pair, it must set the <code>propertyResolved</code> + * property of the <code>ELContext</code> to <code>true</code>. If it could + * not handle the given pair, it must leave this property alone. The caller + * must ignore the return value of the method if <code>propertyResolved</code> + * is <code>false</code>.</p> + * + * <p>The {@link #getFeatureDescriptors} and {@link #getCommonPropertyType} + * methods are primarily designed for design-time tool support, but must + * handle invocation at runtime as well. The + * {@link java.beans.Beans#isDesignTime} method can be used to determine + * if the resolver is being consulted at design-time or runtime.</p> + * + * @see CompositeELResolver + * @see ELContext#getELResolver + * @since JSP 2.1 */ public abstract class ELResolver { - - static String message(ELContext context, String name, Object[] props) { - Locale locale = context.getLocale(); - if (locale == null) { - locale = Locale.getDefault(); - if (locale == null) { - return ""; - } - } - ResourceBundle bundle = ResourceBundle.getBundle( - "javax.el.LocalStrings", locale); - try { - String template = bundle.getString(name); - if (props != null) { - template = MessageFormat.format(template, props); - } - return template; - } catch (MissingResourceException e) { - return "Missing Resource: '" + name + "' for Locale " - + locale.getDisplayName(); - } - } - - public final static String RESOLVABLE_AT_DESIGN_TIME = "resolvableAtDesignTime"; - public final static String TYPE = "type"; - - public abstract Object getValue(ELContext context, Object base, Object property) throws NullPointerException, PropertyNotFoundException, ELException; - - public abstract Class<?> getType(ELContext context, Object base, Object property) throws NullPointerException, PropertyNotFoundException, ELException; - - public abstract void setValue(ELContext context, Object base, Object property, Object value) throws NullPointerException, PropertyNotFoundException, PropertyNotWritableException, ELException; + // --------------------------------------------------------- Constants - public abstract boolean isReadOnly(ELContext context, Object base, Object property) throws NullPointerException, PropertyNotFoundException, ELException; - - public abstract Iterator<java.beans.FeatureDescriptor> getFeatureDescriptors(ELContext context, Object base); - - public abstract Class<?> getCommonPropertyType(ELContext context, Object base); + /** + * <p>The attribute name of the named attribute in the + * <code>FeatureDescriptor</code> that specifies the runtime type of + * the variable or property.</p> + */ + + public static final String TYPE = "type"; + + /** + * <p>The attribute name of the named attribute in the + * <code>FeatureDescriptor</code> that specifies whether the + * variable or property can be resolved at runtime.</p> + */ + + public static final String RESOLVABLE_AT_DESIGN_TIME = "resolvableAtDesignTime"; + + /** + * Attempts to resolve the given <code>property</code> object on the given + * <code>base</code> object. + * + * <p>If this resolver handles the given (base, property) pair, + * the <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> + * by the resolver, before returning. If this property is not + * <code>true</code> after this method is called, the caller should ignore + * the return value.</p> + * + * @param context The context of this evaluation. + * @param base The base object whose property value is to be returned, + * or <code>null</code> to resolve a top-level variable. + * @param property The property or variable to be resolved. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the result of the variable or property resolution; otherwise + * undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if the given (base, property) pair + * is handled by this <code>ELResolver</code> but the specified + * variable or property does not exist or is not readable. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public abstract Object getValue(ELContext context, + Object base, + Object property); + + /** + * Attemps to resolve and invoke the given <code>method</code> on the given + * <code>base</code> object. + * + * <p>If this resolver handles the given (base, method) pair, + * the <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> + * by the resolver, before returning. If this property is not + * <code>true</code> after this method is called, the caller should ignore + * the return value.</p> + * + * <p>A default implementation is provided that returns null so that + * existing classes that extend ELResolver can continue to function.</p> + * + * @param context The context of this evaluation. + * @param base The bean on which to invoke the method + * @param method The simple name of the method to invoke. + * Will be coerced to a <code>String</code>. + * @param paramTypes An array of Class objects identifying the + * method's formal parameter types, in declared order. + * Use an empty array if the method has no parameters. + * Can be <code>null</code>, in which case the method's formal + * parameter types are assumed to be unknown. + * @param params The parameters to pass to the method, or + * <code>null</code> if no parameters. + * @return The result of the method invocation (<code>null</code> if + * the method has a <code>void</code> return type). + * @throws MethodNotFoundException if no suitable method can be found. + * @throws ELException if an exception was thrown while performing + * (base, method) resolution. The thrown exception must be + * included as the cause property of this exception, if + * available. If the exception thrown is an + * <code>InvocationTargetException</code>, extract its + * <code>cause</code> and pass it to the + * <code>ELException</code> constructor. + * @since EL 2.2 + */ + public Object invoke(ELContext context, + Object base, + Object method, + Class<?>[] paramTypes, + Object[] params) { + return null; + } + + + /** + * For a given <code>base</code> and <code>property</code>, attempts to + * identify the most general type that is acceptable for an object to be + * passed as the <code>value</code> parameter in a future call + * to the {@link #setValue} method. + * + * <p>If this resolver handles the given (base, property) pair, + * the <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> + * by the resolver, before returning. If this property is not + * <code>true</code> after this method is called, the caller should ignore + * the return value.</p> + * + * <p>This is not always the same as <code>getValue().getClass()</code>. + * For example, in the case of an {@link ArrayELResolver}, the + * <code>getType</code> method will return the element type of the + * array, which might be a superclass of the type of the actual + * element that is currently in the specified array element.</p> + * + * @param context The context of this evaluation. + * @param base The base object whose property value is to be analyzed, + * or <code>null</code> to analyze a top-level variable. + * @param property The property or variable to return the acceptable + * type for. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the most general acceptable type; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if the given (base, property) pair + * is handled by this <code>ELResolver</code> but the specified + * variable or property does not exist or is not readable. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public abstract Class<?> getType(ELContext context, + Object base, + Object property); + + /** + * Attempts to set the value of the given <code>property</code> + * object on the given <code>base</code> object. + * + * <p>If this resolver handles the given (base, property) pair, + * the <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> + * by the resolver, before returning. If this property is not + * <code>true</code> after this method is called, the caller can + * safely assume no value has been set.</p> + * + * @param context The context of this evaluation. + * @param base The base object whose property value is to be set, + * or <code>null</code> to set a top-level variable. + * @param property The property or variable to be set. + * @param value The value to set the property or variable to. + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if the given (base, property) pair + * is handled by this <code>ELResolver</code> but the specified + * variable or property does not exist. + * @throws PropertyNotWritableException if the given (base, property) + * pair is handled by this <code>ELResolver</code> but the specified + * variable or property is not writable. + * @throws ELException if an exception was thrown while attempting to + * set the property or variable. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public abstract void setValue(ELContext context, + Object base, + Object property, + Object value); + + /** + * For a given <code>base</code> and <code>property</code>, attempts to + * determine whether a call to {@link #setValue} will always fail. + * + * <p>If this resolver handles the given (base, property) pair, + * the <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> + * by the resolver, before returning. If this property is not + * <code>true</code> after this method is called, the caller should ignore + * the return value.</p> + * + * @param context The context of this evaluation. + * @param base The base object whose property value is to be analyzed, + * or <code>null</code> to analyze a top-level variable. + * @param property The property or variable to return the read-only status + * for. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>true</code> if the property is read-only or + * <code>false</code> if not; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if the given (base, property) pair + * is handled by this <code>ELResolver</code> but the specified + * variable or property does not exist. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public abstract boolean isReadOnly(ELContext context, + Object base, + Object property); + + /** + * Returns information about the set of variables or properties that + * can be resolved for the given <code>base</code> object. One use for + * this method is to assist tools in auto-completion. + * + * <p>If the <code>base</code> parameter is <code>null</code>, the + * resolver must enumerate the list of top-level variables it can + * resolve.</p> + * + * <p>The <code>Iterator</code> returned must contain zero or more + * instances of {@link java.beans.FeatureDescriptor}, in no guaranteed + * order. In the case of primitive types such as <code>int</code>, the + * value <code>null</code> must be returned. This is to prevent the + * useless iteration through all possible primitive values. A + * return value of <code>null</code> indicates that this resolver does + * not handle the given <code>base</code> object or that the results + * are too complex to represent with this method and the + * {@link #getCommonPropertyType} method should be used instead.</p> + * + * <p>Each <code>FeatureDescriptor</code> will contain information about + * a single variable or property. In addition to the standard + * properties, the <code>FeatureDescriptor</code> must have two + * named attributes (as set by the <code>setValue</code> method): + * <ul> + * <li>{@link #TYPE} - The value of this named attribute must be + * an instance of <code>java.lang.Class</code> and specify the + * runtime type of the variable or property.</li> + * <li>{@link #RESOLVABLE_AT_DESIGN_TIME} - The value of this + * named attribute must be an instance of + * <code>java.lang.Boolean</code> and indicates whether it is safe + * to attempt to resolve this property at design-time. For + * instance, it may be unsafe to attempt a resolution at design + * time if the <code>ELResolver</code> needs access to a resource + * that is only available at runtime and no acceptable simulated + * value can be provided.</li> + * </ul></p> + * + * <p>The caller should be aware that the <code>Iterator</code> + * returned might iterate through a very large or even infinitely large + * set of properties. Care should be taken by the caller to not get + * stuck in an infinite loop.</p> + * + * <p>This is a "best-effort" list. Not all <code>ELResolver</code>s + * will return completely accurate results, but all must be callable + * at both design-time and runtime (i.e. whether or not + * <code>Beans.isDesignTime()</code> returns <code>true</code>), + * without causing errors.</p> + * + * <p>The <code>propertyResolved</code> property of the + * <code>ELContext</code> is not relevant to this method. + * The results of all <code>ELResolver</code>s are concatenated + * in the case of composite resolvers.</p> + * + * @param context The context of this evaluation. + * @param base The base object whose set of valid properties is to + * be enumerated, or <code>null</code> to enumerate the set of + * top-level variables that this resolver can evaluate. + * @return An <code>Iterator</code> containing zero or more (possibly + * infinitely more) <code>FeatureDescriptor</code> objects, or + * <code>null</code> if this resolver does not handle the given + * <code>base</code> object or that the results are too complex to + * represent with this method + * @see java.beans.FeatureDescriptor + */ + public abstract Iterator<FeatureDescriptor> getFeatureDescriptors( + ELContext context, + Object base); + + /** + * Returns the most general type that this resolver accepts for the + * <code>property</code> argument, given a <code>base</code> object. + * One use for this method is to assist tools in auto-completion. + * + * <p>This assists tools in auto-completion and also provides a + * way to express that the resolver accepts a primitive value, + * such as an integer index into an array. For example, the + * {@link ArrayELResolver} will accept any <code>int</code> as a + * <code>property</code>, so the return value would be + * <code>Integer.class</code>.</p> + * + * @param context The context of this evaluation. + * @param base The base object to return the most general property + * type for, or <code>null</code> to enumerate the set of + * top-level variables that this resolver can evaluate. + * @return <code>null</code> if this <code>ELResolver</code> does not + * know how to handle the given <code>base</code> object; otherwise + * <code>Object.class</code> if any type of <code>property</code> + * is accepted; otherwise the most general <code>property</code> + * type accepted for the given <code>base</code>. + */ + public abstract Class<?> getCommonPropertyType(ELContext context, + Object base); + } Added: trunk/java/javax/el/ELUtil.java =================================================================== --- trunk/java/javax/el/ELUtil.java (rev 0) +++ trunk/java/javax/el/ELUtil.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -0,0 +1,206 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ + +package javax.el; + +import java.text.MessageFormat; +import java.util.HashMap; +import java.util.Locale; +import java.util.Map; +import java.util.MissingResourceException; +import java.util.ResourceBundle; + +/** + * + * <p>Utility methods for this portion of the EL implementation</p> + * + * <p>Methods on this class use a Map instance stored in ThreadLocal storage + * to minimize the performance impact on operations that take place multiple + * times on a single Thread. The keys and values of the Map + * are implementation private.</p> + * + * @author edburns + */ +class ELUtil { + + /** + * <p>This class may not be constructed.</p> + */ + + private ELUtil() { + } + + /** + * <p>The <code>ThreadLocal</code> variable used to record the + * {@link javax.faces.context.FacesContext} instance for each + * processing thread.</p> + */ + private static ThreadLocal instance = new ThreadLocal() { + protected Object initialValue() { return (null); } + }; + + /** + * @return a Map stored in ThreadLocal storage. This may + * be used by methods of this class to minimize the performance + * impact for operations that may take place multiple times on a given + * Thread instance. + */ + + private static Map getCurrentInstance() { + Map result = (Map) instance.get(); + if (null == result) { + result = new HashMap(); + setCurrentInstance(result); + } + return result; + + } + + /** + * <p>Replace the Map with the argument context.</p> + * + * @param context the Map to be stored in ThreadLocal storage. + */ + + private static void setCurrentInstance(Map context) { + + instance.set(context); + + } + + /* + * <p>Convenience method, calls through to + * {@link #getExceptionMessageString(javax.el.ELContext,java.lang.String,Object []). + * </p> + * + * @param context the ELContext from which the Locale for this message + * is extracted. + * + * @param messageId the messageId String in the ResourceBundle + * + * @return a localized String for the argument messageId + */ + + public static String getExceptionMessageString(ELContext context, String messageId) { + return getExceptionMessageString(context, messageId, null); + } + + /* + * <p>Return a Localized message String suitable for use as an Exception message. + * Examine the argument <code>context</code> for a <code>Locale</code>. If + * not present, use <code>Locale.getDefault()</code>. Load the + * <code>ResourceBundle</code> "javax.el.Messages" using that locale. Get + * the message string for argument <code>messageId</code>. If not found + * return "Missing Resource in EL implementation ??? messageId ???" + * with messageId substituted with the runtime + * value of argument <code>messageId</code>. If found, and argument + * <code>params</code> is non-null, format the message using the + * params. If formatting fails, return a sensible message including + * the <code>messageId</code>. If argument <code>params</code> is + * <code>null</code>, skip formatting and return the message directly, otherwise + * return the formatted message.</p> + * + * @param context the ELContext from which the Locale for this message + * is extracted. + * + * @param messageId the messageId String in the ResourceBundle + * + * @param params parameters to the message + * + * @return a localized String for the argument messageId + */ + + public static String getExceptionMessageString(ELContext context, + String messageId, + Object [] params) { + String result = ""; + Locale locale = null; + + if (null == context || null == messageId) { + return result; + } + + if (null == (locale = context.getLocale())) { + locale = Locale.getDefault(); + } + if (null != locale) { + Map threadMap = getCurrentInstance(); + ResourceBundle rb = null; + if (null == (rb = (ResourceBundle) + threadMap.get(locale.toString()))) { + rb = ResourceBundle.getBundle("javax.el.PrivateMessages", + locale); + threadMap.put(locale.toString(), rb); + } + if (null != rb) { + try { + result = rb.getString(messageId); + if (null != params) { + result = MessageFormat.format(result, params); + } + } catch (IllegalArgumentException iae) { + result = "Can't get localized message: parameters to message appear to be incorrect. Message to format: " + messageId; + } catch (MissingResourceException mre) { + result = "Missing Resource in EL implementation: ???" + messageId + "???"; + } catch (Exception e) { + result = "Exception resolving message in EL implementation: ???" + messageId + "???"; + } + } + } + + return result; + } + + +} Modified: trunk/java/javax/el/Expression.java =================================================================== --- trunk/java/javax/el/Expression.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/Expression.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,13 +1,50 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. @@ -20,16 +57,100 @@ import java.io.Serializable; /** + * Base class for the expression subclasses {@link ValueExpression} and + * {@link MethodExpression}, implementing characterstics common to both. * + * <p>All expressions must implement the <code>equals()</code> and + * <code>hashCode()</code> methods so that two expressions can be compared + * for equality. They are redefined abstract in this class to force their + * implementation in subclasses.</p> + * + * <p>All expressions must also be <code>Serializable</code> so that they + * can be saved and restored.</p> + * + * <p><code>Expression</code>s are also designed to be immutable so + * that only one instance needs to be created for any given expression + * String / {@link FunctionMapper}. This allows a container to pre-create + * expressions and not have to re-parse them each time they are evaluated.</p> + * + * @since JSP 2.1 */ -public abstract class Expression implements Serializable { - +public abstract class Expression + implements Serializable { + // Debugging + + /** + * Returns the original String used to create this <code>Expression</code>, + * unmodified. + * + * <p>This is used for debugging purposes but also for the purposes + * of comparison (e.g. to ensure the expression in a configuration + * file has not changed).</p> + * + * <p>This method does not provide sufficient information to + * re-create an expression. Two different expressions can have exactly + * the same expression string but different function mappings. + * Serialization should be used to save and restore the state of an + * <code>Expression</code>.</p> + * + * @return The original expression String. + */ + public abstract String getExpressionString(); + + // Comparison + + /** + * Determines whether the specified object is equal to this + * <code>Expression</code>. + * + * <p>The result is <code>true</code> if and only if the argument is + * not <code>null</code>, is an <code>Expression</code> object that + * is the of the same type (<code>ValueExpression</code> or + * <code>MethodExpression</code>), and has an identical parsed + * representation.</p> + * + * <p>Note that two expressions can be equal if their expression + * Strings are different. For example, <code>${fn1:foo()}</code> + * and <code>${fn2:foo()}</code> are equal if their corresponding + * <code>FunctionMapper</code>s mapped <code>fn1:foo</code> and + * <code>fn2:foo</code> to the same method.</p> + * + * @param obj the <code>Object</code> to test for equality. + * @return <code>true</code> if <code>obj</code> equals this + * <code>Expression</code>; <code>false</code> otherwise. + * @see java.util.Hashtable + * @see java.lang.Object#equals(java.lang.Object) + */ public abstract boolean equals(Object obj); - + + /** + * Returns the hash code for this <code>Expression</code>. + * + * <p>See the note in the {@link #equals} method on how two expressions + * can be equal if their expression Strings are different. Recall that + * if two objects are equal according to the <code>equals(Object)</code> + * method, then calling the <code>hashCode</code> method on each of the + * two objects must produce the same integer result. Implementations must + * take special note and implement <code>hashCode</code> correctly.</p> + * + * @return The hash code for this <code>Expression</code>. + * @see #equals + * @see java.util.Hashtable + * @see java.lang.Object#hashCode() + */ public abstract int hashCode(); - public abstract String getExpressionString(); - + /** + * Returns whether this expression was created from only literal text. + * + * <p>This method must return <code>true</code> if and only if the + * expression string this expression was created from contained no + * unescaped EL delimeters (<code>${...}</code> or + * <code>#{...}</code>).</p> + * + * @return <code>true</code> if this expression was created from only + * literal text; <code>false</code> otherwise. + */ public abstract boolean isLiteralText(); +} -} Modified: trunk/java/javax/el/ExpressionFactory.java =================================================================== --- trunk/java/javax/el/ExpressionFactory.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/ExpressionFactory.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,13 +1,50 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. @@ -18,23 +55,271 @@ package javax.el; /** - * - * @since 2.1 + * Parses a <code>String</code> into a {@link ValueExpression} or + * {@link MethodExpression} instance for later evaluation. + * + * <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 + * instance of the implementation. + * Technologies such as + * JavaServer Pages and JavaServer Faces provide access to an + * implementation via factory methods.</p> + * + * <p>The {@link #createValueExpression} method is used to parse expressions + * that evaluate to values (both l-values and r-values are supported). + * 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> + * + * <p>The ELContext object also provides access to the {@link FunctionMapper} + * and {@link VariableMapper} to be used when parsing the expression. + * EL function and variable mapping is performed at parse-time, and + * the results are + * bound to the expression. Therefore, the {@link ELContext}, + * {@link FunctionMapper}, + * and {@link VariableMapper} + * are not stored for future use and do not have to be + * <code>Serializable</code>.</p> + * + * <p>The <code>createValueExpression</code> and + * <code>createMethodExpression</code> methods must be thread-safe. That is, + * multiple threads may call these methods on the same + * <code>ExpressionFactory</code> object simultaneously. Implementations + * should synchronize access if they depend on transient state. + * Implementations should not, however, assume that only one object of + * each <code>ExpressionFactory</code> type will be instantiated; global + * caching should therefore be static.</p> + * + * <p>The <code>ExpressionFactory</code> must be able to handle the following + * types of input for the <code>expression</code> parameter: + * <ul> + * <li>Single expressions using the <code>${}</code> delimiter + * (e.g. <code>"${employee.lastName}"</code>).</li> + * <li>Single expressions using the <code>#{}</code> delimiter + * (e.g. <code>"#{employee.lastName}"</code>).</li> + * <li>Literal text containing no <code>${}</code> or <code>#{}</code> + * delimiters (e.g. <code>"John Doe"</code>).</li> + * <li>Multiple expressions using the same delimiter (e.g. + * <code>"${employee.firstName}${employee.lastName}"</code> or + * <code>"#{employee.firstName}#{employee.lastName}"</code>).</li> + * <li>Mixed literal text and expressions using the same delimiter (e.g. + * <code>"Name: ${employee.firstName} ${employee.lastName}"</code>).</li> + * </ul></p> + * + * <p>The following types of input are illegal and must cause an + * {@link ELException} to be thrown: + * <ul> + * <li>Multiple expressions using different delimiters (e.g. + * <code>"${employee.firstName}#{employee.lastName}"</code>).</li> + * <li>Mixed literal text and expressions using different delimiters(e.g. + * <code>"Name: ${employee.firstName} #{employee.lastName}"</code>).</li> + * </ul></p> + * + * @since JSP 2.1 */ + +import java.util.Properties; + public abstract class ExpressionFactory { + + /** + * Creates a new instance of a <code>ExpressionFactory</code>. + * This method uses the following ordered lookup procedure to determine + * the <code>ExpressionFactory</code> implementation class to load: + * <ul> + * <li>Use the Services API (as detailed in the JAR specification). + * If a resource with the name of + * <code>META-INF/services/javax.el.ExpressionFactory</code> exists, + * then its first line, if present, is used as the UTF-8 encoded name of + * the implementation class. </li> + * <li>Use the properties file "lib/el.properties" in the JRE directory. + * If this file exists and it is readable by the + * <code> java.util.Properties.load(InputStream)</code> method, + * and it contains an entry whose key is "javax.el.ExpressionFactory", + * then the value of that entry is used as the name of the + * implementation class.</li> + * <li>Use the <code>javax.el.ExpressionFactory</code> system property. + * If a system property with this name is defined, then its value is + * used as the name of the implementation class.</li> + * <li>Use a platform default implementation.</li> + * </ul> + */ + public static ExpressionFactory newInstance() { + return ExpressionFactory.newInstance(null); + } - public abstract Object coerceToType(Object obj, Class<?> expectedType) - throws ELException; + /** + * <p>Create a new instance of a <code>ExpressionFactory</code>, with + * optional properties. + * This method uses the same lookup procedure as the one used in + * <code>newInstance()</code>. + * </p> + * <p> + * If the argument <code>properties</code> is not null, and if the + * implementation contains a constructor with a single parameter of + * type <code>java.util.Properties</code>, then the constructor is used + * to create the instance. + * </p> + * <p> + * Properties are optional and can be ignored by an implementation. + * </p> + * <p>The name of a property should start with "javax.el."</p> + * <p> + * The following are some suggested names for properties. + * <ul> + * <li>javax.el.cacheSize</li> + * </ul></p> + * + * @param properties Properties passed to the implementation. + * If null, then no properties. + */ + public static ExpressionFactory newInstance(Properties properties) { + return (ExpressionFactory) FactoryFinder.find( + "javax.el.ExpressionFactory", + "com.sun.el.ExpressionFactoryImpl", + properties); + } - public abstract ValueExpression createValueExpression(ELContext context, - String expression, Class<?> expectedType) - throws NullPointerException, ELException; - - public abstract ValueExpression createValueExpression(Object instance, + /** + * Parses an expression into a {@link ValueExpression} for later + * evaluation. Use this method for expressions that refer to values. + * + * <p>This method should perform syntactic validation of the expression. + * If in doing so it detects errors, it should raise an + * <code>ELException</code>.</p> + * + * @param context The EL context used to parse the expression. + * The <code>FunctionMapper</code> and <code>VariableMapper</code> + * stored in the ELContext + * are used to resolve functions and variables found in + * the expression. They can be <code>null</code>, in which case + * functions or variables are not supported for this expression. + * The object + * returned must invoke the same functions and access the same + * variable mappings + * regardless of whether + * the mappings in the provided <code>FunctionMapper</code> + * and <code>VariableMapper</code> instances + * change between calling + * <code>ExpressionFactory.createValueExpression()</code> and any + * method on <code>ValueExpression</code>. + * <p> + * Note that within the EL, the ${} and #{} syntaxes are treated identically. + * This includes the use of VariableMapper and FunctionMapper at expression creation + * time. Each is invoked if not null, independent + * of whether the #{} or ${} syntax is used for the expression.</p> + * @param expression The expression to parse + * @param expectedType The type the result of the expression + * will be coerced to after evaluation. + * @return The parsed expression + * @throws NullPointerException Thrown if expectedType is null. + * @throws ELException Thrown if there are syntactical errors in the + * provided expression. + */ + public abstract ValueExpression createValueExpression( + ELContext context, + String expression, Class<?> expectedType); + + /** + * Creates a ValueExpression that wraps an object instance. This + * method can be used to pass any object as a ValueExpression. The + * wrapper ValueExpression is read only, and returns the wrapped + * object via its <code>getValue()</code> method, optionally coerced. + * + * @param instance The object instance to be wrapped. + * @param expectedType The type the result of the expression + * will be coerced to after evaluation. There will be no + * coercion if it is Object.class, + * @throws NullPointerException Thrown if expectedType is null. + */ + public abstract ValueExpression createValueExpression( + Object instance, + Class<?> expectedType); - public abstract MethodExpression createMethodExpression(ELContext context, - String expression, Class<?> expectedReturnType, - Class<?>[] expectedParamTypes) throws ELException, - NullPointerException; + /** + * Parses an expression into a {@link MethodExpression} for later + * evaluation. Use this method for expressions that refer to methods. + * + * <p> + * If the expression is a String literal, a <code>MethodExpression + * </code> is created, which when invoked, returns the String literal, + * coerced to expectedReturnType. An ELException is thrown if + * expectedReturnType is void or if the coercion of the String literal + * to the expectedReturnType yields an error (see Section "1.16 Type + * Conversion"). + * </p> + * <p>This method should perform syntactic validation of the expression. + * If in doing so it detects errors, it should raise an + * <code>ELException</code>.</p> + * + * @param context The EL context used to parse the expression. + * The <code>FunctionMapper</code> and <code>VariableMapper</code> + * stored in the ELContext + * are used to resolve functions and variables found in + * the expression. They can be <code>null</code>, in which + * case functions or variables are not supported for this expression. + * The object + * returned must invoke the same functions and access the same variable + * mappings + * regardless of whether + * the mappings in the provided <code>FunctionMapper</code> + * and <code>VariableMapper</code> instances + * change between calling + * <code>ExpressionFactory.createMethodExpression()</code> and any + * method on <code>MethodExpression</code>. + * <p> + * Note that within the EL, the ${} and #{} syntaxes are treated identically. + * This includes the use of VariableMapper and FunctionMapper at expression creation + * time. Each is invoked if not null, independent + * of whether the #{} or ${} syntax is used for the expression.</p> + * + * @param expression The expression to parse + * @param expectedReturnType The expected return type for the method + * to be found. After evaluating the expression, the + * <code>MethodExpression</code> must check that the return type of + * the actual method matches this type. Passing in a value of + * <code>null</code> indicates the caller does not care what the + * return type is, and the check is disabled. + * @param expectedParamTypes The expected parameter types for the method to + * be found. Must be an array with no elements if there are + * no parameters expected. It is illegal to pass <code>null</code>. + * @return The parsed expression + * @throws ELException Thrown if there are syntactical errors in the + * provided expression. + * @throws NullPointerException if paramTypes is <code>null</code>. + */ + public abstract MethodExpression createMethodExpression( + ELContext context, + String expression, + Class<?> expectedReturnType, + Class<?>[] expectedParamTypes); + + /** + * Coerces an object to a specific type according to the + * EL type conversion rules. + * + * <p>An <code>ELException</code> is thrown if an error results from + * applying the conversion rules. + * </p> + * + * @param obj The object to coerce. + * @param targetType The target type for the coercion. + * @throws ELException thrown if an error results from applying the + * conversion rules. + */ + public abstract Object coerceToType( + Object obj, + Class<?> targetType); + } + + Added: trunk/java/javax/el/FactoryFinder.java =================================================================== --- trunk/java/javax/el/FactoryFinder.java (rev 0) +++ trunk/java/javax/el/FactoryFinder.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -0,0 +1,196 @@ +/* + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ + +package javax.el; + +import java.lang.reflect.Constructor; +import java.io.InputStream; +import java.io.File; +import java.io.FileInputStream; +import java.util.Properties; +import java.io.BufferedReader; +import java.io.InputStreamReader; + +class FactoryFinder { + + /** + * Creates an instance of the specified class using the specified + * <code>ClassLoader</code> object. + * + * @exception ELException if the given class could not be found + * or could not be instantiated + */ + private static Object newInstance(String className, + ClassLoader classLoader, + Properties properties) + { + try { + Class spiClass; + if (classLoader == null) { + spiClass = Class.forName(className); + } else { + spiClass = classLoader.loadClass(className); + } + if (properties != null) { + Constructor constr = null; + try { + constr = spiClass.getConstructor(Properties.class); + } catch (Exception ex) { + } + if (constr != null) { + return constr.newInstance(properties); + } + } + return spiClass.newInstance(); + } catch (ClassNotFoundException x) { + throw new ELException( + "Provider " + className + " not found", x); + } catch (Exception x) { + throw new ELException( + "Provider " + className + " could not be instantiated: " + x, + x); + } + } + + /** + * Finds the implementation <code>Class</code> object for the given + * factory name, or if that fails, finds the <code>Class</code> object + * for the given fallback class name. The arguments supplied must be + * used in order. If using the first argument is successful, the second + * one will not be used. + * <P> + * This method is package private so that this code can be shared. + * + * @return the <code>Class</code> object of the specified message factory; + * may not be <code>null</code> + * + * @param factoryId the name of the factory to find, which is + * a system property + * @param fallbackClassName the implementation class name, which is + * to be used only if nothing else + * is found; <code>null</code> to indicate that + * there is no fallback class name + * @exception ELException if there is an error + */ + static Object find(String factoryId, String fallbackClassName, + Properties properties) + { + ClassLoader classLoader; + try { + classLoader = Thread.currentThread().getContextClassLoader(); + } catch (Exception x) { + throw new ELException(x.toString(), x); + } + + String serviceId = "META-INF/services/" + factoryId; + // try to find services in CLASSPATH + try { + InputStream is=null; + if (classLoader == null) { + is=ClassLoader.getSystemResourceAsStream(serviceId); + } else { + is=classLoader.getResourceAsStream(serviceId); + } + + if( is!=null ) { + BufferedReader rd = + new BufferedReader(new InputStreamReader(is, "UTF-8")); + + String factoryClassName = rd.readLine(); + rd.close(); + + if (factoryClassName != null && + ! "".equals(factoryClassName)) { + return newInstance(factoryClassName, classLoader, properties); + } + } + } catch( Exception ex ) { + } + + + // try to read from $java.home/lib/el.properties + try { + String javah=System.getProperty( "java.home" ); + String configFile = javah + File.separator + + "lib" + File.separator + "el.properties"; + File f=new File( configFile ); + if( f.exists()) { + Properties props=new Properties(); + props.load( new FileInputStream(f)); + String factoryClassName = props.getProperty(factoryId); + return newInstance(factoryClassName, classLoader, properties); + } + } catch(Exception ex ) { + } + + + // Use the system property + try { + String systemProp = + System.getProperty( factoryId ); + if( systemProp!=null) { + return newInstance(systemProp, classLoader, properties); + } + } catch (SecurityException se) { + } + + if (fallbackClassName == null) { + throw new ELException( + "Provider for " + factoryId + " cannot be found", null); + } + + return newInstance(fallbackClassName, classLoader, properties); + } +} + Modified: trunk/java/javax/el/FunctionMapper.java =================================================================== --- trunk/java/javax/el/FunctionMapper.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/FunctionMapper.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,13 +1,50 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. @@ -17,13 +54,32 @@ package javax.el; -import java.lang.reflect.Method; - /** + * The interface to a map between EL function names and methods. * + * <p>A <code>FunctionMapper</code> maps <code>${prefix:name()}</code> + * style functions to a static method that can execute that function.</p> + * + * @since JSP 2.1 */ public abstract class FunctionMapper { - - public abstract Method resolveFunction(String prefix, String localName); + /** + * Resolves the specified prefix and local name into a + * <code>java.lang.Method</code>. + * + * <p>Returns <code>null</code> if no function could be found that matches + * the given prefix and local name.</p> + * + * @param prefix the prefix of the function, or "" if no prefix. + * For example, <code>"fn"</code> in <code>${fn:method()}</code>, or + * <code>""</code> in <code>${method()}</code>. + * @param localName the short name of the function. For example, + * <code>"method"</code> in <code>${fn:method()}</code>. + * @return the static method to invoke, or <code>null</code> if no + * match was found. + */ + public abstract java.lang.reflect.Method resolveFunction(String prefix, + String localName); + } Modified: trunk/java/javax/el/ListELResolver.java =================================================================== --- trunk/java/javax/el/ListELResolver.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/ListELResolver.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,171 +1,414 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; +import java.util.List; +import java.util.Iterator; +import java.util.Collections; +import java.util.ArrayList; import java.beans.FeatureDescriptor; -import java.util.ArrayList; -import java.util.Arrays; -import java.util.Collections; -import java.util.Iterator; -import java.util.List; + +/** + * Defines property resolution behavior on instances of {@link java.util.List}. + * + * <p>This resolver handles base objects of type <code>java.util.List</code>. + * It accepts any object as a property and coerces that object into an + * integer index into the list. The resulting value is the value in the list + * at that index.</p> + * + * <p>This resolver can be constructed in read-only mode, which means that + * {@link #isReadOnly} will always return <code>true</code> and + * {@link #setValue} will always throw + * <code>PropertyNotWritableException</code>.</p> + * + * <p><code>ELResolver</code>s are combined together using + * {@link CompositeELResolver}s, to define rich semantics for evaluating + * an expression. See the javadocs for {@link ELResolver} for details.</p> + * + * @see CompositeELResolver + * @see ELResolver + * @see java.util.List + * @since JSP 2.1 + */ public class ListELResolver extends ELResolver { - private final boolean readOnly; + /** + * Creates a new read/write <code>ListELResolver</code>. + */ + public ListELResolver() { + this.isReadOnly = false; + } - private final static Class UNMODIFIABLE = Collections.unmodifiableList( - new ArrayList()).getClass(); + /** + * Creates a new <code>ListELResolver</code> whose read-only status is + * determined by the given parameter. + * + * @param isReadOnly <code>true</code> if this resolver cannot modify + * lists; <code>false</code> otherwise. + */ + public ListELResolver(boolean isReadOnly) { + this.isReadOnly = isReadOnly; + } - public ListELResolver() { - this.readOnly = false; - } + /** + * If the base object is a list, returns the most general acceptable type + * for a value in this list. + * + * <p>If the base is a <code>List</code>, 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> + * + * <p>Assuming the base is a <code>List</code>, this method will always + * return <code>Object.class</code>. This is because <code>List</code>s + * accept any object as an element.</p> + * + * @param context The context of this evaluation. + * @param base The list to analyze. Only bases of type <code>List</code> + * are handled by this resolver. + * @param property The index of the element in the list to return the + * acceptable type for. Will be coerced into an integer, but + * otherwise ignored by this resolver. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the most general acceptable type; otherwise undefined. + * @throws PropertyNotFoundException if the given index is out of + * bounds for this list. + * @throws NullPointerException if context is <code>null</code> + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Class<?> getType(ELContext context, + Object base, + Object property) { - public ListELResolver(boolean readOnly) { - this.readOnly = readOnly; - } + if (context == null) { + throw new NullPointerException(); + } - public Object getValue(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + if (base != null && base instanceof List) { + context.setPropertyResolved(true); + List list = (List) base; + int index = toInteger(property); + if (index < 0 || index >= list.size()) { + throw new PropertyNotFoundException(); + } + return Object.class; + } + return null; + } - if (base instanceof List) { - context.setPropertyResolved(true); - List list = (List) base; - int idx = coerce(property); - if (idx < 0 || idx >= list.size()) { - return null; - } - return list.get(idx); - } + /** + * If the base object is a list, returns the value at the given index. + * The index is specified by the <code>property</code> argument, and + * coerced into an integer. If the coercion could not be performed, + * an <code>IllegalArgumentException</code> is thrown. If the index is + * out of bounds, <code>null</code> is returned. + * + * <p>If the base is a <code>List</code>, 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> + * + * @param context The context of this evaluation. + * @param base The list to be analyzed. Only bases of type + * <code>List</code> are handled by this resolver. + * @param property The index of the value to be returned. Will be coerced + * into an integer. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the value at the given index or <code>null</code> + * if the index was out of bounds. Otherwise, undefined. + * @throws IllegalArgumentException if the property could not be coerced + * into an integer. + * @throws NullPointerException if context is <code>null</code>. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Object getValue(ELContext context, + Object base, + Object property) { - return null; - } + if (context == null) { + throw new NullPointerException(); + } - public Class<?> getType(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + if (base != null && base instanceof List) { + context.setPropertyResolved(true); + List list = (List) base; + int index = toInteger(property); + if (index < 0 || index >= list.size()) { + return null; + } + return list.get(index); + } + return null; + } - if (base instanceof List) { - context.setPropertyResolved(true); - List list = (List) base; - int idx = coerce(property); - if (idx < 0 || idx >= list.size()) { - return null; - } - Object obj = list.get(idx); - return (obj != null) ? obj.getClass() : null; - } + /** + * If the base object is a list, attempts to set the value at the + * given index with the given value. The index is specified by the + * <code>property</code> argument, and coerced into an integer. If the + * coercion could not be performed, an + * <code>IllegalArgumentException</code> is thrown. If the index is + * out of bounds, a <code>PropertyNotFoundException</code> is thrown. + * + * <p>If the base is a <code>List</code>, 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 + * can safely assume no value was set.</p> + * + * <p>If this resolver was constructed in read-only mode, this method will + * always throw <code>PropertyNotWritableException</code>.</p> + * + * <p>If a <code>List</code> was created using + * {@link java.util.Collections#unmodifiableList}, this method must + * throw <code>PropertyNotWritableException</code>. Unfortunately, + * there is no Collections API method to detect this. However, an + * implementation can create a prototype unmodifiable <code>List</code> + * and query its runtime type to see if it matches the runtime type of + * the base object as a workaround.</p> + * + * @param context The context of this evaluation. + * @param base The list to be modified. Only bases of type + * <code>List</code> are handled by this resolver. + * @param property The index of the value to be set. Will be coerced + * into an integer. + * @param val The value to be set at the given index. + * @throws ClassCastException if the class of the specified element + * prevents it from being added to this list. + * @throws NullPointerException if context is <code>null</code>, or + * if the value is <code>null</code> and this <code>List</code> + * does not support <code>null</code> elements. + * @throws IllegalArgumentException if the property could not be coerced + * into an integer, or if some aspect of the specified element + * prevents it from being added to this list. + * @throws PropertyNotWritableException if this resolver was constructed + * in read-only mode, or if the set operation is not supported by + * the underlying list. + * @throws PropertyNotFoundException if the given index is out of + * bounds for this list. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public void setValue(ELContext context, + Object base, + Object property, + Object val) { - return null; - } + if (context == null) { + throw new NullPointerException(); + } - public void setValue(ELContext context, Object base, Object property, - Object value) throws NullPointerException, - PropertyNotFoundException, PropertyNotWritableException, - ELException { - if (context == null) { - throw new NullPointerException(); - } + if (base != null && base instanceof List) { + context.setPropertyResolved(true); + List list = (List) base; + int index = toInteger(property); + if (isReadOnly) { + throw new PropertyNotWritableException(); + } + try { + list.set(index, val); + } catch (UnsupportedOperationException ex) { + throw new PropertyNotWritableException(); + } catch (IndexOutOfBoundsException ex) { + throw new PropertyNotFoundException(); + } catch (ClassCastException ex) { + throw ex; + } catch (NullPointerException ex) { + throw ex; + } catch (IllegalArgumentException ex) { + throw ex; + } + } + } - if (base instanceof List) { - context.setPropertyResolved(true); - List list = (List) base; + static private Class<?> theUnmodifiableListClass = + Collections.unmodifiableList(new ArrayList()).getClass(); - if (this.readOnly) { - throw new PropertyNotWritableException(message(context, - "resolverNotWriteable", new Object[] { base.getClass() - .getName() })); - } + /** + * If the base object is a list, returns whether a call to + * {@link #setValue} will always fail. + * + * <p>If the base is a <code>List</code>, 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> + * + * <p>If this resolver was constructed in read-only mode, this method will + * always return <code>true</code>.</p> + * + * <p>If a <code>List</code> was created using + * {@link java.util.Collections#unmodifiableList}, this method must + * return <code>true</code>. Unfortunately, there is no Collections API + * method to detect this. However, an implementation can create a + * prototype unmodifiable <code>List</code> and query its runtime type + * to see if it matches the runtime type of the base object as a + * workaround.</p> + * + * @param context The context of this evaluation. + * @param base The list to analyze. Only bases of type <code>List</code> + * are handled by this resolver. + * @param property The index of the element in the list to return the + * acceptable type for. Will be coerced into an integer, but + * otherwise ignored by this resolver. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>true</code> if calling the <code>setValue</code> method + * will always fail or <code>false</code> if it is possible that + * such a call may succeed; otherwise undefined. + * @throws PropertyNotFoundException if the given index is out of + * bounds for this list. + * @throws NullPointerException if context is <code>null</code> + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public boolean isReadOnly(ELContext context, + Object base, + Object property) { - int idx = coerce(property); - try { - list.set(idx, value); - } catch (UnsupportedOperationException e) { - throw new PropertyNotWritableException(e); - } catch (IndexOutOfBoundsException e) { - throw new PropertyNotFoundException(e); - } - } - } + if (context == null) { + throw new NullPointerException(); + } - public boolean isReadOnly(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + if (base != null && base instanceof List) { + context.setPropertyResolved(true); + List list = (List) base; + int index = toInteger(property); + if (index < 0 || index >= list.size()) { + throw new PropertyNotFoundException(); + } + return list.getClass() == theUnmodifiableListClass || isReadOnly; + } + return false; + } - if (base instanceof List) { - context.setPropertyResolved(true); - List list = (List) base; - int idx = coerce(property); - if (idx < 0 || idx >= list.size()) { - throw new PropertyNotFoundException( - new ArrayIndexOutOfBoundsException(idx).getMessage()); - } - return this.readOnly || UNMODIFIABLE.equals(list.getClass()); - } + /** + * Always returns <code>null</code>, since there is no reason to + * iterate through set set of all integers. + * + * <p>The {@link #getCommonPropertyType} method returns sufficient + * information about what properties this resolver accepts.</p> + * + * @param context The context of this evaluation. + * @param base The list. Only bases of type <code>List</code> are + * handled by this resolver. + * @return <code>null</code>. + */ + public Iterator<FeatureDescriptor> getFeatureDescriptors( + ELContext context, + Object base) { + return null; + } - return this.readOnly; - } + /** + * If the base object is a list, returns the most general type that + * this resolver accepts for the <code>property</code> argument. + * Otherwise, returns <code>null</code>. + * + * <p>Assuming the base is a <code>List</code>, this method will always + * return <code>Integer.class</code>. This is because <code>List</code>s + * accept integers as their index.</p> + * + * @param context The context of this evaluation. + * @param base The list to analyze. Only bases of type <code>List</code> + * are handled by this resolver. + * @return <code>null</code> if base is not a <code>List</code>; otherwise + * <code>Integer.class</code>. + */ + public Class<?> getCommonPropertyType(ELContext context, + Object base) { + if (base != null && base instanceof List) { + return Integer.class; + } + return null; + } + + private int toInteger(Object p) { + if (p instanceof Integer) { + return ((Integer) p).intValue(); + } + if (p instanceof Character) { + return ((Character) p).charValue(); + } + if (p instanceof Boolean) { + return ((Boolean) p).booleanValue()? 1: 0; + } + if (p instanceof Number) { + return ((Number) p).intValue(); + } + if (p instanceof String) { + return Integer.parseInt((String) p); + } + throw new IllegalArgumentException(); + } - public Iterator<FeatureDescriptor> getFeatureDescriptors(ELContext context, Object base) { - if (base instanceof List) { - FeatureDescriptor[] descs = new FeatureDescriptor[((List) base).size()]; - for (int i = 0; i < descs.length; i++) { - descs[i] = new FeatureDescriptor(); - descs[i].setDisplayName("["+i+"]"); - descs[i].setExpert(false); - descs[i].setHidden(false); - descs[i].setName(""+i); - descs[i].setPreferred(true); - descs[i].setValue(RESOLVABLE_AT_DESIGN_TIME, Boolean.FALSE); - descs[i].setValue(TYPE, Integer.class); - } - return Arrays.asList(descs).iterator(); - } - return null; - } + private boolean isReadOnly; +} - public Class<?> getCommonPropertyType(ELContext context, Object base) { - if (base != null && base instanceof List) { - return Integer.class; - } - return null; - } - - private final static int coerce(Object property) { - if (property instanceof Number) { - return ((Number) property).intValue(); - } - if (property instanceof Character) { - return ((Character) property).charValue(); - } - if (property instanceof Boolean) { - return (((Boolean) property).booleanValue() ? 1 : 0); - } - if (property instanceof String) { - return Integer.parseInt((String) property); - } - throw new IllegalArgumentException(property != null ? property - .toString() : "null"); - } -} Deleted: trunk/java/javax/el/LocalStrings.properties =================================================================== --- trunk/java/javax/el/LocalStrings.properties 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/LocalStrings.properties 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,24 +0,0 @@ -# Licensed to the Apache Software Foundation (ASF) under one or more -# contributor license agreements. See the NOTICE file distributed with -# this work for additional information regarding copyright ownership. -# The ASF licenses this file to You 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. - -# Default localized string information -# Localized for Locale en_US - -propertyNotFound=Property ''{1}'' not found on type {0} -propertyNotReadable=Property ''{1}'' not readable on type {0} -propertyNotWritable=Property ''{1}'' not writable on type {0} -propertyReadError=Error reading ''{1}'' on type {0} -propertyWriteError=Error writing ''{1}'' on type {0} -resolverNotWritable=ELResolver not writable for type {0} Deleted: trunk/java/javax/el/LocalStrings_es.properties =================================================================== --- trunk/java/javax/el/LocalStrings_es.properties 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/LocalStrings_es.properties 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,6 +0,0 @@ -propertyNotFound = Propiedad ''{1}'' no hallada en el tipo {0} -propertyNotReadable = Propiedad ''{1}'' no legible para el tipo {0} -propertyNotWritable = Propiedad ''{1}'' no grabable para el tipo {0} -propertyReadError = Error reading ''{1}'' en el tipo {0} -propertyWriteError = Error writing ''{1}'' en el tipo {0} -resolverNotWritable = ELResolver no grabable para el tipo {0} Modified: trunk/java/javax/el/MapELResolver.java =================================================================== --- trunk/java/javax/el/MapELResolver.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/MapELResolver.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,141 +1,411 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; import java.beans.FeatureDescriptor; -import java.util.ArrayList; +import java.util.Map; +import java.util.Iterator; import java.util.Collections; import java.util.HashMap; -import java.util.Iterator; import java.util.List; -import java.util.Map; +import java.util.ArrayList; +/** + * Defines property resolution behavior on instances of {@link java.util.Map}. + * + * <p>This resolver handles base objects of type <code>java.util.Map</code>. + * It accepts any object as a property and uses that object as a key in + * the map. The resulting value is the value in the map that is associated with + * that key.</p> + * + * <p>This resolver can be constructed in read-only mode, which means that + * {@link #isReadOnly} will always return <code>true</code> and + * {@link #setValue} will always throw + * <code>PropertyNotWritableException</code>.</p> + * + * <p><code>ELResolver</code>s are combined together using + * {@link CompositeELResolver}s, to define rich semantics for evaluating + * an expression. See the javadocs for {@link ELResolver} for details.</p> + * + * @see CompositeELResolver + * @see ELResolver + * @see java.util.Map + * @since JSP 2.1 + */ public class MapELResolver extends ELResolver { - private final static Class UNMODIFIABLE = Collections.unmodifiableMap( - new HashMap()).getClass(); + /** + * Creates a new read/write <code>MapELResolver</code>. + */ + public MapELResolver() { + this.isReadOnly = false; + } - private final boolean readOnly; + /** + * Creates a new <code>MapELResolver</code> whose read-only status is + * determined by the given parameter. + * + * @param isReadOnly <code>true</code> if this resolver cannot modify + * maps; <code>false</code> otherwise. + */ + public MapELResolver(boolean isReadOnly) { + this.isReadOnly = isReadOnly; + } - public MapELResolver() { - this.readOnly = false; - } + /** + * If the base object is a map, returns the most general acceptable type + * for a value in this map. + * + * <p>If the base is a <code>Map</code>, 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> + * + * <p>Assuming the base is a <code>Map</code>, this method will always + * return <code>Object.class</code>. This is because <code>Map</code>s + * accept any object as the value for a given key.</p> + * + * @param context The context of this evaluation. + * @param base The map to analyze. Only bases of type <code>Map</code> + * are handled by this resolver. + * @param property The key to return the acceptable type for. + * Ignored by this resolver. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the most general acceptable type; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Class<?> getType(ELContext context, + Object base, + Object property) { - public MapELResolver(boolean readOnly) { - this.readOnly = readOnly; - } + if (context == null) { + throw new NullPointerException(); + } + + if (base != null && base instanceof Map) { + context.setPropertyResolved(true); + return Object.class; + } + return null; + } - public Object getValue(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + /** + * If the base object is a map, returns the value associated with the + * given key, as specified by the <code>property</code> argument. If the + * key was not found, <code>null</code> is returned. + * + * <p>If the base is a <code>Map</code>, 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> + * + * <p>Just as in {@link java.util.Map#get}, just because <code>null</code> + * is returned doesn't mean there is no mapping for the key; it's also + * possible that the <code>Map</code> explicitly maps the key to + * <code>null</code>.</p> + * + * @param context The context of this evaluation. + * @param base The map to be analyzed. Only bases of type <code>Map</code> + * are handled by this resolver. + * @param property The key whose associated value is to be returned. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the value associated with the given key or <code>null</code> + * if the key was not found. Otherwise, undefined. + * @throws ClassCastException if the key is of an inappropriate type + * for this map (optionally thrown by the underlying <code>Map</code>). + * @throws NullPointerException if context is <code>null</code>, or if + * the key is null and this map does not permit null keys (the + * latter is optionally thrown by the underlying <code>Map</code>). + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Object getValue(ELContext context, + Object base, + Object property) { - if (base instanceof Map) { - context.setPropertyResolved(true); - return ((Map) base).get(property); - } - - return null; - } + if (context == null) { + throw new NullPointerException(); + } - public Class<?> getType(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + if (base != null && base instanceof Map) { + context.setPropertyResolved(true); + Map map = (Map) base; + return map.get(property); + } + return null; + } - if (base instanceof Map) { - context.setPropertyResolved(true); - Object obj = ((Map) base).get(property); - return (obj != null) ? obj.getClass() : null; - } - - return null; - } + static private Class<?> theUnmodifiableMapClass = + Collections.unmodifiableMap(new HashMap()).getClass(); - public void setValue(ELContext context, Object base, Object property, - Object value) throws NullPointerException, - PropertyNotFoundException, PropertyNotWritableException, - ELException { - if (context == null) { - throw new NullPointerException(); - } + /** + * If the base object is a map, attempts to set the value associated with + * the given key, as specified by the <code>property</code> argument. + * + * <p>If the base is a <code>Map</code>, 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 + * can safely assume no value was set.</p> + * + * <p>If this resolver was constructed in read-only mode, this method will + * always throw <code>PropertyNotWritableException</code>.</p> + * + * <p>If a <code>Map</code> was created using + * {@link java.util.Collections#unmodifiableMap}, this method must + * throw <code>PropertyNotWritableException</code>. Unfortunately, + * there is no Collections API method to detect this. However, an + * implementation can create a prototype unmodifiable <code>Map</code> + * and query its runtime type to see if it matches the runtime type of + * the base object as a workaround.</p> + * + * @param context The context of this evaluation. + * @param base The map to be modified. Only bases of type <code>Map</code> + * are handled by this resolver. + * @param property The key with which the specified value is to be + * associated. + * @param val The value to be associated with the specified key. + * @throws ClassCastException if the class of the specified key or + * value prevents it from being stored in this map. + * @throws NullPointerException if context is <code>null</code>, or if + * this map does not permit <code>null</code> keys or values, and + * the specified key or value is <code>null</code>. + * @throws IllegalArgumentException if some aspect of this key or + * value prevents it from being stored in this map. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + * @throws PropertyNotWritableException if this resolver was constructed + * in read-only mode, or if the put operation is not supported by + * the underlying map. + */ + public void setValue(ELContext context, + Object base, + Object property, + Object val) { - if (base instanceof Map) { - context.setPropertyResolved(true); + if (context == null) { + throw new NullPointerException(); + } - if (this.readOnly) { - throw new PropertyNotWritableException(message(context, - "resolverNotWriteable", new Object[] { base.getClass() - .getName() })); - } + if (base != null && base instanceof Map) { + context.setPropertyResolved(true); + Map map = (Map) base; + if (isReadOnly || map.getClass() == theUnmodifiableMapClass) { + throw new PropertyNotWritableException(); + } + try { + map.put(property, val); + } catch (UnsupportedOperationException ex) { + throw new PropertyNotWritableException(); + } + } + } - try { - ((Map) base).put(property, value); - } catch (UnsupportedOperationException e) { - throw new PropertyNotWritableException(e); - } - } - } + /** + * If the base object is a map, returns whether a call to + * {@link #setValue} will always fail. + * + * <p>If the base is a <code>Map</code>, 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> + * + * <p>If this resolver was constructed in read-only mode, this method will + * always return <code>true</code>.</p> + * + * <p>If a <code>Map</code> was created using + * {@link java.util.Collections#unmodifiableMap}, this method must + * return <code>true</code>. Unfortunately, there is no Collections API + * method to detect this. However, an implementation can create a + * prototype unmodifiable <code>Map</code> and query its runtime type + * to see if it matches the runtime type of the base object as a + * workaround.</p> + * + * @param context The context of this evaluation. + * @param base The map to analyze. Only bases of type <code>Map</code> + * are handled by this resolver. + * @param property The key to return the read-only status for. + * Ignored by this resolver. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>true</code> if calling the <code>setValue</code> method + * will always fail or <code>false</code> if it is possible that + * such a call may succeed; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public boolean isReadOnly(ELContext context, + Object base, + Object property) { - public boolean isReadOnly(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + if (context == null) { + throw new NullPointerException(); + } - if (base instanceof Map) { - context.setPropertyResolved(true); - return this.readOnly || UNMODIFIABLE.equals(base.getClass()); - } - - return this.readOnly; - } + if (base != null && base instanceof Map) { + context.setPropertyResolved(true); + Map map = (Map) base; + return isReadOnly || map.getClass() == theUnmodifiableMapClass; + } + return false; + } - public Iterator<FeatureDescriptor> getFeatureDescriptors(ELContext context, Object base) { - if (base instanceof Map) { - Iterator itr = ((Map) base).keySet().iterator(); - List<FeatureDescriptor> feats = new ArrayList<FeatureDescriptor>(); - Object key; - FeatureDescriptor desc; - while (itr.hasNext()) { - key = itr.next(); - desc = new FeatureDescriptor(); - desc.setDisplayName(key.toString()); - desc.setExpert(false); - desc.setHidden(false); - desc.setName(key.toString()); - desc.setPreferred(true); - desc.setValue(RESOLVABLE_AT_DESIGN_TIME, Boolean.FALSE); - desc.setValue(TYPE, key.getClass()); - feats.add(desc); - } - return feats.iterator(); - } - return null; - } + /** + * If the base object is a map, returns an <code>Iterator</code> + * containing the set of keys available in the <code>Map</code>. + * Otherwise, returns <code>null</code>. + * + * <p>The <code>Iterator</code> returned must contain zero or more + * instances of {@link java.beans.FeatureDescriptor}. Each info object + * contains information about a key in the Map, and is initialized as + * follows: + * <dl> + * <li>displayName - The return value of calling the + * <code>toString</code> method on this key, or + * <code>"null"</code> if the key is <code>null</code>.</li> + * <li>name - Same as displayName property.</li> + * <li>shortDescription - Empty string</li> + * <li>expert - <code>false</code></li> + * <li>hidden - <code>false</code></li> + * <li>preferred - <code>true</code></li> + * </dl> + * In addition, the following named attributes must be set in the + * returned <code>FeatureDescriptor</code>s: + * <dl> + * <li>{@link ELResolver#TYPE} - The return value of calling the <code>getClass()</code> + * method on this key, or <code>null</code> if the key is + * <code>null</code>.</li> + * <li>{@link ELResolver#RESOLVABLE_AT_DESIGN_TIME} - <code>true</code></li> + * </dl> + * </p> + * + * @param context The context of this evaluation. + * @param base The map whose keys are to be iterated over. Only bases + * of type <code>Map</code> are handled by this resolver. + * @return An <code>Iterator</code> containing zero or more (possibly + * infinitely more) <code>FeatureDescriptor</code> objects, each + * representing a key in this map, or <code>null</code> if + * the base object is not a map. + */ + public Iterator<FeatureDescriptor> getFeatureDescriptors( + ELContext context, + Object base) { - public Class<?> getCommonPropertyType(ELContext context, Object base) { - if (base instanceof Map) { - return Object.class; - } - return null; - } + if (base != null && base instanceof Map) { + Map map = (Map) base; + Iterator iter = map.keySet().iterator(); + List<FeatureDescriptor> list = new ArrayList<FeatureDescriptor>(); + while (iter.hasNext()) { + Object key = iter.next(); + FeatureDescriptor descriptor = new FeatureDescriptor(); + String name = (key==null)? null: key.toString(); + descriptor.setName(name); + descriptor.setDisplayName(name); + descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", key==null? null: key.getClass()); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + } + return list.iterator(); + } + return null; + } + /** + * If the base object is a map, returns the most general type that + * this resolver accepts for the <code>property</code> argument. + * Otherwise, returns <code>null</code>. + * + * <p>Assuming the base is a <code>Map</code>, this method will always + * return <code>Object.class</code>. This is because <code>Map</code>s + * accept any object as a key.</p> + * + * @param context The context of this evaluation. + * @param base The map to analyze. Only bases of type <code>Map</code> + * are handled by this resolver. + * @return <code>null</code> if base is not a <code>Map</code>; otherwise + * <code>Object.class</code>. + */ + public Class<?> getCommonPropertyType(ELContext context, + Object base) { + if (base != null && base instanceof Map) { + return Object.class; + } + return null; + } + + private boolean isReadOnly; } + Modified: trunk/java/javax/el/MethodExpression.java =================================================================== --- trunk/java/javax/el/MethodExpression.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/MethodExpression.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,28 +1,170 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; /** + * An <code>Expression</code> that refers to a method on an object. * + * <p>The {@link ExpressionFactory#createMethodExpression} method + * can be used to parse an expression string and return a concrete instance + * of <code>MethodExpression</code> that encapsulates the parsed expression. + * The {@link FunctionMapper} is used at parse time, not evaluation time, + * so one is not needed to evaluate an expression using this class. + * However, the {@link ELContext} is needed at evaluation time.</p> + * + * <p>The {@link #getMethodInfo} and {@link #invoke} methods will evaluate the + * expression each time they are called. The {@link ELResolver} in the + * <code>ELContext</code> is used to resolve the top-level variables and to + * determine the behavior of the <code>.</code> and <code>[]</code> + * operators. For any of the two methods, the {@link ELResolver#getValue} + * method is used to resolve all properties up to but excluding the last + * one. This provides the <code>base</code> object on which the method + * appears. If the <code>base</code> object is null, a + * <code>PropertyNotFoundException</code> must be thrown. + * At the last resolution, + * the final <code>property</code> is then coerced to a <code>String</code>, + * which provides the name of the method to be found. A method matching the + * name and expected parameters provided at parse time is found and it is + * either queried or invoked (depending on the method called on this + * <code>MethodExpression</code>).</p> + * + * <p>See the notes about comparison, serialization and immutability in + * the {@link Expression} javadocs. + * + * @see ELResolver + * @see Expression + * @see ExpressionFactory + * @since JSP 2.1 */ -public abstract class MethodExpression extends Expression { +public abstract class MethodExpression extends Expression +{ + // Evaluation + + /** + * Evaluates the expression relative to the provided context, and + * returns information about the actual referenced method. + * + * @param context The context of this evaluation + * @return an instance of <code>MethodInfo</code> containing information + * about the method the expression evaluated to. + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if one of the property + * resolutions failed because a specified variable or property + * does not exist or is not readable. + * @throws MethodNotFoundException if no suitable method can be found. + * @throws ELException if an exception was thrown while performing + * property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public abstract MethodInfo getMethodInfo(ELContext context); + + /** + * If a String literal is specified as the expression, returns the + * String literal coerced to the expected return type of the method + * signature. An <code>ELException</code> is thrown if + * <code>expectedReturnType</code> is void or if the coercion of the String literal + * to the <code>expectedReturnType</code> yields an error (see Section "1.18 Type + * Conversion" of the EL specification). + * + * If not a String literal, evaluates the expression + * relative to the provided context, invokes the method that was + * found using the supplied parameters, and returns the result of + * the method invocation. + * + * Any parameters passed to this method is ignored if isLiteralText() + * or isParametersProvided() is true. + * + * @param context The context of this evaluation. + * @param params The parameters to pass to the method, or + * <code>null</code> if no parameters. + * @return the result of the method invocation (<code>null</code> if + * the method has a <code>void</code> return type). + * @throws NullPointerException if context is <code>null</code> + * @throws PropertyNotFoundException if one of the property + * resolutions failed because a specified variable or property + * does not exist or is not readable. + * @throws MethodNotFoundException if no suitable method can be found. + * @throws ELException if a String literal is specified and + * expectedReturnType of the MethodExpression is void or if the coercion of the String literal + * to the expectedReturnType yields an error (see Section "1.18 Type + * Conversion"). + * @throws ELException if + * an exception was thrown while performing + * property or variable resolution. The thrown exception must be + * included as the cause property of this exception, if + * available. If the exception thrown is an + * <code>InvocationTargetException</code>, extract its + * <code>cause</code> and pass it to the + * <code>ELException</code> constructor. + */ + public abstract Object invoke(ELContext context, Object[] params); - public abstract MethodInfo getMethodInfo(ELContext context) throws NullPointerException, PropertyNotFoundException, MethodNotFoundException, ELException; - - public abstract Object invoke(ELContext context, Object[] params) throws NullPointerException, PropertyNotFoundException, MethodNotFoundException, ELException; + /** + * Return whether this MethodExpression was created with parameters. + * + * <p>This method must return <code>true</code> if and only if + * parameters are specified in the EL, using the + * expr-a.expr-b(...) syntax.</p> + * + * @return <code>true</code> if the MethodExpression was created with + * parameters, <code>false</code> otherwise. + * @since EL 2.2 + */ + public boolean isParmetersProvided() { + return false; + } } Modified: trunk/java/javax/el/MethodInfo.java =================================================================== --- trunk/java/javax/el/MethodInfo.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/MethodInfo.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,52 +1,110 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; /** + * Holds information about a method that a {@link MethodExpression} + * evaluated to. * + * @since JSP 2.1 */ public class MethodInfo { - - private final String name; - private final Class<?>[] paramTypes; - - private final Class<?> returnType; - - /** - * + /** + * Creates a new instance of <code>MethodInfo</code> with the given + * information. + * + * @param name The name of the method + * @param returnType The return type of the method + * @param paramTypes The types of each of the method's parameters */ public MethodInfo(String name, Class<?> returnType, Class<?>[] paramTypes) { this.name = name; this.returnType = returnType; this.paramTypes = paramTypes; } - + + /** + * Returns the name of the method + * + * @return the name of the method + */ public String getName() { return this.name; } + /** + * Returns the return type of the method + * + * @return the return type of the method + */ + public Class<?> getReturnType() { + return this.returnType; + } + + /** + * Returns the parameter types of the method + * + * @return the parameter types of the method + */ public Class<?>[] getParamTypes() { return this.paramTypes; } - public Class<?> getReturnType() { - return this.returnType; - } - + private String name; + private Class<?> returnType; + private Class<?>[] paramTypes; } Modified: trunk/java/javax/el/MethodNotFoundException.java =================================================================== --- trunk/java/javax/el/MethodNotFoundException.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/MethodNotFoundException.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,13 +1,50 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. @@ -18,36 +55,49 @@ package javax.el; /** + * Thrown when a method could not be found while evaluating a + * {@link MethodExpression}. * + * @see MethodExpression + * @since JSP 2.1 */ public class MethodNotFoundException extends ELException { /** - * + * Creates a <code>MethodNotFoundException</code> with no detail message. */ public MethodNotFoundException() { - super(); + super (); } /** - * @param message + * Creates a <code>MethodNotFoundException</code> with the provided + * detail message. + * + * @param message the detail message */ public MethodNotFoundException(String message) { - super(message); + super (message); } /** - * @param message - * @param cause + * Creates a <code>MethodNotFoundException</code> with the given root + * cause. + * + * @param exception the originating cause of this exception */ - public MethodNotFoundException(String message, Throwable cause) { - super(message, cause); + public MethodNotFoundException(Throwable exception) { + super (exception); } /** - * @param cause + * Creates a <code>MethodNotFoundException</code> with the given detail + * message and root cause. + * + * @param pMessage the detail message + * @param pRootCause the originating cause of this exception */ - public MethodNotFoundException(Throwable cause) { - super(cause); + public MethodNotFoundException(String pMessage, Throwable pRootCause) { + super (pMessage, pRootCause); } } Added: trunk/java/javax/el/PrivateMessages.properties =================================================================== --- trunk/java/javax/el/PrivateMessages.properties (rev 0) +++ trunk/java/javax/el/PrivateMessages.properties 2009-11-05 16:28:02 UTC (rev 1244) @@ -0,0 +1,62 @@ +# +# DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. +# +# Copyright 1997-2008 Sun Microsystems, Inc. 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.html +# or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. +# Sun designates this particular file as subject to the "Classpath" exception +# as provided by Sun in the GPL Version 2 section of the License file that +# accompanied this code. If applicable, add the following below the License +# Header, with the fields enclosed by brackets [] replaced by your own +# identifying information: "Portions Copyrighted [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. +# + +# This properties file is essentially "package private" but because +# there is no way to attach an access specifier to a properties file we +# are including this comment to serve as such. +setPropertyFailed=Can''t set property ''{0}'' on class ''{1}'' to value ''{2}''. +propertyNotFound=The class ''{0}'' does not have the property ''{1}''. +propertyNotReadable=The class ''{0}'' does not have a readable property ''{1}''. +resolverNotWritable=The ELResolver for the class ''{0}'' is not writable. +propertyNotWritable=The class ''{0}'' does not have a writable property ''{1}''. Modified: trunk/java/javax/el/PropertyNotFoundException.java =================================================================== --- trunk/java/javax/el/PropertyNotFoundException.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/PropertyNotFoundException.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,13 +1,50 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. @@ -18,37 +55,55 @@ package javax.el; /** + * Thrown when a property could not be found while evaluating a + * {@link ValueExpression} or {@link MethodExpression}. * + * <p>For example, this could be triggered by an index out of bounds + * while setting an array value, or by an unreadable property while + * getting the value of a JavaBeans property.</p> + * + * @since JSP 2.1 */ public class PropertyNotFoundException extends ELException { - + + //------------------------------------- /** - * + * Creates a <code>PropertyNotFoundException</code> with no detail message. */ public PropertyNotFoundException() { - super(); + super (); } + //------------------------------------- /** - * @param message + * Creates a <code>PropertyNotFoundException</code> with the provided + * detail message. + * + * @param message the detail message */ public PropertyNotFoundException(String message) { - super(message); + super (message); } /** - * @param message - * @param cause + * Creates a <code>PropertyNotFoundException</code> with the given root + * cause. + * + * @param exception the originating cause of this exception */ - public PropertyNotFoundException(String message, Throwable cause) { - super(message, cause); + public PropertyNotFoundException(Throwable exception) { + super (exception); } /** - * @param cause + * Creates a <code>PropertyNotFoundException</code> with the given detail + * message and root cause. + * + * @param pMessage the detail message + * @param pRootCause the originating cause of this exception */ - public PropertyNotFoundException(Throwable cause) { - super(cause); + public PropertyNotFoundException(String pMessage, Throwable pRootCause) { + super (pMessage, pRootCause); } } Modified: trunk/java/javax/el/PropertyNotWritableException.java =================================================================== --- trunk/java/javax/el/PropertyNotWritableException.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/PropertyNotWritableException.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,13 +1,50 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. @@ -17,37 +54,59 @@ package javax.el; + /** + * Thrown when a property could not be written to while setting the + * value on a {@link ValueExpression}. * + * <p>For example, this could be triggered by trying to set a map value + * on an unmodifiable map.</p> + * + * @since JSP 2.1 */ public class PropertyNotWritableException extends ELException { + //------------------------------------- /** - * + * Creates a <code>PropertyNotWritableException</code> with no detail + * message. */ public PropertyNotWritableException() { - super(); + super (); } + //------------------------------------- /** - * @param message + * Creates a <code>PropertyNotWritableException</code> with the + * provided detail message. + * + * @param pMessage the detail message */ - public PropertyNotWritableException(String message) { - super(message); + public PropertyNotWritableException(String pMessage) { + super (pMessage); } + //------------------------------------- /** - * @param message - * @param cause + * Creates a <code>PropertyNotWritableException</code> with the given root + * cause. + * + * @param exception the originating cause of this exception */ - public PropertyNotWritableException(String message, Throwable cause) { - super(message, cause); + public PropertyNotWritableException(Throwable exception) { + super (exception); } + //------------------------------------- /** - * @param cause + * Creates a <code>PropertyNotWritableException</code> with the given + * detail message and root cause. + * + * @param pMessage the detail message + * @param pRootCause the originating cause of this exception */ - public PropertyNotWritableException(Throwable cause) { - super(cause); + public PropertyNotWritableException(String pMessage, Throwable pRootCause) { + super (pMessage, pRootCause); } + } Modified: trunk/java/javax/el/ResourceBundleELResolver.java =================================================================== --- trunk/java/javax/el/ResourceBundleELResolver.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/ResourceBundleELResolver.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,20 +1,56 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ - package javax.el; import java.beans.FeatureDescriptor; @@ -25,104 +61,263 @@ import java.util.MissingResourceException; import java.util.ResourceBundle; +/** + * Defines property resolution behavior on instances of + * {@link java.util.ResourceBundle}. + * + * <p> + * This resolver handles base objects of type + * <code>java.util.ResourceBundle</code>. It accepts any object as a property + * and coerces it to a <code>java.lang.String</code> for invoking + * {@link java.util.ResourceBundle#getObject(java.lang.String)}. + * </p> + * + * <p> + * This resolver is read only and will throw a + * {@link PropertyNotWritableException} if <code>setValue</code> is called. + * </p> + * + * <p> + * <code>ELResolver</code>s are combined together using + * {@link CompositeELResolver}s, to define rich semantics for evaluating an + * expression. See the javadocs for {@link ELResolver} for details. + * </p> + * + * @see CompositeELResolver + * @see ELResolver + * @see java.util.ResourceBundle + * @since JSP 2.1 + */ public class ResourceBundleELResolver extends ELResolver { - public ResourceBundleELResolver() { - super(); - } - - public Object getValue(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { + /** + * If the base object is an instance of <code>ResourceBundle</code>, + * the provided property will first be coerced to a <code>String</code>. + * The <code>Object</code> returned by <code>getObject</code> on + * the base <code>ResourceBundle</code> will be returned. + * </p> + * If the base is <code>ResourceBundle</code>, 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> + * @param context + * The context of this evaluation. + * @param base + * The ResourceBundle to analyze. + * @param property + * The name of the property to analyze. Will be coerced to a + * <code>String</code>. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>null</code> if property is <code>null</code>; + * otherwise the <code>Object</code> for the given key + * (property coerced to <code>String</code>) from the + * <code>ResourceBundle</code>. + * If no object for the given key can be found, then the + * <code>String</code> "???" + key + "???". + * @throws NullPointerException + * if context is <code>null</code> + * @throws ELException + * if an exception was thrown while performing the property or + * variable resolution. The thrown exception must be included as + * the cause property of this exception, if available. + */ + public Object getValue(ELContext context, Object base, Object property) { if (context == null) { throw new NullPointerException(); } - + if (base instanceof ResourceBundle) { + context.setPropertyResolved(true); if (property != null) { try { - Object result = ((ResourceBundle) base).getObject(property + return ((ResourceBundle) base).getObject(property .toString()); - context.setPropertyResolved(true); - return result; - } catch (MissingResourceException mre) { - return "???" + property.toString() + "???"; + } catch (MissingResourceException e) { + return "???" + property + "???"; } } } - return null; } - public Class<?> getType(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { + /** + * If the base object is an instance of <code>ResourceBundle</code>, + * return <code>null</code>, since the resolver is read only. + * + * <p> + * If the base is <code>ResourceBundle</code>, 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> + * + * @param context + * The context of this evaluation. + * @param base + * The ResourceBundle to analyze. + * @param property + * The name of the property to analyze. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>null</code>; otherwise undefined. + * @throws NullPointerException + * if context is <code>null</code> + */ + public Class<?> getType(ELContext context, Object base, Object property) { if (context == null) { throw new NullPointerException(); } - + if (base instanceof ResourceBundle) { context.setPropertyResolved(true); } - return null; } + /** + * If the base object is a ResourceBundle, throw a + * {@link PropertyNotWritableException}. + * + * @param context + * The context of this evaluation. + * @param base + * The ResourceBundle to be modified. Only bases that are of type + * ResourceBundle are handled. + * @param property + * The String property to use. + * @param value + * The value to be set. + * @throws NullPointerException + * if context is <code>null</code>. + * @throws PropertyNotWritableException + * Always thrown if base is an instance of ReasourceBundle. + */ public void setValue(ELContext context, Object base, Object property, - Object value) throws NullPointerException, - PropertyNotFoundException, PropertyNotWritableException, - ELException { + Object value) { if (context == null) { throw new NullPointerException(); } - + if (base instanceof ResourceBundle) { context.setPropertyResolved(true); - throw new PropertyNotWritableException(message(context, - "resolverNotWriteable", new Object[] { base.getClass() - .getName() })); + throw new PropertyNotWritableException( + "ResourceBundles are immutable"); } } - public boolean isReadOnly(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { + /** + * If the base object is not null and an instanceof {@link ResourceBundle}, + * return <code>true</code>. + * + * @param context + * The context of this evaluation. + * @param base + * The ResourceBundle to be modified. Only bases that are of type + * ResourceBundle are handled. + * @param property + * The String property to use. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>true</code>; otherwise undefined. + * @throws NullPointerException + * if context is <code>null</code> + */ + public boolean isReadOnly(ELContext context, Object base, Object property) { if (context == null) { throw new NullPointerException(); } - if (base instanceof ResourceBundle) { context.setPropertyResolved(true); + return true; } - - return true; + return false; } + /** + * If the base object is a ResourceBundle, returns an <code>Iterator</code> + * containing the set of keys available in the <code>ResourceBundle</code>. + * Otherwise, returns <code>null</code>. + * + * <p> + * The <code>Iterator</code> returned must contain zero or more instances + * of {@link java.beans.FeatureDescriptor}. Each info object contains + * information about a key in the ResourceBundle, and is initialized as + * follows: + * <dl> + * <li>displayName - The <code>String</code> key + * <li>name - Same as displayName property.</li> + * <li>shortDescription - Empty string</li> + * <li>expert - <code>false</code></li> + * <li>hidden - <code>false</code></li> + * <li>preferred - <code>true</code></li> + * </dl> + * In addition, the following named attributes must be set in the returned + * <code>FeatureDescriptor</code>s: + * <dl> + * <li>{@link ELResolver#TYPE} - <code>String.class</code></li> + * <li>{@link ELResolver#RESOLVABLE_AT_DESIGN_TIME} - <code>true</code></li> + * </dl> + * </p> + * + * @param context + * The context of this evaluation. + * @param base + * The bundle whose keys are to be iterated over. Only bases of + * type <code>ResourceBundle</code> are handled by this + * resolver. + * @return An <code>Iterator</code> containing zero or more (possibly + * infinitely more) <code>FeatureDescriptor</code> objects, each + * representing a key in this bundle, or <code>null</code> if the + * base object is not a ResourceBundle. + */ public Iterator getFeatureDescriptors(ELContext context, Object base) { if (base instanceof ResourceBundle) { - List<FeatureDescriptor> feats = new ArrayList<FeatureDescriptor>(); - Enumeration e = ((ResourceBundle) base).getKeys(); - FeatureDescriptor feat; - String key; - while (e.hasMoreElements()) { + ResourceBundle bundle = (ResourceBundle) base; + List features = new ArrayList(); + String key = null; + FeatureDescriptor desc = null; + for (Enumeration e = bundle.getKeys(); e.hasMoreElements();) { key = (String) e.nextElement(); - feat = new FeatureDescriptor(); - feat.setDisplayName(key); - feat.setExpert(false); - feat.setHidden(false); - feat.setName(key); - feat.setPreferred(true); - feat.setValue(RESOLVABLE_AT_DESIGN_TIME, Boolean.TRUE); - feat.setValue(TYPE, String.class); - feats.add(feat); + desc = new FeatureDescriptor(); + desc.setDisplayName(key); + desc.setExpert(false); + desc.setHidden(false); + desc.setName(key); + desc.setPreferred(true); + desc.setValue(TYPE, String.class); + desc.setValue(RESOLVABLE_AT_DESIGN_TIME, Boolean.TRUE); + features.add(desc); } - return feats.iterator(); + return features.iterator(); } return null; } + /** + * If the base object is a ResourceBundle, returns the most general type + * that this resolver accepts for the <code>property</code> argument. + * Otherwise, returns <code>null</code>. + * + * <p> + * Assuming the base is a <code>ResourceBundle</code>, this method will + * always return <code>String.class</code>. + * + * @param context + * The context of this evaluation. + * @param base + * The bundle to analyze. Only bases of type + * <code>ResourceBundle</code> are handled by this resolver. + * @return <code>null</code> if base is not a <code>ResourceBundle</code>; + * otherwise <code>String.class</code>. + */ public Class<?> getCommonPropertyType(ELContext context, Object base) { if (base instanceof ResourceBundle) { return String.class; } return null; } - } Modified: trunk/java/javax/el/ValueExpression.java =================================================================== --- trunk/java/javax/el/ValueExpression.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/ValueExpression.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,35 +1,223 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.el; /** + * An <code>Expression</code> that can get or set a value. * + * <p>In previous incarnations of this API, expressions could only be + * read. <code>ValueExpression</code> objects can now be used both to + * retrieve a value and to set a value. Expressions that can have a value + * set on them are referred to as l-value expressions. Those that + * cannot are referred to as r-value expressions. Not all r-value expressions + * can be used as l-value expressions (e.g. <code>"${1+1}"</code> or + * <code>"${firstName} ${lastName}"</code>). See the EL Specification for + * details. Expressions that cannot be used as l-values must always + * return <code>true</code> from <code>isReadOnly()</code>.</p> + * + * <p>The <code>{@link ExpressionFactory#createValueExpression}</code> method + * can be used to parse an expression string and return a concrete instance + * of <code>ValueExpression</code> that encapsulates the parsed expression. + * The {@link FunctionMapper} is used at parse time, not evaluation time, + * so one is not needed to evaluate an expression using this class. + * However, the {@link ELContext} is needed at evaluation time.</p> + * + * <p>The {@link #getValue}, {@link #setValue}, {@link #isReadOnly}, + * {@link #getType} and {@link #getValueReference} + * methods will evaluate the expression each time they are + * called. The {@link ELResolver} in the <code>ELContext</code> is used to + * resolve the top-level variables and to determine the behavior of the + * <code>.</code> and <code>[]</code> operators. For any of the five methods, + * the {@link ELResolver#getValue} method is used to resolve all properties + * up to but excluding the last one. This provides the <code>base</code> + * object. For all methods other than the {@link #getValueReference} method, + * at the last resolution, the <code>ValueExpression</code> will + * call the corresponding {@link ELResolver#getValue}, + * {@link ELResolver#setValue}, {@link ELResolver#isReadOnly} or + * {@link ELResolver#getType} method, depending on which was called on + * the <code>ValueExpression</code>. + * For the {@link getValueReference} method, the (base, property) is + * not resolved by the ELResolver, but an instance of {@link ValueReference} + * is created to encapsulate this (base ,property), and returned. + * </p> + * + * <p>See the notes about comparison, serialization and immutability in + * the {@link Expression} javadocs. + * + * @see ELResolver + * @see Expression + * @see ExpressionFactory + * @since JSP 2.1 */ -public abstract class ValueExpression extends Expression { - - public abstract Class<?> getExpectedType(); +public abstract class ValueExpression + extends Expression +{ - public abstract Class<?> getType(ELContext context) throws NullPointerException, PropertyNotFoundException, ELException; + /** + * Evaluates the expression relative to the provided context, and + * returns the resulting value. + * + * <p>The resulting value is automatically coerced to the type + * returned by <code>getExpectedType()</code>, which was + * provided to the <code>ExpressionFactory</code> when this + * expression was created.</p> + * + * @param context The context of this evaluation. + * @return The result of the expression evaluation. + * @throws NullPointerException if context is <code>null</code>. + * @throws PropertyNotFoundException if one of the property + * resolutions failed because a specified variable or property + * does not exist or is not readable. + * @throws ELException if an exception was thrown while performing + * property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public abstract Object getValue(ELContext context); - public abstract boolean isReadOnly(ELContext context) throws NullPointerException, PropertyNotFoundException, ELException; + /** + * Evaluates the expression relative to the provided context, and + * sets the result to the provided value. + * + * @param context The context of this evaluation. + * @param value The new value to be set. + * @throws NullPointerException if context is <code>null</code>. + * @throws PropertyNotFoundException if one of the property + * resolutions failed because a specified variable or property + * does not exist or is not readable. + * @throws PropertyNotWritableException if the final variable or + * property resolution failed because the specified + * variable or property is not writable. + * @throws ELException if an exception was thrown while attempting to + * set the property or variable. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public abstract void setValue(ELContext context, Object value); - public abstract void setValue(ELContext context, Object value) throws NullPointerException, PropertyNotFoundException, PropertyNotWritableException, ELException; + /** + * Evaluates the expression relative to the provided context, and + * returns <code>true</code> if a call to {@link #setValue} will + * always fail. + * + * @param context The context of this evaluation. + * @return <code>true</code> if the expression is read-only or + * <code>false</code> if not. + * @throws NullPointerException if context is <code>null</code>. + * @throws PropertyNotFoundException if one of the property + * resolutions failed because a specified variable or property + * does not exist or is not readable. + * @throws ELException if an exception was thrown while performing + * property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + * * @throws NullPointerException if context is <code>null</code> + */ + public abstract boolean isReadOnly(ELContext context); - public abstract Object getValue(ELContext context) throws NullPointerException, PropertyNotFoundException, ELException; + /** + * Evaluates the expression relative to the provided context, and + * returns the most general type that is acceptable for an object to be + * passed as the <code>value</code> parameter in a future call + * to the {@link #setValue} method. + * + * <p>This is not always the same as <code>getValue().getClass()</code>. + * For example, in the case of an expression that references an + * array element, the <code>getType</code> method will return the + * element type of the array, which might be a superclass of the type + * of the actual element that is currently in the specified + * array element.</p> + * + * @param context The context of this evaluation. + * @return the most general acceptable type; otherwise undefined. + * @throws NullPointerException if context is <code>null</code>. + * @throws PropertyNotFoundException if one of the property + * resolutions failed because a specified variable or property + * does not exist or is not readable. + * @throws ELException if an exception was thrown while performing + * property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public abstract Class<?> getType(ELContext context); + + /** + * Returns the type the result of the expression will be coerced to + * after evaluation. + * + * @return the <code>expectedType</code> passed to the + * <code>ExpressionFactory.createValueExpression</code> method + * that created this <code>ValueExpression</code>. + */ + public abstract Class<?> getExpectedType(); + /** + * Returns a {@link ValueReference} for this expression instance. + * @param context the context of this evaluation + * @return the <code>ValueReference</code> for this + * <code>ValueExpression</code>, or <code>null</code> if this + * <code>ValueExpression</code> is not a reference to + * a base (null or non-null) and a property. + * If the base is null, and the property is a EL variable, return + * the <code>ValueReference</code> for the + * <code>ValueExpression</code> associated with this EL variable. + * + * @since EL 2.2 + */ + public ValueReference getValueReference(ELContext context) { + return null; + } } Added: trunk/java/javax/el/ValueReference.java =================================================================== --- trunk/java/javax/el/ValueReference.java (rev 0) +++ trunk/java/javax/el/ValueReference.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -0,0 +1,29 @@ +package javax.el; + +import java.io.Serializable; + +/** + * This encapsulates a base model object and one of its properties. + * + * @since EL 2.2 + */ + +public class ValueReference implements Serializable { + + private Object base; + private Object property; + + public ValueReference(Object base, Object porperty) { + this.base = base; + this.property = property; + } + + public Object getBase() { + return base; + } + + public Object getProperty() { + return property; + } + +} Modified: trunk/java/javax/el/VariableMapper.java =================================================================== --- trunk/java/javax/el/VariableMapper.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/el/VariableMapper.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,13 +1,50 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 - * + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. @@ -18,11 +55,35 @@ package javax.el; /** + * The interface to a map between EL variables and the EL expressions + * they are associated with. * + * @since JSP 2.1 */ + public abstract class VariableMapper { - - public abstract ValueExpression resolveVariable(String variable); - public abstract ValueExpression setVariable(String variable, ValueExpression expression); + /** + * @param variable The variable name + * @return the ValueExpression assigned to the variable, + * null if there is no previous assignment to this variable. + */ + public abstract ValueExpression resolveVariable( + String variable); + + /** + * Assign a ValueExpression to an EL variable, replacing + * any previously assignment to the same variable. + * The assignment for the variable is removed if + * the expression is <code>null</code>. + * + * @param variable The variable name + * @param expression The ValueExpression to be assigned + * to the variable. + * @return The previous ValueExpression assigned to this variable, + * null if there is no previouse assignment to this variable. + */ + public abstract ValueExpression setVariable( + String variable, + ValueExpression expression); } Added: trunk/java/javax/el/package.html =================================================================== --- trunk/java/javax/el/package.html (rev 0) +++ trunk/java/javax/el/package.html 2009-11-05 16:28:02 UTC (rev 1244) @@ -0,0 +1,238 @@ +<!-- + DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + + Copyright 1997-2008 Sun Microsystems, Inc. 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.html + or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + Sun designates this particular file as subject to the "Classpath" exception + as provided by Sun in the GPL Version 2 section of the License file that + accompanied this code. If applicable, add the following below the License + Header, with the fields enclosed by brackets [] replaced by your own + identifying information: "Portions Copyrighted [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> +<!-- +FIXME insert copyright +--> +</head> + +<body bgcolor="white"> +Provides the API for the <strong>Unified Expression Language</strong> shared by +the JSP 2.1 and JSF 1.2 technologies. + +<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.1 specification, but does not have any dependencies on any portion +of the JSP 2.1 specification. It is intended for general use outside of +the JSP and JSF specifications as well.</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="#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> +</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>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>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>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. +</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> + +<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>&lt;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> +&lt;c:forEach var="item" items="#{model.list}"> + &lt;h:inputText value="#{item.name}"/> +&lt;/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>&lt;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> + +</body> +</html> + Modified: trunk/java/javax/servlet/jsp/ErrorData.java =================================================================== --- trunk/java/javax/servlet/jsp/ErrorData.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/ErrorData.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp; /** @@ -24,7 +61,7 @@ * to "true". * * @see PageContext#getErrorData - * @since 2.0 + * @since JSP 2.0 */ public final class ErrorData { Modified: trunk/java/javax/servlet/jsp/HttpJspPage.java =================================================================== --- trunk/java/javax/servlet/jsp/HttpJspPage.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/HttpJspPage.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp; Modified: trunk/java/javax/servlet/jsp/JspApplicationContext.java =================================================================== --- trunk/java/javax/servlet/jsp/JspApplicationContext.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/JspApplicationContext.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,77 +1,179 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ + package javax.servlet.jsp; -import javax.el.ELContextListener; import javax.el.ELResolver; import javax.el.ExpressionFactory; +import javax.el.ELContextListener; /** - * <p> - * Stores <i>application</i>-scoped information for the JSP container. + * Stores application-scoped information relevant to JSP containers. + * + * <p>The JSP container must create a single instance of + * <code>JspApplicationContext</code> for each + * <code>ServletContext</code> instance.</p> + * + * <p>An instance of <code>JspApplicationContext</code> is obtained by + * invoking the static {@link JspFactory#getJspApplicationContext} method, + * passing the <code>ServletContext</code> of the corresponding web + * application.</p> + * + * <p>The <code>JspApplicationContext</code> provides the following services + * to JSP applications: + * <ul> + * <li>Allows registration of <code>ELResolver</code>s, which are used to + * resolve variables in EL expressions contained in JSP pages and + * tag files.</li> + * <li>Provides an instance of <code>ExpressionFactory</code> for those + * applications or frameworks that need to perform programmatic + * evaluation of EL expressions instead of allowing the JSP + * container to do it for them.</li> + * <li>Allows the attachment of <code>ELContextListener</code> instances + * for notification whenever a new <code>ELContext</code> is created. + * This is necessary when an application wishes to make custom + * context objects available to their pluggable + * <code>ELResolver</code>s.</li> + * </ul> * </p> - * @since 2.1 + * + * @see javax.servlet.ServletContext + * @see JspFactory + * @see javax.el.ELResolver + * @see javax.el.ExpressionFactory + * @see javax.el.ELContextListener + * @since JSP 2.1 */ public interface JspApplicationContext { - - /** - * <p> - * Registers an <code>ELContextListener</code> that will notified whenever - * a new <code>ELContext</code> is created. - * </p> - * <p> - * At the very least, any <code>ELContext</code> instantiated will have reference - * to the <code>JspContext</code> under <code>JspContext.class</code>. - * </p> - * - * @param listener - */ - public void addELContextListener(ELContextListener listener); - - /** - * <p> - * Adds an <code>ELResolver</code> to the chain of EL variable and property management - * within JSP pages and Tag files. - * </p> - * <p> - * JSP has a default set of ELResolvers to chain for all EL evaluation: - * <ul> - * <li><code>ImplicitObjectELResolver</code></li> - * <li><code>ELResolver</code> instances registered with this method</li> - * <li><code>MapELResolver</code></li> - * <li><code>ListELResolver</code></li> - * <li><code>ArrayELResolver</code></li> - * <li><code>BeanELResolver</code></li> - * <li><code>ScopedAttributeELResolver</code></li> - * </ul> - * </p> - * - * @param resolver an additional resolver - * @throws IllegalStateException if called after the application's <code>ServletContextListeners</code> have been initialized. - */ - public void addELResolver(ELResolver resolver) throws IllegalStateException; - - /** - * <p> - * Returns the JSP container's <code>ExpressionFactory</code> implementation for EL use. - * </p> - * - * @return an <code>ExpressionFactory</code> implementation - */ - public ExpressionFactory getExpressionFactory(); - + + /** + * Adds an <code>ELResolver</code> to affect the way EL variables + * and properties are resolved for EL expressions appearing in JSP pages + * and tag files. + * + * <p>For example, in the EL expression ${employee.lastName}, an + * <code>ELResolver</code> determines what object "employee" + * references and how to find its "lastName" property.</p> + * + * <p>When evaluating an expression, the JSP container will consult a + * set of standard resolvers as well as any resolvers registered via + * this method. The set of resolvers are consulted in the following + * order: + * <ul> + * <li>{@link javax.servlet.jsp.el.ImplicitObjectELResolver}</li> + * <li><code>ELResolver</code>s registered via this method, in the + * order in which they are registered.</li> + * <li>{@link javax.el.MapELResolver}</li> + * <li>{@link javax.el.ListELResolver}</li> + * <li>{@link javax.el.ArrayELResolver}</li> + * <li>{@link javax.el.BeanELResolver}</li> + * <li>{@link javax.servlet.jsp.el.ScopedAttributeELResolver}</li> + * </ul></p> + * + * <p>It is illegal to register an <code>ELResolver</code> after the + * application has received any request from the client. If an + * attempt is made to register an <code>ELResolver</code> after that time, + * an <code>IllegalStateException</code> is thrown.</p> + * This restriction is + * in place to allow the JSP container to optimize for the common + * case where no additional <code>ELResolver</code>s are in the chain, + * aside from the standard ones. It is permissible to add + * <code>ELResolver</code>s before or after initialization to + * a <code>CompositeELResolver</code> that is already in the chain.</p> + * + * <p>It is not possible to remove an <code>ELResolver</code> registered + * with this method, once it has been registered.</p> + * + * @param resolver The new <code>ELResolver</code> + * @throws IllegalStateException if an attempt is made to + * call this method after all <code>ServletContextListener</code>s + * have had their <code>contextInitialized</code> methods invoked. + */ + public void addELResolver(ELResolver resolver); + + /** + * Returns a factory used to create <code>ValueExpression</code>s and + * <code>MethodExpression</code>s so that EL expressions can be + * parsed and evaluated. + * + * @return A concrete implementation of the + * an <code>ExpressionFactory</code>. + */ + public ExpressionFactory getExpressionFactory(); + + /** + * Registers a <code>ELContextListener</code>s so that context objects + * can be added whenever a new <code>ELContext</code> is created. + * + * <p>At a minimum, the <code>ELContext</code> objects created will + * contain a reference to the <code>JspContext</code> for this request, + * which is added by the JSP container. + * This is sufficient for all the + * default <code>ELResolver</code>s listed in {@link #addELResolver}. + * Note that <code>JspContext.class</code> is used as the key to ELContext.putContext() + * for the <code>JspContext</code> object reference.</p> + * + * <p>This method is generally used by frameworks and applications that + * register their own <code>ELResolver</code> that needs context other + * than <code>JspContext</code>. The listener will typically add the + * necessary context to the <code>ELContext</code> provided in the + * event object. Registering a listener that adds context allows the + * <code>ELResolver</code>s in the stack to access the context they + * need when they do a resolution.</p> + * + * @param listener The listener to be notified when a new + * <code>ELContext</code> is created. + */ + public void addELContextListener(ELContextListener listener); } Modified: trunk/java/javax/servlet/jsp/JspContext.java =================================================================== --- trunk/java/javax/servlet/jsp/JspContext.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/JspContext.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,27 +1,65 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp; import java.util.Enumeration; -import javax.el.ELContext; import javax.servlet.jsp.el.ExpressionEvaluator; import javax.servlet.jsp.el.VariableResolver; +import javax.el.ELContext; + /** * <p> * <code>JspContext</code> serves as the base class for the @@ -66,7 +104,7 @@ * Expression Language evaluator: * <code>getExpressionEvaluator()</code>, <code>getVariableResolver()</code> * - * @since 2.0 + * @since JSP 2.0 */ public abstract class JspContext { @@ -220,25 +258,45 @@ * The JSP Container must return a valid instance of an * ExpressionEvaluator that can parse EL expressions. * + * @deprecated As of JSP 2.1, replaced by + * {@link JspApplicationContext#getExpressionFactory} * @return A valid instance of an ExpressionEvaluator. - * @since 2.0 + * @since JSP 2.0 */ public abstract ExpressionEvaluator getExpressionEvaluator(); - - public abstract ELContext getELContext(); - /** * Returns an instance of a VariableResolver that provides access to the * implicit objects specified in the JSP specification using this JspContext * as the context object. * + * @deprecated As of JSP 2.1, replaced by {@link ELContext#getELResolver}, + * which can be obtained by + * <code>jspContext.getELContext().getELResolver()</code>. * @return A valid instance of a VariableResolver. - * @since 2.0 + * @since JSP 2.0 */ public abstract VariableResolver getVariableResolver(); /** + * Returns the <code>ELContext</code> associated with this + * <code>JspContext</code>. + * + * <p>The <code>ELContext</code> is created lazily and is reused if + * it already exists. There is a new <code>ELContext</code> for each + * <code>JspContext</code>.</p> + * + * <p>The <code>ELContext</code> must contain the <code>ELResolver</code> + * described in the JSP specification (and in the javadocs for + * {@link JspApplicationContext#addELResolver}).</p> + * + * @return The <code>ELContext</code> associated with this + * <code>JspContext</code>. + * @since JSP 2.1 + */ + public abstract ELContext getELContext(); + + /** * Return a new JspWriter object that sends output to the * provided Writer. Saves the current "out" JspWriter, * and updates the value of the "out" attribute in the @@ -256,7 +314,7 @@ * @param writer The Writer for the returned JspWriter to send * output to. * @return a new JspWriter that writes to the given Writer. - * @since 2.0 + * @since JSP 2.0 */ public JspWriter pushBody( java.io.Writer writer ) { return null; // XXX to implement Modified: trunk/java/javax/servlet/jsp/JspEngineInfo.java =================================================================== --- trunk/java/javax/servlet/jsp/JspEngineInfo.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/JspEngineInfo.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp; /** Modified: trunk/java/javax/servlet/jsp/JspException.java =================================================================== --- trunk/java/javax/servlet/jsp/JspException.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/JspException.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp; /** @@ -36,63 +73,53 @@ * specified message. The message can be written * to the server log and/or displayed for the user. * - * @param msg a <code>String</code> specifying the text of the exception - * message + * @param msg a <code>String</code> + * specifying the text of + * the exception message + * */ public JspException(String msg) { - super(msg); + super(msg); } /** - * Constructs a new <code>JSPException</code> with the specified detail - * message and cause. The cause is saved for later retrieval by the - * <code>java.lang.Throwable.getCause()</code> and {@link #getRootCause()} - * methods. - * - * @see <code>java.lang.Exception.Exception(String, Throwable)</code> + * Constructs a new <code>JspException</code> with the specified detail + * message and cause. * - * @param message a <code>String</code> containing the text of the - * exception message + * The cause is saved for later retrieval by the + * {@link #getCause()} and {@link #getRootCause()} methods. * - * @param cause the <code>Throwable</code> exception that - * interfered with the JSP's normal operation, - * making this JSP exception necessary + * @see java.lang.Exception#Exception(String, Throwable) */ - public JspException(String message, Throwable cause) { - super(message, cause); + super(message, cause); } /** - * Constructs a new <code>JSPException</code> with the specified cause. + * Constructs a new <code>JspException</code> with the specified cause. + * * The cause is saved for later retrieval by the - * <code>java.lang.Throwable.getCause()</code> and {@link #getRootCause()} - * methods. - * - * @see <code>java.lang.Exception.Exception(Throwable)</code> + * {@link #getCause()} and {@link #getRootCause()} methods. * - * @param cause the <code>Throwable</code> exception that - * interfered with the JSP's normal operation, making - * the JSP exception necessary + * @see java.lang.Exception#Exception(Throwable) */ - public JspException(Throwable cause) { - super(cause); + super(cause); } /** - * @deprecated As of JSP 2.1, replaced by - * <code>java.lang.Throwable.getCause()</code> - * * Returns the exception that caused this JSP exception. * - * @return the <code>Throwable</code> that caused this JSP exception + * @return the <code>Throwable</code> + * that caused this JSP exception + * + * @deprecated As of JSP 2.1, replaced by {@link #getCause()} */ public Throwable getRootCause() { - return getCause(); + return getCause(); } } Modified: trunk/java/javax/servlet/jsp/JspFactory.java =================================================================== --- trunk/java/javax/servlet/jsp/JspFactory.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/JspFactory.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,25 +1,62 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp; import javax.servlet.Servlet; -import javax.servlet.ServletContext; import javax.servlet.ServletRequest; import javax.servlet.ServletResponse; +import javax.servlet.ServletContext; import javax.servlet.jsp.PageContext; /** @@ -35,10 +72,14 @@ * the instance created with this class via the * static <code> setDefaultFactory() </code> method. * <p> - * The PageContext and the JspEngineInfo classes are the only implementation-dependent - * classes that can be created from the factory. + * The only implementation-dependent classes that can be created from the + * factory are: + * PageContext, + * JspEngineInfo, and + * JspApplicationContext. * <p> - * JspFactory objects should not be used by JSP page authors. + * With the exception of JspApplicationContext, + * JspFactory objects should not be used by JSP application developers. */ public abstract class JspFactory { @@ -72,6 +113,15 @@ */ public static synchronized JspFactory getDefaultFactory() { + if (deflt == null) { + try { + Class factory = Class.forName("org.apache.jasper.runtime.JspFactoryImpl"); + if (factory != null) { + deflt = (JspFactory) factory.newInstance(); + } + } catch (Exception ex) { + } + } return deflt; } @@ -141,16 +191,18 @@ */ public abstract JspEngineInfo getEngineInfo(); - + /** - * <p> - * Obtain the <code>JspApplicationContext</code> instance that was associated - * within the passed <code>ServletContext</code> for this web application. - * </p> - * - * @param context the current web application's <code>ServletContext</code> - * @return <code>JspApplicationContext</code> instance + * Obtains the <code>JspApplicationContext</code> instance associated + * with the web application for the given <code>ServletContext</code>. + * + * @param context The <code>ServletContext</code> for the web + * application the desired <code>JspApplicationContext</code> is + * associated with. + * @return The <code>JspApplicationContext</code> associated with the + * web application. * @since 2.1 */ - public abstract JspApplicationContext getJspApplicationContext(ServletContext context); + public abstract JspApplicationContext getJspApplicationContext( + ServletContext context); } Modified: trunk/java/javax/servlet/jsp/JspPage.java =================================================================== --- trunk/java/javax/servlet/jsp/JspPage.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/JspPage.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp; import javax.servlet.*; Modified: trunk/java/javax/servlet/jsp/JspTagException.java =================================================================== --- trunk/java/javax/servlet/jsp/JspTagException.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/JspTagException.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp; /** @@ -58,7 +95,7 @@ * normal operation, making this JSP Tag * exception necessary * - * @since 2.0 + * @since JSP 2.0 */ public JspTagException(String message, Throwable rootCause) { super( message, rootCause ); @@ -83,7 +120,7 @@ * normal operation, making the JSP Tag * exception necessary * - * @since 2.0 + * @since JSP 2.0 */ public JspTagException(Throwable rootCause) { Modified: trunk/java/javax/servlet/jsp/JspWriter.java =================================================================== --- trunk/java/javax/servlet/jsp/JspWriter.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/JspWriter.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp; Modified: trunk/java/javax/servlet/jsp/PageContext.java =================================================================== --- trunk/java/javax/servlet/jsp/PageContext.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/PageContext.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp; @@ -406,7 +443,7 @@ * @throws ServletException if the page that was forwarded to throws * a ServletException * @throws IOException if an I/O error occurred while forwarding - * @since 2.0 + * @since JSP 2.0 */ abstract public void include(String relativeUrlPath, boolean flush) throws ServletException, IOException; @@ -509,7 +546,7 @@ * if the isErrorPage attribute of the page directive is not set * to "true"), the information is meaningless. * - * @since 2.0 + * @since JSP 2.0 */ public ErrorData getErrorData() { return new ErrorData( Modified: trunk/java/javax/servlet/jsp/SkipPageException.java =================================================================== --- trunk/java/javax/servlet/jsp/SkipPageException.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/SkipPageException.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp; /** @@ -31,7 +68,7 @@ * @see javax.servlet.jsp.tagext.SimpleTag#doTag * @see javax.servlet.jsp.tagext.JspFragment#invoke * @see javax.servlet.jsp.tagext.Tag#doEndTag - * @since 2.0 + * @since JSP 2.0 */ public class SkipPageException extends JspException Modified: trunk/java/javax/servlet/jsp/el/ELException.java =================================================================== --- trunk/java/javax/servlet/jsp/el/ELException.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/el/ELException.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.el; @@ -22,8 +59,8 @@ * Represents any of the exception conditions that arise during the * operation evaluation of the evaluator. * - * @since 2.0 - * @deprecated + * @deprecated As of JSP 2.1, replaced by {@link javax.el.ELException} + * @since JSP 2.0 */ public class ELException extends Exception Modified: trunk/java/javax/servlet/jsp/el/ELParseException.java =================================================================== --- trunk/java/javax/servlet/jsp/el/ELParseException.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/el/ELParseException.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.el; @@ -21,8 +58,8 @@ /** * Represents a parsing error encountered while parsing an EL expression. * - * @since 2.0 - * @deprecated + * @deprecated As of JSP 2.1, replaced by {@link javax.el.ELException} + * @since JSP 2.0 */ public class ELParseException extends ELException { Modified: trunk/java/javax/servlet/jsp/el/Expression.java =================================================================== --- trunk/java/javax/servlet/jsp/el/Expression.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/el/Expression.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.el; @@ -29,8 +66,8 @@ * A client invoking the evaluate() method should be ready for the case * where ELParseException exceptions are raised. </p> * - * @since 2.0 - * @deprecated + * @deprecated As of JSP 2.1, replaced by {@link javax.el.ValueExpression} + * @since JSP 2.0 */ public abstract class Expression { Modified: trunk/java/javax/servlet/jsp/el/ExpressionEvaluator.java =================================================================== --- trunk/java/javax/servlet/jsp/el/ExpressionEvaluator.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/el/ExpressionEvaluator.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.el; @@ -50,8 +87,8 @@ * </ul> * </p> * - * @since 2.0 - * @deprecated + * @deprecated As of JSP 2.1, replaced by {@link javax.el.ExpressionFactory} + * @since JSP 2.0 */ public abstract class ExpressionEvaluator { Modified: trunk/java/javax/servlet/jsp/el/FunctionMapper.java =================================================================== --- trunk/java/javax/servlet/jsp/el/FunctionMapper.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/el/FunctionMapper.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.el; @@ -23,8 +60,8 @@ * <p>Classes implementing this interface may, for instance, consult tag library * information to resolve the map. </p> * - * @since 2.0 - * @deprecated + * @deprecated As of JSP 2.1, replaced by {@link javax.el.FunctionMapper} + * @since JSP 2.0 */ public interface FunctionMapper { /** Modified: trunk/java/javax/servlet/jsp/el/ImplicitObjectELResolver.java =================================================================== --- trunk/java/javax/servlet/jsp/el/ImplicitObjectELResolver.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/el/ImplicitObjectELResolver.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,555 +1,1263 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.el; import java.beans.FeatureDescriptor; -import java.util.AbstractMap; +import java.util.Iterator; import java.util.ArrayList; -import java.util.Arrays; +import java.util.Collection; import java.util.Enumeration; -import java.util.HashSet; -import java.util.Iterator; +import java.util.HashMap; import java.util.List; import java.util.Map; import java.util.Set; -import java.util.Vector; -import javax.el.ELContext; -import javax.el.ELException; -import javax.el.ELResolver; -import javax.el.PropertyNotFoundException; -import javax.el.PropertyNotWritableException; +import javax.servlet.ServletContext; import javax.servlet.http.Cookie; import javax.servlet.http.HttpServletRequest; -import javax.servlet.http.HttpSession; +import javax.servlet.jsp.PageContext; import javax.servlet.jsp.JspContext; -import javax.servlet.jsp.PageContext; +import javax.el.PropertyNotWritableException; +import javax.el.ELContext; +import javax.el.ELResolver; + /** + * Defines variable resolution behavior for the EL implicit objects + * defined in the JSP specification. + * + * <p>The following variables are resolved by this <code>ELResolver</code>, + * as per the JSP specification: + * <ul> + * <li><code>pageContext</code> - the <code>PageContext</code> object.</li> + * <li><code>pageScope</code> - a <code>Map</code> that maps page-scoped + * attribute names to their values.</li> + * <li><code>requestScope</code> - a <code>Map</code> that maps + * request-scoped attribute names to their values.</li> + * <li><code>sessionScope</code> - a <code>Map</code> that maps + * session-scoped attribute names to their values.</li> + * <li><code>applicationScope</code> - a <code>Map</code> that maps + * application-scoped attribute names to their values.</li> + * <li><code>param</code> - a <code>Map</code> that maps parameter + * names to a single String parameter value (obtained by calling + * <code>ServletRequest.getParameter(String name)).</li> + * <li><code>paramValues</code> - a <code>Map</code> that maps parameter + * names to a <code>String[]</code> of all values for that + * parameter (obtained by calling + * <code>ServletRequest.getParameterValues(String name))</code>.</li> + * <li><code>header</code> - a <code>Map</code> that maps header names + * to a single String header value (obtained by calling + * <code>HttpServletRequest.getHeader(String name))</code>.</li> + * <li><code>headerValues</code> - a <code>Map</code> that maps header + * names to a <code>String[]</code> of all values for that header + * (obtained by calling + * <code>HttpServletRequest.getHeaders(String))</code>.</li> + * <li><code>cookie</code> - a <code>Map</code> that maps cookie names + * to a single <code>Cookie</code> object. Cookies are retrieved + * according to the semantics of + * <code>HttpServletRequest.getCookies()</code>. If the same name + * is shared by multiple cookies, an implementation must use the + * first one encountered in the array of <code>Cookie</code> objects + * returned by the <code>getCookies()</code> method. However, users + * of the cookie implicit object must be aware that the ordering + * of cookies is currently unspecified in the servlet + * specification.</li> + * <li><code>initParam</code> - a <code>Map</code> that maps context + * initialization parameter names to their String parameter + * value (obtained by calling + * <code>ServletContext.getInitParameter(String name))</code>.</li> + * </ul></p> * - * @since 2.1 + * @see javax.el.ELResolver + * @since JSP 2.1 */ public class ImplicitObjectELResolver extends ELResolver { - private final static String[] SCOPE_NAMES = new String[] { - "applicationScope", "cookie", "header", "headerValues", - "initParam", "pageContext", "pageScope", "param", "paramValues", - "requestScope", "sessionScope" }; + /** + * If the base object is <code>null</code>, and the property matches + * the name of a JSP implicit object, returns the implicit object. + * + * <p>The <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> by + * this resolver before returning if an implicit object is matched. If + * this property is not <code>true</code> after this method is called, + * the caller should ignore the return value.</p> + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in an immediate return. + * @param property The name of the implicit object to resolve. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the implicit object; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Object getValue(ELContext context, + Object base, + Object property) { - private final static int APPLICATIONSCOPE = 0; - - private final static int COOKIE = 1; - - private final static int HEADER = 2; - - private final static int HEADERVALUES = 3; - - private final static int INITPARAM = 4; - - private final static int PAGECONTEXT = 5; - - private final static int PAGESCOPE = 6; - - private final static int PARAM = 7; - - private final static int PARAM_VALUES = 8; - - private final static int REQUEST_SCOPE = 9; - - private final static int SESSION_SCOPE = 10; - - public ImplicitObjectELResolver() { - super(); - } - - public Object getValue(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { if (context == null) { throw new NullPointerException(); } - if (base == null && property != null) { - int idx = Arrays.binarySearch(SCOPE_NAMES, property.toString()); + if (base != null) { + return null; + } - if (idx >= 0) { - PageContext page = (PageContext) context - .getContext(JspContext.class); - context.setPropertyResolved(true); - switch (idx) { - case APPLICATIONSCOPE: - return ScopeManager.get(page).getApplicationScope(); - case COOKIE: - return ScopeManager.get(page).getCookie(); - case HEADER: - return ScopeManager.get(page).getHeader(); - case HEADERVALUES: - return ScopeManager.get(page).getHeaderValues(); - case INITPARAM: - return ScopeManager.get(page).getInitParam(); - case PAGECONTEXT: - return ScopeManager.get(page).getPageContext(); - case PAGESCOPE: - return ScopeManager.get(page).getPageScope(); - case PARAM: - return ScopeManager.get(page).getParam(); - case PARAM_VALUES: - return ScopeManager.get(page).getParamValues(); - case REQUEST_SCOPE: - return ScopeManager.get(page).getRequestScope(); - case SESSION_SCOPE: - return ScopeManager.get(page).getSessionScope(); - } - } + PageContext ctxt = (PageContext)context.getContext(JspContext.class); + + if ("pageContext".equals(property)) { + context.setPropertyResolved(true); + return ctxt; } + ImplicitObjects implicitObjects = + ImplicitObjects.getImplicitObjects(ctxt); + if ("pageScope".equals(property)) { + context.setPropertyResolved(true); + return implicitObjects.getPageScopeMap(); + } + if ("requestScope".equals(property)) { + context.setPropertyResolved(true); + return implicitObjects.getRequestScopeMap(); + } + if ("sessionScope".equals(property)) { + context.setPropertyResolved(true); + return implicitObjects.getSessionScopeMap(); + } + if ("applicationScope".equals (property)) { + context.setPropertyResolved(true); + return implicitObjects.getApplicationScopeMap (); + } + if ("param".equals (property)) { + context.setPropertyResolved(true); + return implicitObjects.getParamMap(); + } + if ("paramValues".equals (property)) { + context.setPropertyResolved(true); + return implicitObjects.getParamsMap(); + } + if ("header".equals (property)) { + context.setPropertyResolved(true); + return implicitObjects.getHeaderMap(); + } + if ("headerValues".equals (property)) { + context.setPropertyResolved(true); + return implicitObjects.getHeadersMap(); + } + if ("initParam".equals (property)) { + context.setPropertyResolved(true); + return implicitObjects.getInitParamMap (); + } + if ("cookie".equals (property)) { + context.setPropertyResolved(true); + return implicitObjects.getCookieMap (); + } return null; } - public Class getType(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { + /** + * If the base object is <code>null</code>, and the property matches + * the name of a JSP implicit object, returns <code>null</code> to + * indicate that no types are ever accepted to <code>setValue()</code>. + * + * <p>The <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> by + * this resolver before returning if an implicit object is matched. If + * this property is not <code>true</code> after this method is called, + * the caller should ignore the return value.</p> + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in an immediate return. + * @param property The name of the implicit object to resolve. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>null</code>; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Class getType(ELContext context, + Object base, + Object property) { + if (context == null) { throw new NullPointerException(); } - if (base == null && property != null) { - int idx = Arrays.binarySearch(SCOPE_NAMES, property.toString()); - if (idx >= 0) { - context.setPropertyResolved(true); - } + if ((base == null) && ("pageContext".equals(property) || + "pageScope".equals(property)) || + "requestScope".equals(property) || + "sessionScope".equals(property) || + "applicationScope".equals (property) || + "param".equals (property) || + "paramValues".equals (property) || + "header".equals (property) || + "headerValues".equals (property) || + "initParam".equals (property) || + "cookie".equals (property)) { + context.setPropertyResolved(true); } return null; } - public void setValue(ELContext context, Object base, Object property, - Object value) throws NullPointerException, - PropertyNotFoundException, PropertyNotWritableException, - ELException { + /** + * If the base object is <code>null</code>, and the property matches + * the name of a JSP implicit object, throws + * <code>PropertyNotWritableException</code> to indicate that implicit + * objects cannot be overwritten. + * + * <p>The <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> by + * this resolver before returning if an implicit object is matched. If + * this property is not <code>true</code> after this method is called, + * the caller should ignore the return value.</p> + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in an immediate return. + * @param property The name of the implicit object. + * @param val The value to be associated with the implicit object. + * @throws NullPointerException if context is <code>null</code>. + * @throws PropertyNotWritableException always thrown, if the + * implicit object name is recognized by this resolver. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public void setValue(ELContext context, + Object base, + Object property, + Object val) { + if (context == null) { throw new NullPointerException(); } - if (base == null && property != null) { - int idx = Arrays.binarySearch(SCOPE_NAMES, property.toString()); - if (idx >= 0) { - context.setPropertyResolved(true); - throw new PropertyNotWritableException(); - } + if ((base == null) && ("pageContext".equals(property) || + "pageScope".equals(property)) || + "requestScope".equals(property) || + "sessionScope".equals(property) || + "applicationScope".equals (property) || + "param".equals (property) || + "paramValues".equals (property) || + "header".equals (property) || + "headerValues".equals (property) || + "initParam".equals (property) || + "cookie".equals (property)) { + throw new PropertyNotWritableException(); } } - public boolean isReadOnly(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { + /** + * If the base object is <code>null</code>, and the property matches + * the name of a JSP implicit object, returns <code>true</code> + * to indicate that implicit objects cannot be overwritten. + * + * <p>The <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> by + * this resolver before returning if an implicit object is matched. If + * this property is not <code>true</code> after this method is called, + * the caller should ignore the return value.</p> + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in an immediate return. + * @param property The name of the implicit object. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>true</code>; otherwise undefined. + * @throws NullPointerException if context is <code>null</code>. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public boolean isReadOnly(ELContext context, + Object base, + Object property) { if (context == null) { throw new NullPointerException(); } - if (base == null && property != null) { - int idx = Arrays.binarySearch(SCOPE_NAMES, property.toString()); - if (idx >= 0) { - context.setPropertyResolved(true); - return true; - } + if ((base == null) && ("pageContext".equals(property) || + "pageScope".equals(property)) || + "requestScope".equals(property) || + "sessionScope".equals(property) || + "applicationScope".equals (property) || + "param".equals (property) || + "paramValues".equals (property) || + "header".equals (property) || + "headerValues".equals (property) || + "initParam".equals (property) || + "cookie".equals (property)) { + context.setPropertyResolved(true); + return true; } - return false; + return false; // Doesn't matter } - public Iterator<FeatureDescriptor> getFeatureDescriptors(ELContext context, Object base) { - List<FeatureDescriptor> feats = new ArrayList<FeatureDescriptor>( - SCOPE_NAMES.length); - FeatureDescriptor feat; - for (int i = 0; i < SCOPE_NAMES.length; i++) { - feat = new FeatureDescriptor(); - feat.setDisplayName(SCOPE_NAMES[i]); - feat.setExpert(false); - feat.setHidden(false); - feat.setName(SCOPE_NAMES[i]); - feat.setPreferred(true); - feat.setValue(RESOLVABLE_AT_DESIGN_TIME, Boolean.TRUE); - feat.setValue(TYPE, String.class); - feats.add(feat); - } - return feats.iterator(); + /** + * If the base object is <code>null</code>, and the property matches + * the name of a JSP implicit object, returns an <code>Iterator</code> + * containing <code>FeatureDescriptor</code> objects with information + * about each JSP implicit object resolved by this resolver. Otherwise, + * returns <code>null</code>. + * + * <p>The <code>Iterator</code> returned must contain one instance of + * {@link java.beans.FeatureDescriptor} for each of the EL implicit objects + * defined by the JSP spec. Each info object contains information about + * a single implicit object, and is initialized as follows: + * <dl> + * <li>displayName - The name of the implicit object.</li> + * <li>name - Same as displayName property.</li> + * <li>shortDescription - A suitable description for the implicit + * object. Will vary by implementation.</li> + * <li>expert - <code>false</code></li> + * <li>hidden - <code>false</code></li> + * <li>preferred - <code>true</code></li> + * </dl> + * In addition, the following named attributes must be set in the + * returned <code>FeatureDescriptor</code>s: + * <dl> + * <li>{@link ELResolver#TYPE} - The runtime type of the implicit object.</li> + * <li>{@link ELResolver#RESOLVABLE_AT_DESIGN_TIME} - <code>true</code>.</li> + * </dl></p> + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in a <code>null</code> return value. + * @return An <code>Iterator</code> containing one + * <code>FeatureDescriptor</code> object for each implicit object, or + * <code>null</code> if <code>base</code> is not <code>null</code>. + */ + public Iterator<FeatureDescriptor> getFeatureDescriptors( + ELContext context, + Object base) { + ArrayList<FeatureDescriptor> list = + new ArrayList<FeatureDescriptor>(11); + + // pageContext + FeatureDescriptor descriptor = new FeatureDescriptor(); + descriptor.setName("pageContext"); + descriptor.setDisplayName("pageContext"); + //descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", javax.servlet.jsp.PageContext.class); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + + // pageScope + descriptor = new FeatureDescriptor(); + descriptor.setName("pageScope"); + descriptor.setDisplayName("pageScope"); + //descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", Map.class); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + + // requestScope + descriptor = new FeatureDescriptor(); + descriptor.setName("requestScope"); + descriptor.setDisplayName("requestScope"); + //descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", Map.class); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + + // sessionScope + descriptor = new FeatureDescriptor(); + descriptor.setName("sessionScope"); + descriptor.setDisplayName("sessionScope"); + //descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", Map.class); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + + // applicationScope + descriptor = new FeatureDescriptor(); + descriptor.setName("applicationScope"); + descriptor.setDisplayName("applicationScope"); + //descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", Map.class); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + + // param + descriptor = new FeatureDescriptor(); + descriptor.setName("param"); + descriptor.setDisplayName("param"); + //descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", Map.class); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + + // paramValues + descriptor = new FeatureDescriptor(); + descriptor.setName("paramValues"); + descriptor.setDisplayName("paramValues"); + //descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", Map.class); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + + // header + descriptor = new FeatureDescriptor(); + descriptor.setName("header"); + descriptor.setDisplayName("header"); + //descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", Map.class); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + + // headerValues + descriptor = new FeatureDescriptor(); + descriptor.setName("headerValues"); + descriptor.setDisplayName("headerValues"); + //descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", Map.class); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + + // cookie + descriptor = new FeatureDescriptor(); + descriptor.setName("cookie"); + descriptor.setDisplayName("cookie"); + //descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", Map.class); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + + // initParam + descriptor = new FeatureDescriptor(); + descriptor.setName("initParam"); + descriptor.setDisplayName("initParam"); + //descriptor.setShortDescription(""); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", Map.class); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + + return list.iterator(); } - public Class<String> getCommonPropertyType(ELContext context, Object base) { + /** + * If the base object is <code>null</code>, returns + * <code>String.class</code>. Otherwise, returns <code>null</code>. + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in a <code>null</code> return value. + * @return <code>null</code> if base is not <code>null</code>; otherwise + * <code>String.class</code>. + */ + public Class<String> getCommonPropertyType(ELContext context, + Object base) { if (base == null) { return String.class; } return null; } - private static class ScopeManager { - private final static String MNGR_KEY = ScopeManager.class.getName(); + // XXX - I moved this class from commons-el to an inner class here + // so that we do not have a dependency from the JSP APIs into commons-el. + // There might be a better way to do this. + /** + * <p>This class is used to generate the implicit Map and List objects + * that wrap various elements of the PageContext. It also returns the + * correct implicit object for a given implicit object name. + * + * @author Nathan Abramson - Art Technology Group + **/ + private static class ImplicitObjects + { + //------------------------------------- + // Constants + //------------------------------------- - private final PageContext page; + + // XXX - This probably needs to change, now that this is in a + // standard pkg. + static final String sAttributeName = + "org.apache.taglibs.standard.ImplicitObjects"; - private Map applicationScope; + //------------------------------------- + // Member variables + //------------------------------------- - private Map cookie; + PageContext mContext; + Map mPage; + Map mRequest; + Map mSession; + Map mApplication; + Map mParam; + Map mParams; + Map mHeader; + Map mHeaders; + Map mInitParam; + Map mCookie; - private Map header; + //------------------------------------- + /** + * + * Constructor + **/ + public ImplicitObjects (PageContext pContext) + { + mContext = pContext; + } - private Map headerValues; + //------------------------------------- + /** + * + * Finds the ImplicitObjects associated with the PageContext, + * creating it if it doesn't yet exist. + **/ + public static ImplicitObjects getImplicitObjects (PageContext pContext) + { + ImplicitObjects objs = + (ImplicitObjects) + pContext.getAttribute (sAttributeName, + PageContext.PAGE_SCOPE); + if (objs == null) { + objs = new ImplicitObjects (pContext); + pContext.setAttribute (sAttributeName, + objs, + PageContext.PAGE_SCOPE); + } + return objs; + } - private Map initParam; + //------------------------------------- + /** + * + * Returns the Map that "wraps" page-scoped attributes + **/ + public Map getPageScopeMap () + { + if (mPage == null) { + mPage = createPageScopeMap (mContext); + } + return mPage; + } - private Map pageScope; + //------------------------------------- + /** + * + * Returns the Map that "wraps" request-scoped attributes + **/ + public Map getRequestScopeMap () + { + if (mRequest == null) { + mRequest = createRequestScopeMap (mContext); + } + return mRequest; + } - private Map param; + //------------------------------------- + /** + * + * Returns the Map that "wraps" session-scoped attributes + **/ + public Map getSessionScopeMap () + { + if (mSession == null) { + mSession = createSessionScopeMap (mContext); + } + return mSession; + } - private Map paramValues; + //------------------------------------- + /** + * + * Returns the Map that "wraps" application-scoped attributes + **/ + public Map getApplicationScopeMap () + { + if (mApplication == null) { + mApplication = createApplicationScopeMap (mContext); + } + return mApplication; + } - private Map requestScope; + //------------------------------------- + /** + * + * Returns the Map that maps parameter name to a single parameter + * values. + **/ + public Map getParamMap () + { + if (mParam == null) { + mParam = createParamMap (mContext); + } + return mParam; + } - private Map sessionScope; + //------------------------------------- + /** + * + * Returns the Map that maps parameter name to an array of parameter + * values. + **/ + public Map getParamsMap () + { + if (mParams == null) { + mParams = createParamsMap (mContext); + } + return mParams; + } - public ScopeManager(PageContext page) { - this.page = page; + //------------------------------------- + /** + * + * Returns the Map that maps header name to a single header + * values. + **/ + public Map getHeaderMap () + { + if (mHeader == null) { + mHeader = createHeaderMap (mContext); } + return mHeader; + } - public static ScopeManager get(PageContext page) { - ScopeManager mngr = (ScopeManager) page.getAttribute(MNGR_KEY); - if (mngr == null) { - mngr = new ScopeManager(page); - page.setAttribute(MNGR_KEY, mngr); - } - return mngr; + //------------------------------------- + /** + * + * Returns the Map that maps header name to an array of header + * values. + **/ + public Map getHeadersMap () + { + if (mHeaders == null) { + mHeaders = createHeadersMap (mContext); } + return mHeaders; + } - public Map getApplicationScope() { - if (this.applicationScope == null) { - this.applicationScope = new ScopeMap() { - protected void setAttribute(String name, Object value) { - page.getServletContext().setAttribute(name, value); - } + //------------------------------------- + /** + * + * Returns the Map that maps init parameter name to a single init + * parameter values. + **/ + public Map getInitParamMap () + { + if (mInitParam == null) { + mInitParam = createInitParamMap (mContext); + } + return mInitParam; + } - protected void removeAttribute(String name) { - page.getServletContext().removeAttribute(name); - } + //------------------------------------- + /** + * + * Returns the Map that maps cookie name to the first matching + * Cookie in request.getCookies(). + **/ + public Map getCookieMap () + { + if (mCookie == null) { + mCookie = createCookieMap (mContext); + } + return mCookie; + } - protected Enumeration getAttributeNames() { - return page.getServletContext().getAttributeNames(); - } + //------------------------------------- + // Methods for generating wrapper maps + //------------------------------------- + /** + * + * Creates the Map that "wraps" page-scoped attributes + **/ + public static Map createPageScopeMap (PageContext pContext) + { + final PageContext context = pContext; + return new EnumeratedMap () + { + public Enumeration enumerateKeys () + { + return context.getAttributeNamesInScope + (PageContext.PAGE_SCOPE); + } - protected Object getAttribute(String name) { - return page.getServletContext().getAttribute(name); - } - }; + public Object getValue (Object pKey) + { + if (pKey instanceof String) { + return context.getAttribute + ((String) pKey, + PageContext.PAGE_SCOPE); + } + else { + return null; + } } - return this.applicationScope; - } - public Map getCookie() { - if (this.cookie == null) { - this.cookie = new ScopeMap() { - protected Enumeration getAttributeNames() { - Cookie[] c = ((HttpServletRequest) page.getRequest()) - .getCookies(); - if (c != null) { - Vector v = new Vector(); - for (int i = 0; i < c.length; i++) { - v.add(c[i].getName()); - } - return v.elements(); - } - return null; - } + public boolean isMutable () + { + return true; + } + }; + } - protected Object getAttribute(String name) { - Cookie[] c = ((HttpServletRequest) page.getRequest()) - .getCookies(); - if (c != null) { - for (int i = 0; i < c.length; i++) { - if (name.equals(c[i].getName())) { - return c[i]; - } - } - } - return null; - } + //------------------------------------- + /** + * + * Creates the Map that "wraps" request-scoped attributes + **/ + public static Map createRequestScopeMap (PageContext pContext) + { + final PageContext context = pContext; + return new EnumeratedMap () + { + public Enumeration enumerateKeys () + { + return context.getAttributeNamesInScope + (PageContext.REQUEST_SCOPE); + } - }; + public Object getValue (Object pKey) + { + if (pKey instanceof String) { + return context.getAttribute + ((String) pKey, + PageContext.REQUEST_SCOPE); + } + else { + return null; + } } - return this.cookie; - } - public Map getHeader() { - if (this.header == null) { - this.header = new ScopeMap() { - protected Enumeration getAttributeNames() { - return ((HttpServletRequest) page.getRequest()) - .getHeaderNames(); - } + public boolean isMutable () + { + return true; + } + }; + } - protected Object getAttribute(String name) { - return ((HttpServletRequest) page.getRequest()) - .getHeader(name); - } - }; + //------------------------------------- + /** + * + * Creates the Map that "wraps" session-scoped attributes + **/ + public static Map createSessionScopeMap (PageContext pContext) + { + final PageContext context = pContext; + return new EnumeratedMap () + { + public Enumeration enumerateKeys () + { + return context.getAttributeNamesInScope + (PageContext.SESSION_SCOPE); } - return this.header; - } - public Map getHeaderValues() { - if (this.headerValues == null) { - this.headerValues = new ScopeMap() { - protected Enumeration getAttributeNames() { - return ((HttpServletRequest) page.getRequest()) - .getHeaderNames(); - } + public Object getValue (Object pKey) + { + if (pKey instanceof String) { + return context.getAttribute + ((String) pKey, + PageContext.SESSION_SCOPE); + } + else { + return null; + } + } - protected Object getAttribute(String name) { - Enumeration e = ((HttpServletRequest) page.getRequest()) - .getHeaders(name); - if (e != null) { - List list = new ArrayList(); - while (e.hasMoreElements()) { - list.add(e.nextElement().toString()); - } - return (String[]) list.toArray(new String[list - .size()]); - } - return null; - } + public boolean isMutable () + { + return true; + } + }; + } - }; + //------------------------------------- + /** + * + * Creates the Map that "wraps" application-scoped attributes + **/ + public static Map createApplicationScopeMap (PageContext pContext) + { + final PageContext context = pContext; + return new EnumeratedMap () + { + public Enumeration enumerateKeys () + { + return context.getAttributeNamesInScope + (PageContext.APPLICATION_SCOPE); } - return this.headerValues; - } - public Map getInitParam() { - if (this.initParam == null) { - this.initParam = new ScopeMap() { - protected Enumeration getAttributeNames() { - return page.getServletContext().getInitParameterNames(); - } + public Object getValue (Object pKey) + { + if (pKey instanceof String) { + return context.getAttribute + ((String) pKey, + PageContext.APPLICATION_SCOPE); + } + else { + return null; + } + } - protected Object getAttribute(String name) { - return page.getServletContext().getInitParameter(name); - } - }; + public boolean isMutable () + { + return true; } - return this.initParam; - } + }; + } - public PageContext getPageContext() { - return this.page; - } + //------------------------------------- + /** + * + * Creates the Map that maps parameter name to single parameter + * value. + **/ + public static Map createParamMap (PageContext pContext) + { + final HttpServletRequest request = + (HttpServletRequest) pContext.getRequest (); + return new EnumeratedMap () + { + public Enumeration enumerateKeys () + { + return request.getParameterNames (); + } - public Map getPageScope() { - if (this.pageScope == null) { - this.pageScope = new ScopeMap() { - protected void setAttribute(String name, Object value) { - page.setAttribute(name, value); - } + public Object getValue (Object pKey) + { + if (pKey instanceof String) { + return request.getParameter ((String) pKey); + } + else { + return null; + } + } - protected void removeAttribute(String name) { - page.removeAttribute(name); - } + public boolean isMutable () + { + return false; + } + }; + } - protected Enumeration getAttributeNames() { - return page - .getAttributeNamesInScope(PageContext.PAGE_SCOPE); - } + //------------------------------------- + /** + * + * Creates the Map that maps parameter name to an array of parameter + * values. + **/ + public static Map createParamsMap (PageContext pContext) + { + final HttpServletRequest request = + (HttpServletRequest) pContext.getRequest (); + return new EnumeratedMap () + { + public Enumeration enumerateKeys () + { + return request.getParameterNames (); + } - protected Object getAttribute(String name) { - return page.getAttribute(name); - } - }; + public Object getValue (Object pKey) + { + if (pKey instanceof String) { + return request.getParameterValues ((String) pKey); + } + else { + return null; + } } - return this.pageScope; - } - public Map getParam() { - if (this.param == null) { - this.param = new ScopeMap() { - protected Enumeration getAttributeNames() { - return page.getRequest().getParameterNames(); - } + public boolean isMutable () + { + return false; + } + }; + } - protected Object getAttribute(String name) { - return page.getRequest().getParameter(name); - } - }; + //------------------------------------- + /** + * + * Creates the Map that maps header name to single header + * value. + **/ + public static Map createHeaderMap (PageContext pContext) + { + final HttpServletRequest request = + (HttpServletRequest) pContext.getRequest (); + return new EnumeratedMap () + { + public Enumeration enumerateKeys () + { + return request.getHeaderNames (); } - return this.param; - } - public Map getParamValues() { - if (this.paramValues == null) { - this.paramValues = new ScopeMap() { - protected Object getAttribute(String name) { - return page.getRequest().getParameterValues(name); - } + public Object getValue (Object pKey) + { + if (pKey instanceof String) { + return request.getHeader ((String) pKey); + } + else { + return null; + } + } - protected Enumeration getAttributeNames() { - return page.getRequest().getParameterNames(); - } - }; + public boolean isMutable () + { + return false; } - return this.paramValues; - } + }; + } - public Map getRequestScope() { - if (this.requestScope == null) { - this.requestScope = new ScopeMap() { - protected void setAttribute(String name, Object value) { - page.getRequest().setAttribute(name, value); - } + //------------------------------------- + /** + * + * Creates the Map that maps header name to an array of header + * values. + **/ + public static Map createHeadersMap (PageContext pContext) + { + final HttpServletRequest request = + (HttpServletRequest) pContext.getRequest (); + return new EnumeratedMap () + { + public Enumeration enumerateKeys () + { + return request.getHeaderNames (); + } - protected void removeAttribute(String name) { - page.getRequest().removeAttribute(name); - } + public Object getValue (Object pKey) + { + if (pKey instanceof String) { + // Drain the header enumeration + List l = new ArrayList (); + Enumeration e = request.getHeaders ((String) pKey); + if (e != null) { + while (e.hasMoreElements ()) { + l.add (e.nextElement ()); + } + } + String [] ret = (String []) l.toArray (new String [l.size ()]); + return ret; + } + else { + return null; + } + } - protected Enumeration getAttributeNames() { - return page.getRequest().getAttributeNames(); - } + public boolean isMutable () + { + return false; + } + }; + } - protected Object getAttribute(String name) { - return page.getRequest().getAttribute(name); - } - }; + //------------------------------------- + /** + * + * Creates the Map that maps init parameter name to single init + * parameter value. + **/ + public static Map createInitParamMap (PageContext pContext) + { + final ServletContext context = pContext.getServletContext (); + return new EnumeratedMap () + { + public Enumeration enumerateKeys () + { + return context.getInitParameterNames (); } - return this.requestScope; - } - public Map getSessionScope() { - if (this.sessionScope == null) { - this.sessionScope = new ScopeMap() { - protected void setAttribute(String name, Object value) { - ((HttpServletRequest) page.getRequest()).getSession() - .setAttribute(name, value); - } + public Object getValue (Object pKey) + { + if (pKey instanceof String) { + return context.getInitParameter ((String) pKey); + } + else { + return null; + } + } - protected void removeAttribute(String name) { - HttpSession session = page.getSession(); - if (session != null) { - session.removeAttribute(name); - } - } + public boolean isMutable () + { + return false; + } + }; + } - protected Enumeration getAttributeNames() { - HttpSession session = page.getSession(); - if (session != null) { - return session.getAttributeNames(); - } - return null; - } - - protected Object getAttribute(String name) { - HttpSession session = page.getSession(); - if (session != null) { - return session.getAttribute(name); - } - return null; - } - }; + //------------------------------------- + /** + * + * Creates the Map that maps cookie name to the first matching + * Cookie in request.getCookies(). + **/ + public static Map createCookieMap (PageContext pContext) + { + // Read all the cookies and construct the entire map + HttpServletRequest request = (HttpServletRequest) pContext.getRequest (); + Cookie [] cookies = request.getCookies (); + Map ret = new HashMap (); + for (int i = 0; cookies != null && i < cookies.length; i++) { + Cookie cookie = cookies [i]; + if (cookie != null) { + String name = cookie.getName (); + if (!ret.containsKey (name)) { + ret.put (name, cookie); } - return this.sessionScope; + } } + return ret; + } + + //------------------------------------- } + + // XXX - I moved this class from commons-el to an inner class here + // so that we do not have a dependency from the JSP APIs into commons-el. + // There might be a better way to do this. + /** + * <p>This is a Map implementation driven by a data source that only + * provides an enumeration of keys and a getValue(key) method. This + * class must be subclassed to implement those methods. + * + * <p>Some of the methods may incur a performance penalty that + * involves enumerating the entire data source. In these cases, the + * Map will try to save the results of that enumeration, but only if + * the underlying data source is immutable. + * + * @author Nathan Abramson - Art Technology Group + **/ + private static abstract class EnumeratedMap + implements Map + { + //------------------------------------- + // Member variables + //------------------------------------- - private abstract static class ScopeMap extends AbstractMap { + Map mMap; - protected abstract Enumeration getAttributeNames(); + //------------------------------------- + public void clear () + { + throw new UnsupportedOperationException (); + } - protected abstract Object getAttribute(String name); + //------------------------------------- + public boolean containsKey (Object pKey) + { + return getValue (pKey) != null; + } - protected void removeAttribute(String name) { - throw new UnsupportedOperationException(); - } + //------------------------------------- + public boolean containsValue (Object pValue) + { + return getAsMap ().containsValue (pValue); + } - protected void setAttribute(String name, Object value) { - throw new UnsupportedOperationException(); - } + //------------------------------------- + public Set entrySet () + { + return getAsMap ().entrySet (); + } - public final Set entrySet() { - Enumeration e = getAttributeNames(); - Set set = new HashSet(); - if (e != null) { - while (e.hasMoreElements()) { - set.add(new ScopeEntry((String) e.nextElement())); - } - } - return set; - } + //------------------------------------- + public Object get (Object pKey) + { + return getValue (pKey); + } - private class ScopeEntry implements Map.Entry { + //------------------------------------- + public boolean isEmpty () + { + return !enumerateKeys ().hasMoreElements (); + } - private final String key; + //------------------------------------- + public Set keySet () + { + return getAsMap ().keySet (); + } - public ScopeEntry(String key) { - this.key = key; - } + //------------------------------------- + public Object put (Object pKey, Object pValue) + { + throw new UnsupportedOperationException (); + } - public Object getKey() { - return (Object) this.key; - } + //------------------------------------- + public void putAll (Map pMap) + { + throw new UnsupportedOperationException (); + } - public Object getValue() { - return getAttribute(this.key); - } + //------------------------------------- + public Object remove (Object pKey) + { + throw new UnsupportedOperationException (); + } - public Object setValue(Object value) { - if (value == null) { - removeAttribute(this.key); - } else { - setAttribute(this.key, value); - } - return null; - } + //------------------------------------- + public int size () + { + return getAsMap ().size (); + } - public boolean equals(Object obj) { - return (obj != null && this.hashCode() == obj.hashCode()); - } + //------------------------------------- + public Collection values () + { + return getAsMap ().values (); + } - public int hashCode() { - return this.key.hashCode(); - } + //------------------------------------- + // Abstract methods + //------------------------------------- + /** + * + * Returns an enumeration of the keys + **/ + public abstract Enumeration enumerateKeys (); - } + //------------------------------------- + /** + * + * Returns true if it is possible for this data source to change + **/ + public abstract boolean isMutable (); - public final Object get(Object key) { - if (key != null) { - return getAttribute(key.toString()); - } - return null; - } + //------------------------------------- + /** + * + * Returns the value associated with the given key, or null if not + * found. + **/ + public abstract Object getValue (Object pKey); - public final Object put(Object key, Object value) { - if (key == null) { - throw new NullPointerException(); - } - if (value == null) { - this.removeAttribute(key.toString()); - } else { - this.setAttribute(key.toString(), value); - } - return null; + //------------------------------------- + /** + * + * Converts the MapSource to a Map. If the map is not mutable, this + * is cached + **/ + public Map getAsMap () + { + if (mMap != null) { + return mMap; } + else { + Map m = convertToMap (); + if (!isMutable ()) { + mMap = m; + } + return m; + } + } - public final Object remove(Object key) { - if (key == null) { - throw new NullPointerException(); - } - this.removeAttribute(key.toString()); - return null; + //------------------------------------- + /** + * + * Converts to a Map + **/ + Map convertToMap () + { + Map ret = new HashMap (); + for (Enumeration e = enumerateKeys (); e.hasMoreElements (); ) { + Object key = e.nextElement (); + Object value = getValue (key); + ret.put (key, value); } + return ret; + } + //------------------------------------- } +} -} Modified: trunk/java/javax/servlet/jsp/el/ScopedAttributeELResolver.java =================================================================== --- trunk/java/javax/servlet/jsp/el/ScopedAttributeELResolver.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/el/ScopedAttributeELResolver.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,199 +1,387 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.el; import java.beans.FeatureDescriptor; +import java.util.Iterator; import java.util.ArrayList; -import java.util.Collection; import java.util.Enumeration; -import java.util.Iterator; -import java.util.List; +import javax.servlet.jsp.PageContext; +import javax.servlet.jsp.JspContext; + import javax.el.ELContext; +import javax.el.ELResolver; import javax.el.ELException; -import javax.el.ELResolver; -import javax.el.PropertyNotFoundException; -import javax.el.PropertyNotWritableException; -import javax.servlet.jsp.JspContext; -import javax.servlet.jsp.PageContext; +/** + * Defines variable resolution behavior for scoped attributes. + * + * <p>This resolver handles all variable resolutions (where <code>base</code> + * is <code>null</code>. It searches <code>PageContext.findAttribute()</code> + * for a matching attribute. If not found, it will return <code>null</code>, + * or in the case of <code>setValue</code> it will create a new attribute + * in the page scope with the given name.</p> + * + * @see javax.el.ELResolver + * @since JSP 2.1 + */ + public class ScopedAttributeELResolver extends ELResolver { - public ScopedAttributeELResolver() { - super(); - } + /** + * If the base object is <code>null</code>, searches the page, + * request, session and application scopes for an attribute with + * the given name and returns it, or <code>null</code> if no + * attribute exists with the current name. + * + * <p>The <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> by + * this resolver before returning if base is <code>null</code>. If + * this property is not <code>true</code> after this method is called, + * the caller should ignore the return value.</p> + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in an immediate return. + * @param property The name of the scoped attribute to resolve. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * the scoped attribute; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Object getValue(ELContext context, + Object base, + Object property) { - public Object getValue(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + if (context == null) { + throw new NullPointerException(); + } - if (base == null) { - context.setPropertyResolved(true); - if (property != null) { - String key = property.toString(); - PageContext page = (PageContext) context - .getContext(JspContext.class); - return page.findAttribute(key); - } - } + if (base == null) { + context.setPropertyResolved(true); + if (property instanceof String) { + String attribute = (String) property; + PageContext ctxt = (PageContext) + context.getContext(JspContext.class); + return ctxt.findAttribute(attribute); + } + } + return null; + } - return null; - } + /** + * If the base object is <code>null</code>, returns + * <code>Object.class</code> to indicate that any type is valid to + * set for a scoped attribute. + * + * <p>The <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> by + * this resolver before returning if base is <code>null</code>. If + * this property is not <code>true</code> after this method is called, + * the caller should ignore the return value.</p> + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in an immediate return. + * @param property The name of the scoped attribute to resolve. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>Object.class</code>; otherwise undefined. + * @throws NullPointerException if context is <code>null</code> + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public Class<Object> getType(ELContext context, + Object base, + Object property) { - public Class<Object> getType(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + if (context == null) { + throw new NullPointerException(); + } - if (base == null) { - context.setPropertyResolved(true); - return Object.class; - } + if (base == null) { + context.setPropertyResolved(true); + return Object.class; + } + return null; + } - return null; - } - public void setValue(ELContext context, Object base, Object property, - Object value) throws NullPointerException, - PropertyNotFoundException, PropertyNotWritableException, - ELException { - if (context == null) { - throw new NullPointerException(); - } + /** + * If the base object is <code>null</code>, sets an existing scoped + * attribute to the new value, or creates a new scoped attribute if one + * does not exist by this name. + * + * <p>If the provided attribute name matches the key of an attribute + * in page scope, request scope, session scope, or application scope, the + * corresponding attribute value will be replaced by the provided value. + * Otherwise, a new page scope attribute will be created with the + * given name and value.</p> + * + * <p>The <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> by + * this resolver before returning if base is <code>null</code>. If + * this property is not <code>true</code> after this method is called, + * the caller should ignore the return value.</p> + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in an immediate return. + * @param property The name of the scoped attribute to set. + * @param val The value for the scoped attribute. + * @throws NullPointerException if context is <code>null</code>. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public void setValue(ELContext context, + Object base, + Object property, + Object val) { + if (context == null) { + throw new NullPointerException(); + } - if (base == null) { - context.setPropertyResolved(true); - if (property != null) { - String key = property.toString(); - PageContext page = (PageContext) context - .getContext(JspContext.class); - int scope = page.getAttributesScope(key); - if (scope != 0) { - page.setAttribute(key, value, scope); - } else { - page.setAttribute(key, value); - } - } - } - } + if (base == null) { + context.setPropertyResolved(true); + if (property instanceof String) { + PageContext ctxt = (PageContext) + context.getContext(JspContext.class); + String attr = (String) property; + if (ctxt.getAttribute(attr, PageContext.REQUEST_SCOPE) != null) + ctxt.setAttribute(attr, val, PageContext.REQUEST_SCOPE); + else if (ctxt.getAttribute(attr, PageContext.SESSION_SCOPE) != null) + ctxt.setAttribute(attr, val, PageContext.SESSION_SCOPE); + else if (ctxt.getAttribute(attr, PageContext.APPLICATION_SCOPE) != null) + ctxt.setAttribute(attr, val, PageContext.APPLICATION_SCOPE); + else { + ctxt.setAttribute(attr, val, PageContext.PAGE_SCOPE); + } + } + } + } - public boolean isReadOnly(ELContext context, Object base, Object property) - throws NullPointerException, PropertyNotFoundException, ELException { - if (context == null) { - throw new NullPointerException(); - } + /** + * If the base object is <code>null</code>, returns <code>false</code> + * to indicate that scoped attributes are never read-only. + * + * <p>The <code>propertyResolved</code> property of the + * <code>ELContext</code> object must be set to <code>true</code> by + * this resolver before returning if base is <code>null</code>. If + * this property is not <code>true</code> after this method is called, + * the caller should ignore the return value.</p> + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in an immediate return. + * @param property The name of the scoped attribute. + * @return If the <code>propertyResolved</code> property of + * <code>ELContext</code> was set to <code>true</code>, then + * <code>false</code>; otherwise undefined. + * @throws NullPointerException if context is <code>null</code>. + * @throws ELException if an exception was thrown while performing + * the property or variable resolution. The thrown exception + * must be included as the cause property of this exception, if + * available. + */ + public boolean isReadOnly(ELContext context, + Object base, + Object property) { + if (context == null) { + throw new NullPointerException(); + } - if (base == null) { - context.setPropertyResolved(true); - } + if (base == null) { + context.setPropertyResolved(true); + } + return false; + } - return false; - } + /** + * If the base object is <code>null</code>, returns an + * <code>Iterator</code> containing <code>FeatureDescriptor</code> objects + * with information about each scoped attribute resolved by this + * resolver. Otherwise, returns <code>null</code>. + * + * <p>The <code>Iterator</code> returned must contain one instance of + * {@link java.beans.FeatureDescriptor} for each scoped attribute found in + * any scope. Each info object contains information about + * a single scoped attribute, and is initialized as follows: + * + * <dl> + * <li>displayName - The name of the scoped attribute.</li> + * <li>name - Same as displayName property.</li> + * <li>shortDescription - A suitable description for the scoped + * attribute. Should include the attribute's current scope + * (page, request, session, application). Will vary by + * implementation.</li> + * <li>expert - <code>false</code></li> + * <li>hidden - <code>false</code></li> + * <li>preferred - <code>true</code></li> + * </dl> + * In addition, the following named attributes must be set in the + * returned <code>FeatureDescriptor</code>s: + * <dl> + * <li>{@link ELResolver#TYPE} - The current runtime type of the scoped attribute.</li> + * <li>{@link ELResolver#RESOLVABLE_AT_DESIGN_TIME} - <code>true</code>.</li> + * </dl></p> + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in a <code>null</code> return value. + * @return An <code>Iterator</code> containing one + * <code>FeatureDescriptor</code> object for each scoped attribute, or + * <code>null</code> if <code>base</code> is not <code>null</code>. + */ + public Iterator<FeatureDescriptor> getFeatureDescriptors( + ELContext context, + Object base) { + Enumeration attrs; + ArrayList<FeatureDescriptor> list = new ArrayList<FeatureDescriptor>(); + PageContext ctxt = (PageContext) context.getContext(JspContext.class); - public Iterator<FeatureDescriptor> getFeatureDescriptors(ELContext context, Object base) { + attrs = ctxt.getAttributeNamesInScope(PageContext.PAGE_SCOPE); + while (attrs.hasMoreElements()) { + String name = (String) attrs.nextElement(); + Object value = ctxt.getAttribute(name, PageContext.PAGE_SCOPE); + FeatureDescriptor descriptor = new FeatureDescriptor(); + descriptor.setName(name); + descriptor.setDisplayName(name); + descriptor.setShortDescription("page scope attribute"); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", value.getClass()); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + } - PageContext ctxt = (PageContext) context.getContext(JspContext.class); - List<FeatureDescriptor> list = new ArrayList<FeatureDescriptor>(); - Enumeration e; - Object value; - String name; + attrs = ctxt.getAttributeNamesInScope(PageContext.REQUEST_SCOPE); + while (attrs.hasMoreElements()) { + String name = (String) attrs.nextElement(); + Object value = ctxt.getAttribute(name, PageContext.REQUEST_SCOPE); + FeatureDescriptor descriptor = new FeatureDescriptor(); + descriptor.setName(name); + descriptor.setDisplayName(name); + descriptor.setShortDescription("request scope attribute"); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", value.getClass()); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + } - e = ctxt.getAttributeNamesInScope(PageContext.PAGE_SCOPE); - while (e.hasMoreElements()) { - name = (String) e.nextElement(); - value = ctxt.getAttribute(name, PageContext.PAGE_SCOPE); - FeatureDescriptor descriptor = new FeatureDescriptor(); - descriptor.setName(name); - descriptor.setDisplayName(name); - descriptor.setExpert(false); - descriptor.setHidden(false); - descriptor.setPreferred(true); - descriptor.setShortDescription("page scoped attribute"); - descriptor.setValue("type", value.getClass()); - descriptor.setValue("resolvableAtDesignTime", Boolean.FALSE); - list.add(descriptor); - } + attrs = ctxt.getAttributeNamesInScope(PageContext.SESSION_SCOPE); + while (attrs.hasMoreElements()) { + String name = (String) attrs.nextElement(); + Object value = ctxt.getAttribute(name, PageContext.SESSION_SCOPE); + FeatureDescriptor descriptor = new FeatureDescriptor(); + descriptor.setName(name); + descriptor.setDisplayName(name); + descriptor.setShortDescription("session scope attribute"); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", value.getClass()); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + } - e = ctxt.getAttributeNamesInScope(PageContext.REQUEST_SCOPE); - while (e.hasMoreElements()) { - name = (String) e.nextElement(); - value = ctxt.getAttribute(name, PageContext.REQUEST_SCOPE); - FeatureDescriptor descriptor = new FeatureDescriptor(); - descriptor.setName(name); - descriptor.setDisplayName(name); - descriptor.setExpert(false); - descriptor.setHidden(false); - descriptor.setPreferred(true); - descriptor.setShortDescription("request scope attribute"); - descriptor.setValue("type", value.getClass()); - descriptor.setValue("resolvableAtDesignTime", Boolean.FALSE); - list.add(descriptor); - } + attrs = ctxt.getAttributeNamesInScope(PageContext.APPLICATION_SCOPE); + while (attrs.hasMoreElements()) { + String name = (String) attrs.nextElement(); + Object value = ctxt.getAttribute(name, PageContext.APPLICATION_SCOPE); + FeatureDescriptor descriptor = new FeatureDescriptor(); + descriptor.setName(name); + descriptor.setDisplayName(name); + descriptor.setShortDescription("application scope attribute"); + descriptor.setExpert(false); + descriptor.setHidden(false); + descriptor.setPreferred(true); + descriptor.setValue("type", value.getClass()); + descriptor.setValue("resolvableAtDesignTime", Boolean.TRUE); + list.add(descriptor); + } + return list.iterator(); + } - if (ctxt.getSession() != null) { - e = ctxt.getAttributeNamesInScope(PageContext.SESSION_SCOPE); - while (e.hasMoreElements()) { - name = (String) e.nextElement(); - value = ctxt.getAttribute(name, PageContext.SESSION_SCOPE); - FeatureDescriptor descriptor = new FeatureDescriptor(); - descriptor.setName(name); - descriptor.setDisplayName(name); - descriptor.setExpert(false); - descriptor.setHidden(false); - descriptor.setPreferred(true); - descriptor.setShortDescription("session scoped attribute"); - descriptor.setValue("type", value.getClass()); - descriptor.setValue("resolvableAtDesignTime", Boolean.FALSE); - list.add(descriptor); - } - } + /** + * If the base object is <code>null</code>, returns + * <code>String.class</code>. Otherwise, returns <code>null</code>. + * + * @param context The context of this evaluation. + * @param base Only <code>null</code> is handled by this resolver. + * Other values will result in a <code>null</code> return value. + * @return <code>null</code> if base is not <code>null</code>; otherwise + * <code>String.class</code>. + */ + public Class<String> getCommonPropertyType(ELContext context, + Object base) { + if (base == null) { + return String.class; + } + return null; + } - e = ctxt.getAttributeNamesInScope(PageContext.APPLICATION_SCOPE); - while (e.hasMoreElements()) { - name = (String) e.nextElement(); - value = ctxt.getAttribute(name, PageContext.APPLICATION_SCOPE); - FeatureDescriptor descriptor = new FeatureDescriptor(); - descriptor.setName(name); - descriptor.setDisplayName(name); - descriptor.setExpert(false); - descriptor.setHidden(false); - descriptor.setPreferred(true); - descriptor.setShortDescription("application scoped attribute"); - descriptor.setValue("type", value.getClass()); - descriptor.setValue("resolvableAtDesignTime", Boolean.FALSE); - list.add(descriptor); - } - return list.iterator(); - } - - private static void appendEnumeration(Collection c, Enumeration e) { - while (e.hasMoreElements()) { - c.add(e.nextElement()); - } - } - - public Class<String> getCommonPropertyType(ELContext context, Object base) { - if (base == null) { - return String.class; - } - return null; - } } Modified: trunk/java/javax/servlet/jsp/el/VariableResolver.java =================================================================== --- trunk/java/javax/servlet/jsp/el/VariableResolver.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/el/VariableResolver.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.el; @@ -28,8 +65,8 @@ * <p>An instance of this class includes the context against which resolution * will happen</p> * - * @since 2.0 - * @deprecated + * @deprecated As of JSP 2.1, replaced by {@link javax.el.ELResolver} + * @since JSP 2.0 */ public interface VariableResolver { Modified: trunk/java/javax/servlet/jsp/el/package.html =================================================================== --- trunk/java/javax/servlet/jsp/el/package.html 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/el/package.html 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,28 +1,94 @@ +<!-- + DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + + Copyright 1997-2008 Sun Microsystems, Inc. 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.html + or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + Sun designates this particular file as subject to the "Classpath" exception + as provided by Sun in the GPL Version 2 section of the License file that + accompanied this code. If applicable, add the following below the License + Header, with the fields enclosed by brackets [] replaced by your own + identifying information: "Portions Copyrighted [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 "-//IETF//DTD HTML//EN"> <html> <head> -<!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You 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. ---> </head> <body bgcolor="white"> -Classes and interfaces for the JSP 2.0 Expression Language API. +Provides the <code>ELResolver</code> classes that define the +object resolution rules that must be supported by a JSP container +with the new unified Expression Language. <p> +The package also defines programmatic access to the old Expression Language +evaluator (pre JSP 2.1). +<p> +<b>Please note +that as of JSP 2.1, all classes and interfaces that were in package +<code>javax.servlet.jsp.el</code> have been deprecated in favor of the new unified +Expression Language APIs (<code>javax.el</code>). See the Expression Language +specification document for more details.</b> +</p> +<p> +<b>While a JSP container must still support the deprecated APIs defined +in <code>javax.servlet.jsp.el</code>, developers should only rely on the +new <code>javax.el</code> APIs +for new development work.</b> +</p> +<p> +Two ELResolver classes have been added in JSP 2.1 to implement +object resolution rules that must be supported by a JSP container +with the new unified Expression Language: +{@link javax.servlet.jsp.el.ImplicitObjectELResolver} and +{@link javax.servlet.jsp.el.ScopedAttributeELResolver}. +</p> + +<h2>Documentation on the old and deprecated API</h2> + +<p> The JavaServer Pages(tm) (JSP) 2.0 specification provides a portable API for evaluating "EL Expressions". As of JSP 2.0, EL expressions can be placed directly in the template text of JSP pages and tag files. @@ -33,5 +99,91 @@ expressions, but other implementations, like open-coding into Java bytecodes, are allowed. This package is intended to have no dependencies on other portions of the JSP 2.0 specification. + +<h3>Expression Evaluator</h3> + +Programmatic access to the EL Expression Evaluator is provided +through the following types: + +<ul> + <li><code>ExpressionEvaluator</code></li> + <li><code>Expression</code></li> + <li><code>FunctionMapper</code></li> + <li><code>VariableResolver</code></li> +</ul> + +<p> An <code>ExpressionEvaluator</code> object can be obtained from a +JspContext object through the <code>getExpressionEvaluator</code> +method. An ExpressionEvaluator encapsulates the EL processor. An EL +expression provided as a String can then be evaluated directly, or it +can be parsed first into an <code>Expression</code> object. The parse +step, can be used to factor out the cost of parsing the expression, or +even the cost of optimizing the implementation.</p> + +<p>The parsing of an expression string is done against a target type, +a default prefix (that applies when a function has no prefix), and +a <code>FunctionMapper</code>. The <code>FunctionMapper</code> object +maps a prefix and a local name part into a +<code>java.lang.reflect.Method</code> object.</p> + +<p>The interpretation or evaluation of a parsed expression is done +using a <code>VariableResolver</code> object. This object resolves +top level object names into Objects. A <code>VariableResolver</code> +can be obtained from a <code>JspContext</code> object through the +<code>getVariableResolver</code> method.</p> + +<h3>Exceptions</h3> + +<p> +The <code>ELException</code> exception is used by the expression +language to denote any exception that may arise during the parsing or +evaluation of an expression. +The <code>ELParseException</code> exception is a subclass of +<code>ELException</code> that corresponds to parsing errors</p> + +<p>Parsing errors are conveyed as exceptions to simplify the API. It +is expected that many JSP containers will use additional mechanisms to +parse EL expressions and report their errors - a run-time API cannot +provide accurate line-error numbers without additional machinery.</p> + +<h3>Code Fragment</h3> + +<p> +Below is a non-normative code fragment outlining how the APIs can be used.</p> + +<pre> +// Get an instance of an ExpressionEvaluator + + +ExpressionEvaluator ee = myJspContext.getExpressionEvaluator(); +VariableResolver vr = myJspContext.getVariableResolver(); + +FunctionMapper fm; // we don't have a portable implementation yet + +// Example of compiling an expression. See [ISSUE-2] +// Errors detected this way may have higher quality than those +// found with a simple validate() invocation. + +ExpressionCompilation ce; + +try { + ce = ee.prepareExpression(expr, + targetClass, + fm, + null // no prefixes + ); +} catch (ELParseException e) { + log (e.getMessage()); +} + +try { + ce.evaluate(vr); +} catch (ElException e) { + log (e); +} +</pre> + </body> </html> + + Modified: trunk/java/javax/servlet/jsp/package.html =================================================================== --- trunk/java/javax/servlet/jsp/package.html 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/package.html 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,29 +1,160 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<html> -<head> <!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You 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 + DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. - http://www.apache.org/licenses/LICENSE-2.0 + Copyright 1997-2008 Sun Microsystems, Inc. All rights reserved. - 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. + 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.html + or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + Sun designates this particular file as subject to the "Classpath" exception + as provided by Sun in the GPL Version 2 section of the License file that + accompanied this code. If applicable, add the following below the License + Header, with the fields enclosed by brackets [] replaced by your own + identifying information: "Portions Copyrighted [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 "-//IETF//DTD HTML//EN"> +<html> +<head> </head> <body bgcolor="white"> -Classes and interfaces for the Core JSP 2.0 API. +Classes and interfaces for the Core JSP 2.1 API. <p> The javax.servlet.jsp package contains a number of classes and interfaces that describe and define the contracts between a JSP page implementation class and the runtime environment provided for an instance of such a class by a conforming JSP container. +</p> + +<h2>JSP Page Implementation Object Contract</h2> +<p> +This section describes the basic contract between a JSP Page +implementation object and its container. +</p> +<p> +The main contract is defined by the classes +{@link javax.servlet.jsp.JspPage} +and {@link javax.servlet.jsp.HttpJspPage}. +The {@link javax.servlet.jsp.JspFactory} class describes the mechanism to +portably instantiate all needed runtime objects, +and {@link javax.servlet.jsp.JspEngineInfo} provides basic information on +the current JSP container. Class {@link javax.servlet.jsp.JspApplicationContext} +stores application-scoped information relevant to JSP containers. +It was added in JSP 2.1 to support the integration of the unified +Expression Language. +</p> +<p> +None of these classes are intended to be used +by JSP page authors; an example of how these classes may be +used is included below. +</p> + +<h2>Implicit Objects</h2> + +The {@link javax.servlet.jsp.PageContext} object and the +{@link javax.servlet.jsp.JspWriter} +are available by default as implicit objects. + +<h2>Exceptions</h2> + +<p> +The {@link javax.servlet.jsp.JspException} class is the base class for all JSP +exceptions. The {@link javax.servlet.jsp.JspTagException} and +{@link javax.servlet.jsp.SkipPageException} exceptions are used by the +tag extension mechanism.</p> +For JSP error pages, the {@link javax.servlet.jsp.ErrorData} class encapsulates information +about the error. + +</p> + +<h2>An Implementation Example</h2> + +<p> An instance of an implementation dependent subclass of the +{@link javax.servlet.jsp.PageContext} +abstract base class can be created by a JSP implementation class at +the beginning of it's <code>_jspService()</code> method via an +implementation default {@link javax.servlet.jsp.JspFactory}. + +<p>Here is one example of how to use these classes + +<p> +<code> +<pre> + public class foo implements Servlet { + + // ... + +public void _jspService(HttpServletRequest request, + HttpServletResponse response) + throws IOException, ServletException { + + JspFactory factory = JspFactory.getDefaultFactory(); + PageContext pageContext = factory.getPageContext( + this, + request, + response, + null, // errorPageURL + false, // needsSession + JspWriter.DEFAULT_BUFFER, + true // autoFlush + ); + + // initialize implicit variables for scripting env ... + + HttpSession session = pageContext.getSession(); + JspWriter out = pageContext.getOut(); + Object page = this; + + try { + // body of translated JSP here ... + } catch (Exception e) { + out.clear(); + pageContext.handlePageException(e); + } finally { + out.close(); + factory.releasePageContext(pageContext); + } +} +</pre> +</code> + </body> </html> Modified: trunk/java/javax/servlet/jsp/tagext/BodyContent.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/BodyContent.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/BodyContent.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; import java.io.Reader; Modified: trunk/java/javax/servlet/jsp/tagext/BodyTag.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/BodyTag.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/BodyTag.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; import javax.servlet.jsp.*; Modified: trunk/java/javax/servlet/jsp/tagext/BodyTagSupport.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/BodyTagSupport.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/BodyTagSupport.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; import javax.servlet.jsp.JspException; Modified: trunk/java/javax/servlet/jsp/tagext/DynamicAttributes.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/DynamicAttributes.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/DynamicAttributes.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; import javax.servlet.jsp.JspException; @@ -29,7 +66,7 @@ * value of the attribute. It is the responsibility of the tag to * remember the names and values of the dynamic attributes. * - * @since 2.0 + * @since JSP 2.0 */ public interface DynamicAttributes { Modified: trunk/java/javax/servlet/jsp/tagext/FunctionInfo.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/FunctionInfo.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/FunctionInfo.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; @@ -22,7 +59,7 @@ * This class is instantiated from the Tag Library Descriptor file (TLD) * and is available only at translation time. * - * @since 2.0 + * @since JSP 2.0 */ public class FunctionInfo { Modified: trunk/java/javax/servlet/jsp/tagext/IterationTag.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/IterationTag.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/IterationTag.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; Modified: trunk/java/javax/servlet/jsp/tagext/JspFragment.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/JspFragment.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/JspFragment.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; @@ -49,7 +86,7 @@ * JspFragment. Upon construction, a discriminator can be passed to * select which fragment that instance will execute. * - * @since 2.0 + * @since JSP 2.0 */ public abstract class JspFragment { Modified: trunk/java/javax/servlet/jsp/tagext/JspIdConsumer.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/JspIdConsumer.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/JspIdConsumer.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,21 +1,110 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * - * http://www.apache.org/licenses/LICENSE-2.0 + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. */ + package javax.servlet.jsp.tagext; +/** + * <p>This interface indicates to the container that a tag handler + * wishes to be provided with a + * compiler generated ID. </p> + *<p>The container sets the <code>jspId</code> + * attribute + * of the tag handler with an identification string, as part of tag + * property initialization. Each tag in a JSP page has a unique + * <code>jspId</code>, and a given tag in a JSP page always has the same + * <code>jspId</code>, + * even for multiple requests to the page. + * </p> + * <p> + * Tag handler instances that implement <code>JspIdConsumer</code> + * cannot be reused. + * </p> + * <p> + * Even though the <code>jspId</code> attribute is similar in concept to + * the <code>jsp:id</code> + * attribute of an XML view (see Section JSP.10.1.13 of the spec), they are + * not related. + * The <code>jsp:id</code> attribute is available only at translation time, + * and the <code>jspId</code> + * attribute is avalable only at request time. + * </p> + * <p> + * The JSP container must provide a value for <code>jspId</code> that + * conforms to the following rules: + * <ul> + * <li>It must start with a letter (as defined by the <code>Character.isLetter()</code> + * method) or underscore ('_'). + * <li>Subsequent characters may be letters (as defined by the <code>Character.isLetter()</code> + * method), digits (as defined by the <code>Character.isDigit()</code> method), dashes ('-'), + * or underscores ('_') + * </ul> + * </p> + * <p> + * Note that the rules exclude colons ':' in a <code>jspId</code>, + * and that they are + * the same rules used for a component ID in JavaServer Faces. + * </p> + * + * @since JSP 2.1 + */ + public interface JspIdConsumer { - public void setJspId(String jspId); + + /** + * Called by the container generated code to set a value for the + * jspId attribute. An unique identification string, relative to + * this page, is generated at translation time. + */ + public void setJspId(String id); } Modified: trunk/java/javax/servlet/jsp/tagext/JspTag.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/JspTag.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/JspTag.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,26 +1,63 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; /** * Serves as a base class for Tag and SimpleTag. * This is mostly for organizational and type-safety purposes. * - * @since 2.0 + * @since JSP 2.0 */ public interface JspTag { } Modified: trunk/java/javax/servlet/jsp/tagext/PageData.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/PageData.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/PageData.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; Modified: trunk/java/javax/servlet/jsp/tagext/SimpleTag.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/SimpleTag.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/SimpleTag.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; import javax.servlet.jsp.JspContext; @@ -68,7 +105,7 @@ * </ol> * * @see SimpleTagSupport - * @since 2.0 + * @since JSP 2.0 */ public interface SimpleTag extends JspTag { Modified: trunk/java/javax/servlet/jsp/tagext/SimpleTagSupport.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/SimpleTagSupport.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/SimpleTagSupport.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; import javax.servlet.jsp.JspContext; @@ -29,7 +66,7 @@ * convenience methods including getter methods for the properties in * SimpleTag. * - * @since 2.0 + * @since JSP 2.0 */ public class SimpleTagSupport implements SimpleTag Modified: trunk/java/javax/servlet/jsp/tagext/Tag.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/Tag.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/Tag.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; Modified: trunk/java/javax/servlet/jsp/tagext/TagAdapter.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/TagAdapter.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/TagAdapter.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; @@ -32,7 +69,7 @@ * adapter is passed to setParent() instead. A classic Tag Handler can * call getAdaptee() to retrieve the encapsulated SimpleTag instance. * - * @since 2.0 + * @since JSP 2.0 */ public class TagAdapter implements Tag Modified: trunk/java/javax/servlet/jsp/tagext/TagAttributeInfo.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/TagAttributeInfo.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/TagAttributeInfo.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,11 +1,48 @@ /* - * Licensed to the Apache Software Foundation (ASF) under one or more - * contributor license agreements. See the NOTICE file distributed with - * this work for additional information regarding copyright ownership. - * The ASF licenses this file to You 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 + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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 @@ -15,221 +52,311 @@ * limitations under the License. */ + package javax.servlet.jsp.tagext; /** - * Information on the attributes of a Tag, available at translation time. This - * class is instantiated from the Tag Library Descriptor file (TLD). - * + * Information on the attributes of a Tag, available at translation time. + * This class is instantiated from the Tag Library Descriptor file (TLD). * <p> - * Only the information needed to generate code is included here. Other - * information like SCHEMA for validation belongs elsewhere. + * Only the information needed to generate code is included here. Other information + * like SCHEMA for validation belongs elsewhere. + * <p> + * Note from the Expert Group:<br> + * This should have been designed as an interface. Every time we change the TLD, + * we need to add a new constructor to this class (not good). + * This class should only be instantiated by container implementations + * (not by JSP developers). */ public class TagAttributeInfo { /** - * "id" is wired in to be ID. There is no real benefit in having it be - * something else IDREFs are not handled any differently. + * "id" is wired in to be ID. There is no real benefit in having it be something else + * IDREFs are not handled any differently. */ - + public static final String ID = "id"; - + /** - * Constructor for TagAttributeInfo. This class is to be instantiated only - * from the TagLibrary code under request from some JSP code that is parsing - * a TLD (Tag Library Descriptor). - * - * @param name - * The name of the attribute. - * @param required - * If this attribute is required in tag instances. - * @param type - * The name of the type of the attribute. - * @param reqTime - * Whether this attribute holds a request-time Attribute. + * Constructor for TagAttributeInfo. + * This class is to be instantiated only from the + * TagLibrary code under request from some JSP code that is parsing a + * TLD (Tag Library Descriptor). + * + * @param name The name of the attribute. + * @param required If this attribute is required in tag instances. + * @param type The name of the type of the attribute. + * @param reqTime Whether this attribute holds a request-time Attribute. */ - - public TagAttributeInfo(String name, boolean required, String type, - boolean reqTime) { + + public TagAttributeInfo(String name, boolean required, + String type, boolean reqTime) { this.name = name; this.required = required; this.type = type; this.reqTime = reqTime; } - + /** - * JSP 2.0 Constructor for TagAttributeInfo. This class is to be - * instantiated only from the TagLibrary code under request from some JSP - * code that is parsing a TLD (Tag Library Descriptor). - * - * @param name - * The name of the attribute. - * @param required - * If this attribute is required in tag instances. - * @param type - * The name of the type of the attribute. - * @param reqTime - * Whether this attribute holds a request-time Attribute. - * @param fragment - * Whether this attribute is of type JspFragment - * - * @since 2.0 + * JSP 2.0 Constructor for TagAttributeInfo. + * This class is to be instantiated only from the + * TagLibrary code under request from some JSP code that is parsing a + * TLD (Tag Library Descriptor). + * + * @param name The name of the attribute. + * @param required If this attribute is required in tag instances. + * @param type The name of the type of the attribute. + * @param reqTime Whether this attribute holds a request-time Attribute. + * @param fragment Whether this attribute is of type JspFragment + * + * @since JSP 2.0 */ - - public TagAttributeInfo(String name, boolean required, String type, - boolean reqTime, boolean fragment) { - this(name, required, type, reqTime); + public TagAttributeInfo(String name, boolean required, + String type, boolean reqTime, + boolean fragment) { + this( name, required, type, reqTime ); this.fragment = fragment; } - + /** + * JSP 2.1 Constructor for TagAttributeInfo. + * This class is to be instantiated only from the + * TagLibrary code under request from some JSP code that is parsing a + * TLD (Tag Library Descriptor). + * + * @param name The name of the attribute. + * @param required If this attribute is required in tag instances. + * @param type The name of the type of the attribute. + * @param reqTime Whether this attribute holds a request-time Attribute. + * @param fragment Whether this attribute is of type JspFragment + * @param description The description of the attribute. + * @param deferredValue Whether this attribute is a deferred value. + * @param deferredMethod Whether this attribute is a deferred method. + * rtexpr or deferred value. + * @param expectedTypeName The name of the expected type of this deferred + * value (or <code>null</code> if this is not a deferred value). + * @param methodSignature The expected method signature of this deferred + * method (or <code>null</code> if this is not a deferred method). + * * @since JSP 2.1 */ - public TagAttributeInfo(String name, boolean required, String type, - boolean reqTime, boolean fragment, String description, - boolean deferredValue, boolean deferredMethod, - String expectedTypeName, String methodSignature) { - this(name, required, type, reqTime, fragment); + public TagAttributeInfo(String name, + boolean required, + String type, + boolean reqTime, + boolean fragment, + String description, + boolean deferredValue, + boolean deferredMethod, + String expectedTypeName, + String methodSignature) + { + this( name, required, type, reqTime, fragment ); this.description = description; this.deferredValue = deferredValue; this.deferredMethod = deferredMethod; this.expectedTypeName = expectedTypeName; this.methodSignature = methodSignature; } - + /** * The name of this attribute. - * + * * @return the name of the attribute */ - + public String getName() { return name; } - + /** * The type (as a String) of this attribute. - * + * + * <p>This method must return <code>"javax.el.ValueExpression"</code> + * if <code>isDeferredValue()</code> returns <code>true</code> and + * <code>canBeRequestTime()</code> returns <code>false</code>. It + * must return <code>"javax.el.MethodExpression"</code> if + * <code>isDeferredMethod()</code> returns <code>true</code>. + * It must return <code>"java.lang.Object"</code> if + * <code>isDeferredValue()</code> returns <code>true</code> and + * <code>canBeRequestTime()</code> returns <code>true</code>. + * </p> + * * @return the type of the attribute */ - + public String getTypeName() { return type; } - + /** - * Whether this attribute can hold a request-time value. - * - * @return if the attribute can hold a request-time value. + * Whether this attribute has been specified in the TLD + * as rtexprvalue. If <code>true</code>, this means the attribute + * can hold a request-time value. + * + * @return true if the attribute has been specified in the TLD + * as rtexprvalue */ - + public boolean canBeRequestTime() { return reqTime; } - + /** * Whether this attribute is required. - * + * * @return if the attribute is required. */ public boolean isRequired() { return required; } - + /** * Convenience static method that goes through an array of TagAttributeInfo * objects and looks for "id". - * - * @param a - * An array of TagAttributeInfo + * + * @param a An array of TagAttributeInfo * @return The TagAttributeInfo reference with name "id" */ public static TagAttributeInfo getIdAttribute(TagAttributeInfo a[]) { - for (int i = 0; i < a.length; i++) { + for (int i=0; i<a.length; i++) { if (a[i].getName().equals(ID)) { return a[i]; } } - return null; // no such attribute + return null; // no such attribute } - + /** * Whether this attribute is of type JspFragment. - * + * * @return if the attribute is of type JspFragment - * - * @since 2.0 + * + * @since JSP 2.0 */ public boolean isFragment() { return fragment; } /** - * Returns a String representation of this TagAttributeInfo, suitable for - * debugging purposes. - * + * Gets the description string of this tag attribute. + * + * @return the description string of this tag attribute + */ + + public String getDescription() { + return description; + } + + /** + * Returns <code>true</code> if this attribute is to be passed a + * <code>ValueExpression</code> so that expression evaluation + * can be deferred. + * + * <p>If this method returns <code>true</code>, then + * <code>getTypeName()</code> must return + * <code>"javax.el.ValueExpression"</code>.</p> + * + * <p>The <code>getExpectedType()</code> method can be used to retrieve + * the expected type this value expression will be constructed with.</p> + * + * @return <code>true</code> if this attribute accepts a deferred value; + * <code>false</code> otherwise. + * + * @since JSP 2.1 + */ + public boolean isDeferredValue() { + return deferredValue; + } + + /** + * Returns <code>true</code> if this attribute is to be passed a + * <code>MethodExpression</code> so that expression evaluation + * can be deferred. + * + * <p>If this method returns <code>true</code>, then + * <code>getTypeName()</code> must return + * <code>"javax.el.MethodExpression"</code>.</p> + * + * <p>The <code>getMethodSignature()</code> method can be used to retrieve + * the expected method signature this method expression will be + * constructed with.</p> + * + * @return <code>true</code> if this attribute accepts a deferred method; + * <code>false</code> otherwise. + * + * @since JSP 2.1 + */ + public boolean isDeferredMethod() { + return deferredMethod; + } + + /** + * Returns the name of the expected type (as a String) of this + * deferred value attribute. + * + * <p>This method returns <code>null</code> if + * <code>isDeferredValue()</code> returns <code>false</code>.</p> + * + * @return the name of the expected type + * @since JSP 2.1 + */ + public String getExpectedTypeName() { + return expectedTypeName; + } + + /** + * Returns the expected method signature of this deferred method attribute. + * + * <p>This method returns <code>null</code> if + * <code>isDeferredMethod()</code> returns <code>false</code>.</p> + * + * @return the method signature + * @since JSP 2.1 + */ + public String getMethodSignature() { + return methodSignature; + } + + /** + * Returns a String representation of this TagAttributeInfo, suitable + * for debugging purposes. + * * @return a String representation of this TagAttributeInfo */ public String toString() { - StringBuffer b = new StringBuffer(64); - b.append("name = " + name + " "); - b.append("type = " + type + " "); - b.append("reqTime = " + reqTime + " "); - b.append("required = " + required + " "); - b.append("fragment = " + fragment + " "); - b.append("deferredValue = " + deferredValue + " "); - b.append("expectedTypeName = " + expectedTypeName + " "); - b.append("deferredMethod = " + deferredMethod + " "); - b.append("methodSignature = " + methodSignature); + StringBuffer b = new StringBuffer(); + b.append("name = "+name+" "); + b.append("type = "+type+" "); + b.append("reqTime = "+reqTime+" "); + b.append("required = "+required+" "); + b.append("fragment = "+fragment+" "); + b.append("deferredValue = "+deferredValue+" "); + b.append("deferredMethod = "+deferredMethod+" "); + b.append("expectedTypeName = "+expectedTypeName+" "); + b.append("methodSignature = "+methodSignature+" "); return b.toString(); } - + /* * private fields */ private String name; - private String type; - private boolean reqTime; - private boolean required; - + /* * private fields for JSP 2.0 */ private boolean fragment; - + /* * private fields for JSP 2.1 */ - private String description; - private boolean deferredValue; - private boolean deferredMethod; - private String expectedTypeName; - private String methodSignature; - - public boolean isDeferredMethod() { - return deferredMethod; - } - - public boolean isDeferredValue() { - return deferredValue; - } - - public String getDescription() { - return description; - } - - public String getExpectedTypeName() { - return expectedTypeName; - } - - public String getMethodSignature() { - return methodSignature; - } + private String description; } Modified: trunk/java/javax/servlet/jsp/tagext/TagData.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/TagData.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/TagData.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; @@ -63,7 +100,7 @@ if (atts != null) { for (int i = 0; i < atts.length; i++) { - attributes.put((String) atts[i][0], atts[i][1]); + attributes.put((String)atts[i][0], atts[i][1]); } } } @@ -95,7 +132,7 @@ * The value of the attribute. * If a static value is specified for an attribute that accepts a * request-time attribute expression then that static value is returned, - * even if the value is provided in the body of a <jsp:attribute> action. + * even if the value is provided in the body of a &lt;jsp:attribute&gt; action. * The distinguished object REQUEST_TIME_VALUE is only returned if * the value is specified as a request-time attribute expression * or via the &lt;jsp:attribute&gt; action with a body that contains @@ -150,5 +187,5 @@ // private data - private Hashtable<String, Object> attributes; // the tagname/value map + private Hashtable<String, Object> attributes; // the tagname/value map } Modified: trunk/java/javax/servlet/jsp/tagext/TagExtraInfo.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/TagExtraInfo.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/TagExtraInfo.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; @@ -104,7 +141,7 @@ * @param data The TagData instance. * @return A null object, or zero length array if no errors, an * array of ValidationMessages otherwise. - * @since 2.0 + * @since JSP 2.0 */ public ValidationMessage[] validate( TagData data ) { ValidationMessage[] result = null; Modified: trunk/java/javax/servlet/jsp/tagext/TagFileInfo.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/TagFileInfo.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/TagFileInfo.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; @@ -23,7 +60,7 @@ * This class is instantiated from the Tag Library Descriptor file (TLD) * and is available only at translation time. * - * @since 2.0 + * @since JSP 2.0 */ public class TagFileInfo { @@ -33,7 +70,7 @@ * under request from some JSP code that is parsing a * TLD (Tag Library Descriptor). * - * Note that, since TagLibraryInfo reflects both TLD information + * Note that, since TagLibibraryInfo reflects both TLD information * and taglib directive information, a TagFileInfo instance is * dependent on a taglib directive. This is probably a * design error, which may be fixed in the future. Modified: trunk/java/javax/servlet/jsp/tagext/TagInfo.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/TagInfo.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/TagInfo.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; @@ -50,7 +87,7 @@ /** * Static constant for getBodyContent() when it is scriptless. * - * @since 2.0 + * @since JSP 2.0 */ public static final String BODY_CONTENT_SCRIPTLESS = "scriptless"; @@ -170,7 +207,7 @@ * @param tvi An array of a TagVariableInfo (or null) * @param dynamicAttributes True if supports dynamic attributes * - * @since 2.0 + * @since JSP 2.0 */ public TagInfo(String tagName, String tagClassName, @@ -264,7 +301,7 @@ * @param data The translation-time TagData instance. * @return A null object, or zero length array if no errors, an * array of ValidationMessages otherwise. - * @since 2.0 + * @since JSP 2.0 */ public ValidationMessage[] validate( TagData data ) { TagExtraInfo tei = getTagExtraInfo(); @@ -415,7 +452,7 @@ * Get dynamicAttributes associated with this TagInfo. * * @return True if tag handler supports dynamic attributes - * @since 2.0 + * @since JSP 2.0 */ public boolean hasDynamicAttributes() { return dynamicAttributes; Modified: trunk/java/javax/servlet/jsp/tagext/TagLibraryInfo.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/TagLibraryInfo.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/TagLibraryInfo.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; @@ -26,8 +63,6 @@ * * Most of the information is directly from the TLD, except for * the prefix and the uri values used in the taglib directive - * - * */ abstract public class TagLibraryInfo { @@ -35,9 +70,6 @@ /** * Constructor. * - * This will invoke the constructors for TagInfo, and TagAttributeInfo - * after parsing the TLD file. - * * @param prefix the prefix actually used by the taglib directive * @param uri the URI actually used by the taglib directive */ @@ -134,7 +166,7 @@ * @return the TagFileInfo objects corresponding to the tag files defined * by this tag library, or a zero length array if this * tag library defines no tags files - * @since 2.0 + * @since JSP 2.0 */ public TagFileInfo[] getTagFiles() { return tagFiles; @@ -172,7 +204,7 @@ * @param shortname The short name (no prefix) of the tag * @return the TagFileInfo for the specified Tag file, or null * if no Tag file is found - * @since 2.0 + * @since JSP 2.0 */ public TagFileInfo getTagFile(String shortname) { TagFileInfo tagFiles[] = getTagFiles(); @@ -194,7 +226,7 @@ * * @return the functions defined in this tag library, or a zero * length array if the tag library defines no functions. - * @since 2.0 + * @since JSP 2.0 */ public FunctionInfo[] getFunctions() { return functions; @@ -208,7 +240,7 @@ * @param name The name (no prefix) of the function * @return the FunctionInfo for the function with the given name, or null * if no such function exists - * @since 2.0 + * @since JSP 2.0 */ public FunctionInfo getFunction(String name) { @@ -227,21 +259,24 @@ /** - * Returns an array of TagLibraryInfo objects representing the entire set - * of tag libraries (including this TagLibraryInfo) imported by taglib - * directives in the translation unit that references this TagLibraryInfo. - * If a tag library is imported more than once and bound to different prefices, - * only the TagLibraryInfo bound to the first prefix must be included - * in the returned array. - * - * @return Array of TagLibraryInfo objects representing the entire set - * of tag libraries (including this TagLibraryInfo) imported by taglib + * Returns an array of TagLibraryInfo objects representing the entire set + * of tag libraries (including this TagLibraryInfo) imported by taglib + * directives in the translation unit that references this + * TagLibraryInfo. + * + * If a tag library is imported more than once and bound to different + * prefices, only the TagLibraryInfo bound to the first prefix must be + * included in the returned array. + * + * @return Array of TagLibraryInfo objects representing the entire set + * of tag libraries (including this TagLibraryInfo) imported by taglib * directives in the translation unit that references this TagLibraryInfo. - * @since 2.1 + * + * @since JSP 2.1 */ - public abstract javax.servlet.jsp.tagext.TagLibraryInfo[] getTagLibraryInfos(); - - + public abstract TagLibraryInfo[] getTagLibraryInfos(); + + // Protected fields /** @@ -263,14 +298,14 @@ /** * An array describing the tag files that are defined in this tag library. * - * @since 2.0 + * @since JSP 2.0 */ protected TagFileInfo[] tagFiles; /** * An array describing the functions that are defined in this tag library. * - * @since 2.0 + * @since JSP 2.0 */ protected FunctionInfo[] functions; Modified: trunk/java/javax/servlet/jsp/tagext/TagLibraryValidator.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/TagLibraryValidator.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/TagLibraryValidator.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; @@ -135,7 +172,6 @@ * Release any data kept by this instance for validation purposes. */ public void release() { - initParameters = null; } // Private data Modified: trunk/java/javax/servlet/jsp/tagext/TagSupport.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/TagSupport.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/TagSupport.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; import java.io.Serializable; @@ -278,7 +315,7 @@ // private fields private Tag parent; - private Hashtable<String, Object> values; + private Hashtable<String, Object> values; /** * The value of the id attribute of this tag; or null. */ Modified: trunk/java/javax/servlet/jsp/tagext/TagVariableInfo.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/TagVariableInfo.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/TagVariableInfo.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; Modified: trunk/java/javax/servlet/jsp/tagext/TryCatchFinally.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/TryCatchFinally.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/TryCatchFinally.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; Modified: trunk/java/javax/servlet/jsp/tagext/ValidationMessage.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/ValidationMessage.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/ValidationMessage.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; Modified: trunk/java/javax/servlet/jsp/tagext/VariableInfo.java =================================================================== --- trunk/java/javax/servlet/jsp/tagext/VariableInfo.java 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/VariableInfo.java 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,19 +1,56 @@ /* -* Licensed to the Apache Software Foundation (ASF) under one or more -* contributor license agreements. See the NOTICE file distributed with -* this work for additional information regarding copyright ownership. -* The ASF licenses this file to You 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. -*/ + * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. + * + * Copyright 1997-2008 Sun Microsystems, Inc. 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.html + * or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + * Sun designates this particular file as subject to the "Classpath" exception + * as provided by Sun in the GPL Version 2 section of the License file that + * accompanied this code. If applicable, add the following below the License + * Header, with the fields enclosed by brackets [] replaced by your own + * identifying information: "Portions Copyrighted [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. + */ package javax.servlet.jsp.tagext; @@ -61,7 +98,7 @@ * is known to the tag library and thus, delivered in the same JAR * file as the tag handlers. In most other remaining cases it will * refer to a class that is in the platform on which the JSP processor - * is built (like J2EE). Using fully qualified class names in this + * is built (like Java EE). Using fully qualified class names in this * manner makes the usage relatively resistant to configuration * errors. * @@ -106,7 +143,6 @@ * <blockquote> * <table cellpadding="2" cellspacing="2" border="0" width="55%" * bgcolor="#999999" summary="Variable Synchronization Points"> - * <tbody> * <tr align="center"> * <td valign="top" colspan="6" bgcolor="#999999"><u><b>Variable Synchronization * Points</b></u><br> @@ -176,7 +212,6 @@ * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> * </td> * </tr> - * </tbody> * </table> * ¹ Called after <code>doStartTag()</code> if * <code>EVAL_BODY_INCLUDE</code> is returned, or after Modified: trunk/java/javax/servlet/jsp/tagext/package.html =================================================================== --- trunk/java/javax/servlet/jsp/tagext/package.html 2009-11-05 15:21:54 UTC (rev 1243) +++ trunk/java/javax/servlet/jsp/tagext/package.html 2009-11-05 16:28:02 UTC (rev 1244) @@ -1,29 +1,99 @@ -<!DOCTYPE HTML PUBLIC "-//IETF//DTD HTML//EN"> -<html> -<head> <!-- - Licensed to the Apache Software Foundation (ASF) under one or more - contributor license agreements. See the NOTICE file distributed with - this work for additional information regarding copyright ownership. - The ASF licenses this file to You 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 + DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. - http://www.apache.org/licenses/LICENSE-2.0 + Copyright 1997-2008 Sun Microsystems, Inc. All rights reserved. - 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. + 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.html + or glassfish/bootstrap/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 glassfish/bootstrap/legal/LICENSE.txt. + Sun designates this particular file as subject to the "Classpath" exception + as provided by Sun in the GPL Version 2 section of the License file that + accompanied this code. If applicable, add the following below the License + Header, with the fields enclosed by brackets [] replaced by your own + identifying information: "Portions Copyrighted [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 "-//IETF//DTD HTML//EN"> +<html> +<head> </head> <body bgcolor="white"> Classes and interfaces for the definition of JavaServer Pages Tag Libraries. +<p> Custom actions can be used by JSP authors and authoring tools to +simplify writing JSP pages. A custom action can be either an empty +or a non-empty action. + <p> -The JavaServer Pages(tm) (JSP) 2.0 specification provides a portable +An empty tag has no body. There are two equivalent syntaxes, one +with separate start and end tags, and one where the start and +end tags are combined. The two following examples are identical: +</p> +<blockquote> +<code> +<pre> +&lt;x:foo att="myObject"&gt;&lt/foo&gt; +&lt;x:foo att="myObject"/&gt; +</pre> +</code> +</blockquote> + +<p> +A non-empty tag has a start tag, a body, and an end tag. A +prototypical example is of the form: +</p> +<blockquote> +<code> +<pre> +&lt;x:foo att="myObject" &gt; + BODY +&lt;/x:foo/&gt; +</pre> +</code> +</blockquote> + + +<p> +The JavaServer Pages(tm) (JSP) specification provides a portable mechanism for the description of tag libraries. <p> A JSP tag library contains @@ -35,13 +105,1349 @@ <li>Possibly some additional classes to provide extra translation information</li> </ul> + +<p> This API is described in the following sections: +<ol> + <li><a href="#classic">Classic Tag Handlers</a></li> + <li><a href="#bodycontent">Tag Handlers that want to access their Body Content</a></li> + <li><a href="#dynamic">Dynamic Attributes</a></li> + <li><a href="#thmgmt">Annotated Tag Handler Management Example</a></li> + <li><a href="#coop">Cooperating Actions</a></li> + <li><a href="#simple">Simple Tag Handlers</a></li> + <li><a href="#fragment">JSP Fragments</a></li> + <li><a href="#sths">Example Simple Tag Handler Scenario</a></li> + <li><a href="#translation">Translation-time Classes</a></li> +</ol> + +<a name="classic"> +<h2>1. Classic Tag Handlers</h2> +</a> +This section introduces the notion of a tag handler and describes the +classic types of tag handler. + +<p> JSP 2.0 introduces a new type of Tag Handler called a Simple +Tag Handler, which is described in a later section. +The protocol for Simple Tag handlers is much more straightforward. + +<h3>Tag Handler</h3> + +<p> A tag handler is a run-time, container-managed object that +evaluates custom actions during the execution of a JSP page. A tag +handler supports a protocol that allows the JSP container to provide +good integration of the server-side actions within a JSP page. + +<p> A tag handler is created initially using a zero argument +constructor on its corresponding class; the method +<code>java.beans.Beans.instantiate()</code> is not used. + +<p> A tag handler has some properties that are exposed to the page as +attributes on an action; these properties are managed by the JSP +container (via generated code). The setter methods used to set +the properties are discovered using the JavaBeans introspector +machinery. + +<p> The protocol supported by a tag handler provides for passing of +parameters, the evaluation and reevaluation of the body of the action, +and for getting access to objects and other tag handlers in the +JSP page. + +<p> A tag handler instance is responsible for processing one request +at a time. It is the responsability of the JSP container to enforce +this. + +<p> Additional translation time information associated with the action +indicates the name of any scripting variables it may introduce, their +types and their scope. At specific moments, the JSP container will +automatically synchronize the {@link javax.servlet.jsp.PageContext} + information with variables +in the scripting language so they can be made available directly +through the scripting elements. + + +<h3>Properties</h3> + + +<p> A tag handler has some properties. All tag handlers have a +<em>pageContext</em> property for the JSP page where the tag is +located, and a <em>parent</em> property for the tag handler to the +closest enclosing action. Specific tag handler classes may have +additional properties. + +<p> All attributes of a custom action must be JavaBeans component +properties, although some properties may not be exposed as attributes. +The attributes that are visible to the JSP translator are exactly +those listed in the Tag Library Descriptor (TLD). + +<p> All properties of a tag handler instance exposed as attributes +will be initialized by the container using the appropriate setter +methods before the instance can be used to perform the action methods. +It is the responsibility of the JSP container to invoke the +appropriate setter methods to initialize these properties. It is the +responsability of user code, be it scriptlets, JavaBeans code, or code +inside custom tags, to not invoke these setter methods, as doing +otherwise would interfere with the container knowledge. + +<p> The setter methods that should be used when assigning a value to +an attribute of a custom action are determined by using the JavaBeans +introspector on the tag handler class, then use the setter method +associated with the property that has the same name as the attribute +in question. An implication (unclear in the JavaBeans specification) +is that there is only one setter per property. + +<p> Unspecified attributes/properties should not be set (using a +setter method). + +<p> Once properly set, all properties are expected to be persistent, +so that if the JSP container ascertains that a property has already +been set on a given tag handler instance, it must not set it +again. + +<p> The JSP container may reuse classic tag handler instances for multiple +occurrences of the corresponding custom action, in the same page or in +different pages, but only if the same set of attributes are used for all +occurrences. If a tag handler is used for more than one occurence, the +container must reset all attributes where the values differ between the +custom action occurrences. Attributes with the same value in all +occurrences must not be reset. If an attribute value is set as a +request-time attribute value (using a scripting or an EL expression), +the container must reset the attribute between all reuses of the tag +handler instance. To prevent confusion, a tag handler with an empty body +must not reuse any previous tag handler with a non-empty body. + +<p> User code can access property information and access and modify +tag handler internal state starting with the first action method (doStartTag) +up until the last action method (doEndTag or doFinally for tag handlers +implementing TryCatchFinally). + + +<h3>Tag Handler as a Container-Managed Object</h3> + +<p> Since a tag handler is a container managed object, the container +needs to maintain its references; specifically, user code should not +keep references to a tag handler except between the start of the first +action method (doStartTag()) and the end of the last action method +(doEndTag() or doFinally() for those tags that implement TryCatchFinally). + +<p> The restrictions on references to tag handler objects and +on modifying attribute properties gives the JSP container substantial +freedom in effectively managing tag handler objects to achieve different +goals. For example, a container may implementing different pooling strategies +to minimize creation cost, or may hoist setting of properties to reduce +cost when a tag handler is inside another iterative tag. + + +<h3>Conversions</h3> + +<p>A tag handler implements an action; the JSP container must follow +the type conversions described in Section 2.13.2 when assigning values +to the attributes of an action. + +<h3>Empty and Non-Empty Actions</h3> + +An empty action has no body; it may use one of two syntaxes: either +&lt;foo/&gt; or &lt;foo&gt;&lt;/foo&gt;. Since empty actions have no +body the methods related to body manipulation are not invoked. +There is a mechanism in the Tag Library Descriptor to indicate +that a tag can only be used to write empty actions; when used, +non-empty actions using that tag will produce a translation error. + <p> -The JSP 2.0 specification and the reference implementation both contain -simple and moderately complex examples of actions defined using this -mechanism. These are available at JSP's web site, at -<a href="http://java.sun.com/products/jsp">http://java.sun.com/...;. -Some readers may want to consult those to get a quick feel for how -the mechanisms work together. +A non-empty action has a body. +<a name="tag interface"> +<h3>The Tag Interface</h3> +</a> + +<p> A Tag handler that does not want to process its body can implement +just the Tag interface. A tag handler may not want to process its +body because it is an empty tag or because the body is just to +be "passed through". + +<p> The Tag interface includes methods to provide page context +information to the Tag Handler instance, methods to handle the +life-cycle of tag handlers, and two main methods for performing +actions on a tag: <code>doStartTag()</code> and +<code>doEndTag()</code>. The method <code>doStartTag()</code> is +invoked when encountering the start tag and its return value indicates +whether the body (if there is any) should be skipped, or evaluated and +passed through to the current response stream. The method +<code>doEndTag()</code> is invoked when encountering the end tag; its +return value indicates whether the rest of the page should continue to +be evaluated or not. + +<p> If an exception is encountered during the evaluation of the +body of a tag, its doEndTag method will not be evaluated. See the +TryCatchFinally tag for methods that are guaranteed to be evaluated. + +<a name="iterationtag interface"> +<h3>The IterationTag Interface</h3> +</a> + +<p> The IterationTag interface is used to repeatedly reevaluate +the body of a custom action. The interface has one method: +<code>doAfterBody()</code> which is invoked after each evaluation +of the body to determine whether to reevaluate or not. + +<p> Reevaluation is requested with the value 2, which in JSP 1.1 is +defined to be BodyTag.EVAL_BODY_TAG. That constant value is still +kept in JSP 1.2 (for full backwards compatibility) but, to improve +clarity, a new name is also available: IterationTag.EVAL_BODY_AGAIN. +To stop iterating, the returned value should be 0, which is +Tag.SKIP_BODY. + +<h3>The JspIdConsumer Interface</h3> +This interface indicates to the container that a tag handler wishes +to be provided with a compiler generated ID that is unique +within the page. + +<h3>The TagSupport Base Class</h3> + +<p> The TagSupport class is a base class that can be used when +implementing the Tag or IterationTag interfaces. + + +<a name="bodycontent"> +<h2>2. Tag Handlers that want Access to their Body Content</h2> +</a> + +<p>The evaluation of a body is delivered into a <code>BodyContent</code> +object. This is then made available to tag handlers that implement +the <code>BodyTag</code> interface. The <code>BodyTagSupport</code> +class provides a useful base class to simplify writing these handlers. + + +<p> If a Tag handler wants to have access to the content of its body +then it must implement the <code>BodyTag</code> interface. + +This interface extends IterationTag, provides two additional methods +<code>setBodyContent(BodyContent)</code> and +<code>doInitBody()</code> +and refers to an object of type BodyContent. + +<p> A BodyContent is a subclass of <code>JspWriter</code> that has a +few additional methods to convert its contents into a String, insert +the contents into another JspWriter, to get a Reader into its +contents, and to clear the contents. Its semantics also assure that +buffer size will never be exceeded. + +<p> The JSP page implementation will create a BodyContent if the +doStartTag() method returns a EVAL_BODY_BUFFERED. This object will be +passed to doInitBody(); then the body of the tag will be evaluated, +and <em>during that evaluation <b>out</b> will be bound to the +BodyContent just passed to the BodyTag handler</em>. Then +doAfterBody() will be evaluated. If that method returns SKIP_BODY, no +more evaluations of the body will be done; if the method returns +EVAL_BODY_AGAIN, then the body will be evaluated, and doAfterBody() will +be invoked again. + +<p> The content of a BodyContent instance remains available until after +the invocation of its associated doEndTag() method. + +<p> A common use of the BodyContent is to extract its contents into a +String and then use the String as a value for some operation. Another +common use is to take its contents and push it into the out Stream +that was valid when the start tag was encountered (that is available +from the PageContext object passed to the handler in setPageContext). + + +<a name="dynamic"> +<h2>3. Dynamic Attributes</h2> +</a> + +<p>Any tag handler can optionally extend the <code>DynamicAttributes</code> +interface to indicate that it supports dynamic attributes. In addition +to implementing the <code>DynamicAttributes</code> interface, tag +handlers that support dynamic attributes must declare that they do so in +the Tag Library Descriptor.</p> + +<p>The TLD is what ultimately determines whether a tag handler accepts +dynamic attributes or not. If a tag handler declares that it supports +dynamic attributes in the TLD but it does not implement the +<code>DynamicAttributes</code> interface, the tag handler must be +considered invalid by the container.</p> + +<p>If the dynamic-attributes element for a tag being invoked contains +the value "true", the following requirements apply:</p> + +<ul> + <li>For each attribute specified in the tag invocation that does not + have a corresponding attribute element in the TLD for this tag, + a call must be made to <code>setDynamicAttribute()</code>, + passing in the namespace of the attribute (or null if the attribute + does not have a namespace or prefix), the name of the attribute without + the namespace prefix, and the final value of the attribute.</li> + + <li>Dynamic attributes must be considered to accept request-time + expression values as well as deferred expressions.</li> + + <li>Dynamic attributes must be treated as though they were of type + <code>java.lang.Object</code>. If a <code>ValueExpression</code> + is passed as a dynamic attribute, the default value for the expected + return type is assumed to be <code>java.lang.Object</code>. If a + <code>MethodExpression</code> is passed as a dynamic + attribute, the default method signature is assumed to be <code>void + method()</code>.</li> + + <li>Note that passing a String literal as a dynamic attribute will never + be considered as a deferred expression.</li> + + <li>The JSP container must recognize dynamic attributes that are + passed to the tag handler using the &lt;jsp:attribute&gt; standard + action.</li> + + <li>If the <code>setDynamicAttribute()</code> method throws + <code>JspException</code>, the <code>doStartTag()</code> or + <code>doTag()</code> method is not invoked for this tag, and the + exception must be treated in the same manner as if it came from + a regular attribute setter method.</li> + + <li>For a JSP document in either standard or XML syntax, If a + dynamic attribute has a prefix that doesn't map to a + namespace, a translation error must occur. In standard + syntax, only namespaces defined using taglib directives are + recognized.</li> + +</ul> + +<p>In the following example, assume attributes a and b are declared +using the attribute element in the TLD, attributes d1 and d2 are not +declared, and the dynamic-attributes element is set to "true". +The attributes are set using the calls: +<ul> + <li><code>setA( "1" )</code>, </li> + <li><code>setDynamicAttribute( null, "d1", "2" )</code>, </li> + <li><code>setDynamicAttribute( "http://www.foo.com/jsp/taglib/mytag.tld", "d2", "3" )</code>, </li> + <li><code>setB( "4" )</code>, </li> + <li><code>setDynamicAttribute( null, "d3", "5" )</code>, and</li> + <li><code>setDynamicAttribute( "http://www.foo.com/jsp/taglib/mytag.tld", "d4", "6" )</code>.</li> +</ul> + +<pre> +&lt;jsp:root xmlns:mytag="http://www.foo.com/jsp/taglib/mytag.tld" version="2.0"&gt; + &lt;mytag:invokeDynamic a="1" d1="2" mytag:d2="3"&gt; + &lt;jsp:attribute name="b"&gt;4&lt;/jsp:attribute&gt; + &lt;jsp:attribute name="d3"&gt;5&lt;/jsp:attribute&gt; + &lt;jsp:attribute name="mytag:d4"&gt;6&lt;/jsp:attribute&gt; + &lt;/mytag:invokeDynamic&gt; +&lt;/jsp:root&gt; +</pre> + +<a name="thmgmt"> +<h2>4. Annotated Tag Handler Management Example</h2> +</a> + +Below is a somewhat complete example of the way one JSP container +could choose to do some tag handler management. There are many +other strategies that could be followed, with different pay offs. + +<p>In this example, we are assuming that +x:iterate is an iterative tag, while x:doit and x:foobar are simple +tag. We will also assume that x:iterate and x:foobar implement the +TryCatchFinally interface, while x:doit does not. + +<pre> +&lt;x:iterate src="foo"&gt; + &lt;x:doit att1="one" att2="&lt;%= 1 + 1 %&gt;" /&gt; + &lt;x:foobar /&gt; + &lt;x:doit att1="one" att2="&lt;%= 2 + 2 %&gt;" /&gt; +&lt;/x:iterate&gt; +&lt;x:doit att1="one" att2="&lt;%= 3 + 3 %&gt;" /&gt; +</pre> + +<p> The particular code shown below assumes there is some pool of tag +handlers that are managed (details not described, although pool +managing is simpler when there are no optional attributes), and +attemps to reuse tag handlers if possible. The code also "hoists" +setting of properties to reduce the cost when appropriate, e.g. inside +an iteration. + +<pre> + +boolean b1, b2; +IterationTag i; // for x:iterate +Tag d; // for x:doit +Tag d; // for x:foobar + +page: // label to end of page... + + +// initialize iteration tag +i = get tag from pool or new(); + +i.setPageContext(pc); +i.setParent(null); +i.setSrc("foo"); + +// x:iterate implements TryCatchFinally +try { + if ((b1 = i.doStartTag()) == EVAL_BODY_INCLUDE) { + + // initialize doit tag + // code has been moved out of the loop for show + d = get tag from pool or new(); + + d.setPageContext(pc); + d.setParent(i); + d.setAtt1("one"); + + loop: + while (1) do { + // I'm ignoring newlines... + + // two invocations, fused together + + // first invocation of x:doit + d.setAtt2(1+1); + if ((b2 = d.doStartTag()) == EVAL_BODY_INCLUDE) { + // nothing + } else if (b2 != SKIP_BODY) { + // Q? protocol error ... + } + if ((b2 = d.doEndTag()) == SKIP_PAGE) { + break page; // be done with it. + } else if (b2 != EVAL_PAGE) { + // Q? protocol error + } + + // x:foobar invocation + f = get tag from pool or new(); + f.setPageContext(pc); + f.setParent(i); + + // x:foobar implements TryCatchFinally + try { + + if ((b2 = f.doStartTag()) == EVAL_BODY_INCLUDE) { + // nothing + } else if (b2 != SKIP_BODY) { + // Q? protocol error + } + if ((b2 = f.doEndTag()) == SKIP_PAGE) { + break page; // be done with it. + } else if (b2 != EVAL_PAGE) { + // Q? protocol error + } + } catch (Throwable t) { + f.doCatch(t); // caught, may been rethrown! + } finally { + f.doFinally(); + } + + // put f back to pool + + // second invocation of x:doit + d.setAtt2(2+2); + if ((b2 = d.doStartTag()) == EVAL_BODY_INCLUDE) { + // nothing + } else if (b2 != SKIP_BODY) { + // Q? protocol error + } + if ((b2 = d.doEndTag()) == SKIP_PAGE) { + break page; // be done with it. + } else if (b2 != EVAL_PAGE) { + // Q? protocol error + } + + if ((b2 = i.doAfterBody()) == EVAL_BODY_AGAIN) { + break loop; + } else if (b2 != SKIP_BODY) { + // Q? protocol error + } + // loop + } + + } else if (b1 != SKIP_BODY) { + // Q? protocol error + } + + // tail end of the IteratorTag ... + + if ((b1 = i.doEndTag()) == SKIP_PAGE) { + break page; // be done with it. + } else if (b1 != EVAL_PAGE) { + // Q? protocol error + } + + // third invocation + // this tag handler could be reused from the previous ones. + d = get tag from pool or new(); + + d.setPageContext(pc); + d.setParent(null); + d.setAtt1("one"); + d.setAtt2(3+3); + + if ((b1 = d.doStartTag()) == EVAL_BODY_INCLUDE) { + // nothing + } else if (b1 != SKIP_BODY) { + // Q? protocol error + } + if ((b1 = d.doEndTag()) == SKIP_PAGE) { + break page; // be done with it. + } else if (b1 != EVAL_PAGE) { + // Q? protocol error + } + +} catch (Throwable t) { + i.doCatch(t); // caught, may been rethrown! +} finally { + i.doFinally(); +} +</pre> + +<a name="coop"> +<h2>5. Cooperating Actions</h2> +</a> + +Actions can cooperate with other actions and with scripting code +in a number of ways. + +<h3>PageContext</h3> +<p> + +Often two actions in a JSP page will want to cooperate, +perhaps by one action creating some server-side object that +needs to be accessed by another. +One mechanism for doing this is by giving the object a name +within the JSP page; the first action will create the object +and associate the name to it while the second action +will use the name to retrieve the object. + +<p> +For example, in the following JSP segment the <code>foo</code> +action might create a server-side object and give it the +name "myObject". +Then the <code>bar</code> +action might access that server-side object and take some action. + +<blockquote> +<code> +<pre> +&lt;x:foo id="myObject" /&gt; +&lt;x:bar ref="myObjet" /&gt; +</pre> +</code> +</blockquote> + +<p> + +In a JSP implementation, the mapping "name"->value is kept by the +implicit object +<code>pageContext</code>. + +This object is passed around through the Tag handler instances +so it can be used to communicate information: all it is needed +is to know the name under which the information is stored into +the pageContext. + +<h3>The Runtime Stack</h3> +<p> + +An alternative to explicit communication of information through +a named object is implicit coordination based on syntactic scoping. + +<p> +For example, in the following JSP segment the <code>foo</code> +action might create a server-side object; +later the nested <code>bar</code> action might access that server-side object. +The object is not named within the <code>pageContext</code>: +it is found because the specific <code>foo</code> element is the +closest enclosing instance of a known element type. + +<blockquote> +<code> +<pre> +&lt;foo&gt; + &lt;bar/&gt; +&lt;/foo&gt; +</pre> +</code> +</blockquote> + +<p> +This functionality is supported through the +<code>TagSupport.findAncestorWithClass(Tag, Class)</code>, +which uses a reference to parent tag kept by each Tag instance, +which effectively provides a run-time execution stack. + +<a name="simple"> +<h2>6. Simple Tag Handlers</h2> +</a> + +<p> This section presents the API to implement Simple Tag Handlers. +Simple Tag Handlers present a much simpler invocation +protocol than do Classic Tag Handlers.</p> + +<p>The Tag Library Descriptor maps tag library declarations to their +physical underlying implementations. A Simple Tag Handler is +represented in Java by a class which implements the +<code>SimpleTag</code> interface.</p> + +<p>Unlike classic tag handlers, the <code>SimpleTag</code> interface does not +extend Tag. Instead of supporting <code>doStartTag()</code> and +<code>doEndTag()</code>, the <code>SimpleTag</code> interface provides +a simple <code>doTag()</code> method, which is called once and only once +for any given tag invocation. All tag logic, iteration, body +evaluations, etc. are to be performed in this single method. Thus, +simple tag handlers have the equivalent power of <code>BodyTag</code>, +but with a much simpler lifecycle and interface.</p> + +<p>To support body content, the <code>setJspBody()</code> +method is provided. The container invokes the <code>setJspBody()</code> +method with a <code>JspFragment</code> object encapsulating the body +of the tag. The tag handler implementation can call +<code>invoke()</code> on that fragment to evaluate the body. The +<code>SimpleTagSupport</code> convenience class provides +<code>getJspBody()</code> and other useful methods to make this even +easier.</p> + +<h3>Lifecycle of Simple Tag Handlers</h3> +<p>This section describes the lifecycle of simple tag handlers, from +creation to invocation. For all semantics left unspecified by this +section, the semantics default to that of a classic tag handler.</p> + +<p>When a simple tag handler is invoked, the following steps occur +(in order):</p> + +<ol> + <li>Simple tag handlers are created initially using a zero + argument constructor on the corresponding implementation class. + Unlike classic tag handlers, this instance must never be pooled by + the container. A new instance must be created for each tag invocation.</li> + + <li>The <code>setJspContext()</code> and <code>setParent()</code> + methods are invoked on the tag handler. The <code>setParent()</code> + method need not be called if the value being passed in is + <code>null</code>. In the case of tag files, a <code>JspContext</code> + wrapper is created so that the tag file can appear to have its own page + scope. Calling <code>getJspContext()</code> must return the wrapped + <code>JspContext</code>.</li> + + <li>The attributes specified as XML element attributes (if any) + are evaluated next, in the order in which they are declared, according + to the following rules (referred to as "evaluating an XML element + attribute" below). The appropriate bean property setter is invoked + for each. If no setter is defined for the specified attribute but + the tag accepts dynamic attributes, the <code>setDynamicAttribute()</code> + method is invoked as the setter. + <ul> + <li>If the attribute is a scripting expression (e.g. "&lt;%= 1+1 %&gt;" + in JSP syntax, or "%= 1+1 %" in XML syntax), the expression is + evaluated, and the result is converted as per the rules in + "Type Conversions", and passed to the setter.</li> + + <li>Otherwise, if the attribute contains any Expression Language + expressions (e.g. "Hello ${name}"), the expression is evaluated, and + the result is converted and passed to the setter.</li> + + <li>Otherwise, the attribute value is taken verbatim, converted, + and passed to the setter.</li> + </ul> + </li> + + <li>The value for each &lt;jsp:attribute&gt; element is evaluated, + and the corresponding bean property setter methods are invoked for + each, in the order in which they appear in the body of the tag. If no + setter is defined for the specified attribute but the tag + accepts dynamic attributes, the <code>setDynamicAttribute()</code> + method is invoked as the setter. + <ul> + <li>Otherwise, if the attribute is not of type + <code>JspFragment</code>, the container evaluates the body of + the &lt;jsp:attribute&gt; element. This evaluation can be done + in a container-specific manner. Container implementors should + note that in the process of evaluating this body, other custom + actions may be invoked.</li> + + <li>Otherwise, if the attribute is of type <code>JspFragment</code>, + an instance of a <code>JspFragment</code> object is created and + passed in.</li> + </ul> + </li> + + <li>The value for the body of the tag is determined, and if + a body exists the <code>setJspBody()</code> method is called on the + tag handler. + <ul> + <li>If the tag is declared to have a <code>body-content</code> + of "<code>empty</code>" or no body or an empty body is passed + for this invocation, then <code>setJspBody()</code> is not + called.</li> + + <li>Otherwise, the body of the tag is either the body of + the &lt;jsp:body&gt; element, or the body of the custom action + invocation if no &lt;jsp:body&gt; or &lt;jsp:attribute&gt; + elements are present. In this case, an instance of a + <code>JspFragment</code> object is created as per the lifecycle + described in the JSP Fragments section and it is passed to the + setter. If the tag is declared to have a <code>body-content</code> + of "<code>tagdependent</code>" the <code>JspFragment</code> must + echo the body's contents verbatim. Otherwise, if the tag is + declared to have a <code>body-content</code> of type + "<code>scriptless</code>", the <code>JspFragment</code> must + evaluate the body's contents as a JSP scriptless body.</li> + </ul> + </li> + + <li>The <code>doTag()</code> method is invoked.</li> + + <li>The implementation of <code>doTag()</code> performs its + function, potentially calling other tag handlers (if the tag + handler is implemented as a tag file) and invoking fragments.</li> + + <li>The <code>doTag()</code> method returns, and the tag handler + instance is discarded. If <code>SkipPageException</code> is thrown, + the rest of the page is not evaluated and the request is completed. + If this request was forwarded or included from another page (or Servlet), + only the current page evaluation stops.</li> + + <li>For each tag scripting variable declared with scopes + <code>AT_BEGIN</code> or <code>AT_END</code>, the appropriate + scripting variables and scoped attributes are declared, as with + classic tag handlers.</li> +</ol> + +<a name="fragment"> +<h2>7. JSP Fragments</h2> +</a> + +<p>JSP Fragments are represented in Java by an instance of the +<code>javax.servlet.jsp.tagext.JspFragment abstract class</code>. +Pieces of JSP code are translated into JSP fragments in the context +of a tag invocation. JSP Fragments are created when providing the body of a +&lt;jsp:attribute&gt; standard action for an attribute that is defined +as a fragment or of type JspFragment, or when providing the body of a +tag invocation handled by a Simple Tag Handler.</p> + +<p>Before being passed to a tag handler, the <code>JspFragment</code> +instance is associated with the <code>JspContext</code> of the +surrounding page in an implementation-dependent manner. In addition, + +it is associated with the parent <code>Tag</code> or <code>SimpleTag</code> +instance for collaboration purposes, so that when a custom action is +invoked from within the fragment, <code>setParent()</code> can be called +with the appropriate value. The fragment implementation must keep +these associations for the duration of the tag invocation in which it +is used.</p> + +<p>The <code>invoke()</code> method executes the body and directs +all output to either the passed in <code>java.io.Writer</code> or +the <code>JspWriter</code> returned by the <code>getOut()</code> method +of the <code>JspContext</code> associated with the fragment.</p> + +<p>The implementation of each method can optionally throw a +<code>JspException</code>, which must be handled by the invoker. Note +that tag library developers and page authors should not generate +<code>JspFragment</code> implementations manually.</p> + +<p>The following sections specify the creation and invocation +lifecycles of a JSP Fragment in detail, from the JSP Container's +perspective.</p> + + +<h3>Creation of a JSP Fragment</h3> + +<p>When a JSP fragment is created, the following steps occur (in order): + +<ol> + <li>An instance of a class implementing the <code>JspFragment</code> + abstract class is obtained (may either be created or can optionally be cached) + each time the tag is invoked. This instance must be configured to + produce the contents of the body of the fragment when invoked. If the + fragment is defining the body of a &lt;jsp:attribute&gt;, the fragment + must evaluate the body each time it is invoked. Otherwise, if the + fragment is defining the body of a simple tag, the behavior of the + fragment when invoked varies depending on the <code>body-content</code> + declared for the tag: + <ul> + <li>If the <code>body-content</code> is "<code>tagdependent</code>", + then the fragment must echo the contents of the body verbatim + when invoked.</li> + + <li>If the <code>body-content</code> is "<code>scriptless</code>", + then the fragment must evaluate the body each time it is invoked.</li> + </ul> + </li> + + <li>The <code>JspFragment</code> instance is passed a reference to + the current <code>JspContext</code>. Whenever the fragment invokes + a tag handler, it must use this value when calling + <code>setJspContext()</code>.</li> + + <li>The <code>JspFragment</code> instance is associated with an + instance of the tag handler of the nearest enclosing tag + invocation, or with <code>null</code> if there is no enclosing tag. + Whenever the fragment invokes a tag handler, the fragment must + use this value when calling <code>setParent()</code>.</li> +</ol> + + +<h3>Invocation of a JSP Fragment</h3> + +<p>After a JSP fragment is created, it is passed to a tag handler for +later invocation. JSP fragments can be invoked either programmatically +from a tag handler written in Java, or from a tag file using the +&lt;jsp:invoke&gt; or &lt;jsp:doBody&gt; standard action.</p> + +<p>JSP fragments are passed to tag handlers using a bean property +of type <code>JspFragment</code>. These fragments can be invoked by +calling the <code>invoke()</code> method in the <code>JspFragment</code> +abstract class. Note that it is legal (and possible) for a fragment to +recursively invoke itself, indirectly.</p> + +<p>The following steps are followed when invoking a JSP fragment:</p> + +<ol> + <li>The tag handler invoking the fragment is responsible for + setting the values of all declared <code>AT_BEGIN</code> and + <code>NESTED</code> variables in the <code>JspContext</code> of the + calling page/tag, before invoking the fragment. Note that this is + not always the same as the <code>JspContext</code> of the fragment + being invoked, as fragments can be passed from one tag to another. + In the case of tag files, for each variable declared + in scope <code>AT_BEGIN</code> or <code>NESTED</code>, if a page + scoped attribute exists with the provided name in the tag file, the + JSP container must generate code to create/update the page scoped + attribute of the provided name in the calling page/tag. If a page + scoped attribute with the provided name does not exist in the tag + file, and a page scoped attribute of the provided name is present in + the calling page, the scoped attribute is removed from the calling + page's page scope. See the chapter on Tag Files for details.</li> + + <li>If &lt;jsp:invoke&gt; or &lt;jsp:doBody&gt; is being used to + invoke a fragment, if the <code>var</code> attribute is specified, + a custom <code>java.io.Writer</code> is created that can expose + the result of the invocation as a <code>java.lang.String</code> + object. If the <code>varReader</code> attribute is + specified, a custom <code>java.io.Writer</code> object is created + that can expose the resulting invocation as a + <code>java.io.Reader</code> object.</li> + + <li>The <code>invoke()</code> method of the fragment is invoked, + passing in an optional <code>Writer</code>.</li> + + <li>Before executing the body of the fragment, if a non-null value + is provided for the writer parameter, then the value of + <code>JspContext.getOut()</code> and the implicit "out" object must + be updated to send output to that writer. To accomplish + this, the container must call <code>pushBody( writer )</code> on the + current <code>JspContext</code>, where <code>writer</code> is the + instance of <code>java.io.Writer</code> passed to the fragment upon + invocation.</li> + + <li>The body of the fragment is then evaluated by executing + the generated code. The body of the fragment may execute other standard + or custom actions. If a classic Custom Tag Handler is invoked and + returns <code>SKIP_PAGE</code>, or if a Simple Tag Handler is invoked + and throws <code>SkipPageException</code>, the + <code>JspFragment</code> must throw <code>SkipPageException</code> to + signal that the calling page is to be skipped.</li> + + <li>Once the fragment has completed its evaluation, even if an exception + is thrown, the value of <code>JspContext.getOut()</code> must be + restored via a call to <code>popBody()</code> on the current + <code>JspContext</code>.</li> + + <li>The fragment returns from invoke()</li> + + <li>If &lt;jsp:invoke&gt; or &lt;jsp:doBody&gt; is being used to + invoke a fragment, if the <code>var</code> or <code>varReader</code> + attribute is specified, a scoped variable with a name equal to the + value of the <code>var</code> or <code>varReader</code> attribute + is created (or modified) in the page scope, and the value is set + to a <code>java.lang.String</code> or <code>java.io.Reader</code> + respectively that can produce the results of the fragment + invocation.</li> + + <li>The <code>invoke()</code> method can be called again, zero or more + times. When the tag invocation defining the fragment is complete, + the tag must discard the fragment instance since it might be reused + by the container.</li> + +</ol> + +<a name="sths"> +<h2>8. Example Simple Tag Handler Scenario</h2> +</a> + +<p>The following non-normative example is intended to help solidify +some of the concepts relating to Tag Files, JSP Fragments and Simple +Tag Handlers. In the first section, two sample input files are +presented, a JSP (my.jsp), and a simple tag handler implemented using +a tag file (simpletag.tag). One possible output of the translation +process is presented in the second section.</p> + +<p>Although short, the example shows all concepts, including +the variable directive. In practice most uses of tags will be much simpler, +but probably longer.</p> + +<p>The sample generated code is annotated with comments that point +to lifecycle steps presented in various sections. The notation is as +follows:</p> + +<ul> + <li>"Step T.x" = Annotated step x from "Lifecycle of Simple Tag + Handlers" earlier in this Chapter.</li> + <li>"Step C.x" = Annotated step x from "Creation of a JSP Fragment" + earlier in this Chapter.</li> + <li>"Step F.x" = Annotated step x from "Invocation of a JSP Fragment" + earlier in this Chapter.</li> +</ul> + + +<h3>Sample Source Files</h3> + +<p>This section presents the sample source files in this scenario, +from which the output files are generated.</p> + +<h4>Original JSP (my.jsp)</h4> +<pre> +&lt;%@ taglib prefix="my" tagdir="/WEB-INF/tags" %&gt; + +&lt;my:simpleTag x="10"&gt; + &lt;jsp:attribute name="y"&gt;20&lt;/jsp:attribute&gt; + &lt;jsp:attribute name="nonfragment"&gt; + Nonfragment Template Text + &lt;/jsp:attribute&gt; + &lt;jsp:attribute name="frag"&gt; + Fragment Template Text ${var1} + &lt;/jsp:attribute&gt; + &lt;jsp:body&gt; + Body of tag that defines an AT_BEGIN + scripting variable ${var1}. + &lt;/jsp:body&gt; +&lt;/my:simpleTag&gt; +</pre> + +<h4>Original Tag File (/WEB-INF/tags/simpletag.tag)</h4> +<pre> +&lt;%-- /WEB-INF/tags/simpletag.tag --%&gt; +&lt;%@ attribute name="x" %&gt; +&lt;%@ attribute name="y" %&gt; +&lt;%@ attribute name="nonfragment" %&gt; +&lt;%@ attribute name="frag" fragment="true" %&gt; +&lt;%@ variable name-given="var1" scope="AT_BEGIN" %&gt; +&lt;%@ taglib prefix="c" uri="http://java.sun.com/jsp/jstl/core" %&gt; + +Some template text. +&lt;c:set var="var1" value="${x+y}"/&gt; +&lt;jsp:invoke fragment="frag" varReader="var1"/&gt; + +Invoke the body: +&lt;jsp:doBody/&gt; +</pre> + + +<h3>Sample Generated Files</h3> +<p>This section presents sample output files that might be generated +by a JSP compiler, from the source files presented in the +previous section.</p> + +<h4>Helper class for JspFragment (JspFragmentBase.java)</h4> +<pre> +public abstract class JspFragmentBase + implements javax.servlet.jsp.tagext.JspFragment +{ + protected javax.servlet.jsp.JspContext jspContext; + protected javax.servlet.jsp.tagext.JspTag parentTag; + public void JspFragmentBase( + javax.servlet.jsp.JspContext jspContext, + javax.servlet.jsp.tagext.JspTag parentTag ) + { + this.jspContext = jspContext; + this.parentTag = parentTag; + } +} +</pre> +<h4>Relevant Portion of JSP Service Method</h4> +<pre> +// Step T.1 - Initial creation +MySimpleTag _jsp_mySimpleTag = new MySimpleTag(); +// Step T.2 - Set page context and parent (since parent is null, +// no need to call setParent() in this case) +_jsp_mySimpleTag.setJspContext( jspContext ); +// Step T.3 - XML element attributes evaluated and set +_jsp.mySimpleTag.setX( "10" ); +// Step T.4 - &lt;jsp:attribute&gt; elements evaluated and set +// - parameter y +// (using PageContext.pushBody() is one possible implementation - +// one limitation is that this code will only work for Servlet-based code). +out = ((PageContext)jspContext).pushBody(); +out.write( "20" ); +_jsp_mySimpleTag.setY( + ((javax.servlet.jsp.tagext.BodyContent)out).getString() ); +out = jspContext.popBody(); +// - parameter nonfragment +// (using PageContext.pushBody() is one possible implementation - +// one limitation is that this code will only work for Servlet-based code). +// Note that trim is enabled by default, else we would have "\n Non..." +out = ((PageContext)jspContext).pushBody(); +out.write( "Nonfragment Template Text" ); +_jsp_mySimpleTag.setNonfragment( + ((javax.servlet.jsp.tagext.BodyContent)out).getString() ); +out = jspContext.popBody(); +// - parameter frag +_jsp_mySimpleTag.setFrag( + // Step C.1 - New instance of fragment created + // Step C.2 - Store jspContext + // Step C.3 - Association with nearest enclosing Tag instance + new JspFragmentBase( jspContext, _jsp_mySimpleTag ) { + public void invoke( java.io.Writer writer ) { + javax.servlet.jsp.JspWriter out; + // Step F.1-F.3 done in tag file (see following example) + // Step F.4 - If writer provided, push body: + if( out == null ) { + out = this.jspContext.getOut(); + } + else { + out = this.jspContext.pushBody( writer ); + } + // Step F.5 - Evaluate body of fragment: + try { + out.write( "Fragment Template Text " ); + out.write( jspContext.getExpressionEvaluator().evaluate( + "${var1}", + java.lang.String.class, + vResolver, fMapper, "my" ) ); + } + finally { + // Step F.6 - Restore value of JspContext.getOut() + if( writer != null ) { + this.jspContext.popBody(); + } + } + + // Step F.7-F.9 done in tag file (see following example) + } + } ); +// Step T.5 - Determine and set body of the tag +// - body of tag +_jsp_mySimpleTag.setJspBody( + // Step C.1 - New instance of fragment created + // Step C.2 - Store jspContext + // Step C.3 - Association with nearest enclosing Tag instance + new JspFragmentBase( jspContext, _jsp_mySimpleTag ) { + public void invoke( java.io.Writer writer ) { + javax.servlet.jsp.JspWriter out; + // Step F.1-F.3 done in tag file (see following example) + // Step F.4 - If writer provided, push body: + if( writer == null ) { + out = this.jspContext.getOut(); + } + else { + out = this.jspContext.pushBody( writer ); + } + // Step F.5 - Evaluate body of fragment: + try { + out.write( + "Body of tag that defines an AT_BEGIN\n" + + " scripting variable " ); + out.write( jspContext.getExpressionEvaluator().evaluate( + "${var1}", + java.lang.String.class, + vResolver, fMapper, "my" ) ); + out.write( ".\n" ); + } + finally { + // Step F.6 - Restore value of JspContext.getOut() + if( writer != null ) { + this.jspContext.popBody(); + } + } + + // Step F.7-F.9 done in tag file (see following example) + } + } ); +// Step T.6 - Inovke doTag +// Step T.7 occurs in the tag file (see following example) +// Step T.8 - doTag returns - page will catch SkipPageException. +_jsp_mySimpleTag.doTag(); +// Step T.9 - Declare AT_BEGIN and AT_END scripting variables +String var1 = (String)jspContext.findAttribute( "var1" ); +</pre> + +<h4>Generated Simple Tag Handler (MySimpleTag.java)</h4> +<pre> +public class MySimpleTag + extends javax.servlet.jsp.tagext.SimpleTagSupport +{ + // Attributes: + private String x; + private String y; + private String nonfragment; + private javax.servlet.jsp.tagext.JspFragment frag; + // Setters and getters for attributes: + public void setX( Stirng x ) { + this.x = x; + } + public String getX() { + return this.x; + } + public void setY( String y ) { + this.y = y; + } + public String getY() { + return this.y; + } + public void setNonfragment( String nonfragment ) { + this.nonfragment = nonfragment; + } + public String getNonfragment() { + return this.nonfragment; + } + public void setFrag( javax.servlet.jsp.tagext.JspFragment frag ) { + this.frag = frag; + } + public javax.servlet.jsp.tagext.JspFragment getFrag() { + return this.frag; + } + + protected JspContext jspContext; + public void setJspContext( JspContext ctx ) { + super.setJspContext( ctx ); + // Step T.2 - A JspContext wrapper is created. + // (Implementation of wrapper not shown). + this.jspContext = new utils.JspContextWrapper( ctx ); + } + public JspContext getJspContext() { + // Step T.2 - Calling getJspContext() must return the + // wrapped JspContext. + return this.jspContext; + } + + public void doTag() throws JspException { + java.lang.Object jspValue; + JspContext jspContext = getJspContext(); + JspContext _jsp_parentContext = + SimpleTagSupport.this.getJspContext(); + try { + javax.servlet.jsp.JspWriter out = jspContext.getOut(); + + // Create page-scope attributes for each tag attribute: + this.jspContext.setAttribute( "x", getX() ); + this.jspContext.setAttribute( "y", getY() ); + this.jspContext.setAttribute( "nonfragment", getNonfragment() ); + this.jspContext.setAttribute( "frag", getFrag() ); + + // Synchronize AT_BEGIN variables from calling page + if( (jspValue = _jsp_parentContext.getAttribute( + "var1" )) != null ) + { + jspContext.setAttribute( "var1", value ); + } + else { + jspContext.removeAttribute( "var1", + JspContext.PAGE_SCOPE ); + } + + // Tag template text: + out.write( "\n\n\n\n\n\n\n\nSome template text.\n" ); + + // Invoke c:set - recognized tag handler from JSTL: + jspContext.setAttribute( "var1", + jspContext.getExpressionEvaluator().evaluate( + "${x+y}", + java.lang.String.class, + jspContext, + prefixMap, functionMap, "my" ) ); + + // Invoke the "frag" fragment: + // Step F.1 - Set values of AT_BEGIN and NESTED variables + // in calling page context. + if( (jspValue = jspContext.getAttribute( "var1" )) != null ) { + _jsp_parentContext.setAttribute( "var1", value ); + } + else { + _jsp_parentContext.removeAttribute( "var1", + JspContext.PAGE_SCOPE ); + } + + // Step F.2 - varReader is specified, generate a writer. + java.io.Writer _jsp_sout = new java.io.StringWriter(); + + // Step F.3 - Invoke fragment with writer + getFrag().invoke( _jsp_sout ); + + // Step F.4 - F.6 occur in the fragment (see above) + // Step F.7 - fragment returns + + // Step F.8 - varReader specified, so save to var + jspContext.setAttribute( + "var1", new StringReader( _jsp_sout.toString() ) ); + + // Step F.9 - Done! + + + out.write( "\n\nInvoke the body:\n" ); + + // Invoke the body of the tag: + // Step F.1 - Set values of AT_BEGIN and NESTED variables + // in calling page context. + if( (jspValue = jspContext.getAttribute( "var1" )) != null ) { + _jsp_parentContext.setAttribute( "var1", value ); + } + else { + _jsp_parentContext.removeAttribute( "var1", + JspContext.PAGE_SCOPE); + } + + // Step F.2 - varReader is not specified - does not apply. + + try { + // Step F.3 - Invoke body, passing optional writer + getJspBody().invoke( null ); + } + finally { + // Steps F.4 - F.6 occur in the fragment (see above) + // Step F.7 - fragment returns + } + + // Step F.8 does not apply. + // Step F.9 - Done! + } + finally { + // Tag handlers generate code to synchronize AT_BEGIN with + // calling page, regardless of whether an error occurs. + if( (jspValue = jspContext.getAttribute( "var1" )) != null ) { + _jsp_parentContext.setAttribute( "var1", value ); + } + else { + _jsp_parentContext.removeAttribute( "var1", + JspContext.PAGE_SCOPE ); + } + } + } +} + +</pre> + +<a name="translation"> +<h2>9. Translation-time Classes</h2> +</a> + +The following classes are used at translation time. + +<h3>Tag mapping, Tag name</h3> + +<p> A taglib directive introduces a tag library and associates a +prefix to it. The TLD associated with the library associates Tag +handler classes (plus other information) with tag names. This +information is used to associate a Tag class, a prefix, and a name +with each custom action element appearing in a JSP page. + +<p> At execution time the implementation of a JSP page will use an +available Tag instance with the appropriate property settings and then +follow the protocol described by the interfaces Tag, IterationTag, +BodyTag, SimpleTag, and TryCatchFinally. The implementation guarantees +that all tag handler instances are initialized and all are released, +but the implementation can assume that previous settings are preserved +by a tag handler, to reduce run-time costs. + + +<h3>Scripting Variables</h3> + +<p> JSP supports scripting variables that can be declared within a +scriptlet and can be used in another. JSP actions also can be used to +define scripting variables so they can used in scripting elements, or +in other actions. This is very useful in some cases; for example, the +<code>jsp:useBean</code> standard action may define an object which +can later be used through a scripting variable. + +<p> In some cases the information on scripting variables can be +described directly into the TLD using elements. A special case is typical +interpretation of the &quot;id&quot; attribute. +In other cases the logic that decides whether an action instance +will define a scripting variable may be quite complex and the name of +a <code>TagExtraInfo</code> class is instead given in the TLD. The +<code>getVariableInfo</code> method of this class is used at +translation time to obtain information on each variable that will be +created at request time when this action is executed. The method is +passed a <code>TagData</code> instance that contains the +translation-time attribute values. + +<h3>Validation</h3> + +<p> The TLD file contains several pieces of information that is used +to do syntactic validation at translation-time. It also contains two +extensible validation mechanisms: a <code>TagLibraryValidator</code> +class can be used to validate a complete JSP page, and a +<code>TagExtraInfo</code> class can be used to validate a specific +action. In some cases, additional request-time validation will be done +dynamically within the methods in the Tag instance. If an error is +discovered, an instance of <code>JspTagException</code> can be thrown. +If uncaught, this object will invoke the errorpage mechanism of JSP. + +<p> The TagLibraryValidator is an addition to the JSP 1.2 +specification and is very open ended, being strictly more powerful +than the TagExtraInfo mechanism. A JSP page is presented via the +<code>PageData</code> object, which abstracts the XML view of the JSP +page. + +<p> A PageData instance will provides an InputStream (read-only) on the +page. Later specifications may add other views on the page (DOM, SAX, +JDOM are all candidates), for now these views can be generated from +the InputStream and perhaps can be cached for improved performance +(recall the view of the page is just read-only). + +<p> As of JSP 2.0, the JSP container must support a jsp:id attribute to +provide higher quality validation errors. The +container will track the JSP pages as passed to the container, and +will assign to each element a unique "id", which is passed as the +value of the jsp:id attribute. Each XML element in the XML view +will be extended with this attribute. The +TagLibraryValidator can use the attribute in one or more +ValidationMessage objects. The container then, in turn, can use these +values to provide more precise information on the location of an +error. + +<p>The prefix for the <code>id</code> attribute need not be "<code>jsp</code>" +but it must map to the namespace <code>http://java.sun.com/JSP/Page</code>;. +In the case where the user has redefined the <code>jsp</code> prefix, an +alternative prefix must be used by the container. + + +<h4>Validation Details</h4> + +<p> In detail, validation is done as follows: + +<p> <b>First</b>, the JSP page is parsed using the information in the TLD. +At this stage valid mandatory and optional attributes are checked. + +<p> <b>Second</b>, for each unique tag library in the page as determined +by the tag library URI, and in the lexical order in which they appear, +their associated validator class (if any) is invoked. This involves +several substeps. + +<p> The first substep is to obtain an initialized validator instance by +either: + +<ul> +<li> construct a new instance and invoke setInitParameters() on it, or +<li> obtain an existing instance that is not being used, invoke release() on it, and then invoke setInitParameters() on it, or +<li> locate an existing instance that is not being used on which the desired setInitParameters() has already been invoked +</ul> + +<p> The class name is as indicated in the &lt;validator-class&gt; element, +and the Map passed through setInitParameters() is as described in the +&lt;init-params&gt; element. +All TagLibraryValidator classes are supposed to keep their initParameters +until new ones are set, or until release() is invoked on them. + +<p> The second substep is to perform the actual validation. This is done +by invoking the validate() method with a prefix, uri, and PageData that +correspond to the taglib directive instance being validated and the +PageData representing the page. In the case where a single URI is mapped +to more than one prefix, the prefix of the first URI must be used. + +<p> The last substep is to invoke the release() method on the validator tag +when it is no longer needed. This method releases all resources. + +<p> <b>Finally</b>, after checking all the tag library validator classes, the +TagExtraInfo classes for all tags will be consulted by invoking their +<code>validate</code> method. The order of invocation of this methods +is undefined. + + + </body> </html>