Bytecode Engineering in Java

You have seen how annotations can be processed at runtime or at the source code level. There is a third possibility: processing at the bytecode level. Unless annotations are removed at the source level, they are present in the class

files. The class file format is documented (see http://docs.oracle.com/javase/specs /jvms/se10/htmt). The format is rather complex, and it would be challenging to process class files without special libraries. One such library is the ASM library, available at http://asm.ow2.org.

1. Modifying Class Files

In this section, we use ASM to add logging messages to annotated methods. If a method is annotated with

@LogEntry(logger=loggerName)

then we add the bytecodes for the following statement at the beginning of the method:

Logger.getLogger(loggerName).entering(className, methodName);

For example, if you annotate the hashCode method of the Item class as

@LogEntry(logger=”global”) public int hashCode()

then a message similar to the following is printed whenever the method is called:

May 17, 2016 10:57:59 AM Item hashCode

FINER: ENTRY

To achieve this, we do the following:

1. Load the bytecodes in the class file.
2. Locate all methods.
3. For each method, check whether it has a LogEntry annotation.
4. If it does, add the bytecodes for the following instructions at the beginning of the method:

ldc loggerName

invokestatic

java/util/logging/Logger.getLogger:(Ljava/lang/String;)Ljava/util/logging/Logger;

ldc className

ldc methodName

invokevirtual

java/util/logging/Logger.entering:(Ljava/lang/String;Ljava/lang/String;)V

Inserting these bytecodes sounds tricky, but ASM makes it fairly straightfor­ward. We don’t describe the process of analyzing and inserting bytecodes in detail. The important point is that the program in Listing 8.9 edits a class file and inserts a logging call at the beginning of the methods annotated with the LogEntry annotation.

For example, here is how you add the logging instructions to Item.java in Listing 8.10, where asm is the directory into which you installed the ASM library:

javac set/Item.java

javac -classpath .:asm/tib/\* bytecodeAnnotations/EntryLogger.java

java -classpath .:asm/lib/\* bytecodeAnnotations.EntryLogger set.Item

Try running

javap -c set.Item

before and after modifying the Item class file. You can see the inserted instructions at the beginning of the hashCode, equals, and compareTo methods.

public int hashCode();

Code:

0: Idc #85; // String global

2:  invokestatic #80;

// Method

// java/util/logging/Logger.getLogger:(Ljava/lang/String;)Ljava/util/logging/Logger;

5:  ldc    #86; //String Item

7:  ldc    #88; //String hashCode

9:  invokevirtual #84;

// Method java/util/logging/Logger.entering:(Ljava/lang/String;Ljava/lang/String;)V

12:        bipush  13

14: aload_0

15: getfield      #2; // Field description:Ljava/lang/String;

18: invokevirtual #15; // Method java/lang/String.hashCode:()I

21: imul

22: bipush 17

24: aload_0

25: getfield      #3; // Field partNumber:I

28: imul

29: iadd

30: ireturn

The SetTest program in Listing 8.11 inserts Item objects into a hash set. When you run it with the modified class file, you will see the logging messages.

May 17, 2016 10:57:59 AM Item hashCode FINER: ENTRY

May 17, 2016 10:57:59 AM Item hashCode FINER: ENTRY

May 17, 2016 10:57:59 AM Item hashCode FINER: ENTRY

May 17, 2016 10:57:59 AM Item equals FINER: ENTRY

[[description=Toaster, partNumber=1729], [description=Microwave, partNumber=4104]]

Note the call to equals when we insert the same item twice.

This example shows the power of bytecode engineering. Annotations are used to add directives to a program, and a bytecode editing tool picks up the directives and modifies the virtual machine instructions.

2. Modifying Bytecodes at Load Time

In the last section, you saw a tool that edits class files. However, it can be cumbersome to add yet another tool into the build process. An attractive al­ternative is to defer the bytecode engineering until load time, when the class loader loads the class.

The instrumentation API has a hook for installing a bytecode transformer. The transformer must be installed before the main method of the program is called. You can meet this requirement by defining an agent, a library that is loaded to monitor a program in some way. The agent code can carry out initializations in a premain method.

Here are the steps required to build an agent:

1. Implement a class with a method

public static void premain(String arg, Instrumentation instr)

This method is called when the agent is loaded. The agent can get a single command-line argument, which is passed in the arg parameter. The instr parameter can be used to install various hooks.

2. Make a manifest file EntryLoggingAgent.mf that sets the Premain-Class attribute, for example:

Premain-Class: bytecodeAnnotations.EntryLoggingAgent

3. Package the agent code and the manifest into a JAR file:

javac -classpath .:asm/lib/\* bytecodeAnnotations/EntryLoggingAgent.java

jar cvfm EntryLoggingAgent.jar bytecodeAnnotations/EntryLoggingAgent.mf \

bytecodeAnnotations/Entry*.class

To launch a Java program together with the agent, use the following command­line options:

java -javaagent:AgentJARFile=agentArgument . . .

For example, to run the SetTest program with the entry logging agent, call

javac set/SetTest.java

java -javaagent:EntryLoggingAgent.jar=set.Item -classpath .:asm/lib/\* set.SetTest

The Item argument is the name of the class that the agent should modify.

Listing 8.12 shows the agent code. The agent installs a class file transformer. The transformer first checks whether the class name matches the agent argu­ment. If so, it uses the EntryLogger class from the preceding section to modify the bytecodes. However, the modified bytecodes are not saved to a file. Instead, the transformer returns them for loading into the virtual machine (see Figure 8.3). In other words, this technique carries out “just in time” modification of the bytecodes.

In this chapter, you have learned how to

• Add annotations to Java programs
• Design your own annotation interfaces
• Implement tools that make use of the annotations

You have seen three technologies for processing code: scripting, compiling Java programs, and processing annotations. The first two were quite straightforward. On the other hand, building annotation tools is undeniably complex and not something that most developers will need to tackle. This chapter gave you the background for understanding the inner workings of the annotation tools you will encounter, and perhaps piqued your interest in developing your own tools.

The following chapter discusses the Java Platform Module System, the key feature of Java 9 that is important for moving the Java platform forward.

Source: Horstmann Cay S. (2019), Core Java. Volume II – Advanced Features, Pearson; 11th edition.