01: /*
02: * JBoss, Home of Professional Open Source.
03: * Copyright 2006, Red Hat Middleware LLC, and individual contributors
04: * as indicated by the @author tags. See the copyright.txt file in the
05: * distribution for a full listing of individual contributors.
06: *
07: * This is free software; you can redistribute it and/or modify it
08: * under the terms of the GNU Lesser General Public License as
09: * published by the Free Software Foundation; either version 2.1 of
10: * the License, or (at your option) any later version.
11: *
12: * This software is distributed in the hope that it will be useful,
13: * but WITHOUT ANY WARRANTY; without even the implied warranty of
14: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15: * Lesser General Public License for more details.
16: *
17: * You should have received a copy of the GNU Lesser General Public
18: * License along with this software; if not, write to the Free
19: * Software Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA
20: * 02110-1301 USA, or see the FSF site: http://www.fsf.org.
21: */
22: package org.jboss.proxy.compiler;
23:
24: import java.lang.reflect.Method;
25:
26: /**
27: * An invoker is a target of method calls, where the calls are expressed
28: * not as primitive Java method invocations, but according to the conventions
29: * of the Core Reflection API.
30: * Invokers are designed to be used along with the Core Reflection API.
31: * <p>
32: * The Invoker.invoke operation is similar to java.lang.reflect.Method.invoke,
33: * except that the object (or objects) which receives the message is hidden
34: * behind the invoker. Also, unlike Method.invoke, the action of the
35: * Invoker.invoke operation is completely under programmer control,
36: * because Invoker.invoke is an interface method, not a native method.
37: * <p>
38: * You can wrap an invoker around an object so that the invoker passes
39: * all method calls down to the object. Such an invoker is called a
40: * <em>proxy invoker</em> for that object.
41: * <p>
42: * You can also wrap a new object around an invoker, so that the object
43: * implements some given interface (or interfaces), and passes all method
44: * calls up to the invoker.
45: * Such an object is called a <em>proxy target object</em> for that invoker.
46: * <p>
47: * You can do more complex tasks with invokers, such as passing each method
48: * call through a network connection before it reaches its target object.
49: * You can also filter or replicate method invocations. You can even
50: * execute the the invocations interpretively, without ever calling
51: * the method on a "real" Java object.
52: *
53: * @see Method#invoke
54: * @see Invoker#invoke
55: * @see Proxies#newInvoker
56: * @see Proxies#newTarget
57: *
58: * @author Unknown
59: * @version $Revision: 57209 $
60: */
61: public interface InvocationHandler {
62: /**
63: * Processes a method invocation on a proxy instance and returns the
64: * result.
65: *
66: * @param dummy ???
67: * @param method The method instance corresponding to the interface
68: * method invoked on the proxy instance.
69: * @param args An array of objects containing the values of the
70: * arguments passed in the method invocation on the proxy
71: * instance, or null if interface method takes no
72: * arguments.
73: * @return The value to return from the method invocation on
74: * the proxy instance.
75: *
76: * @throws Throwable The exception to throw from the method invocation
77: * on the proxy instance.
78: */
79: Object invoke(Object dummy, Method method, Object[] args)
80: throws Throwable;
81: }
|