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 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 AccessController
. If a security manager
is present, the user of this class is responsible for assuring any required privileges.
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.
|
Modifier and Type | Field and Description |
---|---|
private static java.lang.String |
AGENT_CLASS_PROPERTY
The manifest property specifying the agent class.
|
private static java.lang.String |
ATTACHER_FILE_NAME
The naming prefix of all artifacts for an attacher jar.
|
private static ByteBuddyAgent.AttachmentTypeEvaluator |
ATTACHMENT_TYPE_EVALUATOR
The attachment type evaluator to be used for determining if an attachment requires an external process.
|
private static java.lang.ClassLoader |
BOOTSTRAP_CLASS_LOADER
Representation of the bootstrap
ClassLoader . |
private static int |
BUFFER_SIZE
The size of the buffer for copying the agent installer file into another jar.
|
private static java.lang.String |
CAN_REDEFINE_CLASSES_PROPERTY
The manifest property specifying the can redefine property.
|
private static java.lang.String |
CAN_RETRANSFORM_CLASSES_PROPERTY
The manifest property specifying the can retransform property.
|
private static java.lang.String |
CAN_SET_NATIVE_METHOD_PREFIX
The manifest property specifying the can set native method prefix property.
|
private static java.io.File |
CANNOT_SELF_RESOLVE
Represents a failed attempt to self-resolve a jar file location.
|
private static java.lang.String |
CLASS_FILE_EXTENSION
The file extension for a class file.
|
private static java.lang.String |
CLASS_PATH_ARGUMENT
The class path argument to specify the class path elements.
|
private static int |
END_OF_FILE
Convenience indices for reading and writing to the buffer to make the code more readable.
|
private static java.lang.String |
FILE_PROTOCOL
Represents the
file URL protocol. |
private static java.lang.String |
INSTRUMENTATION_METHOD
The name of the method for reading the installer's instrumentation.
|
private static java.lang.String |
JAR_FILE_EXTENSION
The file extension for a jar file.
|
private static java.lang.String |
JAVA_HOME
The Java property denoting the Java home directory.
|
private static java.lang.String |
MANIFEST_VERSION_VALUE
The manifest property value for the manifest version.
|
private static java.lang.String |
OS_NAME
The Java property denoting the operating system name.
|
private static int |
START_INDEX
Convenience indices for reading and writing to the buffer to make the code more readable.
|
private static java.lang.Object |
STATIC_MEMBER
Base for access to a reflective member to make the code more readable.
|
private static int |
SUCCESSFUL_ATTACH
The status code expected as a result of a successful attachment.
|
private static java.lang.instrument.Instrumentation |
UNAVAILABLE
An indicator variable to express that no instrumentation is available.
|
private static java.lang.String |
WITHOUT_ARGUMENT
Represents a no-op argument for a dynamic agent attachment.
|
Modifier | Constructor and Description |
---|---|
private |
ByteBuddyAgent()
The agent provides only
static utility methods and should not be instantiated. |
Modifier and Type | Method and Description |
---|---|
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,
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,
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,
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,
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,
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.
|
private static java.lang.instrument.Instrumentation |
doGetInstrumentation()
Performs the actual lookup of the
Instrumentation from an installed
Byte Buddy agent. |
static java.lang.instrument.Instrumentation |
getInstrumentation()
Looks up the
Instrumentation 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 an agent on the currently running Java virtual machine using the supplied
attachment provider.
|
static java.lang.instrument.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.
|
private static void |
install(ByteBuddyAgent.AttachmentProvider attachmentProvider,
java.lang.String processId,
java.lang.String argument,
ByteBuddyAgent.AgentProvider agentProvider)
Installs a Java agent on a target VM.
|
static java.lang.instrument.Instrumentation |
install(ByteBuddyAgent.ProcessProvider processProvider)
Installs an agent on the Java virtual machine resolved by the process provider.
|
private static void |
installExternal(ByteBuddyAgent.AttachmentProvider.Accessor.ExternalAttachment externalAttachment,
java.lang.String processId,
java.io.File agent,
java.lang.String argument)
Installs a Java agent to the current VM via an external process.
|
private static java.lang.String |
quote(java.lang.String value)
Quotes a value if it contains a white space.
|
private static java.io.File |
trySelfResolve()
Attempts to resolve the location of the
Attacher class for a self-attachment. |
private static final java.lang.String AGENT_CLASS_PROPERTY
private static final java.lang.String CAN_REDEFINE_CLASSES_PROPERTY
private static final java.lang.String CAN_RETRANSFORM_CLASSES_PROPERTY
private static final java.lang.String CAN_SET_NATIVE_METHOD_PREFIX
private static final java.lang.String MANIFEST_VERSION_VALUE
private static final int BUFFER_SIZE
private static final int START_INDEX
private static final int END_OF_FILE
private static final int SUCCESSFUL_ATTACH
private static final java.lang.Object STATIC_MEMBER
private static final java.lang.ClassLoader BOOTSTRAP_CLASS_LOADER
ClassLoader
.private static final java.lang.String WITHOUT_ARGUMENT
private static final java.lang.String ATTACHER_FILE_NAME
private static final java.lang.String CLASS_FILE_EXTENSION
private static final java.lang.String JAR_FILE_EXTENSION
private static final java.lang.String CLASS_PATH_ARGUMENT
private static final java.lang.String JAVA_HOME
private static final java.lang.String OS_NAME
private static final java.lang.String INSTRUMENTATION_METHOD
private static final java.lang.String FILE_PROTOCOL
file
URL protocol.private static final java.lang.instrument.Instrumentation UNAVAILABLE
private static final java.io.File CANNOT_SELF_RESOLVE
private static final ByteBuddyAgent.AttachmentTypeEvaluator ATTACHMENT_TYPE_EVALUATOR
private ByteBuddyAgent()
static
utility methods and should not be instantiated.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.
Instrumentation
instance which is provided by an installed
Byte Buddy agent.public static void attach(java.io.File agentJar, java.lang.String processId)
IllegalStateException
is thrown. The agent is not provided an argument.agentJar
- The agent jar file.processId
- The target process id.public static void attach(java.io.File agentJar, java.lang.String processId, java.lang.String argument)
IllegalStateException
is thrown.agentJar
- The agent jar file.processId
- The target process id.argument
- The argument to provide to the agent.public static void attach(java.io.File agentJar, java.lang.String processId, ByteBuddyAgent.AttachmentProvider attachmentProvider)
agentJar
- The agent jar file.processId
- The target process id.attachmentProvider
- The attachment provider to use.public static void attach(java.io.File agentJar, java.lang.String processId, java.lang.String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider)
agentJar
- The agent jar file.processId
- The target process id.argument
- The argument to provide to the agent.attachmentProvider
- The attachment provider to use.public static void attach(java.io.File agentJar, ByteBuddyAgent.ProcessProvider processProvider)
IllegalStateException
is thrown. The agent is not provided an argument.agentJar
- The agent jar file.processProvider
- A provider of the target process id.public static void attach(java.io.File agentJar, ByteBuddyAgent.ProcessProvider processProvider, java.lang.String argument)
IllegalStateException
is thrown.agentJar
- The agent jar file.processProvider
- A provider of the target process id.argument
- The argument to provide to the agent.public static void attach(java.io.File agentJar, ByteBuddyAgent.ProcessProvider processProvider, ByteBuddyAgent.AttachmentProvider attachmentProvider)
agentJar
- The agent jar file.processProvider
- A provider of the target process id.attachmentProvider
- The attachment provider to use.public static void attach(java.io.File agentJar, ByteBuddyAgent.ProcessProvider processProvider, java.lang.String argument, ByteBuddyAgent.AttachmentProvider attachmentProvider)
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.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:
jdk.attach
module is
available to Byte Buddy which is typically only available for VMs shipped with a JDK.tools.jar
bundled with the VM which
is typically only available for JDK-versions of the JVM.
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.
public static java.lang.instrument.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.
attachmentProvider
- The attachment provider to use for the installation.public static java.lang.instrument.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:
jdk.attach
module is
available to Byte Buddy which is typically only available for VMs shipped with a JDK.tools.jar
bundled with the VM which
is typically only available for JDK-versions of the JVM.
If an agent cannot be installed, an IllegalStateException
is thrown.
processProvider
- The provider for the current JVM's process id.public static java.lang.instrument.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.
attachmentProvider
- The attachment provider to use for the installation.processProvider
- The provider for the current JVM's process id.private static void install(ByteBuddyAgent.AttachmentProvider attachmentProvider, java.lang.String processId, java.lang.String argument, ByteBuddyAgent.AgentProvider agentProvider)
attachmentProvider
- The attachment provider to use.processId
- The process id of the target JVM process.argument
- The argument to provide to the agent.agentProvider
- The agent provider for the agent jar.private static void installExternal(ByteBuddyAgent.AttachmentProvider.Accessor.ExternalAttachment externalAttachment, java.lang.String processId, java.io.File agent, java.lang.String argument) throws java.lang.Exception
jdk.attach.allowAttachSelf
property is set to false
what is the default setting.externalAttachment
- A description of the external attachment.processId
- The process id of the current process.agent
- The Java agent to install.argument
- The argument to provide to the agent or null
if no argument should be supplied.java.lang.Exception
- If an exception occurs during the attachment or the external process fails the attachment.private static java.io.File trySelfResolve()
Attacher
class for a self-attachment. Doing so avoids the creation of a temporary jar file.null
if the jar file cannot be located.private static java.lang.String quote(java.lang.String value)
value
- The value to quote.private static java.lang.instrument.Instrumentation doGetInstrumentation()
Instrumentation
from an installed
Byte Buddy agent.Instrumentation
instance.