net.sf.cglib
Class Enhancer

java.lang.Object
  extended bynet.sf.cglib.core.AbstractClassGenerator
      extended bynet.sf.cglib.Enhancer
All Implemented Interfaces:
ClassGenerator

public class Enhancer
extends AbstractClassGenerator

Generates dynamic subclasses to enable method interception. This class started as a substitute for the standard Dynamic Proxy support included with JDK 1.3, but one that allowed the proxies to extend a concrete base class, in addition to implementing interfaces. The dynamically generated subclasses override the non-final methods of the superclass and have hooks which callback to user-defined interceptor implementations.

The original and most general callback type is the MethodInterceptor, which in AOP terms enables "around advice"--that is, you can invoke custom code both before and after the invocation of the "super" method. In addition you can modify the arguments before calling the super method, or not call it at all.

Although MethodInterceptor is generic enough to meet any interception need, it is often overkill. For simplicity and performance, additional specialized callback types, such as LazyLoader are also available. Often a single callback type will be used per enhanced class, but you can control which callback is used on a per-method basis with a CallbackFilter.

The most common uses of this class are embodied in the static helper methods. For advanced needs, such as customizing the ClassLoader to use, you should create a new instance of Enhancer. Other classes within CGLIB follow a similar pattern.

For an almost drop-in replacement for java.lang.reflect.Proxy, see the Proxy class.


Nested Class Summary
 
Nested classes inherited from class net.sf.cglib.core.AbstractClassGenerator
AbstractClassGenerator.Source
 
Constructor Summary
Enhancer()
          Create a new Enhancer.
 
Method Summary
 Factory create()
          Generate a new class if necessary and uses the specified callbacks (if any) to create a new object instance.
 Factory create(java.lang.Class[] argumentTypes, java.lang.Object[] arguments)
          Generate a new class if necessary and uses the specified callbacks (if any) to create a new object instance.
static Factory create(java.lang.Class type, Callback callback)
          Helper method to create an intercepted object.
static Factory create(java.lang.Class superclass, java.lang.Class[] interfaces, Callback callback)
          Helper method to create an intercepted object.
static Factory create(java.lang.Class superclass, java.lang.Class[] interfaces, CallbackFilter filter, Callbacks callbacks)
          Helper method to create an intercepted object.
 java.lang.Class createClass()
          Generate a new class if necessary and return it without creating a new instance.
protected  java.lang.Object firstInstance(java.lang.Class type)
           
 void generateClass(org.objectweb.asm.ClassVisitor v)
           
protected  java.lang.ClassLoader getDefaultClassLoader()
           
protected  java.lang.Object nextInstance(java.lang.Object instance)
           
 void setCallback(Callback callback)
          Set the single Callback to use.
 void setCallbackFilter(CallbackFilter filter)
          Set the CallbackFilter used to map the generated class' methods to a particular callback type.
 void setCallbacks(Callbacks callbacks)
          Register the callbacks to use when creating the new object instance.
 void setInterfaces(java.lang.Class[] interfaces)
          Set the interfaces to implement.
 void setSuperclass(java.lang.Class superclass)
          Set the class which the generated class will extend.
 
Methods inherited from class net.sf.cglib.core.AbstractClassGenerator
create, getClassLoader, getClassName, setClassLoader, setNamePrefix, setNamingPolicy, setTransformer
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

Enhancer

public Enhancer()
Create a new Enhancer. A new Enhancer object should be used for each generated object, and should not be shared across threads. To create additional instances of a generated class, use the Factory interface.

See Also:
Factory
Method Detail

setSuperclass

public void setSuperclass(java.lang.Class superclass)
Set the class which the generated class will extend. As a convenience, if the supplied superclass is actually an interface, setInterfaces will be called with the appropriate argument instead. Non-interfaces arguments must not be declared as final, and must have an accessible constructor.

Parameters:
superclass - class to extend or interface to implement
See Also:
setInterfaces(Class[])

setInterfaces

public void setInterfaces(java.lang.Class[] interfaces)
Set the interfaces to implement. The Factory interface will always be implemented regardless of what is specified here.

