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, MethodItem method, Object[] parameters)
           
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)
          Tells wether a wrappee has a wrapper whose class can be assigned to a given wrapper class.
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)
          Tells wether a wrapper wraps a wrappee or a class
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(Interceptor[] wrappingChain)
           
static void unwrap(Wrappee wrappee, ClassItem wrappeeClass, Collection acWrappers)
          Removes all wrappers that belong to list of wrappers
static void unwrap(Wrappee wrappee, ClassItem wrappeeClass, Wrapper wrapper)
          Definitively removes a wrapper.
static void unwrap(Wrappee wrappee, Wrapper wrapper, AbstractMethodItem wrappedMethod)
          Unwraps a single method.
static void unwrapAll(Wrappee wrappee, ClassItem wrappeeClass, Wrapper wrapper)
           
static void wrap(Wrappee wrappee, ClassItem wrappeeClass, Wrapper wrapper)
          Adds a wrapper to the current wrappee.
static void wrap(Wrappee wrappee, Wrapper wrapper, AbstractMethodItem wrappedMethod)
          Wrap a method of an object.
static void wrap(Wrappee wrappee, Wrapper wrapper, AbstractMethodItem[] wrappedMethods)
          A nicer way to write wrap when several base methods need to be wrapped.
static void wrap(Wrappee wrappee, Wrapper wrapper, String[] wrappedMethods)
          A string based version of wrap (for simplification purpose).
static void wrapAll(Wrappee wrappee, ClassItem wrappeeClass, Wrapper wrapper)
          Wraps all the wrappable (public) methods of the current wrappee.
static boolean wrapMethod(Wrappee wrappee, Wrapper wrapper, AbstractMethodItem wrappedMethod)
          Wrap a method of an object.
static void wrapModifiers(Wrappee wrappee, Wrapper wrapper)
          Wraps all the writer wrappable (public) methods of the current wrappee.
 
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(Interceptor[] wrappingChain)

wrap

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

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

wrapMethod

public static boolean wrapMethod(Wrappee wrappee,
                                 Wrapper wrapper,
                                 AbstractMethodItem wrappedMethod)
Wrap a method of an object. Only updates the wrapping chain of the method.

Parameters:
wrappee - the object to wrap
wrapper - the wrapper
wrappedMethod - the method of wrappee to wrap
Returns:
true if the method was actually wrapped

wrap

public static void wrap(Wrappee wrappee,
                        Wrapper wrapper,
                        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
wrappedMethods - the names of the wrapped methods

wrap

public static void wrap(Wrappee wrappee,
                        Wrapper wrapper,
                        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
wrappedMethods - the names of the wrapped methods
See Also:
wrap(Wrappee,Wrapper,AbstractMethodItem[])

wrapAll

public static void wrapAll(Wrappee wrappee,
                           ClassItem wrappeeClass,
                           Wrapper wrapper)
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

wrapModifiers

public static void wrapModifiers(Wrappee wrappee,
                                 Wrapper wrapper)
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

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,
                          ClassItem wrappeeClass,
                          Collection acWrappers)
Removes all wrappers that belong to list of wrappers

Parameters:
wrappee - the wrappee to unwrap (may be null for static methods)
wrappeeClass - the class of the wrappee to unwrap
acWrappers - the wrappers to remove (the wrappers of an aspect component)

unwrap

public static void unwrap(Wrappee wrappee,
                          Wrapper wrapper,
                          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
wrappedMethod - the name of the method to unwrap
See Also:
unwrap(Wrappee,ClassItem,Wrapper)

unwrapAll

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

isWrappedBy

public static boolean isWrappedBy(Wrappee wrappee,
                                  ClassItem wrappeeClass,
                                  Wrapper wrapper)
Tells wether a wrapper wraps a wrappee or a class


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)
Tells wether a wrappee has a wrapper whose class can be assigned to a given wrapper class.


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)
methodName - the name of the role method to invoke.
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.
methodName - the name 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).
wrappeeClass - the class of the wrapper (for static methods)
wrapperClass - the class of the role method to invoke.
methodName - the name 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)

invokeOrg

public static Object invokeOrg(Wrappee wrappee,
                               MethodItem method,
                               Object[] parameters)

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.

Parameters:
interaction - the method call being intercepted

methodNextWrapper

public static Object methodNextWrapper(Interaction interaction)