|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
See:
Description
Interface Summary | |
---|---|
ClassFileTransformer | An agent provides an implementation of this interface in order to transform class files. |
Instrumentation | This class provides services needed to instrument Java programming language code. |
Class Summary | |
---|---|
ClassDefinition | This class serves as a parameter block to the Instrumentation.redefineClasses method. |
Exception Summary | |
---|---|
IllegalClassFormatException | Thrown by an implementation of
ClassFileTransformer.transform
when its input parameters are invalid. |
UnmodifiableClassException | Thrown by an implementation of
Instrumentation.redefineClasses
when one of the specified classes cannot be modified. |
Provides services that allow Java programming language agents to instrument programs running on the JVM. The mechanism for instrumentation is modification of the byte-codes of methods.
An agent is launched by indicating the agent class and its agent options when the JVM is launched.
The agent class must implement a public static premain
method
similar in principle to the main
application entry point:
public static void
premain(String agentArgs, Instrumentation inst);
After the JVM is initialized, each premain
method will be called in the order
the agents were specified,
then the real application main
method will be called.
Each premain
method must return in order for the startup sequence to proceed.
The agent class will be loaded by the same classloader
which loads the class containing the application main
method.
The premain
methods will be run under the same security and classloader
rules as the application main
method.
There are no modeling restrictions on what the agent premain
method may do.
Anything application main
can do, including spawning threads, is legal from premain
.
Each agent is passed its agent options via the agentArgs
parameter.
The agent options are passed as a single string,
any additional parsing should be performed by the agent itself.
If the agent cannot be resolved
(for example, because the agent class cannot be loaded,
or because the agent class does not have a conformant premain
method), the JVM will abort.
If a premain
method throws an uncaught exception, the JVM will abort.
jarpath is the path to the agent JAR file. options is the agent options. This switch may be used multiple times on the same command line, thus creating multiple agents. More than one agent may use the same jarpath. An agent JAR file must conform to the JAR file specification. The following manifest attributes are defined for an agent JAR file:-javaagent:
jarpath[=
options]
The agent JAR file is appended to the class path.
Premain-Class
- The agent class. That is, the class containing the
premain
method. This attribute is required, if it is not present the JVM will abort. Note: this is a class name, not a file name or path.Boot-Class-Path
- A list of paths to be searched by the bootstrap class loader. Paths represent directories or libraries (commonly referred to as jar or zip libraries on many platforms). These paths are searched by the bootstrap class loader after the platform specific mechanisms of locating a class have failed. Paths are searched in the order listed. Paths in the list are separated by one or more spaces. A path takes the syntax of the path component of a hierarchical URI. The path is absolute if it begins with a slash character ('/'), otherwise it is relative. A relative path is resolved against the absolute path of the agent JAR file. Malformed and non-existent paths are ignored. This attribute is optional.
Can-Redefine-Classes
- Boolean (
true
orfalse
, case irrelevant). Is the ability to redefine classes needed by this agent. Values other thantrue
are consideredfalse
. This attribute is optional, the default isfalse
.
|
JavaTM 2 Platform Standard Ed. 5.0 |
|||||||||
PREV PACKAGE NEXT PACKAGE | FRAMES NO FRAMES |
Copyright 2004 Sun Microsystems, Inc. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.