2362N/A Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved. 843N/A DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 843N/A This code is free software; you can redistribute it and/or modify it 843N/A under the terms of the GNU General Public License version 2 only, as 2362N/A published by the Free Software Foundation. Oracle designates this 843N/A particular file as subject to the "Classpath" exception as provided 2362N/A by Oracle in the LICENSE file that accompanied this code. 843N/A This code is distributed in the hope that it will be useful, but WITHOUT 843N/A ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 843N/A FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 843N/A version 2 for more details (a copy is included in the LICENSE file that 843N/A accompanied this code). 843N/A You should have received a copy of the GNU General Public License version 843N/A 2 along with this work; if not, write to the Free Software Foundation, 843N/A Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 2362N/A Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 0N/A<!
DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
0N/A Copyright 2003 Wily Technology, Inc. 0N/A<
body bgcolor="white">
0N/AProvides services that allow Java programming language agents to instrument programs running on the JVM.
0N/AThe mechanism for instrumentation is modification of the byte-codes of methods.
0N/A<
h2>Package Specification</
h2>
0N/AAn agent is deployed as a JAR file. An attribute in the JAR file manifest specifies the
0N/Aagent class which will be loaded to start the agent. For implementations that support a command-line
0N/Ainterface, an agent is started by specifying an option on the command-line.
0N/AImplementations may also support a mechanism to start agents some time after the VM has
0N/Astarted. For example, an implementation may provide a mechanism that allows a tool to
0N/A<
i>attach</
i> to a running application, and initiate the loading of the tool's agent into
0N/Athe running application. The details as to how the load is initiated, is implementation
0N/A<
h3>Command-Line Interface</
h3>
0N/AOn implementations with a command-line interface, an agent is started by
0N/Aadding this option to the command-line:
0N/A<
code><
b>-javaagent:</
b></
code><
i>jarpath[</
i><
code><
b>=</
b></
code><
i>options]</
i>
0N/A<
i>jarpath</
i> is the path to the agent JAR file.
0N/A<
i>options</
i> is the agent options.
0N/AThis switch may be used multiple times on the same command-line,
0N/Athus creating multiple agents.
0N/AMore than one agent may use the same <
i>jarpath</
i>.
0N/AAn agent JAR file must conform to the JAR file specification.
0N/AThe manifest of the agent JAR file must contain the attribute <
code>Premain-Class</
code>. The
0N/Avalue of this attribute is the name of the <
i>agent class</
i>. The agent class must implement a
0N/Apublic static <
code>premain</
code> method similar in principle to the <
code>main</
code> application
0N/Aentry point. After the Java Virtual Machine (JVM) has initialized, each <
code>premain</
code> method
0N/Awill be called in the order the agents were specified, then the real application
0N/A<
code>main</
code> method will be called.
0N/AEach <
code>premain</
code> method must return in order for the startup sequence to proceed.
0N/AThe <
code>premain</
code> method has one of two possible signatures. The JVM first attempts to
0N/Ainvoke the following method on the agent class:
0N/A<
code>public static void
0N/Apremain(String agentArgs, Instrumentation inst);
0N/AIf the agent class does not implement this method then the JVM will attempt to invoke:
0N/A<
code>public static void
0N/Apremain(String agentArgs);
0N/AThe agent class may also have an <
code>agentmain</
code> method for use when the agent is started
0N/Aafter VM startup. When the agent is started using a command-line option, the <
code>agentmain</
code>
0N/Amethod is not invoked.
0N/AThe agent class will be loaded by the system class loader
0N/Athe class loader which typically loads the class containing the application <
code>main</
code> method.
0N/AThe <
code>premain</
code> methods will be run under the same security and classloader
0N/Arules as the application <
code>main</
code> method.
0N/AThere are no modeling restrictions on what the agent <
code>premain</
code> method may do.
0N/AAnything application <
code>main</
code> can do, including creating threads, is legal from <
code>premain</
code>.
0N/AEach agent is passed its agent options via the <
code>agentArgs</
code> parameter.
0N/AThe agent options are passed as a single string,
0N/Aany additional parsing should be performed by the agent itself.
0N/AIf the agent cannot be resolved
0N/A(for example, because the agent class cannot be loaded,
0N/Aor because the agent class does not have an appropriate <
code>premain</
code> method), the JVM will abort.
0N/AIf a <
code>premain</
code> method throws an uncaught exception, the JVM will abort.
0N/A<
h3>Starting Agents After VM Startup</
h3>
0N/AAn implementation may provide a mechanism to start agents sometime after the
0N/Athe VM has started. The details as to how this is initiated are implementation
0N/Aspecific but typically the application has already started and its <
code>
0N/Amain</
code> method has already been invoked. In cases where an implementation
0N/Asupports the starting of agents after the VM has started the following applies:
0N/A <
li><
p>The manifest of the agent JAR must contain the attribute <
code>Agent-Class</
code>.
0N/A The value of this attribute is the name of the <
i>agent class</
i>. </
p></
li>
0N/A <
li><
p>The agent class must implement a public static <
code>agentmain</
code> method. </
p></
li>
0N/A <
li><
p>The system class loader (
0N/A support a mechanism to add an agent JAR file to the system class path. <
p></
li>
0N/AThe agent JAR is appended to the system class path. This is the class loader that typically loads
0N/Athe class containing the application <
code>main</
code> method. The agent class is loaded and the
0N/AJVM attempts to invoke the <
code>agentmain</
code> method. The JVM first attempts to invoke
0N/Athe following method on the agent class:
0N/A<
code>public static void
0N/Aagentmain(String agentArgs, Instrumentation inst);
0N/AIf the agent class does not implement this method then the JVM will attempt to invoke:
0N/A<
code>public static void
0N/Aagentmain(String agentArgs);
0N/AThe agent class may also have an <
code>premain</
code> method for use when the agent is started
0N/Ausing a command-line option. When the agent is started after VM startup the <
code>premain</
code>
0N/Amethod is not invoked.
0N/AThe agent is passed its agent options via the <
code>agentArgs</
code> parameter.
0N/AThe agent options are passed as a single string,
0N/Aany additional parsing should be performed by the agent itself.
0N/AThe <
code>agentmain</
code> method should do any necessary initialization
0N/Arequired to start the agent. When startup is complete the method should
0N/Areturn. If the agent cannot be started
0N/A(for example, because the agent class cannot be loaded,
0N/Aor because the agent class does not have a conformant <
code>agentmain</
code> method), the JVM will
0N/Anot abort. If the <
code>agentmain</
code> method throws an uncaught exception it will be ignored.
0N/A<
h3>Manifest Attributes</
h3>
0N/AThe following manifest attributes are defined for an agent JAR file:
0N/A<
dt><
code>Premain-Class</
code></
dt>
0N/A When an agent is specified at JVM launch time this attribute
0N/A specifies the agent class.
0N/A That is, the class containing the <
code>premain</
code> method.
0N/A When an agent is specified at JVM launch time this attribute
0N/A is required. If the attribute is not present the JVM will abort.
0N/A Note: this is a class name, not a file name or path.
0N/A<
dt><
code>Agent-Class</
code></
dt>
0N/A If an implementation supports a mechanism to start agents
0N/A sometime after the VM has started then this attribute specifies
0N/A That is, the class containing the <
code>agentmain</
code> method.
0N/A This attribute is required, if it is not present the agent
0N/A will not be started.
0N/A Note: this is a class name, not a file name or path.
0N/A<
dt><
code>Boot-Class-Path</
code></
dt>
0N/A A list of paths to be searched by the bootstrap class
0N/A loader. Paths represent directories or libraries
0N/A (commonly referred to as JAR or zip libraries on
0N/A These paths are searched by the
0N/A bootstrap class loader after the platform specific
0N/A mechanisms of locating a class have failed.
0N/A Paths are searched in the order listed.
0N/A Paths in the list are separated by one or more spaces.
0N/A A path takes the syntax of the path component of a
0N/A hierarchical URI. The path is
0N/A absolute if it begins with a slash character ('/'),
0N/A otherwise it is relative. A relative path is resolved
0N/A against the absolute path of the agent JAR file.
0N/A Malformed and non-existent paths are ignored.
0N/A When an agent is started sometime after the VM has
0N/A started then paths that do not represent a JAR file
0N/A This attribute is optional.
0N/A<
dt><
code>Can-Redefine-Classes</
code></
dt>
0N/A Boolean (<
code>true</
code> or <
code>false</
code>, case irrelevant).
0N/A Is the ability to redefine classes
0N/A needed by this agent.
0N/A Values other than <
code>true</
code> are considered <
code>false</
code>.
0N/A This attribute is optional, the default is <
code>false</
code>.
0N/A<
dt><
code>Can-Retransform-Classes</
code></
dt>
0N/A Boolean (<
code>true</
code> or <
code>false</
code>, case irrelevant).
0N/A Is the ability to retransform classes
0N/A needed by this agent.
0N/A Values other than <
code>true</
code> are considered <
code>false</
code>.
0N/A This attribute is optional, the default is <
code>false</
code>.
0N/A<
dt><
code>Can-Set-Native-Method-Prefix</
code></
dt>
0N/A Boolean (<
code>true</
code> or <
code>false</
code>, case irrelevant).
0N/A Is the ability to set native method prefix needed by this agent.
0N/A Values other than <
code>true</
code> are considered <
code>false</
code>.
0N/A This attribute is optional, the default is <
code>false</
code>.
0N/AAn agent JAR file may have both the <
code>Premain-Class</
code> and <
code>Agent-Class</
code>
0N/Aattributes present in the manifest. When the agent is started on the command-line using
0N/Athe <
code>-javaagent</
code> option then the <
code>Premain-Class</
code> attribute
0N/Aspecifies the name of the agent class and the <
code>Agent-Class</
code> attribute is
0N/Aignored. Similarly, if the agent is started sometime after the VM has started, then
0N/Athe <
code>Agent-Class</
code> attribute specifies the name of the agent class
0N/A(the value of <
code>Premain-Class</
code> attribute is ignored).
0N/A<
h2>Related Documentation</
h2>
0N/AFor tool documentation, please see: