    001// Licensed under the Apache License, Version 2.0 (the "License");
    002// you may not use this file except in compliance with the License.
    003// You may obtain a copy of the License at
    004//
    005// http://www.apache.org/licenses/LICENSE-2.0
    006//
    007// Unless required by applicable law or agreed to in writing, software
    008// distributed under the License is distributed on an "AS IS" BASIS,
    009// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    010// See the License for the specific language governing permissions and
    011// limitations under the License.
    012
    013package org.apache.tapestry5.plastic;
    014
    015/**
    016 * Allows a portion of a method to be marked so that exception and finally handlers can be provided.
    017 *
    018 * @see InstructionBuilder#startTryCatch(TryCatchCallback)
    019 */
    020public interface TryCatchBlock
    021{
    022    /**
    023     * Invoked first, to generate the code in which exceptions may be caught.
    024     */
    025    void addTry(InstructionBuilderCallback callback);
    026
    027    /**
    028     * Ends the block (if not already ended) and inserts a catch block for the named exception.
    029     * The InstructionBuilder is returned so that the code for handling the exception can be added. The exception object
    030     * will be on top of the stack. This should be called after {@link #addTry(InstructionBuilderCallback)}.
    031     *
    032     * Note: no attempt is made currently to sort the handlers; for example adding a catch for java.lang.Exception first
    033     * will mean that more specific exception handlers added later will never be invoked.
    034     *
    035     * @param exceptionClassName
    036     *            caught exception class
    037     * @param callback
    038     *            that implements the logic of the catch block
    039     */
    040    @Opcodes("TRYCATCHBLOCK")
    041    void addCatch(String exceptionClassName, InstructionBuilderCallback callback);
    042
    043    /**
    044     * As with {@link #addCatch(String, InstructionBuilderCallback)}, but the exception caught is
    045     * null, which acts as a finally block in the Java language. This must be called last (after
    046     * {@link #addTry(InstructionBuilderCallback)} and any calls to
    047     * {@link #addCatch(String, InstructionBuilderCallback)}.
    048     *
    049     * @param callback
    050     *            implements the logic of the finally block
    051     */
    052    @Opcodes("TRYCATCHBLOCK")
    053    void addFinally(InstructionBuilderCallback callback);
    054}