Proxies | Core Java(TM) 2, Volume I--Fundamentals (7th Edition) (Core Series) (Core Series)

In the final section of this chapter, we discuss proxies, a feature that became available with version 1.3 of the JDK. You use a proxy to create at run time new classes that implement a given set of interfaces. Proxies are only necessary when you don't yet know at compile time which interfaces you need to implement. This is not a common situation for application programmers. However, for certain system programming applications, the flexibility that proxies offer can be very important. By using proxies, you can often avoid the mechanical generation and compilation of "stub" code.

NOTE

Stub classes have been used in a number of specialized situations. When you use remote method invocation (RMI), a special utility called rmic produces stub classes that you need to add to your program. (See Chapter 5 of Volume 2 for more information on RMI.) And when you use the bean box, stub classes are produced and compiled on the fly when you connect beans to each other. (See Chapter 8 of Volume 2 for more information on Java beans.) As of JDK 5.0, the proxy facility is used to generate RMI stubs without having to run a utility.

Suppose you have an array of Class objects representing interfaces (maybe only containing a single interface), whose exact nature you may not know at compile time. Now you want to construct an object of a class that implements these interfaces. This is a difficult problem. If a Class object represents an actual class, then you can simply use the newInstance method or use reflection to find a constructor of that class. But you can't instantiate an interface. And you can't define new classes in a running program.

To overcome this problem, some programs such as the BeanBox in early versions of the Bean Development Kit generate code, place it into a file, invoke the compiler, and then load the resulting class file. Naturally, this is slow, and it also requires deployment of the compiler together with the program. The proxy mechanism is a better solution. The proxy class can create brand-new classes at run time. Such a proxy class implements the interfaces that you specify. In particular, the proxy class has the following methods:

All methods required by the specified interfaces; and
All methods defined in the Object class (toString, equals, and so on).

However, you cannot define new code for these methods at run time. Instead, you must supply an invocation handler. An invocation handler is an object of any class that implements the InvocationHandler interface. That interface has a single method:

 Object invoke(Object proxy, Method method, Object[] args)

Whenever a method is called on the proxy object, the invoke method of the invocation handler gets called, with the Method object and parameters of the original call. The invocation handler must then figure out how to handle the call.

To create a proxy object, you use the newProxyInstance method of the Proxy class. The method has three parameters:

A class loader. As part of the Java security model, different class loaders for system classes, classes that are downloaded from the Internet, and so on, can be used. We discuss class loaders in Volume 2. For now, we specify null to use the default class loader.
An array of Class objects, one for each interface to be implemented.
An invocation handler.

There are two remaining questions. How do we define the handler? And what can we do with the resulting proxy object? The answers depend, of course, on the problem that we want to solve with the proxy mechanism. Proxies can be used for many purposes, such as

Routing method calls to remote servers;
Associating user interface events with actions in a running program; and
Tracing method calls for debugging purposes.

