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 }