The JVM (Java Virtual Machine) is an excellent platform for monkey-patching. Monkey patching is a technique used to dynamically update the behavior of a piece of code at run-time. A monkey patch (also spelled monkey-patch, MonkeyPatch) is a way to extend or modify the runtime code of dynamic languages ( Smalltalk, JavaScript, Objective-C, Ruby, Perl, Python, Groovy, etc.) without altering the original source code. e.g. -- Wikipedia I want to demo several approaches for monkey-patching in in this post. Java As an example, I'll use a sample for-loop. Imagine we have a class and a method. We want to call the method multiple times without doing it explicitly. The Decorator Design Pattern While the Decorator Design Pattern is not monkey-patching, it's an excellent introduction to it anyway. Decorator is a pattern described in the foundational book, Design Patterns: Elements of Reusable Object-Oriented Software. structural The decorator pattern is a design pattern that allows behavior to be added to an individual object, dynamically, without affecting the behavior of other objects from the same class. -- Decorator pattern Our use case is a interface with a dedicated console implementation: Logger We can implement it in Java like this: public interface Logger {
    void log(String message);
}

public class ConsoleLogger implements Logger {
    @Override
    public void log(String message) {
        System.out.println(message);
    }
} Here's a simple, configurable decorator implementation: public class RepeatingDecorator implements Logger {        //1

    private final Logger logger;                           //2
    private final int times;                               //3

    public RepeatingDecorator(Logger logger, int times) {
        this.logger = logger;
        this.times = times;
    }

    @Override
    public void log(String message) {
        for (int i = 0; i < times; i++) {                  //4
            logger.log(message);
        }
    }
} implement the interface Must Underlying logger Loop configuration Call the method as many times as necessary Using the decorator is straightforward: var logger = new ConsoleLogger();
var threeTimesLogger = new RepeatingDecorator(logger, 3);
threeTimesLogger.log("Hello world!"); The Java Proxy The Java Proxy is a generic decorator that allows attaching dynamic behavior: Proxy provides static methods for creating objects that act like instances of interfaces but allow for customized method invocation. -- Proxy Javadoc The uses Java Proxies . It's the case of the annotation. If you annotate a method, Spring creates a Java Proxy around the encasing class at runtime. When you call it, Spring calls the proxy instead. Depending on the configuration, it opens the transaction or joins an existing one, then calls the actual method, and finally commits (or rollbacks). Spring Framework a lot @Transactional The API is simple: We can write the following handler: public class RepeatingInvocationHandler implements InvocationHandler {

    private final Logger logger;                                       //1
    private final int times;                                           //2

    public RepeatingInvocationHandler(Logger logger, int times) {
        this.logger = logger;
        this.times = times;
    }

    @Override
    public Object invoke(Object proxy, Method method, Object[] args) throws Exception {
        if (method.getName().equals("log") && args.length ## 1 && args[0] instanceof String) { //3
            for (int i = 0; i < times; i++) {
                method.invoke(logger, args[0]);                        //4
            }
        }
        return null;
    }
} Underlying logger Loop configuration Check every requirement is upheld Call the initial method on the underlying logger Here's how to create the proxy: var logger = new ConsoleLogger();
var proxy = (Logger) Proxy.newProxyInstance(           //1-2
        Main.class.getClassLoader(),
        new Class[]{Logger.class},                     //3
        new RepeatingInvocationHandler(logger, 3));    //4
