author | gadams |
Tue, 12 Mar 2019 11:53:06 -0400 | |
changeset 54080 | 75268d993deb |
parent 54079 | 018217e30f5c |
permissions | -rw-r--r-- |
45652 | 1 |
/* |
54079 | 2 |
* Copyright (c) 2003, 2019, Oracle and/or its affiliates. All rights reserved. |
45652 | 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 |
|
54080
75268d993deb
8220474: Incorrect GPL header in src/java.instrument/share/classes/java/lang/instrument/package-info.java
gadams
parents:
54079
diff
changeset
|
8 |
* particular file as subject to the "Classpath" exception as provided |
45652 | 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 |
/* |
|
27 |
* Copyright 2003 Wily Technology, Inc. |
|
28 |
*/ |
|
29 |
||
30 |
/** |
|
31 |
* Provides services that allow Java programming language agents to instrument |
|
32 |
* programs running on the JVM. The mechanism for instrumentation is modification |
|
33 |
* of the byte-codes of methods. |
|
34 |
* |
|
35 |
* <p> An agent is deployed as a JAR file. An attribute in the JAR file manifest |
|
36 |
* specifies the agent class which will be loaded to start the agent. Agents can |
|
37 |
* be started in several ways: |
|
38 |
* |
|
39 |
* <ol> |
|
40 |
* <li><p> For implementations that support a command-line interface, an agent |
|
41 |
* can be started by specifying an option on the command-line. </p></li> |
|
42 |
* |
|
43 |
* <li><p> An implementation may support a mechanism to start agents some time |
|
44 |
* after the VM has started. For example, an implementation may provide a |
|
45 |
* mechanism that allows a tool to <i>attach</i> to a running application, and |
|
46 |
* initiate the loading of the tool's agent into the running application. </p></li> |
|
47 |
* |
|
48 |
* <li><p> An agent may be packaged with an application in an executable JAR |
|
49 |
* file.</p></li> |
|
50 |
* </ol> |
|
51 |
* |
|
52 |
* <p> Each of these ways to start an agent is described below. |
|
53 |
* |
|
54 |
* |
|
54079 | 55 |
* <h2>Starting an Agent from the Command-Line Interface</h2> |
45652 | 56 |
* |
57 |
* <p> Where an implementation provides a means to start agents from the |
|
58 |
* command-line interface, an agent is started by adding the following option |
|
59 |
* to the command-line: |
|
60 |
* |
|
61 |
* <blockquote>{@code |
|
62 |
* -javaagent:<jarpath>[=<options>] |
|
63 |
* }</blockquote> |
|
64 |
* |
|
65 |
* where <i>{@code <jarpath>}</i> is the path to the agent JAR file and |
|
66 |
* <i>{@code <options>}</i> is the agent options. |
|
67 |
* |
|
68 |
* <p> The manifest of the agent JAR file must contain the attribute {@code |
|
69 |
* Premain-Class} in its main manifest. The value of this attribute is the |
|
70 |
* name of the <i>agent class</i>. The agent class must implement a public |
|
71 |
* static {@code premain} method similar in principle to the {@code main} |
|
72 |
* application entry point. After the Java Virtual Machine (JVM) has |
|
73 |
* initialized, the {@code premain} method will be called, then the real |
|
74 |
* application {@code main} method. The {@code premain} method must return |
|
75 |
* in order for the startup to proceed. |
|
76 |
* |
|
77 |
* <p> The {@code premain} method has one of two possible signatures. The |
|
78 |
* JVM first attempts to invoke the following method on the agent class: |
|
79 |
* |
|
80 |
* <blockquote>{@code |
|
81 |
* public static void premain(String agentArgs, Instrumentation inst) |
|
82 |
* }</blockquote> |
|
83 |
* |
|
84 |
* <p> If the agent class does not implement this method then the JVM will |
|
85 |
* attempt to invoke: |
|
86 |
* <blockquote>{@code |
|
87 |
* public static void premain(String agentArgs) |
|
88 |
* }</blockquote> |
|
89 |
||
90 |
* <p> The agent class may also have an {@code agentmain} method for use when |
|
91 |
* the agent is started after VM startup (see below). When the agent is started |
|
92 |
* using a command-line option, the {@code agentmain} method is not invoked. |
|
93 |
* |
|
94 |
* <p> Each agent is passed its agent options via the {@code agentArgs} parameter. |
|
95 |
* The agent options are passed as a single string, any additional parsing |
|
96 |
* should be performed by the agent itself. |
|
97 |
* |
|
98 |
* <p> If the agent cannot be started (for example, because the agent class |
|
99 |
* cannot be loaded, or because the agent class does not have an appropriate |
|
100 |
* {@code premain} method), the JVM will abort. If a {@code premain} method |
|
101 |
* throws an uncaught exception, the JVM will abort. |
|
102 |
* |
|
103 |
* <p> An implementation is not required to provide a way to start agents |
|
104 |
* from the command-line interface. When it does, then it supports the |
|
105 |
* {@code -javaagent} option as specified above. The {@code -javaagent} option |
|
106 |
* may be used multiple times on the same command-line, thus starting multiple |
|
107 |
* agents. The {@code premain} methods will be called in the order that the |
|
108 |
* agents are specified on the command line. More than one agent may use the |
|
109 |
* same <i>{@code <jarpath>}</i>. |
|
110 |
* |
|
111 |
* <p> There are no modeling restrictions on what the agent {@code premain} |
|
112 |
* method may do. Anything application {@code main} can do, including creating |
|
113 |
* threads, is legal from {@code premain}. |
|
114 |
* |
|
115 |
* |
|
54079 | 116 |
* <h2>Starting an Agent After VM Startup</h2> |
45652 | 117 |
* |
118 |
* <p> An implementation may provide a mechanism to start agents sometime after |
|
119 |
* the the VM has started. The details as to how this is initiated are |
|
120 |
* implementation specific but typically the application has already started and |
|
121 |
* its {@code main} method has already been invoked. In cases where an |
|
122 |
* implementation supports the starting of agents after the VM has started the |
|
123 |
* following applies: |
|
124 |
* |
|
125 |
* <ol> |
|
126 |
* |
|
127 |
* <li><p> The manifest of the agent JAR must contain the attribute {@code |
|
128 |
* Agent-Class} in its main manfiest. The value of this attribute is the name |
|
129 |
* of the <i>agent class</i>. </p></li> |
|
130 |
* |
|
131 |
* <li><p> The agent class must implement a public static {@code agentmain} |
|
132 |
* method. </p></li> |
|
133 |
* |
|
134 |
* </ol> |
|
135 |
* |
|
136 |
* <p> The {@code agentmain} method has one of two possible signatures. The JVM |
|
137 |
* first attempts to invoke the following method on the agent class: |
|
138 |
* |
|
139 |
* <blockquote>{@code |
|
140 |
* public static void agentmain(String agentArgs, Instrumentation inst) |
|
141 |
* }</blockquote> |
|
142 |
* |
|
143 |
* <p> If the agent class does not implement this method then the JVM will |
|
144 |
* attempt to invoke: |
|
145 |
* |
|
146 |
* <blockquote>{@code |
|
147 |
* public static void agentmain(String agentArgs) |
|
148 |
* }</blockquote> |
|
149 |
* |
|
150 |
* <p> The agent class may also have a {@code premain} method for use when the |
|
151 |
* agent is started using a command-line option. When the agent is started after |
|
152 |
* VM startup the {@code premain} method is not invoked. |
|
153 |
* |
|
154 |
* <p> The agent is passed its agent options via the {@code agentArgs} |
|
155 |
* parameter. The agent options are passed as a single string, any additional |
|
156 |
* parsing should be performed by the agent itself. |
|
157 |
* |
|
158 |
* <p> The {@code agentmain} method should do any necessary initialization |
|
159 |
* required to start the agent. When startup is complete the method should |
|
160 |
* return. If the agent cannot be started (for example, because the agent class |
|
161 |
* cannot be loaded, or because the agent class does not have a conformant |
|
162 |
* {@code agentmain} method), the JVM will not abort. If the {@code agentmain} |
|
163 |
* method throws an uncaught exception it will be ignored (but may be logged |
|
164 |
* by the JVM for troubleshooting purposes). |
|
165 |
* |
|
166 |
* |
|
54079 | 167 |
* <h2>Including an Agent in an Executable JAR file</h2> |
45652 | 168 |
* |
169 |
* <p> The JAR File Specification defines manifest attributes for standalone |
|
170 |
* applications that are packaged as <em>executable JAR files</em>. If an |
|
171 |
* implementation supports a mechanism to start an application as an executable |
|
172 |
* JAR then the main manifest may include the {@code Launcher-Agent-Class} |
|
173 |
* attribute to specify the class name of an agent to start before the application |
|
174 |
* {@code main} method is invoked. The Java virtual machine attempts to |
|
175 |
* invoke the following method on the agent class: |
|
176 |
* |
|
177 |
* <blockquote>{@code |
|
178 |
* public static void agentmain(String agentArgs, Instrumentation inst) |
|
179 |
* }</blockquote> |
|
180 |
* |
|
181 |
* <p> If the agent class does not implement this method then the JVM will |
|
182 |
* attempt to invoke: |
|
183 |
* |
|
184 |
* <blockquote>{@code |
|
185 |
* public static void agentmain(String agentArgs) |
|
186 |
* }</blockquote> |
|
187 |
* |
|
188 |
* <p> The value of the {@code agentArgs} parameter is always the empty string. |
|
189 |
* |
|
190 |
* <p> The {@code agentmain} method should do any necessary initialization |
|
191 |
* required to start the agent and return. If the agent cannot be started, for |
|
192 |
* example the agent class cannot be loaded, the agent class does not define a |
|
193 |
* conformant {@code agentmain} method, or the {@code agentmain} method throws |
|
194 |
* an uncaught exception or error, the JVM will abort. |
|
195 |
* |
|
196 |
* |
|
54079 | 197 |
* <h2> Loading agent classes and the modules/classes available to the agent |
198 |
* class </h2> |
|
45652 | 199 |
* |
200 |
* <p> Classes loaded from the agent JAR file are loaded by the |
|
201 |
* {@linkplain ClassLoader#getSystemClassLoader() system class loader} and are |
|
202 |
* members of the system class loader's {@linkplain ClassLoader#getUnnamedModule() |
|
203 |
* unnamed module}. The system class loader typically defines the class containing |
|
204 |
* the application {@code main} method too. |
|
205 |
* |
|
206 |
* <p> The classes visible to the agent class are the classes visible to the system |
|
207 |
* class loader and minimally include: |
|
208 |
* |
|
209 |
* <ul> |
|
210 |
* |
|
211 |
* <li><p> The classes in packages exported by the modules in the {@linkplain |
|
212 |
* ModuleLayer#boot() boot layer}. Whether the boot layer contains all platform |
|
213 |
* modules or not will depend on the initial module or how the application was |
|
214 |
* started. </p></li> |
|
215 |
* |
|
216 |
* <li><p> The classes that can be defined by the system class loader (typically |
|
217 |
* the class path) to be members of its unnamed module. </p></li> |
|
218 |
* |
|
219 |
* <li><p> Any classes that the agent arranges to be defined by the bootstrap |
|
220 |
* class loader to be members of its unnamed module. </p></li> |
|
221 |
* |
|
222 |
* </ul> |
|
223 |
* |
|
224 |
* <p> If agent classes need to link to classes in platform (or other) modules |
|
225 |
* that are not in the boot layer then the application may need to be started in |
|
226 |
* a way that ensures that these modules are in the boot layer. In the JDK |
|
227 |
* implementation for example, the {@code --add-modules} command line option can |
|
228 |
* be used to add modules to the set of root modules to resolve at startup. </p> |
|
229 |
* |
|
230 |
* <p> Supporting classes that the agent arranges to be loaded by the bootstrap |
|
231 |
* class loader (by means of {@link Instrumentation#appendToBootstrapClassLoaderSearch |
|
232 |
* appendToBootstrapClassLoaderSearch} or the {@code Boot-Class-Path} attribute |
|
233 |
* specified below), must link only to classes defined to the bootstrap class loader. |
|
234 |
* There is no guarantee that all platform classes can be defined by the boot |
|
235 |
* class loader. |
|
236 |
* |
|
237 |
* <p> If a custom system class loader is configured (by means of the system property |
|
238 |
* {@code java.system.class.loader} as specified in the {@link |
|
239 |
* ClassLoader#getSystemClassLoader() getSystemClassLoader} method) then it must |
|
240 |
* define the {@code appendToClassPathForInstrumentation} method as specified in |
|
241 |
* {@link Instrumentation#appendToSystemClassLoaderSearch appendToSystemClassLoaderSearch}. |
|
242 |
* In other words, a custom system class loader must support the mechanism to |
|
243 |
* add an agent JAR file to the system class loader search. |
|
244 |
* |
|
54079 | 245 |
* <h2>Manifest Attributes</h2> |
45652 | 246 |
* |
247 |
* <p> The following manifest attributes are defined for an agent JAR file: |
|
248 |
* |
|
249 |
* <blockquote><dl> |
|
250 |
* |
|
251 |
* <dt>{@code Premain-Class}</dt> |
|
252 |
* <dd> When an agent is specified at JVM launch time this attribute specifies |
|
253 |
* the agent class. That is, the class containing the {@code premain} method. |
|
254 |
* When an agent is specified at JVM launch time this attribute is required. If |
|
255 |
* the attribute is not present the JVM will abort. Note: this is a class name, |
|
256 |
* not a file name or path. </dd> |
|
257 |
* |
|
258 |
* <dt>{@code Agent-Class}</dt> |
|
259 |
* <dd> If an implementation supports a mechanism to start agents sometime after |
|
260 |
* the VM has started then this attribute specifies the agent class. That is, |
|
261 |
* the class containing the {@code agentmain} method. This attribute is required |
|
262 |
* if it is not present the agent will not be started. Note: this is a class name, |
|
263 |
* not a file name or path. </dd> |
|
264 |
* |
|
265 |
* <dt>{@code Launcher-Agent-Class}</dt> |
|
266 |
* <dd> If an implementation supports a mechanism to start an application as an |
|
267 |
* executable JAR then the main manifest may include this attribute to specify |
|
268 |
* the class name of an agent to start before the application {@code main} |
|
269 |
* method is invoked. </dd> |
|
270 |
* |
|
271 |
* <dt>{@code Boot-Class-Path}</dt> |
|
272 |
* <dd> A list of paths to be searched by the bootstrap class loader. Paths |
|
273 |
* represent directories or libraries (commonly referred to as JAR or zip |
|
274 |
* libraries on many platforms). These paths are searched by the bootstrap class |
|
275 |
* loader after the platform specific mechanisms of locating a class have failed. |
|
276 |
* Paths are searched in the order listed. Paths in the list are separated by one |
|
277 |
* or more spaces. A path takes the syntax of the path component of a hierarchical |
|
278 |
* URI. The path is absolute if it begins with a slash character ('/'), otherwise |
|
279 |
* it is relative. A relative path is resolved against the absolute path of the |
|
280 |
* agent JAR file. Malformed and non-existent paths are ignored. When an agent is |
|
281 |
* started sometime after the VM has started then paths that do not represent a |
|
282 |
* JAR file are ignored. This attribute is optional. </dd> |
|
283 |
* |
|
284 |
* <dt>{@code Can-Redefine-Classes}</dt> |
|
285 |
* <dd> Boolean ({@code true} or {@code false}, case irrelevant). Is the ability |
|
286 |
* to redefine classes needed by this agent. Values other than {@code true} are |
|
287 |
* considered {@code false}. This attribute is optional, the default is {@code |
|
288 |
* false}. </dd> |
|
289 |
* |
|
290 |
* <dt>{@code Can-Retransform-Classes}</dt> |
|
291 |
* <dd> Boolean ({@code true} or {@code false}, case irrelevant). Is the ability |
|
292 |
* to retransform classes needed by this agent. Values other than {@code true} |
|
293 |
* are considered {@code false}. This attribute is optional, the default is |
|
294 |
* {@code false}. </dd> |
|
295 |
* |
|
296 |
* <dt>{@code Can-Set-Native-Method-Prefix}</dt> |
|
297 |
* <dd> Boolean ({@code true} or {@code false}, case irrelevant). Is the ability |
|
298 |
* to set native method prefix needed by this agent. Values other than {@code |
|
299 |
* true} are considered {@code false}. This attribute is optional, the default |
|
300 |
* is {@code false}. </dd> |
|
301 |
* |
|
302 |
* </dl></blockquote> |
|
303 |
* |
|
304 |
* <p> An agent JAR file may have both the {@code Premain-Class} and {@code |
|
305 |
* Agent-Class} attributes present in the manifest. When the agent is started |
|
306 |
* on the command-line using the {@code -javaagent} option then the {@code |
|
307 |
* Premain-Class} attribute specifies the name of the agent class and the {@code |
|
308 |
* Agent-Class} attribute is ignored. Similarly, if the agent is started sometime |
|
309 |
* after the VM has started, then the {@code Agent-Class} attribute specifies |
|
310 |
* the name of the agent class (the value of {@code Premain-Class} attribute is |
|
311 |
* ignored). |
|
312 |
* |
|
313 |
* |
|
54079 | 314 |
* <h2>Instrumenting code in modules</h2> |
45652 | 315 |
* |
316 |
* <p> As an aid to agents that deploy supporting classes on the search path of |
|
317 |
* the bootstrap class loader, or the search path of the class loader that loads |
|
318 |
* the main agent class, the Java virtual machine arranges for the module of |
|
319 |
* transformed classes to read the unnamed module of both class loaders. |
|
320 |
* |
|
321 |
* @since 1.5 |
|
322 |
* @revised 1.6 |
|
323 |
* @revised 9 |
|
324 |
*/ |
|
325 |
||
54079 | 326 |
package java.lang.instrument; |