java.lang.instrument (Java 2 Platform SE 5.0) (original) (raw)

Package java.lang.instrument

Provides services that allow Java programming language agents to instrument programs running on the JVM.

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](../../../java/lang/instrument/ClassFileTransformer.html#transform%28java.lang.ClassLoader, java.lang.String, java.lang.Class, java.security.ProtectionDomain, byte[]%29) when its input parameters are invalid.
UnmodifiableClassException Thrown by an implementation ofInstrumentation.redefineClasses when one of the specified classes cannot be modified.

Package java.lang.instrument Description

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.

Package Specification

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.

Command-Line Interface

On JVMs with a command-line interface, agents are specified by adding this switch to the JVM command-line:

**-javaagent:**jarpath[**=**options]

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:

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


`Can-Redefine-Classes`

``  Boolean (`true` or `false`, case irrelevant). Is the ability to redefine classes needed by this agent. Values other than `true` are considered `false`. This attribute is optional, the default is `false`.

`` ``` ````

``` `` ```

`` `The agent JAR file is appended to the class path.

For tool documentation, please see:

Since:

JDK1.5

Overview Package Class Use Tree Deprecated Index Help JavaTM 2 PlatformStandard Ed. 5.0
PREV PACKAGE NEXT PACKAGE FRAMES NO FRAMES

Submit a bug or feature
For further API reference and developer documentation, see Java 2 SDK SE Developer Documentation. That documentation contains more detailed, developer-targeted descriptions, with conceptual overviews, definitions of terms, workarounds, and working code examples.

Copyright © 2004, 2010 Oracle and/or its affiliates. All rights reserved. Use is subject to license terms. Also see the documentation redistribution policy.

` ``