Practical Introduction into Code Injection with AspectJ, Javassist, and Java Proxy

Why You Are Going to Need It

• You're passing a collection of data to a closed-source library for processing and one method in the library fails for one of the elements but the exception provides no information about which element it was. You'd need to modify it to either log the offending argument or to include it in the exception. (And you can't use a debugger because it only happens on the production application server.)
• You need to collect performance statistics of important methods in your application including some of its closed-source components under the typical production load. (In the production you of course cannot use a profiler and you want to incur the minimal overhead.)
• You use JDBC to send a lot of data to a database in batches and one of the batch updates fails. You would need some nice way to find out which batch it was and what data it contained.

• Code injection enables you to modify binary classes for which you haven't the source codes
• The injected code can be used to collect various runtime information in environments where you cannot use the traditional development tools such as profilers and debuggers
• Don't Repeat Yourself: When you need the same piece of logic at multiple places, you can define it once and inject it into all those places.
• With code injection you do not modify the original source files so it is great for (possibly large-scale) changes that you need only for a limited period of time, especially with tools that make it possible to easily switch the code injection on and off (such as AspectJ with its load-time weaving). A typical case is performance metrics collection and increased logging during troubleshooting
• You can inject the code either statically, at the build time, or dynamically, when the target classes are being loaded by the JVM

Mini Glossary

Advice

The code to be injected. Typically we talk about before, after, and around advices, which are executed before, after, or instead of a target method. It's possible to make also other changes than injecting code into methods, e.g. adding fields or interfaces to a class.

AOP (Aspect Oriented Programming)

A programming paradigm claiming that "cross-cutting concerns" - the logic needed at many places, without a single class where to implement them - should be implemented once and injected into those places. Check Wikipedia for a better description.

Aspect

A unit of modularity in AOP, corresponds roughly to a class - it can contain different advices and pointcuts.

Joint point

A particular point in a program that might be the target of code injection, e.g. a method call or method entry.

Pointcut

Roughly spoken, a pointcut is an expression which tells a code injection tool where to inject a particular piece of code, i.e. to which joint points to apply a particular advice. It could select only a single such point - e.g. execution of a single method - or many similar points - e.g. executions of all methods marked with a custom annotation such as @MyBusinessMethod.

Weaving

The process of injecting code - advices - into the target places - joint points.

The Tools

Basic Classification of Code Injection Tools

I. Level of Abstraction

1. Direct bytecode manipulation (e.g. ASM) - to use these tools you need to understand the bytecode format of a class because they abstract very little from it, you work directly with opcodes, the operand stack and individual instructions. An ASM example:

   methodVisitor.visitFieldInsn(Opcodes.GETSTATIC, "java/lang/System", "out", "Ljava/io/PrintStream;");

   
   
   
   They are difficult to use due to being so low-level but are the most powerful. Usually they are used to implement higher-level tools and only few actually need to use them.
2. Intermediate level - code in strings, some abstraction of the classfile structure (Javassist)
3. Advices in Java (e.g. AspectJ) - the code to be injected is expressed as syntax-checked and statically compiled Java

1. Manual injection - you have to get somehow hold of the place where you want to inject the code (ASM, Javassist)
2. Primitive pointcuts - you have rather limited possibilities for expressing where to inject the code, for example to a particular method, to all public methods of a class or to all public methods of classes in a group (Java EE interceptors)
3. Pattern matching pointcut expressions - powerful expressions matching joint points based on a number of criteria with wildcards, awareness of the context (e.g. "called from a class in the package XY") etc. (AspectJ)

II. When the Magic Happens

• Manually at run-time - your code has to explicitly ask for the enhanced code, e.g. by manually instantiating a custom proxy wrapping the target object (this is arguably not true code injection)
• At load-time - the modification are performed when the target classes are being loaded by the JVM
• At build-time - you add an extra step to your build process to modify the compiled classes before packaging and deploying your application

III. What It Can Do

• Add code before/after/instead of a method - only member-level methods or also the static ones?
• Add fields to a class
• Add a new method
• Make a class to implement an interface
• Modify an instruction within the body of a method (e.g. a method call)
• Modify generics, annotations, access modifiers, change constant values, ...
• Remove method, field, etc.

Selected Code Injection Tools

1. Dynamic Java Proxy
2. The bytecode manipulation library ASM
3. JBoss Javassist
4. AspectJ
5. Spring AOP/proxies
6. Java EE interceptors

Practical Introduction to Java Proxy, Javassist and AspectJ

The Omnipresent Dynamic Java Proxy

• It's a part of JVM and thus is available everywhere
• You can use the same proxy - more exactly an InvocationHandler - for incompatible objects and thus reuse the code more than you could normally
• You save effort because you can easily forward all calls to a target object and only modify the ones interesting for you. If you were to implement a proxy manually, you would need to implement all the methods of the interface in question

• You can create a dynamic proxy only for an interface, you can't use it if your code expects a concrete class
• You have to instantiate and apply it manually, there is no magical auto-injection
• It's little too verbose
• Its power is very limited, it can only execute some code before/after/around a method

Example

class LoggingStatementDecorator implements InvocationHandler {

   private PreparedStatement target;
   ...

   private LoggingStatementDecorator(PreparedStatement target) { this.target = target; }

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

      try {
         Object result = method.invoke(target, args);
         updateLog(method, args); // remember data, reset upon successful execution
         return result;
      } catch (InvocationTargetException e) {
         Throwable cause = e.getTargetException();
         tryLogFailure(cause);
         throw cause;
      }

   }

   private void tryLogFailure(Throwable cause) {
      if (cause instanceof BatchUpdateException) {
         int failedBatchNr = successfulBatchCounter + 1;
         Logger.getLogger("JavaProxy").warning(
               "THE INJECTED CODE SAYS: " +
               "Batch update failed for batch# " + failedBatchNr +
               " (counting from 1) with values: [" +
               getValuesAsCsv() + "]. Cause: " + cause.getMessage());
      }
   }
...

• To create a proxy, you first need to implement an InvocationHandler and its invoke method, which is called whenever any of the interface's methods is invoked on the proxy
• You can access the information about the call via the java.lang.reflect.* objects and for example delegate the call to the proxied object via method.invoke

public static PreparedStatement createProxy(PreparedStatement target) {
  return (PreparedStatement) Proxy.newProxyInstance(
      PreparedStatement.class.getClassLoader(),
      new Class[] { PreparedStatement.class },
      new LoggingStatementDecorator(target));
};

• You can see that the newProxyInstance call takes a classloader, an array of interfaces that the proxy should implement, and the invocation handler that calls should be delegated to (the handler itself has to manage a reference to the proxied object, if it needs it)

...
PreparedStatement rawPrepStmt = connection.prepareStatement("...");
PreparedStatement loggingPrepStmt = LoggingStatementDecorator.createProxy(rawPrepStmt);
...
loggingPrepStmt.executeBatch();
...

• You see that we have to manually wrap a raw object with the proxy and use the proxy further on

Alternative Solutions

The Independent Javassist

• Code modified by Javassist doesn't require any new run-time dependencies, the injection happens at the build time and the injected advice code itself doesn't depend on any Javassist API
• Higher-level than bytecode manipulation libraries, the injected code is written in Java syntax, though enclosed in strings
• Can do most things that you may need such as "advising" method calls and method executions
• You can achieve both build-time injection (via Java code or a custom Ant task to do execution/call advising) and load-time injection (by implementing your own Java 5+ agent [thx to Anton])

• Still little too low-level and thus harder to use - you have to deal a little with structure of methods and the injected code is not syntax-checked
• Javassist has no tools to perform the injection and you thus have to implement your own injection code - including that there isn't support for injecting the code automatically based on a pattern

Example

public class JavassistInstrumenter {

   public void insertTimingIntoMethod(String targetClass, String targetMethod) throws NotFoundException, CannotCompileException, IOException {
      Logger logger = Logger.getLogger("Javassist");
      final String targetFolder = "./target/javassist";

      try {
         final ClassPool pool = ClassPool.getDefault();
         // Tell Javassist where to look for classes - into our ClassLoader
         pool.appendClassPath(new LoaderClassPath(getClass().getClassLoader()));
         final CtClass compiledClass = pool.get(targetClass);
         final CtMethod method = compiledClass.getDeclaredMethod(targetMethod);

         // Add something to the beginning of the method:
         method.addLocalVariable("startMs", CtClass.longType);
         method.insertBefore("startMs = System.currentTimeMillis();");
         // And also to its very end:
         method.insertAfter("{final long endMs = System.currentTimeMillis();" +
            "iterate.jz2011.codeinjection.javassist.PerformanceMonitor.logPerformance(\"" +
            targetMethod + "\",(endMs-startMs));}");

         compiledClass.writeFile(targetFolder);
         // Enjoy the new $targetFolder/iterate/jz2011/codeinjection/javassist/TargetClass.class

         logger.info(targetClass + "." + targetMethod +
               " has been modified and saved under " + targetFolder);
      } catch (NotFoundException e) {
         logger.warning("Failed to find the target class to modify, " +
               targetClass + ", verify that it ClassPool has been configured to look " +
               "into the right location");
      }
   }

   public static void main(String[] args) throws Exception {
      final String defaultTargetClass = "iterate.jz2011.codeinjection.javassist.TargetClass";
      final String defaultTargetMethod = "myMethod";
      final boolean targetProvided = args.length == 2;

      new JavassistInstrumenter().insertTimingIntoMethod(
            targetProvided? args[0] : defaultTargetClass
            , targetProvided? args[1] : defaultTargetMethod
      );
   }
}

• You can see the "low-levelness" - you have to explicitly deal with objects like CtClass, CtMethod, explicitly add a local variable etc.
• Javassist is rather flexible in where it can look for the classes to modify - it can search the classpath, a particular folder, a JAR file, or a folder with JAR files
• You would compile this class and run its main during your build process

Javassist on Steroids: GluonJ

• No run-time dependencies if build-time weaving used (load-time weaving requires the GluonJ agent library or gluonj.jar)
• Simple Java syntax using GlutonJ's annotation - though the custom syntax is also trivial to understand and easy to use
• Easy, automatic weaving into the target classes with GlutonJ's JAR tool, an Ant task or dynamically at the load-time
• Support for both build-time and load-time weaving

• An aspect can modify only a single class, you cannot inject the same piece of code to multiple classes/methods
• Limited power - only provides for field/method addition and execution of a code instead of/around a target method, either upon any of its executions or only if the execution happens in a particular context, i.e. when called from a particular class/method

The Almighty AspectJ

• Very powerful, can do nearly anything you might need
• Powerful pointcut expressions for defining where to inject an advice and when to activate it (including some run-time checks) - fully enables DRY, i.e. write once & inject many times
• Both build-time and load-time code injection (weaving)

• The modified code depends on the AspectJ runtime library
• The pointcut expressions are very powerful but it might be difficult to get them right and there isn't much support for "debugging" them though the AJDT plugin is partially able to visualize their effects
• It will likely take some time to get started though the basic usage is pretty simple (using @Aspect, @Around, and a simple pointcut expression, as we will see in the example)

Example

@Aspect
public class LoggingAspect {

   @Around("execution(private void TooQuiet3rdPartyClass.failingMethod(..))")
   public Object interceptAndLog(ProceedingJoinPoint invocation) throws Throwable {
      try {
         return invocation.proceed();
      } catch (Exception e) {
         Logger.getLogger("AspectJ").warning(
            "THE INJECTED CODE SAYS: the method " +
            invocation.getSignature().getName() + " failed for the input '" +
            invocation.getArgs()[0] + "'. Original exception: " + e);
         throw e;
      }
   }
}

• The aspect is a normal Java class with the @Aspect annotation, which is just a marker for AspectJ
• The @Around annotation instructs AspectJ to execute the method instead of the one matched by the expression, i.e. instead of the failingMethod of the TooQuiet3rdPartyClass
• The around advice method needs to be public, return an Object, and take a special AspectJ object carrying information about the invocation - ProceedingJoinPoint - as its argument and it may have an arbitrary name (Actually this is the minimal form of the signature, it could be more complex.)
• We use the ProceedingJoinPoint to delegate the call to the original target (an instance of the TooQuiet3rdPartyClass) and, in the case of an exception, to get the argument's value
• I've used an @Around advice though @AfterThrowing would be simpler and more appropriate but this shows better the capabilities of AspectJ and can be nicely compared to the dynamic java proxy example above

Alternative Solutions

The Dark Side

Fancy Uses of Code Injection and AOP

• Typical examples: Caching & et al (ex.: on AOP in JBoss Cache), transaction management, logging, enforcement of security, persistence, thread safety, error recovery, automatic implementation of methods (e.g. toString, equals, hashCode), remoting
• Implementation of role-based programming (e.g. OT/J, using BCEL) or the Data, Context, and Interaction architecture
• Testing
  • Test coverage - inject code to record whether a line has been executed during test run or not
  • Mutation testing (µJava, Jumble) - inject "random" mutation to the application and verify that the tests failed
  • Pattern Testing - automatic verification that Architecture/Design/Best practices recommendations are implemented correctly in the code via AOP
  • Simulate hardware/external failures by injecting the throwing of an exception
• Help to achieve zero turnaround for Java applications - JRebel uses an AOP-like approach for framework and server integration plugins - namely its plugins use Javassist for "binary patching"
• Solving though problems and avoiding monkey-coding with AOP patterns such as Worker Object Creation (turn direct calls into asynchronous with a Runnable and a ThreadPool/task queue) and Wormhole (make context information from a caller available to the callee without having to pass them through all the layers as parameters and without a ThreadLocal) - described in the book AspectJ in Action
• Dealing with legacy code - overriding the class instantiated on a call to a constructor (this and similar may be used to break tight-coupling with feasible amount of work), ensuring backwards-compatibility  o , teaching components to react properly on environment changes
• Preserving backwards-compatibility of an API while not blocking its ability to evolve e.g. by adding backwards-compatible methods when return types have been narrowed/widened (Bridge Method Injector - uses ASM) or by re-adding old methods and implementing them in terms of the new API
• Turning POJOs into JMX beans

Summary

Source Codes

git clone git://github.com/holyjak/JavaZone-Code-Injection.git
cd JavaZone-Code-Injection/
cat README
mvn -P javaproxy test
mvn -P javassist test
mvn -P aspectj   test

Additional Resources

• Spring's introduction into AOP
• dW: AOP@Work: AOP myths and realities 
• Chapter 1 of AspectJ in Action, 2nd. ed.

Acknowledgements