001: /*****************************************************************************
002: * Copyright (c) PicoContainer Organization. All rights reserved. *
003: * ------------------------------------------------------------------------- *
004: * The software in this package is published under the terms of the BSD *
005: * style license a copy of which has been included with this distribution in *
006: * the LICENSE.txt file. *
007: * *
008: * Idea by Rachel Davies, Original code by various *
009: *****************************************************************************/package org.nanocontainer.aop;
010:
011: import org.aopalliance.intercept.MethodInterceptor;
012:
013: /**
014: * Represents the collection of aspects (pointuts + advice) to be applied to a
015: * Pico container. Provides methods for registering mixin and interceptor
016: * advice. Advice can be applied to all components in the container that match a
017: * pointcut, or advice can be applied to just one component. Advice objects may
018: * themselves be components in the container, with dependencies on other
019: * components.
020: *
021: * @author Stephen Molitor
022: * @version $Revision: 3144 $
023: */
024: public interface AspectsContainer {
025:
026: /**
027: * Registers container scoped interceptor advice. The advice will be applied
028: * to all components in the container whose class satisfies the
029: * <code>classPointcut</code>. The interceptor will only intercept
030: * methods that match the <code>methodPointcut</code>.
031: *
032: * @param classPointcut classes to apply the interceptor to.
033: * @param methodPointcut methods to apply the interceptor to.
034: * @param interceptor the interceptor advice object.
035: */
036: void registerInterceptor(ClassPointcut classPointcut,
037: MethodPointcut methodPointcut, MethodInterceptor interceptor);
038:
039: /**
040: * Registers component scoped interceptor advice. The advice will be applied
041: * to all components in the container whose key satisfies
042: * <code>componentPointcut</code>. The interceptor will only intercept
043: * methods that match the <code>methodPointcut</code>.
044: *
045: * @param componentPointcut components to apply the interceptor to.
046: * @param methodPointcut methods to apply the interceptor to.
047: * @param interceptor the interceptor advice object.
048: */
049: void registerInterceptor(ComponentPointcut componentPointcut,
050: MethodPointcut methodPointcut, MethodInterceptor interceptor);
051:
052: /**
053: * Registers container supplied container scoped interceptor advice. The
054: * interceptor advice object itself is a component in the container,
055: * specified by <code>interceptorComponentKey</code>. The advice will be
056: * applied to all components in the container whose class satisfies the
057: * <code>classPointcut</code>. The interceptor will only intercept
058: * methods that match the <code>methodPointcut</code>.
059: *
060: * @param classPointcut classes to apply the interceptor to.
061: * @param methodPointcut methods to apply the interceptor to.
062: * @param interceptorComponentKey the interceptor component key.
063: */
064: void registerInterceptor(ClassPointcut classPointcut,
065: MethodPointcut methodPointcut,
066: Object interceptorComponentKey);
067:
068: /**
069: * Registers component scoped interceptor advice. The interceptor advice
070: * object itself is a component in the container, specified by the
071: * <code>interceptorComponentKey</code>. The advice will be applied to
072: * all components in the container whose key satisfies
073: * <code>componentPointcut</code>. The interceptor will only intercept
074: * methods that match the <code>methodPointcut</code>.
075: *
076: * @param componentPointcut components to apply the interceptor to.
077: * @param methodPointcut methods to apply the interceptor to.
078: * @param interceptorComponentKey the interceptor component key.
079: */
080: void registerInterceptor(ComponentPointcut componentPointcut,
081: MethodPointcut methodPointcut,
082: Object interceptorComponentKey);
083:
084: /**
085: * Registers container scoped mixin advice. The mixin will be added to all
086: * components in the container whose class satisfies the
087: * <code>classPointcut</code>.
088: * <p/>
089: * If a component of type <code>mixinClass</code> has been registered in
090: * the container, that component will be used as the mixin. Otherwise a new
091: * object of type <code>mixinClass</code> will be instantiated each time
092: * the mixin is applied to a component. Any dependencies the mixin has will
093: * be supplied from components in the container, or, if there are no
094: * dependencies, the default constructor will be invoked to instantiate the
095: * mixin.
096: *
097: * @param classPointcut classes to add mixin to.
098: * @param interfaces interfaces the mixin implements.
099: * @param mixinClass the mixin implementation.
100: */
101: void registerMixin(ClassPointcut classPointcut, Class[] interfaces,
102: Class mixinClass);
103:
104: /**
105: * Registers component scoped mixin advice. The mixin will be added to all
106: * components in the container whose key satisfies the
107: * <code>componentPointcut</code>.
108: *
109: * @param componentPointcut classes to add mixin to.
110: * @param interfaces interfaces the mixin implements.
111: * @param mixinClass the mixin implementation.
112: * @see AspectsContainer#registerMixin(ClassPointcut, Class[], Class) for
113: * details on how <code>mixinClass</code> gets instantiated.
114: */
115: void registerMixin(ComponentPointcut componentPointcut,
116: Class[] interfaces, Class mixinClass);
117:
118: /**
119: * Registers container scoped mixin advice. The mixin will be added to all
120: * components in the container whose class satisfies the
121: * <code>classPointcut</code>. Convenience method that uses all
122: * interfaces implemented by the mixin class.
123: *
124: * @param classPointcut classes to add mixin to.
125: * @param mixinClass the mixin implementation.
126: * @see AspectsContainer#registerMixin(ClassPointcut, Class[], Class) for
127: * details on how <code>mixinClass</code> gets instantiated.
128: */
129: void registerMixin(ClassPointcut classPointcut, Class mixinClass);
130:
131: /**
132: * Registers component scoped mixin advice. The mixin will be added to all
133: * components in the container whose key satisfies the
134: * <code>componentPointcut</code>. Convenience method that uses all
135: * interfaces implemented by the mixin class.
136: *
137: * @param componentPointcut classes to add mixin to.
138: * @param mixinClass the mixin implementation.
139: * @see AspectsContainer#registerMixin(ClassPointcut, Class[], Class) for
140: * details on how <code>mixinClass</code> gets instantiated.
141: */
142: void registerMixin(ComponentPointcut componentPointcut,
143: Class mixinClass);
144:
145: /**
146: * Adds interfaces to classes picked by the class pointcut.
147: * <p/>
148: * This can be handy when you want to add an aggregate helper interface that
149: * extends all the mixin interfaces added, to avoid the need for casting.
150: * Note that the interfaces will <i>not </i> be added if no advice
151: * (interceptor or mixin) has been applied to the component.
152: *
153: * @param classPointcut classes to add interfaces to.
154: * @param interfaces the interfaces to add.
155: */
156: void registerInterfaces(ClassPointcut classPointcut,
157: Class[] interfaces);
158:
159: /**
160: * Adds interfaces to components picked by the component pointcut.
161: *
162: * @param componentPointcut components to add interfaces to.
163: * @param interfaces the interfaces to add.
164: * @see AspectsContainer#registerInterfaces(ClassPointcut, Class[]) for
165: * notes on using this method.
166: */
167: void registerInterfaces(ComponentPointcut componentPointcut,
168: Class[] interfaces);
169:
170: /**
171: * Produces a pointcuts factory that can be used to create pointcuts to be
172: * used in aspects registered with this <code>AspectsContainer</code>.
173: * Note that you are not limited to pointcuts produced by this factory; any
174: * pointcut that implements the appropriate <code>ClassPointcut</code>,
175: * <code>MethodPointcut</code> or <code>ComponentPointcut</code> will
176: * work.
177: *
178: * @return a pointcuts factory.
179: */
180: PointcutsFactory getPointcutsFactory();
181:
182: }
|