Class Proxy

This class allows you to dynamically create an instance of any (or even multiple) interfaces by reflection, and decide at runtime how that instance will behave by giving it an appropriate {@link InvocationHandler}. Proxy classes serialize specially, so that the proxy object can be reused between VMs, without requiring a persistent copy of the generated class code.

Creation

To create a proxy for some interface 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);
 

Dynamic Proxy Classes

A dynamic proxy class is created at runtime, and has the following properties:

• The class is public and final, and is neither abstract nor an inner class.
• The class has no canonical name (there is no formula you can use to determine or generate its name), but begins with the sequence "$Proxy". Abuse this knowledge at your own peril. (For now, '$' in user identifiers is legal, but it may not be that way forever. You weren't using '$' in your identifiers, were you?)
• The class extends Proxy, and explicitly implements all the interfaces specified at creation, in order (this is important for determining how method invocation is resolved). Note that a proxy class implements {@link Serializable}, at least implicitly, since Proxy does, but true serial behavior depends on using a serializable invocation handler as well.
• If at least one interface is non-public, the proxy class will be in the same package. Otherwise, the package is unspecified. This will work even if the package is sealed from user-generated classes, because Proxy classes are generated by a trusted source. Meanwhile, the proxy class belongs to the classloader you designated.
• Reflection works as expected: {@link Class#getInterfaces()} and {@link Class#getMethods()} work as they do on normal classes.
• The method {@link #isProxyClass(Class)} will distinguish between true proxy classes and user extensions of this class. It only returns true for classes created by {@link #getProxyClass}.
• The {@link ProtectionDomain} of a proxy class is the same as for bootstrap classes, such as Object or Proxy, since it is created by a trusted source. This protection domain will typically be granted {@link java.security.AllPermission}. But this is not a security risk, since there are adequate permissions on reflection, which is the only way to create an instance of the proxy class.
• The proxy class contains a single constructor, which takes as its only argument an {@link InvocationHandler}. The method {@link #newProxyInstance(ClassLoader, Class[], InvocationHandler)} is shorthand to do the necessary reflection.

Proxy Instances

A proxy instance is an instance of a proxy class. It has the following properties, many of which follow from the properties of a proxy class listed above:

• For a proxy class with Foo listed as one of its interfaces, the expression proxy instanceof Foo will return true, and the expression (Foo) proxy will succeed without a {@link ClassCastException}.
• Each proxy instance has an invocation handler, which can be accessed by {@link #getInvocationHandler(Object)}. Any call to an interface method, including {@link Object#hashCode()}, {@link Object#equals(Object)}, or {@link Object#toString()}, but excluding the public final methods of Object, will be encoded and passed to the {@link InvocationHandler#invoke} method of this handler.

Inheritance Issues

A proxy class may inherit a method from more than one interface. The order in which interfaces are listed matters, because it determines which reflected {@link Method} object will be passed to the invocation handler. This means that the dynamically generated class cannot determine through which interface a method is being invoked.

In short, if a method is declared in Object (namely, hashCode, equals, or toString), then Object will be used; otherwise, the leftmost interface that inherits or declares a method will be used, even if it has a more permissive throws clause than what the proxy class is allowed. Thus, in the invocation handler, it is not always safe to assume that every class listed in the throws clause of the passed Method object can safely be thrown; fortunately, the Proxy instance is robust enough to wrap all illegal checked exceptions in {@link UndeclaredThrowableException}.

Since: 1.3

See Also: InvocationHandler UndeclaredThrowableException Class

UNKNOWN: updated to 1.5, except for the use of ProtectionDomain

   Proxy.getProxyClass(loader, interfaces)
       .getConstructor(new Class[] {InvocationHandler.class})
       .newInstance(new Object[] {handler});