javassist.util.proxy

Class ProxyFactory

java.lang.Object

javassist.util.proxy.ProxyFactory

public class ProxyFactory
extends Object

Factory of dynamic proxy classes.

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 useCache to false. Caching may also be configured for a specific factory by calling instance method 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 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 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 ObjectOutputStream and deserialized from a corresponding 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 ProxyObjectOutputStream and ProxyObjectInputStream (which are subclasses of ObjectOutputStream and 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 useWriteReplace to false. Alternatively, it may be configured per factory by calling instance method setUseWriteReplace(boolean).

Since:

3.1

Author:

Muga Nishizawa, Shigeru Chiba, Andrew Dinn

See Also:

MethodHandler

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ProxyFactory.ClassLoaderProvider A provider of class loaders.

Field Summary

Fields

Modifier and Type	Field and Description
static ProxyFactory.ClassLoaderProvider	classLoaderProvider A provider used by createClass() for obtaining a class loader.
static boolean	useCache If true, a generated proxy class is cached and it will be reused when generating the proxy class with the same properties is requested.
static boolean	useWriteReplace If true, a generated proxy class will implement method writeReplace enabling serialization of its proxies to a conventional ObjectOutputStream.
String	writeDirectory If the value of this variable is not null, the class file of the generated proxy class is written under the directory specified by this variable.

Constructor Summary

Constructors

Constructor and Description
ProxyFactory() Constructs a factory of proxy class.

Method Summary

Methods

Modifier and Type	Method and Description
Object	create(Class[] paramTypes, Object[] args) Creates a proxy class and returns an instance of that class.
Object	create(Class[] paramTypes, Object[] args, MethodHandler mh) Creates a proxy class and returns an instance of that class.
Class	createClass() Generates a proxy class using the current filter.
Class	createClass(MethodFilter filter) Generates a proxy class using the supplied filter.
protected ClassLoader	getClassLoader()
protected ClassLoader	getClassLoader0()
protected ProtectionDomain	getDomain()
static MethodHandler	getHandler(Proxy p) Obtains the method handler of the given proxy object.
Class[]	getInterfaces() Obtains the interfaces set by setInterfaces.
String	getKey(Class superClass, Class[] interfaces, byte[] signature, boolean useWriteReplace)
Class	getSuperclass() Obtains the super class set by setSuperclass().
static boolean	isProxyClass(Class cl) determine if a class is a javassist proxy class
boolean	isUseCache() test whether this factory uses the proxy cache
boolean	isUseWriteReplace() test whether this factory installs a writeReplace method in created classes
void	setFilter(MethodFilter mf) Sets a filter that selects the methods that will be controlled by a handler.
void	setHandler(MethodHandler mi) Deprecated. since 3.12 use of this method is incompatible with proxy class caching. instead clients should call method Proxy.setHandler(MethodHandler) to set the handler for each newly created proxy instance. calling this method will automatically disable caching of classes created by the proxy factory.
void	setInterfaces(Class[] ifs) Sets the interfaces of a proxy class.
void	setSuperclass(Class clazz) Sets the super class of a proxy class.
void	setUseCache(boolean useCache) configure whether this factory should use the proxy cache
void	setUseWriteReplace(boolean useWriteReplace) configure whether this factory should add a writeReplace method to created classes

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

writeDirectory

public String writeDirectory

If the value of this variable is not null, the class file of the generated proxy class is written under the directory specified by this variable. For example, if the value is ".", then the class file is written under the current directory. This method is for debugging.

The default value is null.

useCache

public static volatile boolean useCache

If true, a generated proxy class is cached and it will be reused when generating the proxy class with the same properties is requested. The default value is true. Note that this value merely specifies the initial setting employed by any newly created proxy factory. The factory setting may be overwritten by calling factory instance method setUseCache(boolean)

Since:

3.4

useWriteReplace

public static volatile boolean useWriteReplace

If true, a generated proxy class will implement method writeReplace enabling serialization of its proxies to a conventional ObjectOutputStream. this (default) setting retains the old javassist behaviour which has the advantage that it retains compatibility with older releases and requires no extra work on the part of the client performing the serialization. However, it has the disadvantage that state inherited from the superclasses of the proxy is lost during serialization. if false then serialization/deserialization of the proxy instances will preserve all fields. However, serialization must be performed via a ProxyObjectOutputStream and deserialization must be via ProxyObjectInputStream. Any attempt to serialize proxies whose class was created with useWriteReplace set to false via a normal ObjectOutputStream will fail. Note that this value merely specifies the initial setting employed by any newly created proxy factory. The factory setting may be overwritten by calling factory instance method setUseWriteReplace(boolean)

Since:

3.4

classLoaderProvider

public static ProxyFactory.ClassLoaderProvider classLoaderProvider

A provider used by createClass() for obtaining a class loader. get() on this ClassLoaderProvider object is called to obtain a class loader.

The value of this field can be updated for changing the default implementation.

Example:

 ProxyFactory.classLoaderProvider = new ProxyFactory.ClassLoaderProvider() {
     public ClassLoader get(ProxyFactory pf) {
         return Thread.currentThread().getContextClassLoader();
     }
 };
 

Since:

3.4

Constructor Detail

ProxyFactory

public ProxyFactory()

Constructs a factory of proxy class.

Method Detail

isUseCache

public boolean isUseCache()

test whether this factory uses the proxy cache

Returns:

true if this factory uses the proxy cache otherwise false

setUseCache

public void setUseCache(boolean useCache)

configure whether this factory should use the proxy cache

Parameters:

useCache - true if this factory should use the proxy cache and false if it should not use the cache

Throws:

RuntimeException - if a default interceptor has been set for the factory

isUseWriteReplace

public boolean isUseWriteReplace()

test whether this factory installs a writeReplace method in created classes

Returns:

true if this factory installs a writeReplace method in created classes otherwise false

setUseWriteReplace

public void setUseWriteReplace(boolean useWriteReplace)

configure whether this factory should add a writeReplace method to created classes

Parameters:

useWriteReplace - true if this factory should add a writeReplace method to created classes and false if it should not add a writeReplace method

isProxyClass

public static boolean isProxyClass(Class cl)

determine if a class is a javassist proxy class

Parameters:

cl -

Returns:

true if the class is a javassist proxy class otherwise false

setSuperclass

public void setSuperclass(Class clazz)

Sets the super class of a proxy class.

getSuperclass

public Class getSuperclass()

Obtains the super class set by setSuperclass().

Since:

3.4

setInterfaces

public void setInterfaces(Class[] ifs)

Sets the interfaces of a proxy class.

getInterfaces

public Class[] getInterfaces()

Obtains the interfaces set by setInterfaces.

Since:

3.4

setFilter

public void setFilter(MethodFilter mf)

Sets a filter that selects the methods that will be controlled by a handler.

createClass

public Class createClass()

Generates a proxy class using the current filter.

createClass

public Class createClass(MethodFilter filter)

Generates a proxy class using the supplied filter.

getKey

public String getKey(Class superClass,
            Class[] interfaces,
            byte[] signature,
            boolean useWriteReplace)

getHandler

public static MethodHandler getHandler(Proxy p)

Obtains the method handler of the given proxy object.

Parameters:

p - a proxy object.

Returns:

the method handler.

Since:

3.16

getClassLoader

protected ClassLoader getClassLoader()

getClassLoader0

protected ClassLoader getClassLoader0()

getDomain

protected ProtectionDomain getDomain()

create

public Object create(Class[] paramTypes,
            Object[] args,
            MethodHandler mh)
              throws NoSuchMethodException,
                     IllegalArgumentException,
                     InstantiationException,
                     IllegalAccessException,
                     InvocationTargetException

Creates a proxy class and returns an instance of that class.

Parameters:

paramTypes - parameter types for a constructor.

args - arguments passed to a constructor.

mh - the method handler for the proxy class.

Throws:

NoSuchMethodException

IllegalArgumentException

InstantiationException

IllegalAccessException

InvocationTargetException

Since:

3.4

create

public Object create(Class[] paramTypes,
            Object[] args)
              throws NoSuchMethodException,
                     IllegalArgumentException,
                     InstantiationException,
                     IllegalAccessException,
                     InvocationTargetException

Creates a proxy class and returns an instance of that class.

Parameters:

paramTypes - parameter types for a constructor.

args - arguments passed to a constructor.

Throws:

NoSuchMethodException

IllegalArgumentException

InstantiationException

IllegalAccessException

InvocationTargetException

setHandler

public void setHandler(MethodHandler mi)

Deprecated. since 3.12 use of this method is incompatible with proxy class caching. instead clients should call method Proxy.setHandler(MethodHandler) to set the handler for each newly created proxy instance. calling this method will automatically disable caching of classes created by the proxy factory.

Sets the default invocation handler. This invocation handler is shared among all the instances of a proxy class unless another is explicitly specified.