8178380: Module system implementation refresh (5/2017)
Reviewed-by: mchung, alanb, sspitsyn
Contributed-by: alan.bateman@oracle.com, mandy.chung@oracle.com, chris.hegarty@oracle.com
<!--
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>