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