org.jboss.aop
Interface InstanceAdvisor

All Known Implementing Classes:
ClassInstanceAdvisor, GeneratedInstanceAdvisorMixin, InstanceProxyContainer, MarshalledProxyAdvisor

public interface InstanceAdvisor

Holds an object instance's metadata and attached interceptor chain.
The interceptor chain attached to an advised object contains interceptors that are applied to every method execution and field access joinpoint of that object. At startup, the instance interceptor chain is always empty. This chain is specially tailored for per-instance dynamic AOP operations, allowing the addition and removal of interceptors at runtime. The order in which the interceptors are invoked depends on which method was used to add them to the chain (for more information, see insertInterceptor(org.jboss.aop.advice.Interceptor) and appendInterceptor(org.jboss.aop.advice.Interceptor) methods).
Notice that every interceptor chain operation provided by an instance advisor affects only the advised object interceptor chain, and hence it will not affect other advised instances, regardless of whether they belong to the same class or not.

Version:
$Revision: 68585 $
Author:
Bill Burke

Method Summary
 void appendInterceptor(Interceptor interceptor)
          Appends an interceptor to the end of the instance's interceptor chain.
 void appendInterceptor(int index, Interceptor interceptor)
          Appends an interceptor at position index of the appended instance's interceptor chain.
 void appendInterceptorStack(String stackName)
          Appends an interceptor chain to the end of the instance's interceptor chain.
 Domain getDomain()
          Returns the domain where this advisor belongs.
 Object getInstance()
          Returns the advised instance managed by this advisor.
 Interceptor[] getInterceptors()
          Returns the interceptor chain of the advised instance.
 Interceptor[] getInterceptors(Interceptor[] baseChain)
          Merges the advised instance interceptor chain with baseChain.
 SimpleMetaData getMetaData()
          Returns the metadata bound to the advised instance.
 Object getPerInstanceAspect(AspectDefinition def)
          Returns a per instance aspect object defined by def.
 Object getPerInstanceAspect(String aspectName)
          Returns a per instance aspect object identified by aspectName.
 Object getPerInstanceJoinpointAspect(Joinpoint joinpoint, AspectDefinition def)
          Returns the per instance joinpoint aspect object defined by def to be applied at joipoint.
 boolean hasAspects()
          Indicates whether there are instance aspects bound to the instance advised.
 boolean hasInterceptors()
          Indicates if the advised instance interceptor chain is not empty.
 void insertInterceptor(Interceptor interceptor)
          Inserts an interceptor at the beginning of the instance's interceptor chain.
 void insertInterceptor(int index, Interceptor interceptor)
          Inserts an interceptor at position index of the inserted instance's interceptor chain.
 void insertInterceptorStack(String stackName)
          Inserts an interceptor stack to the beginning of the instance's interceptor chain.
 void removeInterceptor(String name)
          Removes an interceptor from instance's interceptor chain.
 void removeInterceptorStack(String name)
          Removes an interceptor stack from the instance's interceptor chain.
 

Method Detail

getMetaData

SimpleMetaData getMetaData()
Returns the metadata bound to the advised instance.

Returns:
the metadata bound to the advised instance.

getDomain

Domain getDomain()
Returns the domain where this advisor belongs. The domain contains all the configured AOP features (like bindings, aspects, and introductions) that should be applied to the advised instance.

Returns:
the domain bound to this advisor

getInstance

Object getInstance()
Returns the advised instance managed by this advisor.

Returns:
the advised instance

hasInterceptors

boolean hasInterceptors()
Indicates if the advised instance interceptor chain is not empty.

Returns:
true if the advised instance interceptor chain contains one or more elements.

hasAspects

boolean hasAspects()
Indicates whether there are instance aspects bound to the instance advised. In other words, this method returns the same as hasInterceptors().

Returns:
true if there is one or more aspects bound to this advised instance.

insertInterceptor

void insertInterceptor(Interceptor interceptor)
Inserts an interceptor at the beginning of the instance's interceptor chain.

