To create a proxy for some interface {@code Foo}: + *
+ * InvocationHandler handler = new MyInvocationHandler(...);
+ * Class proxyClass = Proxy.getProxyClass(
+ * Foo.class.getClassLoader(), new Class[] { Foo.class });
+ * Foo f = (Foo) proxyClass.
+ * getConstructor(new Class[] { InvocationHandler.class }).
+ * newInstance(new Object[] { handler });
+ *
+ * or more simply:
+ *
+ * Foo f = (Foo) Proxy.newProxyInstance(Foo.class.getClassLoader(),
+ * new Class[] { Foo.class },
+ * handler);
+ *
+ *
+ * A dynamic proxy class (simply referred to as a proxy + * class below) is a class that implements a list of interfaces + * specified at runtime when the class is created, with behavior as + * described below. + * + * A proxy interface is such an interface that is implemented + * by a proxy class. + * + * A proxy instance is an instance of a proxy class. + * + * Each proxy instance has an associated invocation handler + * object, which implements the interface {@link InvocationHandler}. + * A method invocation on a proxy instance through one of its proxy + * interfaces will be dispatched to the {@link InvocationHandler#invoke + * invoke} method of the instance's invocation handler, passing the proxy + * instance, a {@code java.lang.reflect.Method} object identifying + * the method that was invoked, and an array of type {@code Object} + * containing the arguments. The invocation handler processes the + * encoded method invocation as appropriate and the result that it + * returns will be returned as the result of the method invocation on + * the proxy instance. + * + *
A proxy class has the following properties: + * + *
A proxy instance has the following properties: + * + *
+ * {@code proxy instanceof Foo}
+ *
+ * and the following cast operation will succeed (rather than throwing
+ * a {@code ClassCastException}):
+ *
+ * {@code (Foo) proxy}
+ *
+ *
+ * When two or more interfaces of a proxy class contain a method with + * the same name and parameter signature, the order of the proxy class's + * interfaces becomes significant. When such a duplicate method + * is invoked on a proxy instance, the {@code Method} object passed + * to the invocation handler will not necessarily be the one whose + * declaring class is assignable from the reference type of the interface + * that the proxy's method was invoked through. This limitation exists + * because the corresponding method implementation in the generated proxy + * class cannot determine which interface it was invoked through. + * Therefore, when a duplicate method is invoked on a proxy instance, + * the {@code Method} object for the method in the foremost interface + * that contains the method (either directly or inherited through a + * superinterface) in the proxy class's list of interfaces is passed to + * the invocation handler's {@code invoke} method, regardless of the + * reference type through which the method invocation occurred. + * + *
If a proxy interface contains a method with the same name and + * parameter signature as the {@code hashCode}, {@code equals}, + * or {@code toString} methods of {@code java.lang.Object}, + * when such a method is invoked on a proxy instance, the + * {@code Method} object passed to the invocation handler will have + * {@code java.lang.Object} as its declaring class. In other words, + * the public, non-final methods of {@code java.lang.Object} + * logically precede all of the proxy interfaces for the determination of + * which {@code Method} object to pass to the invocation handler. + * + *
Note also that when a duplicate method is dispatched to an
+ * invocation handler, the {@code invoke} method may only throw
+ * checked exception types that are assignable to one of the exception
+ * types in the {@code throws} clause of the method in all of
+ * the proxy interfaces that it can be invoked through. If the
+ * {@code invoke} method throws a checked exception that is not
+ * assignable to any of the exception types declared by the method in one
+ * of the proxy interfaces that it can be invoked through, then an
+ * unchecked {@code UndeclaredThrowableException} will be thrown by
+ * the invocation on the proxy instance. This restriction means that not
+ * all of the exception types returned by invoking
+ * {@code getExceptionTypes} on the {@code Method} object
+ * passed to the {@code invoke} method can necessarily be thrown
+ * successfully by the {@code invoke} method.
+ *
+ * @author Peter Jones
+ * @see InvocationHandler
+ * @since 1.3
+ */
+public class Proxy implements java.io.Serializable {
+
+ private static final long serialVersionUID = -2222568056686623797L;
+
+ /** prefix for all proxy class names */
+ private final static String proxyClassNamePrefix = "$Proxy";
+
+ /** parameter types of a proxy class constructor */
+ private final static Class[] constructorParams =
+ { InvocationHandler.class };
+
+ /** maps a class loader to the proxy class cache for that loader */
+ private static Map There are several restrictions on the parameters that may be
+ * passed to {@code Proxy.getProxyClass}:
+ *
+ * If any of these restrictions are violated,
+ * {@code Proxy.getProxyClass} will throw an
+ * {@code IllegalArgumentException}. If the {@code interfaces}
+ * array argument or any of its elements are {@code null}, a
+ * {@code NullPointerException} will be thrown.
+ *
+ * Note that the order of the specified proxy interfaces is
+ * significant: two requests for a proxy class with the same combination
+ * of interfaces but in a different order will result in two distinct
+ * proxy classes.
+ *
+ * @param loader the class loader to define the proxy class
+ * @param interfaces the list of interfaces for the proxy class
+ * to implement
+ * @return a proxy class that is defined in the specified class loader
+ * and that implements the specified interfaces
+ * @throws IllegalArgumentException if any of the restrictions on the
+ * parameters that may be passed to {@code getProxyClass}
+ * are violated
+ * @throws NullPointerException if the {@code interfaces} array
+ * argument or any of its elements are {@code null}
+ */
+ public static Class getProxyClass(ClassLoader loader,
+ Class... interfaces)
+ throws IllegalArgumentException
+ {
+ if (interfaces.length > 65535) {
+ throw new IllegalArgumentException("interface limit exceeded");
+ }
+
+ Class proxyClass = null;
+
+ /* collect interface names to use as key for proxy class cache */
+ String[] interfaceNames = new String[interfaces.length];
+
+ // for detecting duplicates
+ Set {@code Proxy.newProxyInstance} throws
+ * {@code IllegalArgumentException} for the same reasons that
+ * {@code Proxy.getProxyClass} does.
+ *
+ * @param loader the class loader to define the proxy class
+ * @param interfaces the list of interfaces for the proxy class
+ * to implement
+ * @param h the invocation handler to dispatch method invocations to
+ * @return a proxy instance with the specified invocation handler of a
+ * proxy class that is defined by the specified class loader
+ * and that implements the specified interfaces
+ * @throws IllegalArgumentException if any of the restrictions on the
+ * parameters that may be passed to {@code getProxyClass}
+ * are violated
+ * @throws NullPointerException if the {@code interfaces} array
+ * argument or any of its elements are {@code null}, or
+ * if the invocation handler, {@code h}, is
+ * {@code null}
+ */
+ public static Object newProxyInstance(ClassLoader loader,
+ Class[] interfaces,
+ InvocationHandler h)
+ throws IllegalArgumentException
+ {
+ if (h == null) {
+ throw new NullPointerException();
+ }
+
+ /*
+ * Look up or generate the designated proxy class.
+ */
+ Class cl = getProxyClass(loader, interfaces);
+
+ /*
+ * Invoke its constructor with the designated invocation handler.
+ */
+ try {
+ Constructor cons = cl.getConstructor(constructorParams);
+ return cons.newInstance(new Object[] { h });
+ } catch (NoSuchMethodException e) {
+ throw new InternalError(e.toString());
+ } catch (IllegalAccessException e) {
+ throw new InternalError(e.toString());
+ } catch (InstantiationException e) {
+ throw new InternalError(e.toString());
+ } catch (InvocationTargetException e) {
+ throw new InternalError(e.toString());
+ }
+ }
+
+ /**
+ * Returns true if and only if the specified class was dynamically
+ * generated to be a proxy class using the {@code getProxyClass}
+ * method or the {@code newProxyInstance} method.
+ *
+ * The reliability of this method is important for the ability
+ * to use it to make security decisions, so its implementation should
+ * not just test if the class in question extends {@code Proxy}.
+ *
+ * @param cl the class to test
+ * @return {@code true} if the class is a proxy class and
+ * {@code false} otherwise
+ * @throws NullPointerException if {@code cl} is {@code null}
+ */
+ public static boolean isProxyClass(Class cl) {
+ if (cl == null) {
+ throw new NullPointerException();
+ }
+
+ return proxyClasses.containsKey(cl);
+ }
+
+ /**
+ * Returns the invocation handler for the specified proxy instance.
+ *
+ * @param proxy the proxy instance to return the invocation handler for
+ * @return the invocation handler for the proxy instance
+ * @throws IllegalArgumentException if the argument is not a
+ * proxy instance
+ */
+ public static InvocationHandler getInvocationHandler(Object proxy)
+ throws IllegalArgumentException
+ {
+ /*
+ * Verify that the object is actually a proxy instance.
+ */
+ if (!isProxyClass(proxy.getClass())) {
+ throw new IllegalArgumentException("not a proxy instance");
+ }
+
+ Proxy p = (Proxy) proxy;
+ return p.h;
+ }
+
+ private static native Class defineClass0(ClassLoader loader, String name,
+ byte[] b, int off, int len);
+}
+ *
+ *
+ *
+ * Class.forName(i.getName(), false, cl) == i
+ *
+ *
+ *
+ *
+ *
+ *
+ * Proxy.getProxyClass(loader, interfaces).
+ * getConstructor(new Class[] { InvocationHandler.class }).
+ * newInstance(new Object[] { handler });
+ *
+ *
+ *