Package org.jboss.byteman.rule

Class Rule

  • public class Rule
extends java.lang.Object
    A rule ties together an event, condition and action. It also maintains a TypeGroup identifying type information derived from these components.

    • Field Summary

      Fields 
      Modifier and Type Field Description
      private AccessEnabler accessEnabler
      auxiliary to manage access to normally inaccessible fields
      private java.util.List<AccessibleConstructorInvoker> accessibleConstructorInvokers
      a list of constructor invoker objects used to enable rule code to invoke non-public constructors
      private java.util.List<AccessibleFieldGetter> accessibleFieldGetters
      a list of field getter objects used to enable rule code to read non-public fields
      private java.util.List<AccessibleFieldSetter> accessibleFieldSetters
      a list of field setter objects used by to enable rule code to write non-public fields
      private java.util.List<AccessibleMethodInvoker> accessibleMethodInvokers
      a list of method invoker objects used to enable rule code to invoke non-public methods
      private Action action
      the parsed condition derived from the script for this rule
      private Bindings bindings
      the set of bindings derived from the event supplemented, post type checking, with bindings derived from the trigger method.
      private boolean checked
      flag set to true only after the rule has been type checked
      private boolean checkFailed
      flag set to true only after the rule has been type checked successfully
      private Condition condition
      the parsed condition derived from the script for this rule
      private static boolean debugParse
      flag true if debugging of rule parsing is desired and false if it should not be performed
      private Event event
      the parsed event derived from the script for this rule
      private java.lang.Class helperClass
      a helper class which defines the builtin methods available to this rule -- by default Helper
      private java.lang.Class helperImplementationClass
      an extension of the helper class which implements the methods of interface RuleHelper -- by default InterpretedHelper.
      private java.lang.String helperImplementationClassName
      the name of the helper implementation class in internal format
      private java.lang.ClassLoader helperLoader
      the class loader for the help adapter
      private HelperManager helperManager
      lifecycle event manager for rule helpers
      private java.lang.String helperToUse
      the name of the helper class for this rule
      private java.lang.String key
      the key under which this rule is indexed in the rule key map.
      private java.lang.String name
      the name of this rule supplied in the rule script
      private static int nextId
      a counter used to ensure rule identifiers are unique
      private Type returnType
      return type of the rule's trigger method
      private static java.util.HashMap<java.lang.String,​Rule> ruleKeyMap
      a hash map used to identify rules from their keys
      private RuleScript ruleScript
      the script defining this rule
      private int triggerAccess
      the access mode for the target method defined using flag bits defined in the asm Opcodes class.
      private java.lang.String triggerClass
      the fully qualified name of the class to which this rule has been attached by the code transformation package.
      private java.lang.String triggerDescriptor
      the descriptor of the trigger method in which a trigger call for this rule has been inserted by the code transformation package.
      private java.lang.String[] triggerExceptions
      the name sof all the exceptions declared by the trigger method in which a trigger call for this rule has been inserted by the code transformation package.
      private java.lang.ClassLoader triggerLoader
      the class loader for the trigger class
      private java.lang.String triggerMethod
      the name of the trigger method in which a trigger call for this rule has been inserted by the code transformation package, not including the descriptor component.
      private TypeGroup typeGroup
      the set of types employed by the rule, inlcuding types referenced by abbreviated name (without mentioning the package), array type sand/or their base types and standard builtin types.

    • Field Detail

      • helperToUse

        private final java.lang.String helperToUse
        the name of the helper class for this rule

      • ruleScript

        private RuleScript ruleScript
        the script defining this rule

      • name

        private java.lang.String name
        the name of this rule supplied in the rule script

      • triggerLoader

        private java.lang.ClassLoader triggerLoader
        the class loader for the trigger class

      • helperLoader

        private java.lang.ClassLoader helperLoader
        the class loader for the help adapter

      • event

        private Event event
        the parsed event derived from the script for this rule

      • condition

        private Condition condition
        the parsed condition derived from the script for this rule

      • action

        private Action action
        the parsed condition derived from the script for this rule

      • bindings

        private Bindings bindings
        the set of bindings derived from the event supplemented, post type checking, with bindings derived from the trigger method. we may eventually also be able to install bindings for method local variables. Note that use of the name bindings is slightly misleading since this instance identifies the name and type of each of the available bound variables and, in the case of an event binding, the expression to be evaluated in order to initialise the variable. It does not identify any bound values for the variable. These are stored per rule-firing in a set attached to the Helper instance used to implement the execute method for the rule.

      • triggerClass

        private java.lang.String triggerClass
        the fully qualified name of the class to which this rule has been attached by the code transformation package. note that this may not be the same as targetClass since the latter may not specify a package.

      • triggerMethod

        private java.lang.String triggerMethod
        the name of the trigger method in which a trigger call for this rule has been inserted by the code transformation package, not including the descriptor component. note that this may not be the same as the targetMethod since the latter may include an argument list.

      • triggerDescriptor

        private java.lang.String triggerDescriptor
        the descriptor of the trigger method in which a trigger call for this rule has been inserted by the code transformation package. note that this will be in encoded format e.g. "(IZ)V" rather than declaration format e.g. "void (int, boolean)"

      • triggerExceptions

        private java.lang.String[] triggerExceptions
        the name sof all the exceptions declared by the trigger method in which a trigger call for this rule has been inserted by the code transformation package.

      • triggerAccess

        private int triggerAccess
        the access mode for the target method defined using flag bits defined in the asm Opcodes class.

      • typeGroup

        private TypeGroup typeGroup
        the set of types employed by the rule, inlcuding types referenced by abbreviated name (without mentioning the package), array type sand/or their base types and standard builtin types.

      • checked

        private boolean checked
        flag set to true only after the rule has been type checked

      • checkFailed

        private boolean checkFailed
        flag set to true only after the rule has been type checked successfully

      • returnType

        private Type returnType
        return type of the rule's trigger method

      • key

        private java.lang.String key
        the key under which this rule is indexed in the rule key map.

      • helperManager

        private HelperManager helperManager
        lifecycle event manager for rule helpers

      • accessEnabler

        private AccessEnabler accessEnabler
        auxiliary to manage access to normally inaccessible fields

      • accessibleFieldGetters

        private java.util.List<AccessibleFieldGetter> accessibleFieldGetters
        a list of field getter objects used to enable rule code to read non-public fields

      • accessibleFieldSetters

        private java.util.List<AccessibleFieldSetter> accessibleFieldSetters
        a list of field setter objects used by to enable rule code to write non-public fields

      • accessibleMethodInvokers

        private java.util.List<AccessibleMethodInvoker> accessibleMethodInvokers
        a list of method invoker objects used to enable rule code to invoke non-public methods

      • accessibleConstructorInvokers

        private java.util.List<AccessibleConstructorInvoker> accessibleConstructorInvokers
        a list of constructor invoker objects used to enable rule code to invoke non-public constructors

      • ruleKeyMap

        private static java.util.HashMap<java.lang.String,​Rule> ruleKeyMap
        a hash map used to identify rules from their keys

      • nextId

        private static int nextId
        a counter used to ensure rule identifiers are unique

      • helperClass

        private java.lang.Class helperClass
        a helper class which defines the builtin methods available to this rule -- by default Helper

      • helperImplementationClass

        private java.lang.Class helperImplementationClass
        an extension of the helper class which implements the methods of interface RuleHelper -- by default InterpretedHelper. This is the class which is instantiated and used as the target for an execute operation.

      • helperImplementationClassName

        private java.lang.String helperImplementationClassName
        the name of the helper implementation class in internal format

      • debugParse

        private static boolean debugParse
        flag true if debugging of rule parsing is desired and false if it should not be performed

    • Method Detail

      • getTypeGroup

        public TypeGroup getTypeGroup()

      • getBindings

        public Bindings getBindings()

      • getName

        public java.lang.String getName()

      • getTargetClass

        public java.lang.String getTargetClass()

      • getTargetMethod

        public java.lang.String getTargetMethod()

      • getTargetLocation

        public Location getTargetLocation()

      • isOverride

        public boolean isOverride()

      • isInterface

        public boolean isInterface()

      • getLine

        public int getLine()
        retrieve the start line for the rule
        Returns:
        the start line for the rule

      • getFile

        public java.lang.String getFile()
        retrieve the name of the file containing this rule
        Returns:
        the name of the file containing this rule

      • getEvent

        public Event getEvent()

      • getCondition

        public Condition getCondition()

      • getAction

        public Action getAction()

      • getTriggerClass

        public java.lang.String getTriggerClass()

      • getTriggerMethod

        public java.lang.String getTriggerMethod()

      • getTriggerDescriptor

        public java.lang.String getTriggerDescriptor()

      • getReturnType

        public Type getReturnType()

      • getLoader

        public java.lang.ClassLoader getLoader()
        get the class loader of the target class for the rule
        Returns:
        the class loader

      • getHelperLoader

        public java.lang.ClassLoader getHelperLoader()
        get the class loader of the rule-specific helper adapter class
        Returns:
        the class loader

      • setTypeInfo

        public void setTypeInfo​(java.lang.String className,
                        int access,
                        java.lang.String methodName,
                        java.lang.String desc,
                        java.lang.String[] exceptions)

      • isChecked

        public boolean isChecked()
        has this rule been typechecked and/or compiled
        Returns:
        true if this rule has been typechecked and/or compiled otherwise false

      • isCheckFailed

        public boolean isCheckFailed()
        has this rule failed to typecheck or compile
        Returns:
        true if this rule has failed to typecheck or compile otherwise false

      • isCheckedOk

        public boolean isCheckedOk()
        has this rule been typechecked and compiled without error.
        Returns:
        true if this rule has been typechecked and compiled without error otherwise false

      • disableTriggersInternal

        public static boolean disableTriggersInternal()
        disable triggering of rules inside the current thread. this is the version called internally after returning from a method call in a rule binding, condition or action.
        Returns:
        true if triggering was previously enabled and false if it was already disabled

      • enableTriggersInternal

        public static boolean enableTriggersInternal()
        enable triggering of rules inside the current thread n.b. this is called internally by the rule engine before it executes a method call in a rule binding, condition or action. it will not enable triggers if they have been switched off by an earlier call to userDisableTriggers.
        Returns:
        true if triggering was previously enabled and false if it was already disabled

      • disableTriggers

        public static boolean disableTriggers()
        disable triggering of rules inside the current thread. this is the version which should be called from a Helper class to ensure that subsequent method invocatiosn during execution of the current rule bindings, condition or action do not recursively trigger rules. It ensures that subsequent calls to enableTriggers have no effect. The effect lasts until the end of processing for the current rule when resetTriggers is called.
        Returns:
        true if triggering was previously enabled and false if it was already disabled

      • enableTriggers

        public static boolean enableTriggers()
        enable triggering of rules inside the current thread. this is called internally by the rule engine after rule execution has completed. it will re-enable triggers even if they have been switched off by an earlier call to userDisableTriggers. It is also called by the default helper to reverse the effect of calling userDisableTriggers.
        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

      • ensureTypeCheckedCompiled

        private boolean ensureTypeCheckedCompiled()
        typecheck and then compile this rule unless either action has been tried before
        Returns:
        true if the rule successfully type checks and then compiles under this call or a previous call or false if either operation has previously failed or fails under this call.

      • typeCheck

        public void typeCheck()
               throws TypeException
        type check this rule
        Throws:
        TypeException - if the rule contains type errors

      • compile

        public void compile()
             throws CompileException
        install helper class used to execute this rule. this may involve generating a compiled helper class for the rule and, if compilation to bytecode is enabled, generating bytecode for a method of this class used to execute the rule binding, condition and action expressions. If the rule employ sthe default helper without enabling compilation to bytecode then no class need be generated. the installed helper class will be the predefined class InterpretedHelper.
        Throws:
        CompileException - if the rule cannot be compiled

      • isCompileToBytecode

        private boolean isCompileToBytecode()
        is this rule marked for compilation to bytecode
        Returns:
        true if this rule is marked for compilation to bytecode otherwise false

      • doCompileToBytecode

        private boolean doCompileToBytecode()
        should this rule actually be compiled to bytecode
        Returns:
        true if this rule should actually be compiled to bytecode otherwise false this method allows compilation to be overridden when the trigger class is an inner class, avoiding the most common case where trying to use bytecode will result in a verify error. it only applies for overriding or interface rules because asking for direct injection into an inner class with compilation enabled is a mistake which deserves to be punished with failure

      • installParameters

        private void installParameters​(boolean isStatic,
                               java.lang.String className)
                        throws TypeException
        Throws:
        TypeException

      • execute

        public static void execute​(java.lang.String key,
                           java.lang.Object recipient,
                           java.lang.Object[] args)
                    throws ExecuteException
        forward an execute request a rule identified by its unique key
        Parameters:
        key - a string key identifying the rule instance to be fired
        recipient - the recipient of the method from which execution of the rule was triggered or null if it was a static method
        args - the arguments of the method from which execution of the rule was triggered
        Throws:
        ExecuteException

      • execute

        private void execute​(java.lang.Object recipient,
                     java.lang.Object[] args)
              throws ExecuteException
        forward an execute request to a helper instance associated with the rule
        Parameters:
        recipient - the recipient of the method from which execution of this rule was triggered or null if it was a static method
        args - the arguments of the method from which execution of this rule was triggered
        Throws:
        ExecuteException

      • getKey

        public java.lang.String getKey()
        called when a trigger is compiled for the rule to provide a String key which can be used at execution time to obtain a handle on the rule instance
        Returns:
        a key which can be used later to obtain a reference to the rule

      • purge

        public void purge()
        delete any reference to the rule from the rule map

      • nextId

        private static int nextId()
        a method to return the next available counter for use in constructing a key for the rule
        Returns:
        the next id

      • toString

        public java.lang.String toString()
        generate a string representation of the rule
        Overrides:
        toString in class java.lang.Object
        Returns:
        a string representation of the rule

      • getHelperClass

        public java.lang.Class getHelperClass()
        a getter allowing the helper class for the rule to be identified
        Returns:
        the helper

      • ensureHelperClass

        private void ensureHelperClass()
                        throws TypeException
        method called at start of type check to ensure helper class can be loaded
        Throws:
        TypeException

      • getHelperImplementationClassName

        public java.lang.String getHelperImplementationClassName()
        a getter allowing the helper implementation class name for the rule to be identified
        Returns:
        the helper

      • installed

        public void installed()
        method called when the rule has been successfully injected into a class, type checked and compiled. it passes the message on to the Transformer so it can perform helper lifecycle management.

      • uninstalled

        public void uninstalled()
        method called when the rule has been uninstalled after previously being successfully injected into a class, type checked and compiled. it passes the message on to the Transformer so it can perform helper lifecycle management.

      • requiresAccess

        public boolean requiresAccess​(Type type)

      • requiresAccess

        public boolean requiresAccess​(java.lang.reflect.Field field)

      • requiresAccess

        public boolean requiresAccess​(java.lang.reflect.Method method)

      • addAccessibleFieldGetter

        public int addAccessibleFieldGetter​(java.lang.reflect.Field field)

      • addAccessibleFieldSetter

        public int addAccessibleFieldSetter​(java.lang.reflect.Field field)

      • addAccessibleMethodInvoker

        public int addAccessibleMethodInvoker​(java.lang.reflect.Method method)

      • addAccessibleConstructorInvoker

        public int addAccessibleConstructorInvoker​(java.lang.reflect.Constructor constructor)

      • setAccessibleField

        public void setAccessibleField​(java.lang.Object owner,
                               java.lang.Object value,
                               int fieldIndex)
                        throws ExecuteException
        Throws:
        ExecuteException

      • invokeAccessibleMethod

        public java.lang.Object invokeAccessibleMethod​(java.lang.Object target,
                                               java.lang.Object[] args,
                                               int methodIndex)

      • invokeAccessibleConstructor

        public void invokeAccessibleConstructor​(java.lang.Object[] args,
                                        int methodIndex)

      • getObjectSize

        public long getObjectSize​(java.lang.Object o)