--- a/jdk/src/java.instrument/share/classes/java/lang/instrument/package.html Mon Jul 03 12:58:30 2017 +0530
+++ /dev/null Thu Jan 01 00:00:00 1970 +0000
@@ -1,356 +0,0 @@
-<!--
- Copyright (c) 2003, 2017, 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 system class loader must support a mechanism to add an agent JAR file to the system class path.
-If it is a custom system class loader then it must define the
-<code>appendToClassPathForInstrumentation</code> method as specified in
-{@link Instrumentation#appendToSystemClassLoaderSearch appendToSystemClassLoaderSearch}.
-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.
- If it is a custom system class loader then it must define the
- <code>appendToClassPathForInstrumentation</code> method as specified in
- {@link Instrumentation#appendToSystemClassLoaderSearch appendToSystemClassLoaderSearch}.</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>Deploying Agents in Executable JAR file</h3>
-
-The JAR File Specification defines manifest attributes for standalone applications that are
-bundled as <em>executable JAR files</em>. If an implementation supports a mechanism to start
-an application as an executable JAR then the main manifest may include the
-<code>Launcher-Agent-Class</code> attribute to specify the class name
-of an agent to start before the application <code>main</code> method is invoked. The Java
-virtual machine 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 value of the <code>agentArgs</code> parameter is always the empty string.
-
-<P>
-The <code>agentmain</code> method should do any necessary initialization
-required to start the agent and return. If the agent cannot be started, for
-example the agent class cannot be loaded, the agent class does not define a
-conformant <code>agentmain</code> method, or the <code>agentmain</code> method
-throws an uncaught exception or error, the JVM will abort.
-
-
-<h3>Visibility</h3>
-
-The types visible to the agent class are the types visible to the system class
-loader. They minimally include the types in packages exported by
-<a href="{@docRoot}/java.base-summary.html">java.base</a> and
-<a href="{@docRoot}/java.instrument-summary.html">java.instrument</a>.
-Whether all {@linkplain ClassLoader#getPlatformClassLoader() platform classes}
-are visible or not will depend on the initial module or application.
-
-<p>
-Supporting classes that the agent makes visible to the bootstrap class loader
-(by means of {@link Instrumentation#appendToBootstrapClassLoaderSearch
-appendToBootstrapClassLoaderSearch} or the <code>Boot-Class-Path</code> attribute
-specified below) can only link to types defined to the bootstrap class loader.
-There is no guarantee that all platform classes are visible to the boot class
-loader.
-
-
-<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>Launcher-Agent-Class</code></dt>
-<dd>
- If an implementation supports a mechanism to start an application
- as an executable JAR then the main manifest may include this
- attribute to specify the class name of an agent to start before the
- application <code>main</code> method is invoked.
-</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).
-
-
-<h3>Instrumenting code in modules</h3>
-
-As an aid to agents that deploy supporting classes on the search path of the
-bootstrap class loader, or the search path of the class loader that loads
-the main agent class, the Java virtual machine arranges for the module of
-transformed classes to read the unnamed module of both class loaders.
-
-
-<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>