Package: BodyTag

BodyTag

Coverage

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