001    // Copyright 2010 The Apache Software Foundation
002    //
003    // Licensed under the Apache License, Version 2.0 (the "License");
004    // you may not use this file except in compliance with the License.
005    // You may obtain a copy of the License at
006    //
007    // http://www.apache.org/licenses/LICENSE-2.0
008    //
009    // Unless required by applicable law or agreed to in writing, software
010    // distributed under the License is distributed on an "AS IS" BASIS,
011    // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
012    // See the License for the specific language governing permissions and
013    // limitations under the License.
014    
015    package org.apache.tapestry5.services;
016    
017    /**
018     * Captures the result of invoking a method.
019     * 
020     * @since 5.2.0
021     */
022    public interface MethodInvocationResult
023    {
024        /**
025         * The return value from the method invocation. This will be null if the method returns null,
026         * is a void method, or if a checked exception was thrown by the method.
027         */
028        Object getReturnValue();
029    
030        /**
031         * If true, then the method invocation ended with a checked exception being thrown.
032         */
033        boolean isFail();
034    
035        /**
036         * If the invocation threw a checked exception, this method will wrap that exception in a
037         * RuntimeException and throw that. For most code that doesn't specifically care about
038         * the thrown exception, this method should be invoked before continuing on to
039         * examine {@link #getReturnValue()}.
040         */
041        void rethrow();
042    
043        /**
044         * If {@link #isFail()} is true, this method provides access to the actual checked exception that was thrown.
045         * 
046         * @param throwableClass
047         *            the type of exception to match
048         * @return the exception, if the method invocation threw a checked exception, and the exception is assignable to
049         *         the provided type. In other cases, null is returned.
050         */
051        <T extends Throwable> T getThrown(Class<T> throwableClass);
052    }