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 }