Parameters:
interceptor - the interceptor to be added to the instance's chain.

insertInterceptor

void insertInterceptor(int index,
                       Interceptor interceptor)
                       throws IndexOutOfBoundsException
Inserts an interceptor at position index of the inserted instance's interceptor chain.

Parameters:
index - the position where to insert interceptor. This value must not be greater than or equal to the number of inserted interceptors in the chain.
interceptor - the interceptor to be added to the instance's chain.
Throws:
IndexOutOfBoundsException - if index is greater than or equal to the total number of inserted interceptors contained in this advisor, or if index is a negative value

insertInterceptorStack

void insertInterceptorStack(String stackName)
Inserts an interceptor stack to the beginning of the instance's interceptor chain.

Parameters:
stackName - the name that identifies the interceptor stack to be inserted

appendInterceptor

void appendInterceptor(Interceptor interceptor)
Appends an interceptor to the end of the instance's interceptor chain.

Parameters:
interceptor - the interceptor to be appended to the instance's chain

appendInterceptor

void appendInterceptor(int index,
                       Interceptor interceptor)
                       throws IndexOutOfBoundsException
Appends an interceptor at position index of the appended instance's interceptor chain.

Parameters:
index - the position where to insert interceptor. This value must not be greater than or equal to the number of appended interceptors in the chain.
interceptor - the interceptor to be added to the instance's chain.
Throws:
IndexOutOfBoundsException - if index is greater than or equal to the total number of appended interceptors contained in this advisor, or if index is a negative value

appendInterceptorStack

void appendInterceptorStack(String stackName)
Appends an interceptor chain to the end of the instance's interceptor chain.

Parameters:
stackName - the name that identifies the interceptor stack to be appended

removeInterceptor

void removeInterceptor(String name)
Removes an interceptor from instance's interceptor chain.

Parameters:
name - name of the interceptor to be removed from the chain.
See Also:
Interceptor.getName()

removeInterceptorStack

void removeInterceptorStack(String name)
Removes an interceptor stack from the instance's interceptor chain.

Parameters:
name - the name that identifies the interceptor stack to be removed

getInterceptors

Interceptor[] getInterceptors()
Returns the interceptor chain of the advised instance.

For internal use only.

Returns:
the interceptor chain of the advised instance.

getInterceptors

Interceptor[] getInterceptors(Interceptor[] baseChain)
Merges the advised instance interceptor chain with baseChain.
The result of the merge will contain first all the inserted interceptors, then baseChain, and finally all the appended interceptors.

For internal use only.

Parameters:
baseChain - the chain to be joined with the advised instance's chain.
Returns:
a new interception chain as a result of the merge of baseChain with the instance's chain. May return baseChain if the last one is empty.

getPerInstanceAspect

Object getPerInstanceAspect(String aspectName)
Returns a per instance aspect object identified by aspectName.
Notice that the aspect objects are created by JBoss AOP, either by using an aspect factory or by using the constructor of an aspect class.

For internal use only.

Parameters:
aspectName - name of the queried aspect
Returns:
the per instance aspect named aspectName

getPerInstanceAspect

Object getPerInstanceAspect(AspectDefinition def)
Returns a per instance aspect object defined by def.
Notice that the aspect objects are created by JBoss AOP, either by using an aspect factory or by using the constructor of an aspect class.

For internal use only.

Parameters:
def - definition of the queried aspect
Returns:
the per instance aspect defined by def

getPerInstanceJoinpointAspect

Object getPerInstanceJoinpointAspect(Joinpoint joinpoint,
                                     AspectDefinition def)
Returns the per instance joinpoint aspect object defined by def to be applied at joipoint.
Notice that the aspect objects are created by JBoss AOP, either by using an aspect factory or by using the constructor of an aspect class.

For internal use only.

Parameters:
joinpoint - the joinpoint to which the aspect object will be applied.
def - definition of the queried aspect
Returns:
the per instance joinpoint aspect defined by def to be applied at joinpoint


Copyright © 2008 JBoss, a division of Red Hat, Inc.. All Rights Reserved.