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