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    
015    package org.apache.tapestry5.plastic;
016    
017    /**
018     * MethodAdvice is a special callback that is threaded into the implementation of a method.
019     * The advice recieves a {@link MethodInvocation}, which gives the advice the ability to change
020     * parameters or return values or thrown exceptions. In many cases, new behavior is added around the method invocation
021     * with affecting it; common examples include logging, null checks, transaction management, or security checks.
022     */
023    public interface MethodAdvice
024    {
025        /**
026         * Advise the method, usually invoking {@link MethodInvocation#proceed()} at some point.
027         * The advice is free to inspect and even replace parameters. Most
028         * Aspects will then invoke {@link MethodInvocation#proceed()}. The advice may then inspect and
029         * replace any checked thrown exceptions. Some advice (for example, caching) may selectively decide to bypass the
030         * invocation entirely, and instead invoke some other method or otherwise set a return value or thrown exception.
031         * 
032         * @param invocation
033         *            identifies the method being invoked, including parameters
034         */
035        void advise(MethodInvocation invocation);
036    }