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