changeset 19563:32367b88f515

Update java.lang.instrument to document Launcher-Agent-Class and link to JAR spec
author alanb
date Tue, 25 Apr 2017 15:22:19 +0100
parents 12dd6436acea
children adada70846e8
files src/java.instrument/share/classes/java/lang/instrument/package.html
diffstat 1 files changed, 44 insertions(+), 3 deletions(-) [+]
line wrap: on
line diff
--- a/src/java.instrument/share/classes/java/lang/instrument/package.html	Mon Apr 24 20:05:14 2017 +0100
+++ b/src/java.instrument/share/classes/java/lang/instrument/package.html	Tue Apr 25 15:22:19 2017 +0100
@@ -117,6 +117,12 @@
 
 
 <P>
+The types visible to the agent class will be determined by the application and will
+minimally include the types in the <a href="{@docRoot}/java.base-summary.html">java.base</a>
+and <a href="{@docRoot}/java.instrument-summary.html">java.instrument</a> modules, and other
+types visible via the application class loader.
+
+<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.
@@ -128,7 +134,6 @@
 If a <code>premain</code> method throws an uncaught exception, the JVM will abort.
 
 
-
 <h3>Starting Agents After VM Startup</h3>
 
 <p>
@@ -193,6 +198,33 @@
 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.
+
 
 <h3>Manifest Attributes</h3>
 The following manifest attributes are defined for an agent JAR file:
@@ -217,9 +249,18 @@
             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>			
+</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 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.
+</dd>
 
-<dt><code>Boot-Class-Path</code></dt>
+    <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