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 java.io.IOException;
    27  import java.io.Writer;
    28
    29  import javax.servlet.jsp.JspContext;
    30  import javax.servlet.jsp.JspException;
    31
    32  /**
    33   * Encapsulates a portion of JSP code in an object that
    34   * can be invoked as many times as needed.  JSP Fragments are defined
    35   * using JSP syntax as the body of a tag for an invocation to a SimpleTag
    36   * handler, or as the body of a &lt;jsp:attribute&gt; standard action
    37   * specifying the value of an attribute that is declared as a fragment,
    38   * or to be of type JspFragment in the TLD.
    39   * <p>
    40   * The definition of the JSP fragment must only contain template
    41   * text and JSP action elements.  In other words, it must not contain
    42   * scriptlets or scriptlet expressions.  At translation time, the
    43   * container generates an implementation of the JspFragment abstract class
    44   * capable of executing the defined fragment.
    45   * <p>
    46   * A tag handler can invoke the fragment zero or more times, or
    47   * pass it along to other tags, before returning.  To communicate values
    48   * to/from a JSP fragment, tag handlers store/retrieve values in
    49   * the JspContext associated with the fragment.
    50   * <p>
    51   * Note that tag library developers and page authors should not generate
    52   * JspFragment implementations manually.
    53   * <p>
    54   * <i>Implementation Note</i>: It is not necessary to generate a
    55   * separate class for each fragment.  One possible implementation is
    56   * to generate a single helper class for each page that implements
    57   * JspFragment. Upon construction, a discriminator can be passed to
    58   * select which fragment that instance will execute.
    59   *
    60   * @since 2.0
    61   */
    62  public abstract class JspFragment {
    63
    64      /**
    65       * Executes the fragment and directs all output to the given Writer,
    66       * or the JspWriter returned by the getOut() method of the JspContext
    67       * associated with the fragment if out is null.
    68       *
    69       * @param out The Writer to output the fragment to, or null if
    70       *     output should be sent to JspContext.getOut().
    71       * @throws javax.servlet.jsp.JspException Thrown if an error occured
    72       *     while invoking this fragment.
    73       * @throws javax.servlet.jsp.SkipPageException Thrown if the page
    74       *     that (either directly or indirectly) invoked the tag handler that
    75       *     invoked this fragment is to cease evaluation.  The container
    76       *     must throw this exception if a Classic Tag EventHandler returned
    77       *     Tag.SKIP_PAGE or if a Simple Tag EventHandler threw SkipPageException.
    78       * @throws java.io.IOException If there was an error writing to the
    79       *     stream.
    80       */
    81      public abstract void invoke( Writer out )
    82          throws JspException, IOException;
    83
    84      /**
    85       * Returns the JspContext that is bound to this JspFragment.
    86       *
    87       * @return The JspContext used by this fragment at invocation time.
    88       */
    89      public abstract JspContext getJspContext();
    90
    91  }