Class Rule

java.lang.Object
org.jboss.byteman.rule.Rule

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

    • helperToUse

      private final String helperToUse
      the name of the helper class for this rule
    • ruleScript

      private RuleScript ruleScript
      the script defining this rule
    • name

      private String name
      the name of this rule supplied in the rule script
    • triggerLoader

      private ClassLoader triggerLoader
      the class loader for the trigger class
    • helperLoader

      private 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 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 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 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 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 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 List<AccessibleFieldGetter> accessibleFieldGetters
      a list of field getter objects used to enable rule code to read non-public fields
    • accessibleFieldSetters

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

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

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

      private static HashMap<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 Class helperClass
      a helper class which defines the builtin methods available to this rule -- by default Helper
    • helperImplementationClass

      private 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 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
  • Constructor Details

  • Method Details

    • getTypeGroup

      public TypeGroup getTypeGroup()
    • getBindings

      public Bindings getBindings()
    • getName

      public String getName()
    • getTargetClass

      public String getTargetClass()
    • getTargetMethod

      public 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 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 String getTriggerClass()
    • getTriggerMethod

      public String getTriggerMethod()
    • getTriggerDescriptor

      public String getTriggerDescriptor()
    • getReturnType

      public Type getReturnType()
    • getLoader

      public ClassLoader getLoader()
      get the class loader of the target class for the rule
      Returns:
      the class loader
    • getHelperLoader

      public ClassLoader getHelperLoader()
      get the class loader of the rule-specific helper adapter class
      Returns:
      the class loader
    • create

      public static Rule create(RuleScript ruleScript, ClassLoader loader, HelperManager helperManager, AccessEnabler accessEnabler) throws ParseException, TypeException, CompileException
      Throws:
      ParseException
      TypeException
      CompileException
    • setEvent

      public void setEvent(String eventSpec) throws ParseException, TypeException
      Throws:
      ParseException
      TypeException
    • setCondition

      public void setCondition(String conditionSpec) throws ParseException, TypeException
      Throws:
      ParseException
      TypeException
    • setAction

      public void setAction(String actionSpec) throws ParseException, TypeException
      Throws:
      ParseException
      TypeException
    • setTypeInfo

      public void setTypeInfo(String className, int access, String methodName, String desc, 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
    • getModuleSystem

      public ModuleSystem getModuleSystem()
    • 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, String className) throws TypeException
      Throws:
      TypeException
    • execute

      public static void execute(String key, Object recipient, 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(Object recipient, 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 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 String toString()
      generate a string representation of the rule
      Overrides:
      toString in class Object
      Returns:
      a string representation of the rule
    • getHelperClass

      public 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 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(Field field)
    • requiresAccess

      public boolean requiresAccess(Method method)
    • addAccessibleFieldGetter

      public int addAccessibleFieldGetter(Field field)
    • addAccessibleFieldSetter

      public int addAccessibleFieldSetter(Field field)
    • addAccessibleMethodInvoker

      public int addAccessibleMethodInvoker(Method method)
    • addAccessibleConstructorInvoker

      public int addAccessibleConstructorInvoker(Constructor constructor)
    • getAccessibleField

      public Object getAccessibleField(Object owner, int fieldIndex) throws ExecuteException
      Throws:
      ExecuteException
    • setAccessibleField

      public void setAccessibleField(Object owner, Object value, int fieldIndex) throws ExecuteException
      Throws:
      ExecuteException
    • invokeAccessibleMethod

      public Object invokeAccessibleMethod(Object target, Object[] args, int methodIndex)
    • invokeAccessibleConstructor

      public void invokeAccessibleConstructor(Object[] args, int methodIndex)
    • getObjectSize

      public long getObjectSize(Object o)