001    // Copyright 2008 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.ioc.services;
016    
017    import org.apache.tapestry5.ioc.MethodAdvice;
018    
019    /**
020     * A decorator used to create an interceptor that delegates each method's invocation to an {@link
021     * org.apache.tapestry5.ioc.MethodAdvice} for advice.  Advice can inspect or change method parameters, inspect or change
022     * the method's return value, and inspect and change thrown exceptions (checked and unchecked).
023     */
024    public interface AspectDecorator
025    {
026        /**
027         * Intercepts method invocations on the delegate and passes them through the provided aspect. Note that the advice
028         * <em>must</em> be thread-safe.
029         *
030         * @param serviceInterface defines the interface of the interceptor and delegate
031         * @param delegate         the object on which methods will be invoked
032         * @param advice           intercepts the method invocations on the delegate
033         * @param description      used as the toString() of the returned interceptor, unless toString() is part of the
034         *                         service interface
035         * @return the interceptor, wrapping the delegate with all the advice
036         */
037        <T> T build(Class<T> serviceInterface, T delegate, MethodAdvice advice, String description);
038    
039        /**
040         * Creates a builder that can be used to create the interceptor.  This is used when only some of the methods need to
041         * be advised, or when different methods need to recieve different advice, or when multiple advice is to be
042         * applied.
043         *
044         * @param serviceInterface defines the interface of the interceptor and the delegate
045         * @param delegate         the object on which methods will be invokes
046         * @param description      used as the toString() of the interceptor unless toString() is part of the service
047         *                         interface
048         * @return a builder that can be used to generate the final interceptor
049         */
050        <T> AspectInterceptorBuilder<T> createBuilder(Class<T> serviceInterface, T delegate, String description);
051    }