The
byte code instrumentation library
cglib is a popular choice among many well-known Java frameworks such as
Hibernate (
not anymore) or
Spring for doing their dirty work. Byte code instrumentation allows to manipulate or to create classes after the compilation phase of a Java application. Since Java classes are linked dynamically at run time, it is possible to add new classes to an already running Java program. Hibernate uses cglib for example for its generation of dynamic proxies. Instead of returning the full object that you stored ina a database, Hibernate will return you an instrumented version of your stored class that lazily loads some values from the database only when they are requested. Spring used cglib for example when adding security constraints to your method calls. Instead of calling your method directly, Spring security will first check if a specified security check passes and only delegate to your actual method after this verification. Another popular use of cglib is within mocking frameworks such as
mockito, where mocks are nothing more than instrumented class where the methods were replaced with empty implementations (plus some tracking logic).
Other than
ASM - another very high-level byte code manipulation library on top of which cglib is built - cglib offers rather low-level byte code transformers that can be used without even knowing about the details of a compiled Java class. Unfortunately, the documentation of cglib is rather short, not to say that there is basically none. Besides a
single blog article from 2005 that demonstrates the Enhancer class, there is not much to find. This blog article is an attempt to demonstrate cglib and its unfortunately often awkward API.
Enhancer
Let's start with the
Enhancer class, the probably most used class of the cglib library. An enhancer allows the creation of Java proxies for non-interface types. The
Enhancer can be compared with the Java standard library's
Proxy class which was introduced in Java 1.3. The
Enhancer dynamically creates a subclass of a given type but intercepts all method calls. Other than with the
Proxy class, this works for both class and interface types. The following example and some of the examples after are based on this simple Java POJO:
public class SampleClass {
public String test(String input) {
return "Hello world!";
}
}
Using cglib, the return value of
test(String) method can easily be replaced by another value using an
Enhancer and a
FixedValue callback:
@Test
public void testFixedValue() throws Exception {
Enhancer enhancer = new Enhancer();
enhancer.setSuperclass(SampleClass.class);
enhancer.setCallback(new FixedValue() {
@Override
public Object loadObject() throws Exception {
return "Hello cglib!";
}
});
SampleClass proxy = (SampleClass) enhancer.create();
assertEquals("Hello cglib!", proxy.test(null));
}
In the above example, the enhancer will return an instance of an instrumented subclass of
SampleClass where all method calls return a fixed value which is generated by the anonymous
FixedValue implementation above. The object is created by
Enhancer#create(Object...) where the method takes any number of arguments which are used to pick any constructor of the enhanced class. (Even though constructors are only methods on the Java byte code level, the
Enhancer class cannot instrument constructors. Neither can it instrument
static or
final classes.) If you only want to create a class, but no instance,
Enhancer#createClass will create a
Class instance which can be used to create instances dynamically. All constructors of the enhanced class will be available as delegation constructors in this dynamically generated class.
Be aware that any method call will be delegated in the above example, also calls to the methods defined in
java.lang.Object. As a result, a call to
proxy.toString() will also return "Hello cglib!". In contrast will a call to
proxy.hashCode() result in a
ClassCastException since the
FixedValue interceptor always returns a
String even though the
Object#hashCode signature requires a primitive integer.
Another observation that can be made is that final methods are not intercepted. An example of such a method is
Object#getClass which will return something like "SampleClass$$EnhancerByCGLIB$$e277c63c" when it is invoked. This class name is generated randomly by cglib in order to avoid naming conflicts. Be aware of the different class of the enhanced instance when you are making use of explicit types in your program code. The class generated by cglib will however be in the same package as the enhanced class (and therefore be able to override package-private methods). Similar to final methods, the subclassing approach makes for the inability of enhancing final classes. Therefore frameworks as Hibernate cannot persist final classes.
Next, let us look at a more powerful callback class, the
InvocationHandler, that can also be used with an
Enhancer:
@Test
public void testInvocationHandler() throws Exception {
Enhancer enhancer = new Enhancer();
enhancer.setSuperclass(SampleClass.class);
enhancer.setCallback(new InvocationHandler() {
@Override
public Object invoke(Object proxy, Method method, Object[] args)
throws Throwable {
if(method.getDeclaringClass() != Object.class && method.getReturnType() == String.class) {
return "Hello cglib!";
} else {
throw new RuntimeException("Do not know what to do.");
}
}
});
SampleClass proxy = (SampleClass) enhancer.create();
assertEquals("Hello cglib!", proxy.test(null));
assertNotEquals("Hello cglib!", proxy.toString());
}
This callback allows us to answer with regards to the invoked method. However, you should be careful when calling a method on the proxy object that comes with the
InvocationHandler#invoke method. All calls on this method will be dispatched with the same
InvocationHandler and might therefore result in an endless loop. In order to avoid this, we can use yet another callback dispatcher:
@Test
public void testMethodInterceptor() throws Exception {
Enhancer enhancer = new Enhancer();
enhancer.setSuperclass(SampleClass.class);
enhancer.setCallback(new MethodInterceptor() {
@Override
public Object intercept(Object obj, Method method, Object[] args, MethodProxy proxy)
throws Throwable {
if(method.getDeclaringClass() != Object.class && method.getReturnType() == String.class) {
return "Hello cglib!";
} else {
proxy.invokeSuper(obj, args);
}
}
});
SampleClass proxy = (SampleClass) enhancer.create();
assertEquals("Hello cglib!", proxy.test(null));
assertNotEquals("Hello cglib!", proxy.toString());
proxy.hashCode(); // Does not throw an exception or result in an endless loop.
}
The
MethodInterceptor allows full control over the intercepted method and offers some utilities for calling the method of the enhanced class in their original state. But why would one want to use other methods anyways? Because the other methods are more efficient and cglib is often used in edge case frameworks where efficiency plays a significant role. The creation and linkage of the
MethodInterceptor requires for example the generation of a different type of byte code and the creation of some runtime objects that are not required with the InvocationHandler. Because of that, there are other classes that can be used with the Enhancer:
LazyLoader: Even though the LazyLoader's only method has the same method signature as FixedValue, the LazyLoader is fundamentally different to the FixedValue interceptor. The LazyLoader is actually supposed to return an instance of a subclass of the enhanced class. This instance is requested only when a method is called on the enhanced object and then stored for future invocations of the generated proxy. This makes sense if your object is expensive in its creation without knowing if the object will ever be used. Be aware that some constructor of the enhanced class must be called both for the proxy object and for the lazily loaded object. Thus, make sure that there is another cheap (maybe protected) constructor available or use an interface type for the proxy. You can choose the invoked constructed by supplying arguments to Enhancer#create(Object...).Dispatcher: The Dispatcher is like the LazyLoader but will be invoked on every method call without storing the loaded object. This allows to change the implementation of a class without changing the reference to it. Again, be aware that some constructor must be called for both the proxy and the generated objects.ProxyRefDispatcher: This class carries a reference to the proxy object it is invoked from in its signature. This allows for example to delegate method calls to another method of this proxy. Be aware that this can easily cause an endless loop and will always cause an endless loop if the same method is called from within ProxyRefDispatcher#loadObject(Object).NoOp: The NoOp class does not what its name suggests. Instead, it delegates each method call to the enhanced class's method implementation.
At this point, the last two interceptors might not make sense to you. Why would you even want to enhance a class when you will always delegate method calls to the enhanced class anyways? And you are right. These interceptors should only be used together with a
CallbackFilter as it is demonstrated in the following code snippet:
@Test
public void testCallbackFilter() throws Exception {
Enhancer enhancer = new Enhancer();
CallbackHelper callbackHelper = new CallbackHelper(SampleClass.class, new Class[0]) {
@Override
protected Object getCallback(Method method) {
if(method.getDeclaringClass() != Object.class && method.getReturnType() == String.class) {
return new FixedValue() {
@Override
public Object loadObject() throws Exception {
return "Hello cglib!";
};
}
} else {
return NoOp.INSTANCE; // A singleton provided by NoOp.
}
}
};
enhancer.setSuperclass(MyClass.class);
enhancer.setCallbackFilter(callbackHelper);
enhancer.setCallbacks(callbackHelper.getCallbacks());
SampleClass proxy = (SampleClass) enhancer.create();
assertEquals("Hello cglib!", proxy.test(null));
assertNotEquals("Hello cglib!", proxy.toString());
proxy.hashCode(); // Does not throw an exception or result in an endless loop.
}
The
Enhancer instance accepts a
CallbackFilter in its
Enhancer#setCallbackFilter(CallbackFilter) method where it expects methods of the enhanced class to be mapped to array indices of an array of
Callback instances. When a method is invoked on the created proxy, the
Enhancer will then choose the according interceptor and dispatch the called method on the corresponding
Callback (which is a marker interface for all the interceptors that were introduced so far). To make this API less awkward, cglib offers a
CallbackHelper which will represent a
CallbackFilter and which can create an array of
Callbacks for you. The enhanced object above will be functionally equivalent to the one in the example for the
MethodInterceptor but it allows you to write specialized interceptors whilst keeping the dispatching logic to these interceptors separate.
How does it work?
When the
Enhancer creates a class, it will set create a
private static field for each interceptor that was registered as a
Callback for the enhanced class after its creation. This also means that class definitions that were created with cglib cannot be reused after their creation since the registration of callbacks does not become a part of the generated class's initialization phase but are prepared manually by cglib after the class was already initialized by the JVM. This also means that classes created with cglib are not technically ready after their initialization and for example cannot be sent over the wire since the callbacks would not exist for the class loaded in the target machine.
Depending on the registered interceptors, cglib might register additional fields such as for example for the
MethodInterceptor where two
private static fields (one holding a reflective
Method and a the other holding
MethodProxy) are registered per method that is intercepted in the enhanced class or any of its subclasses. Be aware that the
MethodProxy is making excessive use of the
FastClass which triggers the creation of additional classes and is described in further detail below.
For all these reasons, be careful when using the
Enhancer. And always register callback types defensively, since the
MethodInterceptor will for example trigger the creation of additional classes and register additional fields in the enhanced class. This is specifically dangerous since the callback variables are also stored in the enhancer's cache: This implies that the callback instances are
not garbage collected (unless all instances and the enhancer's
ClassLoader is, what is unusual). This is in particular dangerous when using anonymous classes which silently carry a reference to their outer class. Recall the example above:
@Test
public void testFixedValue() throws Exception {
Enhancer enhancer = new Enhancer();
enhancer.setSuperclass(SampleClass.class);
enhancer.setCallback(new FixedValue() {
@Override
public Object loadObject() throws Exception {
return "Hello cglib!";
}
});
SampleClass proxy = (SampleClass) enhancer.create();
assertEquals("Hello cglib!", proxy.test(null));
}
The anonymous subclass of
FixedValue would become hardly referenced from the enhanced
SampleClass such that neither the anonymous
FixedValue instance or the class holding the
@Test method would ever be garbage collected. This can introduce nasty memory leaks in your applications. Therefore, do not use non-
static inner classes with cglib. (I only use them in this blog entry for keeping the examples short.)
Finally, you should never intercept
Object#finalize(). Due to the subclassing approach of cglib, intercepting
finalize is implemented by overriding it what is
in general a bad idea. Enhanced instances that intercept finalize will be treated differently by the garbage collector and will also cause these objects being queued in the JVM's finalization queue. Also, if you (accidentally) create a hard reference to the enhanced class in your intercepted call to
finalize, you have effectively created an noncollectable instance. This is in general nothing you want. Note that
final methods are never intercepted by cglib. Thus,
Object#wait,
Object#notify and
Object#notifyAll do not impose the same problems. Be however aware that
Object#clone can be intercepted what is something you might not want to do.
Immutable bean
cglib's
ImmutableBean allows you to create an immutability wrapper similar to for example
Collections#immutableSet. All changes of the underlying bean will be prevented by an
IllegalStateException (however, not by an
UnsupportedOperationException as recommended by the Java API). Looking at some bean
public class SampleBean {
private String value;
public String getValue() {
return value;
}
public void setValue(String value) {
this.value = value;
}
}
we can make this bean immutable:
@Test(expected = IllegalStateException.class)
public void testImmutableBean() throws Exception {
SampleBean bean = new SampleBean();
bean.setValue("Hello world!");
SampleBean immutableBean = (SampleBean) ImmutableBean.create(bean);
assertEquals("Hello world!", immutableBean.getValue());
bean.setValue("Hello world, again!");
assertEquals("Hello world, again!", immutableBean.getValue());
immutableBean.setValue("Hello cglib!"); // Causes exception.
}
As obvious from the example, the immutable bean prevents all state changes by throwing an
IllegalStateException. However, the state of the bean can be changed by changing the original object. All such changes will be reflected by the
ImmutableBean.
Bean generator
The
BeanGenerator is another bean utility of cglib. It will create a bean for you at run time:
@Test
public void testBeanGenerator() throws Exception {
BeanGenerator beanGenerator = new BeanGenerator();
beanGenerator.addProperty("value", String.class);
Object myBean = beanGenerator.create();
Method setter = myBean.getClass().getMethod("setValue", String.class);
setter.invoke(myBean, "Hello cglib!");
Method getter = myBean.getClass().getMethod("getValue");
assertEquals("Hello cglib!", getter.invoke(myBean));
}
As obvious from the example, the
BeanGenerator first takes some properties as name value pairs. On creation, the
BeanGenerator creates the accessors
<type> get<name>()
void set<name>(<type>)
for you. This might be useful when another library expects beans which it resolved by reflection but you do not know these beans at run time. (An example would be
Apache Wicket which works a lot with beans.)
Bean copier
The
BeanCopier is another bean utility that copies beans by their property values. Consider another bean with similar properties as
SampleBean:
public class OtherSampleBean {
private String value;
public String getValue() {
return value;
}
public void setValue(String value) {
this.value = value;
}
}
Now you can copy properties from one bean to another:
@Test
public void testBeanCopier() throws Exception {
BeanCopier copier = BeanCopier.create(SampleBean.class, OtherSampleBean.class, false);
SampleBean bean = new SampleBean();
myBean.setValue("Hello cglib!");
OtherSampleBean otherBean = new OtherSampleBean();
copier.copy(bean, otherBean, null);
assertEquals("Hello cglib!", otherBean.getValue());
}
without being restrained to a specific type. The
BeanCopier#copy mehtod takles an (eventually) optional
Converter which allows to do some further manipulations on each bean property. If the
BeanCopier is created with false as the third constructor argument, the
Converter is ignored and can therefore be
null.
Bulk bean
A
BulkBean allows to use a specified set of a bean's accessors by arrays instead of method calls:
@Test
public void testBulkBean() throws Exception {
BulkBean bulkBean = BulkBean.create(SampleBean.class,
new String[]{"getValue"},
new String[]{"setValue"},
new Class[]{String.class});
SampleBean bean = new SampleBean();
bean.setValue("Hello world!");
assertEquals(1, bulkBean.getPropertyValues(bean).length);
assertEquals("Hello world!", bulkBean.getPropertyValues(bean)[0]);
bulkBean.setPropertyValues(bean, new Object[] {"Hello cglib!"});
assertEquals("Hello cglib!", bean.getValue());
}
The
BulkBean takes an array of getter names, an array of setter names and an array of property types as its constructor arguments. The resulting instrumented class can then extracted as an array by
BulkBean#getPropertyBalues(Object). Similarly, a bean's properties can be set by
BulkBean#setPropertyBalues(Object, Object[]).
Bean map
This is the last bean utility within the cglib library. The
BeanMap converts all properties of a bean to a
String-to-
Object Java
Map:
@Test
public void testBeanGenerator() throws Exception {
SampleBean bean = new SampleBean();
BeanMap map = BeanMap.create(bean);
bean.setValue("Hello cglib!");
assertEquals("Hello cglib", map.get("value"));
}
Additionally, the
BeanMap#newInstance(Object) method allows to create maps for other beans by reusing the same
Class.
Key factory
The
KeyFactory factory allows the dynamic creation of keys that are composed of multiple values that can be used in for example
Map implementations. For doing so, the
KeyFactory requires some interface that defines the values that should be used in such a key. This interface must contain a single method by the name newInstance that returns an
Object. For example:
public interface SampleKeyFactory {
Object newInstance(String first, int second);
}
Now an instance of a a key can be created by:
@Test
public void testKeyFactory() throws Exception {
SampleKeyFactory keyFactory = (SampleKeyFactory) KeyFactory.create(Key.class);
Object key = keyFactory.newInstance("foo", 42);
Map<Object, String> map = new HashMap<Object, String>();
map.put(key, "Hello cglib!");
assertEquals("Hello cglib!", map.get(keyFactory.newInstance("foo", 42)));
}
The
KeyFactory will assure the correct implementation of the
Object#equals(Object) and
Object#hashCode methods such that the resulting key objects can be used in a
Map or a
Set. The
KeyFactory is also used quite a lot internally in the cglib library.
Mixin
