001 /* 002 * Licensed to the Apache Software Foundation (ASF) under one 003 * or more contributor license agreements. See the NOTICE file 004 * distributed with this work for additional information 005 * regarding copyright ownership. The ASF licenses this file 006 * to you under the Apache License, Version 2.0 (the 007 * "License"); you may not use this file except in compliance 008 * with the License. You may obtain a copy of the License at 009 * 010 * http://www.apache.org/licenses/LICENSE-2.0 011 * 012 * Unless required by applicable law or agreed to in writing, 013 * software distributed under the License is distributed on an 014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY 015 * KIND, either express or implied. See the License for the 016 * specific language governing permissions and limitations 017 * under the License. 018 */ 019 020 // 021 // This source code implements specifications defined by the Java 022 // Community Process. In order to remain compliant with the specification 023 // DO NOT add / change / or delete method signatures! 024 // 025 026 package javax.servlet.jsp.tagext; 027 028 import javax.servlet.jsp.*; 029 030 031 /** 032 * The interface of a classic tag handler that does not want to manipulate 033 * its body. The Tag interface defines the basic protocol between a Tag 034 * handler and JSP page implementation class. It defines the life cycle 035 * and the methods to be invoked at start and end tag. 036 * 037 * <p><B>Properties</B></p> 038 * 039 * <p>The Tag interface specifies the setter and getter methods for the core 040 * pageContext and parent properties.</p> 041 * 042 * <p>The JSP page implementation object invokes setPageContext and 043 * setParent, in that order, before invoking doStartTag() or doEndTag().</p> 044 * 045 * <p><B>Methods</B></p> 046 * 047 * <p>There are two main actions: doStartTag and doEndTag. Once all 048 * appropriate properties have been initialized, the doStartTag and 049 * doEndTag methods can be invoked on the tag handler. Between these 050 * invocations, the tag handler is assumed to hold a state that must 051 * be preserved. After the doEndTag invocation, the tag handler is 052 * available for further invocations (and it is expected to have 053 * retained its properties).</p> 054 * 055 * <p><B>Lifecycle</B></p> 056 * 057 * <p>Lifecycle details are described by the transition diagram below, 058 * with the following comments: 059 * <ul> 060 * <li> [1] This transition is intended to be for releasing long-term data. 061 * no guarantees are assumed on whether any properties have been retained 062 * or not. 063 * <li> [2] This transition happens if and only if the tag ends normally 064 * without raising an exception 065 * <li> [3] Some setters may be called again before a tag handler is 066 * reused. For instance, <code>setParent()</code> is called if it's 067 * reused within the same page but at a different level, 068 * <code>setPageContext()</code> is called if it's used in another page, 069 * and attribute setters are called if the values differ or are expressed 070 * as request-time attribute values. 071 * <li> Check the TryCatchFinally interface for additional details related 072 * to exception handling and resource management. 073 * </ul></p> 074 * 075 * <IMG src="doc-files/TagProtocol.gif" 076 * alt="Lifecycle Details Transition Diagram for Tag"/> 077 * 078 * <p>Once all invocations on the tag handler 079 * are completed, the release method is invoked on it. Once a release 080 * method is invoked <em>all</em> properties, including parent and 081 * pageContext, are assumed to have been reset to an unspecified value. 082 * The page compiler guarantees that release() will be invoked on the Tag 083 * handler before the handler is released to the GC.</p> 084 * 085 * <p><B>Empty and Non-Empty Action</B></p> 086 * <p>If the TagLibraryDescriptor file indicates that the action must 087 * always have an empty action, by an <body-content> entry of "empty", 088 * then the doStartTag() method must return SKIP_BODY.</p> 089 * 090 * <p>Otherwise, the doStartTag() method may return SKIP_BODY or 091 * EVAL_BODY_INCLUDE.</p> 092 * 093 * <p>If SKIP_BODY is returned the body, if present, is not evaluated.</p> 094 * 095 * <p>If EVAL_BODY_INCLUDE is returned, the body is evaluated and 096 * "passed through" to the current out.</p> 097 */ 098 099 public interface Tag extends JspTag { 100 101 /** 102 * Skip body evaluation. 103 * Valid return value for doStartTag and doAfterBody. 104 */ 105 106 public final static int SKIP_BODY = 0; 107 108 /** 109 * Evaluate body into existing out stream. 110 * Valid return value for doStartTag. 111 */ 112 113 public final static int EVAL_BODY_INCLUDE = 1; 114 115 /** 116 * Skip the rest of the page. 117 * Valid return value for doEndTag. 118 */ 119 120 public final static int SKIP_PAGE = 5; 121 122 /** 123 * Continue evaluating the page. 124 * Valid return value for doEndTag(). 125 */ 126 127 public final static int EVAL_PAGE = 6; 128 129 // Setters for Tag handler data 130 131 132 /** 133 * Set the current page context. 134 * This method is invoked by the JSP page implementation object 135 * prior to doStartTag(). 136 * <p> 137 * This value is *not* reset by doEndTag() and must be explicitly reset 138 * by a page implementation if it changes between calls to doStartTag(). 139 * 140 * @param pc The page context for this tag handler. 141 */ 142 143 void setPageContext(PageContext pc); 144 145 146 /** 147 * Set the parent (closest enclosing tag handler) of this tag handler. 148 * Invoked by the JSP page implementation object prior to doStartTag(). 149 * <p> 150 * This value is *not* reset by doEndTag() and must be explicitly reset 151 * by a page implementation. 152 * 153 * @param t The parent tag, or null. 154 */ 155 156 157 void setParent(Tag t); 158 159 160 /** 161 * Get the parent (closest enclosing tag handler) for this tag handler. 162 * 163 * <p> 164 * The getParent() method can be used to navigate the nested tag 165 * handler structure at runtime for cooperation among custom actions; 166 * for example, the findAncestorWithClass() method in TagSupport 167 * provides a convenient way of doing this. 168 * 169 * <p> 170 * The current version of the specification only provides one formal 171 * way of indicating the observable type of a tag handler: its 172 * tag handler implementation class, described in the tag-class 173 * subelement of the tag element. This is extended in an 174 * informal manner by allowing the tag library author to 175 * indicate in the description subelement an observable type. 176 * The type should be a subtype of the tag handler implementation 177 * class or void. 178 * This addititional constraint can be exploited by a 179 * specialized container that knows about that specific tag library, 180 * as in the case of the JSP standard tag library. 181 * 182 * @return the current parent, or null if none. 183 * @see TagSupport#findAncestorWithClass 184 */ 185 186 Tag getParent(); 187 188 189 // Actions for basic start/end processing. 190 191 192 /** 193 * Process the start tag for this instance. 194 * This method is invoked by the JSP page implementation object. 195 * 196 * <p> 197 * The doStartTag method assumes that the properties pageContext and 198 * parent have been set. It also assumes that any properties exposed as 199 * attributes have been set too. When this method is invoked, the body 200 * has not yet been evaluated. 201 * 202 * <p> 203 * This method returns Tag.EVAL_BODY_INCLUDE or 204 * BodyTag.EVAL_BODY_BUFFERED to indicate 205 * that the body of the action should be evaluated or SKIP_BODY to 206 * indicate otherwise. 207 * 208 * <p> 209 * When a Tag returns EVAL_BODY_INCLUDE the result of evaluating 210 * the body (if any) is included into the current "out" JspWriter as it 211 * happens and then doEndTag() is invoked. 212 * 213 * <p> 214 * BodyTag.EVAL_BODY_BUFFERED is only valid if the tag handler 215 * implements BodyTag. 216 * 217 * <p> 218 * The JSP container will resynchronize the values of any AT_BEGIN and 219 * NESTED variables (defined by the associated TagExtraInfo or TLD) 220 * after the invocation of doStartTag(), except for a tag handler 221 * implementing BodyTag whose doStartTag() method returns 222 * BodyTag.EVAL_BODY_BUFFERED. 223 * 224 * @return EVAL_BODY_INCLUDE if the tag wants to process body, SKIP_BODY 225 * if it does not want to process it. 226 * @throws JspException if an error occurred while processing this tag 227 * @see BodyTag 228 */ 229 230 int doStartTag() throws JspException; 231 232 233 /** 234 * Process the end tag for this instance. 235 * This method is invoked by the JSP page implementation object 236 * on all Tag handlers. 237 * 238 * <p> 239 * This method will be called after returning from doStartTag. The 240 * body of the action may or may not have been evaluated, depending on 241 * the return value of doStartTag. 242 * 243 * <p> 244 * If this method returns EVAL_PAGE, the rest of the page continues 245 * to be evaluated. If this method returns SKIP_PAGE, the rest of 246 * the page is not evaluated, the request is completed, and 247 * the doEndTag() methods of enclosing tags are not invoked. If this 248 * request was forwarded or included from another page (or Servlet), 249 * only the current page evaluation is stopped. 250 * 251 * <p> 252 * The JSP container will resynchronize the values of any AT_BEGIN and 253 * AT_END variables (defined by the associated TagExtraInfo or TLD) 254 * after the invocation of doEndTag(). 255 * 256 * @return indication of whether to continue evaluating the JSP page. 257 * @throws JspException if an error occurred while processing this tag 258 */ 259 260 int doEndTag() throws JspException; 261 262 /** 263 * Called on a Tag handler to release state. 264 * The page compiler guarantees that JSP page implementation 265 * objects will invoke this method on all tag handlers, 266 * but there may be multiple invocations on doStartTag and doEndTag in between. 267 */ 268 269 void release(); 270 271 }