java.lang.reflect
Class Proxy

java.lang.Object
  extended by java.lang.reflect.Proxy
All Implemented Interfaces:
Serializable

public class Proxy
extends Object
implements Serializable

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 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:

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:

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 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 UndeclaredThrowableException.

Since:
1.3
See Also:
InvocationHandler, UndeclaredThrowableException, Class, Serialized Form

Field Summary
protected  InvocationHandler h
          The invocation handler for this proxy instance.
 
Constructor Summary
protected Proxy(InvocationHandler handler)
          Constructs a new Proxy from a subclass (usually a proxy class), with the specified invocation handler.
 
Method Summary
static InvocationHandler getInvocationHandler(Object proxy)
          Returns the invocation handler for the given proxy instance.
static Class<?> getProxyClass(ClassLoader loader, Class<?>... interfaces)
          Returns the proxy Class for the given ClassLoader and array of interfaces, dynamically generating it if necessary.
static boolean isProxyClass(Class<?> clazz)
          Returns true if and only if the Class object is a dynamically created proxy class (created by getProxyClass or by the syntactic sugar of newProxyInstance).
static Object newProxyInstance(ClassLoader loader, Class<?>[] interfaces, InvocationHandler handler)
          Combines several methods into one.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

h

protected InvocationHandler h
The invocation handler for this proxy instance. For Proxy, this field is unused, but it appears here in order to be serialized in all proxy classes. NOTE: This implementation is more secure for proxy classes than what Sun specifies. Sun does not require h to be immutable, but this means you could change h after the fact by reflection. However, by making h immutable, we may break non-proxy classes which extend Proxy.

Constructor Detail

Proxy

protected Proxy(InvocationHandler handler)
Constructs a new Proxy from a subclass (usually a proxy class), with the specified invocation handler. NOTE: This throws a NullPointerException if you attempt to create a proxy instance with a null handler using reflection. This behavior is not yet specified by Sun; see Sun Bug 4487672.

Parameters:
handler - the invocation handler, may be null if the subclass is not a proxy class
Throws:
NullPointerException - if handler is null and this is a proxy instance
Method Detail

getProxyClass

public static Class<?> getProxyClass(ClassLoader loader,
                                     Class<?>... interfaces)
Returns the proxy Class for the given ClassLoader and array of interfaces, dynamically generating it if necessary.

There are several restrictions on this method, the violation of which will result in an IllegalArgumentException or NullPointerException:

Note that different orders of interfaces produce distinct classes.

Parameters:
loader - the class loader to define the proxy class in; null implies the bootstrap class loader
interfaces - the array of interfaces the proxy class implements, may be empty, but not null
Returns:
the Class object of the proxy class
Throws:
IllegalArgumentException - if the constraints above were violated, except for problems with null
NullPointerException - if `interfaces' is null or contains a null entry

newProxyInstance

public static Object newProxyInstance(ClassLoader loader,
                                      Class<?>[] interfaces,
                                      InvocationHandler handler)
Combines several methods into one. This is equivalent to:
   Proxy.getProxyClass(loader, interfaces)
       .getConstructor(new Class[] {InvocationHandler.class})
       .newInstance(new Object[] {handler});
 
except that it will not fail with the normal problems caused by reflection. It can still fail for the same reasons documented in getProxyClass, or if handler is null.

Parameters:
loader - the class loader to define the proxy class in; null implies the bootstrap class loader
interfaces - the array of interfaces the proxy class implements, may be empty, but not null
handler - the invocation handler, may not be null
Returns:
a proxy instance implementing the specified interfaces
Throws:
IllegalArgumentException - if the constraints for getProxyClass were violated, except for problems with null
NullPointerException - if `interfaces' is null or contains a null entry, or if handler is null
See Also:
getProxyClass(ClassLoader, Class[]), Class.getConstructor(Class[]), Constructor.newInstance(Object[])

isProxyClass

public static boolean isProxyClass(Class<?> clazz)
Returns true if and only if the Class object is a dynamically created proxy class (created by getProxyClass or by the syntactic sugar of newProxyInstance).

This check is secure (in other words, it is not simply clazz.getSuperclass() == Proxy.class), it will not be spoofed by non-proxy classes that extend Proxy.

Parameters:
clazz - the class to check, must not be null
Returns:
true if the class represents a proxy class
Throws:
NullPointerException - if clazz is null

getInvocationHandler

public static InvocationHandler getInvocationHandler(Object proxy)
Returns the invocation handler for the given proxy instance.

NOTE: We guarantee a non-null result if successful, but Sun allows the creation of a proxy instance with a null handler. See the comments for Proxy(InvocationHandler).

Parameters:
proxy - the proxy instance, must not be null
Returns:
the invocation handler, guaranteed non-null.
Throws:
IllegalArgumentException - if Proxy.isProxyClass(proxy.getClass()) returns false.
NullPointerException - if proxy is null