1 <!DOCTYPE HTML>
2 <!-- NewPage -->
3 <html lang="en">
4 <head>
5 <!-- Generated by javadoc -->
6 <title>Instrumentation (Java SE 14 & JDK 14 [ad-hoc build])</title>
7 <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
8 <meta name="description" content="declaration: module: java.instrument, package: java.lang.instrument, interface: Instrumentation">
9 <meta name="generator" content="javadoc/ClassWriterImpl">
10 <meta name="keywords" content="java.lang.instrument.Instrumentation interface">
11 <meta name="keywords" content="addTransformer()">
12 <meta name="keywords" content="removeTransformer()">
13 <meta name="keywords" content="isRetransformClassesSupported()">
14 <meta name="keywords" content="retransformClasses()">
15 <meta name="keywords" content="isRedefineClassesSupported()">
16 <meta name="keywords" content="redefineClasses()">
17 <meta name="keywords" content="isModifiableClass()">
18 <meta name="keywords" content="getAllLoadedClasses()">
19 <meta name="keywords" content="getInitiatedClasses()">
20 <meta name="keywords" content="getObjectSize()">
21 <meta name="keywords" content="appendToBootstrapClassLoaderSearch()">
22 <meta name="keywords" content="appendToSystemClassLoaderSearch()">
23 <meta name="keywords" content="isNativeMethodPrefixSupported()">
24 <meta name="keywords" content="setNativeMethodPrefix()">
25 <meta name="keywords" content="redefineModule()">
26 <meta name="keywords" content="isModifiableModule()">
27 <link rel="stylesheet" type="text/css" href="../../../../stylesheet.css" title="Style">
28 <link rel="stylesheet" type="text/css" href="../../../../script-dir/jquery-ui.css" title="Style">
29 <script type="text/javascript" src="../../../../script.js"></script>
30 <script type="text/javascript" src="../../../../script-dir/jszip/dist/jszip.min.js"></script>
31 <script type="text/javascript" src="../../../../script-dir/jszip-utils/dist/jszip-utils.min.js"></script>
32 <!--[if IE]>
33 <script type="text/javascript" src="../../../../script-dir/jszip-utils/dist/jszip-utils-ie.min.js"></script>
34 <![endif]-->
35 <script type="text/javascript" src="../../../../script-dir/jquery-3.4.1.js"></script>
36 <script type="text/javascript" src="../../../../script-dir/jquery-ui.js"></script>
37 </head>
38 <body class="class-declaration">
39 <script type="text/javascript">var data = {"i0":6,"i1":6,"i2":6,"i3":6,"i4":6,"i5":6,"i6":6,"i7":6,"i8":6,"i9":6,"i10":6,"i11":6,"i12":6,"i13":6,"i14":6,"i15":6,"i16":6};
40 var tabs = {65535:["t0","All Methods"],2:["t2","Instance Methods"],4:["t3","Abstract Methods"]};
41 var altColor = "altColor";
42 var rowColor = "rowColor";
43 var tableTab = "tableTab";
44 var activeTableTab = "activeTableTab";
45 var pathtoroot = "../../../../";
46 loadScripts(document, 'script');</script>
47 <noscript>
48 <div>JavaScript is disabled on your browser.</div>
49 </noscript>
50 <div class="flexBox">
51 <header role="banner" class="flexHeader"><div style="padding: 6px; text-align: center; font-size: 80%; font-family: DejaVu Sans, Arial, Helvetica, sans-serif; font-weight: normal;">This specification is not final and is subject to change. Use is subject to <a href="https://www.oracle.com/technetwork/java/javase/terms/license/java14speclicense.html">license terms</a>.</div>
52 <nav role="navigation">
53 <!-- ========= START OF TOP NAVBAR ======= -->
54 <div class="topNav"><a id="navbar.top">
55 <!-- -->
56 </a>
57 <div class="skipNav"><a href="#skip.navbar.top" title="Skip navigation links">Skip navigation links</a></div>
58 <a id="navbar.top.firstrow">
59 <!-- -->
60 </a>
61 <ul class="navList" title="Navigation">
62 <li><a href="../../../../index.html">Overview</a></li>
63 <li><a href="../../../module-summary.html">Module</a></li>
64 <li><a href="package-summary.html">Package</a></li>
65 <li class="navBarCell1Rev">Class</li>
66 <li><a href="class-use/Instrumentation.html">Use</a></li>
67 <li><a href="package-tree.html">Tree</a></li>
68 <li><a href="../../../../deprecated-list.html">Deprecated</a></li>
69 <li><a href="../../../../index-files/index-1.html">Index</a></li>
70 <li><a href="../../../../help-doc.html">Help</a></li>
71 </ul>
72 <div class="aboutLanguage"><div style="margin-top: 9px;"><strong>Java SE 14 & JDK 14</strong> <br><strong>DRAFT 14-internal+0-2019-12-04-2218569.hseigel.bug8235360</strong></div></div>
73 </div>
74 <div class="subNav">
75 <div>
76 <ul class="subNavList">
77 <li>Summary: </li>
78 <li>Nested | </li>
79 <li>Field | </li>
80 <li>Constr | </li>
81 <li><a href="#method.summary">Method</a></li>
82 </ul>
83 <ul class="subNavList">
84 <li>Detail: </li>
85 <li>Field | </li>
86 <li>Constr | </li>
87 <li><a href="#method.detail">Method</a></li>
88 </ul>
89 </div>
90 <div class="navListSearch"><label for="search">SEARCH:</label>
91 <input type="text" id="search" value="search" disabled="disabled">
92 <input type="reset" id="reset" value="reset" disabled="disabled">
93 </div>
94 </div>
95 <!-- ========= END OF TOP NAVBAR ========= -->
96 <div class="skipNav"><a id="skip.navbar.top">
97 <!-- -->
98 </a></div>
99 </nav>
100 </header>
101 <div class="flexContent">
102 <main role="main">
103 <!-- ======== START OF CLASS DATA ======== -->
104 <div class="header">
105 <div class="subTitle"><span class="moduleLabelInType">Module</span> <a href="../../../module-summary.html">java.instrument</a></div>
106 <div class="subTitle"><span class="packageLabelInType">Package</span> <a href="package-summary.html">java.lang.instrument</a></div>
107 <h1 title="Interface Instrumentation" class="title">Interface Instrumentation</h1>
108 </div>
109 <div class="contentContainer">
110 <section class="description">
111 <hr>
112 <pre>public interface <span class="typeNameLabel">Instrumentation</span></pre>
113 <div class="block">This class provides services needed to instrument Java
114 programming language code.
115 Instrumentation is the addition of byte-codes to methods for the
116 purpose of gathering data to be utilized by tools.
117 Since the changes are purely additive, these tools do not modify
118 application state or behavior.
119 Examples of such benign tools include monitoring agents, profilers,
120 coverage analyzers, and event loggers.
121
122 <P>
123 There are two ways to obtain an instance of the
124 <code>Instrumentation</code> interface:
125
126 <ol>
127 <li><p> When a JVM is launched in a way that indicates an agent
128 class. In that case an <code>Instrumentation</code> instance
129 is passed to the <code>premain</code> method of the agent class.
130 </p></li>
131 <li><p> When a JVM provides a mechanism to start agents sometime
132 after the JVM is launched. In that case an <code>Instrumentation</code>
133 instance is passed to the <code>agentmain</code> method of the
134 agent code. </p> </li>
135 </ol>
136 <p>
137 These mechanisms are described in the
138 <a href="package-summary.html">package specification</a>.
139 <p>
140 Once an agent acquires an <code>Instrumentation</code> instance,
141 the agent may call methods on the instance at any time.</div>
142 <dl>
143 <dt><span class="simpleTagLabel">API Note:</span></dt>
144 <dd>This interface is not intended to be implemented outside of
145 the java.instrument module.</dd>
146 <dt><span class="simpleTagLabel">Since:</span></dt>
147 <dd>1.5</dd>
148 </dl>
149 </section>
150 <section class="summary">
151 <ul class="blockList">
152 <!-- ========== METHOD SUMMARY =========== -->
153 <li class="blockList">
154 <section class="methodSummary"><a id="method.summary">
155 <!-- -->
156 </a>
157 <h2>Method Summary</h2>
158 <div class="memberSummary">
159 <div role="tablist" aria-orientation="horizontal"><button role="tab" aria-selected="true" aria-controls="memberSummary_tabpanel" tabindex="0" onkeydown="switchTab(event)" id="t0" class="activeTableTab">All Methods</button><button role="tab" aria-selected="false" aria-controls="memberSummary_tabpanel" tabindex="-1" onkeydown="switchTab(event)" id="t2" class="tableTab" onclick="show(2);">Instance Methods</button><button role="tab" aria-selected="false" aria-controls="memberSummary_tabpanel" tabindex="-1" onkeydown="switchTab(event)" id="t3" class="tableTab" onclick="show(4);">Abstract Methods</button></div>
160 <div id="memberSummary_tabpanel" role="tabpanel">
161 <table aria-labelledby="t0">
162 <thead>
163 <tr>
164 <th class="colFirst" scope="col">Modifier and Type</th>
165 <th class="colSecond" scope="col">Method</th>
166 <th class="colLast" scope="col">Description</th>
167 </tr>
168 </thead>
169 <tbody>
170 <tr class="altColor" id="i0">
171 <td class="colFirst"><code>void</code></td>
172 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#addTransformer(java.lang.instrument.ClassFileTransformer)">addTransformer</a></span>(<a href="ClassFileTransformer.html" title="interface in java.lang.instrument">ClassFileTransformer</a> transformer)</code></th>
173 <td class="colLast">
174 <div class="block">Registers the supplied transformer.</div>
175 </td>
176 </tr>
177 <tr class="rowColor" id="i1">
178 <td class="colFirst"><code>void</code></td>
179 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#addTransformer(java.lang.instrument.ClassFileTransformer,boolean)">addTransformer</a></span>(<a href="ClassFileTransformer.html" title="interface in java.lang.instrument">ClassFileTransformer</a> transformer,
180 boolean canRetransform)</code></th>
181 <td class="colLast">
182 <div class="block">Registers the supplied transformer.</div>
183 </td>
184 </tr>
185 <tr class="altColor" id="i2">
186 <td class="colFirst"><code>void</code></td>
187 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#appendToBootstrapClassLoaderSearch(java.util.jar.JarFile)">appendToBootstrapClassLoaderSearch</a></span>(<a href="../../../../java.base/java/util/jar/JarFile.html" title="class in java.util.jar">JarFile</a> jarfile)</code></th>
188 <td class="colLast">
189 <div class="block">Specifies a JAR file with instrumentation classes to be defined by the
190 bootstrap class loader.</div>
191 </td>
192 </tr>
193 <tr class="rowColor" id="i3">
194 <td class="colFirst"><code>void</code></td>
195 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#appendToSystemClassLoaderSearch(java.util.jar.JarFile)">appendToSystemClassLoaderSearch</a></span>(<a href="../../../../java.base/java/util/jar/JarFile.html" title="class in java.util.jar">JarFile</a> jarfile)</code></th>
196 <td class="colLast">
197 <div class="block">Specifies a JAR file with instrumentation classes to be defined by the
198 system class loader.</div>
199 </td>
200 </tr>
201 <tr class="altColor" id="i4">
202 <td class="colFirst"><code><a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a>[]</code></td>
203 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getAllLoadedClasses()">getAllLoadedClasses</a></span>()</code></th>
204 <td class="colLast">
205 <div class="block">Returns an array of all classes currently loaded by the JVM.</div>
206 </td>
207 </tr>
208 <tr class="rowColor" id="i5">
209 <td class="colFirst"><code><a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a>[]</code></td>
210 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getInitiatedClasses(java.lang.ClassLoader)">getInitiatedClasses</a></span>(<a href="../../../../java.base/java/lang/ClassLoader.html" title="class in java.lang">ClassLoader</a> loader)</code></th>
211 <td class="colLast">
212 <div class="block">Returns an array of all classes for which <code>loader</code> is an initiating loader.</div>
213 </td>
214 </tr>
215 <tr class="altColor" id="i6">
216 <td class="colFirst"><code>long</code></td>
217 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#getObjectSize(java.lang.Object)">getObjectSize</a></span>(<a href="../../../../java.base/java/lang/Object.html" title="class in java.lang">Object</a> objectToSize)</code></th>
218 <td class="colLast">
219 <div class="block">Returns an implementation-specific approximation of the amount of storage consumed by
220 the specified object.</div>
221 </td>
222 </tr>
223 <tr class="rowColor" id="i7">
224 <td class="colFirst"><code>boolean</code></td>
225 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#isModifiableClass(java.lang.Class)">isModifiableClass</a></span>(<a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a><?> theClass)</code></th>
226 <td class="colLast">
227 <div class="block">Tests whether a class is modifiable by
228 <a href="#retransformClasses(java.lang.Class...)">retransformation</a>
229 or <a href="#redefineClasses(java.lang.instrument.ClassDefinition...)">redefinition</a>.</div>
230 </td>
231 </tr>
232 <tr class="altColor" id="i8">
233 <td class="colFirst"><code>boolean</code></td>
234 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#isModifiableModule(java.lang.Module)">isModifiableModule</a></span>(<a href="../../../../java.base/java/lang/Module.html" title="class in java.lang">Module</a> module)</code></th>
235 <td class="colLast">
236 <div class="block">Tests whether a module can be modified with <a href="#redefineModule(java.lang.Module,java.util.Set,java.util.Map,java.util.Map,java.util.Set,java.util.Map)"><code>redefineModule</code></a>.</div>
237 </td>
238 </tr>
239 <tr class="rowColor" id="i9">
240 <td class="colFirst"><code>boolean</code></td>
241 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#isNativeMethodPrefixSupported()">isNativeMethodPrefixSupported</a></span>()</code></th>
242 <td class="colLast">
243 <div class="block">Returns whether the current JVM configuration supports
244 <a href="#setNativeMethodPrefix(java.lang.instrument.ClassFileTransformer,java.lang.String)">setting a native method prefix</a>.</div>
245 </td>
246 </tr>
247 <tr class="altColor" id="i10">
248 <td class="colFirst"><code>boolean</code></td>
249 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#isRedefineClassesSupported()">isRedefineClassesSupported</a></span>()</code></th>
250 <td class="colLast">
251 <div class="block">Returns whether or not the current JVM configuration supports redefinition
252 of classes.</div>
253 </td>
254 </tr>
255 <tr class="rowColor" id="i11">
256 <td class="colFirst"><code>boolean</code></td>
257 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#isRetransformClassesSupported()">isRetransformClassesSupported</a></span>()</code></th>
258 <td class="colLast">
259 <div class="block">Returns whether or not the current JVM configuration supports retransformation
260 of classes.</div>
261 </td>
262 </tr>
263 <tr class="altColor" id="i12">
264 <td class="colFirst"><code>void</code></td>
265 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#redefineClasses(java.lang.instrument.ClassDefinition...)">redefineClasses</a></span>(<a href="ClassDefinition.html" title="class in java.lang.instrument">ClassDefinition</a>... definitions)</code></th>
266 <td class="colLast">
267 <div class="block">Redefine the supplied set of classes using the supplied class files.</div>
268 </td>
269 </tr>
270 <tr class="rowColor" id="i13">
271 <td class="colFirst"><code>void</code></td>
272 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#redefineModule(java.lang.Module,java.util.Set,java.util.Map,java.util.Map,java.util.Set,java.util.Map)">redefineModule</a></span>(<a href="../../../../java.base/java/lang/Module.html" title="class in java.lang">Module</a> module,
273 <a href="../../../../java.base/java/util/Set.html" title="interface in java.util">Set</a><<a href="../../../../java.base/java/lang/Module.html" title="class in java.lang">Module</a>> extraReads,
274 <a href="../../../../java.base/java/util/Map.html" title="interface in java.util">Map</a><<a href="../../../../java.base/java/lang/String.html" title="class in java.lang">String</a>,<a href="../../../../java.base/java/util/Set.html" title="interface in java.util">Set</a><<a href="../../../../java.base/java/lang/Module.html" title="class in java.lang">Module</a>>> extraExports,
275 <a href="../../../../java.base/java/util/Map.html" title="interface in java.util">Map</a><<a href="../../../../java.base/java/lang/String.html" title="class in java.lang">String</a>,<a href="../../../../java.base/java/util/Set.html" title="interface in java.util">Set</a><<a href="../../../../java.base/java/lang/Module.html" title="class in java.lang">Module</a>>> extraOpens,
276 <a href="../../../../java.base/java/util/Set.html" title="interface in java.util">Set</a><<a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a><?>> extraUses,
277 <a href="../../../../java.base/java/util/Map.html" title="interface in java.util">Map</a><<a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a><?>,<a href="../../../../java.base/java/util/List.html" title="interface in java.util">List</a><<a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a><?>>> extraProvides)</code></th>
278 <td class="colLast">
279 <div class="block">Redefine a module to expand the set of modules that it reads, the set of
280 packages that it exports or opens, or the services that it uses or
281 provides.</div>
282 </td>
283 </tr>
284 <tr class="altColor" id="i14">
285 <td class="colFirst"><code>boolean</code></td>
286 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#removeTransformer(java.lang.instrument.ClassFileTransformer)">removeTransformer</a></span>(<a href="ClassFileTransformer.html" title="interface in java.lang.instrument">ClassFileTransformer</a> transformer)</code></th>
287 <td class="colLast">
288 <div class="block">Unregisters the supplied transformer.</div>
289 </td>
290 </tr>
291 <tr class="rowColor" id="i15">
292 <td class="colFirst"><code>void</code></td>
293 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#retransformClasses(java.lang.Class...)">retransformClasses</a></span>(<a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a><?>... classes)</code></th>
294 <td class="colLast">
295 <div class="block">Retransform the supplied set of classes.</div>
296 </td>
297 </tr>
298 <tr class="altColor" id="i16">
299 <td class="colFirst"><code>void</code></td>
300 <th class="colSecond" scope="row"><code><span class="memberNameLink"><a href="#setNativeMethodPrefix(java.lang.instrument.ClassFileTransformer,java.lang.String)">setNativeMethodPrefix</a></span>(<a href="ClassFileTransformer.html" title="interface in java.lang.instrument">ClassFileTransformer</a> transformer,
301 <a href="../../../../java.base/java/lang/String.html" title="class in java.lang">String</a> prefix)</code></th>
302 <td class="colLast">
303 <div class="block">This method modifies the failure handling of
304 native method resolution by allowing retry
305 with a prefix applied to the name.</div>
306 </td>
307 </tr>
308 </tbody>
309 </table>
310 </div>
311 </div>
312 </section>
313 </li>
314 </ul>
315 </section>
316 <section class="details">
317 <ul class="blockList">
318 <!-- ============ METHOD DETAIL ========== -->
319 <li class="blockList">
320 <section class="methodDetails"><a id="method.detail">
321 <!-- -->
322 </a>
323 <h2>Method Details</h2>
324 <ul class="blockList">
325 <li class="blockList">
326 <section class="detail">
327 <h3><a id="addTransformer(java.lang.instrument.ClassFileTransformer,boolean)">addTransformer</a></h3>
328 <div class="memberSignature"><span class="returnType">void</span> <span class="memberName">addTransformer</span>(<span class="arguments"><a href="ClassFileTransformer.html" title="interface in java.lang.instrument">ClassFileTransformer</a> transformer,
329 boolean canRetransform)</span></div>
330 <div class="block">Registers the supplied transformer. All future class definitions
331 will be seen by the transformer, except definitions of classes upon which any
332 registered transformer is dependent.
333 The transformer is called when classes are loaded, when they are
334 <a href="#redefineClasses(java.lang.instrument.ClassDefinition...)">redefined</a>. and if <code>canRetransform</code> is true,
335 when they are <a href="#retransformClasses(java.lang.Class...)">retransformed</a>.
336 <a href="ClassFileTransformer.html" title="interface in java.lang.instrument"><code>ClassFileTransformer</code></a> defines the order of transform calls.
337
338 If a transformer throws
339 an exception during execution, the JVM will still call the other registered
340 transformers in order. The same transformer may be added more than once,
341 but it is strongly discouraged -- avoid this by creating a new instance of
342 transformer class.
343 <P>
344 This method is intended for use in instrumentation, as described in the
345 <a href="Instrumentation.html" title="interface in java.lang.instrument">class specification</a>.</div>
346 <dl>
347 <dt><span class="paramLabel">Parameters:</span></dt>
348 <dd><code>transformer</code> - the transformer to register</dd>
349 <dd><code>canRetransform</code> - can this transformer's transformations be retransformed</dd>
350 <dt><span class="throwsLabel">Throws:</span></dt>
351 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - if passed a <code>null</code> transformer</dd>
352 <dd><code><a href="../../../../java.base/java/lang/UnsupportedOperationException.html" title="class in java.lang">UnsupportedOperationException</a></code> - if <code>canRetransform</code>
353 is true and the current configuration of the JVM does not allow
354 retransformation (<a href="#isRetransformClassesSupported()"><code>isRetransformClassesSupported()</code></a> is false)</dd>
355 <dt><span class="simpleTagLabel">Since:</span></dt>
356 <dd>1.6</dd>
357 </dl>
358 </section>
359 </li>
360 <li class="blockList">
361 <section class="detail">
362 <h3><a id="addTransformer(java.lang.instrument.ClassFileTransformer)">addTransformer</a></h3>
363 <div class="memberSignature"><span class="returnType">void</span> <span class="memberName">addTransformer</span>(<span class="arguments"><a href="ClassFileTransformer.html" title="interface in java.lang.instrument">ClassFileTransformer</a> transformer)</span></div>
364 <div class="block">Registers the supplied transformer.
365 <P>
366 Same as <code>addTransformer(transformer, false)</code>.</div>
367 <dl>
368 <dt><span class="paramLabel">Parameters:</span></dt>
369 <dd><code>transformer</code> - the transformer to register</dd>
370 <dt><span class="throwsLabel">Throws:</span></dt>
371 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - if passed a <code>null</code> transformer</dd>
372 <dt><span class="seeLabel">See Also:</span></dt>
373 <dd><a href="#addTransformer(java.lang.instrument.ClassFileTransformer,boolean)"><code>addTransformer(ClassFileTransformer,boolean)</code></a></dd>
374 </dl>
375 </section>
376 </li>
377 <li class="blockList">
378 <section class="detail">
379 <h3><a id="removeTransformer(java.lang.instrument.ClassFileTransformer)">removeTransformer</a></h3>
380 <div class="memberSignature"><span class="returnType">boolean</span> <span class="memberName">removeTransformer</span>(<span class="arguments"><a href="ClassFileTransformer.html" title="interface in java.lang.instrument">ClassFileTransformer</a> transformer)</span></div>
381 <div class="block">Unregisters the supplied transformer. Future class definitions will
382 not be shown to the transformer. Removes the most-recently-added matching
383 instance of the transformer. Due to the multi-threaded nature of
384 class loading, it is possible for a transformer to receive calls
385 after it has been removed. Transformers should be written defensively
386 to expect this situation.</div>
387 <dl>
388 <dt><span class="paramLabel">Parameters:</span></dt>
389 <dd><code>transformer</code> - the transformer to unregister</dd>
390 <dt><span class="returnLabel">Returns:</span></dt>
391 <dd>true if the transformer was found and removed, false if the
392 transformer was not found</dd>
393 <dt><span class="throwsLabel">Throws:</span></dt>
394 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - if passed a <code>null</code> transformer</dd>
395 </dl>
396 </section>
397 </li>
398 <li class="blockList">
399 <section class="detail">
400 <h3><a id="isRetransformClassesSupported()">isRetransformClassesSupported</a></h3>
401 <div class="memberSignature"><span class="returnType">boolean</span> <span class="memberName">isRetransformClassesSupported</span>()</div>
402 <div class="block">Returns whether or not the current JVM configuration supports retransformation
403 of classes.
404 The ability to retransform an already loaded class is an optional capability
405 of a JVM.
406 Retransformation will only be supported if the
407 <code>Can-Retransform-Classes</code> manifest attribute is set to
408 <code>true</code> in the agent JAR file (as described in the
409 <a href="package-summary.html">package specification</a>) and the JVM supports
410 this capability.
411 During a single instantiation of a single JVM, multiple calls to this
412 method will always return the same answer.</div>
413 <dl>
414 <dt><span class="returnLabel">Returns:</span></dt>
415 <dd>true if the current JVM configuration supports retransformation of
416 classes, false if not.</dd>
417 <dt><span class="simpleTagLabel">Since:</span></dt>
418 <dd>1.6</dd>
419 <dt><span class="seeLabel">See Also:</span></dt>
420 <dd><a href="#retransformClasses(java.lang.Class...)"><code>retransformClasses(java.lang.Class<?>...)</code></a></dd>
421 </dl>
422 </section>
423 </li>
424 <li class="blockList">
425 <section class="detail">
426 <h3><a id="retransformClasses(java.lang.Class...)">retransformClasses</a></h3>
427 <div class="memberSignature"><span class="returnType">void</span> <span class="memberName">retransformClasses</span>(<span class="arguments"><a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a><?>... classes)</span>
428 throws <span class="exceptions"><a href="UnmodifiableClassException.html" title="class in java.lang.instrument">UnmodifiableClassException</a></span></div>
429 <div class="block">Retransform the supplied set of classes.
430
431 <P>
432 This function facilitates the instrumentation
433 of already loaded classes.
434 When classes are initially loaded or when they are
435 <a href="#redefineClasses(java.lang.instrument.ClassDefinition...)">redefined</a>,
436 the initial class file bytes can be transformed with the
437 <a href="ClassFileTransformer.html" title="interface in java.lang.instrument"><code>ClassFileTransformer</code></a>.
438 This function reruns the transformation process
439 (whether or not a transformation has previously occurred).
440 This retransformation follows these steps:
441 <ul>
442 <li>starting from the initial class file bytes
443 </li>
444 <li>for each transformer that was added with <code>canRetransform</code>
445 false, the bytes returned by
446 <a href="ClassFileTransformer.html#transform(java.lang.Module,java.lang.ClassLoader,java.lang.String,java.lang.Class,java.security.ProtectionDomain,byte%5B%5D)"><code>transform</code></a> during the last class load or redefine are
447 reused as the output of the transformation; note that this is
448 equivalent to reapplying the previous transformation, unaltered;
449 except that <code>transform</code> method is not called.
450 </li>
451 <li>for each transformer that was added with <code>canRetransform</code>
452 true, the
453 <a href="ClassFileTransformer.html#transform(java.lang.Module,java.lang.ClassLoader,java.lang.String,java.lang.Class,java.security.ProtectionDomain,byte%5B%5D)"><code>transform</code></a> method is called in these transformers
454 </li>
455 <li>the transformed class file bytes are installed as the new
456 definition of the class
457 </li>
458 </ul>
459 <P>
460
461 The order of transformation is described in <a href="ClassFileTransformer.html" title="interface in java.lang.instrument"><code>ClassFileTransformer</code></a>.
462 This same order is used in the automatic reapplication of
463 retransformation incapable transforms.
464 <P>
465
466 The initial class file bytes represent the bytes passed to
467 <a href="../../../../java.base/java/lang/ClassLoader.html#defineClass(byte%5B%5D,int,int)"><code>ClassLoader.defineClass</code></a> or
468 <a href="#redefineClasses(java.lang.instrument.ClassDefinition...)"><code>redefineClasses</code></a>
469 (before any transformations
470 were applied), however they might not exactly match them.
471 The constant pool might not have the same layout or contents.
472 The constant pool may have more or fewer entries.
473 Constant pool entries may be in a different order; however,
474 constant pool indices in the bytecodes of methods will correspond.
475 Some attributes may not be present.
476 Where order is not meaningful, for example the order of methods,
477 order might not be preserved.
478
479 <P>
480 This method operates on
481 a set in order to allow interdependent changes to more than one class at the same time
482 (a retransformation of class A can require a retransformation of class B).
483
484 <P>
485 If a retransformed method has active stack frames, those active frames continue to
486 run the bytecodes of the original method.
487 The retransformed method will be used on new invokes.
488
489 <P>
490 This method does not cause any initialization except that which would occur
491 under the customary JVM semantics. In other words, redefining a class
492 does not cause its initializers to be run. The values of static variables
493 will remain as they were prior to the call.
494
495 <P>
496 Instances of the retransformed class are not affected.
497
498 <P>
499 The retransformation may change method bodies, the constant pool and
500 attributes (unless explicitly prohibited).
501 The retransformation must not add, remove or rename fields or methods, change the
502 signatures of methods, or change inheritance.
503 The retransformation must not change the <code>NestHost</code>,
504 <code>NestMembers</code>, or <code>Record</code> attributes.
505 These restrictions may be lifted in future versions.
506 The class file bytes are not checked, verified and installed
507 until after the transformations have been applied, if the resultant bytes are in
508 error this method will throw an exception.
509
510 <P>
511 If this method throws an exception, no classes have been retransformed.
512 <P>
513 This method is intended for use in instrumentation, as described in the
514 <a href="Instrumentation.html" title="interface in java.lang.instrument">class specification</a>.</div>
515 <dl>
516 <dt><span class="paramLabel">Parameters:</span></dt>
517 <dd><code>classes</code> - array of classes to retransform;
518 a zero-length array is allowed, in this case, this method does nothing</dd>
519 <dt><span class="throwsLabel">Throws:</span></dt>
520 <dd><code><a href="UnmodifiableClassException.html" title="class in java.lang.instrument">UnmodifiableClassException</a></code> - if a specified class cannot be modified
521 (<a href="#isModifiableClass(java.lang.Class)"><code>isModifiableClass(java.lang.Class<?>)</code></a> would return <code>false</code>)</dd>
522 <dd><code><a href="../../../../java.base/java/lang/UnsupportedOperationException.html" title="class in java.lang">UnsupportedOperationException</a></code> - if the current configuration of the JVM does not allow
523 retransformation (<a href="#isRetransformClassesSupported()"><code>isRetransformClassesSupported()</code></a> is false) or the retransformation attempted
524 to make unsupported changes</dd>
525 <dd><code><a href="../../../../java.base/java/lang/ClassFormatError.html" title="class in java.lang">ClassFormatError</a></code> - if the data did not contain a valid class</dd>
526 <dd><code><a href="../../../../java.base/java/lang/NoClassDefFoundError.html" title="class in java.lang">NoClassDefFoundError</a></code> - if the name in the class file is not equal to the name of the class</dd>
527 <dd><code><a href="../../../../java.base/java/lang/UnsupportedClassVersionError.html" title="class in java.lang">UnsupportedClassVersionError</a></code> - if the class file version numbers are not supported</dd>
528 <dd><code><a href="../../../../java.base/java/lang/ClassCircularityError.html" title="class in java.lang">ClassCircularityError</a></code> - if the new classes contain a circularity</dd>
529 <dd><code><a href="../../../../java.base/java/lang/LinkageError.html" title="class in java.lang">LinkageError</a></code> - if a linkage error occurs</dd>
530 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - if the supplied classes array or any of its components
531 is <code>null</code>.</dd>
532 <dt><span class="simpleTagLabel">Since:</span></dt>
533 <dd>1.6</dd>
534 <dt><span class="seeLabel">See Also:</span></dt>
535 <dd><a href="#isRetransformClassesSupported()"><code>isRetransformClassesSupported()</code></a>,
536 <a href="#addTransformer(java.lang.instrument.ClassFileTransformer,boolean)"><code>addTransformer(java.lang.instrument.ClassFileTransformer, boolean)</code></a>,
537 <a href="ClassFileTransformer.html" title="interface in java.lang.instrument"><code>ClassFileTransformer</code></a></dd>
538 </dl>
539 </section>
540 </li>
541 <li class="blockList">
542 <section class="detail">
543 <h3><a id="isRedefineClassesSupported()">isRedefineClassesSupported</a></h3>
544 <div class="memberSignature"><span class="returnType">boolean</span> <span class="memberName">isRedefineClassesSupported</span>()</div>
545 <div class="block">Returns whether or not the current JVM configuration supports redefinition
546 of classes.
547 The ability to redefine an already loaded class is an optional capability
548 of a JVM.
549 Redefinition will only be supported if the
550 <code>Can-Redefine-Classes</code> manifest attribute is set to
551 <code>true</code> in the agent JAR file (as described in the
552 <a href="package-summary.html">package specification</a>) and the JVM supports
553 this capability.
554 During a single instantiation of a single JVM, multiple calls to this
555 method will always return the same answer.</div>
556 <dl>
557 <dt><span class="returnLabel">Returns:</span></dt>
558 <dd>true if the current JVM configuration supports redefinition of classes,
559 false if not.</dd>
560 <dt><span class="seeLabel">See Also:</span></dt>
561 <dd><a href="#redefineClasses(java.lang.instrument.ClassDefinition...)"><code>redefineClasses(java.lang.instrument.ClassDefinition...)</code></a></dd>
562 </dl>
563 </section>
564 </li>
565 <li class="blockList">
566 <section class="detail">
567 <h3><a id="redefineClasses(java.lang.instrument.ClassDefinition...)">redefineClasses</a></h3>
568 <div class="memberSignature"><span class="returnType">void</span> <span class="memberName">redefineClasses</span>(<span class="arguments"><a href="ClassDefinition.html" title="class in java.lang.instrument">ClassDefinition</a>... definitions)</span>
569 throws <span class="exceptions"><a href="../../../../java.base/java/lang/ClassNotFoundException.html" title="class in java.lang">ClassNotFoundException</a>,
570 <a href="UnmodifiableClassException.html" title="class in java.lang.instrument">UnmodifiableClassException</a></span></div>
571 <div class="block">Redefine the supplied set of classes using the supplied class files.
572
573 <P>
574 This method is used to replace the definition of a class without reference
575 to the existing class file bytes, as one might do when recompiling from source
576 for fix-and-continue debugging.
577 Where the existing class file bytes are to be transformed (for
578 example in bytecode instrumentation)
579 <a href="#retransformClasses(java.lang.Class...)"><code>retransformClasses</code></a>
580 should be used.
581
582 <P>
583 This method operates on
584 a set in order to allow interdependent changes to more than one class at the same time
585 (a redefinition of class A can require a redefinition of class B).
586
587 <P>
588 If a redefined method has active stack frames, those active frames continue to
589 run the bytecodes of the original method.
590 The redefined method will be used on new invokes.
591
592 <P>
593 This method does not cause any initialization except that which would occur
594 under the customary JVM semantics. In other words, redefining a class
595 does not cause its initializers to be run. The values of static variables
596 will remain as they were prior to the call.
597
598 <P>
599 Instances of the redefined class are not affected.
600
601 <P>
602 The redefinition may change method bodies, the constant pool and attributes
603 (unless explicitly prohibited).
604 The redefinition must not add, remove or rename fields or methods, change the
605 signatures of methods, or change inheritance.
606 The redefinition must not change the <code>NestHost</code>,
607 <code>NestMembers</code>, or <code>Record</code> attributes.
608 These restrictions may be lifted in future versions.
609 The class file bytes are not checked, verified and installed
610 until after the transformations have been applied, if the resultant bytes are in
611 error this method will throw an exception.
612
613 <P>
614 If this method throws an exception, no classes have been redefined.
615 <P>
616 This method is intended for use in instrumentation, as described in the
617 <a href="Instrumentation.html" title="interface in java.lang.instrument">class specification</a>.</div>
618 <dl>
619 <dt><span class="paramLabel">Parameters:</span></dt>
620 <dd><code>definitions</code> - array of classes to redefine with corresponding definitions;
621 a zero-length array is allowed, in this case, this method does nothing</dd>
622 <dt><span class="throwsLabel">Throws:</span></dt>
623 <dd><code><a href="UnmodifiableClassException.html" title="class in java.lang.instrument">UnmodifiableClassException</a></code> - if a specified class cannot be modified
624 (<a href="#isModifiableClass(java.lang.Class)"><code>isModifiableClass(java.lang.Class<?>)</code></a> would return <code>false</code>)</dd>
625 <dd><code><a href="../../../../java.base/java/lang/UnsupportedOperationException.html" title="class in java.lang">UnsupportedOperationException</a></code> - if the current configuration of the JVM does not allow
626 redefinition (<a href="#isRedefineClassesSupported()"><code>isRedefineClassesSupported()</code></a> is false) or the redefinition attempted
627 to make unsupported changes</dd>
628 <dd><code><a href="../../../../java.base/java/lang/ClassFormatError.html" title="class in java.lang">ClassFormatError</a></code> - if the data did not contain a valid class</dd>
629 <dd><code><a href="../../../../java.base/java/lang/NoClassDefFoundError.html" title="class in java.lang">NoClassDefFoundError</a></code> - if the name in the class file is not equal to the name of the class</dd>
630 <dd><code><a href="../../../../java.base/java/lang/UnsupportedClassVersionError.html" title="class in java.lang">UnsupportedClassVersionError</a></code> - if the class file version numbers are not supported</dd>
631 <dd><code><a href="../../../../java.base/java/lang/ClassCircularityError.html" title="class in java.lang">ClassCircularityError</a></code> - if the new classes contain a circularity</dd>
632 <dd><code><a href="../../../../java.base/java/lang/LinkageError.html" title="class in java.lang">LinkageError</a></code> - if a linkage error occurs</dd>
633 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - if the supplied definitions array or any of its components
634 is <code>null</code></dd>
635 <dd><code><a href="../../../../java.base/java/lang/ClassNotFoundException.html" title="class in java.lang">ClassNotFoundException</a></code> - Can never be thrown (present for compatibility reasons only)</dd>
636 <dt><span class="seeLabel">See Also:</span></dt>
637 <dd><a href="#isRedefineClassesSupported()"><code>isRedefineClassesSupported()</code></a>,
638 <a href="#addTransformer(java.lang.instrument.ClassFileTransformer,boolean)"><code>addTransformer(java.lang.instrument.ClassFileTransformer, boolean)</code></a>,
639 <a href="ClassFileTransformer.html" title="interface in java.lang.instrument"><code>ClassFileTransformer</code></a></dd>
640 </dl>
641 </section>
642 </li>
643 <li class="blockList">
644 <section class="detail">
645 <h3><a id="isModifiableClass(java.lang.Class)">isModifiableClass</a></h3>
646 <div class="memberSignature"><span class="returnType">boolean</span> <span class="memberName">isModifiableClass</span>(<span class="arguments"><a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a><?> theClass)</span></div>
647 <div class="block">Tests whether a class is modifiable by
648 <a href="#retransformClasses(java.lang.Class...)">retransformation</a>
649 or <a href="#redefineClasses(java.lang.instrument.ClassDefinition...)">redefinition</a>.
650 If a class is modifiable then this method returns <code>true</code>.
651 If a class is not modifiable then this method returns <code>false</code>.
652 <P>
653 For a class to be retransformed, <a href="#isRetransformClassesSupported()"><code>isRetransformClassesSupported()</code></a> must also be true.
654 But the value of <code>isRetransformClassesSupported()</code> does not influence the value
655 returned by this function.
656 For a class to be redefined, <a href="#isRedefineClassesSupported()"><code>isRedefineClassesSupported()</code></a> must also be true.
657 But the value of <code>isRedefineClassesSupported()</code> does not influence the value
658 returned by this function.
659 <P>
660 Primitive classes (for example, <code>java.lang.Integer.TYPE</code>)
661 and array classes are never modifiable.</div>
662 <dl>
663 <dt><span class="paramLabel">Parameters:</span></dt>
664 <dd><code>theClass</code> - the class to check for being modifiable</dd>
665 <dt><span class="returnLabel">Returns:</span></dt>
666 <dd>whether or not the argument class is modifiable</dd>
667 <dt><span class="throwsLabel">Throws:</span></dt>
668 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - if the specified class is <code>null</code>.</dd>
669 <dt><span class="simpleTagLabel">Since:</span></dt>
670 <dd>1.6</dd>
671 <dt><span class="seeLabel">See Also:</span></dt>
672 <dd><a href="#retransformClasses(java.lang.Class...)"><code>retransformClasses(java.lang.Class<?>...)</code></a>,
673 <a href="#isRetransformClassesSupported()"><code>isRetransformClassesSupported()</code></a>,
674 <a href="#redefineClasses(java.lang.instrument.ClassDefinition...)"><code>redefineClasses(java.lang.instrument.ClassDefinition...)</code></a>,
675 <a href="#isRedefineClassesSupported()"><code>isRedefineClassesSupported()</code></a></dd>
676 </dl>
677 </section>
678 </li>
679 <li class="blockList">
680 <section class="detail">
681 <h3><a id="getAllLoadedClasses()">getAllLoadedClasses</a></h3>
682 <div class="memberSignature"><span class="returnType"><a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a>[]</span> <span class="memberName">getAllLoadedClasses</span>()</div>
683 <div class="block">Returns an array of all classes currently loaded by the JVM.</div>
684 <dl>
685 <dt><span class="returnLabel">Returns:</span></dt>
686 <dd>an array containing all the classes loaded by the JVM, zero-length if there are none</dd>
687 </dl>
688 </section>
689 </li>
690 <li class="blockList">
691 <section class="detail">
692 <h3><a id="getInitiatedClasses(java.lang.ClassLoader)">getInitiatedClasses</a></h3>
693 <div class="memberSignature"><span class="returnType"><a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a>[]</span> <span class="memberName">getInitiatedClasses</span>(<span class="arguments"><a href="../../../../java.base/java/lang/ClassLoader.html" title="class in java.lang">ClassLoader</a> loader)</span></div>
694 <div class="block">Returns an array of all classes for which <code>loader</code> is an initiating loader.
695 If the supplied loader is <code>null</code>, classes initiated by the bootstrap class
696 loader are returned.</div>
697 <dl>
698 <dt><span class="paramLabel">Parameters:</span></dt>
699 <dd><code>loader</code> - the loader whose initiated class list will be returned</dd>
700 <dt><span class="returnLabel">Returns:</span></dt>
701 <dd>an array containing all the classes for which loader is an initiating loader,
702 zero-length if there are none</dd>
703 </dl>
704 </section>
705 </li>
706 <li class="blockList">
707 <section class="detail">
708 <h3><a id="getObjectSize(java.lang.Object)">getObjectSize</a></h3>
709 <div class="memberSignature"><span class="returnType">long</span> <span class="memberName">getObjectSize</span>(<span class="arguments"><a href="../../../../java.base/java/lang/Object.html" title="class in java.lang">Object</a> objectToSize)</span></div>
710 <div class="block">Returns an implementation-specific approximation of the amount of storage consumed by
711 the specified object. The result may include some or all of the object's overhead,
712 and thus is useful for comparison within an implementation but not between implementations.
713
714 The estimate may change during a single invocation of the JVM.</div>
715 <dl>
716 <dt><span class="paramLabel">Parameters:</span></dt>
717 <dd><code>objectToSize</code> - the object to size</dd>
718 <dt><span class="returnLabel">Returns:</span></dt>
719 <dd>an implementation-specific approximation of the amount of storage consumed by the specified object</dd>
720 <dt><span class="throwsLabel">Throws:</span></dt>
721 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - if the supplied Object is <code>null</code>.</dd>
722 </dl>
723 </section>
724 </li>
725 <li class="blockList">
726 <section class="detail">
727 <h3><a id="appendToBootstrapClassLoaderSearch(java.util.jar.JarFile)">appendToBootstrapClassLoaderSearch</a></h3>
728 <div class="memberSignature"><span class="returnType">void</span> <span class="memberName">appendToBootstrapClassLoaderSearch</span>(<span class="arguments"><a href="../../../../java.base/java/util/jar/JarFile.html" title="class in java.util.jar">JarFile</a> jarfile)</span></div>
729 <div class="block">Specifies a JAR file with instrumentation classes to be defined by the
730 bootstrap class loader.
731
732 <p> When the virtual machine's built-in class loader, known as the "bootstrap
733 class loader", unsuccessfully searches for a class, the entries in the <a href="../../../../java.base/java/util/jar/JarFile.html" title="class in java.util.jar"><code>JAR file</code></a> will be searched as well.
734
735 <p> This method may be used multiple times to add multiple JAR files to be
736 searched in the order that this method was invoked.
737
738 <p> The agent should take care to ensure that the JAR does not contain any
739 classes or resources other than those to be defined by the bootstrap
740 class loader for the purpose of instrumentation.
741 Failure to observe this warning could result in unexpected
742 behavior that is difficult to diagnose. For example, suppose there is a
743 loader L, and L's parent for delegation is the bootstrap class loader.
744 Furthermore, a method in class C, a class defined by L, makes reference to
745 a non-public accessor class C$1. If the JAR file contains a class C$1 then
746 the delegation to the bootstrap class loader will cause C$1 to be defined
747 by the bootstrap class loader. In this example an <code>IllegalAccessError</code>
748 will be thrown that may cause the application to fail. One approach to
749 avoiding these types of issues, is to use a unique package name for the
750 instrumentation classes.
751
752 <p>
753 <cite>The Java™ Virtual Machine Specification</cite>
754 specifies that a subsequent attempt to resolve a symbolic
755 reference that the Java virtual machine has previously unsuccessfully attempted
756 to resolve always fails with the same error that was thrown as a result of the
757 initial resolution attempt. Consequently, if the JAR file contains an entry
758 that corresponds to a class for which the Java virtual machine has
759 unsuccessfully attempted to resolve a reference, then subsequent attempts to
760 resolve that reference will fail with the same error as the initial attempt.</div>
761 <dl>
762 <dt><span class="paramLabel">Parameters:</span></dt>
763 <dd><code>jarfile</code> - The JAR file to be searched when the bootstrap class loader
764 unsuccessfully searches for a class.</dd>
765 <dt><span class="throwsLabel">Throws:</span></dt>
766 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - If <code>jarfile</code> is <code>null</code>.</dd>
767 <dt><span class="simpleTagLabel">Since:</span></dt>
768 <dd>1.6</dd>
769 <dt><span class="seeLabel">See Also:</span></dt>
770 <dd><a href="#appendToSystemClassLoaderSearch(java.util.jar.JarFile)"><code>appendToSystemClassLoaderSearch(java.util.jar.JarFile)</code></a>,
771 <a href="../../../../java.base/java/lang/ClassLoader.html" title="class in java.lang"><code>ClassLoader</code></a>,
772 <a href="../../../../java.base/java/util/jar/JarFile.html" title="class in java.util.jar"><code>JarFile</code></a></dd>
773 </dl>
774 </section>
775 </li>
776 <li class="blockList">
777 <section class="detail">
778 <h3><a id="appendToSystemClassLoaderSearch(java.util.jar.JarFile)">appendToSystemClassLoaderSearch</a></h3>
779 <div class="memberSignature"><span class="returnType">void</span> <span class="memberName">appendToSystemClassLoaderSearch</span>(<span class="arguments"><a href="../../../../java.base/java/util/jar/JarFile.html" title="class in java.util.jar">JarFile</a> jarfile)</span></div>
780 <div class="block">Specifies a JAR file with instrumentation classes to be defined by the
781 system class loader.
782
783 When the system class loader for delegation (see
784 <a href="../../../../java.base/java/lang/ClassLoader.html#getSystemClassLoader()"><code>getSystemClassLoader()</code></a>)
785 unsuccessfully searches for a class, the entries in the <a href="../../../../java.base/java/util/jar/JarFile.html" title="class in java.util.jar"><code>JarFile</code></a> will be searched as well.
786
787 <p> This method may be used multiple times to add multiple JAR files to be
788 searched in the order that this method was invoked.
789
790 <p> The agent should take care to ensure that the JAR does not contain any
791 classes or resources other than those to be defined by the system class
792 loader for the purpose of instrumentation.
793 Failure to observe this warning could result in unexpected
794 behavior that is difficult to diagnose (see
795 <a href="#appendToBootstrapClassLoaderSearch(java.util.jar.JarFile)"><code>appendToBootstrapClassLoaderSearch</code></a>).
796
797 <p> The system class loader supports adding a JAR file to be searched if
798 it implements a method named <code>appendToClassPathForInstrumentation</code>
799 which takes a single parameter of type <code>java.lang.String</code>. The
800 method is not required to have <code>public</code> access. The name of
801 the JAR file is obtained by invoking the <a href="../../../../java.base/java/util/zip/ZipFile.html#getName()"><code>getName()</code></a> method on the <code>jarfile</code> and this is provided as the
802 parameter to the <code>appendToClassPathForInstrumentation</code> method.
803
804 <p>
805 <cite>The Java™ Virtual Machine Specification</cite>
806 specifies that a subsequent attempt to resolve a symbolic
807 reference that the Java virtual machine has previously unsuccessfully attempted
808 to resolve always fails with the same error that was thrown as a result of the
809 initial resolution attempt. Consequently, if the JAR file contains an entry
810 that corresponds to a class for which the Java virtual machine has
811 unsuccessfully attempted to resolve a reference, then subsequent attempts to
812 resolve that reference will fail with the same error as the initial attempt.
813
814 <p> This method does not change the value of <code>java.class.path</code>
815 <a href="../../../../java.base/java/lang/System.html#getProperties()"><code>system property</code></a>.</div>
816 <dl>
817 <dt><span class="paramLabel">Parameters:</span></dt>
818 <dd><code>jarfile</code> - The JAR file to be searched when the system class loader
819 unsuccessfully searches for a class.</dd>
820 <dt><span class="throwsLabel">Throws:</span></dt>
821 <dd><code><a href="../../../../java.base/java/lang/UnsupportedOperationException.html" title="class in java.lang">UnsupportedOperationException</a></code> - If the system class loader does not support appending a
822 a JAR file to be searched.</dd>
823 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - If <code>jarfile</code> is <code>null</code>.</dd>
824 <dt><span class="simpleTagLabel">Since:</span></dt>
825 <dd>1.6</dd>
826 <dt><span class="seeLabel">See Also:</span></dt>
827 <dd><a href="#appendToBootstrapClassLoaderSearch(java.util.jar.JarFile)"><code>appendToBootstrapClassLoaderSearch(java.util.jar.JarFile)</code></a>,
828 <a href="../../../../java.base/java/lang/ClassLoader.html#getSystemClassLoader()"><code>ClassLoader.getSystemClassLoader()</code></a>,
829 <a href="../../../../java.base/java/util/jar/JarFile.html" title="class in java.util.jar"><code>JarFile</code></a></dd>
830 </dl>
831 </section>
832 </li>
833 <li class="blockList">
834 <section class="detail">
835 <h3><a id="isNativeMethodPrefixSupported()">isNativeMethodPrefixSupported</a></h3>
836 <div class="memberSignature"><span class="returnType">boolean</span> <span class="memberName">isNativeMethodPrefixSupported</span>()</div>
837 <div class="block">Returns whether the current JVM configuration supports
838 <a href="#setNativeMethodPrefix(java.lang.instrument.ClassFileTransformer,java.lang.String)">setting a native method prefix</a>.
839 The ability to set a native method prefix is an optional
840 capability of a JVM.
841 Setting a native method prefix will only be supported if the
842 <code>Can-Set-Native-Method-Prefix</code> manifest attribute is set to
843 <code>true</code> in the agent JAR file (as described in the
844 <a href="package-summary.html">package specification</a>) and the JVM supports
845 this capability.
846 During a single instantiation of a single JVM, multiple
847 calls to this method will always return the same answer.</div>
848 <dl>
849 <dt><span class="returnLabel">Returns:</span></dt>
850 <dd>true if the current JVM configuration supports
851 setting a native method prefix, false if not.</dd>
852 <dt><span class="simpleTagLabel">Since:</span></dt>
853 <dd>1.6</dd>
854 <dt><span class="seeLabel">See Also:</span></dt>
855 <dd><a href="#setNativeMethodPrefix(java.lang.instrument.ClassFileTransformer,java.lang.String)"><code>setNativeMethodPrefix(java.lang.instrument.ClassFileTransformer, java.lang.String)</code></a></dd>
856 </dl>
857 </section>
858 </li>
859 <li class="blockList">
860 <section class="detail">
861 <h3><a id="setNativeMethodPrefix(java.lang.instrument.ClassFileTransformer,java.lang.String)">setNativeMethodPrefix</a></h3>
862 <div class="memberSignature"><span class="returnType">void</span> <span class="memberName">setNativeMethodPrefix</span>(<span class="arguments"><a href="ClassFileTransformer.html" title="interface in java.lang.instrument">ClassFileTransformer</a> transformer,
863 <a href="../../../../java.base/java/lang/String.html" title="class in java.lang">String</a> prefix)</span></div>
864 <div class="block">This method modifies the failure handling of
865 native method resolution by allowing retry
866 with a prefix applied to the name.
867 When used with the
868 <a href="ClassFileTransformer.html" title="interface in java.lang.instrument"><code>ClassFileTransformer</code></a>,
869 it enables native methods to be
870 instrumented.
871 <p>
872 Since native methods cannot be directly instrumented
873 (they have no bytecodes), they must be wrapped with
874 a non-native method which can be instrumented.
875 For example, if we had:
876 <pre>
877 native boolean foo(int x);</pre>
878 <p>
879 We could transform the class file (with the
880 ClassFileTransformer during the initial definition
881 of the class) so that this becomes:
882 <pre>
883 boolean foo(int x) {
884 <i>... record entry to foo ...</i>
885 return wrapped_foo(x);
886 }
887
888 native boolean wrapped_foo(int x);</pre>
889 <p>
890 Where <code>foo</code> becomes a wrapper for the actual native
891 method with the appended prefix "wrapped_". Note that
892 "wrapped_" would be a poor choice of prefix since it
893 might conceivably form the name of an existing method
894 thus something like "$$$MyAgentWrapped$$$_" would be
895 better but would make these examples less readable.
896 <p>
897 The wrapper will allow data to be collected on the native
898 method call, but now the problem becomes linking up the
899 wrapped method with the native implementation.
900 That is, the method <code>wrapped_foo</code> needs to be
901 resolved to the native implementation of <code>foo</code>,
902 which might be:
903 <pre>
904 Java_somePackage_someClass_foo(JNIEnv* env, jint x)</pre>
905 <p>
906 This function allows the prefix to be specified and the
907 proper resolution to occur.
908 Specifically, when the standard resolution fails, the
909 resolution is retried taking the prefix into consideration.
910 There are two ways that resolution occurs, explicit
911 resolution with the JNI function <code>RegisterNatives</code>
912 and the normal automatic resolution. For
913 <code>RegisterNatives</code>, the JVM will attempt this
914 association:
915 <pre><code>
916 method(foo) -> nativeImplementation(foo)
917 </code></pre>
918 <p>
919 When this fails, the resolution will be retried with
920 the specified prefix prepended to the method name,
921 yielding the correct resolution:
922 <pre><code>
923 method(wrapped_foo) -> nativeImplementation(foo)
924 </code></pre>
925 <p>
926 For automatic resolution, the JVM will attempt:
927 <pre><code>
928 method(wrapped_foo) -> nativeImplementation(wrapped_foo)
929 </code></pre>
930 <p>
931 When this fails, the resolution will be retried with
932 the specified prefix deleted from the implementation name,
933 yielding the correct resolution:
934 <pre><code>
935 method(wrapped_foo) -> nativeImplementation(foo)
936 </code></pre>
937 <p>
938 Note that since the prefix is only used when standard
939 resolution fails, native methods can be wrapped selectively.
940 <p>
941 Since each <code>ClassFileTransformer</code>
942 can do its own transformation of the bytecodes, more
943 than one layer of wrappers may be applied. Thus each
944 transformer needs its own prefix. Since transformations
945 are applied in order, the prefixes, if applied, will
946 be applied in the same order
947 (see <a href="#addTransformer(java.lang.instrument.ClassFileTransformer,boolean)"><code>addTransformer</code></a>).
948 Thus if three transformers applied
949 wrappers, <code>foo</code> might become
950 <code>$trans3_$trans2_$trans1_foo</code>. But if, say,
951 the second transformer did not apply a wrapper to
952 <code>foo</code> it would be just
953 <code>$trans3_$trans1_foo</code>. To be able to
954 efficiently determine the sequence of prefixes,
955 an intermediate prefix is only applied if its non-native
956 wrapper exists. Thus, in the last example, even though
957 <code>$trans1_foo</code> is not a native method, the
958 <code>$trans1_</code> prefix is applied since
959 <code>$trans1_foo</code> exists.</div>
960 <dl>
961 <dt><span class="paramLabel">Parameters:</span></dt>
962 <dd><code>transformer</code> - The ClassFileTransformer which wraps using this prefix.</dd>
963 <dd><code>prefix</code> - The prefix to apply to wrapped native methods when
964 retrying a failed native method resolution. If prefix
965 is either <code>null</code> or the empty string, then
966 failed native method resolutions are not retried for
967 this transformer.</dd>
968 <dt><span class="throwsLabel">Throws:</span></dt>
969 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - if passed a <code>null</code> transformer.</dd>
970 <dd><code><a href="../../../../java.base/java/lang/UnsupportedOperationException.html" title="class in java.lang">UnsupportedOperationException</a></code> - if the current configuration of
971 the JVM does not allow setting a native method prefix
972 (<a href="#isNativeMethodPrefixSupported()"><code>isNativeMethodPrefixSupported()</code></a> is false).</dd>
973 <dd><code><a href="../../../../java.base/java/lang/IllegalArgumentException.html" title="class in java.lang">IllegalArgumentException</a></code> - if the transformer is not registered
974 (see <a href="#addTransformer(java.lang.instrument.ClassFileTransformer,boolean)"><code>addTransformer</code></a>).</dd>
975 <dt><span class="simpleTagLabel">Since:</span></dt>
976 <dd>1.6</dd>
977 </dl>
978 </section>
979 </li>
980 <li class="blockList">
981 <section class="detail">
982 <h3><a id="redefineModule(java.lang.Module,java.util.Set,java.util.Map,java.util.Map,java.util.Set,java.util.Map)">redefineModule</a></h3>
983 <div class="memberSignature"><span class="returnType">void</span> <span class="memberName">redefineModule</span>(<span class="arguments"><a href="../../../../java.base/java/lang/Module.html" title="class in java.lang">Module</a> module,
984 <a href="../../../../java.base/java/util/Set.html" title="interface in java.util">Set</a><<a href="../../../../java.base/java/lang/Module.html" title="class in java.lang">Module</a>> extraReads,
985 <a href="../../../../java.base/java/util/Map.html" title="interface in java.util">Map</a><<a href="../../../../java.base/java/lang/String.html" title="class in java.lang">String</a>,<a href="../../../../java.base/java/util/Set.html" title="interface in java.util">Set</a><<a href="../../../../java.base/java/lang/Module.html" title="class in java.lang">Module</a>>> extraExports,
986 <a href="../../../../java.base/java/util/Map.html" title="interface in java.util">Map</a><<a href="../../../../java.base/java/lang/String.html" title="class in java.lang">String</a>,<a href="../../../../java.base/java/util/Set.html" title="interface in java.util">Set</a><<a href="../../../../java.base/java/lang/Module.html" title="class in java.lang">Module</a>>> extraOpens,
987 <a href="../../../../java.base/java/util/Set.html" title="interface in java.util">Set</a><<a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a><?>> extraUses,
988 <a href="../../../../java.base/java/util/Map.html" title="interface in java.util">Map</a><<a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a><?>,<a href="../../../../java.base/java/util/List.html" title="interface in java.util">List</a><<a href="../../../../java.base/java/lang/Class.html" title="class in java.lang">Class</a><?>>> extraProvides)</span></div>
989 <div class="block">Redefine a module to expand the set of modules that it reads, the set of
990 packages that it exports or opens, or the services that it uses or
991 provides. This method facilitates the instrumentation of code in named
992 modules where that instrumentation requires changes to the set of modules
993 that are read, the packages that are exported or open, or the services
994 that are used or provided.
995
996 <p> This method cannot reduce the set of modules that a module reads, nor
997 reduce the set of packages that it exports or opens, nor reduce the set
998 of services that it uses or provides. This method is a no-op when invoked
999 to redefine an unnamed module. </p>
1000
1001 <p> When expanding the services that a module uses or provides then the
1002 onus is on the agent to ensure that the service type will be accessible at
1003 each instrumentation site where the service type is used. This method
1004 does not check if the service type is a member of the module or in a
1005 package exported to the module by another module that it reads. </p>
1006
1007 <p> The <code>extraExports</code> parameter is the map of additional packages
1008 to export. The <code>extraOpens</code> parameter is the map of additional
1009 packages to open. In both cases, the map key is the fully-qualified name
1010 of the package as defined in section 6.5.3 of
1011 <cite>The Java™ Language Specification </cite>, for example, <code>
1012 "java.lang"</code>. The map value is the non-empty set of modules that the
1013 package should be exported or opened to. </p>
1014
1015 <p> The <code>extraProvides</code> parameter is the additional service providers
1016 for the module to provide. The map key is the service type. The map value
1017 is the non-empty list of implementation types, each of which is a member
1018 of the module and an implementation of the service. </p>
1019
1020 <p> This method is safe for concurrent use and so allows multiple agents
1021 to instrument and update the same module at around the same time. </p></div>
1022 <dl>
1023 <dt><span class="paramLabel">Parameters:</span></dt>
1024 <dd><code>module</code> - the module to redefine</dd>
1025 <dd><code>extraReads</code> - the possibly-empty set of additional modules to read</dd>
1026 <dd><code>extraExports</code> - the possibly-empty map of additional packages to export</dd>
1027 <dd><code>extraOpens</code> - the possibly-empty map of additional packages to open</dd>
1028 <dd><code>extraUses</code> - the possibly-empty set of additional services to use</dd>
1029 <dd><code>extraProvides</code> - the possibly-empty map of additional services to provide</dd>
1030 <dt><span class="throwsLabel">Throws:</span></dt>
1031 <dd><code><a href="../../../../java.base/java/lang/IllegalArgumentException.html" title="class in java.lang">IllegalArgumentException</a></code> - If <code>extraExports</code> or <code>extraOpens</code> contains a key
1032 that is not a package in the module; if <code>extraExports</code> or
1033 <code>extraOpens</code> maps a key to an empty set; if a value in the
1034 <code>extraProvides</code> map contains a service provider type that
1035 is not a member of the module or an implementation of the service;
1036 or <code>extraProvides</code> maps a key to an empty list</dd>
1037 <dd><code><a href="UnmodifiableModuleException.html" title="class in java.lang.instrument">UnmodifiableModuleException</a></code> - if the module cannot be modified</dd>
1038 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - if any of the arguments are <code>null</code> or
1039 any of the Sets or Maps contains a <code>null</code> key or value</dd>
1040 <dt><span class="simpleTagLabel">Since:</span></dt>
1041 <dd>9</dd>
1042 <dt><span class="seeLabel">See Also:</span></dt>
1043 <dd><a href="#isModifiableModule(java.lang.Module)"><code>isModifiableModule(Module)</code></a></dd>
1044 </dl>
1045 </section>
1046 </li>
1047 <li class="blockList">
1048 <section class="detail">
1049 <h3><a id="isModifiableModule(java.lang.Module)">isModifiableModule</a></h3>
1050 <div class="memberSignature"><span class="returnType">boolean</span> <span class="memberName">isModifiableModule</span>(<span class="arguments"><a href="../../../../java.base/java/lang/Module.html" title="class in java.lang">Module</a> module)</span></div>
1051 <div class="block">Tests whether a module can be modified with <a href="#redefineModule(java.lang.Module,java.util.Set,java.util.Map,java.util.Map,java.util.Set,java.util.Map)"><code>redefineModule</code></a>. If a module is modifiable then this method returns
1052 <code>true</code>. If a module is not modifiable then this method returns
1053 <code>false</code>. This method always returns <code>true</code> when the module
1054 is an unnamed module (as redefining an unnamed module is a no-op).</div>
1055 <dl>
1056 <dt><span class="paramLabel">Parameters:</span></dt>
1057 <dd><code>module</code> - the module to test if it can be modified</dd>
1058 <dt><span class="returnLabel">Returns:</span></dt>
1059 <dd><code>true</code> if the module is modifiable, otherwise <code>false</code></dd>
1060 <dt><span class="throwsLabel">Throws:</span></dt>
1061 <dd><code><a href="../../../../java.base/java/lang/NullPointerException.html" title="class in java.lang">NullPointerException</a></code> - if the module is <code>null</code></dd>
1062 <dt><span class="simpleTagLabel">Since:</span></dt>
1063 <dd>9</dd>
1064 </dl>
1065 </section>
1066 </li>
1067 </ul>
1068 </section>
1069 </li>
1070 </ul>
1071 </section>
1072 </div>
1073 <!-- ========= END OF CLASS DATA ========= -->
1074 </main>
1075 <footer role="contentinfo">
1076 <nav role="navigation">
1077 <!-- ======= START OF BOTTOM NAVBAR ====== -->
1078 <div class="bottomNav"><a id="navbar.bottom">
1079 <!-- -->
1080 </a>
1081 <div class="skipNav"><a href="#skip.navbar.bottom" title="Skip navigation links">Skip navigation links</a></div>
1082 <a id="navbar.bottom.firstrow">
1083 <!-- -->
1084 </a>
1085 <ul class="navList" title="Navigation">
1086 <li><a href="../../../../index.html">Overview</a></li>
1087 <li><a href="../../../module-summary.html">Module</a></li>
1088 <li><a href="package-summary.html">Package</a></li>
1089 <li class="navBarCell1Rev">Class</li>
1090 <li><a href="class-use/Instrumentation.html">Use</a></li>
1091 <li><a href="package-tree.html">Tree</a></li>
1092 <li><a href="../../../../deprecated-list.html">Deprecated</a></li>
1093 <li><a href="../../../../index-files/index-1.html">Index</a></li>
1094 <li><a href="../../../../help-doc.html">Help</a></li>
1095 </ul>
1096 <div class="aboutLanguage"><div style="margin-top: 9px;"><strong>Java SE 14 & JDK 14</strong> <br><strong>DRAFT 14-internal+0-2019-12-04-2218569.hseigel.bug8235360</strong></div></div>
1097 </div>
1098 <div class="subNav">
1099 <div>
1100 <ul class="subNavList">
1101 <li>Summary: </li>
1102 <li>Nested | </li>
1103 <li>Field | </li>
1104 <li>Constr | </li>
1105 <li><a href="#method.summary">Method</a></li>
1106 </ul>
1107 <ul class="subNavList">
1108 <li>Detail: </li>
1109 <li>Field | </li>
1110 <li>Constr | </li>
1111 <li><a href="#method.detail">Method</a></li>
1112 </ul>
1113 </div>
1114 </div>
1115 <a id="skip.navbar.bottom">
1116 <!-- -->
1117 </a>
1118 <!-- ======== END OF BOTTOM NAVBAR ======= -->
1119 </nav>
1120 <p class="legalCopy"><small><a href="https://bugreport.java.com/bugreport/">Report a bug or suggest an enhancement</a><br> For further API reference and developer documentation see the <a href="https://docs.oracle.com/pls/topic/lookup?ctx=javase14&id=homepage" target="_blank">Java SE Documentation</a>, which contains more detailed, developer-targeted descriptions with conceptual overviews, definitions of terms, workarounds, and working code examples.<br> Java is a trademark or registered trademark of Oracle and/or its affiliates in the US and other countries.<br> <a href="../../../../../legal/copyright.html">Copyright</a> © 1993, 2019, Oracle and/or its affiliates, 500 Oracle Parkway, Redwood Shores, CA 94065 USA.<br>All rights reserved. Use is subject to <a href="https://www.oracle.com/technetwork/java/javase/terms/license/java14speclicense.html">license terms</a> and the <a href="https://www.oracle.com/technetwork/java/redist-137594.html">documentation redistribution policy</a>. <br><strong>DRAFT 14-internal+0-2019-12-04-2218569.hseigel.bug8235360</strong> <!-- Version 14-internal+0-2019-12-04-2218569.hseigel.bug8235360 --></small></p>
1121 </footer>
1122 </div>
1123 </div>
1124 </body>
1125 </html>