1 /** 2 * 3 * Copyright 2003-2004 The Apache Software Foundation 4 * 5 * Licensed under the Apache License, Version 2.0 (the "License"); 6 * you may not use this file except in compliance with the License. 7 * You may obtain a copy of the License at 8 * 9 * http://www.apache.org/licenses/LICENSE-2.0 10 * 11 * Unless required by applicable law or agreed to in writing, software 12 * distributed under the License is distributed on an "AS IS" BASIS, 13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 14 * See the License for the specific language governing permissions and 15 * limitations under the License. 16 */ 17 18 // 19 // This source code implements specifications defined by the Java 20 // Community Process. In order to remain compliant with the specification 21 // DO NOT add / change / or delete method signatures! 22 // 23 24 package javax.servlet.jsp.tagext; 25 26 import javax.servlet.jsp.JspException; 27 28 /** 29 * The BodyTag interface extends IterationTag by defining additional 30 * methods that let a tag handler manipulate the _content of evaluating its body. 31 * 32 * <p> 33 * It is the responsibility of the tag handler to manipulate the body 34 * _content. For example the tag handler may take the body _content, 35 * convert it into a String using the bodyContent.getString 36 * method and then use it. Or the tag handler may take the body 37 * _content and write it out into its enclosing JspWriter using 38 * the bodyContent.writeOut method. 39 * 40 * <p> A tag handler that implements BodyTag is treated as one that 41 * implements IterationTag, except that the doStartTag method can 42 * return SKIP_BODY, EVAL_BODY_INCLUDE or EVAL_BODY_BUFFERED. 43 * 44 * <p> 45 * If EVAL_BODY_INCLUDE is returned, then evaluation happens 46 * as in IterationTag. 47 * 48 * <p> 49 * If EVAL_BODY_BUFFERED is returned, then a BodyContent object will be 50 * created (by code generated by the JSP compiler) to capture the body 51 * evaluation. 52 * The code generated by the JSP compiler obtains the BodyContent object by 53 * calling the pushBody method of the current pageContext, which 54 * additionally has the effect of saving the previous out value. 55 * The page compiler returns this object by calling the popBody 56 * method of the PageContext class; 57 * the call also restores the value of out. 58 * 59 * <p> 60 * The interface provides one new property with a setter method and one 61 * new action method. 62 * 63 * <p><B>Properties</B> 64 * <p> There is a new property: bodyContent, to contain the BodyContent 65 * object, where the JSP Page implementation object will place the 66 * evaluation (and reevaluation, if appropriate) of the body. The setter 67 * method (setBodyContent) will only be invoked if doStartTag() returns 68 * EVAL_BODY_BUFFERED and the corresponding action element does not have 69 * an empty body. 70 * 71 * <p><B>Methods</B> 72 * <p> In addition to the setter method for the bodyContent property, there 73 * is a new action method: doInitBody(), which is invoked right after 74 * setBodyContent() and before the body evaluation. This method is only 75 * invoked if doStartTag() returns EVAL_BODY_BUFFERED. 76 * 77 * <p><B>Lifecycle</B> 78 * <p> Lifecycle details are described by the transition diagram below. 79 * Exceptions that are thrown during the computation of doStartTag(), 80 * setBodyContent(), doInitBody(), BODY, doAfterBody() interrupt the 81 * execution sequence and are propagated up the stack, unless the 82 * tag handler implements the TryCatchFinally interface; see that 83 * interface for details. 84 * <p> 85 * <IMG src="doc-files/BodyTagProtocol.gif" 86 * alt="Lifecycle Details Transition Diagram for BodyTag"/> 87 * 88 * <p><B>Empty and Non-Empty Action</B> 89 * <p> If the TagLibraryDescriptor file indicates that the action must 90 * always have an empty element body, by an <body-_content> entry 91 * of "empty", then the doStartTag() method must return SKIP_BODY. 92 * Otherwise, the doStartTag() method may return SKIP_BODY, 93 * EVAL_BODY_INCLUDE, or EVAL_BODY_BUFFERED. 94 * 95 * <p>Note that which methods are invoked after the doStartTag() depends on 96 * both the return value and on if the custom action element is empty 97 * or not in the JSP page, not how it's declared in the TLD. 98 * 99 * <p> 100 * If SKIP_BODY is returned the body is not evaluated, and doEndTag() is 101 * invoked. 102 * 103 * <p> 104 * If EVAL_BODY_INCLUDE is returned, and the custom action element is not 105 * empty, setBodyContent() is not invoked, 106 * doInitBody() is not invoked, the body is evaluated and 107 * "passed through" to the current out, doAfterBody() is invoked 108 * and then, after zero or more iterations, doEndTag() is invoked. 109 * If the custom action element is empty, only doStart() and 110 * doEndTag() are invoked. 111 * 112 * <p> 113 * If EVAL_BODY_BUFFERED is returned, and the custom action element is not 114 * empty, setBodyContent() is invoked, 115 * doInitBody() is invoked, the body is evaluated, doAfterBody() is 116 * invoked, and then, after zero or more iterations, doEndTag() is invoked. 117 * If the custom action element is empty, only doStart() and doEndTag() 118 * are invoked. 119 */ 120 121 public interface BodyTag extends IterationTag { 122 123 /** 124 * Deprecated constant that has the same value as EVAL_BODY_BUFFERED 125 * and EVAL_BODY_AGAIN. This name has been marked as deprecated 126 * to encourage the use of the two different terms, which are much 127 * more descriptive. 128 * 129 * @deprecated As of Java JSP API 1.2, use BodyTag.EVAL_BODY_BUFFERED 130 * or IterationTag.EVAL_BODY_AGAIN. 131 */ 132 133 public final static int EVAL_BODY_TAG = 2; 134 135 /** 136 * Request the creation of new buffer, a BodyContent on which to 137 * evaluate the body of this tag. 138 * 139 * Returned from doStartTag when it implements BodyTag. 140 * This is an illegal return value for doStartTag when the class 141 * does not implement BodyTag. 142 */ 143 144 public final static int EVAL_BODY_BUFFERED = 2; 145 146 147 /** 148 * Set the bodyContent property. 149 * This method is invoked by the JSP page implementation object at 150 * most once per action invocation. 151 * This method will be invoked before doInitBody. 152 * This method will not be invoked for empty tags or for non-empty 153 * tags whose doStartTag() method returns SKIP_BODY or EVAL_BODY_INCLUDE. 154 * 155 * <p> 156 * When setBodyContent is invoked, the value of the implicit object out 157 * has already been changed in the pageContext object. The BodyContent 158 * object passed will have not data on it but may have been reused 159 * (and cleared) from some previous invocation. 160 * 161 * <p> 162 * The BodyContent object is available and with the appropriate _content 163 * until after the invocation of the doEndTag method, at which case it 164 * may be reused. 165 * 166 * @param b the BodyContent 167 * @see #doInitBody 168 * @see #doAfterBody 169 */ 170 171 void setBodyContent(BodyContent b); 172 173 174 /** 175 * Prepare for evaluation of the body. 176 * This method is invoked by the JSP page implementation object 177 * after setBodyContent and before the first time 178 * the body is to be evaluated. 179 * This method will not be invoked for empty tags or for non-empty 180 * tags whose doStartTag() method returns SKIP_BODY or EVAL_BODY_INCLUDE. 181 * 182 * <p> 183 * The JSP container will resynchronize the values of any AT_BEGIN and 184 * NESTED variables (defined by the associated TagExtraInfo or TLD) after 185 * the invocation of doInitBody(). 186 * 187 * @throws JspException if an error occurred while processing this tag 188 * @see #doAfterBody 189 */ 190 191 void doInitBody() throws JspException; 192 193 }