JAC project
AOPSYS
CEDRIC & LIP6 labs

org.objectweb.jac.core
Class Wrapping

java.lang.Object
  |
  +--org.objectweb.jac.core.Wrapping

public class Wrapping
extends Object

This class provides a set of useful static methods that allow the wrapping of wrappable objects (wrappee) by some wrapper objects.

Author:
Renaud Pawlak, Lionel Seinturier

Field Summary
static Object[] emptyArray
           
 
Constructor Summary
Wrapping()
           
 
Method Summary
static void addExceptionHandler(Wrappee wrappee, Wrapper wrapper, String method)
           
static void addExceptionHandler(Wrappee wrappee, Wrapper wrapper, String method, AbstractMethodItem listenedMethod)
           
static Object clone(Object org)
           
static List getCatchingChain(Wrappee wrappee, AbstractMethodItem method)
          Returns the catching chain that wraps the given method.
static List getWrapperClasses(Wrappee wrappee, ClassItem wrappeeClass)
          Returns the classes of the wrappers that wrap the given wrappee or wrappee's class.
static List getWrappers(Wrappee wrappee, ClassItem wrappeeClass)
          Returns the wrappers that wrap the given wrappee or wrappee's class.
static WrappingChain getWrappingChain(Wrappee wrappee, AbstractMethodItem method)
          Returns the wrapping chain that wraps the given method.
static Object invokeOrg(Wrappee wrappee, String name, Object[] parameters)
          This method can be used to shortcut the wrapping chain and directly call the original method.
static Object invokeRoleMethod(Wrappee wrappee, ClassItem wrappeeClass, Class wrapperClass, String methodName, Object[] parameters)
          Invokes a role method on the wrappee.
static Object invokeRoleMethod(Wrappee wrappee, Class wrapperClass, String methodName, Object[] parameters)
          Invokes a role method on the wrappee.
static Object invokeRoleMethod(Wrappee wrappee, String methodName, Object[] parameters)
          Invokes a role method on the wrappee.
static boolean isExtendedBy(Wrappee wrappee, ClassItem wrappeeClass, Class wrapperClass)
           
static boolean isWrappable(AbstractMethodItem method)
          Tells if a given method is wrappable.
static boolean isWrappedBy(Wrappee wrappee, ClassItem wrappeeClass, Class wrapperClass)
          Returns true if the wrappee or the wrappeeClass is wrapped by a wrapper class.
static boolean isWrappedBy(Wrappee wrappee, ClassItem wrappeeClass, Wrapper wrapper)
           
static Object methodNextWrapper(Interaction interaction)
           
static Object nextWrapper(Interaction interaction)
          This method factorizes the common code that is used when the next wrapper is called.
static String printWrappingChain(Object[][] wrappingChain)
           
static void unwrap(Wrappee wrappee, ClassItem wrappeeClass, Wrapper wrapper)
          Definitively removes a wrapper.
static void unwrap(Wrappee wrappee, Wrapper wrapper, String wrappingMethod, AbstractMethodItem wrappedMethod)
          Unwraps a single method.
static void unwrapAll(Wrappee wrappee, ClassItem wrappeeClass, Wrapper wrapper)
           
static void unwrapAll(Wrappee wrappee, ClassItem wrappeeClass, Wrapper wrapper, String wrappingMethod)
           
static void wrap(Wrappee wrappee, ClassItem wrappeeClass, Wrapper wrapper)
          Adds a wrapper to the current wrappee.
static void wrap(Wrappee wrappee, Wrapper wrapper, MethodItem wrappingMethod, AbstractMethodItem wrappedMethod)
          Wrap a method of an object
static void wrap(Wrappee wrappee, Wrapper wrapper, String wrappingMethod, AbstractMethodItem wrappedMethod)
          Wrap a method of an object
static void wrap(Wrappee wrappee, Wrapper wrapper, String wrappingMethod, AbstractMethodItem[] wrappedMethods)
          A nicer way to write wrap when several base methods need to be wrapped.
static void wrap(Wrappee wrappee, Wrapper wrapper, String wrappingMethod, String[] wrappedMethods)
          A string based version of wrap (for simplification purpose).
static void wrapAll(Wrappee wrappee, ClassItem wrappeeClass, Wrapper wrapper, String wrapperMethod)
          Wraps all the wrappable (public) methods of the current wrappee.
static void wrapModifiers(Wrappee wrappee, Wrapper wrapper, String wrapperMethod)
          Wraps all the writer wrappable (public) methods of the current wrappee.
static void wrapSameName(Wrappee wrappee, Wrapper wrapper, String[] wrappingMethods)
          A convenient way to wrap methods when the wrapped methods have the same name as the wrapping methods.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

emptyArray

public static final Object[] emptyArray
Constructor Detail

Wrapping

public Wrapping()
Method Detail

getWrappingChain

public static WrappingChain getWrappingChain(Wrappee wrappee,
                                             AbstractMethodItem method)
