1 <!-- 2 Copyright (c) 2003, 2013, 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. <p></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 JDK1.5 278 @revised 1.6 279 280 </body> 281 </html>