Package org.jboss.byteman.agent

Class Transformer

    • Field Detail

      • 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

      • 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 JVM
        scriptPaths - list of file paths for each input script
        scriptTexts - the text of each input script
        isRedefine - true if class redefinition is allowed false if not
        moduleSystem - 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 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
        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 script
        loader - the loader of the class being injected into
        className - the name of the class being injected into
        targetClassBytes - 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 checked
        baseLoader - 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 class
        targetMethodName - the name of the target method
        targetDescriptor - 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()