1/* 2 * Copyright (c) 2003, 2017, 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/* 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 * 55 * <h3>Starting an Agent from the Command-Line Interface</h3> 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 * 116 * <h3>Starting an Agent After VM Startup</h3> 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 * 167 * <h3>Including an Agent in an Executable JAR file</h3> 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 * 197 * <h3> Loading agent classes and the modules/classes available to the agent 198 * class </h3> 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 * 245 * <h3>Manifest Attributes</h3> 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 * 314 * <h3>Instrumenting code in modules</h3> 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 326package java.lang.instrument;