001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one
003     * or more contributor license agreements.  See the NOTICE file
004     * distributed with this work for additional information
005     * regarding copyright ownership.  The ASF licenses this file
006     * to you under the Apache License, Version 2.0 (the
007     * "License"); you may not use this file except in compliance
008     * with the License.  You may obtain a copy of the License at
009     *
010     *  http://www.apache.org/licenses/LICENSE-2.0
011     *
012     * Unless required by applicable law or agreed to in writing,
013     * software distributed under the License is distributed on an
014     * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015     * KIND, either express or implied.  See the License for the
016     * specific language governing permissions and limitations
017     * under the License.
018     */
019    
020    //
021    // This source code implements specifications defined by the Java
022    // Community Process. In order to remain compliant with the specification
023    // DO NOT add / change / or delete method signatures!
024    //
025    
026    package javax.servlet.jsp.tagext;
027    
028    
029    
030    /**
031     * The auxiliary interface of a Tag, IterationTag or BodyTag tag
032     * handler that wants additional hooks for managing resources.
033     *
034     * <p>This interface provides two new methods: doCatch(Throwable)
035     * and doFinally().  The prototypical invocation is as follows:
036     *
037     * <pre>
038     * h = get a Tag();  // get a tag handler, perhaps from pool
039     *
040     * h.setPageContext(pc);  // initialize as desired
041     * h.setParent(null);
042     * h.setFoo("foo");
043     * 
044     * // tag invocation protocol; see Tag.java
045     * try {
046     *   doStartTag()...
047     *   ....
048     *   doEndTag()...
049     * } catch (Throwable t) {
050     *   // react to exceptional condition
051     *   h.doCatch(t);
052     * } finally {
053     *   // restore data invariants and release per-invocation resources
054     *   h.doFinally();
055     * }
056     * 
057     * ... other invocations perhaps with some new setters
058     * ...
059     * h.release();  // release long-term resources
060     * </pre>
061     */
062    
063    public interface TryCatchFinally {
064    
065        /**
066         * Invoked if a Throwable occurs while evaluating the BODY
067         * inside a tag or in any of the following methods:
068         * Tag.doStartTag(), Tag.doEndTag(),
069         * IterationTag.doAfterBody() and BodyTag.doInitBody().
070         *
071         * <p>This method is not invoked if the Throwable occurs during
072         * one of the setter methods.
073         *
074         * <p>This method may throw an exception (the same or a new one)
075         * that will be propagated further up the nest chain.  If an exception
076         * is thrown, doFinally() will be invoked.
077         *
078         * <p>This method is intended to be used to respond to an exceptional
079         * condition.
080         *
081         * @param t The throwable exception navigating through this tag.
082         * @throws Throwable if the exception is to be rethrown further up 
083         *     the nest chain.
084         */
085     
086        void doCatch(Throwable t) throws Throwable;
087    
088        /**
089         * Invoked in all cases after doEndTag() for any class implementing
090         * Tag, IterationTag or BodyTag.  This method is invoked even if
091         * an exception has occurred in the BODY of the tag,
092         * or in any of the following methods:
093         * Tag.doStartTag(), Tag.doEndTag(),
094         * IterationTag.doAfterBody() and BodyTag.doInitBody().
095         *
096         * <p>This method is not invoked if the Throwable occurs during
097         * one of the setter methods.
098         *
099         * <p>This method should not throw an Exception.
100         *
101         * <p>This method is intended to maintain per-invocation data
102         * integrity and resource management actions.
103         */
104    
105        void doFinally();
106    }