net.bytebuddy.agent

Class ByteBuddyAgent

java.lang.Object

net.bytebuddy.agent.ByteBuddyAgent

public class ByteBuddyAgent
extends Object

The Byte Buddy agent provides a JVM Instrumentation in order to allow Byte Buddy the redefinition of already loaded classes. An agent must normally be specified via the command line via the javaagent parameter. As an argument to this parameter, one must specify the location of this agent's jar file such as for example in

java -javaagent:byte-buddy-agent.jar -jar app.jar

Note: The runtime installation of a Java agent is not possible on all JVMs. See the documentation for install() for details on JVMs that are supported out of the box.

Important: This class's name is known to the Byte Buddy main application and must not be altered.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	ByteBuddyAgent.AttachmentProvider An attachment provider is responsible for making the Java attachment API available.

Method Summary

Modifier and Type	Method and Description
static Instrumentation	getInstrumentation() Looks up the Instrumentation instance of an installed Byte Buddy agent.
static Instrumentation	install() Installs an agent on the currently running Java virtual machine.
static Instrumentation	install(ByteBuddyAgent.AttachmentProvider attachmentProvider) Installs a Java agent using the Java attach API.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

install

public static Instrumentation install()

Installs an agent on the currently running Java virtual machine. Unfortunately, this does not always work. The runtime installation of a Java agent is supported for:

• JVM version 9+: For Java VM of at least version 9, the attachment API was merged into a Jigsaw module and the runtime installation is always possible.
• OpenJDK / Oracle JDK / IBM J9 versions 8-: The installation for HotSpot is only possible when bundled with a JDK up until Java version 8. It is not possible for runtime-only installations of HotSpot or J9 for these versions.

If an agent cannot be installed, a IllegalStateException is thrown.

Important: This is a rather computation-heavy operation. Therefore, this operation is not repeated after an agent was successfully installed for the first time. Instead, the previous instrumentation instance is returned. However, invoking this method requires synchronization such that subsequently to an installation, getInstrumentation() should be invoked instead.

Returns:

An instrumentation instance representing the currently running JVM.

install

public static Instrumentation install(ByteBuddyAgent.AttachmentProvider attachmentProvider)

Installs a Java agent using the Java attach API. This API is available under different access routes for different JVMs and JVM versions or it might not be available at all. If a Java agent cannot be installed by using the supplied attachment provider, a IllegalStateException is thrown.

Parameters:

attachmentProvider - The attachment provider to use for the installation.

Returns:

An instrumentation instance representing the currently running JVM.

getInstrumentation

public static Instrumentation getInstrumentation()

Looks up the Instrumentation instance of an installed Byte Buddy agent. Note that this method implies reflective lookup and reflective invocation such that the returned value should be cached rather than calling this method several times.

Note: This method throws an IllegalStateException If the Byte Buddy agent is not properly installed.

Returns:

The Instrumentation instance which is provided by an installed Byte Buddy agent.