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 }