AspectsContainer


1   /*****************************************************************************
2    * Copyright (c) PicoContainer Organization. All rights reserved.            *
3    * ------------------------------------------------------------------------- *
4    * The software in this package is published under the terms of the BSD      *
5    * style license a copy of which has been included with this distribution in *
6    * the LICENSE.txt file.                                                     *
7    *                                                                           *
8    * Idea by Rachel Davies, Original code by various                           *
9    *****************************************************************************/
10  package org.nanocontainer.aop;
11  
12  import org.aopalliance.intercept.MethodInterceptor;
13  
14  /**
15   * Represents the collection of aspects (pointuts + advice) to be applied to a
16   * Pico container. Provides methods for registering mixin and interceptor
17   * advice. Advice can be applied to all components in the container that match a
18   * pointcut, or advice can be applied to just one component. Advice objects may
19   * themselves be components in the container, with dependencies on other
20   * components.
21   *
22   * @author Stephen Molitor
23   * @version $Revision: 3144 $
24   */
25  public interface AspectsContainer {
26  
27      /**
28       * Registers container scoped interceptor advice. The advice will be applied
29       * to all components in the container whose class satisfies the
30       * <code>classPointcut</code>. The interceptor will only intercept
31       * methods that match the <code>methodPointcut</code>.
32       *
33       * @param classPointcut  classes to apply the interceptor to.
34       * @param methodPointcut methods to apply the interceptor to.
35       * @param interceptor    the interceptor advice object.
36       */
37      void registerInterceptor(ClassPointcut classPointcut, MethodPointcut methodPointcut, MethodInterceptor interceptor);
38  
39      /**
40       * Registers component scoped interceptor advice. The advice will be applied
41       * to all components in the container whose key satisfies
42       * <code>componentPointcut</code>. The interceptor will only intercept
43       * methods that match the <code>methodPointcut</code>.
44       *
45       * @param componentPointcut components to apply the interceptor to.
46       * @param methodPointcut    methods to apply the interceptor to.
47       * @param interceptor       the interceptor advice object.
48       */
49      void registerInterceptor(ComponentPointcut componentPointcut, MethodPointcut methodPointcut,
50                               MethodInterceptor interceptor);
51  
52      /**
53       * Registers container supplied container scoped interceptor advice. The
54       * interceptor advice object itself is a component in the container,
55       * specified by <code>interceptorComponentKey</code>. The advice will be
56       * applied to all components in the container whose class satisfies the
57       * <code>classPointcut</code>. The interceptor will only intercept
58       * methods that match the <code>methodPointcut</code>.
59       *
60       * @param classPointcut           classes to apply the interceptor to.
61       * @param methodPointcut          methods to apply the interceptor to.
62       * @param interceptorComponentKey the interceptor component key.
63       */
64      void registerInterceptor(ClassPointcut classPointcut, MethodPointcut methodPointcut, Object   interceptorComponentKey);
65  
66      /**
67       * Registers component scoped interceptor advice. The interceptor advice
68       * object itself is a component in the container, specified by the
69       * <code>interceptorComponentKey</code>. The advice will be applied to
70       * all components in the container whose key satisfies
71       * <code>componentPointcut</code>. The interceptor will only intercept
72       * methods that match the <code>methodPointcut</code>.
73       *
74       * @param componentPointcut       components to apply the interceptor to.
75       * @param methodPointcut          methods to apply the interceptor to.
76       * @param interceptorComponentKey the interceptor component key.
77       */
78      void registerInterceptor(ComponentPointcut componentPointcut, MethodPointcut methodPointcut,
79                               Object   interceptorComponentKey);
80  
81      /**
82       * Registers container scoped mixin advice. The mixin will be added to all
83       * components in the container whose class satisfies the
84       * <code>classPointcut</code>.
85       * <p/>
86       * If a component of type <code>mixinClass</code> has been registered in
87       * the container, that component will be used as the mixin. Otherwise a new
88       * object of type <code>mixinClass</code> will be instantiated each time
89       * the mixin is applied to a component. Any dependencies the mixin has will
90       * be supplied from components in the container, or, if there are no
91       * dependencies, the default constructor will be invoked to instantiate the
92       * mixin.
93       *
94       * @param classPointcut classes to add mixin to.
95       * @param interfaces    interfaces the mixin implements.
96       * @param mixinClass    the mixin implementation.
97       */
98      void registerMixin(ClassPointcut classPointcut, Class  [] interfaces, Class   mixinClass);
99  
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 }
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags