1 <!--
2 Copyright (c) 2003, 2014, Oracle and/or its affiliates. All rights reserved.
3 DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4
5 This code is free software; you can redistribute it and/or modify it
6 under the terms of the GNU General Public License version 2 only, as
7 published by the Free Software Foundation. Oracle designates this
8 particular file as subject to the "Classpath" exception as provided
9 by Oracle in the LICENSE file that accompanied this code.
10
11 This code is distributed in the hope that it will be useful, but WITHOUT
12 ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 version 2 for more details (a copy is included in the LICENSE file that
15 accompanied this code).
16
17 You should have received a copy of the GNU General Public License version
18 2 along with this work; if not, write to the Free Software Foundation,
19 Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20
21 Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 or visit www.oracle.com if you need additional information or have any
23 questions.
24 -->
25
26 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
27 <html>
28 <head>
29 <!--
30
31 Copyright 2003 Wily Technology, Inc.
32
33 -->
34 </head>
35
36 <body bgcolor="white">
37
38 Provides services that allow Java programming language agents to instrument programs running on the JVM.
39 The mechanism for instrumentation is modification of the byte-codes of methods.
40
41 <h2>Package Specification</h2>
42
43 <P>
44 An agent is deployed as a JAR file. An attribute in the JAR file manifest specifies the
45 agent class which will be loaded to start the agent. For implementations that support a command-line
46 interface, an agent is started by specifying an option on the command-line.
47 Implementations may also support a mechanism to start agents some time after the VM has
48 started. For example, an implementation may provide a mechanism that allows a tool to
49 <i>attach</i> to a running application, and initiate the loading of the tool's agent into
50 the running application. The details as to how the load is initiated, is implementation
51 dependent.
52
53 <h3>Command-Line Interface</h3>
54
55 <P>
56 An implementation is not required to provide a way to start agents from the
57 command-line interface. On implementations that do provide a way to start agents
58 from the command-line interface, an agent is started by adding this option to
59 the command-line:
60 <blockquote>
61 <code><b>-javaagent:</b></code><i>jarpath[</i><code><b>=</b></code><i>options]</i>
62 </blockquote>
63 <i>jarpath</i> is the path to the agent JAR file.
64 <i>options</i> is the agent options.
65 This switch may be used multiple times on the same command-line,
66 thus creating multiple agents.
67 More than one agent may use the same <i>jarpath</i>.
68 An agent JAR file must conform to the JAR file specification.
69
70 <P>
71 The manifest of the agent JAR file must contain the attribute <code>Premain-Class</code>. The
72 value of this attribute is the name of the <i>agent class</i>. The agent class must implement a
73 public static <code>premain</code> method similar in principle to the <code>main</code> application
74 entry point. After the Java Virtual Machine (JVM) has initialized, each <code>premain</code> method
75 will be called in the order the agents were specified, then the real application
76 <code>main</code> method will be called.
77 Each <code>premain</code> method must return in order for the startup sequence to proceed.
78
79 <P>
80 The <code>premain</code> method has one of two possible signatures. The JVM first attempts to
81 invoke the following method on the agent class:
82
83 <blockquote>
84 <code>public static void
85 premain(String agentArgs, Instrumentation inst);
86 </code>
87 </blockquote>
88
89 <P>
90 If the agent class does not implement this method then the JVM will attempt to invoke:
91
92 <blockquote>
93 <code>public static void
94 premain(String agentArgs);
95 </code>
96 </blockquote>
97
98 <P>
99 The agent class may also have an <code>agentmain</code> method for use when the agent is started
100 after VM startup. When the agent is started using a command-line option, the <code>agentmain</code>
101 method is not invoked.
102
103
104 <P>
105 The agent class will be loaded by the system class loader
106 (see {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}). This is
107 the class loader which typically loads the class containing the application <code>main</code> method.
108 The <code>premain</code> methods will be run under the same security and classloader
109 rules as the application <code>main</code> method.
110 There are no modeling restrictions on what the agent <code>premain</code> method may do.
111 Anything application <code>main</code> can do, including creating threads, is legal from <code>premain</code>.
112
113 <P>
114 Each agent is passed its agent options via the <code>agentArgs</code> parameter.
115 The agent options are passed as a single string,
116 any additional parsing should be performed by the agent itself.
117
118 <P>
119 If the agent cannot be resolved
120 (for example, because the agent class cannot be loaded,
121 or because the agent class does not have an appropriate <code>premain</code> method), the JVM will abort.
122 If a <code>premain</code> method throws an uncaught exception, the JVM will abort.
123
124
125
126 <h3>Starting Agents After VM Startup</h3>
127
128 <p>
129 An implementation may provide a mechanism to start agents sometime after the
130 the VM has started. The details as to how this is initiated are implementation
131 specific but typically the application has already started and its <code>
132 main</code> method has already been invoked. In cases where an implementation
133 supports the starting of agents after the VM has started the following applies:
134
135 <ol>
136 <li><p>The manifest of the agent JAR must contain the attribute <code>Agent-Class</code>.
137 The value of this attribute is the name of the <i>agent class</i>. </p></li>
138
139 <li><p>The agent class must implement a public static <code>agentmain</code> method. </p></li>
140
141 <li><p>The system class loader (
142 {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}) must
143 support a mechanism to add an agent JAR file to the system class path.</li>
144 </ol>
145
146 <P>
147 The agent JAR is appended to the system class path. This is the class loader that typically loads
148 the class containing the application <code>main</code> method. The agent class is loaded and the
149 JVM attempts to invoke the <code>agentmain</code> method. The JVM first attempts to invoke
150 the following method on the agent class:
151
152 <blockquote>
153 <code>public static void
154 agentmain(String agentArgs, Instrumentation inst);
155 </code>
156 </blockquote>
157
158 <P>
159 If the agent class does not implement this method then the JVM will attempt to invoke:
160
161 <blockquote>
162 <code>public static void
163 agentmain(String agentArgs);
164 </code>
165 </blockquote>
166
167 <P>
168 The agent class may also have an <code>premain</code> method for use when the agent is started
169 using a command-line option. When the agent is started after VM startup the <code>premain</code>
170 method is not invoked.
171
172
173 <P>
174 The agent is passed its agent options via the <code>agentArgs</code> parameter.
175 The agent options are passed as a single string,
176 any additional parsing should be performed by the agent itself.
177
178 <P>
179 The <code>agentmain</code> method should do any necessary initialization
180 required to start the agent. When startup is complete the method should
181 return. If the agent cannot be started
182 (for example, because the agent class cannot be loaded,
183 or because the agent class does not have a conformant <code>agentmain</code> method), the JVM will
184 not abort. If the <code>agentmain</code> method throws an uncaught exception it will be ignored.
185
186
187
188 <h3>Manifest Attributes</h3>
189 The following manifest attributes are defined for an agent JAR file:
190 <blockquote>
191 <dl>
192 <dt><code>Premain-Class</code></dt>
193 <dd>
194 When an agent is specified at JVM launch time this attribute
195 specifies the agent class.
196 That is, the class containing the <code>premain</code> method.
197 When an agent is specified at JVM launch time this attribute
198 is required. If the attribute is not present the JVM will abort.
199 Note: this is a class name, not a file name or path.
200 </dd>
201
202 <dt><code>Agent-Class</code></dt>
203 <dd>
204 If an implementation supports a mechanism to start agents
205 sometime after the VM has started then this attribute specifies
206 the agent class.
207 That is, the class containing the <code>agentmain</code> method.
208 This attribute is required, if it is not present the agent
209 will not be started.
210 Note: this is a class name, not a file name or path.
211 </dd>
212
213 <dt><code>Boot-Class-Path</code></dt>
214 <dd>
215 A list of paths to be searched by the bootstrap class
216 loader. Paths represent directories or libraries
217 (commonly referred to as JAR or zip libraries on
218 many platforms).
219 These paths are searched by the
220 bootstrap class loader after the platform specific
221 mechanisms of locating a class have failed.
222 Paths are searched in the order listed.
223 Paths in the list are separated by one or more spaces.
224 A path takes the syntax of the path component of a
225 hierarchical URI. The path is
226 absolute if it begins with a slash character ('/'),
227 otherwise it is relative. A relative path is resolved
228 against the absolute path of the agent JAR file.
229 Malformed and non-existent paths are ignored.
230 When an agent is started sometime after the VM has
231 started then paths that do not represent a JAR file
232 are ignored.
233 This attribute is optional.
234 </dd>
235 <dt><code>Can-Redefine-Classes</code></dt>
236 <dd>
237 Boolean (<code>true</code> or <code>false</code>, case irrelevant).
238 Is the ability to redefine classes
239 needed by this agent.
240 Values other than <code>true</code> are considered <code>false</code>.
241 This attribute is optional, the default is <code>false</code>.
242 </dd>
243 <dt><code>Can-Retransform-Classes</code></dt>
244 <dd>
245 Boolean (<code>true</code> or <code>false</code>, case irrelevant).
246 Is the ability to retransform classes
247 needed by this agent.
248 Values other than <code>true</code> are considered <code>false</code>.
249 This attribute is optional, the default is <code>false</code>.
250 </dd>
251 <dt><code>Can-Set-Native-Method-Prefix</code></dt>
252 <dd>
253 Boolean (<code>true</code> or <code>false</code>, case irrelevant).
254 Is the ability to set native method prefix needed by this agent.
255 Values other than <code>true</code> are considered <code>false</code>.
256 This attribute is optional, the default is <code>false</code>.
257 </dd>
258 </dl>
259 </blockquote>
260
261 <p>
262 An agent JAR file may have both the <code>Premain-Class</code> and <code>Agent-Class</code>
263 attributes present in the manifest. When the agent is started on the command-line using
264 the <code>-javaagent</code> option then the <code>Premain-Class</code> attribute
265 specifies the name of the agent class and the <code>Agent-Class</code> attribute is
266 ignored. Similarly, if the agent is started sometime after the VM has started, then
267 the <code>Agent-Class</code> attribute specifies the name of the agent class
268 (the value of <code>Premain-Class</code> attribute is ignored).
269
270 <h2>Related Documentation</h2>
271
272 For tool documentation, please see:
273 <ul>
274 <li><a href="{@docRoot}/../technotes/tools/index.html">JDK Tools and Utilities</a>
275 </ul>
276
277 @since 1.5
278 @revised 1.6
279
280 </body>
281 </html>