ojluni/src/main/java/java/lang/instrument/package.html - platform/libcore - Git at Google

 <!--
  Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
  DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

  This code is free software; you can redistribute it and/or modify it
  under the terms of the GNU General Public License version 2 only, as
  published by the Free Software Foundation.  Oracle designates this
  particular file as subject to the "Classpath" exception as provided
  by Oracle in the LICENSE file that accompanied this code.

  This code is distributed in the hope that it will be useful, but WITHOUT
  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  version 2 for more details (a copy is included in the LICENSE file that
  accompanied this code).

  You should have received a copy of the GNU General Public License version
  2 along with this work; if not, write to the Free Software Foundation,
  Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

  Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  or visit www.oracle.com if you need additional information or have any
  questions.
 -->

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
 <html>
 <head>
 <!--

   Copyright 2003 Wily Technology, Inc.

 -->
 </head>

 <body bgcolor="white">

 Provides services that allow Java programming language agents to instrument programs running on the JVM.
 The mechanism for instrumentation is modification of the byte-codes of methods.

 <h2>Package Specification</h2>

 <P>
 An agent is deployed as a JAR file. An attribute in the JAR file manifest specifies the
 agent class which will be loaded to start the agent. For implementations that support a command-line
 interface, an agent is started by specifying an option on the command-line.
 Implementations may also support a mechanism to start agents some time after the VM has
 started. For example, an implementation may provide a mechanism that allows a tool to
 <i>attach</i> to a running application, and initiate the loading of the tool's agent into
 the running application. The details as to how the load is initiated, is implementation
 dependent.

 <h3>Command-Line Interface</h3>

 <P>
 On implementations with a command-line interface, an agent is started by
 adding this option to the command-line:
 <blockquote>
 <code><b>-javaagent:</b></code><i>jarpath[</i><code><b>=</b></code><i>options]</i>
 </blockquote>
 <i>jarpath</i> is the path to the agent JAR file.
 <i>options</i> is the agent options.
 This switch may be used multiple times on the same command-line,
 thus creating multiple agents.
 More than one agent may use the same <i>jarpath</i>.
 An agent JAR file must conform to the JAR file specification.

 <P>
 The manifest of the agent JAR file must contain the attribute <code>Premain-Class</code>. The
 value of this attribute is the name of the <i>agent class</i>. The agent class must implement a
 public static <code>premain</code> method similar in principle to the <code>main</code> application
 entry point.  After the Java Virtual Machine (JVM) has initialized, each <code>premain</code> method
 will be called in the order the agents were specified, then the real application
 <code>main</code> method will be called.
 Each <code>premain</code> method must return in order for the startup sequence to proceed.

 <P>
 The <code>premain</code> method has one of two possible signatures. The JVM first attempts to
 invoke the following method on the agent class:

 <blockquote>
 <code>public static void
 premain(String agentArgs, Instrumentation inst);
 </code>
 </blockquote>

 <P>
 If the agent class does not implement this method then the JVM will attempt to invoke:

 <blockquote>
 <code>public static void
 premain(String agentArgs);
 </code>
 </blockquote>

 <P>
 The agent class may also have an <code>agentmain</code> method for use when the agent is started
 after VM startup. When the agent is started using a command-line option, the <code>agentmain</code>
 method is not invoked.


 <P>
 The agent class will be loaded by the system class loader
 (see {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}). This is
 the class loader which typically loads the class containing the application <code>main</code> method.
 The <code>premain</code> methods will be run under the same security and classloader
 rules as the application <code>main</code> method.
 There are no modeling restrictions on what the agent <code>premain</code> method may do.
 Anything application <code>main</code> can do, including creating threads, is legal from <code>premain</code>.

 <P>
 Each agent is passed its agent options via the <code>agentArgs</code> parameter.
 The agent options are passed as a single string,
 any additional parsing should be performed by the agent itself.

 <P>
 If the agent cannot be resolved
 (for example, because the agent class cannot be loaded,
 or because the agent class does not have an appropriate <code>premain</code> method), the JVM will abort.
 If a <code>premain</code> method throws an uncaught exception, the JVM will abort.


 <h3>Starting Agents After VM Startup</h3>

 <p>
 An implementation may provide a mechanism to start agents sometime after the
 the VM has started. The details as to how this is initiated are implementation
 specific but typically the application has already started and its <code>
 main</code> method has already been invoked. In cases where an implementation
 supports the starting of agents after the VM has started the following applies:

 <ol>
   <li><p>The manifest of the agent JAR must contain the attribute <code>Agent-Class</code>.
       The value of this attribute is the name of the <i>agent class</i>. </p></li>

   <li><p>The agent class must implement a public static <code>agentmain</code> method. </p></li>

   <li><p>The system class loader (
       {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}) must
       support a mechanism to add an agent JAR file to the system class path. <p></li>
 </ol>

 <P>
 The agent JAR is appended to the system class path. This is the class loader that typically loads
 the class containing the application <code>main</code> method. The agent class is loaded and the
 JVM attempts to invoke the <code>agentmain</code> method. The JVM first attempts to invoke
 the following method on the agent class:

 <blockquote>
 <code>public static void
 agentmain(String agentArgs, Instrumentation inst);
 </code>
 </blockquote>

 <P>
 If the agent class does not implement this method then the JVM will attempt to invoke:

 <blockquote>
 <code>public static void
 agentmain(String agentArgs);
 </code>
 </blockquote>

 <P>
 The agent class may also have an <code>premain</code> method for use when the agent is started
 using a command-line option. When the agent is started after VM startup the <code>premain</code>
 method is not invoked.


 <P>
 The agent is passed its agent options via the <code>agentArgs</code> parameter.
 The agent options are passed as a single string,
 any additional parsing should be performed by the agent itself.

 <P>
 The <code>agentmain</code> method should do any necessary initialization
 required to start the agent. When startup is complete the method should
 return. If the agent cannot be started
 (for example, because the agent class cannot be loaded,
 or because the agent class does not have a conformant <code>agentmain</code> method), the JVM will
 not abort. If the <code>agentmain</code> method throws an uncaught exception it will be ignored.


 <h3>Manifest Attributes</h3>
 The following manifest attributes are defined for an agent JAR file:
 <blockquote>
 <dl>
 <dt><code>Premain-Class</code></dt>
 <dd>
                         When an agent is specified at JVM launch time this attribute
 			specifies the agent class.
 			That is, the class containing the <code>premain</code> method.
                         When an agent is specified at JVM launch time this attribute
 			is required. If the attribute is not present the JVM will abort.
                         Note: this is a class name, not a file name or path.
 </dd>

 <dt><code>Agent-Class</code></dt>
 <dd>
                         If an implementation supports a mechanism to start agents
                         sometime after the VM has started then this attribute specifies
                         the agent class.
                         That is, the class containing the <code>agentmain</code> method.
                         This attribute is required, if it is not present the agent
                         will not be started.
                         Note: this is a class name, not a file name or path.
 </dd>

 <dt><code>Boot-Class-Path</code></dt>
 <dd>
                         A list of paths to be searched by the bootstrap class
                         loader. Paths represent directories or libraries
                         (commonly referred to as JAR or zip libraries on
                         many platforms).
                         These paths are searched by the
                         bootstrap class loader after the platform specific
                         mechanisms of locating a class have failed.
                         Paths are searched in the order listed.
                         Paths in the list are separated by one or more spaces.
                         A path takes the syntax of the path component of a
                         hierarchical URI. The path is
                         absolute if it begins with a slash character ('/'),
                         otherwise it is relative. A relative path is resolved
                         against the absolute path of the agent JAR file.
                         Malformed and non-existent paths are ignored.
 			When an agent is started sometime after the VM has
 			started then paths that do not represent a JAR file
 			are ignored.
                         This attribute is optional.
 </dd>
 <dt><code>Can-Redefine-Classes</code></dt>
 <dd>
                         Boolean (<code>true</code> or <code>false</code>, case irrelevant).
                         Is the ability to redefine classes
                         needed by this agent.
                         Values other than <code>true</code> are considered <code>false</code>.
                         This attribute is optional, the default is <code>false</code>.
 </dd>
 <dt><code>Can-Retransform-Classes</code></dt>
 <dd>
                         Boolean (<code>true</code> or <code>false</code>, case irrelevant).
                         Is the ability to retransform classes
                         needed by this agent.
                         Values other than <code>true</code> are considered <code>false</code>.
                         This attribute is optional, the default is <code>false</code>.
 </dd>
 <dt><code>Can-Set-Native-Method-Prefix</code></dt>
 <dd>
                         Boolean (<code>true</code> or <code>false</code>, case irrelevant).
                         Is the ability to set native method prefix needed by this agent.
                         Values other than <code>true</code> are considered <code>false</code>.
                         This attribute is optional, the default is <code>false</code>.
 </dd>
 </dl>
 </blockquote>

 <p>
 An agent JAR file may have both the <code>Premain-Class</code> and <code>Agent-Class</code>
 attributes present in the manifest. When the agent is started on the command-line using
 the <code>-javaagent</code> option then the <code>Premain-Class</code> attribute
 specifies the name of the agent class and the <code>Agent-Class</code> attribute is
 ignored. Similarly, if the agent is started sometime after the VM has started, then
 the <code>Agent-Class</code> attribute specifies the name of the agent class
 (the value of <code>Premain-Class</code> attribute is ignored).

 <h2>Related Documentation</h2>

 For tool documentation, please see:
 <ul>
   <li><a href="{@docRoot}/../technotes/tools/index.html">JDK Tools and Utilities</a>
 </ul>

 @since JDK1.5
 @revised 1.6

 </body>
 </html>
	<!--
	Copyright (c) 2003, 2006, Oracle and/or its affiliates. All rights reserved.
	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.

	This code is free software; you can redistribute it and/or modify it
	under the terms of the GNU General Public License version 2 only, as
	published by the Free Software Foundation. Oracle designates this
	particular file as subject to the "Classpath" exception as provided
	by Oracle in the LICENSE file that accompanied this code.

	This code is distributed in the hope that it will be useful, but WITHOUT
	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
	version 2 for more details (a copy is included in the LICENSE file that
	accompanied this code).

	You should have received a copy of the GNU General Public License version
	2 along with this work; if not, write to the Free Software Foundation,
	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.

	Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
	or visit www.oracle.com if you need additional information or have any
	questions.
	-->

	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
	<html>
	<head>
	<!--

	Copyright 2003 Wily Technology, Inc.

	-->
	</head>

	<body bgcolor="white">

	Provides services that allow Java programming language agents to instrument programs running on the JVM.
	The mechanism for instrumentation is modification of the byte-codes of methods.

	<h2>Package Specification</h2>

	<P>
	An agent is deployed as a JAR file. An attribute in the JAR file manifest specifies the
	agent class which will be loaded to start the agent. For implementations that support a command-line
	interface, an agent is started by specifying an option on the command-line.
	Implementations may also support a mechanism to start agents some time after the VM has
	started. For example, an implementation may provide a mechanism that allows a tool to
	<i>attach</i> to a running application, and initiate the loading of the tool's agent into
	the running application. The details as to how the load is initiated, is implementation
	dependent.

	<h3>Command-Line Interface</h3>

	<P>
	On implementations with a command-line interface, an agent is started by
	adding this option to the command-line:
	<blockquote>
	<code><b>-javaagent:</b></code><i>jarpath[</i><code><b>=</b></code><i>options]</i>
	</blockquote>
	<i>jarpath</i> is the path to the agent JAR file.
	<i>options</i> is the agent options.
	This switch may be used multiple times on the same command-line,
	thus creating multiple agents.
	More than one agent may use the same <i>jarpath</i>.
	An agent JAR file must conform to the JAR file specification.

	<P>
	The manifest of the agent JAR file must contain the attribute <code>Premain-Class</code>. The
	value of this attribute is the name of the <i>agent class</i>. The agent class must implement a
	public static <code>premain</code> method similar in principle to the <code>main</code> application
	entry point. After the Java Virtual Machine (JVM) has initialized, each <code>premain</code> method
	will be called in the order the agents were specified, then the real application
	<code>main</code> method will be called.
	Each <code>premain</code> method must return in order for the startup sequence to proceed.

	<P>
	The <code>premain</code> method has one of two possible signatures. The JVM first attempts to
	invoke the following method on the agent class:

	<blockquote>
	<code>public static void
	premain(String agentArgs, Instrumentation inst);
	</code>
	</blockquote>

	<P>
	If the agent class does not implement this method then the JVM will attempt to invoke:

	<blockquote>
	<code>public static void
	premain(String agentArgs);
	</code>
	</blockquote>

	<P>
	The agent class may also have an <code>agentmain</code> method for use when the agent is started
	after VM startup. When the agent is started using a command-line option, the <code>agentmain</code>
	method is not invoked.


	<P>
	The agent class will be loaded by the system class loader
	(see {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}). This is
	the class loader which typically loads the class containing the application <code>main</code> method.
	The <code>premain</code> methods will be run under the same security and classloader
	rules as the application <code>main</code> method.
	There are no modeling restrictions on what the agent <code>premain</code> method may do.
	Anything application <code>main</code> can do, including creating threads, is legal from <code>premain</code>.

	<P>
	Each agent is passed its agent options via the <code>agentArgs</code> parameter.
	The agent options are passed as a single string,
	any additional parsing should be performed by the agent itself.

	<P>
	If the agent cannot be resolved
	(for example, because the agent class cannot be loaded,
	or because the agent class does not have an appropriate <code>premain</code> method), the JVM will abort.
	If a <code>premain</code> method throws an uncaught exception, the JVM will abort.



	<h3>Starting Agents After VM Startup</h3>

	<p>
	An implementation may provide a mechanism to start agents sometime after the
	the VM has started. The details as to how this is initiated are implementation
	specific but typically the application has already started and its <code>
	main</code> method has already been invoked. In cases where an implementation
	supports the starting of agents after the VM has started the following applies:

	<ol>
	<li><p>The manifest of the agent JAR must contain the attribute <code>Agent-Class</code>.
	The value of this attribute is the name of the <i>agent class</i>. </p></li>

	<li><p>The agent class must implement a public static <code>agentmain</code> method. </p></li>

	<li><p>The system class loader (
	{@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}) must
	support a mechanism to add an agent JAR file to the system class path. <p></li>
	</ol>

	<P>
	The agent JAR is appended to the system class path. This is the class loader that typically loads
	the class containing the application <code>main</code> method. The agent class is loaded and the
	JVM attempts to invoke the <code>agentmain</code> method. The JVM first attempts to invoke
	the following method on the agent class:

	<blockquote>
	<code>public static void
	agentmain(String agentArgs, Instrumentation inst);
	</code>
	</blockquote>

	<P>
	If the agent class does not implement this method then the JVM will attempt to invoke:

	<blockquote>
	<code>public static void
	agentmain(String agentArgs);
	</code>
	</blockquote>

	<P>
	The agent class may also have an <code>premain</code> method for use when the agent is started
	using a command-line option. When the agent is started after VM startup the <code>premain</code>
	method is not invoked.


	<P>
	The agent is passed its agent options via the <code>agentArgs</code> parameter.
	The agent options are passed as a single string,
	any additional parsing should be performed by the agent itself.

	<P>
	The <code>agentmain</code> method should do any necessary initialization
	required to start the agent. When startup is complete the method should
	return. If the agent cannot be started
	(for example, because the agent class cannot be loaded,
	or because the agent class does not have a conformant <code>agentmain</code> method), the JVM will
	not abort. If the <code>agentmain</code> method throws an uncaught exception it will be ignored.



	<h3>Manifest Attributes</h3>
	The following manifest attributes are defined for an agent JAR file:
	<blockquote>
	<dl>
	<dt><code>Premain-Class</code></dt>
	<dd>
	When an agent is specified at JVM launch time this attribute
	specifies the agent class.
	That is, the class containing the <code>premain</code> method.
	When an agent is specified at JVM launch time this attribute
	is required. If the attribute is not present the JVM will abort.
	Note: this is a class name, not a file name or path.
	</dd>

	<dt><code>Agent-Class</code></dt>
	<dd>
	If an implementation supports a mechanism to start agents
	sometime after the VM has started then this attribute specifies
	the agent class.
	That is, the class containing the <code>agentmain</code> method.
	This attribute is required, if it is not present the agent
	will not be started.
	Note: this is a class name, not a file name or path.
	</dd>

	<dt><code>Boot-Class-Path</code></dt>
	<dd>
	A list of paths to be searched by the bootstrap class
	loader. Paths represent directories or libraries
	(commonly referred to as JAR or zip libraries on
	many platforms).
	These paths are searched by the
	bootstrap class loader after the platform specific
	mechanisms of locating a class have failed.
	Paths are searched in the order listed.
	Paths in the list are separated by one or more spaces.
	A path takes the syntax of the path component of a
	hierarchical URI. The path is
	absolute if it begins with a slash character ('/'),
	otherwise it is relative. A relative path is resolved
	against the absolute path of the agent JAR file.
	Malformed and non-existent paths are ignored.
	When an agent is started sometime after the VM has
	started then paths that do not represent a JAR file
	are ignored.
	This attribute is optional.
	</dd>
	<dt><code>Can-Redefine-Classes</code></dt>
	<dd>
	Boolean (<code>true</code> or <code>false</code>, case irrelevant).
	Is the ability to redefine classes
	needed by this agent.
	Values other than <code>true</code> are considered <code>false</code>.
	This attribute is optional, the default is <code>false</code>.
	</dd>
	<dt><code>Can-Retransform-Classes</code></dt>
	<dd>
	Boolean (<code>true</code> or <code>false</code>, case irrelevant).
	Is the ability to retransform classes
	needed by this agent.
	Values other than <code>true</code> are considered <code>false</code>.
	This attribute is optional, the default is <code>false</code>.
	</dd>
	<dt><code>Can-Set-Native-Method-Prefix</code></dt>
	<dd>
	Boolean (<code>true</code> or <code>false</code>, case irrelevant).
	Is the ability to set native method prefix needed by this agent.
	Values other than <code>true</code> are considered <code>false</code>.
	This attribute is optional, the default is <code>false</code>.
	</dd>
	</dl>
	</blockquote>

	<p>
	An agent JAR file may have both the <code>Premain-Class</code> and <code>Agent-Class</code>
	attributes present in the manifest. When the agent is started on the command-line using
	the <code>-javaagent</code> option then the <code>Premain-Class</code> attribute
	specifies the name of the agent class and the <code>Agent-Class</code> attribute is
	ignored. Similarly, if the agent is started sometime after the VM has started, then
	the <code>Agent-Class</code> attribute specifies the name of the agent class
	(the value of <code>Premain-Class</code> attribute is ignored).

	<h2>Related Documentation</h2>

	For tool documentation, please see:
	<ul>
	<li><a href="{@docRoot}/../technotes/tools/index.html">JDK Tools and Utilities</a>
	</ul>

	@since JDK1.5
	@revised 1.6

	</body>
	</html>