Explanation how CGLIB proxies work

 In my lastblog entry I explained how proxy based mock frameworks work and created my own demo mock framework based on CGLIB. Now I will explain how exactly the CGLIB proxy works. Because then you will understand why these things doesn't work with a proxy:

• intercept static method calls
• intercept private method calls
• intercept final method calls
• build a proxy for a final class

ASM

CGLIB is based on ASM. ASM is a library to create class files, on bytecode level, on the fly. So it's very low level and you need a good understanding of the bytecode to use it. But it abstracts the bytecode and is much more comfortable to generate bytecode with ASM than writing the bytecode itself. Because it takes care of the common structures like classes, constructors, method definitions and so on. One of the most helpful features is that it takes care about the constant pool. Because the constant pool holds many elements and you need to adapt it if you change anything. E.g. if a new method is added than you have to add the needed elements to the constant pool and increase the constant pool size. Or the labels in ASM are quite nice, too. Or that there are constants for the opcodes. After the complete class is generated, you have the bytecode of the class. This bytecode is passed into the ClassLoader which will load the class and then the class can be used.

How the generated CGLIB looks

Now you know how the generation of the proxy works. The question is how the generated proxy looks like. Actually it's quite simple. The proxy class extends the original class. All classes which should be intercepted by the proxy will be overridden. These methods will call the MethodInterceptor:: intercept method with the corresponding parameters. If the proxy callback is null than the super method will be called. Here is the code snippet for a simple echo(String) method:

public class at.rseiler.concept.mock.Foo$$EnhancerByCGLIB$$c0699eac

  extends at.rseiler.concept.mock.Foo

  implements org.mockito.cglib.proxy.Factory

{

  private static final org.mockito.cglib.proxy.MethodProxy CGLIB$echo$1$Proxy;

  private static final java.lang.reflect.Method CGLIB$echo$1$Method;

  // ...

  private org.mockito.cglib.proxy.MethodInterceptor CGLIB$CALLBACK_0;

  // ...

  public final String echo(String arg0) {

    if(CGLIB$CALLBACK_0 == null) {

      CGLIB$BIND_CALLBACKS(this);

    }

    if(CGLIB$CALLBACK_0 != null) {

      // MethodInterceptor::intercept(Object obj, Method method, Object[] args, MethodProxy proxy)

      Object obj = CGLIB$CALLBACK_0.intercept(this, GLIB$echo$0$Method, new Object[] {arg0}, CGLIB$echo$0$Proxy);

      if(!(obj instanceOf String)) {

        throw new ClassCastException();

      }

      return obj;

    }

    return super.echo(arg0);

  }

  private static final void CGLIB$BIND_CALLBACKS(java.lang.Object object) {

    /* compiled code */

  }

  // ...

}

Now you should understand the limits of the proxy (see above). The limits caused because the proxy is a subclass of the original class. Therefore it's not possible to extend a final class or final methods and so on. That's just basic Java limitations.
With code generation it's not possible to work around these limits. Sure it would be possible to generate a proxy class without the relationship to the original class. Than it would be possible to copy the whole class and insert the MethodInterceptor::intercept calls. This new class could remove all final keywords and make private methods public. The problem is that you can't call any method of this class without reflection. Because you don't have the type information of the "proxy" class at  compile time - clearly because the class is generated at runtime. Further you can't pass the "proxy" object to any constructor or any method because it's not a subclass.

The only way to break this limits is to do bytecode transformations of the original class before the ClassLoader loads the class. Before the class is loaded replace all private keywords with public keywords and to remove all final keywords. To do so you need to create your own ClassLoader which will performs the bytecode transformation. I don't know the code of PowerMock, but it must work like this.

At last the with javap --verbose decompiled bytecode of the echo(String) method from which I created the Java code above:

public final java.lang.String echo(java.lang.String);

flags: ACC_PUBLIC, ACC_FINAL

Code:

stack=7, locals=2, args_size=2

0: aload_0

1: getfield      #37                 // Field CGLIB$CALLBACK_0:Lorg/mockito/cglib/proxy/MethodInterceptor;

4: dup

5: ifnonnull     17

8: pop

9: aload_0

10: invokestatic  #41                 // Method CGLIB$BIND_CALLBACKS:(Ljava/lang/Object;)V

13: aload_0

14: getfield      #37                 // Field CGLIB$CALLBACK_0:Lorg/mockito/cglib/proxy/MethodInterceptor;

17: dup

18: ifnull        45

21: aload_0

22: getstatic     #64                 // Field CGLIB$echo$1$Method:Ljava/lang/reflect/Method;

25: iconst_1

26: anewarray     #66                 // class java/lang/Object

