Class ByteBuddyAgent
- java.lang.Object
-
- net.bytebuddy.agent.ByteBuddyAgent
-
public class ByteBuddyAgent extends java.lang.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 thejavaagent
parameter. As an argument to this parameter, one must specify the location of this agent's jar file such as for example injava -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
AccessController
. If a security manager is present, the user of this class is responsible for assuring any required privileges.
-
-
Nested Class Summary
Nested Classes Modifier and Type Class 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.
-
Method Summary
All Methods Static Methods Concrete Methods Modifier and Type Method Description static void
attach(java.io.File agentJar, java.lang.String processId)
Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach(java.io.File agentJar, java.lang.String processId, java.lang.String argument)
Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach(java.io.File agentJar, java.lang.String processId, java.lang.String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider)
Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach(java.io.File agentJar, java.lang.String processId, ByteBuddyAgent.AttachmentProvider attachmentProvider)
Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach(java.io.File agentJar, ByteBuddyAgent.ProcessProvider processProvider)
Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach(java.io.File agentJar, ByteBuddyAgent.ProcessProvider processProvider, java.lang.String argument)
Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach(java.io.File agentJar, ByteBuddyAgent.ProcessProvider processProvider, java.lang.String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider)
Attaches the given agent Jar on the target process which must be a virtual machine process.static void
attach(java.io.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 java.lang.instrument.Instrumentation
getInstrumentation()
Looks up theInstrumentation
instance of an installed Byte Buddy agent.static java.lang.instrument.Instrumentation
install()
Installs an agent on the currently running Java virtual machine.static java.lang.instrument.Instrumentation
install(ByteBuddyAgent.AttachmentProvider attachmentProvider)
Installs a Java agent using the Java attach API.static java.lang.instrument.Instrumentation
install(ByteBuddyAgent.AttachmentProvider attachmentProvider, ByteBuddyAgent.ProcessProvider processProvider)
Installs a Java agent using the Java attach API.static java.lang.instrument.Instrumentation
install(ByteBuddyAgent.ProcessProvider processProvider)
Installs a Java agent using the Java attach API.
-
-
-
Method Detail
-
getInstrumentation
public static java.lang.instrument.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(java.io.File agentJar, java.lang.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, anIllegalStateException
is thrown. The agent is not provided an argument.- Parameters:
agentJar
- The agent jar file.processId
- The target process id.
-
attach
public static void attach(java.io.File agentJar, java.lang.String processId, java.lang.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, anIllegalStateException
is thrown.- Parameters:
agentJar
- The agent jar file.processId
- The target process id.argument
- The argument to provide to the agent.
-
attach
public static void attach(java.io.File agentJar, java.lang.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.- Parameters:
agentJar
- The agent jar file.processId
- The target process id.attachmentProvider
- The attachment provider to use.
-
attach
public static void attach(java.io.File agentJar, java.lang.String processId, java.lang.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.- 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(java.io.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, anIllegalStateException
is thrown. The agent is not provided an argument.- Parameters:
agentJar
- The agent jar file.processProvider
- A provider of the target process id.
-
attach
public static void attach(java.io.File agentJar, ByteBuddyAgent.ProcessProvider processProvider, java.lang.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, anIllegalStateException
is thrown.- 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(java.io.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.- 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(java.io.File agentJar, ByteBuddyAgent.ProcessProvider processProvider, java.lang.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.- 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.
-
install
public static java.lang.instrument.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, 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 java.lang.instrument.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, anIllegalStateException
is thrown. The same happens if the default process provider cannot resolve a process id for the current VM.- Parameters:
attachmentProvider
- The attachment provider to use for the installation.- Returns:
- An instrumentation instance representing the currently running JVM.
-
install
public static java.lang.instrument.Instrumentation install(ByteBuddyAgent.ProcessProvider processProvider)
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 process provider, anIllegalStateException
is thrown. The same happens if the default attachment provider cannot be used.- Parameters:
processProvider
- The provider for the current JVM's process id.- Returns:
- An instrumentation instance representing the currently running JVM.
-
install
public static java.lang.instrument.Instrumentation install(ByteBuddyAgent.AttachmentProvider attachmentProvider, ByteBuddyAgent.ProcessProvider processProvider)
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 and process provider, anIllegalStateException
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.
-
-