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 }