To create a proxy for some interface {@code Foo}: *
* InvocationHandler handler = new MyInvocationHandler(...); * Class<?> proxyClass = Proxy.getProxyClass(Foo.class.getClassLoader(), Foo.class); * Foo f = (Foo) proxyClass.getConstructor(InvocationHandler.class). * newInstance(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;
/** parameter types of a proxy class constructor */
private static final Class[] constructorParams =
{ InvocationHandler.class };
/**
* a cache of proxy classes
*/
private static final WeakCache 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 SecurityException if a security manager, s, is present
* and any of the following conditions is met:
* {@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 SecurityException if a security manager, s, is present
* and any of the following conditions is met:
* 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) {
return Proxy.class.isAssignableFrom(cl) && proxyClassCache.containsValue(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
*
*
*
*
*
*
*
* @throws NullPointerException if the {@code interfaces} array
* argument or any of its elements are {@code null}
*/
@CallerSensitive
public static Class getProxyClass(ClassLoader loader,
Class... interfaces)
throws IllegalArgumentException
{
SecurityManager sm = System.getSecurityManager();
if (sm != null) {
checkProxyAccess(Reflection.getCallerClass(), loader, interfaces);
}
return getProxyClass0(loader, interfaces);
}
/*
* Check permissions required to create a Proxy class.
*
* To define a proxy class, it performs the access checks as in
* Class.forName (VM will invoke ClassLoader.checkPackageAccess):
* 1. "getClassLoader" permission check if loader == null
* 2. checkPackageAccess on the interfaces it implements
*
* To get a constructor and new instance of a proxy class, it performs
* the package access check on the interfaces it implements
* as in Class.getConstructor.
*
* If an interface is non-public, the proxy class must be defined by
* the defining loader of the interface. If the caller's class loader
* is not the same as the defining loader of the interface, the VM
* will throw IllegalAccessError when the generated proxy class is
* being defined via the defineClass0 method.
*/
private static void checkProxyAccess(Class caller,
ClassLoader loader,
Class... interfaces)
{
SecurityManager sm = System.getSecurityManager();
if (sm != null) {
ClassLoader ccl = caller.getClassLoader();
if (VM.isSystemDomainLoader(loader) && !VM.isSystemDomainLoader(ccl)) {
sm.checkPermission(SecurityConstants.GET_CLASSLOADER_PERMISSION);
}
ReflectUtil.checkProxyPackageAccess(ccl, interfaces);
}
}
/**
* Generate a proxy class. Must call the checkProxyAccess method
* to perform permission checks before calling this.
*/
private static Class getProxyClass0(ClassLoader loader,
Class... interfaces) {
if (interfaces.length > 65535) {
throw new IllegalArgumentException("interface limit exceeded");
}
// If the proxy class defined by the given loader implementing
// the given interfaces exists, this will simply return the cached copy;
// otherwise, it will create the proxy class via the ProxyClassFactory
return proxyClassCache.get(loader, interfaces);
}
/*
* a key used for proxy class with 0 implemented interfaces
*/
private static final Object key0 = new Object();
/*
* Key1 and Key2 are optimized for the common use of dynamic proxies
* that implement 1 or 2 interfaces.
*/
/*
* a key used for proxy class with 1 implemented interface
*/
private static final class Key1 extends WeakReference
*
* @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}
*/
@CallerSensitive
public static Object newProxyInstance(ClassLoader loader,
Class[] interfaces,
InvocationHandler h)
throws IllegalArgumentException
{
if (h == null) {
throw new NullPointerException();
}
final SecurityManager sm = System.getSecurityManager();
if (sm != null) {
checkProxyAccess(Reflection.getCallerClass(), loader, interfaces);
}
/*
* Look up or generate the designated proxy class.
*/
Class cl = getProxyClass0(loader, interfaces);
/*
* Invoke its constructor with the designated invocation handler.
*/
try {
if (sm != null) {
checkNewProxyPermission(Reflection.getCallerClass(), cl);
}
final Constructor cons = cl.getConstructor(constructorParams);
final InvocationHandler ih = h;
if (!Modifier.isPublic(cl.getModifiers())) {
AccessController.doPrivileged(new PrivilegedAction