Package org.jboss.byteman.agent
Class Transformer
- java.lang.Object
-
- org.jboss.byteman.agent.Transformer
-
- All Implemented Interfaces:
ClassFileTransformer
- Direct Known Subclasses:
Retransformer
public class Transformer extends Object implements ClassFileTransformer
byte code transformer used to introduce byteman events into JBoss code
-
-
Field Summary
Fields Modifier and Type Field Description static String
ALLOW_CONFIG_UPDATE
system property which determines whether or not byteman configuration can be updated at runtime via the byteman agent listenerstatic String
BYTEMAN_PACKAGE_PREFIX
prefix for byteman packagestatic String
BYTEMAN_SAMPLE_PACKAGE_PREFIX
prefix for byteman sample packagestatic String
BYTEMAN_TEST_PACKAGE_PREFIX
prefix for byteman test packageprotected CheckerCache
checkerCache
static String
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.static String
COMPILE_TO_BYTECODE_COMPATIBILITY
retained for compatibilitystatic String
DEBUG
system property set (to any value) in order to switch on debug statements in the default Helperstatic String
DISALLOW_DOWNCAST
system property which disables downcasts in bindingsstatic String
DUMP_CFG
system property set (to any value) in order to switch on dumping of control flow graph for triger method after constructionstatic String
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 constructionstatic String
DUMP_GENERATED_CLASSES
system property set (to any value) in order to switch on dumping of generated bytecode to .class filesstatic String
DUMP_GENERATED_CLASSES_DIR
system property identifying directory in which to dump generated bytecode .class filesstatic String
DUMP_GENERATED_CLASSES_INTERMEDIATE
system property set (to any value) in order to switch on dumping of intermediate generated bytecode to .class filesprotected HelperManager
helperManager
a manager for helper lifecycle events which can be safely handed on to rulesprotected Instrumentation
inst
the instrumentation interface to the JVMprotected boolean
isRedefine
true if the instrumentor allows redefinitionstatic String
JAVA_LANG_PACKAGE_PREFIX
prefix for org.jboss packageprotected ScriptRepository
scriptRepository
a mapping from target class names which appear in rules to a script object holding the rule detailsstatic String
SKIP_OVERRIDE_RULES
system property which turns off injection into overriding methodsstatic String
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.static String
TRANSFORM_ALL
system property set to true in order to enable transform of java.lang classesstatic String
TRANSFORM_ALL_COMPATIBILITY
retained for compatibilitystatic String
VERBOSE
system property set (to any value) in order to switch on dumping of generated bytecode to .class filesstatic String
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.
-
Constructor Summary
Constructors Constructor Description Transformer(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
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description static boolean
allowConfigUpdate()
check whether changes to org.jboss.byteman.* system properties will affect the agent configuration.static boolean
computeDumpGeneratedClasses()
static String
computeDumpGeneratedClassesDir()
static boolean
computeDumpGeneratedClassesIntermediate()
static boolean
disableTriggers(boolean isUser)
disable triggering of rules inside the current threadstatic boolean
disallowDowncast()
check whether downcasts in bindings are disallowed.protected void
dumpScript(RuleScript ruleScript)
static boolean
enableTriggers(boolean isReset)
enable triggering of rules inside the current threadClassChecker
getClassChecker(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
getDumpGeneratedClassesDir()
void
installBootScripts()
ensure that scripts which apply to classes loaded before registering the transformer are installed by retransforming the relevant classesvoid
installPolicy()
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
isCompileToBytecode()
check whether compilation of rules is enabled or disabledstatic boolean
isDebug()
check whether debug mode for rule processing is enabled or disabledstatic boolean
isDumpCFG()
check whether dumping of the control flow graph for the trigger class is enabledstatic boolean
isDumpCFGPartial()
check whether dumping of the control flow graph for the trigger class during construction is enabledprotected static boolean
isDumpGeneratedClasses()
protected static boolean
isDumpGeneratedClassesIntermediate()
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 notificationsstatic boolean
isTriggeringEnabled()
check if triggering of rules is enabled inside the current threadstatic boolean
isVerbose()
check whether verbose mode for rule processing is enabled or disabledstatic void
maybeDumpClass(String fullName, byte[] bytes)
static void
maybeDumpClassIntermediate(String fullName, byte[] bytes)
boolean
skipOverrideRules()
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.void
updateConfiguration(String property)
notify a change to an org.jboss.byteman.* system property so that the agent can choose to update its configuration.-
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 Detail
-
BYTEMAN_PACKAGE_PREFIX
public static final String BYTEMAN_PACKAGE_PREFIX
prefix for byteman package- See Also:
- Constant Field Values
-
BYTEMAN_TEST_PACKAGE_PREFIX
public static final String BYTEMAN_TEST_PACKAGE_PREFIX
prefix for byteman test package- See Also:
- Constant Field Values
-
BYTEMAN_SAMPLE_PACKAGE_PREFIX
public static final String BYTEMAN_SAMPLE_PACKAGE_PREFIX
prefix for byteman sample package- See Also:
- Constant Field Values
-
JAVA_LANG_PACKAGE_PREFIX
public static final String JAVA_LANG_PACKAGE_PREFIX
prefix for org.jboss package- See Also:
- Constant Field Values
-
VERBOSE
public static final String VERBOSE
system property set (to any value) in order to switch on dumping of generated bytecode to .class files- See Also:
- Constant Field Values
-
DUMP_CFG_PARTIAL
public static final String 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:
- Constant Field Values
-
DUMP_CFG
public static final String 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:
- Constant Field Values
-
DEBUG
public static final String DEBUG
system property set (to any value) in order to switch on debug statements in the default Helper- See Also:
- Constant Field Values
-
COMPILE_TO_BYTECODE_COMPATIBILITY
public static final String COMPILE_TO_BYTECODE_COMPATIBILITY
retained for compatibility- See Also:
- Constant Field Values
-
COMPILE_TO_BYTECODE
public static final String 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:
- Constant Field Values
-
DUMP_GENERATED_CLASSES
public static final String DUMP_GENERATED_CLASSES
system property set (to any value) in order to switch on dumping of generated bytecode to .class files- See Also:
- Constant Field Values
-
DUMP_GENERATED_CLASSES_INTERMEDIATE
public static final String 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:
- Constant Field Values
-
DUMP_GENERATED_CLASSES_DIR
public static final String DUMP_GENERATED_CLASSES_DIR
system property identifying directory in which to dump generated bytecode .class files- See Also:
- Constant Field Values
-
TRANSFORM_ALL
public static final String TRANSFORM_ALL
system property set to true in order to enable transform of java.lang classes- See Also:
- Constant Field Values
-
TRANSFORM_ALL_COMPATIBILITY
public static final String TRANSFORM_ALL_COMPATIBILITY
retained for compatibility- See Also:
- Constant Field Values
-
SKIP_OVERRIDE_RULES
public static final String SKIP_OVERRIDE_RULES
system property which turns off injection into overriding methods- See Also:
- Constant Field Values
-
SYSPROPS_STRICT_MODE
public static final String 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:
- Constant Field Values
-
VERIFY_TRANSFORMED_BYTES
public static final String 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:
- Constant Field Values
-
ALLOW_CONFIG_UPDATE
public static final String ALLOW_CONFIG_UPDATE
system property which determines whether or not byteman configuration can be updated at runtime via the byteman agent listener- See Also:
- Constant Field Values
-
DISALLOW_DOWNCAST
public static final String DISALLOW_DOWNCAST
system property which disables downcasts in bindings- See Also:
- Constant Field Values
-
inst
protected final Instrumentation inst
the instrumentation interface to the JVM
-
isRedefine
protected boolean isRedefine
true if the instrumentor allows redefinition
-
scriptRepository
protected final ScriptRepository scriptRepository
a mapping from target class names which appear in rules to a script object holding the rule details
-
checkerCache
protected final CheckerCache checkerCache
-
helperManager
protected final HelperManager helperManager
a manager for helper lifecycle events which can be safely handed on to rules
-
-
Constructor Detail
-
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 JVMscriptPaths
- list of file paths for each input scriptscriptTexts
- the text of each input scriptisRedefine
- true if class redefinition is allowed false if notmoduleSystem
- the module system to use in transformation- Throws:
Exception
- if a script is in error
-
-
Method Detail
-
installBootScripts
public void installBootScripts() throws Exception
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:
Instrumentation.redefineClasses(java.lang.instrument.ClassDefinition...)
-
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
protected static String 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
public void updateConfiguration(String property)
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
protected boolean isTransformable(String className)
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
public static void maybeDumpClassIntermediate(String fullName, byte[] bytes)
-
maybeDumpClass
public static void maybeDumpClass(String fullName, byte[] bytes)
-
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
protected boolean isSkipClass(Class<?> clazz)
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
-
dumpScript
protected void dumpScript(RuleScript ruleScript)
-
getClassChecker
public ClassChecker getClassChecker(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.- 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
-
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
-
isBytemanClass
public static boolean isBytemanClass(String className)
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
-
computeDumpGeneratedClasses
public static boolean computeDumpGeneratedClasses()
-
computeDumpGeneratedClassesIntermediate
public static boolean computeDumpGeneratedClassesIntermediate()
-
computeDumpGeneratedClassesDir
public static String computeDumpGeneratedClassesDir()
-
-