Package org.jboss.byteman.rule
Class Rule
java.lang.Object
org.jboss.byteman.rule.Rule
A rule ties together an event, condition and action. It also maintains a TypeGroup
identifying type information derived from these components.
-
Field Summary
FieldsModifier and TypeFieldDescriptionprivate AccessEnabler
auxiliary to manage access to normally inaccessible fieldsprivate List
<AccessibleConstructorInvoker> a list of constructor invoker objects used to enable rule code to invoke non-public constructorsprivate List
<AccessibleFieldGetter> a list of field getter objects used to enable rule code to read non-public fieldsprivate List
<AccessibleFieldSetter> a list of field setter objects used by to enable rule code to write non-public fieldsprivate List
<AccessibleMethodInvoker> a list of method invoker objects used to enable rule code to invoke non-public methodsprivate Action
the parsed condition derived from the script for this ruleprivate Bindings
the set of bindings derived from the event supplemented, post type checking, with bindings derived from the trigger method.private boolean
flag set to true only after the rule has been type checkedprivate boolean
flag set to true only after the rule has been type checked successfullyprivate Condition
the parsed condition derived from the script for this ruleprivate static boolean
flag true if debugging of rule parsing is desired and false if it should not be performedprivate Event
the parsed event derived from the script for this ruleprivate Class
a helper class which defines the builtin methods available to this rule -- by default Helperprivate Class
an extension of the helper class which implements the methods of interface RuleHelper -- by default InterpretedHelper.private String
the name of the helper implementation class in internal formatprivate ClassLoader
the class loader for the help adapterprivate HelperManager
lifecycle event manager for rule helpersprivate final String
the name of the helper class for this ruleprivate String
the key under which this rule is indexed in the rule key map.private String
the name of this rule supplied in the rule scriptprivate static int
a counter used to ensure rule identifiers are uniqueprivate Type
return type of the rule's trigger methoda hash map used to identify rules from their keysprivate RuleScript
the script defining this ruleprivate int
the access mode for the target method defined using flag bits defined in the asm Opcodes class.private String
the fully qualified name of the class to which this rule has been attached by the code transformation package.private String
the descriptor of the trigger method in which a trigger call for this rule has been inserted by the code transformation package.private String[]
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 ClassLoader
the class loader for the trigger classprivate String
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
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
ConstructorsModifierConstructorDescriptionprivate
Rule
(RuleScript ruleScript, ClassLoader loader, HelperManager helperManager, AccessEnabler accessEnabler) -
Method Summary
Modifier and TypeMethodDescriptionint
addAccessibleConstructorInvoker
(Constructor constructor) int
addAccessibleFieldGetter
(Field field) int
addAccessibleFieldSetter
(Field field) int
addAccessibleMethodInvoker
(Method method) void
compile()
install helper class used to execute this rule.static Rule
create
(RuleScript ruleScript, ClassLoader loader, HelperManager helperManager, AccessEnabler accessEnabler) static boolean
disable triggering of rules inside the current thread.static boolean
disable triggering of rules inside the current thread.private boolean
should this rule actually be compiled to bytecodestatic boolean
enable triggering of rules inside the current thread.static boolean
enable triggering of rules inside the current thread n.b.private void
method called at start of type check to ensure helper class can be loadedprivate boolean
typecheck and then compile this rule unless either action has been tried beforeprivate void
forward an execute request to a helper instance associated with the rulestatic void
forward an execute request a rule identified by its unique keygetAccessibleField
(Object owner, int fieldIndex) getEvent()
getFile()
retrieve the name of the file containing this rulea getter allowing the helper class for the rule to be identifieda getter allowing the helper implementation class name for the rule to be identifiedget the class loader of the rule-specific helper adapter classgetKey()
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 instanceint
getLine()
retrieve the start line for the ruleget the class loader of the target class for the rulegetName()
long
void
method called when the rule has been successfully injected into a class, type checked and compiled.private void
installParameters
(boolean isStatic, String className) void
invokeAccessibleConstructor
(Object[] args, int methodIndex) invokeAccessibleMethod
(Object target, Object[] args, int methodIndex) boolean
has this rule been typechecked and/or compiledboolean
has this rule been typechecked and compiled without error.boolean
has this rule failed to typecheck or compileprivate boolean
is this rule marked for compilation to bytecodeboolean
boolean
static boolean
check if triggering of rules is enabled inside the current threadprivate static int
nextId()
a method to return the next available counter for use in constructing a key for the rulevoid
purge()
delete any reference to the rule from the rule mapboolean
requiresAccess
(Field field) boolean
requiresAccess
(Method method) boolean
requiresAccess
(Type type) void
setAccessibleField
(Object owner, Object value, int fieldIndex) void
void
setCondition
(String conditionSpec) void
void
setTypeInfo
(String className, int access, String methodName, String desc, String[] exceptions) toString()
generate a string representation of the rulevoid
type check this rulevoid
method called when the rule has been uninstalled after previously being successfully injected into a class, type checked and compiled.
-
Field Details
-
helperToUse
the name of the helper class for this rule -
ruleScript
the script defining this rule -
name
the name of this rule supplied in the rule script -
triggerLoader
the class loader for the trigger class -
helperLoader
the class loader for the help adapter -
event
the parsed event derived from the script for this rule -
condition
the parsed condition derived from the script for this rule -
action
the parsed condition derived from the script for this rule -
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
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
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
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
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 triggerAccessthe access mode for the target method defined using flag bits defined in the asm Opcodes class. -
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 checkedflag set to true only after the rule has been type checked -
checkFailed
private boolean checkFailedflag set to true only after the rule has been type checked successfully -
returnType
return type of the rule's trigger method -
key
the key under which this rule is indexed in the rule key map. -
helperManager
lifecycle event manager for rule helpers -
accessEnabler
auxiliary to manage access to normally inaccessible fields -
accessibleFieldGetters
a list of field getter objects used to enable rule code to read non-public fields -
accessibleFieldSetters
a list of field setter objects used by to enable rule code to write non-public fields -
accessibleMethodInvokers
a list of method invoker objects used to enable rule code to invoke non-public methods -
accessibleConstructorInvokers
a list of constructor invoker objects used to enable rule code to invoke non-public constructors -
ruleKeyMap
a hash map used to identify rules from their keys -
nextId
private static int nextIda counter used to ensure rule identifiers are unique -
helperClass
a helper class which defines the builtin methods available to this rule -- by default Helper -
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
the name of the helper implementation class in internal format -
debugParse
private static boolean debugParseflag true if debugging of rule parsing is desired and false if it should not be performed
-
-
Constructor Details
-
Rule
private Rule(RuleScript ruleScript, ClassLoader loader, HelperManager helperManager, AccessEnabler accessEnabler) throws ParseException, TypeException, CompileException
-
-
Method Details
-
getTypeGroup
-
getBindings
-
getName
-
getTargetClass
-
getTargetMethod
-
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
retrieve the name of the file containing this rule- Returns:
- the name of the file containing this rule
-
getEvent
-
getCondition
-
getAction
-
getTriggerClass
-
getTriggerMethod
-
getTriggerDescriptor
-
getReturnType
-
getLoader
get the class loader of the target class for the rule- Returns:
- the class loader
-
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 -
setEvent
- Throws:
ParseException
TypeException
-
setCondition
- Throws:
ParseException
TypeException
-
setAction
- Throws:
ParseException
TypeException
-
setTypeInfo
-
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
type check this rule- Throws:
TypeException
- if the rule contains type errors
-
getModuleSystem
-
compile
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
- Throws:
TypeException
-
execute
forward an execute request a rule identified by its unique key- Parameters:
key
- a string key identifying the rule instance to be firedrecipient
- the recipient of the method from which execution of the rule was triggered or null if it was a static methodargs
- the arguments of the method from which execution of the rule was triggered- Throws:
ExecuteException
-
execute
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 methodargs
- the arguments of the method from which execution of this rule was triggered- Throws:
ExecuteException
-
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
generate a string representation of the rule -
getHelperClass
a getter allowing the helper class for the rule to be identified- Returns:
- the helper
-
ensureHelperClass
method called at start of type check to ensure helper class can be loaded- Throws:
TypeException
-
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
-
requiresAccess
-
requiresAccess
-
addAccessibleFieldGetter
-
addAccessibleFieldSetter
-
addAccessibleMethodInvoker
-
addAccessibleConstructorInvoker
-
getAccessibleField
- Throws:
ExecuteException
-
setAccessibleField
- Throws:
ExecuteException
-
invokeAccessibleMethod
-
invokeAccessibleConstructor
-
getObjectSize
-