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