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
015import java.lang.reflect.Method;
016
017/**
018 * A representation of the invocation of a method that allows the behavior of the method to be advised: either by
019 * changing parameter values, or by changing the return value, or by catch or throwing different exceptions. Provides
020 * access to annotations on the advised method.
021 * 
022 * @see MethodAdvice
023 */
024public interface MethodInvocation extends MethodInvocationResult, AnnotationAccess
025{
026    /** The instance on which the method was originally invoked. */
027    Object getInstance();
028
029    InstanceContext getInstanceContext();
030
031    /**
032     * Proceed with the method invocation, either chaining into the next {@link MethodAdvice} added to the method, or
033     * ultimately into the actual method implementation. The method may throw a checked exception, which will be caught
034     * and be reported as {@link #didThrowCheckedException()}.
035     * 
036     * @return this method invocation, for a fluent API
037     */
038    MethodInvocation proceed();
039
040    /**
041     * Overrides the return value of the method. The value provided will be cast to the actual return type
042     * (or, if the return type is a primitive value, the value will be cast to the corresponding wrapper type and then
043     * converted to a primitive).
044     *
045     * Overriding the return value clears any checked exception.
046     * 
047     * @param returnValue
048     * @return this method invocation, for a fluent API
049     * @throws NullPointerException
050     *             if the method's return type is a primitive and null is provided
051     */
052    MethodInvocation setReturnValue(Object returnValue);
053
054    /**
055     * Returns the parameter at the given index. Primitive types will be wrapped as they are returned.
056     * 
057     * @param index
058     *            of parameter to access
059     * @return parameter value
060     */
061    Object getParameter(int index);
062
063    /**
064     * Changes a parameter value. The value will be cast to the parameter's type. For primitive types, the
065     * value will be cast to the corresponding wrapper type.
066     * 
067     * @param index
068     *            index of parameter to modify
069     * @param newValue
070     *            new value for parameter
071     * @return this method invocation, for a fluent API
072     */
073    MethodInvocation setParameter(int index, Object newValue);
074
075    /**
076     * Sets the checked exception; this can be used to indicate failure for the method, or
077     * to cancel the thrown exception (by setting the exception to null).
078     * 
079     * @param exception
080     *            new checked exception, or null
081     * @return this method invocation, for a fluent API
082     */
083    MethodInvocation setCheckedException(Exception exception);
084
085    /** Returns the method being invoked. */
086    Method getMethod();
087}