Home > Articles > Programming > Java

  • Print
  • + Share This
This chapter is from the book


In the final section of this chapter, we will discuss proxies, a new feature that became available with version 1.3 of the Java SDK. You use a proxy to create new classes at runtime 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.


In versions 1.2 and below of the Java SDK, you encounter stub code in a number of 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 4 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 7 of Volume 2 for more information on Java beans.) It is expected that these mechanisms will be updated soon to take advantage of the proxy capability.

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 runtime. 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;

  • All methods defined in the Object class (toString, equals, and so on).

However, you cannot define new code for these methods at runtime. 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:

  1. A class loader. As part of the Java security model, it is possible to use different class loaders for system classes, classes that are downloaded from the Internet, and so on. We will discuss class loaders in Volume 2. For now, we will specify null to use the default class loader.

  2. An array of Class objects, one for each interface to be implemented.

  3. 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;

  • Tracing method calls for debugging purposes.

In our example program, we will 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 out 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 then the method is 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 out 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 = new Integer(i + 1);
   elements[i] = . . .; // proxy for value;

// construct a random integer
Random generator = new Random();
int r = generator.nextInt(elements.length);
Integer key = new Integer(r + 1);

// search for the key
int result = Arrays.binarySearch(elements, key);

// print match if found
if (result >= 0)

The Integer class implements the Comparable interface. The proxy objects belong to a class that is defined at runtime. (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.

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 out the method name and parameters and then invokes compareTo on the wrapped Integer object.

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


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:


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

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 is 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 the Java 2 SDK 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.

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.

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.

  • + Share This
  • 🔖 Save To Your Account