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