42 * VirtualMachine to load an agent into the target VM. For example, a profiler tool
43 * written in the Java Language might attach to a running application and load its
44 * profiler agent to profile the running application. </p>
45 *
46 * <p> A VirtualMachine is obtained by invoking the {@link #attach(String) attach} method
47 * with an identifier that identifies the target virtual machine. The identifier is
48 * implementation-dependent but is typically the process identifier (or pid) in
49 * environments where each Java virtual machine runs in its own operating system process.
50 * Alternatively, a <code>VirtualMachine</code> instance is obtained by invoking the
51 * {@link #attach(VirtualMachineDescriptor) attach} method with a {@link
52 * com.sun.tools.attach.VirtualMachineDescriptor VirtualMachineDescriptor} obtained
53 * from the list of virtual machine descriptors returned by the {@link #list list} method.
54 * Once a reference to a virtual machine is obtained, the {@link #loadAgent loadAgent},
55 * {@link #loadAgentLibrary loadAgentLibrary}, and {@link #loadAgentPath loadAgentPath}
56 * methods are used to load agents into target virtual machine. The {@link
57 * #loadAgent loadAgent} method is used to load agents that are written in the Java
58 * Language and deployed in a {@link java.util.jar.JarFile JAR file}. (See
59 * {@link java.lang.instrument} for a detailed description on how these agents
60 * are loaded and started). The {@link #loadAgentLibrary loadAgentLibrary} and
61 * {@link #loadAgentPath loadAgentPath} methods are used to load agents that
62 * are deployed in a dynamic library and make use of the <a
63 * href="../../../../../../../../technotes/guides/jvmti/index.html">JVM Tools
64 * Interface</a>. </p>
65 *
66 * <p> In addition to loading agents a VirtualMachine provides read access to the
67 * {@link java.lang.System#getProperties() system properties} in the target VM.
68 * This can be useful in some environments where properties such as
69 * <code>java.home</code>, <code>os.name</code>, or <code>os.arch</code> are
70 * used to construct the path to agent that will be loaded into the target VM.
71 *
72 * <p> The following example demonstrates how VirtualMachine may be used:</p>
73 *
74 * <pre>
75 *
76 * // attach to target VM
77 * VirtualMachine vm = VirtualMachine.attach("2177");
78 *
79 * // get system properties in target VM
80 * Properties props = vm.getSystemProperties();
81 *
82 * // construct path to management agent
281 */
282 public final AttachProvider provider() {
283 return provider;
284 }
285
286 /**
287 * Returns the identifier for this Java virtual machine.
288 *
289 * @return The identifier for this Java virtual machine.
290 */
291 public final String id() {
292 return id;
293 }
294
295 /**
296 * Loads an agent library.
297 *
298 * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
299 * TI</a> client is called an <i>agent</i>. It is developed in a native language.
300 * A JVM TI agent is deployed in a platform specific manner but it is typically the
301 * platform equivalent of a dynamic library. This method causes the given agent
302 * library to be loaded into the target VM (if not already loaded).
303 * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
304 * as specified in the
305 * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
306 * Interface</a> specification. Note that the <code>Agent_OnAttach</code>
307 * function is invoked even if the agent library was loaded prior to invoking
308 * this method.
309 *
310 * <p> The agent library provided is the name of the agent library. It is interpreted
311 * in the target virtual machine in an implementation-dependent manner. Typically an
312 * implementation will expand the library name into an operating system specific file
313 * name. For example, on UNIX systems, the name <tt>foo</tt> might be expanded to
314 * <tt>libfoo.so</tt>, and located using the search path specified by the
315 * <tt>LD_LIBRARY_PATH</tt> environment variable.</p>
316 *
317 * <p> If the <code>Agent_OnAttach</code> function in the agent library returns
318 * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
319 * thrown. The return value from the <code>Agent_OnAttach</code> can then be
320 * obtained by invoking the {@link
321 * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
322 * method on the exception. </p>
323 *
324 * @param agentLibrary
325 * The name of the agent library.
326 *
327 * @param options
328 * The options to provide to the <code>Agent_OnAttach</code>
329 * function (can be <code>null</code>).
330 *
331 * @throws AgentLoadException
332 * If the agent library does not exist, or cannot be loaded for
333 * another reason.
334 *
335 * @throws AgentInitializationException
336 * If the <code>Agent_OnAttach</code> function returns an error
337 *
338 * @throws IOException
339 * If an I/O error occurs
340 *
341 * @throws NullPointerException
342 * If <code>agentLibrary</code> is <code>null</code>.
343 *
344 * @see com.sun.tools.attach.AgentInitializationException#returnValue()
345 */
346 public abstract void loadAgentLibrary(String agentLibrary, String options)
347 throws AgentLoadException, AgentInitializationException, IOException;
348
349 /**
350 * Loads an agent library.
351 *
352 * <p> This convenience method works as if by invoking:
353 *
354 * <blockquote><tt>
355 * {@link #loadAgentLibrary(String, String) loadAgentLibrary}(agentLibrary, null);
356 * </tt></blockquote>
357 *
358 * @param agentLibrary
359 * The name of the agent library.
360 *
361 * @throws AgentLoadException
362 * If the agent library does not exist, or cannot be loaded for
363 * another reason.
364 *
365 * @throws AgentInitializationException
366 * If the <code>Agent_OnAttach</code> function returns an error
367 *
368 * @throws IOException
369 * If an I/O error occurs
370 *
371 * @throws NullPointerException
372 * If <code>agentLibrary</code> is <code>null</code>.
373 */
374 public void loadAgentLibrary(String agentLibrary)
375 throws AgentLoadException, AgentInitializationException, IOException
376 {
377 loadAgentLibrary(agentLibrary, null);
378 }
379
380 /**
381 * Load a native agent library by full pathname.
382 *
383 * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
384 * TI</a> client is called an <i>agent</i>. It is developed in a native language.
385 * A JVM TI agent is deployed in a platform specific manner but it is typically the
386 * platform equivalent of a dynamic library. This method causes the given agent
387 * library to be loaded into the target VM (if not already loaded).
388 * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
389 * as specified in the
390 * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
391 * Interface</a> specification. Note that the <code>Agent_OnAttach</code>
392 * function is invoked even if the agent library was loaded prior to invoking
393 * this method.
394 *
395 * <p> The agent library provided is the absolute path from which to load the
396 * agent library. Unlike {@link #loadAgentLibrary loadAgentLibrary}, the library name
397 * is not expanded in the target virtual machine. </p>
398 *
399 * <p> If the <code>Agent_OnAttach</code> function in the agent library returns
400 * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
401 * thrown. The return value from the <code>Agent_OnAttach</code> can then be
402 * obtained by invoking the {@link
403 * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
404 * method on the exception. </p>
405 *
406 * @param agentPath
407 * The full path of the agent library.
408 *
409 * @param options
410 * The options to provide to the <code>Agent_OnAttach</code>
411 * function (can be <code>null</code>).
412 *
413 * @throws AgentLoadException
414 * If the agent library does not exist, or cannot be loaded for
415 * another reason.
416 *
417 * @throws AgentInitializationException
418 * If the <code>Agent_OnAttach</code> function returns an error
419 *
420 * @throws IOException
421 * If an I/O error occurs
422 *
423 * @throws NullPointerException
424 * If <code>agentPath</code> is <code>null</code>.
425 *
426 * @see com.sun.tools.attach.AgentInitializationException#returnValue()
427 */
428 public abstract void loadAgentPath(String agentPath, String options)
429 throws AgentLoadException, AgentInitializationException, IOException;
430
431 /**
432 * Load a native agent library by full pathname.
433 *
434 * <p> This convenience method works as if by invoking:
435 *
436 * <blockquote><tt>
437 * {@link #loadAgentPath(String, String) loadAgentPath}(agentLibrary, null);
438 * </tt></blockquote>
439 *
440 * @param agentPath
441 * The full path to the agent library.
442 *
443 * @throws AgentLoadException
444 * If the agent library does not exist, or cannot be loaded for
445 * another reason.
446 *
447 * @throws AgentInitializationException
448 * If the <code>Agent_OnAttach</code> function returns an error
449 *
450 * @throws IOException
451 * If an I/O error occurs
452 *
453 * @throws NullPointerException
454 * If <code>agentPath</code> is <code>null</code>.
455 */
456 public void loadAgentPath(String agentPath)
457 throws AgentLoadException, AgentInitializationException, IOException
458 {
459 loadAgentPath(agentPath, null);
460 }
461
462
463 /**
464 * Loads an agent.
465 *
466 * <p> The agent provided to this method is a path name to a JAR file on the file
467 * system of the target virtual machine. This path is passed to the target virtual
468 * machine where it is interpreted. The target virtual machine attempts to start
|
42 * VirtualMachine to load an agent into the target VM. For example, a profiler tool
43 * written in the Java Language might attach to a running application and load its
44 * profiler agent to profile the running application. </p>
45 *
46 * <p> A VirtualMachine is obtained by invoking the {@link #attach(String) attach} method
47 * with an identifier that identifies the target virtual machine. The identifier is
48 * implementation-dependent but is typically the process identifier (or pid) in
49 * environments where each Java virtual machine runs in its own operating system process.
50 * Alternatively, a <code>VirtualMachine</code> instance is obtained by invoking the
51 * {@link #attach(VirtualMachineDescriptor) attach} method with a {@link
52 * com.sun.tools.attach.VirtualMachineDescriptor VirtualMachineDescriptor} obtained
53 * from the list of virtual machine descriptors returned by the {@link #list list} method.
54 * Once a reference to a virtual machine is obtained, the {@link #loadAgent loadAgent},
55 * {@link #loadAgentLibrary loadAgentLibrary}, and {@link #loadAgentPath loadAgentPath}
56 * methods are used to load agents into target virtual machine. The {@link
57 * #loadAgent loadAgent} method is used to load agents that are written in the Java
58 * Language and deployed in a {@link java.util.jar.JarFile JAR file}. (See
59 * {@link java.lang.instrument} for a detailed description on how these agents
60 * are loaded and started). The {@link #loadAgentLibrary loadAgentLibrary} and
61 * {@link #loadAgentPath loadAgentPath} methods are used to load agents that
62 * are deployed either in a dynamic library or statically linked into the VM and make use of the <a
63 * href="../../../../../../../../technotes/guides/jvmti/index.html">JVM Tools
64 * Interface</a>. </p>
65 *
66 * <p> In addition to loading agents a VirtualMachine provides read access to the
67 * {@link java.lang.System#getProperties() system properties} in the target VM.
68 * This can be useful in some environments where properties such as
69 * <code>java.home</code>, <code>os.name</code>, or <code>os.arch</code> are
70 * used to construct the path to agent that will be loaded into the target VM.
71 *
72 * <p> The following example demonstrates how VirtualMachine may be used:</p>
73 *
74 * <pre>
75 *
76 * // attach to target VM
77 * VirtualMachine vm = VirtualMachine.attach("2177");
78 *
79 * // get system properties in target VM
80 * Properties props = vm.getSystemProperties();
81 *
82 * // construct path to management agent
281 */
282 public final AttachProvider provider() {
283 return provider;
284 }
285
286 /**
287 * Returns the identifier for this Java virtual machine.
288 *
289 * @return The identifier for this Java virtual machine.
290 */
291 public final String id() {
292 return id;
293 }
294
295 /**
296 * Loads an agent library.
297 *
298 * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
299 * TI</a> client is called an <i>agent</i>. It is developed in a native language.
300 * A JVM TI agent is deployed in a platform specific manner but it is typically the
301 * platform equivalent of a dynamic library. Alternatively, it may be statically linked into the VM.
302 * This method causes the given agent library to be loaded into the target
303 * VM (if not already loaded or if not statically linked into the VM).
304 * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
305 * or, for a statically linked agent named 'L', the <code>Agent_OnAttach_L</code> function
306 * as specified in the
307 * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
308 * Interface</a> specification. Note that the <code>Agent_OnAttach[_L]</code>
309 * function is invoked even if the agent library was loaded prior to invoking
310 * this method.
311 *
312 * <p> The agent library provided is the name of the agent library. It is interpreted
313 * in the target virtual machine in an implementation-dependent manner. Typically an
314 * implementation will expand the library name into an operating system specific file
315 * name. For example, on UNIX systems, the name <tt>L</tt> might be expanded to
316 * <tt>libL.so</tt>, and located using the search path specified by the
317 * <tt>LD_LIBRARY_PATH</tt> environment variable. If the agent named 'L' is
318 * statically linked into the VM then the VM must export a function named
319 * <code>Agent_OnAttach_L</code>.</p>
320 *
321 * <p> If the <code>Agent_OnAttach[_L]</code> function in the agent library returns
322 * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
323 * thrown. The return value from the <code>Agent_OnAttach[_L]</code> can then be
324 * obtained by invoking the {@link
325 * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
326 * method on the exception. </p>
327 *
328 * @param agentLibrary
329 * The name of the agent library.
330 *
331 * @param options
332 * The options to provide to the <code>Agent_OnAttach[_L]</code>
333 * function (can be <code>null</code>).
334 *
335 * @throws AgentLoadException
336 * If the agent library does not exist, the agent library is not
337 * statically linked with the VM, or the agent library cannot be
338 * loaded for another reason.
339 *
340 * @throws AgentInitializationException
341 * If the <code>Agent_OnAttach</code> function returns an error
342 * or, for a statically linked agent named 'L', if the
343 * <code>Agent_OnAttach_L</code> function returns
344 * an error.
345 *
346 * @throws IOException
347 * If an I/O error occurs
348 *
349 * @throws NullPointerException
350 * If <code>agentLibrary</code> is <code>null</code>.
351 *
352 * @see com.sun.tools.attach.AgentInitializationException#returnValue()
353 */
354 public abstract void loadAgentLibrary(String agentLibrary, String options)
355 throws AgentLoadException, AgentInitializationException, IOException;
356
357 /**
358 * Loads an agent library.
359 *
360 * <p> This convenience method works as if by invoking:
361 *
362 * <blockquote><tt>
363 * {@link #loadAgentLibrary(String, String) loadAgentLibrary}(agentLibrary, null);
364 * </tt></blockquote>
365 *
366 * @param agentLibrary
367 * The name of the agent library.
368 *
369 * @throws AgentLoadException
370 * If the agent library does not exist, the agent library is not
371 * statically linked with the VM, or the agent library cannot be
372 * loaded for another reason.
373 *
374 * @throws AgentInitializationException
375 * If the <code>Agent_OnAttach</code> function returns an error
376 * or, for a statically linked agent named 'L', if the
377 * <code>Agent_OnAttach_L</code> function returns
378 * an error.
379 *
380 * @throws IOException
381 * If an I/O error occurs
382 *
383 * @throws NullPointerException
384 * If <code>agentLibrary</code> is <code>null</code>.
385 */
386 public void loadAgentLibrary(String agentLibrary)
387 throws AgentLoadException, AgentInitializationException, IOException
388 {
389 loadAgentLibrary(agentLibrary, null);
390 }
391
392 /**
393 * Load a native agent library by full pathname.
394 *
395 * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
396 * TI</a> client is called an <i>agent</i>. It is developed in a native language.
397 * A JVM TI agent is deployed in a platform specific manner but it is typically the
398 * platform equivalent of a dynamic library. Alternatively, the native
399 * library specified by the agentPath parameter may be statically
400 * linked with the VM. The parsing of the agentPath paramter into
401 * a statically linked library name is done in a platform
402 * specific manner in the VM. For example, in UNIX, an agentPath paramter
403 * of <code>/a/b/libL.so</code> would name a library 'L'.
404 *
405 * See the JVM TI Specification for more details.
406 *
407 * This method causes the given agent library to be loaded into the target
408 * VM (if not already loaded or if not statically linked into the VM).
409 * It then causes the target VM to invoke the <code>Agent_OnAttach</code>
410 * function or, for a statically linked agent named 'L', the
411 * <code>Agent_OnAttach_L</code> function as specified in the
412 * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
413 * Interface</a> specification.
414 * Note that the <code>Agent_OnAttach[_L]</code>
415 * function is invoked even if the agent library was loaded prior to invoking
416 * this method.
417 *
418 * <p> The agent library provided is the absolute path from which to load the
419 * agent library. Unlike {@link #loadAgentLibrary loadAgentLibrary}, the library name
420 * is not expanded in the target virtual machine. </p>
421 *
422 * <p> If the <code>Agent_OnAttach[_L]</code> function in the agent library returns
423 * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
424 * thrown. The return value from the <code>Agent_OnAttach[_L]</code> can then be
425 * obtained by invoking the {@link
426 * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
427 * method on the exception. </p>
428 *
429 * @param agentPath
430 * The full path of the agent library.
431 *
432 * @param options
433 * The options to provide to the <code>Agent_OnAttach[_L]</code>
434 * function (can be <code>null</code>).
435 *
436 * @throws AgentLoadException
437 * If the agent library does not exist, the agent library is not
438 * statically linked with the VM, or the agent library cannot be
439 * loaded for another reason.
440 *
441 * @throws AgentInitializationException
442 * If the <code>Agent_OnAttach</code> function returns an error
443 * or, for a statically linked agent named 'L', if the
444 * <code>Agent_OnAttach_L</code> function returns an error
445 *
446 * @throws IOException
447 * If an I/O error occurs
448 *
449 * @throws NullPointerException
450 * If <code>agentPath</code> is <code>null</code>.
451 *
452 * @see com.sun.tools.attach.AgentInitializationException#returnValue()
453 */
454 public abstract void loadAgentPath(String agentPath, String options)
455 throws AgentLoadException, AgentInitializationException, IOException;
456
457 /**
458 * Load a native agent library by full pathname.
459 *
460 * <p> This convenience method works as if by invoking:
461 *
462 * <blockquote><tt>
463 * {@link #loadAgentPath(String, String) loadAgentPath}(agentLibrary, null);
464 * </tt></blockquote>
465 *
466 * @param agentPath
467 * The full path to the agent library.
468 *
469 * @throws AgentLoadException
470 * If the agent library does not exist, the agent library is not
471 * statically linked with the VM, or the agent library cannot be
472 * loaded for another reason.
473 *
474 * @throws AgentInitializationException
475 * If the <code>Agent_OnAttach</code> function returns an error
476 * or, for a statically linked agent named 'L', if the
477 * <code>Agent_OnAttach_L</code> function returns
478 * an error.
479 *
480 * @throws IOException
481 * If an I/O error occurs
482 *
483 * @throws NullPointerException
484 * If <code>agentPath</code> is <code>null</code>.
485 */
486 public void loadAgentPath(String agentPath)
487 throws AgentLoadException, AgentInitializationException, IOException
488 {
489 loadAgentPath(agentPath, null);
490 }
491
492
493 /**
494 * Loads an agent.
495 *
496 * <p> The agent provided to this method is a path name to a JAR file on the file
497 * system of the target virtual machine. This path is passed to the target virtual
498 * machine where it is interpreted. The target virtual machine attempts to start
|