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 }