org.objectweb.jac.core
Class Wrapper

java.lang.Object
  |
  +--org.objectweb.jac.core.Wrapper
All Implemented Interfaces:
Advice, ConstructorInterceptor, Interceptor, MethodInterceptor, Serializable
Direct Known Subclasses:
AbstractPersistenceWrapper, AuthenticationWrapper, BeginPersistentSessionWrapper, BeginTransactionWrapper, BindingWrapper, BroadcastingAC.BroadcastingWrapper, CacheWrapper, CacheWrapper, ConfirmationAC.ConfirmationWrapper, ConsistencyWrapper, ConstraintWrapper, DebuggingWrapper, DeploymentWrapper, DispatchTransactionWrapper, EndPersistentSessionWrapper, EndTransactionWrapper, ForwardingWrapper, I18nAC.TranslatorWrapper, IdGenAC.IdGenWrapper, InputWrapper, LimiterWrapper, LoadBalancingAC.LoadBalancingWrapper, MessageQueueWrapper, PerSessionObjectWrapper, PrimaryKeyWrapper, ReadWrapper, RecordingWrapper, RepositoryWrapper, RoleWrapper, SessionWrapper, SimpleCountingWrapper, StubWrapper, SynchronizationAC.SynchronizationWrapper, TimestampAC.Wrapper, TransactionAC.TransactionWrapper, UserAC.FilterWrapper, UserAC.OwnerFilterWrapper, UserWrapper, VerboseWrapper, ViewControlWrapper, WaitWrapper, WriteWrapper

public abstract class Wrapper
extends Object
implements Serializable, MethodInterceptor, ConstructorInterceptor

This class is the root class for all the wrappers. A wrapper is part of a collaboration point when one or several of its methods wrap a base program object (a wrappee). The set of wrappers (methods) that wrap a wrappee (method) it called a wrapping (method) chain.

When a method call occurs on a wrappee, the system creates a new collaboration point in the current collaboration and all the wrappers are sequentially called.

A given wrapper passes the hand to the next wrapper (or to the wrappee if last) by explicitly calling the proceed() method.

For futher details about wrapping semantics, see the Wrapper.proceed() method and the Wrappee.wrap() methods.

Author:
Renaud Pawlak
See Also:
Serialized Form

Field Summary
protected  AspectComponent ac
          The AC of the wrapper.
protected static ClassRepository cr
           
 
Constructor Summary
Wrapper(AspectComponent ac)
          The constructor sets the aspect component that owns the wrapper from the context.
 
Method Summary
 Object attr(String name)
           
 void attrdef(String name, Object value)
           
 Object construct(ConstructorInvocation invocation)
           
static boolean defines(String methodName)
          Returns true if the method is defined in the wrapper class.
 AspectComponent getAspectComponent()
          Returns the Aspect Component the wrapper belongs to by resolving the name.
 String getAspectComponentName()
          Returns the Aspect Component name the wrapper belongs to.
static Vector getExceptionHandlers(Class wrapperClass)
          Returns the exception handlers of the given wrapper class.
 Object invoke(MethodInvocation invocation)
           
 Object proceed(Invocation invocation)
          Run the next wrapper of the collaboration point.
 String toString()
          String representation of a wrapper (eg {wrapper className owned by aspectComponentName}).
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

cr

protected static final ClassRepository cr

ac

protected final transient AspectComponent ac
The AC of the wrapper.

Constructor Detail

Wrapper

public Wrapper(AspectComponent ac)
The constructor sets the aspect component that owns the wrapper from the context.

Method Detail

defines

public static boolean defines(String methodName)
Returns true if the method is defined in the wrapper class.

Parameters:
methodName - the method to test
Returns:
true if wrapper method

getExceptionHandlers

public static Vector getExceptionHandlers(Class wrapperClass)
Returns the exception handlers of the given wrapper class. Are considered as exception handlers all methods whose first argument is an Exception.

Parameters:
wrapperClass - the wrapper class
Returns:
a vector containing the methods names

getAspectComponent

public AspectComponent getAspectComponent()
Returns the Aspect Component the wrapper belongs to by resolving the name.

See Also:
getAspectComponentName()

getAspectComponentName

public String getAspectComponentName()
Returns the Aspect Component name the wrapper belongs to. By default, this name is set by the system when an aspect component wraps a given wrappee.

See Also:
Wrappee

toString

public String toString()
String representation of a wrapper (eg {wrapper className owned by aspectComponentName}).

Overrides:
toString in class Object

proceed

public final Object proceed(Invocation invocation)
Run the next wrapper of the collaboration point.

A new collaboration point is initiated by the system when a method call occurs on a base program object (a wrappee). If the called method is wrapped by one or several wrapping methods (wrappers methods - see Wrappee.wrap()), then the system first upcalls all the wrapping methods.

A wrapping method is a regular Java method that takes no argument and returns an object. It can access the currently called method runtime caracteristics by using the CollaborationParticipant interface methods implemented by the wrapper (see method() or args).

The set of wrapping methods that wraps a wrappee method is called a wrapping method chain. The wrapping methods of a wrapping chain are sequentially called. A given wrapping method of the wrapping chain passes the hand to the next wrapping method of this chain by calling proceed().

A wrapper should ALWAYS call the proceed method except if it delibaratly wants to replace all the upcoming wrappers and base method functionalities (e.g. the org.objectweb.jac.aspects.binding.ForwardingWrapper).

The wrapping methods are called in a well-defined order. A wrapper cannot change this order by himself since it is the composition aspect that is responsible for setting this order (see Wrappee.wrap() and CompositionAspect.getWeaveTimeRank()).

Within a clean aspect-oriented design, the wrapper can be shortcutted by its aspect component if needed (see AspectComponent.beforeRunningWrapper()).

In a wrapping method, proceed returns the value returned by the wrappee method. A wrapper can modify this return value if needed. The wrapping method code that is placed before the proceed() call is called before code (since it is executed before the wrapped method execution), and the code that is placed after the proceed call is called after code (since it is executed after).

A typical wrapping method looks like the following:

Returns:
the final value returned by the current method call
See Also:
Wrapping.wrap(Wrappee,Wrapper,AbstractMethodItem), CollaborationParticipant, CompositionAspect.getWeaveTimeRank(WrappingChain,Wrapper), AspectComponent.beforeRunningWrapper(Wrapper,String)

attrdef

public final void attrdef(String name,
                          Object value)

attr

public final Object attr(String name)

invoke

public Object invoke(MethodInvocation invocation)
              throws Throwable
Specified by:
invoke in interface MethodInterceptor
Throwable

construct

public Object construct(ConstructorInvocation invocation)
                 throws Throwable
Specified by:
construct in interface ConstructorInterceptor
Throwable