Parameters:
interfaces - array of interfaces to implement, or null
See Also:
Factory

setCallbackFilter

public void setCallbackFilter(CallbackFilter filter)
Set the CallbackFilter used to map the generated class' methods to a particular callback type. See the Callbacks interface for a description of the various callback types. New object instances will always use the same mapping, but may use different actual callback objects.

Parameters:
filter - the callback filter to use when generating a new class
See Also:
Callbacks

setCallback

public void setCallback(Callback callback)
Set the single Callback to use. This will override any CallbackFilter that has been specified previously, and ensure that every applicable method is mapped to the given callback object. Ignored if you use createClass.

Parameters:
callback - the callback to use for all methods
See Also:
setCallbackFilter(net.sf.cglib.CallbackFilter), setCallbacks(net.sf.cglib.Callbacks), createClass()

setCallbacks

public void setCallbacks(Callbacks callbacks)
Register the callbacks to use when creating the new object instance. For each callback type (see Callbacks) returned by the registered CallbackFilter, the Callbacks argument should return a non-null Callback implementation (where applicable--for instance the Callbacks.NO_OP type does not have an associated implementation). Ignored if you use createClass.

Parameters:
callbacks - callback implementations to use for the enhanced object
See Also:
SimpleCallbacks, setCallbackFilter(net.sf.cglib.CallbackFilter), createClass()

create

public Factory create()
Generate a new class if necessary and uses the specified callbacks (if any) to create a new object instance. Uses the no-arg constructor of the superclass.

Returns:
a new instance

create

public Factory create(java.lang.Class[] argumentTypes,
                      java.lang.Object[] arguments)
Generate a new class if necessary and uses the specified callbacks (if any) to create a new object instance. Uses the constructor of the superclass matching the argumentTypes parameter, with the given arguments.

Parameters:
argumentTypes - constructor signature
arguments - compatible wrapped arguments to pass to constructor
Returns:
a new instance

createClass

public java.lang.Class createClass()
Generate a new class if necessary and return it without creating a new instance. This ignores any callbacks that have been set. To create a new instance you will have to use reflection, and methods called during the constructor will not be intercepted. To avoid this problem, use the multi-arg create method.

See Also:
create(Class[], Object[])

getDefaultClassLoader

protected java.lang.ClassLoader getDefaultClassLoader()
Specified by:
getDefaultClassLoader in class AbstractClassGenerator

generateClass

public void generateClass(org.objectweb.asm.ClassVisitor v)
                   throws java.lang.Exception
Throws:
java.lang.Exception

firstInstance

protected java.lang.Object firstInstance(java.lang.Class type)
                                  throws java.lang.Exception
Specified by:
firstInstance in class AbstractClassGenerator
Throws:
java.lang.Exception

nextInstance

protected java.lang.Object nextInstance(java.lang.Object instance)
Specified by:
nextInstance in class AbstractClassGenerator

create

public static Factory create(java.lang.Class type,
                             Callback callback)
Helper method to create an intercepted object. For finer control over the generated instance, use a new instance of Enhancer instead of this static method.

Parameters:
type - class to extend or interface to implement
callback - the callback to use for all methods

create

public static Factory create(java.lang.Class superclass,
                             java.lang.Class[] interfaces,
                             Callback callback)
Helper method to create an intercepted object. For finer control over the generated instance, use a new instance of Enhancer instead of this static method.

Parameters:
interfaces - array of interfaces to implement, or null
callback - the callback to use for all methods

create

public static Factory create(java.lang.Class superclass,
                             java.lang.Class[] interfaces,
                             CallbackFilter filter,
                             Callbacks callbacks)
Helper method to create an intercepted object. For finer control over the generated instance, use a new instance of Enhancer instead of this static method.

Parameters:
interfaces - array of interfaces to implement, or null
filter - the callback filter to use when generating a new class
callbacks - callback implementations to use for the enhanced object


Copyright © 2002-2003 cglib. All Rights Reserved.