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: * Return the advisors applying to this proxy.
095: * @return a list of Advisors applying to this proxy (never <code>null</code>)
096: */
097: Advisor[] getAdvisors();
098:
099: /**
100: * Add an advisor at the end of the advisor chain.
101: * <p>The Advisor may be an {@link org.springframework.aop.IntroductionAdvisor},
102: * in which new interfaces will be available when a proxy is next obtained
103: * from the relevant factory.
104: * @param advisor the advisor to add to the end of the chain
105: * @throws AopConfigException in case of invalid advice
106: */
107: void addAdvisor(Advisor advisor) throws AopConfigException;
108:
109: /**
110: * Add an Advisor at the specified position in the chain.
111: * @param advisor the advisor to add at the specified position in the chain
112: * @param pos position in chain (0 is head). Must be valid.
113: * @throws AopConfigException in case of invalid advice
114: */
115: void addAdvisor(int pos, Advisor advisor) throws AopConfigException;
116:
117: /**
118: * Remove the given advisor.
119: * @param advisor the advisor to remove
120: * @return <code>true</code> if the advisor was removed; <code>false</code>
121: * if the advisor was not found and hence could not be removed
122: */
123: boolean removeAdvisor(Advisor advisor);
124:
125: /**
126: * Remove the advisor at the given index.
127: * @param index index of advisor to remove
128: * @throws AopConfigException if the index is invalid
129: */
130: void removeAdvisor(int index) throws AopConfigException;
131:
132: /**
133: * Return the index (from 0) of the given advisor,
134: * or -1 if no such advisor applies to this proxy.
135: * <p>The return value of this method can be used to index into the advisors array.
136: * @param advisor the advisor to search for
137: * @return index from 0 of this advisor, or -1 if there's no such advisor
138: */
139: int indexOf(Advisor advisor);
140:
141: /**
142: * Replace the given advisor.
143: * <p><b>Note:</b> If the advisor is an {@link org.springframework.aop.IntroductionAdvisor}
144: * and the replacement is not or implements different interfaces, the proxy will need
145: * to be re-obtained or the old interfaces won't be supported and the new interface
146: * won't be implemented.
147: * @param a the advisor to replace
148: * @param b the advisor to replace it with
149: * @return whether it was replaced. If the advisor wasn't found in the
150: * list of advisors, this method returns <code>false</code> and does nothing.
151: * @throws AopConfigException in case of invalid advice
152: */
153: boolean replaceAdvisor(Advisor a, Advisor b)
154: throws AopConfigException;
155:
156: /**
157: * Add the given AOP Alliance advice to the tail of the advice (interceptor) chain.
158: * <p>This will be wrapped in a DefaultPointcutAdvisor with a pointcut that always
159: * applies, and returned from the <code>getAdvisors()</code> method in this wrapped form.
160: * <p>Note that the given advice will apply to all invocations on the proxy,
161: * even to the <code>toString()</code> method! Use appropriate advice implementations
162: * or specify appropriate pointcuts to apply to a narrower set of methods.
163: * @param advice advice to add to the tail of the chain
164: * @throws AopConfigException in case of invalid advice
165: * @see #addAdvice(int, Advice)
166: * @see org.springframework.aop.support.DefaultPointcutAdvisor
167: */
168: void addAdvice(Advice advice) throws AopConfigException;
169:
170: /**
171: * Add the given AOP Alliance Advice at the specified position in the advice chain.
172: * <p>This will be wrapped in a {@link org.springframework.aop.support.DefaultPointcutAdvisor}
173: * with a pointcut that always applies, and returned from the {@link #getAdvisors()}
174: * method in this wrapped form.
175: * <p>Note: The given advice will apply to all invocations on the proxy,
176: * even to the <code>toString()</code> method! Use appropriate advice implementations
177: * or specify appropriate pointcuts to apply to a narrower set of methods.
178: * @param pos index from 0 (head)
179: * @param advice advice to add at the specified position in the advice chain
180: * @throws AopConfigException in case of invalid advice
181: */
182: void addAdvice(int pos, Advice advice) throws AopConfigException;
183:
184: /**
185: * Remove the Advisor containing the given advice.
186: * @param advice the advice to remove
187: * @return <code>true</code> of the advice was found and removed;
188: * <code>false</code> if there was no such advice
189: */
190: boolean removeAdvice(Advice advice);
191:
192: /**
193: * Return the index (from 0) of the given AOP Alliance Advice,
194: * or -1 if no such advice is an advice for this proxy.
195: * <p>The return value of this method can be used to index into
196: * the advisors array.
197: * @param advice AOP Alliance advice to search for
198: * @return index from 0 of this advice, or -1 if there's no such advice
199: */
200: int indexOf(Advice advice);
201:
202: /**
203: * As <code>toString()</code> will normally be delegated to the target,
204: * this returns the equivalent for the AOP proxy.
205: * @return a string description of the proxy configuration
206: */
207: String toProxyConfigString();
208:
209: }
|