Getting to know javaagents

Posted on October 25, 2015 Updated on October 26, 2015

Java agent is a powerful tool introduced with Java 5. It has been highly useful in profiling activities where developers and application users can monitor tasks carried out within servers and applications. The ability to inject code segments by modifying classes and their method bodies during the run time has become useful in many ways. Intercepting parameter values passed between methods, calculation of execution time of methods can be considered as some examples. As long as you know the class name and the structure of class along with their method bodies, injecting a piece of code would take less than a minute.

Since this is going to be a series of instruction for beginners in java agents, I would start with a brief introduction on powerful java agents. Hence, this post will cover basic points as, the concept behind agents and how they work.

Well, the true power of these java agents lie on their ability to do the bytecode instrumentation. Now, you may wonder what is this bytecode. Although we humans can understand the program files written using programming languages known to us (java, python, php), computer processors do not understand them. Processors have their own language, with set of terms known as opcodes. They represent the instruction needed to carryout operations. Collection of these opcodes, instructions are referred to as bytecode, which is included in .class files we obtain after compiling our .java files. Instrumentation is the process of modifying these bytecode.

But, why do we need this java agent feature? If this is the first time you are reading about java agents, you surely may have this question.

Well, the answer is, although we get those .java files when we write our own code, files we receive with jars or any type of application we download or install would contain only .class files. We cannot read them using IDEs we use for development. The only way to access and modify their content is using libraries that work close with bytecode. Given below are three most famous libraries used in bytecode instrumentation.

• ASM – low level library. Need to have better understanding about bytcode instructions
• Javassist – middle level library. Operates on top of ASM. Knowledge about bytecode is not a must.
• AspectJ – high level framework. Much more easy to work with.

Out of these three libraries, Javassist will be the library used in the future examples. But, before we start writing a simple agent, let’s get an overall idea on how an agent works.

Mainly, there are two ways that an agent can be invoked. Type of the agent is decided based on the main method type selected by the developer.

• premain() – Agent is loaded before main class and other respective classes are loaded onto memory. This premain method, as its name described, will be invoked before the main method.
• agentmain() – Using this method, we can invoke an agent at an arbitrary point in time, after all the classes are load onto JVM.

Since we are new to the process, let’s start with the simple premain() method. JVM will be informed about our agent by passing the path to our agent jar as a parameter. It can be done by including the -javaagent parameter in the command line.

The above figure describes the basic concept of this instrumentation process. Once we provide the details of the class we want to modify along with method names and content we need to inject, agent will obtain the bytecode of the respective class before it load onto JVM. It will make a copy of those byte code as a byte array and do requested changes on the instruction set by pushing and popping instruction on the stack. Finally, once the instrumentation is completed, it’ll recompile the new bytecode to verify whether there are any compilation errors. If it cause no compilation errors, it will load the new bytecode to the JVM, which can then be used in the tasks it was assigned to do.

So, above is a brief introduction to java agents. This long description without any example may have make you sleepy. But, don’t worry, next few articles would raise your enthusiasm in agents.

Next topic would be on ‘Requirements of a Java Agent’. Have a great time.