jakarta.servlet.jsp.tagext.TryCatchFinally Maven / Gradle / Ivy
/*
* Copyright (c) 1997, 2020 Oracle and/or its affiliates and others.
* All rights reserved.
* Copyright 2004 The Apache Software Foundation
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
package jakarta.servlet.jsp.tagext;
/**
* The auxiliary interface of a Tag, IterationTag or BodyTag tag handler that wants additional hooks for managing
* resources.
*
*
* This interface provides two new methods: doCatch(Throwable) and doFinally(). The prototypical invocation is as
* follows:
*
*
* h = get a Tag(); // get a tag handler, perhaps from pool
*
* h.setPageContext(pc); // initialize as desired
* h.setParent(null);
* h.setFoo("foo");
*
* // tag invocation protocol; see Tag.java
* try {
* doStartTag()...
* ....
* doEndTag()...
* } catch (Throwable t) {
* // react to exceptional condition
* h.doCatch(t);
* } finally {
* // restore data invariants and release per-invocation resources
* h.doFinally();
* }
*
* ... other invocations perhaps with some new setters
* ...
* h.release(); // release long-term resources
*
*/
public interface TryCatchFinally {
/**
* Invoked if a Throwable occurs while evaluating the BODY inside a tag or in any of the following methods:
* Tag.doStartTag(), Tag.doEndTag(), IterationTag.doAfterBody() and BodyTag.doInitBody().
*
*
* This method is not invoked if the Throwable occurs during one of the setter methods.
*
*
* This method may throw an exception (the same or a new one) that will be propagated further up the nest chain. If
* an exception is thrown, doFinally() will be invoked.
*
*
* This method is intended to be used to respond to an exceptional condition.
*
* @param t The throwable exception navigating through this tag.
* @throws Throwable if the exception is to be rethrown further up the nest chain.
*/
void doCatch(Throwable t) throws Throwable;
/**
* Invoked in all cases after doEndTag() for any class implementing Tag, IterationTag or BodyTag. This method is
* invoked even if an exception has occurred in the BODY of the tag, or in any of the following methods:
* Tag.doStartTag(), Tag.doEndTag(), IterationTag.doAfterBody() and BodyTag.doInitBody().
*
*
* This method is not invoked if the Throwable occurs during one of the setter methods.
*
*
* This method should not throw an Exception.
*
*
* This method is intended to maintain per-invocation data integrity and resource management actions.
*/
void doFinally();
}