Java tutorial
/* * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS HEADER. * * Copyright (c) 1997-2010 Oracle and/or its affiliates. All rights reserved. * * The contents of this file are subject to the terms of either the GNU * General Public License Version 2 only ("GPL") or the Common Development * and Distribution License("CDDL") (collectively, the "License"). You * may not use this file except in compliance with the License. You can * obtain a copy of the License at * https://glassfish.dev.java.net/public/CDDL+GPL_1_1.html * or packager/legal/LICENSE.txt. See the License for the specific * language governing permissions and limitations under the License. * * When distributing the software, include this License Header Notice in each * file and include the License file at packager/legal/LICENSE.txt. * * GPL Classpath Exception: * Oracle designates this particular file as subject to the "Classpath" * exception as provided by Oracle in the GPL Version 2 section of the License * file that accompanied this code. * * Modifications: * If applicable, add the following below the License Header, with the fields * enclosed by brackets [] replaced by your own identifying information: * "Portions Copyright [year] [name of copyright owner]" * * Contributor(s): * If you wish your version of this file to be governed by only the CDDL or * only the GPL Version 2, indicate your decision by adding "[Contributor] * elects to include this software in this distribution under the [CDDL or GPL * Version 2] license." If you don't indicate a single choice of license, a * recipient has the option to distribute your version of this file under * either the CDDL, the GPL Version 2 or to extend the choice of license to * its licensees as provided above. However, if you add GPL Version 2 code * and therefore, elected the GPL Version 2 license, then the option applies * only if the new code is made subject to such option by the copyright * holder. * * * This file incorporates work covered by the following copyright and * permission notice: * * Copyright 2004 The Apache Software Foundation * * Licensed under the Apache License, Version 2.0 (the "License"); * you may not use this file except in compliance with the License. * You may obtain a copy of the License at * * http://www.apache.org/licenses/LICENSE-2.0 * * Unless required by applicable law or agreed to in writing, software * distributed under the License is distributed on an "AS IS" BASIS, * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. * See the License for the specific language governing permissions and * limitations under the License. */ package javax.servlet.jsp.tagext; /** * Information on the scripting variables that are created/modified by * a tag (at run-time). This information is provided by TagExtraInfo * classes and it is used by the translation phase of JSP. * * <p> * Scripting variables generated by a custom action have an associated * scope of either AT_BEGIN, NESTED, or AT_END. * * <p> * The class name (VariableInfo.getClassName) in the returned objects * is used to determine the types of the scripting variables. * Note that because scripting variables are assigned their values * from scoped attributes which cannot be of primitive types, * "boxed" types such as <code>java.lang.Integer</code> must * be used instead of primitives. * * <p> * The class name may be a Fully Qualified Class Name, or a short * class name. * * <p> * If a Fully Qualified Class Name is provided, it should refer to a * class that should be in the CLASSPATH for the Web Application (see * Servlet 2.4 specification - essentially it is WEB-INF/lib and * WEB-INF/classes). Failure to be so will lead to a translation-time * error. * * <p> * If a short class name is given in the VariableInfo objects, then * the class name must be that of a public class in the context of the * import directives of the page where the custom action appears. * The class must also be in the CLASSPATH for the Web Application * (see Servlet 2.4 specification - essentially it is WEB-INF/lib and * WEB-INF/classes). Failure to be so will lead to a translation-time * error. * * <p><B>Usage Comments</B> * <p> * Frequently a fully qualified class name will refer to a class that * 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 Java EE). Using fully qualified class names in this * manner makes the usage relatively resistant to configuration * errors. * * <p> * A short name is usually generated by the tag library based on some * attributes passed through from the custom action user (the author), * and it is thus less robust: for instance a missing import directive * in the referring JSP page will lead to an invalid short name class * and a translation error. * * <p><B>Synchronization Protocol</B> * * <p> * The result of the invocation on getVariableInfo is an array of * VariableInfo objects. Each such object describes a scripting * variable by providing its name, its type, whether the variable is * new or not, and what its scope is. Scope is best described through * a picture: * * <p> * <IMG src="doc-files/VariableInfo-1.gif" * alt="NESTED, AT_BEGIN and AT_END Variable Scopes"/> * *<p> * The JSP 2.0 specification defines the interpretation of 3 values: * * <ul> * <li> NESTED, if the scripting variable is available between * the start tag and the end tag of the action that defines it. * <li> * AT_BEGIN, if the scripting variable is available from the start tag * of the action that defines it until the end of the scope. * <li> AT_END, if the scripting variable is available after the end tag * of the action that defines it until the end of the scope. * </ul> * * The scope value for a variable implies what methods may affect its * value and thus where synchronization is needed as illustrated by * the table below. <b>Note:</b> the synchronization of the variable(s) * will occur <em>after</em> the respective method has been called. * * <blockquote> * <table cellpadding="2" cellspacing="2" border="0" width="55%" * bgcolor="#999999" summary="Variable Synchronization Points"> * <tr align="center"> * <td valign="top" colspan="6" bgcolor="#999999"><u><b>Variable Synchronization * Points</b></u><br> * </td> * </tr> * <tr> * <th valign="top" bgcolor="#c0c0c0"> </th> * <th valign="top" bgcolor="#c0c0c0" align="center">doStartTag()</th> * <th valign="top" bgcolor="#c0c0c0" align="center">doInitBody()</th> * <th valign="top" bgcolor="#c0c0c0" align="center">doAfterBody()</th> * <th valign="top" bgcolor="#c0c0c0" align="center">doEndTag()</th> * <th valign="top" bgcolor="#c0c0c0" align="center">doTag()</th> * </tr> * <tr> * <td valign="top" bgcolor="#c0c0c0"><b>Tag<br> * </b></td> * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br> * </td> * <td valign="top" align="center" bgcolor="#ffffff"><br> * </td> * <td valign="top" align="center" bgcolor="#ffffff"><br> * </td> * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> * </td> * <td valign="top" align="center" bgcolor="#ffffff"><br> * </td> * </tr> * <tr> * <td valign="top" bgcolor="#c0c0c0"><b>IterationTag<br> * </b></td> * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br> * </td> * <td valign="top" align="center" bgcolor="#ffffff"><br> * </td> * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br> * </td> * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> * </td> * <td valign="top" align="center" bgcolor="#ffffff"><br> * </td> * </tr> * <tr> * <td valign="top" bgcolor="#c0c0c0"><b>BodyTag<br> * </b></td> * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<sup>1</sup><br> * </td> * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<sup>1</sup><br> * </td> * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, NESTED<br> * </td> * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> * </td> * <td valign="top" align="center" bgcolor="#ffffff"><br> * </td> * </tr> * <tr> * <td valign="top" bgcolor="#c0c0c0"><b>SimpleTag<br> * </b></td> * <td valign="top" align="center" bgcolor="#ffffff"><br> * </td> * <td valign="top" align="center" bgcolor="#ffffff"><br> * </td> * <td valign="top" align="center" bgcolor="#ffffff"><br> * </td> * <td valign="top" align="center" bgcolor="#ffffff"><br> * </td> * <td valign="top" align="center" bgcolor="#ffffff">AT_BEGIN, AT_END<br> * </td> * </tr> * </table> * <sup>1</sup> Called after <code>doStartTag()</code> if * <code>EVAL_BODY_INCLUDE</code> is returned, or after * <code>doInitBody()</code> otherwise. * </blockquote> * * <p><B>Variable Information in the TLD</B> * <p> * Scripting variable information can also be encoded directly for most cases * into the Tag Library Descriptor using the <variable> subelement of the * <tag> element. See the JSP specification. */ public class VariableInfo { /** * Scope information that scripting variable is visible only within the * start/end tags. */ public static final int NESTED = 0; /** * Scope information that scripting variable is visible after start tag. */ public static final int AT_BEGIN = 1; /** * Scope information that scripting variable is visible after end tag. */ public static final int AT_END = 2; /** * Constructor * These objects can be created (at translation time) by the TagExtraInfo * instances. * * @param varName The name of the scripting variable * @param className The type of this variable * @param declare If true, it is a new variable (in some languages this will * require a declaration) * @param scope Indication on the lexical scope of the variable */ public VariableInfo(String varName, String className, boolean declare, int scope) { this.varName = varName; this.className = className; this.declare = declare; this.scope = scope; } // Accessor methods /** * Returns the name of the scripting variable. * * @return the name of the scripting variable */ public String getVarName() { return varName; } /** * Returns the type of this variable. * * @return the type of this variable */ public String getClassName() { return className; } /** * Returns whether this is a new variable. * If so, in some languages this will require a declaration. * * @return whether this is a new variable. */ public boolean getDeclare() { return declare; } /** * Returns the lexical scope of the variable. * * @return the lexical scope of the variable, either AT_BEGIN, AT_END, * or NESTED. * @see #AT_BEGIN * @see #AT_END * @see #NESTED */ public int getScope() { return scope; } // == private data private String varName; private String className; private boolean declare; private int scope; }