Package org.jboss.byteman.agent
Class Transformer
java.lang.Object
org.jboss.byteman.agent.Transformer
- All Implemented Interfaces:
ClassFileTransformer
- Direct Known Subclasses:
Retransformer
byte code transformer used to introduce byteman events into JBoss code
-
Nested Class Summary
Nested ClassesModifier and TypeClassDescriptionprivate class
classloader used by transformer when verification is switched on to detect errors in transformed bytecode -
Field Summary
FieldsModifier and TypeFieldDescription(package private) AccessEnabler
an object we use to enable access to reflective fields where neededstatic final String
system property set to record the currently installed Byteman agent's versionstatic final String
system property which determines whether or not byteman configuration can be updated at runtime via the byteman agent listenerprivate static boolean
master switch which determines whether or not config values can be updatedhash set naming blacklisted methods we refuse to inject intostatic final String
prefix for byteman packagestatic final String
prefix for byteman sample packagestatic final String
prefix for byteman test packageprotected final CheckerCache
static final String
system property set (to any value) in order to switch on compilation of rules and left unset if rules are to be interpreted.static final String
retained for compatibilityprivate static boolean
switch to control whether rules are compiled to bytecode or notprivate static Object
lock object used to control getters and setters when allowConfigUpdate is trueprivate static boolean
switch to control debug output during rule processingstatic final String
system property set (to any value) in order to switch on debug statements in the default Helperprivate static final Integer
private static final Integer
static final String
system property which disables downcasts in bindingsprivate static boolean
switch which determines whether downcasts in binding initialisations are disallowedstatic final String
system property set (to any value) in order to switch on dumping of control flow graph for triger method after constructionstatic final String
system property set (to any value) in order to switch on dumping of control flow graph for trigger method at each stage of constructionstatic final String
system property set (to any value) in order to switch on dumping of generated bytecode to .class filesstatic final String
system property identifying directory in which to dump generated bytecode .class filesstatic final String
system property set (to any value) in order to switch on dumping of intermediate generated bytecode to .class filesprivate static boolean
switch to control control flow graph output during rule processingprivate static boolean
switch to control control flow graph output during rule processingprivate static boolean
switch to control dumping of generated bytecode to .class filesprivate static String
directory in which to dump generated bytecode .class files (defaults to "."private static boolean
switch to control dumping of generated bytecode to .class filesprivate static final Integer
protected final HelperManager
a manager for helper lifecycle events which can be safely handed on to rulesprotected final Instrumentation
the instrumentation interface to the JVMprivate static ThreadLocal
<Integer> Thread local holding a per thread Boolean which is true if triggering is disabled and false if triggering is enabledprotected boolean
true if the instrumentor allows redefinitionstatic final String
prefix for org.jboss packageprotected final ScriptRepository
a mapping from target class names which appear in rules to a script object holding the rule detailsstatic final String
system property which turns off injection into overriding methodsprivate static boolean
switch to control whether rules are injected into overriding methodsstatic final String
system property which enables the restriction that only byteman specific system properties will be gettable/settable via a client using the LISTSYSPROPS and SETSYSPROPS commands.static final String
system property set to true in order to enable transform of java.lang classesstatic final String
retained for compatibilityprivate static boolean
switch to control whether transformations will be applied to java.lang.* classesprivate static boolean
switch to control verbose output during rule processingstatic final String
system property set (to any value) in order to switch on dumping of generated bytecode to .class filesstatic final String
system property which enables the restriction that only byteman specific system properties will be gettable/settable via a client using the LISTSYSPROPS and SETSYSPROPS commands.private static boolean
switch to control whether we attempt to verify transformed bytecode before returning it by consructing a temporary class from it. -
Constructor Summary
ConstructorsConstructorDescriptionTransformer
(Instrumentation inst, ModuleSystem moduleSystem, List<String> scriptPaths, List<String> scriptTexts, boolean isRedefine) constructor allowing this transformer to be provided with access to the JVM's instrumentation implementation -
Method Summary
Modifier and TypeMethodDescriptionstatic boolean
check whether changes to org.jboss.byteman.* system properties will affect the agent configuration.private void
checkConfiguration
(String property) private static boolean
private static boolean
private static boolean
private static boolean
private static boolean
static boolean
static String
static boolean
private static boolean
private static boolean
private static boolean
private static boolean
static boolean
disableTriggers
(boolean isUser) disable triggering of rules inside the current threadstatic boolean
check whether downcasts in bindings are disallowed.private static void
private static void
protected void
dumpScript
(RuleScript ruleScript) static boolean
enableTriggers
(boolean isReset) enable triggering of rules inside the current threadprivate static boolean
ensureDumpDirectory
(String fileName) private ClassChecker
getClassChecker
(byte[] bytecode) return a checker object which can be used to retrieve the super and interfaces of a class from its defining bytecodegetClassChecker
(String name, ClassLoader baseLoader) return a checker object which can be used to retrieve the super and interfaces of a class from its name and classloader without forcing a load of the class.protected static String
init method to create hash set naming blacklisted methods we refuse to inject intovoid
ensure that scripts which apply to classes loaded before registering the transformer are installed by retransforming the relevant classesvoid
boolean
isBlacklisted
(String triggerClassName, String targetMethodName, String targetDescriptor) check whether we are unwilling to inject into a given target methodstatic boolean
isBytemanClass
(String className) test whether a class with a given name is located in the byteman packagestatic boolean
check whether compilation of rules is enabled or disabledstatic boolean
isDebug()
check whether debug mode for rule processing is enabled or disabledstatic boolean
check whether dumping of the control flow graph for the trigger class is enabledstatic boolean
check whether dumping of the control flow graph for the trigger class during construction is enabledprotected static boolean
protected static boolean
protected boolean
isSkipClass
(Class<?> clazz) check whether a class should not be considered for transformationprotected boolean
isTransformable
(String className) test whether a class with a given name is a potential candidate for insertion of event notificationsprivate boolean
isTransformed
(Class clazz, String name, boolean isInterface) static boolean
check if triggering of rules is enabled inside the current threadstatic boolean
check whether verbose mode for rule processing is enabled or disabledstatic void
maybeDumpClass
(String fullName, byte[] bytes) static void
maybeDumpClassIntermediate
(String fullName, byte[] bytes) private byte[]
maybeVerifyTransformedBytes
(ClassLoader loader, String classname, ProtectionDomain protectionDomain, byte[] bytes) return the result from calling verifyTransformedBytes if verification is enabled otherwise just return the supplied bytecodeprivate void
boolean
check whether compilation of rules is enabled or disabledbyte[]
transform
(ClassLoader originalLoader, String className, Class<?> classBeingRedefined, ProtectionDomain protectionDomain, byte[] classfileBuffer) The implementation of this method may transform the supplied class file and return a new replacement class file.byte[]
transform
(RuleScript ruleScript, ClassLoader loader, String className, byte[] targetClassBytes) The routine which actually does the real bytecode transformation.private byte[]
tryTransform
(byte[] buffer, String name, ClassLoader loader, String key, boolean isInterface) private byte[]
tryTransform
(byte[] buffer, String name, ClassLoader loader, String key, boolean isInterface, boolean isOverride) void
updateConfiguration
(String property) notify a change to an org.jboss.byteman.* system property so that the agent can choose to update its configuration.private byte[]
verifyTransformedBytes
(ClassLoader loader, String classname, ProtectionDomain protectionDomain, byte[] bytes) verify the supplied bytecode by converting it to a class and calling newInstance with no args to instantiate.Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
Methods inherited from interface java.lang.instrument.ClassFileTransformer
transform
-
Field Details
-
BYTEMAN_PACKAGE_PREFIX
prefix for byteman package- See Also:
-
BYTEMAN_TEST_PACKAGE_PREFIX
prefix for byteman test package- See Also:
-
BYTEMAN_SAMPLE_PACKAGE_PREFIX
prefix for byteman sample package- See Also:
-
JAVA_LANG_PACKAGE_PREFIX
prefix for org.jboss package- See Also:
-
VERBOSE
system property set (to any value) in order to switch on dumping of generated bytecode to .class files- See Also:
-
DUMP_CFG_PARTIAL
system property set (to any value) in order to switch on dumping of control flow graph for trigger method at each stage of construction- See Also:
-
DUMP_CFG
system property set (to any value) in order to switch on dumping of control flow graph for triger method after construction- See Also:
-
DEBUG
system property set (to any value) in order to switch on debug statements in the default Helper- See Also:
-
AGENT_VERSION
system property set to record the currently installed Byteman agent's version- See Also:
-
COMPILE_TO_BYTECODE_COMPATIBILITY
retained for compatibility- See Also:
-
COMPILE_TO_BYTECODE
system property set (to any value) in order to switch on compilation of rules and left unset if rules are to be interpreted.- See Also:
-
DUMP_GENERATED_CLASSES
system property set (to any value) in order to switch on dumping of generated bytecode to .class files- See Also:
-
DUMP_GENERATED_CLASSES_INTERMEDIATE
system property set (to any value) in order to switch on dumping of intermediate generated bytecode to .class files- See Also:
-
DUMP_GENERATED_CLASSES_DIR
system property identifying directory in which to dump generated bytecode .class files- See Also:
-
TRANSFORM_ALL
system property set to true in order to enable transform of java.lang classes- See Also:
-
TRANSFORM_ALL_COMPATIBILITY
retained for compatibility- See Also:
-
SKIP_OVERRIDE_RULES
system property which turns off injection into overriding methods- See Also:
-
SYSPROPS_STRICT_MODE
system property which enables the restriction that only byteman specific system properties will be gettable/settable via a client using the LISTSYSPROPS and SETSYSPROPS commands.- See Also:
-
VERIFY_TRANSFORMED_BYTES
system property which enables the restriction that only byteman specific system properties will be gettable/settable via a client using the LISTSYSPROPS and SETSYSPROPS commands.- See Also:
-
ALLOW_CONFIG_UPDATE
system property which determines whether or not byteman configuration can be updated at runtime via the byteman agent listener- See Also:
-
DISALLOW_DOWNCAST
system property which disables downcasts in bindings- See Also:
-
blacklisted
hash set naming blacklisted methods we refuse to inject into -
inst
the instrumentation interface to the JVM -
accessEnabler
AccessEnabler accessEnableran object we use to enable access to reflective fields where needed -
isRedefine
protected boolean isRedefinetrue if the instrumentor allows redefinition -
scriptRepository
a mapping from target class names which appear in rules to a script object holding the rule details -
checkerCache
-
helperManager
a manager for helper lifecycle events which can be safely handed on to rules -
verbose
private static boolean verboseswitch to control verbose output during rule processing -
dumpCFGPartial
private static boolean dumpCFGPartialswitch to control control flow graph output during rule processing -
dumpCFG
private static boolean dumpCFGswitch to control control flow graph output during rule processing -
debug
private static boolean debugswitch to control debug output during rule processing -
compileToBytecode
private static boolean compileToBytecodeswitch to control whether rules are compiled to bytecode or not -
skipOverrideRules
private static boolean skipOverrideRulesswitch to control whether rules are injected into overriding methods -
dumpGeneratedClasses
private static boolean dumpGeneratedClassesswitch to control dumping of generated bytecode to .class files -
dumpGeneratedClassesIntermediate
private static boolean dumpGeneratedClassesIntermediateswitch to control dumping of generated bytecode to .class files -
dumpGeneratedClassesDir
directory in which to dump generated bytecode .class files (defaults to "." -
transformAll
private static boolean transformAllswitch to control whether transformations will be applied to java.lang.* classes -
verifyTransformedBytes
private static boolean verifyTransformedBytesswitch to control whether we attempt to verify transformed bytecode before returning it by consructing a temporary class from it. -
disallowDowncast
private static boolean disallowDowncastswitch which determines whether downcasts in binding initialisations are disallowed -
allowConfigUpdate
private static boolean allowConfigUpdatemaster switch which determines whether or not config values can be updated -
configLock
lock object used to control getters and setters when allowConfigUpdate is true -
isEnabled
Thread local holding a per thread Boolean which is true if triggering is disabled and false if triggering is enabled -
DISABLED_USER
-
DISABLED
-
ENABLED
-
-
Constructor Details
-
Transformer
public Transformer(Instrumentation inst, ModuleSystem moduleSystem, List<String> scriptPaths, List<String> scriptTexts, boolean isRedefine) throws Exception constructor allowing this transformer to be provided with access to the JVM's instrumentation implementation- Parameters:
inst
- the instrumentation object used to interface to the JVMmoduleSystem
- the module system to use in transformationscriptPaths
- list of file paths for each input scriptscriptTexts
- the text of each input scriptisRedefine
- true if class redefinition is allowed false if not- Throws:
Exception
- if a script is in error
-
-
Method Details
-
installBootScripts
ensure that scripts which apply to classes loaded before registering the transformer are installed by retransforming the relevant classes- Throws:
Exception
- if the retransform fails
-
installPolicy
public void installPolicy() -
transform
public byte[] transform(ClassLoader originalLoader, String className, Class<?> classBeingRedefined, ProtectionDomain protectionDomain, byte[] classfileBuffer) throws IllegalClassFormatException The implementation of this method may transform the supplied class file and return a new replacement class file. Once a transformer has been registered withInstrumentation.addTransformer
, the transformer will be called for every new class definition and every class redefinition. The request for a new class definition is made withClassLoader.defineClass
. The request for a class redefinition is made withInstrumentation.redefineClasses
or its native equivalents. The transformer is called during the processing of the request, before the class file bytes have been verified or applied. If the implementing method determines that no transformations are needed, it should returnnull
. Otherwise, it should create a newbyte[]
array, copy the inputclassfileBuffer
into it, along with all desired transformations, and return the new array. The inputclassfileBuffer
must not be modified. In the redefine case, the transformer must support the redefinition semantics. If a class that the transformer changed during initial definition is later redefined, the transformer must insure that the second class output class file is a legal redefinition of the first output class file. If the transformer believes theclassFileBuffer
does not represent a validly formatted class file, it should throw anIllegalClassFormatException
. Subsequent transformers will still be called and the load or redefine will still be attempted. Throwing anIllegalClassFormatException
thus has the same effect as returning null but facilitates the logging or debugging of format corruptions.- Specified by:
transform
in interfaceClassFileTransformer
- Parameters:
originalLoader
- the defining loader of the class to be transformed, may benull
if the bootstrap loaderclassName
- the name of the class in the internal form of fully qualified class and interface names as defined in The Java Virtual Machine Specification. For example,"java/util/List"
.classBeingRedefined
- if this is a redefine, the class being redefined, otherwisenull
protectionDomain
- the protection domain of the class being defined or redefinedclassfileBuffer
- the input byte buffer in class file format - must not be modified- Returns:
- a well-formed class file buffer (the result of the transform),
or
null
if no transform is performed. - Throws:
IllegalClassFormatException
- if the input does not represent a well-formed class file- See Also:
-
disableTriggers
public static boolean disableTriggers(boolean isUser) disable triggering of rules inside the current thread- Parameters:
isUser
- true if this was called by rule code false if called internally by Byteman- Returns:
- true if triggering was previously enabled and false if it was already disabled
-
enableTriggers
public static boolean enableTriggers(boolean isReset) enable triggering of rules inside the current thread- Parameters:
isReset
- true if this was called by rule code and hence should reset a setting enabled by rule code false if called internally by Byteman and hence should nto reset a setting enabled by rule code- Returns:
- true if triggering was previously enabled and false if it was already disabled
-
isTriggeringEnabled
public static boolean isTriggeringEnabled()check if triggering of rules is enabled inside the current thread- Returns:
- true if triggering is enabled and false if it is disabled
-
isVerbose
public static boolean isVerbose()check whether verbose mode for rule processing is enabled or disabled- Returns:
- true if verbose mode is enabled etherwise false
-
isDumpCFG
public static boolean isDumpCFG()check whether dumping of the control flow graph for the trigger class is enabled- Returns:
- true if dumping is enabled etherwise false
-
isDumpCFGPartial
public static boolean isDumpCFGPartial()check whether dumping of the control flow graph for the trigger class during construction is enabled- Returns:
- true if dumping is enabled etherwise false
-
isDumpGeneratedClasses
protected static boolean isDumpGeneratedClasses() -
getDumpGeneratedClassesDir
-
isDumpGeneratedClassesIntermediate
protected static boolean isDumpGeneratedClassesIntermediate() -
isDebug
public static boolean isDebug()check whether debug mode for rule processing is enabled or disabled- Returns:
- true if debug mode is enabled or verbose mode is enabled otherwise false
-
isCompileToBytecode
public static boolean isCompileToBytecode()check whether compilation of rules is enabled or disabled- Returns:
- true if compilation of rules is enabled etherwise false
-
disallowDowncast
public static boolean disallowDowncast()check whether downcasts in bindings are disallowed.- Returns:
- true if downcasts in bindings are disallowed otherwise false
-
skipOverrideRules
public boolean skipOverrideRules()check whether compilation of rules is enabled or disabled- Returns:
- true if compilation of rules is enabled otherwise false
-
allowConfigUpdate
public static boolean allowConfigUpdate()check whether changes to org.jboss.byteman.* system properties will affect the agent configuration.- Returns:
- true if changes will affect the agent configuration otherwise false
-
updateConfiguration
notify a change to an org.jboss.byteman.* system property so that the agent can choose to update its configuration. n.b. this method is not synchronized because there is an implicit assumption that it is called from the the listener thread immediately after it has updated the property and that no other thread will modify org.jboss.byteman.* properties- Parameters:
property
- an org.jboss.byteman.* system property which has been updated.
-
isTransformable
test whether a class with a given name is a potential candidate for insertion of event notifications- Parameters:
className
- name of the class to test- Returns:
- true if a class is a potential candidate for insertion of event notifications otherwise return false
-
maybeDumpClassIntermediate
-
maybeDumpClass
-
transform
public byte[] transform(RuleScript ruleScript, ClassLoader loader, String className, byte[] targetClassBytes) The routine which actually does the real bytecode transformation. this is public because it needs to be callable from the type checker script. In normal running the javaagent is the only class which has a handle on the registered transformer so it is the only one which can reach this point.- Parameters:
ruleScript
- the scriptloader
- the loader of the class being injected intoclassName
- the name of the class being injected intotargetClassBytes
- the current class bytecode- Returns:
- the transformed bytecode or NULL if no transform was applied
-
isSkipClass
check whether a class should not be considered for transformation- Parameters:
clazz
- the class to check- Returns:
- true if clazz should not be considered for transformation otherwise false
-
tryTransform
private byte[] tryTransform(byte[] buffer, String name, ClassLoader loader, String key, boolean isInterface) -
tryTransform
private byte[] tryTransform(byte[] buffer, String name, ClassLoader loader, String key, boolean isInterface, boolean isOverride) -
dumpScript
-
isTransformed
-
getClassChecker
return a checker object which can be used to retrieve the super and interfaces of a class from its defining bytecode- Parameters:
bytecode
-- Returns:
- a checker
-
getClassChecker
return a checker object which can be used to retrieve the super and interfaces of a class from its name and classloader without forcing a load of the class.- Parameters:
name
- the name of the superclass being checkedbaseLoader
- the class loader of the subclass's bytecode- Returns:
- the requisite checker or null if the class does not need to be checked or cannot be loaded
-
initBlackList
init method to create hash set naming blacklisted methods we refuse to inject into- Returns:
- the hash set
-
isBlacklisted
public boolean isBlacklisted(String triggerClassName, String targetMethodName, String targetDescriptor) check whether we are unwilling to inject into a given target method- Parameters:
triggerClassName
- the name of the target classtargetMethodName
- the name of the target methodtargetDescriptor
- the descriptor of the target method ignored at present- Returns:
- true if we are unwilling to inject into the target method
-
maybeVerifyTransformedBytes
private byte[] maybeVerifyTransformedBytes(ClassLoader loader, String classname, ProtectionDomain protectionDomain, byte[] bytes) return the result from calling verifyTransformedBytes if verification is enabled otherwise just return the supplied bytecode- Parameters:
loader
-classname
-protectionDomain
-bytes
-- Returns:
- the verified bytecode or the original
-
verifyTransformedBytes
private byte[] verifyTransformedBytes(ClassLoader loader, String classname, ProtectionDomain protectionDomain, byte[] bytes) verify the supplied bytecode by converting it to a class and calling newInstance with no args to instantiate. since not all transformed classes have an empty constructor this should only be enabled for testing of Byteman itself in cases where a transformed class is known to have an empty constructor.- Parameters:
loader
-classname
-protectionDomain
-bytes
-- Returns:
- the supplied bytecode if verification succeeds or null if it fails
-
isBytemanClass
test whether a class with a given name is located in the byteman package- Parameters:
className
- the name to be checked- Returns:
- true if a class is located in the byteman package otherwise return false
-
computeVerbose
private static boolean computeVerbose() -
computeDumpCFGPartial
private static boolean computeDumpCFGPartial() -
computeDumpCFG
private static boolean computeDumpCFG() -
computeDebug
private static boolean computeDebug() -
computeCompileToBytecode
private static boolean computeCompileToBytecode() -
computeSkipOverrideRules
private static boolean computeSkipOverrideRules() -
computeDumpGeneratedClasses
public static boolean computeDumpGeneratedClasses() -
computeDumpGeneratedClassesIntermediate
public static boolean computeDumpGeneratedClassesIntermediate() -
computeDumpGeneratedClassesDir
-
computeTransformAll
private static boolean computeTransformAll() -
computeVerifyTransformedBytes
private static boolean computeVerifyTransformedBytes() -
computeDisallowDowncast
private static boolean computeDisallowDowncast() -
checkConfiguration
-
dumpClass
-
dumpClass
-
ensureDumpDirectory
-
setAgentVersion
- Throws:
Exception
-