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; - - - - /** - * the invocation handler for this proxy instance. - * @serial - */ - protected InvocationHandler h; - - /** - * Prohibits instantiation. - */ - private Proxy() { - } - - /** - * Constructs a new {@code Proxy} instance from a subclass - * (typically, a dynamic proxy class) with the specified value - * for its invocation handler. - * - * @param h the invocation handler for this proxy instance - */ - protected Proxy(InvocationHandler h) { - this.h = h; - } - - /** - * Returns the {@code java.lang.Class} object for a proxy class - * given a class loader and an array of interfaces. The proxy class - * will be defined by the specified class loader and will implement - * all of the supplied interfaces. If a proxy class for the same - * permutation of interfaces has already been defined by the class - * loader, then the existing proxy class will be returned; otherwise, - * a proxy class for those interfaces will be generated dynamically - * and defined by the class loader. - * - *
There are several restrictions on the parameters that may be - * passed to {@code Proxy.getProxyClass}: - * - *
- * Class.forName(i.getName(), false, cl) == i - *- * - *
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 - { - throw new IllegalArgumentException(); - } - - /** - * Returns an instance of a proxy class for the specified interfaces - * that dispatches method invocations to the specified invocation - * handler. This method is equivalent to: - *
- * Proxy.getProxyClass(loader, interfaces).
- * getConstructor(new Class[] { InvocationHandler.class }).
- * newInstance(new Object[] { handler });
- *
- *
- * {@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(); - } - throw new IllegalArgumentException(); - } - - /** - * 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 false; - } - - /** - * 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); -}