001: /*
002: * Copyright 2002-2007 the original author or authors.
003: *
004: * Licensed under the Apache License, Version 2.0 (the "License");
005: * you may not use this file except in compliance with the License.
006: * You may obtain a copy of the License at
007: *
008: * http://www.apache.org/licenses/LICENSE-2.0
009: *
010: * Unless required by applicable law or agreed to in writing, software
011: * distributed under the License is distributed on an "AS IS" BASIS,
012: * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013: * See the License for the specific language governing permissions and
014: * limitations under the License.
015: */
016:
017: package org.springframework.aop.framework;
018:
019: import org.aopalliance.aop.Advice;
020:
021: import org.springframework.aop.Advisor;
022: import org.springframework.aop.TargetClassAware;
023: import org.springframework.aop.TargetSource;
024:
025: /**
026: * Interface to be implemented by classes that hold the configuration
027: * of a factory of AOP proxies. This configuration includes the
028: * Interceptors and other advice, and Advisors, and the proxied interfaces.
029: *
030: * <p>Any AOP proxy obtained from Spring can be cast to this interface to
031: * allow manipulation of its AOP advice.
032: *
033: * @author Rod Johnson
034: * @author Juergen Hoeller
035: * @since 13.03.2003
036: * @see org.springframework.aop.framework.AdvisedSupport
037: */
038: public interface Advised extends TargetClassAware {
039:
040: /**
041: * Return whether the Advised configuration is frozen,
042: * in which case no advice changes can be made.
043: */
044: boolean isFrozen();
045:
046: /**
047: * Are we proxying the full target class instead of specified interfaces?
048: */
049: boolean isProxyTargetClass();
050:
051: /**
052: * Return the interfaces proxied by the AOP proxy. Will not
053: * include the target class, which may also be proxied.
054: */
055: Class[] getProxiedInterfaces();
056:
057: /**
058: * Determine whether the given interface is proxied.
059: * @param intf the interface to check
060: */
061: boolean isInterfaceProxied(Class intf);
062:
063: /**
064: * Change the TargetSource used by this Advised object.
065: * Only works if the configuration isn't frozen.
066: * @param targetSource new TargetSource to use
067: */
068: void setTargetSource(TargetSource targetSource);
069:
070: /**
071: * Return the TargetSource used by this Advised object.
072: */
073: TargetSource getTargetSource();
074:
075: /**
076: * Set whether the proxy should be exposed by the AOP framework as a
077: * ThreadLocal for retrieval via the AopContext class. This is useful
078: * if an advised object needs to call another advised method on itself.
079: * (If it uses <code>this</code>, the invocation will not be advised).
080: * <p>Default is "false", for optimal performance.
081: */
082: void setExposeProxy(boolean exposeProxy);
083:
084: /**
085: * Return whether the factory should expose the proxy as a ThreadLocal.
086: * This can be necessary if a target object needs to invoke a method on itself
087: * benefitting from advice. (If it invokes a method on <code>this</code> no advice
088: * will apply.) Getting the proxy is analogous to an EJB calling getEJBObject().
089: * @see AopContext
090: */
091: boolean isExposeProxy();
092:
093: /**
094: * Set whether this proxy configuration is pre-filtered so that it only
095: * contains applicable advisors (matching this proxy's target class).
096: * <p>Default is "false". Set this to "true" if the advisors have been
097: * pre-filtered already, meaning that the ClassFilter check can be skipped
098: * when building the actual advisor chain for proxy invocations.
099: * @see org.springframework.aop.ClassFilter
100: */
101: void setPreFiltered(boolean preFiltered);
102:
103: /**
104: * Return whether this proxy configuration is pre-filtered so that it only
105: * contains applicable advisors (matching this proxy's target class).
106: */
107: boolean isPreFiltered();
108:
109: /**
110: * Return the advisors applying to this proxy.
111: * @return a list of Advisors applying to this proxy (never <code>null</code>)
112: */
113: Advisor[] getAdvisors();
114:
115: /**
116: * Add an advisor at the end of the advisor chain.
117: * <p>The Advisor may be an {@link org.springframework.aop.IntroductionAdvisor},
118: * in which new interfaces will be available when a proxy is next obtained
119: * from the relevant factory.
120: * @param advisor the advisor to add to the end of the chain
121: * @throws AopConfigException in case of invalid advice
122: */
123: void addAdvisor(Advisor advisor) throws AopConfigException;
124:
125: /**
126: * Add an Advisor at the specified position in the chain.
127: * @param advisor the advisor to add at the specified position in the chain
128: * @param pos position in chain (0 is head). Must be valid.
129: * @throws AopConfigException in case of invalid advice
130: */
131: void addAdvisor(int pos, Advisor advisor) throws AopConfigException;
132:
133: /**
134: * Remove the given advisor.
135: * @param advisor the advisor to remove
136: * @return <code>true</code> if the advisor was removed; <code>false</code>
137: * if the advisor was not found and hence could not be removed
138: */
139: boolean removeAdvisor(Advisor advisor);
140:
141: /**
142: * Remove the advisor at the given index.
143: * @param index index of advisor to remove
144: * @throws AopConfigException if the index is invalid
145: */
146: void removeAdvisor(int index) throws AopConfigException;
147:
148: /**
149: * Return the index (from 0) of the given advisor,
150: * or -1 if no such advisor applies to this proxy.
151: * <p>The return value of this method can be used to index into the advisors array.
152: * @param advisor the advisor to search for
153: * @return index from 0 of this advisor, or -1 if there's no such advisor
154: */
155: int indexOf(Advisor advisor);
156:
157: /**
158: * Replace the given advisor.
159: * <p><b>Note:</b> If the advisor is an {@link org.springframework.aop.IntroductionAdvisor}
160: * and the replacement is not or implements different interfaces, the proxy will need
161: * to be re-obtained or the old interfaces won't be supported and the new interface
162: * won't be implemented.
163: * @param a the advisor to replace
164: * @param b the advisor to replace it with
165: * @return whether it was replaced. If the advisor wasn't found in the
166: * list of advisors, this method returns <code>false</code> and does nothing.
167: * @throws AopConfigException in case of invalid advice
168: */
169: boolean replaceAdvisor(Advisor a, Advisor b)
170: throws AopConfigException;
171:
172: /**
173: * Add the given AOP Alliance advice to the tail of the advice (interceptor) chain.
174: * <p>This will be wrapped in a DefaultPointcutAdvisor with a pointcut that always
175: * applies, and returned from the <code>getAdvisors()</code> method in this wrapped form.
176: * <p>Note that the given advice will apply to all invocations on the proxy,
177: * even to the <code>toString()</code> method! Use appropriate advice implementations
178: * or specify appropriate pointcuts to apply to a narrower set of methods.
179: * @param advice advice to add to the tail of the chain
180: * @throws AopConfigException in case of invalid advice
181: * @see #addAdvice(int, Advice)
182: * @see org.springframework.aop.support.DefaultPointcutAdvisor
183: */
184: void addAdvice(Advice advice) throws AopConfigException;
185:
186: /**
187: * Add the given AOP Alliance Advice at the specified position in the advice chain.
188: * <p>This will be wrapped in a {@link org.springframework.aop.support.DefaultPointcutAdvisor}
189: * with a pointcut that always applies, and returned from the {@link #getAdvisors()}
190: * method in this wrapped form.
191: * <p>Note: The given advice will apply to all invocations on the proxy,
192: * even to the <code>toString()</code> method! Use appropriate advice implementations
193: * or specify appropriate pointcuts to apply to a narrower set of methods.
194: * @param pos index from 0 (head)
195: * @param advice advice to add at the specified position in the advice chain
196: * @throws AopConfigException in case of invalid advice
197: */
198: void addAdvice(int pos, Advice advice) throws AopConfigException;
199:
200: /**
201: * Remove the Advisor containing the given advice.
202: * @param advice the advice to remove
203: * @return <code>true</code> of the advice was found and removed;
204: * <code>false</code> if there was no such advice
205: */
206: boolean removeAdvice(Advice advice);
207:
208: /**
209: * Return the index (from 0) of the given AOP Alliance Advice,
210: * or -1 if no such advice is an advice for this proxy.
211: * <p>The return value of this method can be used to index into
212: * the advisors array.
213: * @param advice AOP Alliance advice to search for
214: * @return index from 0 of this advice, or -1 if there's no such advice
215: */
216: int indexOf(Advice advice);
217:
218: /**
219: * As <code>toString()</code> will normally be delegated to the target,
220: * this returns the equivalent for the AOP proxy.
221: * @return a string description of the proxy configuration
222: */
223: String toProxyConfigString();
224:
225: }
|