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.

Note: Byte Buddy does not execute code using an java.security.AccessController. If a security manager is present, the user of this class is responsible for assuring any required privileges. To read an Instrumentation, the net.bytebuddy.agent.getInstrumentation runtime permission is required.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
protected static interface	ByteBuddyAgent.AgentProvider An agent provider is responsible for handling and providing the jar file of an agent that is being attached.
static interface	ByteBuddyAgent.AttachmentProvider An attachment provider is responsible for making the Java attachment API available.
protected static interface	ByteBuddyAgent.AttachmentTypeEvaluator An attachment evaluator is responsible for deciding if an agent can be attached from the current process.
static interface	ByteBuddyAgent.ProcessProvider A process provider is responsible for providing the process id of the current VM.

Field Summary

Fields

Modifier and Type	Field and Description
static String	LATENT_RESOLVE Indicates that the agent should not resolve its own code location for a self-attachment.

Method Summary

Modifier and Type	Method and Description
static void	attach(File agentJar, ByteBuddyAgent.ProcessProvider processProvider) Attaches the given agent Jar on the target process which must be a virtual machine process.
static void	attach(File agentJar, ByteBuddyAgent.ProcessProvider processProvider, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process.
static void	attach(File agentJar, ByteBuddyAgent.ProcessProvider processProvider, String argument) Attaches the given agent Jar on the target process which must be a virtual machine process.
static void	attach(File agentJar, ByteBuddyAgent.ProcessProvider processProvider, String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process.
static void	attach(File agentJar, String processId) Attaches the given agent Jar on the target process which must be a virtual machine process.
static void	attach(File agentJar, String processId, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process.
static void	attach(File agentJar, String processId, String argument) Attaches the given agent Jar on the target process which must be a virtual machine process.
static void	attach(File agentJar, String processId, String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent Jar on the target process which must be a virtual machine process.
static void	attachNative(File agentLibrary, ByteBuddyAgent.ProcessProvider processProvider) Attaches the given agent library on the target process which must be a virtual machine process.
static void	attachNative(File agentLibrary, ByteBuddyAgent.ProcessProvider processProvider, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process.
static void	attachNative(File agentLibrary, ByteBuddyAgent.ProcessProvider processProvider, String argument) Attaches the given agent library on the target process which must be a virtual machine process.
static void	attachNative(File agentLibrary, ByteBuddyAgent.ProcessProvider processProvider, String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process.
static void	attachNative(File agentLibrary, String processId) Attaches the given agent library on the target process which must be a virtual machine process.
static void	attachNative(File agentLibrary, String processId, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process.
static void	attachNative(File agentLibrary, String processId, String argument) Attaches the given agent library on the target process which must be a virtual machine process.
static void	attachNative(File agentLibrary, String processId, String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider) Attaches the given agent library on the target process which must be a virtual machine process.
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 an agent on the currently running Java virtual machine using the supplied attachment provider.
static Instrumentation	install(ByteBuddyAgent.AttachmentProvider attachmentProvider, ByteBuddyAgent.ProcessProvider processProvider) Installs an agent on the currently running Java virtual machine using the supplied attachment provider and process provider.
static Instrumentation	install(ByteBuddyAgent.ProcessProvider processProvider) Installs an agent on the Java virtual machine resolved by the process provider.

Methods inherited from class java.lang.Object

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

Field Detail

LATENT_RESOLVE

public static final String LATENT_RESOLVE

Indicates that the agent should not resolve its own code location for a self-attachment.

See Also:

Constant Field Values

Method Detail

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.

attach

public static void attach(File agentJar,
                          String processId)

Attaches the given agent Jar on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an IllegalStateException is thrown. The agent is not provided an argument.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentJar - The agent jar file.

processId - The target process id.

attach

public static void attach(File agentJar,
                          String processId,
                          @MaybeNull
                          String argument)

Attaches the given agent Jar on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an IllegalStateException is thrown.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentJar - The agent jar file.

processId - The target process id.

argument - The argument to provide to the agent.

attach

public static void attach(File agentJar,
                          String processId,
                          ByteBuddyAgent.AttachmentProvider attachmentProvider)

Attaches the given agent Jar on the target process which must be a virtual machine process. This operation blocks until the attachment is complete. The agent is not provided an argument.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentJar - The agent jar file.

processId - The target process id.

attachmentProvider - The attachment provider to use.

attach

public static void attach(File agentJar,
                          String processId,
                          @MaybeNull
                          String argument,
                          ByteBuddyAgent.AttachmentProvider attachmentProvider)

Attaches the given agent Jar on the target process which must be a virtual machine process. This operation blocks until the attachment is complete.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentJar - The agent jar file.

processId - The target process id.

argument - The argument to provide to the agent.

attachmentProvider - The attachment provider to use.

attach

public static void attach(File agentJar,
                          ByteBuddyAgent.ProcessProvider processProvider)

Attaches the given agent Jar on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an IllegalStateException is thrown. The agent is not provided an argument.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentJar - The agent jar file.

processProvider - A provider of the target process id.

attach

public static void attach(File agentJar,
                          ByteBuddyAgent.ProcessProvider processProvider,
                          @MaybeNull
                          String argument)

Attaches the given agent Jar on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an IllegalStateException is thrown.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentJar - The agent jar file.

processProvider - A provider of the target process id.

argument - The argument to provide to the agent.

attach

public static void attach(File agentJar,
                          ByteBuddyAgent.ProcessProvider processProvider,
                          ByteBuddyAgent.AttachmentProvider attachmentProvider)

Attaches the given agent Jar on the target process which must be a virtual machine process. This operation blocks until the attachment is complete. The agent is not provided an argument.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentJar - The agent jar file.

processProvider - A provider of the target process id.

attachmentProvider - The attachment provider to use.

attach

public static void attach(File agentJar,
                          ByteBuddyAgent.ProcessProvider processProvider,
                          @MaybeNull
                          String argument,
                          ByteBuddyAgent.AttachmentProvider attachmentProvider)

Attaches the given agent Jar on the target process which must be a virtual machine process. This operation blocks until the attachment is complete.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentJar - The agent jar file.

processProvider - A provider of the target process id.

argument - The argument to provide to the agent.

attachmentProvider - The attachment provider to use.

attachNative

public static void attachNative(File agentLibrary,
                                String processId)

Attaches the given agent library on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an IllegalStateException is thrown. The agent is not provided an argument.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentLibrary - The agent jar file.

processId - The target process id.

attachNative

public static void attachNative(File agentLibrary,
                                String processId,
                                @MaybeNull
                                String argument)

Attaches the given agent library on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an IllegalStateException is thrown.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentLibrary - The agent library.

processId - The target process id.

argument - The argument to provide to the agent.

attachNative

public static void attachNative(File agentLibrary,
                                String processId,
                                ByteBuddyAgent.AttachmentProvider attachmentProvider)

Attaches the given agent library on the target process which must be a virtual machine process. This operation blocks until the attachment is complete. The agent is not provided an argument.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentLibrary - The agent library.

processId - The target process id.

attachmentProvider - The attachment provider to use.

attachNative

public static void attachNative(File agentLibrary,
                                String processId,
                                @MaybeNull
                                String argument,
                                ByteBuddyAgent.AttachmentProvider attachmentProvider)

Attaches the given agent library on the target process which must be a virtual machine process. This operation blocks until the attachment is complete.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentLibrary - The agent library.

processId - The target process id.

argument - The argument to provide to the agent.

attachmentProvider - The attachment provider to use.

attachNative

public static void attachNative(File agentLibrary,
                                ByteBuddyAgent.ProcessProvider processProvider)

Attaches the given agent library on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an IllegalStateException is thrown. The agent is not provided an argument.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentLibrary - The agent library.

processProvider - A provider of the target process id.

attachNative

public static void attachNative(File agentLibrary,
                                ByteBuddyAgent.ProcessProvider processProvider,
                                @MaybeNull
                                String argument)

Attaches the given agent library on the target process which must be a virtual machine process. The default attachment provider is used for applying the attachment. This operation blocks until the attachment is complete. If the current VM does not supply any known form of attachment to a remote VM, an IllegalStateException is thrown.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentLibrary - The agent library.

processProvider - A provider of the target process id.

argument - The argument to provide to the agent.

attachNative

public static void attachNative(File agentLibrary,
                                ByteBuddyAgent.ProcessProvider processProvider,
                                ByteBuddyAgent.AttachmentProvider attachmentProvider)

Attaches the given agent library on the target process which must be a virtual machine process. This operation blocks until the attachment is complete. The agent is not provided an argument.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentLibrary - The agent library.

processProvider - A provider of the target process id.

attachmentProvider - The attachment provider to use.

attachNative

public static void attachNative(File agentLibrary,
                                ByteBuddyAgent.ProcessProvider processProvider,
                                @MaybeNull
                                String argument,
                                ByteBuddyAgent.AttachmentProvider attachmentProvider)

Attaches the given agent library on the target process which must be a virtual machine process. This operation blocks until the attachment is complete.

Important: It is only possible to attach to processes that are executed by the same operating system user.

Parameters:

agentLibrary - The agent library.

processProvider - A provider of the target process id.

argument - The argument to provide to the agent.

attachmentProvider - The attachment provider to use.

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 moved into a module and the runtime installation is possible if the jdk.attach module is available to Byte Buddy which is typically only available for VMs shipped with a JDK.
• OpenJDK / Oracle JDK / IBM J9 versions 8-: The installation for HotSpot is only possible when bundled with a JDK and requires a tools.jar bundled with the VM which is typically only available for JDK-versions of the JVM.
• When running Linux and including the optional junixsocket-native-common depedency, Byte Buddy emulates a Unix socket connection to attach to the target VM.

If an agent cannot be installed, an 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 an agent on the currently running Java virtual machine using the supplied attachment provider.

If an agent cannot be installed, an 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.

Parameters:

attachmentProvider - The attachment provider to use for the installation.

Returns:

An instrumentation instance representing the currently running JVM.

install

public static Instrumentation install(ByteBuddyAgent.ProcessProvider processProvider)

Installs an agent on the Java virtual machine resolved by the process provider. 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 moved into a module and the runtime installation is possible if the jdk.attach module is available to Byte Buddy which is typically only available for VMs shipped with a JDK.
• OpenJDK / Oracle JDK / IBM J9 versions 8-: The installation for HotSpot is only possible when bundled with a JDK and requires a tools.jar bundled with the VM which is typically only available for JDK-versions of the JVM.
• When running Linux and including the optional junixsocket-native-common depedency, Byte Buddy emulates a Unix socket connection to attach to the target VM.

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

Parameters:

processProvider - The provider for the current JVM's process id.

Returns:

An instrumentation instance representing the currently running JVM.

install

public static Instrumentation install(ByteBuddyAgent.AttachmentProvider attachmentProvider,
                                      ByteBuddyAgent.ProcessProvider processProvider)

Installs an agent on the currently running Java virtual machine using the supplied attachment provider and process provider.

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

Parameters:

attachmentProvider - The attachment provider to use for the installation.

processProvider - The provider for the current JVM's process id.

Returns:

An instrumentation instance representing the currently running JVM.