jdk-sandbox: jdk/src/java.instrument/share/classes/java/lang/instrument/package.html@ea3137042a61 (annotated)

1935 4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	1	<!--
45004 ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	2	Copyright (c) 2003, 2017, Oracle and/or its affiliates. All rights reserved.
1935 4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	3	DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	4
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	5	This code is free software; you can redistribute it and/or modify it
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	6	under the terms of the GNU General Public License version 2 only, as
5506 202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 1935 diff changeset	7	published by the Free Software Foundation. Oracle designates this
1935 4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	8	particular file as subject to the "Classpath" exception as provided
5506 202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 1935 diff changeset	9	by Oracle in the LICENSE file that accompanied this code.
1935 4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	10
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	11	This code is distributed in the hope that it will be useful, but WITHOUT
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	12	ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	13	FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	14	version 2 for more details (a copy is included in the LICENSE file that
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	15	accompanied this code).
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	16
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	17	You should have received a copy of the GNU General Public License version
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	18	2 along with this work; if not, write to the Free Software Foundation,
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	19	Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	20
5506 202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 1935 diff changeset	21	Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 1935 diff changeset	22	or visit www.oracle.com if you need additional information or have any
202f599c92aa 6943119: Rebrand source copyright notices ohair parents: 1935 diff changeset	23	questions.
1935 4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	24	-->
4010e03f8c1c 6719182: update legal notice in java/lang/instrument/package.html darcy parents: 2 diff changeset	25
2 90ce3da70b43 Initial load duke parents: diff changeset	26	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
90ce3da70b43 Initial load duke parents: diff changeset	27	<html>
90ce3da70b43 Initial load duke parents: diff changeset	28	<head>
90ce3da70b43 Initial load duke parents: diff changeset	29	<!--
90ce3da70b43 Initial load duke parents: diff changeset	30
90ce3da70b43 Initial load duke parents: diff changeset	31	Copyright 2003 Wily Technology, Inc.
90ce3da70b43 Initial load duke parents: diff changeset	32
90ce3da70b43 Initial load duke parents: diff changeset	33	-->
90ce3da70b43 Initial load duke parents: diff changeset	34	</head>
90ce3da70b43 Initial load duke parents: diff changeset	35
90ce3da70b43 Initial load duke parents: diff changeset	36	<body bgcolor="white">
90ce3da70b43 Initial load duke parents: diff changeset	37
90ce3da70b43 Initial load duke parents: diff changeset	38	Provides services that allow Java programming language agents to instrument programs running on the JVM.
90ce3da70b43 Initial load duke parents: diff changeset	39	The mechanism for instrumentation is modification of the byte-codes of methods.
90ce3da70b43 Initial load duke parents: diff changeset	40
90ce3da70b43 Initial load duke parents: diff changeset	41	<h2>Package Specification</h2>
90ce3da70b43 Initial load duke parents: diff changeset	42
90ce3da70b43 Initial load duke parents: diff changeset	43	<P>
90ce3da70b43 Initial load duke parents: diff changeset	44	An agent is deployed as a JAR file. An attribute in the JAR file manifest specifies the
90ce3da70b43 Initial load duke parents: diff changeset	45	agent class which will be loaded to start the agent. For implementations that support a command-line
90ce3da70b43 Initial load duke parents: diff changeset	46	interface, an agent is started by specifying an option on the command-line.
90ce3da70b43 Initial load duke parents: diff changeset	47	Implementations may also support a mechanism to start agents some time after the VM has
90ce3da70b43 Initial load duke parents: diff changeset	48	started. For example, an implementation may provide a mechanism that allows a tool to
90ce3da70b43 Initial load duke parents: diff changeset	49	<i>attach</i> to a running application, and initiate the loading of the tool's agent into
90ce3da70b43 Initial load duke parents: diff changeset	50	the running application. The details as to how the load is initiated, is implementation
90ce3da70b43 Initial load duke parents: diff changeset	51	dependent.
90ce3da70b43 Initial load duke parents: diff changeset	52
90ce3da70b43 Initial load duke parents: diff changeset	53	<h3>Command-Line Interface</h3>
90ce3da70b43 Initial load duke parents: diff changeset	54
90ce3da70b43 Initial load duke parents: diff changeset	55	<P>
15306 4d1877e73daa 8006565: java.lang.instrument specification should make it clear that -javaagent is optional alanb parents: 5506 diff changeset	56	An implementation is not required to provide a way to start agents from the
4d1877e73daa 8006565: java.lang.instrument specification should make it clear that -javaagent is optional alanb parents: 5506 diff changeset	57	command-line interface. On implementations that do provide a way to start agents
4d1877e73daa 8006565: java.lang.instrument specification should make it clear that -javaagent is optional alanb parents: 5506 diff changeset	58	from the command-line interface, an agent is started by adding this option to
4d1877e73daa 8006565: java.lang.instrument specification should make it clear that -javaagent is optional alanb parents: 5506 diff changeset	59	the command-line:
2 90ce3da70b43 Initial load duke parents: diff changeset	60	<blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	61	<code><b>-javaagent:</b></code><i>jarpath[</i><code><b>=</b></code><i>options]</i>
90ce3da70b43 Initial load duke parents: diff changeset	62	</blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	63	<i>jarpath</i> is the path to the agent JAR file.
90ce3da70b43 Initial load duke parents: diff changeset	64	<i>options</i> is the agent options.
90ce3da70b43 Initial load duke parents: diff changeset	65	This switch may be used multiple times on the same command-line,
90ce3da70b43 Initial load duke parents: diff changeset	66	thus creating multiple agents.
90ce3da70b43 Initial load duke parents: diff changeset	67	More than one agent may use the same <i>jarpath</i>.
90ce3da70b43 Initial load duke parents: diff changeset	68	An agent JAR file must conform to the JAR file specification.
90ce3da70b43 Initial load duke parents: diff changeset	69
90ce3da70b43 Initial load duke parents: diff changeset	70	<P>
90ce3da70b43 Initial load duke parents: diff changeset	71	The manifest of the agent JAR file must contain the attribute <code>Premain-Class</code>. The
90ce3da70b43 Initial load duke parents: diff changeset	72	value of this attribute is the name of the <i>agent class</i>. The agent class must implement a
90ce3da70b43 Initial load duke parents: diff changeset	73	public static <code>premain</code> method similar in principle to the <code>main</code> application
90ce3da70b43 Initial load duke parents: diff changeset	74	entry point. After the Java Virtual Machine (JVM) has initialized, each <code>premain</code> method
90ce3da70b43 Initial load duke parents: diff changeset	75	will be called in the order the agents were specified, then the real application
90ce3da70b43 Initial load duke parents: diff changeset	76	<code>main</code> method will be called.
90ce3da70b43 Initial load duke parents: diff changeset	77	Each <code>premain</code> method must return in order for the startup sequence to proceed.
90ce3da70b43 Initial load duke parents: diff changeset	78
90ce3da70b43 Initial load duke parents: diff changeset	79	<P>
90ce3da70b43 Initial load duke parents: diff changeset	80	The <code>premain</code> method has one of two possible signatures. The JVM first attempts to
90ce3da70b43 Initial load duke parents: diff changeset	81	invoke the following method on the agent class:
90ce3da70b43 Initial load duke parents: diff changeset	82
90ce3da70b43 Initial load duke parents: diff changeset	83	<blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	84	<code>public static void
90ce3da70b43 Initial load duke parents: diff changeset	85	premain(String agentArgs, Instrumentation inst);
90ce3da70b43 Initial load duke parents: diff changeset	86	</code>
90ce3da70b43 Initial load duke parents: diff changeset	87	</blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	88
90ce3da70b43 Initial load duke parents: diff changeset	89	<P>
90ce3da70b43 Initial load duke parents: diff changeset	90	If the agent class does not implement this method then the JVM will attempt to invoke:
90ce3da70b43 Initial load duke parents: diff changeset	91
90ce3da70b43 Initial load duke parents: diff changeset	92	<blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	93	<code>public static void
90ce3da70b43 Initial load duke parents: diff changeset	94	premain(String agentArgs);
90ce3da70b43 Initial load duke parents: diff changeset	95	</code>
90ce3da70b43 Initial load duke parents: diff changeset	96	</blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	97
90ce3da70b43 Initial load duke parents: diff changeset	98	<P>
90ce3da70b43 Initial load duke parents: diff changeset	99	The agent class may also have an <code>agentmain</code> method for use when the agent is started
90ce3da70b43 Initial load duke parents: diff changeset	100	after VM startup. When the agent is started using a command-line option, the <code>agentmain</code>
90ce3da70b43 Initial load duke parents: diff changeset	101	method is not invoked.
90ce3da70b43 Initial load duke parents: diff changeset	102
90ce3da70b43 Initial load duke parents: diff changeset	103
90ce3da70b43 Initial load duke parents: diff changeset	104	<P>
90ce3da70b43 Initial load duke parents: diff changeset	105	The agent class will be loaded by the system class loader
90ce3da70b43 Initial load duke parents: diff changeset	106	(see {@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}). This is
90ce3da70b43 Initial load duke parents: diff changeset	107	the class loader which typically loads the class containing the application <code>main</code> method.
40818 9c2079cba606 8160950: Agent JAR added to app class loader rather than system class loader when running with -Djava.system.class.loader sspitsyn parents: 36511 diff changeset	108	The system class loader must support a mechanism to add an agent JAR file to the system class path.
9c2079cba606 8160950: Agent JAR added to app class loader rather than system class loader when running with -Djava.system.class.loader sspitsyn parents: 36511 diff changeset	109	If it is a custom system class loader then it must define the
9c2079cba606 8160950: Agent JAR added to app class loader rather than system class loader when running with -Djava.system.class.loader sspitsyn parents: 36511 diff changeset	110	<code>appendToClassPathForInstrumentation</code> method as specified in
9c2079cba606 8160950: Agent JAR added to app class loader rather than system class loader when running with -Djava.system.class.loader sspitsyn parents: 36511 diff changeset	111	{@link Instrumentation#appendToSystemClassLoaderSearch appendToSystemClassLoaderSearch}.
2 90ce3da70b43 Initial load duke parents: diff changeset	112	The <code>premain</code> methods will be run under the same security and classloader
90ce3da70b43 Initial load duke parents: diff changeset	113	rules as the application <code>main</code> method.
90ce3da70b43 Initial load duke parents: diff changeset	114	There are no modeling restrictions on what the agent <code>premain</code> method may do.
45004 ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	115	Anything application <code>main</code> can do, including creating threads, is legal from
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	116	<code>premain</code>.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	117
2 90ce3da70b43 Initial load duke parents: diff changeset	118
90ce3da70b43 Initial load duke parents: diff changeset	119	<P>
90ce3da70b43 Initial load duke parents: diff changeset	120	Each agent is passed its agent options via the <code>agentArgs</code> parameter.
90ce3da70b43 Initial load duke parents: diff changeset	121	The agent options are passed as a single string,
90ce3da70b43 Initial load duke parents: diff changeset	122	any additional parsing should be performed by the agent itself.
90ce3da70b43 Initial load duke parents: diff changeset	123
90ce3da70b43 Initial load duke parents: diff changeset	124	<P>
90ce3da70b43 Initial load duke parents: diff changeset	125	If the agent cannot be resolved
90ce3da70b43 Initial load duke parents: diff changeset	126	(for example, because the agent class cannot be loaded,
90ce3da70b43 Initial load duke parents: diff changeset	127	or because the agent class does not have an appropriate <code>premain</code> method), the JVM will abort.
90ce3da70b43 Initial load duke parents: diff changeset	128	If a <code>premain</code> method throws an uncaught exception, the JVM will abort.
90ce3da70b43 Initial load duke parents: diff changeset	129
90ce3da70b43 Initial load duke parents: diff changeset	130
90ce3da70b43 Initial load duke parents: diff changeset	131	<h3>Starting Agents After VM Startup</h3>
90ce3da70b43 Initial load duke parents: diff changeset	132
90ce3da70b43 Initial load duke parents: diff changeset	133	<p>
90ce3da70b43 Initial load duke parents: diff changeset	134	An implementation may provide a mechanism to start agents sometime after the
90ce3da70b43 Initial load duke parents: diff changeset	135	the VM has started. The details as to how this is initiated are implementation
90ce3da70b43 Initial load duke parents: diff changeset	136	specific but typically the application has already started and its <code>
90ce3da70b43 Initial load duke parents: diff changeset	137	main</code> method has already been invoked. In cases where an implementation
90ce3da70b43 Initial load duke parents: diff changeset	138	supports the starting of agents after the VM has started the following applies:
90ce3da70b43 Initial load duke parents: diff changeset	139
90ce3da70b43 Initial load duke parents: diff changeset	140	<ol>
90ce3da70b43 Initial load duke parents: diff changeset	141	<li><p>The manifest of the agent JAR must contain the attribute <code>Agent-Class</code>.
90ce3da70b43 Initial load duke parents: diff changeset	142	The value of this attribute is the name of the <i>agent class</i>. </p></li>
90ce3da70b43 Initial load duke parents: diff changeset	143
90ce3da70b43 Initial load duke parents: diff changeset	144	<li><p>The agent class must implement a public static <code>agentmain</code> method. </p></li>
90ce3da70b43 Initial load duke parents: diff changeset	145
90ce3da70b43 Initial load duke parents: diff changeset	146	<li><p>The system class loader (
90ce3da70b43 Initial load duke parents: diff changeset	147	{@link java.lang.ClassLoader#getSystemClassLoader ClassLoader.getSystemClassLoader}) must
40818 9c2079cba606 8160950: Agent JAR added to app class loader rather than system class loader when running with -Djava.system.class.loader sspitsyn parents: 36511 diff changeset	148	support a mechanism to add an agent JAR file to the system class path.
9c2079cba606 8160950: Agent JAR added to app class loader rather than system class loader when running with -Djava.system.class.loader sspitsyn parents: 36511 diff changeset	149	If it is a custom system class loader then it must define the
9c2079cba606 8160950: Agent JAR added to app class loader rather than system class loader when running with -Djava.system.class.loader sspitsyn parents: 36511 diff changeset	150	<code>appendToClassPathForInstrumentation</code> method as specified in
9c2079cba606 8160950: Agent JAR added to app class loader rather than system class loader when running with -Djava.system.class.loader sspitsyn parents: 36511 diff changeset	151	{@link Instrumentation#appendToSystemClassLoaderSearch appendToSystemClassLoaderSearch}.</li>
2 90ce3da70b43 Initial load duke parents: diff changeset	152	</ol>
90ce3da70b43 Initial load duke parents: diff changeset	153
90ce3da70b43 Initial load duke parents: diff changeset	154	<P>
90ce3da70b43 Initial load duke parents: diff changeset	155	The agent JAR is appended to the system class path. This is the class loader that typically loads
90ce3da70b43 Initial load duke parents: diff changeset	156	the class containing the application <code>main</code> method. The agent class is loaded and the
90ce3da70b43 Initial load duke parents: diff changeset	157	JVM attempts to invoke the <code>agentmain</code> method. The JVM first attempts to invoke
90ce3da70b43 Initial load duke parents: diff changeset	158	the following method on the agent class:
90ce3da70b43 Initial load duke parents: diff changeset	159
90ce3da70b43 Initial load duke parents: diff changeset	160	<blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	161	<code>public static void
90ce3da70b43 Initial load duke parents: diff changeset	162	agentmain(String agentArgs, Instrumentation inst);
90ce3da70b43 Initial load duke parents: diff changeset	163	</code>
90ce3da70b43 Initial load duke parents: diff changeset	164	</blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	165
90ce3da70b43 Initial load duke parents: diff changeset	166	<P>
90ce3da70b43 Initial load duke parents: diff changeset	167	If the agent class does not implement this method then the JVM will attempt to invoke:
90ce3da70b43 Initial load duke parents: diff changeset	168
90ce3da70b43 Initial load duke parents: diff changeset	169	<blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	170	<code>public static void
90ce3da70b43 Initial load duke parents: diff changeset	171	agentmain(String agentArgs);
90ce3da70b43 Initial load duke parents: diff changeset	172	</code>
90ce3da70b43 Initial load duke parents: diff changeset	173	</blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	174
90ce3da70b43 Initial load duke parents: diff changeset	175	<P>
90ce3da70b43 Initial load duke parents: diff changeset	176	The agent class may also have an <code>premain</code> method for use when the agent is started
90ce3da70b43 Initial load duke parents: diff changeset	177	using a command-line option. When the agent is started after VM startup the <code>premain</code>
90ce3da70b43 Initial load duke parents: diff changeset	178	method is not invoked.
90ce3da70b43 Initial load duke parents: diff changeset	179
90ce3da70b43 Initial load duke parents: diff changeset	180
90ce3da70b43 Initial load duke parents: diff changeset	181	<P>
90ce3da70b43 Initial load duke parents: diff changeset	182	The agent is passed its agent options via the <code>agentArgs</code> parameter.
90ce3da70b43 Initial load duke parents: diff changeset	183	The agent options are passed as a single string,
90ce3da70b43 Initial load duke parents: diff changeset	184	any additional parsing should be performed by the agent itself.
90ce3da70b43 Initial load duke parents: diff changeset	185
90ce3da70b43 Initial load duke parents: diff changeset	186	<P>
90ce3da70b43 Initial load duke parents: diff changeset	187	The <code>agentmain</code> method should do any necessary initialization
90ce3da70b43 Initial load duke parents: diff changeset	188	required to start the agent. When startup is complete the method should
90ce3da70b43 Initial load duke parents: diff changeset	189	return. If the agent cannot be started
90ce3da70b43 Initial load duke parents: diff changeset	190	(for example, because the agent class cannot be loaded,
90ce3da70b43 Initial load duke parents: diff changeset	191	or because the agent class does not have a conformant <code>agentmain</code> method), the JVM will
90ce3da70b43 Initial load duke parents: diff changeset	192	not abort. If the <code>agentmain</code> method throws an uncaught exception it will be ignored.
90ce3da70b43 Initial load duke parents: diff changeset	193
90ce3da70b43 Initial load duke parents: diff changeset	194
45004 ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	195	<h3>Deploying Agents in Executable JAR file</h3>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	196
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	197	The JAR File Specification defines manifest attributes for standalone applications that are
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	198	bundled as <em>executable JAR files</em>. If an implementation supports a mechanism to start
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	199	an application as an executable JAR then the main manifest may include the
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	200	<code>Launcher-Agent-Class</code> attribute to specify the class name
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	201	of an agent to start before the application <code>main</code> method is invoked. The Java
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	202	virtual machine attempts to invoke the following method on the agent class:
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	203
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	204	<blockquote>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	205	<code>public static void
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	206	agentmain(String agentArgs, Instrumentation inst);
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	207	</code>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	208	</blockquote>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	209
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	210	<P>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	211	If the agent class does not implement this method then the JVM will attempt to invoke:
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	212
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	213	<blockquote>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	214	<code>public static void
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	215	agentmain(String agentArgs);
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	216	</code>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	217	</blockquote>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	218
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	219	<p>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	220	The value of the <code>agentArgs</code> parameter is always the empty string.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	221
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	222	<P>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	223	The <code>agentmain</code> method should do any necessary initialization
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	224	required to start the agent and return. If the agent cannot be started, for
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	225	example the agent class cannot be loaded, the agent class does not define a
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	226	conformant <code>agentmain</code> method, or the <code>agentmain</code> method
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	227	throws an uncaught exception or error, the JVM will abort.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	228
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	229
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	230	<h3>Visibility</h3>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	231
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	232	The types visible to the agent class are the types visible to the system class
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	233	loader. They minimally include the types in packages exported by
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	234	<a href="{@docRoot}/java.base-summary.html">java.base</a> and
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	235	<a href="{@docRoot}/java.instrument-summary.html">java.instrument</a>.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	236	Whether all {@linkplain ClassLoader#getPlatformClassLoader() platform classes}
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	237	are visible or not will depend on the initial module or application.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	238
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	239	<p>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	240	Supporting classes that the agent makes visible to the bootstrap class loader
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	241	(by means of {@link Instrumentation#appendToBootstrapClassLoaderSearch
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	242	appendToBootstrapClassLoaderSearch} or the <code>Boot-Class-Path</code> attribute
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	243	specified below) can only link to types defined to the bootstrap class loader.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	244	There is no guarantee that all platform classes are visible to the boot class
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	245	loader.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	246
2 90ce3da70b43 Initial load duke parents: diff changeset	247
90ce3da70b43 Initial load duke parents: diff changeset	248	<h3>Manifest Attributes</h3>
45004 ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	249
2 90ce3da70b43 Initial load duke parents: diff changeset	250	The following manifest attributes are defined for an agent JAR file:
90ce3da70b43 Initial load duke parents: diff changeset	251	<blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	252	<dl>
90ce3da70b43 Initial load duke parents: diff changeset	253	<dt><code>Premain-Class</code></dt>
90ce3da70b43 Initial load duke parents: diff changeset	254	<dd>
45004 ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	255	When an agent is specified at JVM launch time this attribute
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	256	specifies the agent class.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	257	That is, the class containing the <code>premain</code> method.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	258	When an agent is specified at JVM launch time this attribute
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	259	is required. If the attribute is not present the JVM will abort.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	260	Note: this is a class name, not a file name or path.
2 90ce3da70b43 Initial load duke parents: diff changeset	261	</dd>
90ce3da70b43 Initial load duke parents: diff changeset	262	<dt><code>Agent-Class</code></dt>
90ce3da70b43 Initial load duke parents: diff changeset	263	<dd>
45004 ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	264	If an implementation supports a mechanism to start agents
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	265	sometime after the VM has started then this attribute specifies
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	266	the agent class.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	267	That is, the class containing the <code>agentmain</code> method.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	268	This attribute is required, if it is not present the agent
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	269	will not be started.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	270	Note: this is a class name, not a file name or path.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	271	</dd>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	272	<dt><code>Launcher-Agent-Class</code></dt>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	273	<dd>
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	274	If an implementation supports a mechanism to start an application
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	275	as an executable JAR then the main manifest may include this
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	276	attribute to specify the class name of an agent to start before the
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	277	application <code>main</code> method is invoked.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	278	</dd>
2 90ce3da70b43 Initial load duke parents: diff changeset	279	<dt><code>Boot-Class-Path</code></dt>
90ce3da70b43 Initial load duke parents: diff changeset	280	<dd>
45004 ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	281	A list of paths to be searched by the bootstrap class
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	282	loader. Paths represent directories or libraries
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	283	(commonly referred to as JAR or zip libraries on
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	284	many platforms).
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	285	These paths are searched by the
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	286	bootstrap class loader after the platform specific
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	287	mechanisms of locating a class have failed.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	288	Paths are searched in the order listed.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	289	Paths in the list are separated by one or more spaces.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	290	A path takes the syntax of the path component of a
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	291	hierarchical URI. The path is
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	292	absolute if it begins with a slash character ('/'),
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	293	otherwise it is relative. A relative path is resolved
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	294	against the absolute path of the agent JAR file.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	295	Malformed and non-existent paths are ignored.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	296	When an agent is started sometime after the VM has
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	297	started then paths that do not represent a JAR file
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	298	are ignored.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	299	This attribute is optional.
2 90ce3da70b43 Initial load duke parents: diff changeset	300	</dd>
90ce3da70b43 Initial load duke parents: diff changeset	301	<dt><code>Can-Redefine-Classes</code></dt>
90ce3da70b43 Initial load duke parents: diff changeset	302	<dd>
45004 ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	303	Boolean (<code>true</code> or <code>false</code>, case irrelevant).
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	304	Is the ability to redefine classes
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	305	needed by this agent.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	306	Values other than <code>true</code> are considered <code>false</code>.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	307	This attribute is optional, the default is <code>false</code>.
2 90ce3da70b43 Initial load duke parents: diff changeset	308	</dd>
90ce3da70b43 Initial load duke parents: diff changeset	309	<dt><code>Can-Retransform-Classes</code></dt>
90ce3da70b43 Initial load duke parents: diff changeset	310	<dd>
45004 ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	311	Boolean (<code>true</code> or <code>false</code>, case irrelevant).
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	312	Is the ability to retransform classes
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	313	needed by this agent.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	314	Values other than <code>true</code> are considered <code>false</code>.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	315	This attribute is optional, the default is <code>false</code>.
2 90ce3da70b43 Initial load duke parents: diff changeset	316	</dd>
90ce3da70b43 Initial load duke parents: diff changeset	317	<dt><code>Can-Set-Native-Method-Prefix</code></dt>
90ce3da70b43 Initial load duke parents: diff changeset	318	<dd>
45004 ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	319	Boolean (<code>true</code> or <code>false</code>, case irrelevant).
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	320	Is the ability to set native method prefix needed by this agent.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	321	Values other than <code>true</code> are considered <code>false</code>.
ea3137042a61 8178380: Module system implementation refresh (5/2017) alanb parents: 42338 diff changeset	322	This attribute is optional, the default is <code>false</code>.
2 90ce3da70b43 Initial load duke parents: diff changeset	323	</dd>
90ce3da70b43 Initial load duke parents: diff changeset	324	</dl>
90ce3da70b43 Initial load duke parents: diff changeset	325	</blockquote>
90ce3da70b43 Initial load duke parents: diff changeset	326
90ce3da70b43 Initial load duke parents: diff changeset	327	<p>
90ce3da70b43 Initial load duke parents: diff changeset	328	An agent JAR file may have both the <code>Premain-Class</code> and <code>Agent-Class</code>
90ce3da70b43 Initial load duke parents: diff changeset	329	attributes present in the manifest. When the agent is started on the command-line using
90ce3da70b43 Initial load duke parents: diff changeset	330	the <code>-javaagent</code> option then the <code>Premain-Class</code> attribute
90ce3da70b43 Initial load duke parents: diff changeset	331	specifies the name of the agent class and the <code>Agent-Class</code> attribute is
90ce3da70b43 Initial load duke parents: diff changeset	332	ignored. Similarly, if the agent is started sometime after the VM has started, then
90ce3da70b43 Initial load duke parents: diff changeset	333	the <code>Agent-Class</code> attribute specifies the name of the agent class
90ce3da70b43 Initial load duke parents: diff changeset	334	(the value of <code>Premain-Class</code> attribute is ignored).
90ce3da70b43 Initial load duke parents: diff changeset	335
36511 9d0388c6b336 8142968: Module System implementation alanb parents: 25859 diff changeset	336
9d0388c6b336 8142968: Module System implementation alanb parents: 25859 diff changeset	337	<h3>Instrumenting code in modules</h3>
9d0388c6b336 8142968: Module System implementation alanb parents: 25859 diff changeset	338
9d0388c6b336 8142968: Module System implementation alanb parents: 25859 diff changeset	339	As an aid to agents that deploy supporting classes on the search path of the
9d0388c6b336 8142968: Module System implementation alanb parents: 25859 diff changeset	340	bootstrap class loader, or the search path of the class loader that loads
9d0388c6b336 8142968: Module System implementation alanb parents: 25859 diff changeset	341	the main agent class, the Java virtual machine arranges for the module of
9d0388c6b336 8142968: Module System implementation alanb parents: 25859 diff changeset	342	transformed classes to read the unnamed module of both class loaders.
9d0388c6b336 8142968: Module System implementation alanb parents: 25859 diff changeset	343
9d0388c6b336 8142968: Module System implementation alanb parents: 25859 diff changeset	344
2 90ce3da70b43 Initial load duke parents: diff changeset	345	<h2>Related Documentation</h2>
90ce3da70b43 Initial load duke parents: diff changeset	346
90ce3da70b43 Initial load duke parents: diff changeset	347	For tool documentation, please see:
90ce3da70b43 Initial load duke parents: diff changeset	348	<ul>
90ce3da70b43 Initial load duke parents: diff changeset	349	<li><a href="{@docRoot}/../technotes/tools/index.html">JDK Tools and Utilities</a>
90ce3da70b43 Initial load duke parents: diff changeset	350	</ul>
90ce3da70b43 Initial load duke parents: diff changeset	351
24865 09b1d992ca72 8044740: Convert all JDK versions used in @since tag to 1.n[.n] in jdk repo henryjen parents: 24367 diff changeset	352	@since 1.5
2 90ce3da70b43 Initial load duke parents: diff changeset	353	@revised 1.6
90ce3da70b43 Initial load duke parents: diff changeset	354
90ce3da70b43 Initial load duke parents: diff changeset	355	</body>
90ce3da70b43 Initial load duke parents: diff changeset	356	</html>

author	alanb
	Thu, 04 May 2017 07:26:55 +0000
changeset 45004	ea3137042a61
parent 42338	a60f280f803c
permissions	-rw-r--r--