A ProxyFactory can be used to create three different "flavors" of proxy objects.

• Delegator - the proxy will delegate to an object provided by an {@link ObjectProvider}
• Interceptor - the proxy will pass each method invocation through an {@link Interceptor}
• Invoker - the proxy will allow an {@link Invoker} to handle all method invocations

Originally, the ProxyFactory class was an interface. However, to allow for future changes to the class without breaking binary or semantic compatibility, it has been changed to a concrete class.

Note: This class uses Java reflection. For more efficient proxies, try using either {@link org.apache.commons.proxy.factory.cglib.CglibProxyFactory CglibProxyFactory} or{@link org.apache.commons.proxy.factory.javassist.JavassistProxyFactory JavassistProxyFactory} instead.

@author James Carman @since 1.0

@version $Rev: 46019 $ $Date: 2004-09-14 04:56:06 -0500 (Tue, 14 Sep 2004) $

@version $Rev: 396405 $ $Date: 2006-04-24 05:53:26 +0200 (Mon, 24 Apr 2006) $

Creates proxies that implement Java interfaces and invocation handlers for fronting wires @version $$Rev: 628809 $$ $$Date: 2008-02-18 16:50:37 +0000 (Mon, 18 Feb 2008) $$

@deprecated Factory for {@link AMXProxy} proxies.

Contract for run-time, proxy-based lazy initialization proxies. @author Gavin King

re 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 {@link ProxyFactory#useCache} to false.Caching may also be configured for a specific factory by calling instance method {@link 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 {@link ProxyFactory#setHandler(MethodHandler)} is called. This method wasused 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 {@link Proxy#setHandler(MethodHandler)} as shown in the sample code above. Newclients are strongly recommended to use this model rather than calling {@link 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 {@link java.io.ObjectOutputStream} and deserialized from a corresponding{@link 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 {@link ProxyObjectOutputStream} and {@link ProxyObjectInputStream}(which are subclasses of {@link java.io.ObjectOutputStream} and {@link 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 {@link ProxyFactory#useWriteReplace} to false. Alternatively, it may beconfigured per factory by calling instance method {@link ProxyFactory#setUseWriteReplace(boolean)}. @author Muga Nishizawa @author Shigeru Chiba @author Andrew Dinn @see MethodHandler @since 3.1

Comment @author Bill Burke @version $Revision: 64133 $

Contract for a generic EJB3 Proxy Factory @author Bill Burke @author ALR @version $Revision: 80774 $

ProxyFactory Contract for a generic Proxy Factory, specifying a simple lifecycle and functions common to all Proxy Factories @author ALR @version $Revision: $

ProxyFactory Contract for a generic Proxy Factory, specifying a simple lifecycle and functions common to all Proxy Factories @author ALR @version $Revision: $

Defines the contract for a factory capable of creating implementation non-specific proxies. @author Jaikiran Pai @author ALR @version $Revision: $

re 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 {@link ProxyFactory#useCache} to false.Caching may also be configured for a specific factory by calling instance method {@link 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 {@link ProxyFactory#setHandler(MethodHandler)} is called. This method wasused 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 org.jboss.forge.furnace.proxy.javassist. Unfortunately,this legacy behaviour makes caching and reuse of proxy classes impossible. The current programming model expects org.jboss.forge.furnace.proxy.javassist clients to set the handler of a proxy instance explicitly by calling method {@link Proxy#setHandler(MethodHandler)} as shown in the sample code above. Newclients are strongly recommended to use this model rather than calling {@link 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 {@link java.io.ObjectOutputStream} and deserialized from a corresponding{@link 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 {@link org.jboss.forge.furnace.proxy.javassist.util.proxy.ProxyObjectOutputStream} and {@link org.jboss.forge.furnace.proxy.javassist.util.proxy.ProxyObjectInputStream}(which are subclasses of {@link java.io.ObjectOutputStream} and {@link java.io.ObjectInputStream}) to serialize and deserialize, respectively, the proxy. These streams recognise org.jboss.forge.furnace.proxy.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 {@link ProxyFactory#useWriteReplace} to false. Alternatively, it may beconfigured per factory by calling instance method {@link ProxyFactory#setUseWriteReplace(boolean)}. @see MethodHandler @since 3.1 @author Muga Nishizawa @author Shigeru Chiba @author Andrew Dinn

Proxy Factory that generates proxies that delegate all calls to an {@link InvocationHandler}.

Typical usage looks like:

 ProxyFactory<SimpleClass> proxyFactory = new ProxyFactory<SimpleClass>(SimpleClass.class); SimpleClass instance = proxyFactory.newInstance(new SimpleDispatcher()); 

This will create a proxy for SimpleClass, and return a new instance that handles invocations using the InvocationDispatcher SimpleDispatcher.

Invocations on these proxies are very efficient, as no reflection is involved. @author Stuart Douglas @param < T> the superclass type

ute the original method. } }; f.setFilter(new MethodFilter() { public boolean isHandled(Method m) { // ignore finalize() return !m.getName().equals("finalize"); } }); Class c = f.createClass(); Foo foo = (Foo)c.newInstance(); ((ProxyObject)foo).setHandler(mi);

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 mi2 = ... ;    // another handler ((ProxyObject)foo).setHandler(mi2); 

You can also specify the default method handler:

 ProxyFactory f2 = new ProxyFactory(); f2.setSuperclass(Foo.class); f2.setHandler(mi);            // set the default handler Class c2 = f2.createClass(); 

The default handler is implicitly attached to an instance of the generated class c2. Calling setHandler on the instance is not necessary unless another method handler must be attached to the instance.

The following code is an example of method handler. It does not execute anything except invoking the original method:

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

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

Factory for AOP proxies for programmatic use, rather than via a bean factory. This class provides a simple way of obtaining and configuring AOP proxies in code. @author Rod Johnson @author Juergen Hoeller @author Rob Harrop @since 14.03.2003