29: dup

30: iconst_0

31: aload_1

32: aastore

33: getstatic     #68                 // Field CGLIB$echo$1$Proxy:Lorg/mockito/cglib/proxy/MethodProxy;

36: invokeinterface #53,  5           // InterfaceMethod org/mockito/cglib/proxy/MethodInterceptor.intercept:(Ljava/lang/Object;Ljava/lang/reflect/Method;[Ljava/lang/Object;Lorg/mockito/cglib/proxy/MethodProxy;)Ljava/lang/Object;

41: checkcast     #55                 // class java/lang/String

44: areturn

45: aload_0

46: aload_1

47: invokespecial #62                 // Method at/rseiler/concept/mock/Foo.echo:(Ljava/lang/String;)Ljava/lang/String;

50: areturn

Explanation how proxy based Mock Frameworks work

Have you ever wondered how these Mockito lines work?

Foo foo = Mockito.mock(Foo.class);

Mockito.when(foo.echo("foo")).thenReturn("foo");

Yes or you are now interested? Great, then you should read this article. Otherwise you are probably lost and I can't help you. Sorry.

The first important thing to know is that there are two types of frameworks.

1. the proxy based mock frameworks: Mockito, EasyMock, jMock, ...
2. the mock frameworks based on bytecode manipulation: PowerMock, ...

There is a big different between those both concepts.

1. are much easier to implement but they are more restricted in the features they can support.
2. bytecode manipulation should tell you everything you should know about it: it's based on "very dark magic". It can break on major Java releases. So be careful if you start to use such frameworks, because they could prevent you from upgrade your Java version. PowerMock for example builds on top of Javassist. A framework which makes bytecode manipulation more simple.

In this article I will explain only how the proxy based mock frameworks like Mockito works. Because it's quite easy to understand how this kind of mock frameworks work. The knowledge will probably help you to use those frameworks if you know how they work and where the limits are. So you will never try to do anything which is technically impossible.

What is a Proxy?

A proxy is just an object which will be used instead of the original object. If a method of the proxy object is called then the proxy object can decide what it will do with this call:

• delegate it to the original object
• handles the call itself

Proxies can be used to implement some kind of permission system. The proxy checks if the user is allowed to call the method and if the user doesn't have the permission then it throws an exception.

A proxy doesn't require an instance of an interface/class if the proxy handles all method invocations itself.  
Mockito.mock(Foo.class) is now easily explained. This code just creates a proxy object for the Foo class.

Limits of a Proxy

There are a few important restrictions to the proxies. It's not possible to:

• intercept static method calls
• intercept private method calls
• intercept final method calls
• build a proxy for a final class

If you want to understand these limitations then read my other blog entry about: Explanation how CGLIP proxies work
Another restriction is that you have always to create the proxy explicitly. So it's not possible to say, that all Foo instances, created with new Foo() should be automatically wrapped into a proxy object. With PowerMock such things are possible. 

How to create a Proxy

If you look into the Java API you will find the java.lang.reflect.Proxy class. 

