BodyTag


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