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