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 }