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
|
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. If a native agent library
302 * called <code>agent-lib-name</code> is statically linked with the VM, then the
303 * <code>Agent_OnAttach_agent-lib-name</code> function exported by the agent
304 * is invoked.
305 *
306 * See the JVMTI Specification for more details.
307 *
308 * Otherwise, this method causes the given agent
309 * library to be loaded into the target VM (if not already loaded).
310 * It then causes the target VM to invoke the <code>Agent_OnAttach</code> function
311 * or, for statically linked agents, the <code>Agent_OnAttach_agent-lib-name</code> function
312 * as specified in the
313 * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
314 * Interface</a> specification. Note that the <code>Agent_OnAttach[_agent-lib-name]</code>
315 * function is invoked even if the agent library was loaded prior to invoking
316 * this method.
317 *
318 * <p> The agent library provided is the name of the agent library. It is interpreted
319 * in the target virtual machine in an implementation-dependent manner. Typically an
320 * implementation will expand the library name into an operating system specific file
321 * name. For example, on UNIX systems, the name <tt>foo</tt> might be expanded to
322 * <tt>libfoo.so</tt>, and located using the search path specified by the
323 * <tt>LD_LIBRARY_PATH</tt> environment variable.</p>
324 *
325 * <p> If the <code>Agent_OnAttach[_agent-lib-name]</code> function in the agent library returns
326 * an error then an {@link com.sun.tools.attach.AgentInitializationException} is
327 * thrown. The return value from the <code>Agent_OnAttach[_agent-lib-name]</code> can then be
328 * obtained by invoking the {@link
329 * com.sun.tools.attach.AgentInitializationException#returnValue() returnValue}
330 * method on the exception. </p>
331 *
332 * @param agentLibrary
333 * The name of the agent library.
334 *
335 * @param options
336 * The options to provide to the <code>Agent_OnAttach[_agent-lib-name]</code>
337 * function (can be <code>null</code>).
338 *
339 * @throws AgentLoadException
340 * If the agent library does not exist, the agent library is not
341 * statically linked with the VM, or the agent library cannot be
342 * loaded for another reason.
343 *
344 * @throws AgentInitializationException
345 * If the <code>Agent_OnAttach</code> function returns an error
346 * or, for statically linked agents, if the
347 * <code>Agent_OnAttach_agent-lib-name</code> function returns
348 * an error.
349 *
350 * @throws IOException
351 * If an I/O error occurs
352 *
353 * @throws NullPointerException
354 * If <code>agentLibrary</code> is <code>null</code>.
355 *
356 * @see com.sun.tools.attach.AgentInitializationException#returnValue()
357 */
358 public abstract void loadAgentLibrary(String agentLibrary, String options)
359 throws AgentLoadException, AgentInitializationException, IOException;
360
361 /**
362 * Loads an agent library.
363 *
364 * <p> This convenience method works as if by invoking:
365 *
366 * <blockquote><tt>
367 * {@link #loadAgentLibrary(String, String) loadAgentLibrary}(agentLibrary, null);
368 * </tt></blockquote>
369 *
370 * @param agentLibrary
371 * The name of the agent library.
372 *
373 * @throws AgentLoadException
374 * If the agent library does not exist, the agent library is not
375 * statically linked with the VM, or the agent library cannot be
376 * loaded for another reason.
377 *
378 * @throws AgentInitializationException
379 * If the <code>Agent_OnAttach</code> function returns an error
380 * or, for statically linked agents, if the
381 * <code>Agent_OnAttach_agent-lib-name</code> function returns
382 * an error.
383 *
384 * @throws IOException
385 * If an I/O error occurs
386 *
387 * @throws NullPointerException
388 * If <code>agentLibrary</code> is <code>null</code>.
389 */
390 public void loadAgentLibrary(String agentLibrary)
391 throws AgentLoadException, AgentInitializationException, IOException
392 {
393 loadAgentLibrary(agentLibrary, null);
394 }
395
396 /**
397 * Load a native agent library by full pathname.
398 *
399 * <p> A <a href="../../../../../../../../technotes/guides/jvmti/index.html">JVM
400 * TI</a> client is called an <i>agent</i>. It is developed in a native language.
401 * A JVM TI agent is deployed in a platform specific manner but it is typically the
402 * platform equivalent of a dynamic library. If a native agent library
403 * called <code>agent-lib-name</code> is statically linked with the VM, then the
404 * <code>Agent_OnAttach_agent-lib-name</code> function exported by the agent
405 * is invoked.
406 *
407 * See the JVMTI Specification for more details.
408 *
409 * Otherwise, this method causes the given agent
410 * library to be loaded into the target VM (if not already loaded).
411 * It then causes the target VM to invoke the <code>Agent_OnAttach[_agent-lib-name]</code> function
412 * as specified in the
413 * <a href="../../../../../../../../technotes/guides/jvmti/index.html"> JVM Tools
414 * Interface</a> specification. Note that the <code>Agent_OnAttach[_agent-lib-name]</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[_agent-lib-name]</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[_agent-lib-name]</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[_agent-lib-name]</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 statically linked agents, if the
444 * <code>Agent_OnAttach_agent-lib-name</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 statically linked agents, if the
477 * <code>Agent_OnAttach_agent-lib-name</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
|