1 <!--
   2  Copyright 2003-2006 Sun Microsystems, Inc.  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.  Sun designates this
   8  particular file as subject to the "Classpath" exception as provided
   9  by Sun 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 Sun Microsystems, Inc., 4150 Network Circle, Santa Clara,
  22  CA 95054 USA or visit www.sun.com if you need additional information or
  23  have any 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 On implementations with a command-line interface, an agent is started by
  57 adding this option to the command-line:
  58 <blockquote>
  59 <code><b>-javaagent:</b></code><i>jarpath[</i><code><b>=</b></code><i>options]</i>
  60 </blockquote>
  61 <i>jarpath</i> is the path to the agent JAR file.
  62 <i>options</i> is the agent options.
  63 This switch may be used multiple times on the same command-line, 
  64 thus creating multiple agents.
  65 More than one agent may use the same <i>jarpath</i>.
  66 An agent JAR file must conform to the JAR file specification.
  67 
  68 <P>
  69 The manifest of the agent JAR file must contain the attribute <code>Premain-Class</code>. The
  70 value of this attribute is the name of the <i>agent class</i>. The agent class must implement a 
  71 public static <code>premain</code> method similar in principle to the <code>main</code> application 
  72 entry point.  After the Java Virtual Machine (JVM) has initialized, each <code>premain</code> method 
  73 will be called in the order the agents were specified, then the real application
  74 <code>main</code> method will be called. 
  75 Each <code>premain</code> method must return in order for the startup sequence to proceed.
  76 
  77 <P>
  78 The <code>premain</code> method has one of two possible signatures. The JVM first attempts to
  79 invoke the following method on the agent class:
  80 
  81 <blockquote>
  82 <code>public static void
  83 premain(String agentArgs, Instrumentation inst);
  84 </code>
  85 </blockquote>
  86 
  87 <P>
  88 If the agent class does not implement this method then the JVM will attempt to invoke:
  89 
  90 <blockquote>
  91 <code>public static void
  92 premain(String agentArgs);
  93 </code>
  94 </blockquote>
  95 
  96 <P>
  97 The agent class may also have an <code>agentmain</code> method for use when the agent is started 
  98 after VM startup. When the agent is started using a command-line option, the <code>agentmain</code>
  99 method is not invoked.
 100 
 101 
 102 <P>
 103 The agent class will be loaded by the system class loader
 104 (see {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}). This is
 105 the class loader which typically loads the class containing the application <code>main</code> method.
 106 The <code>premain</code> methods will be run under the same security and classloader 
 107 rules as the application <code>main</code> method.
 108 There are no modeling restrictions on what the agent <code>premain</code> method may do.
 109 Anything application <code>main</code> can do, including creating threads, is legal from <code>premain</code>.
 110 
 111 <P>
 112 Each agent is passed its agent options via the <code>agentArgs</code> parameter.
 113 The agent options are passed as a single string,
 114 any additional parsing should be performed by the agent itself.
 115 
 116 <P>
 117 If the agent cannot be resolved 
 118 (for example, because the agent class cannot be loaded,
 119 or because the agent class does not have an appropriate <code>premain</code> method), the JVM will abort.
 120 If a <code>premain</code> method throws an uncaught exception, the JVM will abort.
 121 
 122 
 123 
 124 <h3>Starting Agents After VM Startup</h3>
 125 
 126 <p>
 127 An implementation may provide a mechanism to start agents sometime after the
 128 the VM has started. The details as to how this is initiated are implementation 
 129 specific but typically the application has already started and its <code>
 130 main</code> method has already been invoked. In cases where an implementation
 131 supports the starting of agents after the VM has started the following applies:
 132 
 133 <ol>
 134   <li><p>The manifest of the agent JAR must contain the attribute <code>Agent-Class</code>. 
 135       The value of this attribute is the name of the <i>agent class</i>. </p></li> 
 136       
 137   <li><p>The agent class must implement a public static <code>agentmain</code> method. </p></li>
 138 
 139   <li><p>The system class loader (
 140       {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}) must
 141       support a mechanism to add an agent JAR file to the system class path. <p></li>
 142 </ol>  
 143 
 144 <P>
 145 The agent JAR is appended to the system class path. This is the class loader that typically loads 
 146 the class containing the application <code>main</code> method. The agent class is loaded and the
 147 JVM attempts to invoke the <code>agentmain</code> method. The JVM first attempts to invoke 
 148 the following method on the agent class:
 149 
 150 <blockquote>
 151 <code>public static void
 152 agentmain(String agentArgs, Instrumentation inst);
 153 </code>
 154 </blockquote>
 155 
 156 <P>
 157 If the agent class does not implement this method then the JVM will attempt to invoke:
 158 
 159 <blockquote>
 160 <code>public static void
 161 agentmain(String agentArgs);
 162 </code>
 163 </blockquote>
 164 
 165 <P>
 166 The agent class may also have an <code>premain</code> method for use when the agent is started
 167 using a command-line option. When the agent is started after VM startup the <code>premain</code>
 168 method is not invoked.
 169 
 170 
 171 <P>
 172 The agent is passed its agent options via the <code>agentArgs</code> parameter.
 173 The agent options are passed as a single string,
 174 any additional parsing should be performed by the agent itself. 
 175 
 176 <P>
 177 The <code>agentmain</code> method should do any necessary initialization 
 178 required to start the agent. When startup is complete the method should 
 179 return. If the agent cannot be started
 180 (for example, because the agent class cannot be loaded,
 181 or because the agent class does not have a conformant <code>agentmain</code> method), the JVM will
 182 not abort. If the <code>agentmain</code> method throws an uncaught exception it will be ignored.
 183 
 184 
 185 
 186 <h3>Manifest Attributes</h3>
 187 The following manifest attributes are defined for an agent JAR file:
 188 <blockquote>
 189 <dl>
 190 <dt><code>Premain-Class</code></dt>
 191 <dd>
 192                         When an agent is specified at JVM launch time this attribute
 193                         specifies the agent class.
 194                         That is, the class containing the <code>premain</code> method.
 195                         When an agent is specified at JVM launch time this attribute
 196                         is required. If the attribute is not present the JVM will abort.
 197                         Note: this is a class name, not a file name or path.                                                    
 198 </dd>
 199 
 200 <dt><code>Agent-Class</code></dt>
 201 <dd>
 202                         If an implementation supports a mechanism to start agents 
 203                         sometime after the VM has started then this attribute specifies
 204                         the agent class.
 205                         That is, the class containing the <code>agentmain</code> method.
 206                         This attribute is required, if it is not present the agent
 207                         will not be started.
 208                         Note: this is a class name, not a file name or path.
 209 </dd>                     
 210 
 211 <dt><code>Boot-Class-Path</code></dt>
 212 <dd>
 213                         A list of paths to be searched by the bootstrap class
 214                         loader. Paths represent directories or libraries
 215                         (commonly referred to as JAR or zip libraries on
 216                         many platforms).                        
 217                         These paths are searched by the
 218                         bootstrap class loader after the platform specific
 219                         mechanisms of locating a class have failed.
 220                         Paths are searched in the order listed.
 221                         Paths in the list are separated by one or more spaces.
 222                         A path takes the syntax of the path component of a
 223                         hierarchical URI. The path is
 224                         absolute if it begins with a slash character ('/'),
 225                         otherwise it is relative. A relative path is resolved
 226                         against the absolute path of the agent JAR file.
 227                         Malformed and non-existent paths are ignored.   
 228                         When an agent is started sometime after the VM has
 229                         started then paths that do not represent a JAR file
 230                         are ignored.
 231                         This attribute is optional.
 232 </dd>
 233 <dt><code>Can-Redefine-Classes</code></dt>
 234 <dd>
 235                         Boolean (<code>true</code> or <code>false</code>, case irrelevant).
 236                         Is the ability to redefine classes
 237                         needed by this agent.
 238                         Values other than <code>true</code> are considered <code>false</code>.
 239                         This attribute is optional, the default is <code>false</code>.
 240 </dd>
 241 <dt><code>Can-Retransform-Classes</code></dt>
 242 <dd>
 243                         Boolean (<code>true</code> or <code>false</code>, case irrelevant).
 244                         Is the ability to retransform classes
 245                         needed by this agent.
 246                         Values other than <code>true</code> are considered <code>false</code>.
 247                         This attribute is optional, the default is <code>false</code>.
 248 </dd>
 249 <dt><code>Can-Set-Native-Method-Prefix</code></dt>
 250 <dd>
 251                         Boolean (<code>true</code> or <code>false</code>, case irrelevant).
 252                         Is the ability to set native method prefix needed by this agent.
 253                         Values other than <code>true</code> are considered <code>false</code>.
 254                         This attribute is optional, the default is <code>false</code>.
 255 </dd>
 256 </dl>
 257 </blockquote>
 258 
 259 <p> 
 260 An agent JAR file may have both the <code>Premain-Class</code> and <code>Agent-Class</code>
 261 attributes present in the manifest. When the agent is started on the command-line using
 262 the <code>-javaagent</code> option then the <code>Premain-Class</code> attribute
 263 specifies the name of the agent class and the <code>Agent-Class</code> attribute is
 264 ignored. Similarly, if the agent is started sometime after the VM has started, then
 265 the <code>Agent-Class</code> attribute specifies the name of the agent class
 266 (the value of <code>Premain-Class</code> attribute is ignored).
 267 
 268 <h2>Related Documentation</h2>
 269 
 270 For tool documentation, please see:
 271 <ul>
 272   <li><a href="{@docRoot}/../technotes/tools/index.html">JDK Tools and Utilities</a>
 273 </ul>
 274 
 275 @since JDK1.5
 276 @revised 1.6
 277 
 278 </body>
 279 </html>