In our example program, we use proxies and invocation handlers to trace method calls. We define a traceHandler wrapper class that stores a wrapped object. Its invoke method simply prints the name and parameters of the method to be called and then calls the method with the wrapped object as the implicit parameter.

 class TraceHandler implements InvocationHandler {    public TraceHandler(Object t)    {       target = t;    }    public Object invoke(Object proxy, Method m, Object[] args)       throws Throwable    {       // print method name and parameters       . . .       // invoke actual method       return m.invoke(target, args);    }    private Object target; }

Here is how you construct a proxy object that causes the tracing behavior whenever one of its methods is called.

 Object value = . . .; // construct wrapper InvocationHandler handler = new TraceHandler(value); // construct proxy for all interfaces Class[] interfaces = value.getClass().getInterfaces(); Object proxy = Proxy.newProxyInstance(null, interfaces, handler);

Now, whenever a method is called on proxy, the method name and parameters are printed out and the method is then invoked on value.

In the program shown in Example 6-7, we use proxy objects to trace a binary search. We fill an array with proxies to the integers 1 . . . 1000. Then we invoke the binarySearch method of the Arrays class to search for a random integer in the array. Finally, we print the matching element.

 Object[] elements = new Object[1000]; // fill elements with proxies for the integers 1  . . . 1000 for (int i = 0; i < elements.length; i++) {    Integer value = i + 1;    elements[i] = . . .; // proxy for value; } // construct a random integer Integer key = new Random().nextInt(elements.length) + 1; // search for the key int result = Arrays.binarySearch(elements, key); // print match if found if (result >= 0) System.out.println(elements[result]);

The Integer class implements the Comparable interface. The proxy objects belong to a class that is defined at run time. (It has a name such as $Proxy0.) That class also implements the Comparable interface. However, its compareTo method calls the invoke method of the proxy object's handler.

NOTE

As you saw earlier in this chapter, as of JDK 5.0, the Integer class actually implements Comparable<Integer>. However, at run time, all generic types are erased and the proxy is constructed with the class object for the raw Comparable class.

The binarySearch method makes calls like this:

 if (elements[i].compareTo(key) < 0) . . .

Because we filled the array with proxy objects, the compareTo calls call the invoke method of the traceHandler class. That method prints the method name and parameters and then invokes compareTo on the wrapped Integer object.

Finally, at the end of the sample program, we call

 System.out.println(elements[result]);

The println method calls toString on the proxy object, and that call is also redirected to the invocation handler.

Here is the complete trace of a program run:

 500.compareTo(288) 250.compareTo(288) 375.compareTo(288) 312.compareTo(288) 281.compareTo(288) 296.compareTo(288) 288.compareTo(288) 288.toString()

You can see how the binary search algorithm homes in on the key by cutting the search interval in half in every step.

Example 6-7. ProxyTest.java

  1. import java.lang.reflect.*;  2. import java.util.*;  3.  4. public class ProxyTest  5. {  6.    public static void main(String[] args)  7.    {  8.       Object[] elements = new Object[1000];  9. 10.       // fill elements with proxies for the integers 1 ... 1000 11.       for (int i = 0; i < elements.length; i++) 12.       { 13.          Integer value = i + 1; 14.          Class[] interfaces = value.getClass().getInterfaces(); 15.          InvocationHandler handler = new TraceHandler(value); 16.          Object proxy = Proxy.newProxyInstance(null, 17.             interfaces, handler); 18.          elements[i] = proxy; 19.       } 20. 21.       // construct a random integer 22.       Integer key = new Random().nextInt(elements.length) + 1; 23. 24.       // search for the key 25.       int result = Arrays.binarySearch(elements, key); 26. 27.       // print match if found 28.       if (result >= 0) System.out.println(elements[result]); 29.    } 30. } 31. 32. /** 33.    An invocation handler that prints out the method name 34.    and parameters, then invokes the original method 35. */ 36. class TraceHandler implements InvocationHandler 37. { 38.    /** 39.       Constructs a TraceHandler 40.       @param t the implicit parameter of the method call 41.    */ 42.    public TraceHandler(Object t) 43.    { 44.       target = t; 45.    } 46. 47.    public Object invoke(Object proxy, Method m, Object[] args) throws Throwable 48.    { 49.       // print implicit argument 50.       System.out.print(target); 51.       // print method name 52.       System.out.print("." + m.getName() + "("); 53.       // print explicit arguments 54.       if (args != null) 55.       { 56.          for (int i = 0; i < args.length; i++) 57.          { 58.             System.out.print(args[i]); 59.             if (i < args.length - 1) 60.                System.out.print(", "); 61.          } 62.       } 63.       System.out.println(")"); 64. 65.       // invoke actual method 66.       return m.invoke(target, args); 67.    } 68. 69.    private Object target; 70. }

Properties of Proxy Classes

Now that you have seen proxy classes in action, we want to go over some of their properties. Remember that proxy classes are created on the fly in a running program. However, once they are created, they are regular classes, just like any other classes in the virtual machine.

All proxy classes extend the class Proxy. A proxy class has only one instance variable the invocation handler, which is defined in the Proxy superclass. Any additional data that are required to carry out the proxy objects' tasks must be stored in the invocation handler. For example, when we proxied Comparable objects in the program shown in Example 6-7, the traceHandler wrapped the actual objects.

All proxy classes override the toString, equals, and hashCode methods of the Object class. Like all proxy methods, these methods simply call invoke on the invocation handler. The other methods of the Object class (such as clone and getClass) are not redefined.

The names of proxy classes are not defined. The Proxy class in Sun's virtual machine generates class names that begin with the string $Proxy.

There is only one proxy class for a particular class loader and ordered set of interfaces. That is, if you call the newProxyInstance method twice with the same class loader and interface array, then you get two objects of the same class. You can also obtain that class with the getProxyClass method:

 Class proxyClass = Proxy.getProxyClass(null, interfaces);

A proxy class is always public and final. If all interfaces that the proxy class implements are public, then the proxy class does not belong to any particular package. Otherwise, all non-public interfaces must belong to the same package, and then the proxy class also belongs to that package.

You can test whether a particular Class object represents a proxy class by calling the isProxyClass method of the Proxy class.

 java.lang.reflect.InvocationHandler 1.3

Object invoke(Object proxy, Method method, Object[] args)
define this method to contain the action that you want carried out whenever a method was invoked on the proxy object.

 java.lang.reflect.Proxy 1.3

static Class getProxyClass(ClassLoader loader, Class[] interfaces)
returns the proxy class that implements the given interfaces.
static Object newProxyInstance(ClassLoader loader, Class[] interfaces, InvocationHandler handler)
constructs a new instance of the proxy class that implements the given interfaces. All methods call the invoke method of the given handler object.
static boolean isProxyClass(Class c)
returns true if c is a proxy class.

This ends our final chapter on the fundamentals of the Java programming language. Interfaces and inner classes are concepts that you will encounter frequently. However, as we already mentioned, proxies are an advanced technique that is of interest mainly to tool builders, not application programmers. You are now ready to go on to learn about graphics and user interfaces, starting with Chapter 7.