public Class ProxyFactory

This factory generates a class that extends the given super class and implements the given interfaces. The calls of the methods inherited from the super class are forwarded and then invoke() is called on the method handler associated with instances of the generated class. The calls of the methods from the interfaces are also forwarded to the method handler.

For example, if the following code is executed,

ProxyFactory f = new ProxyFactory();
f.setSuperclass(Foo.class);
f.setFilter(new MethodFilter() {
    public boolean isHandled(Method m) {
        // ignore finalize()
        return !m.getName().equals("finalize");
    }
});
Class c = f.createClass();
MethodHandler mi = new MethodHandler() {
    public Object invoke(Object self, Method m, Method proceed,
                         Object[] args) throws Throwable {
        System.out.println("Name: " + m.getName());
        return proceed.invoke(self, args);  // execute the original method.
    }
};
Foo foo = (Foo)c.newInstance();
((Proxy)foo).setHandler(mi);

Here, Method is java.lang.reflect.Method.

Then, the following method call will be forwarded to MethodHandler mi and prints a message before executing the originally called method bar() in Foo.

foo.bar();

The last three lines of the code shown above can be replaced with a call to the helper method create, which generates a proxy class, instantiates it, and sets the method handler of the instance:

    :
Foo foo = (Foo)f.create(new Class[0], new Object[0], mi);

To change the method handler during runtime, execute the following code:

MethodHandler mi = ... ;    // alternative handler
((Proxy)foo).setHandler(mi);

If setHandler is never called for a proxy instance then it will employ the default handler which proceeds by invoking the original method. The behaviour of the default handler is identical to the following handler:

class EmptyHandler implements MethodHandler {
    public Object invoke(Object self, Method m,
                         Method proceed, Object[] args) throws Exception {
        return proceed.invoke(self, args);
    }
}

A proxy factory caches and reuses proxy classes by default. It is possible to reset this default globally by setting static field ProxyFactory#useCache to false. Caching may also be configured for a specific factory by calling instance method ProxyFactory#setUseCache(boolean). It is strongly recommended that new clients of class ProxyFactory enable caching. Failure to do so may lead to exhaustion of the heap memory area used to store classes.

Caching is automatically disabled for any given proxy factory if deprecated instance method ProxyFactory#setHandler(MethodHandler) is called. This method was used to specify a default handler which newly created proxy classes should install when they create their instances. It is only retained to provide backward compatibility with previous releases of javassist. Unfortunately,this legacy behaviour makes caching and reuse of proxy classes impossible. The current programming model expects javassist clients to set the handler of a proxy instance explicitly by calling method Proxy#setHandler(MethodHandler) as shown in the sample code above. New clients are strongly recommended to use this model rather than calling ProxyFactory#setHandler(MethodHandler).

A proxy object generated by ProxyFactory is serializable if its super class or any of its interfaces implement java.io.Serializable. However, a serialized proxy object may not be compatible with future releases. The serialization support should be used for short-term storage or RMI.

For compatibility with older releases serialization of proxy objects is implemented by adding a writeReplace method to the proxy class. This allows a proxy to be serialized to a conventional java.io.ObjectOutputStream and deserialized from a corresponding java.io.ObjectInputStream. However this method suffers from several problems, the most notable one being that it fails to serialize state inherited from the proxy's superclass.

An alternative method of serializing proxy objects is available which fixes these problems. It requires inhibiting generation of the writeReplace method and instead using instances of javassist.util.proxy.ProxyObjectOutputStream and javassist.util.proxy.ProxyObjectInputStream (which are subclasses of java.io.ObjectOutputStream and java.io.ObjectInputStream) to serialize and deserialize, respectively, the proxy. These streams recognise javassist proxies and ensure that they are serialized and deserialized without the need for the proxy class to implement special methods such as writeReplace. Generation of the writeReplace method can be disabled globally by setting static field ProxyFactory#useWriteReplace to false. Alternatively, it may be configured per factory by calling instance method ProxyFactory#setUseWriteReplace(boolean).