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    package org.apache.geronimo.interceptor;
019    
020    /**
021     * The result of an Invocation.
022     * There are two types of result:
023     * <ul>
024     * <li>normal - indicating the operation completed normally (e.g. the method returned)</li>
025     * <li>exception - indicating the operation completed abnormally (e.g. the method threw a checked exception)</li>
026     * </ul>
027     * <p>Note that these should both be considered a normal completion of the operation by the container. Abnormal
028     * completions, such as a RuntimeException or Error from the invocation, or any problem in the interceptor
029     * chain itself, should result in a Throwable being thrown up the chain rather than being contained in this
030     * result.</p>
031     * <p>This distinction mirrors the semantics for EJB invocations, where a business method is considered to have
032     * completed successfuly even if it throws declared Exception - the Exception there is indicating a business level
033     * issue and not a system problem.</p>
034     *
035     * @version $Rev: 476049 $ $Date: 2006-11-16 23:35:17 -0500 (Thu, 16 Nov 2006) $
036     */
037    public interface InvocationResult {
038        /**
039         * Was this a normal completion (return)?
040         * @return true if the invocation returned; false if a declared exception was thrown
041         */
042        boolean isNormal();
043    
044        /**
045         * Get the return value from the invocation.
046         * It is an error to call this method if the invocation is not complete normally.
047         * @return the return value from the invocation; null if the operation was void
048         */
049        Object getResult();
050    
051        /**
052         * Was an application exception raised by the invocation?
053         * Note, this indicates a checked application exception was thrown; this will never contain
054         * a system exception
055         * @return true if a declared exception was thrown; false if the invocation returned
056         */
057        boolean isException();
058    
059        /**
060         * Get the application exception raised by the invocation.
061         * It is an error to call this method if the invocation did not raise an exception
062         * @return the checked Exception raised by the application
063         */
064        Exception getException();
065    }