Jiapi: Java Instrumentation API

What is Jiapi

When a Java virtual machine encounters a request for a class which hasn't been loaded to its memory, it consults a class loader to locate and load the class. Typically, the classes are loaded from a filesystem or URL as a bytecode array and then converted into an instance of class java.lang.Class within the virtual machine. Jiapi is a tool which can be used to alter this normal class loading behavior. Instead of letting the class to be loaded as it is, Jiapi is used to manipulate classes' bytecode. The manipulated class is then passed to a class loader which loads it into a Java virtual machine. In addition to just described just-in-time bytecode weaving, Jiapi can be used to instrument a class ahead-of-time. In this mode compiled classes are preprocessed by Jiapi instrumentors and modified classes are then serialized on a filesystem to be executed later.

This whole process can be arranged so that it is transparent to a class being manipulated. This transparency can be utilized by several types of applications:

  • Debugging tools Debugger could add tracing information in between the original bytecode of a class.
  • Profiling tools A profiling application could manipulate classes by adding "hooks" which can be caught at runtime to them. This way it is possible to analyze and visualize the runtime characteristics of a program without touching the code itself.
  • Aspect oriented programming tools AOP compilers could utilize Jiapi as a bytecode weaver.
  • etc...

The focus of a project is to provide:

  • a framework to implement instruments which manipulate Java bytecode
  • implementations for common bytecode manipulations
  • an abstraction for some of the details in bytecode structure
  • easy to use event based API and runtime hooks for application developers
  • instrumentation configuration tools
  • ClassLoaders utilizing bytecode instrumentation
  • class loading plugins for application servers

Jiapi realization can be viewed as a layered architecture where each layer is implemented on top the lower layer.

    +--------------------------------------+
    |         Applications                 |
    +-----------------------+              |
    | Jiapi instrumentation |              |  alt.jiapi.event, alt.jiapi.interceptor, alt.jiapi.jazzpect
    +-----------------------+-------+      |
    |       Jiapi reflection        |      |  alt.jiapi.reflect
    +-------------------------------+------+
    |       Jiapi file                     |  alt.jiapi.file
    +--------------------------------------+