/**

* Returns an instance of a proxy class for the specified interfaces

* that dispatches method invocations to the specified invocation

* handler.

*

* @param   loader the class loader to define the proxy class

* @param   interfaces the list of interfaces for the proxy class to implement

* @param   h the invocation handler to dispatch method invocations to
Proxy.newProxyInstance(ClassLoader loader, Class<?>[] interfaces, InvocationHandler h)

It's quite simple to use. To showcase the usage of this proxy we just build our own simple mock framework - you find the complete source code at the end of the article. We create the static mock method which returns the proxy object.

public class Mock {

  public static <T> T mock(Class<T> clazz) {

    MockInvocationHandler invocationHandler = new MockInvocationHandler();

    T proxy = (T) Proxy.newProxyInstance(Mock.class.getClassLoader(), new Class[]{clazz}, invocationHandler);

    return proxy;

  }

}

This creates a proxy object for the clazz and redirects all calls to the MockInvocationHandler which looks like this:

private static class MockInvocationHandler implements InvocationHandler {

  @Override

  public Object invoke(Object proxy, Method method, Object[] args) throws Throwable {

    return null;

  }

}

So each call to a method of the proxy object will return null. At this stage we have an proxy object on which we can call methods. 

How to dynamically define the Proxy?

Now the question is how to setup the proxy to return something else than just null. We need to do something like: Mock.when(foo.echo("foo")).thenReturn("foo")

But how does this work? To understand how this work you have to analyze the one line of code very carefully and think about what it actually does. 

What does the when() method actually gets?

In the case of our example it would just gets a null object. In the first step we created the foo object which is a proxy which always return null. The when() method doesn't get the method echo() with a parameter. It's an common method call. It's a call to the proxy which will return null and pass the null value to the when() method. That's it. 

How the thenReturn() method works?

You have learned that the when() method just got null. So how can the thenReturn() call work? Think a few minutes about it. It's nothing special. It can be called at most "a little trick".

The solution is simple: with static variables in which the state is stored.

• in the MockInvocationHandler we store the method and the arguments of the last call
• in the Mock class - Mock.when(foo.echo("foo")).thenReturn("foo") - we store the reference to the MockInvocationHandler which was called last

These two steps happens in the invoke() method of the proxy object - in the MockInvocationHandler. The when() method doesn't have any logic. When thenReturn() is called then we store the return value for the stored (remembered) MockInvocationHandler with it's last method and arguments. If the proxy is called again then it will return the stored return value (if it's the same method gets called with the same parameter).

Basically that's it

I hope you could follow so far. I will summarize it again with other words

• create a proxy
• if a proxy method is called then remember which method was called. This proxy method call is normally located inside of the Mock.when() method - even if it has no relationship to the when() method.
• if thenReturn(value) is called store the "value" to the stored/remembered method.
• the proxy returns the "value" if the method is called again with the correct arguments.

The genius behind this is

The very simple API which makes the whole thing looks like very nice. Another great decision is that the when() method uses generics so that the thenReturn() method is type safe.

But what's about classes?

The current solution only works for interfaces. Because java.lang.reflect.Proxy only supports interfaces and not classes. So we need another mechanism to create the proxy. We have to dig a little be deeper and finally come to CGLIB - Code Generation Library. So we are back to magic. But it's by far not so dangerous like bytecode manipulation. We just use bytecode generation to create the proxy which shouldn't fail. In fact many tools are using CGLIB (e.g. Spring, Hibernate).

To create a proxy with CGLIB isn't any more difficult than with the Java`s Proxy class.

public static <T> T mock(Class<T> clazz) {

  Enhancer enhancer = new Enhancer();

  enhancer.setSuperclass(clazz);

  enhancer.setCallback(new MockMethodInterceptor());

  return (T) enhancer.create();

}

private static class MockMethodInterceptor {

  @Override

  public Object intercept(Object obj, Method method, Object[] args, MethodProxy proxy) throws Throwable {

    return null;

  }

}

That's it. Everything else stays the same.
With this kind of proxy you can easily build something like

Foo foo = new Foo();
foo = Mockito.spy(foo);
Mockito.when(foo.echo("foo")).thenReturn("bar");

You can create a proxy for a real object. All calls will be delegated to the real object expect if the method call is redefined. With CGLIB this is very easy to build. If you want to know more just take a look at the source code. 

Source Code

A simple mock framework to demonstrate how the proxy based mock frameworks work. With two implementations:

• based on the java.lang.reflect.Proxy.
• based on CGLIB. The CGLIB mock also implements the spy method.

Checkout the code from https://github.com/rseiler/concept-of-proxy-based-mock-frameworks

Mock Framework vs Anonymous Class for Unit Tests

I recently discussed at work what to use for unit tests: a mock framework (e.g. Mockito) or anonymous classes. Surprisingly for my only one person choose anonymous classes and there where many votes for the mock framework. I prefer myself the mock framework. 

The benefits of a mock framework:

• if you mock an interface within multiple tests with anonymous classes and then you change the interface you have to touch all of these test files. Even if the new added method doesn't break the old tests.
• if the interface has many methods but you need only a few of them, the anonymous class still have to implement each method. So it's quite messy and doesn't help to read the code.
• sure your IDE will generate the anonymous class with all methods with one keystroke. But if you want to make explicit which method is used in the test than you have to rewrite all unnecessary methods to something like this: throw new RuntimeException("not implemented"). Because otherwise you can't decide if the test relies on the method to return null or it's not used for the test.
• the code navigation in the IDE (at least IntelliJ) gets messed up because of the anonymous test classes. If you want to jump to the method implementation of an interface and there is one class implementing the interface than IntelliJ will jump directly to the correct code (ctrl+shift+b). But if in the test classes the anonymous mock classes are defined than IntelliJ will show you all anonymous classes which are in this case completely uninteresting.
• mocks are cleaner to write. if you want different return values by different parameters than you just define them in two lines. In an anonymous class you have to use if/else.
• mocks are more powerful. You can verify if the methods got called with the right parameters and are called exactly x times.

There is just one downside of mock frameworks: you have to learn one of them. 

It pays off to learn a mock framework and to use it because of all the benefits you get from it (see above). I am currently using Mockito which has a very easy and clean API.