Returns the wrapping chain that wraps the given method.

Parameters:
wrappee - the wrappee (if null, the given method is nesserally a static method)
method - the wrapped method (can be static, then wrappee is null)

getCatchingChain

public static List getCatchingChain(Wrappee wrappee,
                                    AbstractMethodItem method)
Returns the catching chain that wraps the given method.

Parameters:
wrappee - the wrappee (if null, the given method is nesserally a static method)
method - the wrapped method (can be static, then wrappee is null)

getWrappers

public static List getWrappers(Wrappee wrappee,
                               ClassItem wrappeeClass)
Returns the wrappers that wrap the given wrappee or wrappee's class.

Parameters:
wrappee - the wrappee (can be null if wrappeeClass is not null)
wrappeeClass - the wrappee's class (can be null if wrappee is not null)

getWrapperClasses

public static List getWrapperClasses(Wrappee wrappee,
                                     ClassItem wrappeeClass)
Returns the classes of the wrappers that wrap the given wrappee or wrappee's class.

Parameters:
wrappee - the wrappee (can be null if wrappeeClass is not null)
wrappeeClass - the wrappee's class (can be null if wrappee is not null)

wrap

public static void wrap(Wrappee wrappee,
                        ClassItem wrappeeClass,
                        Wrapper wrapper)
Adds a wrapper to the current wrappee.

Any method of this wrapper can then be used on the wrappee with invokeRoleMethod.

To precise which method of this wrapper should actually wrap the current wrappee methods, use the wrap methods.

Parameters:
wrappee - the wrappee (can be null if wrappeeClass is not null, then wraps all the instances of the class in a static mode)
wrappeeClass - the wrappee's class (can be null if wrappee is not null)
wrapper - the new wrapper

isWrappable

public static boolean isWrappable(AbstractMethodItem method)
Tells if a given method is wrappable.

Parameters:
method - the method to check

printWrappingChain

public static String printWrappingChain(Object[][] wrappingChain)

wrap

public static void wrap(Wrappee wrappee,
                        Wrapper wrapper,
                        String wrappingMethod,
                        AbstractMethodItem wrappedMethod)
Wrap a method of an object

Parameters:
wrappee - the object to wrap
wrapper - the wrapper
wrappingMethod - the method of the wrapper
wrappedMethod - the method of wrappee to wrap

wrap

public static void wrap(Wrappee wrappee,
                        Wrapper wrapper,
                        MethodItem wrappingMethod,
                        AbstractMethodItem wrappedMethod)
Wrap a method of an object

Parameters:
wrappee - the object to wrap
wrapper - the wrapper
wrappingMethod - the method of the wrapper
wrappedMethod - the method of wrappee to wrap

wrap

public static void wrap(Wrappee wrappee,
                        Wrapper wrapper,
                        String wrappingMethod,
                        AbstractMethodItem[] wrappedMethods)
A nicer way to write wrap when several base methods need to be wrapped.

Parameters:
wrappee - the wrappee (can be null if the wrappeed methods are static)
wrapper - the wrapper where the wrapping method is implemented
wrappingMethod - the name of the wrapping method in the wrapper
wrappedMethods - the names of the wrapped methods

wrap

public static void wrap(Wrappee wrappee,
                        Wrapper wrapper,
                        String wrappingMethod,
                        String[] wrappedMethods)
A string based version of wrap (for simplification purpose).

Parameters:
wrappee - the wrappee (cannot be null, this version only works for non-static methods)
wrapper - the wrapper where the wrapping method is implemented
wrappingMethod - the name of the wrapping method in the wrapper
wrappedMethods - the names of the wrapped methods
See Also:
wrap(Wrappee,Wrapper,String,AbstractMethodItem[])

wrapSameName

public static void wrapSameName(Wrappee wrappee,
                                Wrapper wrapper,
                                String[] wrappingMethods)
A convenient way to wrap methods when the wrapped methods have the same name as the wrapping methods.

Parameters:
wrappee - the wrappee (cannot be null, this version only works for non-static methods)
wrapper - the wrapper
wrappingMethods - the names of the wrapping methods in the wrapper (must be also found in the wrappee)

wrapAll

public static void wrapAll(Wrappee wrappee,
                           ClassItem wrappeeClass,
                           Wrapper wrapper,
                           String wrapperMethod)
Wraps all the wrappable (public) methods of the current wrappee.

Parameters:
wrappee - the wrappee (can be null, then only wrap static methods)
wrappeeClass - the wrappee's class (can be null if wrappee is not null)
wrapper - the wrapper
wrapperMethod - the name of the wrapping method

wrapModifiers

public static void wrapModifiers(Wrappee wrappee,
                                 Wrapper wrapper,
                                 String wrapperMethod)
Wraps all the writer wrappable (public) methods of the current wrappee.

Parameters:
wrappee - the wrappee (cannot be null, this version only works for non-static methods)
wrapper - the wrapper
wrapperMethod - the name of the wrapping method

