org.jboss.byteman.rule
Class Rule

java.lang.Object
  extended by org.jboss.byteman.rule.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
private  java.util.List<java.lang.reflect.Field> accessibleFields
          a list of field objects used by compiled code to enable rule code to access non-public fields
private  java.util.List<java.lang.reflect.Method> accessibleMethods
          a list of method objects used by compiled code to enable rule code to access 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  HelperManager helperManager
          lifecycle event manager for rule helpers
private  java.lang.String key
          the key under which this rule is indexed in the rule key map.
private  java.lang.ClassLoader loader
          the class loader for the target class
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.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.
 
Constructor Summary
private Rule(RuleScript ruleScript, java.lang.ClassLoader loader, HelperManager helperManager)
           
 
Method Summary
 int addAccessibleField(java.lang.reflect.Field field)
           
 int addAccessibleMethod(java.lang.reflect.Method method)
           
 void compile()
          install helper class used to execute this rule.
private static boolean compileRules()
           
static Rule create(RuleScript ruleScript, java.lang.ClassLoader loader, HelperManager helperManager)
           
static boolean disableTriggers()
          disable triggering of rules inside the current thread.
static boolean disableTriggersInternal()
          disable triggering of rules inside the current thread.
static boolean enableTriggers()
          enable triggering of rules inside the current thread.
static boolean enableTriggersInternal()
          enable triggering of rules inside the current thread n.b.
private  boolean ensureTypeCheckedCompiled()
          typecheck and then compile this rule unless either action has been tried before
private  void execute(java.lang.Object recipient, java.lang.Object[] args)
          forward an execute request to a helper instance associated with the rule
static void execute(java.lang.String key, java.lang.Object recipient, java.lang.Object[] args)
          forward an execute request a rule identified by its unique key
 java.lang.Object getAccessibleField(java.lang.Object owner, int fieldIndex)
           
 Action getAction()
           
 Bindings getBindings()
           
 Condition getCondition()
           
 Event getEvent()
           
 java.lang.String getFile()
          retrieve the name of the file containing this rule
 java.lang.Class getHelperClass()
          a getter allowing the helper class for the rule to be identified
 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
 int getLine()
          retrieve the start line for the rule
 java.lang.ClassLoader getLoader()
          get the class loader of the target class for the rule
 java.lang.String getName()
           
 Type getReturnType()
           
 java.lang.String getTargetClass()
           
 Location getTargetLocation()
           
 java.lang.String getTargetMethod()
           
 java.lang.String getTriggerClass()
           
 java.lang.String getTriggerDescriptor()
           
 java.lang.String getTriggerMethod()
           
 TypeGroup getTypeGroup()
           
private  void installed()
          method called when the rule has been successfully injected into a class, type checked and compiled.
private  void installParameters(boolean isStatic, java.lang.String className)
           
 java.lang.Object invokeAccessibleMethod(java.lang.Object target, java.lang.Object[] args, int methodIndex)
           
 boolean isChecked()
          has this rule been typechecked and/or compiled
 boolean isCheckedOk()
          has this rule been typechecked and compiled without error.
 boolean isCheckFailed()
          has this rule failed to typecheck or compile
private  boolean isCompileToBytecode()
          should rules be compiled to bytecode
 boolean isInterface()
           
 boolean isOverride()
           
static boolean isTriggeringEnabled()
          check if triggering of rules is enabled inside the current thread
 java.lang.String lookupKey()
          return the key under which this rule has been indexed in the rule key map
private static int nextId()
          a method to return the next available counter for use in constructing a key for the rule
 void purge()
          delete any reference to the rule from the rule map
 void setAccessibleField(java.lang.Object owner, java.lang.Object value, int fieldIndex)
           
 void setAction(java.lang.String actionSpec)
           
 void setCondition(java.lang.String conditionSpec)
           
 void setEvent(java.lang.String eventSpec)
           
 void setTypeInfo(java.lang.String className, int access, java.lang.String methodName, java.lang.String desc, java.lang.String[] exceptions)
           
 java.lang.String toString()
          generate a string representation of the rule
 void typeCheck()
          type check this rule
private  void uninstalled()
          method called when the rule has been uninstalled after previously being successfully injected into a class, type checked and compiled.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

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


loader

private java.lang.ClassLoader loader
the class loader for the target class


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


accessibleFields

private java.util.List<java.lang.reflect.Field> accessibleFields
a list of field objects used by compiled code to enable rule code to access non-public fields


accessibleMethods

private java.util.List<java.lang.reflect.Method> accessibleMethods
a list of method objects used by compiled code to enable rule code to access non-public methods


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.


debugParse

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

Constructor Detail

Rule

private Rule(RuleScript ruleScript,
             java.lang.ClassLoader loader,
             HelperManager helperManager)
      throws ParseException,
             TypeException,
             CompileException
Throws:
ParseException
TypeException
CompileException
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:

create

public static Rule create(RuleScript ruleScript,
                          java.lang.ClassLoader loader,
                          HelperManager helperManager)
                   throws ParseException,
                          TypeException,
                          CompileException
Throws:
ParseException
TypeException
CompileException

setEvent

public void setEvent(java.lang.String eventSpec)
              throws ParseException,
                     TypeException
Throws:
ParseException
TypeException

setCondition

public void setCondition(java.lang.String conditionSpec)
                  throws ParseException,
                         TypeException
Throws:
ParseException
TypeException

setAction

public void setAction(java.lang.String actionSpec)
               throws ParseException,
                      TypeException
Throws:
ParseException
TypeException

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 ruele 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()
should rules be compiled to bytecode

Returns:
true if rules should be compiled to bytecode otherwise false

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

lookupKey

public java.lang.String lookupKey()
return the key under which this rule has been indexed in the rule key map

Returns:

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:

compileRules

private static boolean compileRules()

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:

installed

private 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

private 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.


addAccessibleField

public int addAccessibleField(java.lang.reflect.Field field)

addAccessibleMethod

public int addAccessibleMethod(java.lang.reflect.Method method)

getAccessibleField

public java.lang.Object getAccessibleField(java.lang.Object owner,
                                           int fieldIndex)
                                    throws ExecuteException
Throws:
ExecuteException

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)