001    /*****************************************************************************
002     * Copyright (c) PicoContainer Organization. All rights reserved.            *
003     * ------------------------------------------------------------------------- *
004     * The software in this package is published under the terms of the BSD      *
005     * style license a copy of which has been included with this distribution in *
006     * the LICENSE.txt file.                                                     *
007     *                                                                           *
008     * Idea by Rachel Davies, Original code by various                           *
009     *****************************************************************************/
010    package org.nanocontainer.aop;
011    
012    import org.aopalliance.intercept.MethodInterceptor;
013    
014    /**
015     * Represents the collection of aspects (pointuts + advice) to be applied to a
016     * Pico container. Provides methods for registering mixin and interceptor
017     * advice. Advice can be applied to all components in the container that match a
018     * pointcut, or advice can be applied to just one component. Advice objects may
019     * themselves be components in the container, with dependencies on other
020     * components.
021     *
022     * @author Stephen Molitor
023     * @version $Revision: 3144 $
024     */
025    public interface AspectsContainer {
026    
027        /**
028         * Registers container scoped interceptor advice. The advice will be applied
029         * to all components in the container whose class satisfies the
030         * <code>classPointcut</code>. The interceptor will only intercept
031         * methods that match the <code>methodPointcut</code>.
032         *
033         * @param classPointcut  classes to apply the interceptor to.
034         * @param methodPointcut methods to apply the interceptor to.
035         * @param interceptor    the interceptor advice object.
036         */
037        void registerInterceptor(ClassPointcut classPointcut, MethodPointcut methodPointcut, MethodInterceptor interceptor);
038    
039        /**
040         * Registers component scoped interceptor advice. The advice will be applied
041         * to all components in the container whose key satisfies
042         * <code>componentPointcut</code>. The interceptor will only intercept
043         * methods that match the <code>methodPointcut</code>.
044         *
045         * @param componentPointcut components to apply the interceptor to.
046         * @param methodPointcut    methods to apply the interceptor to.
047         * @param interceptor       the interceptor advice object.
048         */
049        void registerInterceptor(ComponentPointcut componentPointcut, MethodPointcut methodPointcut,
050                                 MethodInterceptor interceptor);
051    
052        /**
053         * Registers container supplied container scoped interceptor advice. The
054         * interceptor advice object itself is a component in the container,
055         * specified by <code>interceptorComponentKey</code>. The advice will be
056         * applied to all components in the container whose class satisfies the
057         * <code>classPointcut</code>. The interceptor will only intercept
058         * methods that match the <code>methodPointcut</code>.
059         *
060         * @param classPointcut           classes to apply the interceptor to.
061         * @param methodPointcut          methods to apply the interceptor to.
062         * @param interceptorComponentKey the interceptor component key.
063         */
064        void registerInterceptor(ClassPointcut classPointcut, MethodPointcut methodPointcut, Object interceptorComponentKey);
065    
066        /**
067         * Registers component scoped interceptor advice. The interceptor advice
068         * object itself is a component in the container, specified by the
069         * <code>interceptorComponentKey</code>. The advice will be applied to
070         * all components in the container whose key satisfies
071         * <code>componentPointcut</code>. The interceptor will only intercept
072         * methods that match the <code>methodPointcut</code>.
073         *
074         * @param componentPointcut       components to apply the interceptor to.
075         * @param methodPointcut          methods to apply the interceptor to.
076         * @param interceptorComponentKey the interceptor component key.
077         */
078        void registerInterceptor(ComponentPointcut componentPointcut, MethodPointcut methodPointcut,
079                                 Object interceptorComponentKey);
080    
081        /**
082         * Registers container scoped mixin advice. The mixin will be added to all
083         * components in the container whose class satisfies the
084         * <code>classPointcut</code>.
085         * <p/>
086         * If a component of type <code>mixinClass</code> has been registered in
087         * the container, that component will be used as the mixin. Otherwise a new
088         * object of type <code>mixinClass</code> will be instantiated each time
089         * the mixin is applied to a component. Any dependencies the mixin has will
090         * be supplied from components in the container, or, if there are no
091         * dependencies, the default constructor will be invoked to instantiate the
092         * mixin.
093         *
094         * @param classPointcut classes to add mixin to.
095         * @param interfaces    interfaces the mixin implements.
096         * @param mixinClass    the mixin implementation.
097         */
098        void registerMixin(ClassPointcut classPointcut, Class[] interfaces, Class mixinClass);
099    
100        /**
101         * Registers component scoped mixin advice. The mixin will be added to all
102         * components in the container whose key satisfies the
103         * <code>componentPointcut</code>.
104         *
105         * @param componentPointcut classes to add mixin to.
106         * @param interfaces        interfaces the mixin implements.
107         * @param mixinClass        the mixin implementation.
108         * @see AspectsContainer#registerMixin(ClassPointcut, Class[], Class) for
109         *      details on how <code>mixinClass</code> gets instantiated.
110         */
111        void registerMixin(ComponentPointcut componentPointcut, Class[] interfaces, Class mixinClass);
112    
113        /**
114         * Registers container scoped mixin advice. The mixin will be added to all
115         * components in the container whose class satisfies the
116         * <code>classPointcut</code>. Convenience method that uses all
117         * interfaces implemented by the mixin class.
118         *
119         * @param classPointcut classes to add mixin to.
120         * @param mixinClass    the mixin implementation.
121         * @see AspectsContainer#registerMixin(ClassPointcut, Class[], Class) for
122         *      details on how <code>mixinClass</code> gets instantiated.
123         */
124        void registerMixin(ClassPointcut classPointcut, Class mixinClass);
125    
126        /**
127         * Registers component scoped mixin advice. The mixin will be added to all
128         * components in the container whose key satisfies the
129         * <code>componentPointcut</code>. Convenience method that uses all
130         * interfaces implemented by the mixin class.
131         *
132         * @param componentPointcut classes to add mixin to.
133         * @param mixinClass        the mixin implementation.
134         * @see AspectsContainer#registerMixin(ClassPointcut, Class[], Class) for
135         *      details on how <code>mixinClass</code> gets instantiated.
136         */
137        void registerMixin(ComponentPointcut componentPointcut, Class mixinClass);
138    
139        /**
140         * Adds interfaces to classes picked by the class pointcut.
141         * <p/>
142         * This can be handy when you want to add an aggregate helper interface that
143         * extends all the mixin interfaces added, to avoid the need for casting.
144         * Note that the interfaces will <i>not </i> be added if no advice
145         * (interceptor or mixin) has been applied to the component.
146         *
147         * @param classPointcut classes to add interfaces to.
148         * @param interfaces    the interfaces to add.
149         */
150        void registerInterfaces(ClassPointcut classPointcut, Class[] interfaces);
151    
152        /**
153         * Adds interfaces to components picked by the component pointcut.
154         *
155         * @param componentPointcut components to add interfaces to.
156         * @param interfaces        the interfaces to add.
157         * @see AspectsContainer#registerInterfaces(ClassPointcut, Class[]) for
158         *      notes on using this method.
159         */
160        void registerInterfaces(ComponentPointcut componentPointcut, Class[] interfaces);
161    
162        /**
163         * Produces a pointcuts factory that can be used to create pointcuts to be
164         * used in aspects registered with this <code>AspectsContainer</code>.
165         * Note that you are not limited to pointcuts produced by this factory; any
166         * pointcut that implements the appropriate <code>ClassPointcut</code>,
167         * <code>MethodPointcut</code> or <code>ComponentPointcut</code> will
168         * work.
169         *
170         * @return a pointcuts factory.
171         */
172        PointcutsFactory getPointcutsFactory();
173    
174    }