org.objectweb.jac.core
Class MethodPointcut

java.lang.Object
  |
  +--org.objectweb.jac.core.Pointcut
        |
        +--org.objectweb.jac.core.MethodPointcut
All Implemented Interfaces:
Serializable

public class MethodPointcut
extends Pointcut

This class can be used by JAC aspect components to easily define a set of method points on the base program that the aspects will use to modify its behavior.

A method pointcut is defined through four pointcut expressions. For the moment, these pointcut expressions are a simple extension of regular expressions -- in an EMACS_LISP syntax (see the GNU-regexp tutorial) that can be combined with the && operator (in this case all the regexps must match) or the || operator (in this case, only one regexp must match). Before a regexp, you can use the ! (not) operator to inverse the matching.

Depending on the pointcut expression, you can also use keywords that will be dynamically interpreted. We intend to provide a more complete and suited desciption language. Note that for the moment, the tricky cases that cannot be handled by these expressions can be treated by programming the AspectComponent.whenUsingNewInstance method.

For more informations on pointcut expressions, please see the Renaud Pawlak

See Also:
AspectComponent, Serialized Form

Constructor Summary
MethodPointcut(AspectComponent aspectComponent, String wrappeeExpr, String wrappeeClassExpr, String wrappeeMethodExpr, Wrapper initWrapper, String wrappingClassName, String methodName, Object[] methodArgs, String hostExpr, String exceptionHandler, boolean one2one)
          Instantiates a new pointcut with the given characterisitics.
 
Method Summary
 void applyTo(Wrappee wrappee, ClassItem cl)
          Applies this pointcut to the given wrappee.
static gnu.regexp.RE buildRegexp(String pattern)
           
protected  void filterMethodKeywords(Object wrappee, ClassItem cli, String expr, boolean inv, Collection source, Collection dest)
          Adds methods from source that match an expression to a collection
static Collection filterObjects(Collection initial, String filter)
          Filters a collection of objects regarding an expression.
protected  Collection getMatchingMethodsFor(Wrappee wrappee, ClassItem cli)
          Gets the methods of the wrappee that are modified by this pointcut.
protected  Collection getMatchingStaticMethodsFor(ClassItem cli)
           
static Collection getRelatedObjects(Collection initial, String relationExpr)
          Gets all the objects that are related to a set of objects through relations that match the given expression.
 boolean isClassMatching(Wrappee wrappee, ClassItem cl)
          Tests if the given component class is modified (in a way or another) by this pointcut.
 boolean isHostMatching(Wrappee wrappee, ClassItem cl)
          Tests if the given component is modified (in a way or another) by this pointcut.
static boolean isInPath(Object candidate, String pathExpr)
          Tells if this object is reachable for the given object path expression.
 boolean isMethodMatching(AbstractMethodItem method)
          Tests if the given method item is modified (in a way or another) by this pointcut.
 boolean isNameMatching(Wrappee wrappee, ClassItem cl)
          Tests if the given component is modified (in a way or another) by this pointcut.
 boolean isNameMatching(Wrappee wrappee, String name)
           
static boolean isPathExpression(String expr)
          Tells if this expression is a path expression (of the form o/r/o...).
protected  String parseKeyword(Wrappee wrappee, ClassItem cli, String keywordExpr, List parameters)
          Parses a keyword expression and returns its actual value as a regular expression regarding the context.
 Collection parseMethodExpr(Wrappee wrappee, ClassItem cli, String expr)
           
 String toString()
          Returns a readable description of the pointcut.
 
Methods inherited from class org.objectweb.jac.core.Pointcut
parseExpr, replaceTags
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Constructor Detail

MethodPointcut

public MethodPointcut(AspectComponent aspectComponent,
                      String wrappeeExpr,
                      String wrappeeClassExpr,
                      String wrappeeMethodExpr,
                      Wrapper initWrapper,
                      String wrappingClassName,
                      String methodName,
                      Object[] methodArgs,
                      String hostExpr,
                      String exceptionHandler,
                      boolean one2one)
Instantiates a new pointcut with the given characterisitics.

