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