    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}