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.JspContext;
    27
    28  /**
    29   * Interface for defining Simple Tag Handlers.
    30   *
    31   * <p>Simple Tag Handlers differ from Classic Tag Handlers in that instead
    32   * of supporting <code>doStartTag()</code> and <code>doEndTag()</code>,
    33   * the <code>SimpleTag</code> interface provides a simple
    34   * <code>doTag()</code> method, which is called once and only once for any
    35   * given tag invocation.  All tag logic, iteration, body evaluations, etc.
    36   * are to be performed in this single method.  Thus, simple tag handlers
    37   * have the equivalent power of <code>BodyTag</code>, but with a much
    38   * simpler lifecycle and interface.</p>
    39   *
    40   * <p>To support body _content, the <code>setJspBody()</code>
    41   * method is provided.  The container invokes the <code>setJspBody()</code>
    42   * method with a <code>JspFragment</code> object encapsulating the body of
    43   * the tag.  The tag handler implementation can call
    44   * <code>invoke()</code> on that fragment to evaluate the body as
    45   * many times as it needs.</p>
    46   *
    47   * <p>A SimpleTag handler must have a public no-args constructor.  Most
    48   * SimpleTag handlers should extend SimpleTagSupport.</p>
    49   *
    50   * <p><b>Lifecycle</b></p>
    51   *
    52   * <p>The following is a non-normative, brief overview of the
    53   * SimpleTag lifecycle.  Refer to the JSP Specification for details.</p>
    54   *
    55   * <ol>
    56   *   <li>A new tag handler instance is created each time by the container
    57   *       by calling the provided zero-args constructor.  Unlike classic
    58   *       tag handlers, simple tag handlers are never cached and reused by
    59   *       the JSP container.</li>
    60   *   <li>The <code>setJspContext()</code> and <code>setParent()</code>
    61   *       methods are called by the container.  The <code>setParent()</code>
    62   *       method is only called if the element is nested within another tag
    63   *       invocation.</li>
    64   *   <li>The setters for each attribute defined for this tag are called
    65   *       by the container.</li>
    66   *   <li>If a body exists, the <code>setJspBody()</code> method is called
    67   *       by the container to set the body of this tag, as a
    68   *       <code>JspFragment</code>.  If the action element is empty in
    69   *       the page, this method is not called at all.</li>
    70   *   <li>The <code>doTag()</code> method is called by the container.  All
    71   *       tag logic, iteration, body evaluations, etc. occur in this
    72   *       method.</li>
    73   *   <li>The <code>doTag()</code> method returns and all variables are
    74   *       synchronized.</li>
    75   * </ol>
    76   *
    77   * @see SimpleTagSupport
    78   * @since 2.0
    79   */
    80  public interface SimpleTag extends JspTag {
    81
    82      /**
    83       * Called by the container to invoke this tag.
    84       * The implementation of this method is provided by the tag library
    85       * developer, and handles all tag processing, body iteration, etc.
    86       *
    87       * <p>
    88       * The JSP container will resynchronize any AT_BEGIN and AT_END
    89       * variables (defined by the associated tag file, TagExtraInfo, or TLD)
    90       * after the invocation of doTag().
    91       *
    92       * @throws javax.servlet.jsp.JspException If an error occurred
    93       *     while processing this tag.
    94       * @throws javax.servlet.jsp.SkipPageException If the page that
    95       *     (either directly or indirectly) invoked this tag is to
    96       *     cease evaluation.  A Simple Tag EventHandler generated from a
    97       *     tag file must throw this exception if an invoked Classic
    98       *     Tag EventHandler returned SKIP_PAGE or if an invoked Simple
    99       *     Tag EventHandler threw SkipPageException or if an invoked Jsp Fragment
    100      *     threw a SkipPageException.
    101      * @throws java.io.IOException If there was an error writing to the
    102      *     output stream.
    103      */
    104     public void doTag()
    105         throws javax.servlet.jsp.JspException, java.io.IOException;
    106
    107     /**
    108      * Sets the parent of this tag, for collaboration purposes.
    109      * <p>
    110      * The container invokes this method only if this tag invocation is
    111      * nested within another tag invocation.
    112      *
    113      * @param parent the tag that encloses this tag
    114      */
    115     public void setParent( JspTag parent );
    116
    117     /**
    118      * Returns the parent of this tag, for collaboration purposes.
    119      *
    120      * @return the parent of this tag
    121      */
    122     public JspTag getParent();
    123
    124     /**
    125      * Called by the container to provide this tag handler with
    126      * the <code>JspContext</code> for this invocation.
    127      * An implementation should save this value.
    128      *
    129      * @param pc the page context for this invocation
    130      * @see Tag#setPageContext
    131      */
    132     public void setJspContext( JspContext pc );
    133
    134     /**
    135      * Provides the body of this tag as a JspFragment object, able to be
    136      * invoked zero or more times by the tag handler.
    137      * <p>
    138      * This method is invoked by the JSP page implementation
    139      * object prior to <code>doTag()</code>.  If the action element is
    140      * empty in the page, this method is not called at all.
    141      *
    142      * @param jspBody The fragment encapsulating the body of this tag.
    143      */
    144     public void setJspBody( JspFragment jspBody );
    145
    146
    147 }