Advised


1   /*
2    * Copyright 2002-2007 the original author or authors.
3    *
4    * Licensed under the Apache License, Version 2.0 (the "License");
5    * you may not use this file except in compliance with the License.
6    * You may obtain a copy of the License at
7    *
8    *      http://www.apache.org/licenses/LICENSE-2.0
9    *
10   * Unless required by applicable law or agreed to in writing, software
11   * distributed under the License is distributed on an "AS IS" BASIS,
12   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13   * See the License for the specific language governing permissions and
14   * limitations under the License.
15   */
16  
17  package org.springframework.aop.framework;
18  
19  import org.aopalliance.aop.Advice;
20  
21  import org.springframework.aop.Advisor;
22  import org.springframework.aop.TargetClassAware;
23  import org.springframework.aop.TargetSource;
24  
25  /**
26   * Interface to be implemented by classes that hold the configuration
27   * of a factory of AOP proxies. This configuration includes the
28   * Interceptors and other advice, and Advisors, and the proxied interfaces.
29   *
30   * <p>Any AOP proxy obtained from Spring can be cast to this interface to
31   * allow manipulation of its AOP advice.
32   *
33   * @author Rod Johnson
34   * @author Juergen Hoeller
35   * @since 13.03.2003
36   * @see org.springframework.aop.framework.AdvisedSupport
37   */
38  public interface Advised extends TargetClassAware {
39  
40      /**
41       * Return whether the Advised configuration is frozen,
42       * in which case no advice changes can be made.
43       */
44      boolean isFrozen();
45  
46      /**
47       * Are we proxying the full target class instead of specified interfaces?
48       */
49      boolean isProxyTargetClass();
50  
51      /**
52       * Return the interfaces proxied by the AOP proxy. Will not
53       * include the target class, which may also be proxied.
54       */
55      Class  [] getProxiedInterfaces();
56  
57      /**
58       * Determine whether the given interface is proxied.
59       * @param intf the interface to check
60       */
61      boolean isInterfaceProxied(Class   intf);
62  
63  
64      /**
65       * Change the TargetSource used by this Advised object.
66       * Only works if the configuration isn't frozen.
67       * @param targetSource new TargetSource to use
68       */
69      void setTargetSource(TargetSource targetSource);
70  
71      /**
72       * Return the TargetSource used by this Advised object.
73       */
74      TargetSource getTargetSource();
75  
76      /**
77       * Set whether the proxy should be exposed by the AOP framework as a
78       * ThreadLocal for retrieval via the AopContext class. This is useful
79       * if an advised object needs to call another advised method on itself.
80       * (If it uses <code>this</code>, the invocation will not be advised).
81       * <p>Default is "false", for optimal performance.
82       */
83      void setExposeProxy(boolean exposeProxy);
84  
85      /**
86       * Return whether the factory should expose the proxy as a ThreadLocal.
87       * This can be necessary if a target object needs to invoke a method on itself
88       * benefitting from advice. (If it invokes a method on <code>this</code> no advice
89       * will apply.) Getting the proxy is analogous to an EJB calling getEJBObject().
90       * @see AopContext
91       */
92      boolean isExposeProxy();
93  
94  
95      /**
96       * Return the advisors applying to this proxy.
97       * @return a list of Advisors applying to this proxy (never <code>null</code>)
98       */
99      Advisor[] getAdvisors();
100 
101     /**
102      * Add an advisor at the end of the advisor chain.
103      * <p>The Advisor may be an {@link org.springframework.aop.IntroductionAdvisor},
104      * in which new interfaces will be available when a proxy is next obtained
105      * from the relevant factory.
106      * @param advisor the advisor to add to the end of the chain
107      * @throws AopConfigException in case of invalid advice
108      */
109     void addAdvisor(Advisor advisor) throws AopConfigException;
110 
111     /** 
112      * Add an Advisor at the specified position in the chain.
113      * @param advisor the advisor to add at the specified position in the chain
114      * @param pos position in chain (0 is head). Must be valid.
115      * @throws AopConfigException in case of invalid advice
116      */
117     void addAdvisor(int pos, Advisor advisor) throws AopConfigException;
118 
119     /**
120      * Remove the given advisor.
121      * @param advisor the advisor to remove
122      * @return <code>true</code> if the advisor was removed; <code>false</code>
123      * if the advisor was not found and hence could not be removed
124      */
125     boolean removeAdvisor(Advisor advisor);
126 
127     /**
128      * Remove the advisor at the given index.
129      * @param index index of advisor to remove
130      * @throws AopConfigException if the index is invalid
131      */
132     void removeAdvisor(int index) throws AopConfigException;
133 
134     /**
135      * Return the index (from 0) of the given advisor,
136      * or -1 if no such advisor applies to this proxy.
137      * <p>The return value of this method can be used to index into the advisors array.
138      * @param advisor the advisor to search for
139      * @return index from 0 of this advisor, or -1 if there's no such advisor
140      */
141     int indexOf(Advisor advisor);
142 
143     /**
144      * Replace the given advisor.
145      * <p><b>Note:</b> If the advisor is an {@link org.springframework.aop.IntroductionAdvisor}
146      * and the replacement is not or implements different interfaces, the proxy will need
147      * to be re-obtained or the old interfaces won't be supported and the new interface
148      * won't be implemented.
149      * @param a the advisor to replace
150      * @param b the advisor to replace it with
151      * @return whether it was replaced. If the advisor wasn't found in the
152      * list of advisors, this method returns <code>false</code> and does nothing.
153      * @throws AopConfigException in case of invalid advice
154      */
155     boolean replaceAdvisor(Advisor a, Advisor b) throws AopConfigException;
156 
157 
158     /**
159      * Add the given AOP Alliance advice to the tail of the advice (interceptor) chain.
160      * <p>This will be wrapped in a DefaultPointcutAdvisor with a pointcut that always
161      * applies, and returned from the <code>getAdvisors()</code> method in this wrapped form.
162      * <p>Note that the given advice will apply to all invocations on the proxy,
163      * even to the <code>toString()</code> method! Use appropriate advice implementations
164      * or specify appropriate pointcuts to apply to a narrower set of methods.
165      * @param advice advice to add to the tail of the chain
166      * @throws AopConfigException in case of invalid advice
167      * @see #addAdvice(int, Advice)
168      * @see org.springframework.aop.support.DefaultPointcutAdvisor
169      */
170     void addAdvice(Advice advice) throws AopConfigException;
171 
172     /**
173      * Add the given AOP Alliance Advice at the specified position in the advice chain.
174      * <p>This will be wrapped in a {@link org.springframework.aop.support.DefaultPointcutAdvisor}
175      * with a pointcut that always applies, and returned from the {@link #getAdvisors()}
176      * method in this wrapped form.
177      * <p>Note: The given advice will apply to all invocations on the proxy,
178      * even to the <code>toString()</code> method! Use appropriate advice implementations
179      * or specify appropriate pointcuts to apply to a narrower set of methods.
180      * @param pos index from 0 (head)
181      * @param advice advice to add at the specified position in the advice chain
182      * @throws AopConfigException in case of invalid advice
183      */
184     void addAdvice(int pos, Advice advice) throws AopConfigException;
185 
186     /**
187      * Remove the Advisor containing the given advice.
188      * @param advice the advice to remove
189      * @return <code>true</code> of the advice was found and removed;
190      * <code>false</code> if there was no such advice
191      */
192     boolean removeAdvice(Advice advice);
193 
194     /**
195      * Return the index (from 0) of the given AOP Alliance Advice,
196      * or -1 if no such advice is an advice for this proxy.
197      * <p>The return value of this method can be used to index into
198      * the advisors array.
199      * @param advice AOP Alliance advice to search for
200      * @return index from 0 of this advice, or -1 if there's no such advice
201      */
202     int indexOf(Advice advice);
203 
204 
205     /**
206      * As <code>toString()</code> will normally be delegated to the target,
207      * this returns the equivalent for the AOP proxy.
208      * @return a string description of the proxy configuration
209      */
210     String   toProxyConfigString();
211 
212 }
213
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags