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    }