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
    27
    28  /**
    29   * The auxiliary interface of a Tag, IterationTag or BodyTag tag
    30   * handler that wants additional hooks for managing resources.
    31   *
    32   * <p>This interface provides two new methods: doCatch(Throwable)
    33   * and doFinally().  The prototypical invocation is as follows:
    34   *
    35   * <pre>
    36   * h = get a Tag();  // get a tag handler, perhaps from pool
    37   *
    38   * h.setPageContext(pc);  // initialize as desired
    39   * h.setParent(null);
    40   * h.setFoo("foo");
    41   *
    42   * // tag invocation protocol; see Tag.java
    43   * try {
    44   *   doStartTag()...
    45   *   ....
    46   *   doEndTag()...
    47   * } catch (Throwable t) {
    48   *   // react to exceptional condition
    49   *   h.doCatch(t);
    50   * } finally {
    51   *   // restore data invariants and release per-invocation resources
    52   *   h.doFinally();
    53   * }
    54   *
    55   * ... other invocations perhaps with some new setters
    56   * ...
    57   * h.release();  // release long-term resources
    58   * </pre>
    59   */
    60
    61  public interface TryCatchFinally {
    62
    63      /**
    64       * Invoked if a Throwable occurs while evaluating the BODY
    65       * inside a tag or in any of the following methods:
    66       * Tag.doStartTag(), Tag.doEndTag(),
    67       * IterationTag.doAfterBody() and BodyTag.doInitBody().
    68       *
    69       * <p>This method is not invoked if the Throwable occurs during
    70       * one of the setter methods.
    71       *
    72       * <p>This method may throw an exception (the same or a new one)
    73       * that will be propagated further up the nest chain.  If an exception
    74       * is thrown, doFinally() will be invoked.
    75       *
    76       * <p>This method is intended to be used to respond to an exceptional
    77       * condition.
    78       *
    79       * @param t The throwable exception navigating through this tag.
    80       * @throws Throwable if the exception is to be rethrown further up
    81       *     the nest chain.
    82       */
    83
    84      void doCatch(Throwable t) throws Throwable;
    85
    86      /**
    87       * Invoked in all cases after doEndTag() for any class implementing
    88       * Tag, IterationTag or BodyTag.  This method is invoked even if
    89       * an exception has occurred in the BODY of the tag,
    90       * or in any of the following methods:
    91       * Tag.doStartTag(), Tag.doEndTag(),
    92       * IterationTag.doAfterBody() and BodyTag.doInitBody().
    93       *
    94       * <p>This method is not invoked if the Throwable occurs during
    95       * one of the setter methods.
    96       *
    97       * <p>This method should not throw an Exception.
    98       *
    99       * <p>This method is intended to maintain per-invocation data
    100      * integrity and resource management actions.
    101      */
    102
    103     void doFinally();
    104 }