Overview

A project that contains utility classes that allow one to more easily interact with the Sun/Oracle Attach API present in JDK6 and later.

Notably, this utility allows users to obtain an instance of java.lang.instrument.Instrumentation for the local virtual machine. This simplifies writing and testing dynamic/runtime loaded agent code.

Instead of packaging JVM agents into jar files, one can instrument the running VM directly at any point during runtime without having to modify JVM arguments.

When combined with a bytecode manipulation library like ASM, one can write powerful tooling. Examples of tools that use JVM agents include AspectJ, JRebel and spring-loaded.

Example

An example of using the LocalInstrumentationFactory to list all classes currently loaded by the JVM: package com.acme; import com.rrd.tools.attach.LocalInstrumentationFactory; public class ClassLister { public void printAllClassesInJVM(){ for(Class<?> loadedClass:LocalInstrumentationFactory.getLocalInstrumentation() .getAllLoadedClasses()){ System.out.println(loadedClass); } } }

Compatibility

The latest release of this utility has been tested on | Vendor | Version | Architecture | OS | |:-----------|:---------------|:-----------------|:------------------| | Oracle | JDK7 (all) | x86_64 | OSX | | Oracle | JDK7 (all) | i386 (32) | Windows XP |

The utility is however potentially backwards compatible with all Sun/Oracle JDK releases from 5.0 onwards. Other vendor JDKs have not been tested.

Maven

To import maven artficats for this library, the below repository must be first added to pom.xml: <repositories> ... <repository> <id>rrd-attach-uitl</id> <url>http://repo.rrd-attach-util.googlecode.com/git/</url> </repository> ... </repositories>

Artifacts can then be resolved using the below snippet: <dependencies> ... <dependency> <groupId>com.rrd.tools.attach</groupId> <artifactId>rrd-attach-util</artifactId> <version>1.0.1</version> </dependency> ... </dependencies>

Alternatives

There are a few options available if you really need to modify bytecode at runtime without using agents (or the attach API). One option is to load all of your classes in a ClassLoader that overrides the define method - similar to TomcatInstrumentableClassLoader. Another option is to load classes in parallel to those already loaded by using a bytecode manipulation toolkit (like ASM) to rename them, copying all fields, and intercepting all methods through a proxy. Any path one choses however, has its limitations.