    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    }