author | rriggs |
Sat, 01 Mar 2014 11:57:57 -0500 | |
changeset 23040 | 0cb50d5761df |
parent 20754 | 3d7b2fafc34b |
permissions | -rw-r--r-- |
2 | 1 |
/* |
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
2 |
* Copyright (c) 2003, 2013, Oracle and/or its affiliates. All rights reserved. |
2 | 3 |
* DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. |
4 |
* |
|
5 |
* This code is free software; you can redistribute it and/or modify it |
|
6 |
* under the terms of the GNU General Public License version 2 only, as |
|
5506 | 7 |
* published by the Free Software Foundation. Oracle designates this |
2 | 8 |
* particular file as subject to the "Classpath" exception as provided |
5506 | 9 |
* by Oracle in the LICENSE file that accompanied this code. |
2 | 10 |
* |
11 |
* This code is distributed in the hope that it will be useful, but WITHOUT |
|
12 |
* ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or |
|
13 |
* FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License |
|
14 |
* version 2 for more details (a copy is included in the LICENSE file that |
|
15 |
* accompanied this code). |
|
16 |
* |
|
17 |
* You should have received a copy of the GNU General Public License version |
|
18 |
* 2 along with this work; if not, write to the Free Software Foundation, |
|
19 |
* Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. |
|
20 |
* |
|
5506 | 21 |
* Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA |
22 |
* or visit www.oracle.com if you need additional information or have any |
|
23 |
* questions. |
|
2 | 24 |
*/ |
25 |
||
26 |
package java.lang.instrument; |
|
27 |
||
28 |
import java.io.File; |
|
29 |
import java.io.IOException; |
|
30 |
import java.util.jar.JarFile; |
|
31 |
||
32 |
/* |
|
33 |
* Copyright 2003 Wily Technology, Inc. |
|
34 |
*/ |
|
35 |
||
36 |
/** |
|
37 |
* This class provides services needed to instrument Java |
|
38 |
* programming language code. |
|
39 |
* Instrumentation is the addition of byte-codes to methods for the |
|
40 |
* purpose of gathering data to be utilized by tools. |
|
41 |
* Since the changes are purely additive, these tools do not modify |
|
42 |
* application state or behavior. |
|
43 |
* Examples of such benign tools include monitoring agents, profilers, |
|
44 |
* coverage analyzers, and event loggers. |
|
45 |
* |
|
46 |
* <P> |
|
47 |
* There are two ways to obtain an instance of the |
|
48 |
* <code>Instrumentation</code> interface: |
|
49 |
* |
|
50 |
* <ol> |
|
51 |
* <li><p> When a JVM is launched in a way that indicates an agent |
|
52 |
* class. In that case an <code>Instrumentation</code> instance |
|
53 |
* is passed to the <code>premain</code> method of the agent class. |
|
54 |
* </p></li> |
|
55 |
* <li><p> When a JVM provides a mechanism to start agents sometime |
|
56 |
* after the JVM is launched. In that case an <code>Instrumentation</code> |
|
57 |
* instance is passed to the <code>agentmain</code> method of the |
|
58 |
* agent code. </p> </li> |
|
59 |
* </ol> |
|
60 |
* <p> |
|
61 |
* These mechanisms are described in the |
|
62 |
* {@linkplain java.lang.instrument package specification}. |
|
63 |
* <p> |
|
64 |
* Once an agent acquires an <code>Instrumentation</code> instance, |
|
65 |
* the agent may call methods on the instance at any time. |
|
66 |
* |
|
67 |
* @since 1.5 |
|
68 |
*/ |
|
69 |
public interface Instrumentation { |
|
70 |
/** |
|
71 |
* Registers the supplied transformer. All future class definitions |
|
72 |
* will be seen by the transformer, except definitions of classes upon which any |
|
73 |
* registered transformer is dependent. |
|
74 |
* The transformer is called when classes are loaded, when they are |
|
75 |
* {@linkplain #redefineClasses redefined}. and if <code>canRetransform</code> is true, |
|
76 |
* when they are {@linkplain #retransformClasses retransformed}. |
|
77 |
* See {@link java.lang.instrument.ClassFileTransformer#transform |
|
78 |
* ClassFileTransformer.transform} for the order |
|
79 |
* of transform calls. |
|
80 |
* If a transformer throws |
|
81 |
* an exception during execution, the JVM will still call the other registered |
|
82 |
* transformers in order. The same transformer may be added more than once, |
|
83 |
* but it is strongly discouraged -- avoid this by creating a new instance of |
|
3495
6b2a376f365c
6870298: 4/4 fix minor typos in java/lang/instrument/Instrumentation.java
dcubed
parents:
715
diff
changeset
|
84 |
* transformer class. |
2 | 85 |
* <P> |
86 |
* This method is intended for use in instrumentation, as described in the |
|
87 |
* {@linkplain Instrumentation class specification}. |
|
88 |
* |
|
89 |
* @param transformer the transformer to register |
|
90 |
* @param canRetransform can this transformer's transformations be retransformed |
|
91 |
* @throws java.lang.NullPointerException if passed a <code>null</code> transformer |
|
92 |
* @throws java.lang.UnsupportedOperationException if <code>canRetransform</code> |
|
93 |
* is true and the current configuration of the JVM does not allow |
|
94 |
* retransformation ({@link #isRetransformClassesSupported} is false) |
|
95 |
* @since 1.6 |
|
96 |
*/ |
|
97 |
void |
|
98 |
addTransformer(ClassFileTransformer transformer, boolean canRetransform); |
|
99 |
||
100 |
/** |
|
101 |
* Registers the supplied transformer. |
|
102 |
* <P> |
|
103 |
* Same as <code>addTransformer(transformer, false)</code>. |
|
104 |
* |
|
105 |
* @param transformer the transformer to register |
|
106 |
* @throws java.lang.NullPointerException if passed a <code>null</code> transformer |
|
107 |
* @see #addTransformer(ClassFileTransformer,boolean) |
|
108 |
*/ |
|
109 |
void |
|
110 |
addTransformer(ClassFileTransformer transformer); |
|
111 |
||
112 |
/** |
|
113 |
* Unregisters the supplied transformer. Future class definitions will |
|
114 |
* not be shown to the transformer. Removes the most-recently-added matching |
|
115 |
* instance of the transformer. Due to the multi-threaded nature of |
|
116 |
* class loading, it is possible for a transformer to receive calls |
|
117 |
* after it has been removed. Transformers should be written defensively |
|
118 |
* to expect this situation. |
|
119 |
* |
|
120 |
* @param transformer the transformer to unregister |
|
121 |
* @return true if the transformer was found and removed, false if the |
|
122 |
* transformer was not found |
|
123 |
* @throws java.lang.NullPointerException if passed a <code>null</code> transformer |
|
124 |
*/ |
|
125 |
boolean |
|
126 |
removeTransformer(ClassFileTransformer transformer); |
|
127 |
||
128 |
/** |
|
129 |
* Returns whether or not the current JVM configuration supports retransformation |
|
130 |
* of classes. |
|
131 |
* The ability to retransform an already loaded class is an optional capability |
|
132 |
* of a JVM. |
|
133 |
* Retransformation will only be supported if the |
|
134 |
* <code>Can-Retransform-Classes</code> manifest attribute is set to |
|
135 |
* <code>true</code> in the agent JAR file (as described in the |
|
136 |
* {@linkplain java.lang.instrument package specification}) and the JVM supports |
|
137 |
* this capability. |
|
138 |
* During a single instantiation of a single JVM, multiple calls to this |
|
139 |
* method will always return the same answer. |
|
140 |
* @return true if the current JVM configuration supports retransformation of |
|
141 |
* classes, false if not. |
|
142 |
* @see #retransformClasses |
|
143 |
* @since 1.6 |
|
144 |
*/ |
|
145 |
boolean |
|
146 |
isRetransformClassesSupported(); |
|
147 |
||
148 |
/** |
|
149 |
* Retransform the supplied set of classes. |
|
150 |
* |
|
151 |
* <P> |
|
152 |
* This function facilitates the instrumentation |
|
153 |
* of already loaded classes. |
|
154 |
* When classes are initially loaded or when they are |
|
155 |
* {@linkplain #redefineClasses redefined}, |
|
156 |
* the initial class file bytes can be transformed with the |
|
157 |
* {@link java.lang.instrument.ClassFileTransformer ClassFileTransformer}. |
|
158 |
* This function reruns the transformation process |
|
159 |
* (whether or not a transformation has previously occurred). |
|
160 |
* This retransformation follows these steps: |
|
161 |
* <ul> |
|
162 |
* <li>starting from the initial class file bytes |
|
163 |
* </li> |
|
164 |
* <li>for each transformer that was added with <code>canRetransform</code> |
|
165 |
* false, the bytes returned by |
|
166 |
* {@link java.lang.instrument.ClassFileTransformer#transform transform} |
|
167 |
* during the last class load or redefine are |
|
168 |
* reused as the output of the transformation; note that this is |
|
169 |
* equivalent to reapplying the previous transformation, unaltered; |
|
170 |
* except that |
|
171 |
* {@link java.lang.instrument.ClassFileTransformer#transform transform} |
|
172 |
* is not called |
|
173 |
* </li> |
|
174 |
* <li>for each transformer that was added with <code>canRetransform</code> |
|
175 |
* true, the |
|
176 |
* {@link java.lang.instrument.ClassFileTransformer#transform transform} |
|
177 |
* method is called in these transformers |
|
178 |
* </li> |
|
179 |
* <li>the transformed class file bytes are installed as the new |
|
180 |
* definition of the class |
|
181 |
* </li> |
|
182 |
* </ul> |
|
183 |
* <P> |
|
184 |
* |
|
185 |
* The order of transformation is described in the |
|
3495
6b2a376f365c
6870298: 4/4 fix minor typos in java/lang/instrument/Instrumentation.java
dcubed
parents:
715
diff
changeset
|
186 |
* {@link java.lang.instrument.ClassFileTransformer#transform transform} method. |
2 | 187 |
* This same order is used in the automatic reapplication of retransformation |
188 |
* incapable transforms. |
|
189 |
* <P> |
|
190 |
* |
|
191 |
* The initial class file bytes represent the bytes passed to |
|
192 |
* {@link java.lang.ClassLoader#defineClass ClassLoader.defineClass} or |
|
193 |
* {@link #redefineClasses redefineClasses} |
|
194 |
* (before any transformations |
|
195 |
* were applied), however they might not exactly match them. |
|
196 |
* The constant pool might not have the same layout or contents. |
|
197 |
* The constant pool may have more or fewer entries. |
|
198 |
* Constant pool entries may be in a different order; however, |
|
199 |
* constant pool indices in the bytecodes of methods will correspond. |
|
200 |
* Some attributes may not be present. |
|
201 |
* Where order is not meaningful, for example the order of methods, |
|
202 |
* order might not be preserved. |
|
203 |
* |
|
204 |
* <P> |
|
205 |
* This method operates on |
|
206 |
* a set in order to allow interdependent changes to more than one class at the same time |
|
207 |
* (a retransformation of class A can require a retransformation of class B). |
|
208 |
* |
|
209 |
* <P> |
|
210 |
* If a retransformed method has active stack frames, those active frames continue to |
|
211 |
* run the bytecodes of the original method. |
|
212 |
* The retransformed method will be used on new invokes. |
|
213 |
* |
|
214 |
* <P> |
|
215 |
* This method does not cause any initialization except that which would occur |
|
216 |
* under the customary JVM semantics. In other words, redefining a class |
|
217 |
* does not cause its initializers to be run. The values of static variables |
|
218 |
* will remain as they were prior to the call. |
|
219 |
* |
|
220 |
* <P> |
|
221 |
* Instances of the retransformed class are not affected. |
|
222 |
* |
|
223 |
* <P> |
|
224 |
* The retransformation may change method bodies, the constant pool and attributes. |
|
225 |
* The retransformation must not add, remove or rename fields or methods, change the |
|
226 |
* signatures of methods, or change inheritance. These restrictions maybe be |
|
227 |
* lifted in future versions. The class file bytes are not checked, verified and installed |
|
228 |
* until after the transformations have been applied, if the resultant bytes are in |
|
229 |
* error this method will throw an exception. |
|
230 |
* |
|
231 |
* <P> |
|
232 |
* If this method throws an exception, no classes have been retransformed. |
|
233 |
* <P> |
|
234 |
* This method is intended for use in instrumentation, as described in the |
|
235 |
* {@linkplain Instrumentation class specification}. |
|
236 |
* |
|
237 |
* @param classes array of classes to retransform; |
|
238 |
* a zero-length array is allowed, in this case, this method does nothing |
|
239 |
* @throws java.lang.instrument.UnmodifiableClassException if a specified class cannot be modified |
|
240 |
* ({@link #isModifiableClass} would return <code>false</code>) |
|
241 |
* @throws java.lang.UnsupportedOperationException if the current configuration of the JVM does not allow |
|
242 |
* retransformation ({@link #isRetransformClassesSupported} is false) or the retransformation attempted |
|
243 |
* to make unsupported changes |
|
244 |
* @throws java.lang.ClassFormatError if the data did not contain a valid class |
|
245 |
* @throws java.lang.NoClassDefFoundError if the name in the class file is not equal to the name of the class |
|
246 |
* @throws java.lang.UnsupportedClassVersionError if the class file version numbers are not supported |
|
247 |
* @throws java.lang.ClassCircularityError if the new classes contain a circularity |
|
248 |
* @throws java.lang.LinkageError if a linkage error occurs |
|
249 |
* @throws java.lang.NullPointerException if the supplied classes array or any of its components |
|
250 |
* is <code>null</code>. |
|
251 |
* |
|
252 |
* @see #isRetransformClassesSupported |
|
253 |
* @see #addTransformer |
|
254 |
* @see java.lang.instrument.ClassFileTransformer |
|
255 |
* @since 1.6 |
|
256 |
*/ |
|
257 |
void |
|
258 |
retransformClasses(Class<?>... classes) throws UnmodifiableClassException; |
|
259 |
||
260 |
/** |
|
261 |
* Returns whether or not the current JVM configuration supports redefinition |
|
262 |
* of classes. |
|
263 |
* The ability to redefine an already loaded class is an optional capability |
|
264 |
* of a JVM. |
|
265 |
* Redefinition will only be supported if the |
|
266 |
* <code>Can-Redefine-Classes</code> manifest attribute is set to |
|
267 |
* <code>true</code> in the agent JAR file (as described in the |
|
268 |
* {@linkplain java.lang.instrument package specification}) and the JVM supports |
|
269 |
* this capability. |
|
270 |
* During a single instantiation of a single JVM, multiple calls to this |
|
271 |
* method will always return the same answer. |
|
272 |
* @return true if the current JVM configuration supports redefinition of classes, |
|
273 |
* false if not. |
|
274 |
* @see #redefineClasses |
|
275 |
*/ |
|
276 |
boolean |
|
277 |
isRedefineClassesSupported(); |
|
278 |
||
279 |
/** |
|
280 |
* Redefine the supplied set of classes using the supplied class files. |
|
281 |
* |
|
282 |
* <P> |
|
283 |
* This method is used to replace the definition of a class without reference |
|
284 |
* to the existing class file bytes, as one might do when recompiling from source |
|
285 |
* for fix-and-continue debugging. |
|
286 |
* Where the existing class file bytes are to be transformed (for |
|
287 |
* example in bytecode instrumentation) |
|
288 |
* {@link #retransformClasses retransformClasses} |
|
289 |
* should be used. |
|
290 |
* |
|
291 |
* <P> |
|
292 |
* This method operates on |
|
293 |
* a set in order to allow interdependent changes to more than one class at the same time |
|
294 |
* (a redefinition of class A can require a redefinition of class B). |
|
295 |
* |
|
296 |
* <P> |
|
297 |
* If a redefined method has active stack frames, those active frames continue to |
|
298 |
* run the bytecodes of the original method. |
|
299 |
* The redefined method will be used on new invokes. |
|
300 |
* |
|
301 |
* <P> |
|
302 |
* This method does not cause any initialization except that which would occur |
|
303 |
* under the customary JVM semantics. In other words, redefining a class |
|
304 |
* does not cause its initializers to be run. The values of static variables |
|
305 |
* will remain as they were prior to the call. |
|
306 |
* |
|
307 |
* <P> |
|
308 |
* Instances of the redefined class are not affected. |
|
309 |
* |
|
310 |
* <P> |
|
311 |
* The redefinition may change method bodies, the constant pool and attributes. |
|
312 |
* The redefinition must not add, remove or rename fields or methods, change the |
|
313 |
* signatures of methods, or change inheritance. These restrictions maybe be |
|
314 |
* lifted in future versions. The class file bytes are not checked, verified and installed |
|
315 |
* until after the transformations have been applied, if the resultant bytes are in |
|
316 |
* error this method will throw an exception. |
|
317 |
* |
|
318 |
* <P> |
|
319 |
* If this method throws an exception, no classes have been redefined. |
|
320 |
* <P> |
|
321 |
* This method is intended for use in instrumentation, as described in the |
|
322 |
* {@linkplain Instrumentation class specification}. |
|
323 |
* |
|
324 |
* @param definitions array of classes to redefine with corresponding definitions; |
|
325 |
* a zero-length array is allowed, in this case, this method does nothing |
|
326 |
* @throws java.lang.instrument.UnmodifiableClassException if a specified class cannot be modified |
|
327 |
* ({@link #isModifiableClass} would return <code>false</code>) |
|
328 |
* @throws java.lang.UnsupportedOperationException if the current configuration of the JVM does not allow |
|
329 |
* redefinition ({@link #isRedefineClassesSupported} is false) or the redefinition attempted |
|
330 |
* to make unsupported changes |
|
331 |
* @throws java.lang.ClassFormatError if the data did not contain a valid class |
|
332 |
* @throws java.lang.NoClassDefFoundError if the name in the class file is not equal to the name of the class |
|
333 |
* @throws java.lang.UnsupportedClassVersionError if the class file version numbers are not supported |
|
334 |
* @throws java.lang.ClassCircularityError if the new classes contain a circularity |
|
335 |
* @throws java.lang.LinkageError if a linkage error occurs |
|
336 |
* @throws java.lang.NullPointerException if the supplied definitions array or any of its components |
|
337 |
* is <code>null</code> |
|
338 |
* @throws java.lang.ClassNotFoundException Can never be thrown (present for compatibility reasons only) |
|
339 |
* |
|
340 |
* @see #isRedefineClassesSupported |
|
341 |
* @see #addTransformer |
|
342 |
* @see java.lang.instrument.ClassFileTransformer |
|
343 |
*/ |
|
344 |
void |
|
345 |
redefineClasses(ClassDefinition... definitions) |
|
346 |
throws ClassNotFoundException, UnmodifiableClassException; |
|
347 |
||
348 |
||
349 |
/** |
|
350 |
* Determines whether a class is modifiable by |
|
351 |
* {@linkplain #retransformClasses retransformation} |
|
352 |
* or {@linkplain #redefineClasses redefinition}. |
|
353 |
* If a class is modifiable then this method returns <code>true</code>. |
|
354 |
* If a class is not modifiable then this method returns <code>false</code>. |
|
355 |
* <P> |
|
356 |
* For a class to be retransformed, {@link #isRetransformClassesSupported} must also be true. |
|
357 |
* But the value of <code>isRetransformClassesSupported()</code> does not influence the value |
|
358 |
* returned by this function. |
|
359 |
* For a class to be redefined, {@link #isRedefineClassesSupported} must also be true. |
|
360 |
* But the value of <code>isRedefineClassesSupported()</code> does not influence the value |
|
361 |
* returned by this function. |
|
362 |
* <P> |
|
363 |
* Primitive classes (for example, <code>java.lang.Integer.TYPE</code>) |
|
364 |
* and array classes are never modifiable. |
|
365 |
* |
|
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
366 |
* @param theClass the class to check for being modifiable |
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
367 |
* @return whether or not the argument class is modifiable |
2 | 368 |
* @throws java.lang.NullPointerException if the specified class is <code>null</code>. |
369 |
* |
|
370 |
* @see #retransformClasses |
|
371 |
* @see #isRetransformClassesSupported |
|
372 |
* @see #redefineClasses |
|
373 |
* @see #isRedefineClassesSupported |
|
374 |
* @since 1.6 |
|
375 |
*/ |
|
376 |
boolean |
|
377 |
isModifiableClass(Class<?> theClass); |
|
378 |
||
379 |
/** |
|
380 |
* Returns an array of all classes currently loaded by the JVM. |
|
381 |
* |
|
382 |
* @return an array containing all the classes loaded by the JVM, zero-length if there are none |
|
383 |
*/ |
|
20754
3d7b2fafc34b
8025967: addition of -Werror broke the old build
valeriep
parents:
18589
diff
changeset
|
384 |
@SuppressWarnings("rawtypes") |
2 | 385 |
Class[] |
386 |
getAllLoadedClasses(); |
|
387 |
||
388 |
/** |
|
389 |
* Returns an array of all classes for which <code>loader</code> is an initiating loader. |
|
390 |
* If the supplied loader is <code>null</code>, classes initiated by the bootstrap class |
|
391 |
* loader are returned. |
|
392 |
* |
|
393 |
* @param loader the loader whose initiated class list will be returned |
|
394 |
* @return an array containing all the classes for which loader is an initiating loader, |
|
395 |
* zero-length if there are none |
|
396 |
*/ |
|
20754
3d7b2fafc34b
8025967: addition of -Werror broke the old build
valeriep
parents:
18589
diff
changeset
|
397 |
@SuppressWarnings("rawtypes") |
2 | 398 |
Class[] |
399 |
getInitiatedClasses(ClassLoader loader); |
|
400 |
||
401 |
/** |
|
402 |
* Returns an implementation-specific approximation of the amount of storage consumed by |
|
403 |
* the specified object. The result may include some or all of the object's overhead, |
|
404 |
* and thus is useful for comparison within an implementation but not between implementations. |
|
405 |
* |
|
406 |
* The estimate may change during a single invocation of the JVM. |
|
407 |
* |
|
408 |
* @param objectToSize the object to size |
|
409 |
* @return an implementation-specific approximation of the amount of storage consumed by the specified object |
|
410 |
* @throws java.lang.NullPointerException if the supplied Object is <code>null</code>. |
|
411 |
*/ |
|
412 |
long |
|
413 |
getObjectSize(Object objectToSize); |
|
414 |
||
415 |
||
416 |
/** |
|
417 |
* Specifies a JAR file with instrumentation classes to be defined by the |
|
418 |
* bootstrap class loader. |
|
419 |
* |
|
420 |
* <p> When the virtual machine's built-in class loader, known as the "bootstrap |
|
421 |
* class loader", unsuccessfully searches for a class, the entries in the {@link |
|
422 |
* java.util.jar.JarFile JAR file} will be searched as well. |
|
423 |
* |
|
424 |
* <p> This method may be used multiple times to add multiple JAR files to be |
|
425 |
* searched in the order that this method was invoked. |
|
426 |
* |
|
427 |
* <p> The agent should take care to ensure that the JAR does not contain any |
|
428 |
* classes or resources other than those to be defined by the bootstrap |
|
429 |
* class loader for the purpose of instrumentation. |
|
430 |
* Failure to observe this warning could result in unexpected |
|
3495
6b2a376f365c
6870298: 4/4 fix minor typos in java/lang/instrument/Instrumentation.java
dcubed
parents:
715
diff
changeset
|
431 |
* behavior that is difficult to diagnose. For example, suppose there is a |
2 | 432 |
* loader L, and L's parent for delegation is the bootstrap class loader. |
433 |
* Furthermore, a method in class C, a class defined by L, makes reference to |
|
434 |
* a non-public accessor class C$1. If the JAR file contains a class C$1 then |
|
435 |
* the delegation to the bootstrap class loader will cause C$1 to be defined |
|
436 |
* by the bootstrap class loader. In this example an <code>IllegalAccessError</code> |
|
437 |
* will be thrown that may cause the application to fail. One approach to |
|
438 |
* avoiding these types of issues, is to use a unique package name for the |
|
439 |
* instrumentation classes. |
|
440 |
* |
|
9266
121fb370f179
7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks
jjh
parents:
5506
diff
changeset
|
441 |
* <p> |
121fb370f179
7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks
jjh
parents:
5506
diff
changeset
|
442 |
* <cite>The Java™ Virtual Machine Specification</cite> |
121fb370f179
7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks
jjh
parents:
5506
diff
changeset
|
443 |
* specifies that a subsequent attempt to resolve a symbolic |
2 | 444 |
* reference that the Java virtual machine has previously unsuccessfully attempted |
445 |
* to resolve always fails with the same error that was thrown as a result of the |
|
446 |
* initial resolution attempt. Consequently, if the JAR file contains an entry |
|
447 |
* that corresponds to a class for which the Java virtual machine has |
|
448 |
* unsuccessfully attempted to resolve a reference, then subsequent attempts to |
|
449 |
* resolve that reference will fail with the same error as the initial attempt. |
|
450 |
* |
|
451 |
* @param jarfile |
|
452 |
* The JAR file to be searched when the bootstrap class loader |
|
453 |
* unsuccessfully searches for a class. |
|
454 |
* |
|
455 |
* @throws NullPointerException |
|
456 |
* If <code>jarfile</code> is <code>null</code>. |
|
457 |
* |
|
458 |
* @see #appendToSystemClassLoaderSearch |
|
459 |
* @see java.lang.ClassLoader |
|
460 |
* @see java.util.jar.JarFile |
|
461 |
* |
|
462 |
* @since 1.6 |
|
463 |
*/ |
|
464 |
void |
|
465 |
appendToBootstrapClassLoaderSearch(JarFile jarfile); |
|
466 |
||
467 |
/** |
|
468 |
* Specifies a JAR file with instrumentation classes to be defined by the |
|
469 |
* system class loader. |
|
470 |
* |
|
471 |
* When the system class loader for delegation (see |
|
472 |
* {@link java.lang.ClassLoader#getSystemClassLoader getSystemClassLoader()}) |
|
473 |
* unsuccessfully searches for a class, the entries in the {@link |
|
474 |
* java.util.jar.JarFile JarFile} will be searched as well. |
|
475 |
* |
|
476 |
* <p> This method may be used multiple times to add multiple JAR files to be |
|
477 |
* searched in the order that this method was invoked. |
|
478 |
* |
|
479 |
* <p> The agent should take care to ensure that the JAR does not contain any |
|
480 |
* classes or resources other than those to be defined by the system class |
|
481 |
* loader for the purpose of instrumentation. |
|
482 |
* Failure to observe this warning could result in unexpected |
|
3495
6b2a376f365c
6870298: 4/4 fix minor typos in java/lang/instrument/Instrumentation.java
dcubed
parents:
715
diff
changeset
|
483 |
* behavior that is difficult to diagnose (see |
2 | 484 |
* {@link #appendToBootstrapClassLoaderSearch |
3495
6b2a376f365c
6870298: 4/4 fix minor typos in java/lang/instrument/Instrumentation.java
dcubed
parents:
715
diff
changeset
|
485 |
* appendToBootstrapClassLoaderSearch}). |
2 | 486 |
* |
487 |
* <p> The system class loader supports adding a JAR file to be searched if |
|
488 |
* it implements a method named <code>appendToClassPathForInstrumentation</code> |
|
489 |
* which takes a single parameter of type <code>java.lang.String</code>. The |
|
490 |
* method is not required to have <code>public</code> access. The name of |
|
491 |
* the JAR file is obtained by invoking the {@link java.util.zip.ZipFile#getName |
|
492 |
* getName()} method on the <code>jarfile</code> and this is provided as the |
|
3495
6b2a376f365c
6870298: 4/4 fix minor typos in java/lang/instrument/Instrumentation.java
dcubed
parents:
715
diff
changeset
|
493 |
* parameter to the <code>appendToClassPathForInstrumentation</code> method. |
2 | 494 |
* |
9266
121fb370f179
7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks
jjh
parents:
5506
diff
changeset
|
495 |
* <p> |
121fb370f179
7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks
jjh
parents:
5506
diff
changeset
|
496 |
* <cite>The Java™ Virtual Machine Specification</cite> |
121fb370f179
7032960: API files in java.awt need to be updated for references to JVM Spec with editions/hyperlinks
jjh
parents:
5506
diff
changeset
|
497 |
* specifies that a subsequent attempt to resolve a symbolic |
2 | 498 |
* reference that the Java virtual machine has previously unsuccessfully attempted |
499 |
* to resolve always fails with the same error that was thrown as a result of the |
|
500 |
* initial resolution attempt. Consequently, if the JAR file contains an entry |
|
501 |
* that corresponds to a class for which the Java virtual machine has |
|
502 |
* unsuccessfully attempted to resolve a reference, then subsequent attempts to |
|
503 |
* resolve that reference will fail with the same error as the initial attempt. |
|
504 |
* |
|
505 |
* <p> This method does not change the value of <code>java.class.path</code> |
|
506 |
* {@link java.lang.System#getProperties system property}. |
|
507 |
* |
|
508 |
* @param jarfile |
|
509 |
* The JAR file to be searched when the system class loader |
|
510 |
* unsuccessfully searches for a class. |
|
511 |
* |
|
512 |
* @throws UnsupportedOperationException |
|
513 |
* If the system class loader does not support appending a |
|
514 |
* a JAR file to be searched. |
|
515 |
* |
|
516 |
* @throws NullPointerException |
|
517 |
* If <code>jarfile</code> is <code>null</code>. |
|
518 |
* |
|
519 |
* @see #appendToBootstrapClassLoaderSearch |
|
520 |
* @see java.lang.ClassLoader#getSystemClassLoader |
|
521 |
* @see java.util.jar.JarFile |
|
522 |
* @since 1.6 |
|
523 |
*/ |
|
524 |
void |
|
525 |
appendToSystemClassLoaderSearch(JarFile jarfile); |
|
526 |
||
527 |
/** |
|
528 |
* Returns whether the current JVM configuration supports |
|
529 |
* {@linkplain #setNativeMethodPrefix(ClassFileTransformer,String) |
|
530 |
* setting a native method prefix}. |
|
531 |
* The ability to set a native method prefix is an optional |
|
532 |
* capability of a JVM. |
|
533 |
* Setting a native method prefix will only be supported if the |
|
534 |
* <code>Can-Set-Native-Method-Prefix</code> manifest attribute is set to |
|
535 |
* <code>true</code> in the agent JAR file (as described in the |
|
536 |
* {@linkplain java.lang.instrument package specification}) and the JVM supports |
|
537 |
* this capability. |
|
538 |
* During a single instantiation of a single JVM, multiple |
|
539 |
* calls to this method will always return the same answer. |
|
540 |
* @return true if the current JVM configuration supports |
|
541 |
* setting a native method prefix, false if not. |
|
542 |
* @see #setNativeMethodPrefix |
|
543 |
* @since 1.6 |
|
544 |
*/ |
|
545 |
boolean |
|
546 |
isNativeMethodPrefixSupported(); |
|
547 |
||
548 |
/** |
|
549 |
* This method modifies the failure handling of |
|
550 |
* native method resolution by allowing retry |
|
551 |
* with a prefix applied to the name. |
|
552 |
* When used with the |
|
553 |
* {@link java.lang.instrument.ClassFileTransformer ClassFileTransformer}, |
|
554 |
* it enables native methods to be |
|
555 |
* instrumented. |
|
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
556 |
* <p> |
2 | 557 |
* Since native methods cannot be directly instrumented |
558 |
* (they have no bytecodes), they must be wrapped with |
|
559 |
* a non-native method which can be instrumented. |
|
560 |
* For example, if we had: |
|
561 |
* <pre> |
|
562 |
* native boolean foo(int x);</pre> |
|
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
563 |
* <p> |
2 | 564 |
* We could transform the class file (with the |
565 |
* ClassFileTransformer during the initial definition |
|
566 |
* of the class) so that this becomes: |
|
567 |
* <pre> |
|
568 |
* boolean foo(int x) { |
|
569 |
* <i>... record entry to foo ...</i> |
|
570 |
* return wrapped_foo(x); |
|
571 |
* } |
|
572 |
* |
|
573 |
* native boolean wrapped_foo(int x);</pre> |
|
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
574 |
* <p> |
2 | 575 |
* Where <code>foo</code> becomes a wrapper for the actual native |
576 |
* method with the appended prefix "wrapped_". Note that |
|
577 |
* "wrapped_" would be a poor choice of prefix since it |
|
578 |
* might conceivably form the name of an existing method |
|
579 |
* thus something like "$$$MyAgentWrapped$$$_" would be |
|
580 |
* better but would make these examples less readable. |
|
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
581 |
* <p> |
2 | 582 |
* The wrapper will allow data to be collected on the native |
583 |
* method call, but now the problem becomes linking up the |
|
584 |
* wrapped method with the native implementation. |
|
585 |
* That is, the method <code>wrapped_foo</code> needs to be |
|
586 |
* resolved to the native implementation of <code>foo</code>, |
|
587 |
* which might be: |
|
588 |
* <pre> |
|
589 |
* Java_somePackage_someClass_foo(JNIEnv* env, jint x)</pre> |
|
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
590 |
* <p> |
2 | 591 |
* This function allows the prefix to be specified and the |
592 |
* proper resolution to occur. |
|
593 |
* Specifically, when the standard resolution fails, the |
|
594 |
* resolution is retried taking the prefix into consideration. |
|
595 |
* There are two ways that resolution occurs, explicit |
|
596 |
* resolution with the JNI function <code>RegisterNatives</code> |
|
597 |
* and the normal automatic resolution. For |
|
598 |
* <code>RegisterNatives</code>, the JVM will attempt this |
|
599 |
* association: |
|
18156 | 600 |
* <pre>{@code |
601 |
* method(foo) -> nativeImplementation(foo) |
|
602 |
* }</pre> |
|
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
603 |
* <p> |
2 | 604 |
* When this fails, the resolution will be retried with |
605 |
* the specified prefix prepended to the method name, |
|
606 |
* yielding the correct resolution: |
|
18156 | 607 |
* <pre>{@code |
608 |
* method(wrapped_foo) -> nativeImplementation(foo) |
|
609 |
* }</pre> |
|
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
610 |
* <p> |
2 | 611 |
* For automatic resolution, the JVM will attempt: |
18156 | 612 |
* <pre>{@code |
613 |
* method(wrapped_foo) -> nativeImplementation(wrapped_foo) |
|
614 |
* }</pre> |
|
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
615 |
* <p> |
2 | 616 |
* When this fails, the resolution will be retried with |
617 |
* the specified prefix deleted from the implementation name, |
|
618 |
* yielding the correct resolution: |
|
18156 | 619 |
* <pre>{@code |
620 |
* method(wrapped_foo) -> nativeImplementation(foo) |
|
621 |
* }</pre> |
|
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
622 |
* <p> |
2 | 623 |
* Note that since the prefix is only used when standard |
624 |
* resolution fails, native methods can be wrapped selectively. |
|
18589
8b03e152e2fe
8019527: Fix doclint issues in java.lang.instrument
darcy
parents:
18156
diff
changeset
|
625 |
* <p> |
2 | 626 |
* Since each <code>ClassFileTransformer</code> |
627 |
* can do its own transformation of the bytecodes, more |
|
628 |
* than one layer of wrappers may be applied. Thus each |
|
629 |
* transformer needs its own prefix. Since transformations |
|
630 |
* are applied in order, the prefixes, if applied, will |
|
631 |
* be applied in the same order |
|
632 |
* (see {@link #addTransformer(ClassFileTransformer,boolean) addTransformer}). |
|
633 |
* Thus if three transformers applied |
|
634 |
* wrappers, <code>foo</code> might become |
|
635 |
* <code>$trans3_$trans2_$trans1_foo</code>. But if, say, |
|
636 |
* the second transformer did not apply a wrapper to |
|
637 |
* <code>foo</code> it would be just |
|
638 |
* <code>$trans3_$trans1_foo</code>. To be able to |
|
639 |
* efficiently determine the sequence of prefixes, |
|
640 |
* an intermediate prefix is only applied if its non-native |
|
641 |
* wrapper exists. Thus, in the last example, even though |
|
642 |
* <code>$trans1_foo</code> is not a native method, the |
|
643 |
* <code>$trans1_</code> prefix is applied since |
|
644 |
* <code>$trans1_foo</code> exists. |
|
645 |
* |
|
646 |
* @param transformer |
|
647 |
* The ClassFileTransformer which wraps using this prefix. |
|
648 |
* @param prefix |
|
283
f141a78d9f2b
6655234: 4/4 j.l.i.: setNativeMethodPrefix does not document that prefix string can be null
dcubed
parents:
2
diff
changeset
|
649 |
* The prefix to apply to wrapped native methods when |
f141a78d9f2b
6655234: 4/4 j.l.i.: setNativeMethodPrefix does not document that prefix string can be null
dcubed
parents:
2
diff
changeset
|
650 |
* retrying a failed native method resolution. If prefix |
f141a78d9f2b
6655234: 4/4 j.l.i.: setNativeMethodPrefix does not document that prefix string can be null
dcubed
parents:
2
diff
changeset
|
651 |
* is either <code>null</code> or the empty string, then |
f141a78d9f2b
6655234: 4/4 j.l.i.: setNativeMethodPrefix does not document that prefix string can be null
dcubed
parents:
2
diff
changeset
|
652 |
* failed native method resolutions are not retried for |
f141a78d9f2b
6655234: 4/4 j.l.i.: setNativeMethodPrefix does not document that prefix string can be null
dcubed
parents:
2
diff
changeset
|
653 |
* this transformer. |
2 | 654 |
* @throws java.lang.NullPointerException if passed a <code>null</code> transformer. |
655 |
* @throws java.lang.UnsupportedOperationException if the current configuration of |
|
656 |
* the JVM does not allow setting a native method prefix |
|
657 |
* ({@link #isNativeMethodPrefixSupported} is false). |
|
658 |
* @throws java.lang.IllegalArgumentException if the transformer is not registered |
|
659 |
* (see {@link #addTransformer(ClassFileTransformer,boolean) addTransformer}). |
|
660 |
* |
|
661 |
* @since 1.6 |
|
662 |
*/ |
|
663 |
void |
|
664 |
setNativeMethodPrefix(ClassFileTransformer transformer, String prefix); |
|
665 |
} |