{"id":43745,"date":"2015-09-18T21:54:19","date_gmt":"2015-09-18T18:54:19","guid":{"rendered":"http:\/\/www.javacodegeeks.com\/?p=43745"},"modified":"2023-12-06T14:28:35","modified_gmt":"2023-12-06T12:28:35","slug":"java-agents","status":"publish","type":"post","link":"https:\/\/www.javacodegeeks.com\/2015\/09\/java-agents.html","title":{"rendered":"Java Agents"},"content":{"rendered":"

This article is part of our Academy Course titled Advanced Java<\/a>.<\/p>\n

This course is designed to help you make the most effective use of Java. It discusses advanced topics, including object creation, concurrency, serialization, reflection and many more. It will guide you through your journey to Java mastery! Check it out here<\/a>!<\/em><\/p>\n

\n

Table Of Contents<\/h4>\n
\n
1. Introduction<\/a><\/dt>\n
2. Java Agent Basics<\/a><\/dt>\n
3. Java Agent and Instrumentation<\/a><\/dt>\n
4. Writing Your First Java Agent<\/a><\/dt>\n
5. Running Java Agents<\/a><\/dt>\n
6. What\u2019s next<\/a><\/dt>\n
7. Download the source code<\/a><\/dt>\n<\/dl>\n<\/div>\n

<\/a>1. Introduction<\/h2>\n

In this last part of the tutorial we are going to talk about Java agents, a real black magic for regular Java developers out there. Java agents are able to “intrude” into the execution of Java applications running on the JVM at runtime by performing the direct modifications of the bytecode. Java agents are extremely as powerful as dangerous: they can do mostly everything however if something goes wrong, they can easily crash the JVM.<\/p>\n

The goal of this part is to demystify Java agents by explaining how they work, how to run them and showing off some simple examples where Java agents come as a clear advantage.<\/p>\n

<\/a>2. Java Agent Basics<\/h2>\n

In its essence, a Java agent is a regular Java class which follows a set of strict conventions. The agent class must implement a public static void premain(String agentArgs, Instrumentation inst)<\/code> method which becomes an agent entry point (similar to the main<\/code> method for regular Java applications). <\/p>\n

Once the Java Virtual Machine (JVM) has initialized, each such premain(String agentArgs, Instrumentation inst)<\/code> method of every agent will be called in the order the agents were specified on JVM start. When this initialization step is done, the real Java application main<\/code> method will be called. <\/p>\n

However, if the class does not implement public static void premain(String agentArgs, Instrumentation inst)<\/code> method, the JVM will try to look up and invoke another, overloaded version, public static void premain(String agentArgs)<\/code>. Please notice that each premain<\/code> method must return in order for the startup phase to proceed. <\/p>\n

Last but not least, the Java agent class may also have a public static void agentmain(String agentArgs, Instrumentation inst)<\/code> or public static void agentmain(String agentArgs)<\/code> methods which are used when the agent is started after JVM startup.<\/p>\n

It looks simple on the first glance but there is one more thing which Java agent implementation should provide as part of its packaging: manifest. Manifest files, usually located in the META-INF<\/strong> folder and named MANIFEST.MF<\/strong>, contain a various metadata related to package distribution.<\/p>\n

We have not talked about manifests along this tutorial because most of the time they are not required, however this is not the case with Java agents. The following attributes are defined for Java agents who are packaged as a Java archive (or simply JAR) files:<\/p>\n\n\n\n\n\n\n\n\n
Manifest Attribute<\/strong><\/td>\nDescription<\/strong><\/td>\n<\/tr>\n
Premain-Class<\/strong><\/td>\n\nWhen an agent is specified at JVM launch time this attribute defines the Java agent class: the class containing the premain<\/code> method. When an agent is specified at JVM launch time this attribute is required. If the attribute is not present the JVM will abort. <\/td>\n<\/tr>\n
Agent-Class<\/strong><\/td>\nIf an implementation supports a mechanism to start Java agents sometime after the JVM has started then this attribute specifies the agent class: the class containing the agentmain<\/code> method. This attribute is required and the agent will not be started if this attribute is not present. <\/td>\n<\/tr>\n
Boot-Class-Path<\/strong><\/td>\nA list of paths to be searched by the bootstrap class loader. Paths represent directories or libraries. <\/td>\n<\/tr>\n
Can-Redefine-Classes<\/strong><\/td>\nA value of true<\/code> or false<\/code>, case-insensitive and defines if the ability to redefine classes needed by this agent. This attribute is optional, the default is false<\/code>. <\/td>\n<\/tr>\n
Can-Retransform-Classes<\/strong><\/td>\nA value of true<\/code> or false<\/code>, case-insensitive and defines if the ability to retransform classes needed by this agent. This attribute is optional, the default is false<\/code>.<\/td>\n<\/tr>\n
\nCan-Set-Native-Method-Prefix<\/strong><\/td>\nA value of true<\/code> or false<\/code>, case-insensitive and defines if the ability to set native method prefix needed by this agent. This attribute is optional, the default is false<\/code>.<\/td>\n<\/tr>\n<\/table>\n

For more details please do not hesitate to consult the official documentation<\/a> dedicated to Java agents and instrumentation.

<\/div> <\/div><\/p>\n

<\/a>3. Java Agent and Instrumentation<\/h2>\n

The instrumentation capabilities of Java agents are truly unlimited. Most noticeable ones include but are not limited to: <\/p>\n