01 /*
02 * Copyright 2004 The Apache Software Foundation
03 *
04 * Licensed under the Apache License, Version 2.0 (the "License");
05 * you may not use this file except in compliance with the License.
06 * You may obtain a copy of the License at
07 *
08 * http://www.apache.org/licenses/LICENSE-2.0
09 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17 package javax.servlet.jsp.tagext;
18
19 /**
20 * The auxiliary interface of a Tag, IterationTag or BodyTag tag
21 * handler that wants additional hooks for managing resources.
22 *
23 * <p>This interface provides two new methods: doCatch(Throwable)
24 * and doFinally(). The prototypical invocation is as follows:
25 *
26 * <pre>
27 * h = get a Tag(); // get a tag handler, perhaps from pool
28 *
29 * h.setPageContext(pc); // initialize as desired
30 * h.setParent(null);
31 * h.setFoo("foo");
32 *
33 * // tag invocation protocol; see Tag.java
34 * try {
35 * doStartTag()...
36 * ....
37 * doEndTag()...
38 * } catch (Throwable t) {
39 * // react to exceptional condition
40 * h.doCatch(t);
41 * } finally {
42 * // restore data invariants and release per-invocation resources
43 * h.doFinally();
44 * }
45 *
46 * ... other invocations perhaps with some new setters
47 * ...
48 * h.release(); // release long-term resources
49 * </pre>
50 */
51
52 public interface TryCatchFinally {
53
54 /**
55 * Invoked if a Throwable occurs while evaluating the BODY
56 * inside a tag or in any of the following methods:
57 * Tag.doStartTag(), Tag.doEndTag(),
58 * IterationTag.doAfterBody() and BodyTag.doInitBody().
59 *
60 * <p>This method is not invoked if the Throwable occurs during
61 * one of the setter methods.
62 *
63 * <p>This method may throw an exception (the same or a new one)
64 * that will be propagated further up the nest chain. If an exception
65 * is thrown, doFinally() will be invoked.
66 *
67 * <p>This method is intended to be used to respond to an exceptional
68 * condition.
69 *
70 * @param t The throwable exception navigating through this tag.
71 * @throws Throwable if the exception is to be rethrown further up
72 * the nest chain.
73 */
74
75 void doCatch(Throwable t) throws Throwable;
76
77 /**
78 * Invoked in all cases after doEndTag() for any class implementing
79 * Tag, IterationTag or BodyTag. This method is invoked even if
80 * an exception has occurred in the BODY of the tag,
81 * or in any of the following methods:
82 * Tag.doStartTag(), Tag.doEndTag(),
83 * IterationTag.doAfterBody() and BodyTag.doInitBody().
84 *
85 * <p>This method is not invoked if the Throwable occurs during
86 * one of the setter methods.
87 *
88 * <p>This method should not throw an Exception.
89 *
90 * <p>This method is intended to maintain per-invocation data
91 * integrity and resource management actions.
92 */
93
94 void doFinally();
95 }
|