proxy.log("Hello world!"); Create the object Proxy We must cast to as the API was created before generics, and it returns an Logger Object An array of interfaces the object needs to conform to Pass our handler Instrumentation Instrumentation is the capability of the JVM to transform bytecode before it loads it via a . Two Java agent flavors are available: Java agent Static, with the agent passed on the command line when you launch the application Dynamic allows connecting to a running JVM and attaching an agent on it via the . Note that it represents a huge security issue and has been drastically limited in the latest JDK. Attach API The 's surface is limited: Instrumentation API As seen above, the API exposes the user to low-level bytecode manipulation via byte arrays. It would be unwieldy to do it directly. Hence, real-life projects rely on bytecode manipulation libraries. has been the traditional library for this, but it seems that has superseded it. Note that Byte Buddy uses ASM but provides a higher-level abstraction. ASM Byte Buddy The Byte Buddy API is outside the scope of this blog post, so let's dive directly into the code: public class Repeater {

  public static void premain(String arguments, Instrumentation instrumentation) {      //1
    var withRepeatAnnotation = isAnnotatedWith(named("ch.frankel.blog.instrumentation.Repeat")); //2
    new AgentBuilder.Default()                                                         //3
      .type(declaresMethod(withRepeatAnnotation))                                      //4
      .transform((builder, typeDescription, classLoader, module, domain) -> builder    //5
        .method(withRepeatAnnotation)                                                  //6
        .intercept(                                                                    //7
           SuperMethodCall.INSTANCE                                                    //8
            .andThen(SuperMethodCall.INSTANCE)
            .andThen(SuperMethodCall.INSTANCE))
      ).installOn(instrumentation);                                                    //3
  }
} Required signature; it's similar to the method, with the added argument main Instrumentation Match that is annotated with the annotation. The DSL reads fluently even if you don't know it (I don't). @Repeat Byte Buddy provides a builder to create the Java agent Match all types that declare a method with the annotation @Repeat Transform the class accordingly Transform methods annotated with @Repeat Replace the original implementation with the following Call the original implementation three times The next step is to create the Java agent package. A Java agent is a regular JAR with specific manifest attributes. Let's configure Maven to build the agent: <plugin>
    <artifactId>maven-assembly-plugin</artifactId>                                      
    <configuration>
        <descriptorRefs>
            <descriptorRef>jar-with-dependencies</descriptorRef>                        
        </descriptorRefs>
        <archive>
            <manifestEntries>
                <Premain-Class>ch.frankel.blog.instrumentation.Repeater</Premain-Class> 
            </manifestEntries>
        </archive>
    </configuration>
    <executions>
        <execution>
            <goals>
                <goal>single</goal>
            </goals>
            <phase>package</phase>                                                      
        </execution>
    </executions>
</plugin> Create a JAR containing all dependencies () Testing is more involved, as we need two different codebases, one for the agent and one for the regular code with the annotation. Let's create the agent first: mvn install We can then run the app with the agent: java -javaagent:/Users/nico/.m2/repository/ch/frankel/blog/agent/1.0-SNAPSHOT/agent-1.0-SNAPSHOT-jar-with-dependencies.jar \ #1
     -cp ./target/classes                                                                                                    #2
     ch.frankel.blog.instrumentation.Main                                                                                    #3 Run java with the agent created in the previous step. The JVM will run the method of the class configured in the agent premain Configure the classpath Set the main class Aspect-Oriented Programming The idea behind AOP is to apply some code across different unrelated object hierarchies - cross-cutting concerns. It's a valuable technique in languages that don't allow , or code you can graft on third-party objects/classes. Fun fact: I learned about AOP before . AOP relies on two main concepts: an aspect is the transformation applied to code, while a point cut matches where the aspect applies. traits Proxy In Java, AOP's historical implementation is the excellent library. AspectJ provides two approaches, known as : build-time weaving, which transforms the compiled bytecode, and runtime weaving, which relies on the above instrumentation. Either way, AspectJ uses a specific format for aspects and pointcuts. Before Java 5, the format looked like Java but not quite; for example, it used the keyword. With Java 5, one can use annotations in regular Java code to achieve the same goal. AspectJ weaving aspect We need an AspectJ dependency: <dependency>
    <groupId>org.aspectj</groupId>
    <artifactId>aspectjrt</artifactId>
    <version>1.9.19</version>
</dependency> As Byte Buddy, AspectJ also uses ASM underneath. Here's the code: @Aspect                                                                              //1
public class RepeatingAspect {

    @Pointcut("@annotation(repeat) && call(* *(..))")                                //2
    public void callAt(Repeat repeat) {}                                             //3

    @Around("callAt(repeat)")                                                        //4
    public Object around(ProceedingJoinPoint pjp, Repeat repeat) throws Throwable {  //5
        for (int i = 0; i < repeat.times(); i++) {                                   //6
            pjp.proceed();                                                           //7
        }
        return null;
    }
} Mark this class as an aspect Define the pointcut; every call to a method annotated with @Repeat Bind the annotation to the the name used in the annotation above @Repeat repeat Define the aspect applied to the call site; it's an , meaning that we need to call the original method explicitly @Around The signature uses a , which references the original method, as well as the annotation ProceedingJoinPoint @Repeat Loop over as many times as configured Call the original method At this point, we need to weave the aspect. Let's do it at build-time. For this, we can add the AspectJ build plugin: <plugin>
    <groupId>org.codehaus.mojo</groupId>
    <artifactId>aspectj-maven-plugin</artifactId>
    <executions>
        <execution>
            <goals>
                <goal>compile</goal>                  
            </goals>
        </execution>
    </executions>
</plugin> Bind execution of the plugin to the phase compile To see the demo in effect: mvnd compile exec:java -Dexec.mainClass=ch.frankel.blog.aop.Main Java compiler plugin Last, it's possible to change the generated bytecode via a Java compiler plugin, introduced in Java 6 as JSR 269. From a bird's eye view, plugins involve hooking into the Java compiler to manipulate the AST in three phases: parse the source code into multiple ASTs, analyze further into , and potentially generate source code. Element The documentation could be less sparse. I found the following Awesome Java Annotation Processing. Here's a simplified class diagram to get you started: I'm too lazy to implement the same as above with such a low-level API. As the expression goes, this is left as an exercise to the reader. If you are interested, I believe the is a good starting point. DocLint source code Conclusion I described several approaches to monkey-patching in Java in this post: the class, instrumentation via a Java Agent, AOP via AspectJ, and compiler plugins. To choose one over the other, consider the following criteria: build-time vs. runtime, complexity, native vs. third-party, and security concerns. Proxy javac To go further: Guide to Java Instrumentation Creating a Java Compiler Plugin Awesome Java Annotation Processing Maven AspectJ plugin Originally published at on September 17th, 2023 A Java Geek

Walkthroughs, tutorials, guides, and tips. This story will teach you how to do something new or how to do something better.

Follow @nicolas_frankel on Twitter

Read My Stories

Read all my posts!

Too Long; Didn't Read

In your car, at home, or at work — Bosch technology shapes many areas of life.

A Guide to Monkey-Patching in Java

Too Long; Didn't Read

People Mentioned

Nicolas Fränkel

STORY’S CREDIBILITY

Guide

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

A Guide to Monkey-Patching in Java

Too Long; Didn't Read

People Mentioned

Nicolas Fränkel

STORY’S CREDIBILITY

Guide

About Author

TOPICS

THIS ARTICLE WAS FEATURED IN...

RELATED STORIES