Parameters:
aspectComponent - the aspect component this pointcut belongs to
wrappeeExpr - the wrappee definition that matches the names as defined by the naming aspect
wrappeeClassExpr - the wrappee class expression (matches the fully qualified class name)
wrappeeMethodExpr - the wrappee method expression (matches the full method name as defined by the rtti)
initWrapper - the instance of the wrapper used by this pointcut, if null a new one is automatically created depending on the one2one flag
wrappingClassName - the name of the wrapper class
methodName - the name of the aspect component method to upcall when a mathing object is used
methodArgs - the argument values for this method method to upcall when a matching object is used
hostExpr - a regular expression that macthes the hosts where the pointcut has to be applied (if null or empty string, default is ".*" which means that the pointcut will be applied on all the hosts)
one2one - true if each new wrapped instance corresponds to one different wrapper (it has no effect if initWrapper is not null
Method Detail

toString

public String toString()
Returns a readable description of the pointcut.

Overrides:
toString in class Object

buildRegexp

public static gnu.regexp.RE buildRegexp(String pattern)
                                 throws gnu.regexp.REException
gnu.regexp.REException

applyTo

public void applyTo(Wrappee wrappee,
                    ClassItem cl)
Applies this pointcut to the given wrappee.

The pointcut application consists in wrapping the wrappee accordingly to the pointcut description. Note that in JAC, the pointcut is usually applied on a per-component basis, and when the component (wrappee) is used for the first time.

Specified by:
applyTo in class Pointcut
Parameters:
wrappee - the component the pointcut is applied to
cl - class the pointcut is applied to

getMatchingMethodsFor

protected Collection getMatchingMethodsFor(Wrappee wrappee,
                                           ClassItem cli)
Gets the methods of the wrappee that are modified by this pointcut.

Parameters:
wrappee - the component to test
cli - the class of the wrappee
Returns:
a vector containing the matching method items

getMatchingStaticMethodsFor

protected Collection getMatchingStaticMethodsFor(ClassItem cli)

parseMethodExpr

public Collection parseMethodExpr(Wrappee wrappee,
                                  ClassItem cli,
                                  String expr)
Parameters:
wrappee - the object the pointcut applies to
cli - the class the pointcut applies to (in case wrappee==null, for static methods)
expr - the pointcut expression
Returns:
A set of method matching the pointcut for the wrappee or class

filterMethodKeywords

protected void filterMethodKeywords(Object wrappee,
                                    ClassItem cli,
                                    String expr,
                                    boolean inv,
                                    Collection source,
                                    Collection dest)
Adds methods from source that match an expression to a collection

Parameters:
wrappee - object to match with
cli - class to macth with, used if wrappee==null
expr - the expression to match
inv - wether to keep or reject matching methods
source - method items to chose from
dest - collection to add the matching methods to

isClassMatching

public boolean isClassMatching(Wrappee wrappee,
                               ClassItem cl)
Tests if the given component class is modified (in a way or another) by this pointcut.

Parameters:
wrappee - the component to test
Returns:
true if the class matches

isNameMatching

public boolean isNameMatching(Wrappee wrappee,
                              ClassItem cl)
Tests if the given component is modified (in a way or another) by this pointcut.

Contrary to the class-based matching, this matching works on a per-component basis and not on a per-class basis. This is posible by using the naming aspect of the system (assuming it is there). If the naming aspect appears not to be woven, then all the components should mathes here.

Parameters:
wrappee - the component to test
Returns:
true if the name matches

isNameMatching

public boolean isNameMatching(Wrappee wrappee,
                              String name)

isPathExpression

public static boolean isPathExpression(String expr)
Tells if this expression is a path expression (of the form o/r/o...).

Parameters:
expr - the expression to check
Returns:
true is a path expression

isInPath

public static boolean isInPath(Object candidate,
                               String pathExpr)
Tells if this object is reachable for the given object path expression.

Parameters:
candidate - the candidate object
pathExpr - the path expression
Returns:
boolean true if reachable

getRelatedObjects

public static Collection getRelatedObjects(Collection initial,
                                           String relationExpr)
Gets all the objects that are related to a set of objects through relations that match the given expression.

Parameters:
initial - the initial objects
relationExpr - the expression that matches the relations
Returns:
a set of accessible objects

filterObjects

public static Collection filterObjects(Collection initial,
                                       String filter)
Filters a collection of objects regarding an expression.

Parameters:
initial - the collection to filter
filter - the filtering expression
Returns:
a filtered collection that contains only the objects that match the expression

isHostMatching

public boolean isHostMatching(Wrappee wrappee,
                              ClassItem cl)
Tests if the given component is modified (in a way or another) by this pointcut.

Contrary to the class-based matching, this matching works on a per-component basis and not on a per-class basis. This is posible by using the naming aspect of the system (assuming it is there). If the naming aspect appears not to be woven, then all the components should mathes here.

Parameters:
wrappee - the component to test
cl - the class, in case of static method
Returns:
true if the name matches

isMethodMatching

public boolean isMethodMatching(AbstractMethodItem method)
Tests if the given method item is modified (in a way or another) by this pointcut.

Parameters:
method - the method to test
Returns:
true if the method matches

parseKeyword

protected String parseKeyword(Wrappee wrappee,
                              ClassItem cli,
                              String keywordExpr,
                              List parameters)
Description copied from class: Pointcut
Parses a keyword expression and returns its actual value as a regular expression regarding the context.

Specified by:
parseKeyword in class Pointcut