    001    // Copyright 2010, 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
    015    package org.apache.tapestry5.services;
    016
    017    import java.lang.annotation.Annotation;
    018
    019    import org.apache.tapestry5.ioc.AnnotationProvider;
    020
    021    /**
    022     * A method defined by (or created within) a {@link ClassTransformation}, allowing
    023     * for access and manipulation of the method.
    024     * <p>
    025     * The natural sorting order of TransformMethods is the same as {@link TransformMethodSignature}.
    026     *
    027     * @since 5.2.0
    028     */
    029    public interface TransformMethod extends AnnotationProvider, Comparable<TransformMethod>
    030    {
    031        /**
    032         * @return the signature for the method, defining name, visibility, return type, parameter types and thrown
    033         *         exceptions
    034         */
    035        TransformMethodSignature getSignature();
    036
    037        /** Returns just the name of the method. */
    038        String getName();
    039
    040        /**
    041         * Returns an object that can be used to invoke the method on an instance of the component class (regardless
    042         * of the actual visibility of the method).
    043         */
    044        MethodAccess getAccess();
    045
    046        /**
    047         * Add advice for the method; the advice will be threaded into method invocations of the indicated method.
    048         * A method may be given multiple advice; each advice will receive control in turn (assuming
    049         * the previous advice invokes {@link ComponentMethodInvocation#proceed()}) in the order the advice
    050         * is added. The last advice will proceed to the original method implementation.
    051         *
    052         * @param advice
    053         *            to receive control when the method is invoked
    054         * @see #addOperationAfter(ComponentInstanceOperation)
    055         * @see #addOperationBefore(ComponentInstanceOperation)
    056         */
    057        void addAdvice(ComponentMethodAdvice advice);
    058
    059        /**
    060         * Adds an operation that will execute before any
    061         * further advice or operations. This is converted into
    062         * advice that invokes the operation, then invokes {@link ComponentMethodInvocation#proceed()}.
    063         */
    064        void addOperationBefore(ComponentInstanceOperation operation);
    065
    066        /**
    067         * Adds an operation that will execute after any
    068         * further advice or operations. This is converted into
    069         * advice that invokes {@link ComponentMethodInvocation#proceed()} before invoking the operation.
    070         */
    071        void addOperationAfter(ComponentInstanceOperation operation);
    072
    073        /**
    074         * Converts a signature to a string used to identify the method; this consists of the
    075         * {@link TransformMethodSignature#getMediumDescription()} appended with source file information
    076         * and line number
    077         * information (when available).
    078         *
    079         * @return a string that identifies the class, method name, types of parameters, source file and
    080         *         source line number
    081         */
    082        String getMethodIdentifier();
    083
    084        /**
    085         * Returns true if the method is an override of a method from the parent class.
    086         *
    087         * @return true if the parent class contains a method with the name signature
    088         */
    089        boolean isOverride();
    090
    091        /**
    092         * Gets an annotation on a parameter of the method.
    093         *
    094         * @param index
    095         *            index of parameter
    096         * @param annotationType
    097         *            type of annotation to check for
    098         * @return the annotation, if found, or null
    099         */
    100        <A extends Annotation> A getParameterAnnotation(int index, Class<A> annotationType);
    101    }