unwrap

public static void unwrap(Wrappee wrappee,
                          ClassItem wrappeeClass,
                          Wrapper wrapper)
Definitively removes a wrapper.

When this method is called, none of the methods of the wrapper can be used as role methods anymore.

This method before calls the unwrapAll to ensure that none of the current wrappee methods are yet wrapped.

Parameters:
wrappee - the wrappee (can be null, then only wrap static methods)
wrappeeClass - the wrappee's class (can be null if wrappee is not null)
wrapper - the wrapper to remove
See Also:
unwrapAll(Wrappee,ClassItem,Wrapper), invokeRoleMethod(Wrappee,String,Object[])

unwrap

public static void unwrap(Wrappee wrappee,
                          Wrapper wrapper,
                          String wrappingMethod,
                          AbstractMethodItem wrappedMethod)
Unwraps a single method.

The wrapper must implement wrappingMethod. If the wrapped method was not actually wrapped at the time this method is called, then this code has no effect.

To definitively remove the wrapper so that none of its method will not be considered as role methods anymore, use the unwrap(Wrappee,ClassItem,Wrapper) method.

Parameters:
wrappee - the wrappee (can be null, then the wrappedMethod must be static)
wrapper - the wrapper
See Also:
unwrap(Wrappee,ClassItem,Wrapper)

unwrapAll

public static void unwrapAll(Wrappee wrappee,
                             ClassItem wrappeeClass,
                             Wrapper wrapper,
                             String wrappingMethod)

unwrapAll

public static void unwrapAll(Wrappee wrappee,
                             ClassItem wrappeeClass,
                             Wrapper wrapper)

isWrappedBy

public static boolean isWrappedBy(Wrappee wrappee,
                                  ClassItem wrappeeClass,
                                  Wrapper wrapper)

isWrappedBy

public static boolean isWrappedBy(Wrappee wrappee,
                                  ClassItem wrappeeClass,
                                  Class wrapperClass)
Returns true if the wrappee or the wrappeeClass is wrapped by a wrapper class.


isExtendedBy

public static boolean isExtendedBy(Wrappee wrappee,
                                   ClassItem wrappeeClass,
                                   Class wrapperClass)

addExceptionHandler

public static void addExceptionHandler(Wrappee wrappee,
                                       Wrapper wrapper,
                                       String method,
                                       AbstractMethodItem listenedMethod)

addExceptionHandler

public static void addExceptionHandler(Wrappee wrappee,
                                       Wrapper wrapper,
                                       String method)

invokeRoleMethod

public static Object invokeRoleMethod(Wrappee wrappee,
                                      String methodName,
                                      Object[] parameters)
Invokes a role method on the wrappee. The first wrapper which defines a role method with that name is used, so in order to avoid ambiguity, it is preferable to use invokeRoleMethod(Wrappee,Class,String,Object[])

Parameters:
wrappee - the wrappee (must be wrapped by a wrapper that supports the role method)
parameters - the parameters.
Returns:
the returned object
See Also:
invokeRoleMethod(Wrappee,Class,String,Object[])

invokeRoleMethod

public static Object invokeRoleMethod(Wrappee wrappee,
                                      Class wrapperClass,
                                      String methodName,
                                      Object[] parameters)
Invokes a role method on the wrappee.

Parameters:
wrappee - the wrappee (must be wrapped by a wrapper that supports the role method).
wrapperClass - the class of the role method to invoke.
parameters - the parameters.
Returns:
the returned object

invokeRoleMethod

public static Object invokeRoleMethod(Wrappee wrappee,
                                      ClassItem wrappeeClass,
                                      Class wrapperClass,
                                      String methodName,
                                      Object[] parameters)
Invokes a role method on the wrappee.

Parameters:
wrappee - the wrappee (must be wrapped by a wrapper that supports the role method).
wrapperClass - the class of the role method to invoke.
parameters - the parameters.
Returns:
the returned object

invokeOrg

public static Object invokeOrg(Wrappee wrappee,
                               String name,
                               Object[] parameters)
This method can be used to shortcut the wrapping chain and directly call the original method.

NOTE: avoid doing this unless you really know what you are doing. It is not clean to shortcut the whole wrapping chain. Instead, use the invoke method or, if you really need to, AspectComponent.before/afterRunningWrapper() to skip some wrappers.

Parameters:
wrappee - the object that supports the method
name - the name of the method to call
parameters - the argument values
Returns:
the called method return value as an object
See Also:
AspectComponent.beforeRunningWrapper(Wrapper,String), AspectComponent.afterRunningWrapper(Wrapper,String)

clone

public static Object clone(Object org)

nextWrapper

public static Object nextWrapper(Interaction interaction)
This method factorizes the common code that is used when the next wrapper is called.


methodNextWrapper

public static Object methodNextWrapper(Interaction interaction)

Contact JAC development team:
Renaud Pawlak
Lionel Seinturier
Laurent Martelli