| J. Duke | 319a3b9 | 2007-12-01 00:00:00 +0000 | [diff] [blame^] | 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> |