1. /*

  2.  * The Apache Software License, Version 1.1

  3.  *

  4.  * Copyright (c) 1999 The Apache Software Foundation.  All rights 

  5.  * reserved.

  6.  *

  7.  * Redistribution and use in source and binary forms, with or without

  8.  * modification, are permitted provided that the following conditions

  9.  * are met:

  10.  *

  11.  * 1. Redistributions of source code must retain the above copyright

  12.  *    notice, this list of conditions and the following disclaimer. 

  13.  *

  14.  * 2. Redistributions in binary form must reproduce the above copyright

  15.  *    notice, this list of conditions and the following disclaimer in

  16.  *    the documentation and/or other materials provided with the

  17.  *    distribution.

  18.  *

  19.  * 3. The end-user documentation included with the redistribution, if

  20.  *    any, must include the following acknowlegement:  

  21.  *       "This product includes software developed by the 

  22.  *        Apache Software Foundation (http://www.apache.org/)."

  23.  *    Alternately, this acknowlegement may appear in the software itself,

  24.  *    if and wherever such third-party acknowlegements normally appear.

  25.  *

  26.  * 4. The names "The Jakarta Project", "Tomcat", and "Apache Software

  27.  *    Foundation" must not be used to endorse or promote products derived

  28.  *    from this software without prior written permission. For written 

  29.  *    permission, please contact apache@apache.org.

  30.  *

  31.  * 5. Products derived from this software may not be called "Apache"

  32.  *    nor may "Apache" appear in their names without prior written

  33.  *    permission of the Apache Group.

  34.  *

  35.  * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED

  36.  * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES

  37.  * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE

  38.  * DISCLAIMED.  IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR

  39.  * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

  40.  * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

  41.  * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF

  42.  * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND

  43.  * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,

  44.  * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT

  45.  * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF

  46.  * SUCH DAMAGE.

  47.  * ====================================================================

  48.  *

  49.  * This software consists of voluntary contributions made by many

  50.  * individuals on behalf of the Apache Software Foundation.  For more

  51.  * information on the Apache Software Foundation, please see

  52.  * <http://www.apache.org/>.

  53.  *

  54.  */

  55. package javax.servlet.jsp.tagext;

  56. 

  57. import javax.servlet.jsp.*;

  58. 

  59. /**

  60.  * The BodyTag interface extends IterationTag by defining additional

  61.  * methods that let a tag handler manipulate the content of evaluating its body.

  62.  *

  63.  * <p>

  64.  * It is the responsibility of the tag handler to manipulate the body

  65.  * content.  For example the tag handler may take the body content,

  66.  * convert it into a String using the bodyContent.getString

  67.  * method and then use it.  Or the tag handler may take the body

  68.  * content and write it out into its enclosing JspWriter using

  69.  * the bodyContent.writeOut method.

  70.  *

  71.  * <p> A tag handler that implements BodyTag is treated as one that

  72.  * implements IterationTag, except that the doStartTag method can

  73.  * return SKIP_BODY, EVAL_BODY_INCLUDE or EVAL_BODY_BUFFERED.

  74.  *

  75.  * <p>

  76.  * If EVAL_BODY_INCLUDE is returned, then evaluation happens

  77.  * as in IterationTag.

  78.  *

  79.  * <p>

  80.  * If EVAL_BODY_BUFFERED is returned, then a BodyContent object will be

  81.  * created (by code generated by the JSP compiler) to capture the body

  82.  * evaluation.

  83.  * The code generated by the JSP compiler obtains the BodyContent object by

  84.  * calling the pushBody method of the current pageContext, which

  85.  * additionally has the effect of saving the previous out value.

  86.  * The page compiler returns this object by calling the popBody

  87.  * method of the PageContext class;

  88.  * the call also restores the value of out.

  89.  *

  90.  * <p>

  91.  * The interface provides one new property with a setter method and one

  92.  * new action method.

  93.  *

  94.  * <p><B>Properties</B>

  95.  * <p> There is a new property: bodyContent, to contain the BodyContent

  96.  * object, where the JSP Page implementation object will place the

  97.  * evaluation (and reevaluation, if appropriate) of the body.  The setter

  98.  * method (setBodyContent) will only be invoked if doStartTag() returns

  99.  * EVAL_BODY_BUFFERED.

  100.  *

  101.  * <p><B>Methods</B>

  102.  * <p> In addition to the setter method for the bodyContent property, there

  103.  * is a new action methods: doInitBody(), which is invoked right after

  104.  * setBodyContent() and before the body evaluation.  This method is only

  105.  * invoked if doStartTag() returns EVAL_BODY_BUFFERED.

  106.  *

  107.  * <p><B>Lifecycle</B>

  108.  * <p> Lifecycle details are described by the transition diagram below.

  109.  * Exceptions that are thrown during the computation of doStartTag(),

  110.  * setBodyContent(), doInitBody(), BODY, doAfterBody() interrupt the

  111.  * execution sequence and are propagated up the stack, unless the

  112.  * tag handler implements the TryCatchFinally interface; see that

  113.  * interface for details.

  114.  * <p>

  115.  * <IMG src="doc-files/BodyTagProtocol.gif"/>

  116. 

  117.  * <p><B>Empty and Non-Empty Action</B>

  118.  * <p> If the TagLibraryDescriptor file indicates that the action must

  119.  * always have an empty action, by an <body-content> entry of "empty",

  120.  * then the doStartTag() method must return SKIP_BODY.

  121.  *

  122.  * Otherwise, the doStartTag() method may return SKIP_BODY,

  123.  * EVAL_BODY_INCLUDE, or EVAL_BODY_BUFFERED.

  124.  *

  125.  * <p>

  126.  * If SKIP_BODY is returned the body is not evaluated, and doEndTag() is

  127.  * invoked.

  128.  *

  129.  * <p>

  130.  * If EVAL_BODY_INCLUDE is returned, setBodyContent() is not invoked,

  131.  * doInitBody() is not invoked, the body is evaluated and

  132.  * "passed through" to the current out, doAfterBody() is invoked

  133.  * and then, after zero or more iterations, doEndTag() is invoked.

  134.  *

  135.  * <p>

  136.  * If EVAL_BODY_BUFFERED is returned, setBodyContent() is invoked,

  137.  * doInitBody() is invoked, the body is evaluated, doAfterBody() is

  138.  * invoked, and then, after zero or more iterations, doEndTag() is invoked.

  139.  */

  140. 

  141. public interface BodyTag extends IterationTag {

  142. 

  143.     /**

  144.      * Deprecated constant that has the same value as EVAL_BODY_BUFFERED

  145.      * and EVAL_BODY_AGAIN.  This name has been marked as deprecated

  146.      * to encourage the use of the two different terms, which are much

  147.      * more descriptive.

  148.      *

  149.      * @deprecated	As of Java JSP API 1.2, use BodyTag.EVAL_BODY_BUFFERED

  150.      * or IterationTag.EVAL_BODY_AGAIN.

  151.      */

  152.  

  153.     public final static int EVAL_BODY_TAG = 2;

  154. 

  155.     /**

  156.      * Request the creation of new buffer, a BodyContent on which to

  157.      * evaluate the body of this tag.

  158.      *

  159.      * Returned from doStartTag when it implements BodyTag.

  160.      * This is an illegal return value for doStartTag when the class

  161.      * does not implement BodyTag.

  162.      */

  163. 

  164.     public final static int EVAL_BODY_BUFFERED = 2;

  165. 

  166. 

  167.     /**

  168.      * Set the bodyContent property.

  169.      * This method is invoked by the JSP page implementation object at

  170.      * most once per action invocation.

  171.      * This method will be invoked before doInitBody.

  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.      * When setBodyContent is invoked, the value of the implicit object out

  177.      * has already been changed in the pageContext object.  The BodyContent

  178.      * object passed will have not data on it but may have been reused

  179.      * (and cleared) from some previous invocation.

  180.      *

  181.      * <p>

  182.      * The BodyContent object is available and with the appropriate content

  183.      * until after the invocation of the doEndTag method, at which case it

  184.      * may be reused.

  185.      *

  186.      * @param b the BodyContent

  187.      * @seealso #doInitBody

  188.      * @seealso #doAfterBody

  189.      */

  190. 

  191.     void setBodyContent(BodyContent b);

  192. 

  193. 

  194.     /**

  195.      * Prepare for evaluation of the body.

  196.      * This method is invoked by the JSP page implementation object

  197.      * after setBodyContent and before the first time

  198.      * the body is to be evaluated.

  199.      * This method will not be invoked for empty tags or for non-empty

  200.      * tags whose doStartTag() method returns SKIP_BODY or EVAL_BODY_INCLUDE.

  201.      *

  202.      * <p>

  203.      * The JSP container will resynchronize

  204.      * any variable values that are indicated as so in TagExtraInfo after the

  205.      * invocation of doInitBody().

  206.      *

  207.      * @throws JspException

  208.      * @seealso #doAfterBody

  209.      */

  210. 

  211.     void doInitBody() throws JspException;

  212. 

  213. }