--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/jdk/src/java.instrument/share/classes/java/lang/instrument/package.html Sun Aug 17 15:54:13 2014 +0100
@@ -0,0 +1,281 @@
+<!--
+ Copyright (c) 2003, 2014, 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>
+An implementation is not required to provide a way to start agents from the
+command-line interface. On implementations that do provide a way to start agents
+from the 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.</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 1.5
+@revised 1.6
+
+</body>
+</html>