    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 java.lang.reflect.Method;
    013
    014    /**
    015     * Produces pointcuts.
    016     *
    017     * @author Stephen Molitor
    018     * @version $Revision: 3144 $
    019     */
    020    public interface PointcutsFactory {
    021
    022        /**
    023         * Returns a component pointcut that picks one component key.
    024         *
    025         * @param componentKey the component key to match against.
    026         * @return a <code>ComponentPointcut</code> that matches
    027         *         <code>componentKey</code>.
    028         */
    029        ComponentPointcut component(Object componentKey);
    030
    031        /**
    032         * Returns a component pointcut that matches component keys with a regular
    033         * expression. The regular expression must be an <a
    034         * href="http://jakarta.apache.org/oro/index.html">ORO </a> Perl5 compatible
    035         * regular expression.
    036         *
    037         * @param regex the regular expression to match against.
    038         * @return a <code>ComponentPointcut</code> that matches the component key
    039         *         against <code>regex</code>.
    040         * @throws MalformedRegularExpressionException
    041         *          if the regular expression is
    042         *          invalid.
    043         */
    044        ComponentPointcut componentName(String regex) throws MalformedRegularExpressionException;
    045
    046        /**
    047         * Returns a class pointcut that picks all classes.
    048         *
    049         * @return a <code>ClassPointcut</code> that matches all classes.
    050         */
    051        ClassPointcut allClasses();
    052
    053        /**
    054         * Returns a class pointcut that picks all instances of a given type.
    055         *
    056         * @param type the base interface or class.
    057         * @return a <code>ClassPointcut</code> that matches instances of
    058         *         <code>type</code>.
    059         */
    060        ClassPointcut instancesOf(Class type);
    061
    062        /**
    063         * Returns a class pointcut that matches class names with a regular
    064         * expression. The regular expression must be an <a
    065         * href="http://jakarta.apache.org/oro/index.html">ORO </a> Perl5 regular
    066         * expression.
    067         *
    068         * @param regex the regular expression to match against.
    069         * @return a <code>ClassPointcut</code> that matches the class name
    070         *         against <code>regex</code>.
    071         * @throws org.nanocontainer.aop.MalformedRegularExpressionException
    072         *          if the regular expression is
    073         *          invalid.
    074         */
    075        ClassPointcut className(String regex) throws MalformedRegularExpressionException;
    076
    077        /**
    078         * Returns a class pointcut that picks one class.
    079         *
    080         * @param clazz the class to match against.
    081         * @return a <code>ClassPointcut</code> that matches <code>clazz</code>.
    082         */
    083        ClassPointcut oneClass(Class clazz);
    084
    085        /**
    086         * Returns a class pointcut that picks all classes in a package. Note that
    087         * the <code>packageName</code> argument is not a regular expression; the
    088         * returned pointcut expects an exact match against the package name.
    089         *
    090         * @param packageName the package name to match against the package of the
    091         *                    candidate component's class.
    092         * @return a <code>ClassPointcut</code> that matches the class package
    093         *         with <code>packageName</code>.
    094         */
    095        ClassPointcut packageName(String packageName);
    096
    097        /**
    098         * Returns a class pointcut that is the intersection of two class pointcuts.
    099         *
    100         * @param a the first <code>ClassPointcut</code>.
    101         * @param b the second <code>ClassPointcut</code>.
    102         * @return a <code>ClassPointcut</code> that is the intersection of
    103         *         <code>a</code> and <code>b</code>.
    104         */
    105        ClassPointcut intersection(ClassPointcut a, ClassPointcut b);
    106
    107        /**
    108         * Returns a pointcut that is the union of two class pointcuts.
    109         *
    110         * @param a the first <code>ClassPointcut</code>.
    111         * @param b the second <code>ClassPointcut</code>.
    112         * @return a <code>ClassPointcut</code> that is the union of
    113         *         <code>a</code> and <code>b</code>.
    114         */
    115        ClassPointcut union(ClassPointcut a, ClassPointcut b);
    116
    117        /**
    118         * Returns a class pointcut that inverts the original pointcut.
    119         *
    120         * @param classPointcut the pointcut to negate.
    121         * @return a <code>ClassPointcut</code> that inverts
    122         *         <code>classPointcut</code>.
    123         */
    124        ClassPointcut not(ClassPointcut classPointcut);
    125
    126        /**
    127         * Returns a pointcut that matches all methods.
    128         *
    129         * @return a <code>MethodPointcut</code> that matches all methods.
    130         */
    131        MethodPointcut allMethods();
    132
    133        /**
    134         * Returns a pointcut that matches get methods. Note that this does not
    135         * include 'is' methods.
    136         *
    137         * @return a <code>MethodPointcut</code> that matches get methods.
    138         */
    139        MethodPointcut getMethods();
    140
    141        /**
    142         * Returns a pointcut that matches is methods.
    143         *
    144         * @return a <code>MethodPointcut</code> that matches is methods.
    145         */
    146        MethodPointcut isMethods();
    147
    148        /**
    149         * Returns a method pointcut that matches set methods.
    150         *
    151         * @return a <code>MethodPointcut</code> that matches set methods.
    152         */
    153        MethodPointcut setMethods();
    154
    155        /**
    156         * Returns a method pointcut that picks <code>equals</code>,
    157         * <code>hashCode</code>, and <code>toString</code>.
    158         *
    159         * @return a <code>MethodPointcut</code> that matches methods declared by
    160         *         <code>java.lang.Object</code>.
    161         */
    162        MethodPointcut objectMethods();
    163
    164        /**
    165         * Returns a method pointcut that matches the method signatures with a
    166         * regular expression. Uses dynaop's signature pointcut. Method signatures
    167         * follow this pattern:
    168         * <p/>
    169         * <pre>
    170         * <p/>
    171         * <p/>
    172         * <p/>
    173         * <p/>
    174         *         ReturnType methodName(ArgumentType, ArgumentType, ...)
    175         *             throws ExceptionType, ExceptionType
    176         * <p/>
    177         * <p/>
    178         * <p/>
    179         * <p/>
    180         * </pre>
    181         * <p/>
    182         * Omits "java.lang." from classes in java.lang package. The regular
    183         * expression must be an <a
    184         * href="http://jakarta.apache.org/oro/index.html">ORO </a> Perl5 regular
    185         * expression.
    186         *
    187         * @param regexp the method signature regular expression.
    188         * @return a <code>MethodPointcut</code> that matches the method signature
    189         *         against a regular expression.
    190         */
    191        MethodPointcut signature(String regexp);
    192
    193        /**
    194         * Returns a pointcut that matches one method.
    195         *
    196         * @param method the method to match against.
    197         * @return a <code>MethodPointcut</code> that matches one method.
    198         */
    199        MethodPointcut oneMethod(Method method);
    200
    201        /**
    202         * Returns a method pointcut that picks a method if the given class pointcut
    203         * picks the method's return type.
    204         *
    205         * @param classPointcut the class pointcut to match against the method's
    206         *                      return type.
    207         * @return a <code>MethodPointcut</code> that matches
    208         *         <code>classPointcut</code> against the method's return type
    209         */
    210        MethodPointcut returnType(ClassPointcut classPointcut);
    211
    212        /**
    213         * Returns a method pointcut that picks a method if the given class pointcut
    214         * picks the method's declaring class.
    215         *
    216         * @param classPointcut the class pointcut to match against the method's
    217         *                      declaring class.
    218         * @return a <code>MethodPointcut</code> that matches
    219         *         <code>classPointcut</code> against the method's declaring
    220         *         class.
    221         */
    222        MethodPointcut declaringClass(ClassPointcut classPointcut);
    223
    224        /**
    225         * Picks methods that are members of the given class (even if the method was
    226         * declared in a super class of the given class).
    227         *
    228         * @param clazz the class that we will check to see if the method is a
    229         *              member of.
    230         * @return a <code>MethodPointcut</code> that will check to see if the
    231         *         method is a member of <code>clazz</code>.
    232         */
    233        MethodPointcut membersOf(Class clazz);
    234
    235        /**
    236         * Returns a method pointcut that is the intersection of two other method
    237         * pointcuts.
    238         *
    239         * @param a the first method pointcut.
    240         * @param b the second method pointcut.
    241         * @return a <code>MethodPointcut</code> that is the intersection of
    242         *         <code>a</code> and <code>b</code>.
    243         */
    244        MethodPointcut intersection(MethodPointcut a, MethodPointcut b);
    245
    246        /**
    247         * Returns a method pointcut that is the union of two other method
    248         * pointcuts.
    249         *
    250         * @param a the first method pointcut.
    251         * @param b the second method pointcut.
    252         * @return a <code>MethodPointcut</code> that is the union of
    253         *         <code>a</code> and <code>b</code>.
    254         */
    255        MethodPointcut union(MethodPointcut a, MethodPointcut b);
    256
    257        /**
    258         * Creates a method pointcut that inverts the original pointcut.
    259         *
    260         * @param methodPointcut the pointcut to negate.
    261         * @return a new <code>MethodPointcut</code> that inverts
    262         *         <code>methodPointcut</code>.
    263         */
    264        MethodPointcut not(MethodPointcut methodPointcut);
    265
    266    }