Transformer (byteman-root 2.0.4 API)

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 and Description
`static String`	`ALLOW_CONFIG_UPDATE` system property which determines whether or not byteman configuration can be updated at runtime via the byteman agent listener
`static String`	`BYTEMAN_PACKAGE_PREFIX` prefix for byteman package
`static String`	`BYTEMAN_SAMPLE_PACKAGE_PREFIX` prefix for byteman sample package
`static String`	`BYTEMAN_TEST_PACKAGE_PREFIX` prefix for byteman test package
`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 compatibility
`static String`	`DEBUG` system property set (to any value) in order to switch on debug statements in the default Helper
`static String`	`DUMP_CFG` system property set (to any value) in order to switch on dumping of control flow graph for triger method after construction
`static 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
`static String`	`DUMP_GENERATED_CLASSES` system property set (to any value) in order to switch on dumping of generated bytecode to .class files
`static String`	`DUMP_GENERATED_CLASSES_DIR` system property identifying directory in which to dump generated bytecode .class files
`static String`	`DUMP_GENERATED_CLASSES_INTERMEDIATE` system property set (to any value) in order to switch on dumping of intermediate generated bytecode to .class files
`protected HelperManager`	`helperManager` a manager for helper lifecycle events which can be safely handed on to rules
`protected Instrumentation`	`inst` the instrumentation interface to the JVM
`protected boolean`	`isRedefine` true if the instrumentor allows redefinition
`static String`	`JAVA_LANG_PACKAGE_PREFIX` prefix for org.jboss package
`protected LoadCache`	`loadCache` a cache tracking which classes have been loaded by which class loaders which is used when attempting to resolve a superName to a superclass.
`protected ScriptRepository`	`scriptRepository` a mapping from target class names which appear in rules to a script object holding the rule details
`static String`	`SKIP_OVERRIDE_RULES` system property which turns off injection into overriding methods
`static 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 classes
`static String`	`TRANSFORM_ALL_COMPATIBILITY` retained for compatibility
`static String`	`VERBOSE` system property set (to any value) in order to switch on dumping of generated bytecode to .class files
`static 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 and Description
`Transformer(Instrumentation inst, 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

Methods
Modifier and Type	Method and 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 thread
`protected void`	`dumpScript(RuleScript ruleScript)`
`static boolean`	`enableTriggers(boolean isReset)` enable triggering of rules inside the current thread
`void`	`installBootScripts()` ensure that scripts which apply to classes loaded before registering the transformer get are installed by retransforming the relevant classes
`protected boolean`	`isBytemanClass(String className)` test whether a class with a given name is located in the byteman package
`static boolean`	`isCompileToBytecode()` check whether compilation of rules is enabled or disabled
`static boolean`	`isDebug()` check whether debug mode for rule processing is enabled or disabled
`static boolean`	`isDumpCFG()` check whether dumping of the control flow graph for the trigger class is enabled
`static boolean`	`isDumpCFGPartial()` check whether dumping of the control flow graph for the trigger class during construction is enabled
`protected boolean`	`isSkipClass(Class<?> clazz)` check whether a class should not be considered for transformation
`protected boolean`	`isTransformable(String className)` test whether a class with a given name is a potential candidate for insertion of event notifications
`static boolean`	`isTriggeringEnabled()` check if triggering of rules is enabled inside the current thread
`static boolean`	`isVerbose()` check whether verbose mode for rule processing is enabled or disabled
`static void`	`maybeDumpClass(String fullName, byte[] bytes)`
`static void`	`maybeDumpClassIntermediate(String fullName, byte[] bytes)`
`boolean`	`skipOverrideRules()` check whether compilation of rules is enabled or disabled
`byte[]`	`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

- 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
  - 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
  - loadCache
```
protected final LoadCache loadCache
```
    a cache tracking which classes have been loaded by which class loaders which is used when attempting to resolve a superName to a superclass.
  - 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,
           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 JVM
    
    Throws:
    
    Exception
- Method Detail
  - installBootScripts
```
public void installBootScripts()
                        throws Exception
```
    ensure that scripts which apply to classes loaded before registering the transformer get are installed by retransforming the relevant classes
    
    Throws:
    
    Exception
  - 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 with Instrumentation.addTransformer, the transformer will be called for every new class definition and every class redefinition. The request for a new class definition is made with ClassLoader.defineClass. The request for a class redefinition is made with Instrumentation.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 return null. Otherwise, it should create a new byte[] array, copy the input classfileBuffer into it, along with all desired transformations, and return the new array. The input classfileBuffer 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 the classFileBuffer does not represent a validly formatted class file, it should throw an IllegalClassFormatException. Subsequent transformers will still be called and the load or redefine will still be attempted. Throwing an IllegalClassFormatException thus has the same effect as returning null but facilitates the logging or debugging of format corruptions.
    
    Specified by:
    
    transform in interface ClassFileTransformer
    
    Parameters:
    originalLoader - the defining loader of the class to be transformed, may be null if the bootstrap loader
    className - 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, otherwise null
    protectionDomain - the protection domain of the class being defined or redefined
    classfileBuffer - 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
    
    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
    
    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
  - 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
  - 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 -
    
    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 form 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 -
    loader -
    className -
    targetClassBytes -
    
    Returns:
  - 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)
```
  - isBytemanClass
```
protected boolean isBytemanClass(String className)
```
    test whether a class with a given name is located in the byteman package
    
    Parameters:
    className -
    
    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()
```

Class Transformer

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

BYTEMAN_PACKAGE_PREFIX

BYTEMAN_TEST_PACKAGE_PREFIX

BYTEMAN_SAMPLE_PACKAGE_PREFIX

JAVA_LANG_PACKAGE_PREFIX

VERBOSE

DUMP_CFG_PARTIAL

DUMP_CFG

DEBUG

COMPILE_TO_BYTECODE_COMPATIBILITY

COMPILE_TO_BYTECODE

DUMP_GENERATED_CLASSES

DUMP_GENERATED_CLASSES_INTERMEDIATE

DUMP_GENERATED_CLASSES_DIR

TRANSFORM_ALL

TRANSFORM_ALL_COMPATIBILITY

SKIP_OVERRIDE_RULES

SYSPROPS_STRICT_MODE

VERIFY_TRANSFORMED_BYTES

ALLOW_CONFIG_UPDATE

inst

isRedefine

scriptRepository

loadCache

helperManager

Constructor Detail

Transformer

Method Detail

installBootScripts

transform

disableTriggers

enableTriggers

isTriggeringEnabled

isVerbose

isDumpCFG

isDumpCFGPartial

isDebug

isCompileToBytecode

skipOverrideRules

allowConfigUpdate

updateConfiguration

isTransformable

maybeDumpClassIntermediate

maybeDumpClass

transform

isSkipClass

dumpScript

isBytemanClass

computeDumpGeneratedClasses

computeDumpGeneratedClassesIntermediate

computeDumpGeneratedClassesDir