View Javadoc

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 &lt;body-_content&gt; 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 }