Class RuleScript


  • public class RuleScript
    extends java.lang.Object
    details of a single rule obtained from a rule file. RuleScript instances are stored in the script repository attached to the transformer. They are used to generate Rule instances at transform time. The RuleScript contains a list of Transforms which detail failed or successful transforms performed using the script.
    • Field Summary

      Fields 
      Modifier and Type Field Description
      private boolean compileToBytecode
      true if this rule should be compiled to bytecode otherwise false
      private boolean deleted
      this is set to true if the rule is dynamically deleted or updated so as to inhibit execution of trigger code between the delete/update and recompilation/reinstatement of the affected bytecode.
      private java.lang.String file
      the name of the file from which the rule has been loaded, if defined, or some suitable dummy string if it was noti obtained from a file
      private java.lang.String[] imports
      the details of the IMPORT lines
      private boolean isInterface
      true if the target is an interface or false if the target is a class, in the former case the rule should be injected into methods of classes which implement the interface.
      private boolean isOverride
      true if the rule should be injected into overriding implementations of the target method false if it should only be injected into the implementation defined by the target class or, in the case of an interface rule, by the class directly implementing the target interface
      private java.lang.String key_base
      base string from which to construct rule injection keys
      private java.util.HashMap<java.lang.String,​java.lang.String> keySet
      hash map used to lookup a key used at injection time to identify a rule cloned from this script for injection into a specific trigger method.
      private int line
      the line number at which the rule text starts
      private java.lang.String name
      the name of the rule from which this script is derived
      private static int nextId
      a counter used to ensure rule identifiers are unique
      private java.lang.String ruleText
      the text of the rule's BIND IF and DO clauses which are parsed using a grammar based parser
      private java.lang.String targetClass
      the name supplied in the CLASS or INTERFACE clause of the rule identifying which class(es) triggers should be injected into
      private java.lang.String targetHelper
      the name of a class whose public instance methods define the built-in methods available for use in the rule body
      private Location targetLocation
      identifies the location in the method if the trigger point at which the rule code should be injected.
      private java.lang.String targetMethod
      the name of the method of the target class or interface into which the rule should be injected
      private java.util.List<TransformSet> transformSets
      a list of records identifying transforms associated with a specific class.
    • Constructor Summary

      Constructors 
      Constructor Description
      RuleScript​(java.lang.String name, java.lang.String targetClass, boolean isInterface, boolean isOverride, java.lang.String targetMethod, java.lang.String targetHelper, java.lang.String[] imports, Location targetLocation, java.lang.String ruleText, int line, java.lang.String file, boolean compileToBytecode)
      standard constructor for a rule
    • Method Summary

      All Methods Static Methods Instance Methods Concrete Methods 
      Modifier and Type Method Description
      java.util.List<Transform> allTransforms()  
      TransformSet ensureTransformSet​(java.lang.ClassLoader loader, java.lang.String triggerClass, Rule installedRule)  
      java.lang.String getFile()  
      java.lang.String[] getImports()  
      int getLine()  
      java.lang.String getName()  
      java.lang.String getRuleKey​(java.lang.String triggerClassName, java.lang.String triggerMethodName, java.lang.String triggerMethodDescriptor, java.lang.ClassLoader loader)  
      java.lang.String getRuleText()  
      java.lang.String getTargetClass()  
      java.lang.String getTargetHelper()  
      Location getTargetLocation()  
      java.lang.String getTargetMethod()  
      java.util.List<TransformSet> getTransformSets()
      getter for list of transforms applied for this script.
      int getTransformSetsCount()
      return a count of the number of transforms applied for this script.
      boolean hasTransform​(java.lang.Class<?> clazz)
      check whether a rule has been used to transform a specific class.
      boolean isCompileToBytecode()  
      boolean isDeleted()
      called when indexing a script to ensure that it has not already been deleted.
      boolean isInterface()  
      boolean isOverride()  
      TransformSet lookupTransformSet​(java.lang.ClassLoader loader, java.lang.String triggerClass)  
      private static int nextId()
      a method to return the next available counter for use in constructing a key for a rule
      void purge()
      uninstall all transforms associated with this script.
      void purge​(java.lang.ClassLoader loader, java.lang.String triggerClassName)
      delete any transforms associated with a specific trigger class and loader for deletion.
      boolean recordCompile​(Rule rule, java.lang.String triggerClass, java.lang.ClassLoader loader, boolean successful, java.lang.String detail)
      record the fact that a rule has been compiled with or without success
      boolean recordFailedTransform​(java.lang.ClassLoader loader, java.lang.String internalClassName, java.lang.Throwable th)
      record the fact that an error was thrown when attempting to transform a given class using this rule script
      boolean recordTransform​(java.lang.ClassLoader loader, java.lang.String internalClassName, java.lang.String triggerMethodName, java.lang.String desc, Rule rule, java.lang.Throwable th)
      record the fact that a trigger call has succeeded or else failed to install into bytecode associated with a specific class and loader
      boolean setDeleted()
      invoked by the scriptmanager when a rule is redefined to inhibit further transformations via this script
      java.lang.String toString()  
      void writeTo​(java.io.PrintWriter writer)  
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
    • Field Detail

      • nextId

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

        private java.lang.String name
        the name of the rule from which this script is derived
      • targetClass

        private java.lang.String targetClass
        the name supplied in the CLASS or INTERFACE clause of the rule identifying which class(es) triggers should be injected into
      • isInterface

        private boolean isInterface
        true if the target is an interface or false if the target is a class, in the former case the rule should be injected into methods of classes which implement the interface.
      • targetMethod

        private java.lang.String targetMethod
        the name of the method of the target class or interface into which the rule should be injected
      • isOverride

        private boolean isOverride
        true if the rule should be injected into overriding implementations of the target method false if it should only be injected into the implementation defined by the target class or, in the case of an interface rule, by the class directly implementing the target interface
      • targetHelper

        private java.lang.String targetHelper
        the name of a class whose public instance methods define the built-in methods available for use in the rule body
      • imports

        private java.lang.String[] imports
        the details of the IMPORT lines
      • targetLocation

        private Location targetLocation
        identifies the location in the method if the trigger point at which the rule code should be injected. note that for an AT EXIT rule there may be multiple trigger points.
      • ruleText

        private java.lang.String ruleText
        the text of the rule's BIND IF and DO clauses which are parsed using a grammar based parser
      • deleted

        private boolean deleted
        this is set to true if the rule is dynamically deleted or updated so as to inhibit execution of trigger code between the delete/update and recompilation/reinstatement of the affected bytecode.
      • line

        private int line
        the line number at which the rule text starts
      • file

        private java.lang.String file
        the name of the file from which the rule has been loaded, if defined, or some suitable dummy string if it was noti obtained from a file
      • compileToBytecode

        private final boolean compileToBytecode
        true if this rule should be compiled to bytecode otherwise false
      • keySet

        private final java.util.HashMap<java.lang.String,​java.lang.String> keySet
        hash map used to lookup a key used at injection time to identify a rule cloned from this script for injection into a specific trigger method. the map translates a string constructed from the trigger class name, method name, method descriptor and class loader hash to a unique key based on the rule name. This ensures that concurrent attempts to inject the rule into the same trigger method will employ the same key and hence perform exactly the same transformation. That way it does not matter which of the transformations are accepted or dropped by the JVM when defining a newly loaded class. Any transform result for a given key is as valid as any other.
      • key_base

        private final java.lang.String key_base
        base string from which to construct rule injection keys
      • transformSets

        private java.util.List<TransformSet> transformSets
        a list of records identifying transforms associated with a specific class. each set is identified by the name of a trigger class and the class's associated loader i.e. it corresponds with an attempt to transform a unique class using this rule script. A transform set may contain more than one transform because the rule's METHOD clause may omit a descriptor, leading to injection into multiple methods. Each transform references the specific method it applies to with a name and and descriptor string. Also, not all transforms record successful injections. Entries are added to record parse errors or warnings, including failure to inject a rule at all. There is at most one successful Transform for a given class+method, at most one failure or, possibly, one or more warnings.
    • Constructor Detail

      • RuleScript

        public RuleScript​(java.lang.String name,
                          java.lang.String targetClass,
                          boolean isInterface,
                          boolean isOverride,
                          java.lang.String targetMethod,
                          java.lang.String targetHelper,
                          java.lang.String[] imports,
                          Location targetLocation,
                          java.lang.String ruleText,
                          int line,
                          java.lang.String file,
                          boolean compileToBytecode)
        standard constructor for a rule
        Parameters:
        name - the name of the rule
        targetClass - the name of the class or interface to which the rule applies
        isInterface - true if the ruel applies to an interface false if it appies ot a class
        isOverride - true if the rule should inject down class hierarchies false if it should inly inject into direct implementations
        targetMethod - the name of the method to which the rule applies
        targetHelper - the name of the helper class to be used
        imports - the list of imports for the module system
        targetLocation - description of where the rule should be injected
        ruleText - the body of the rule as text including the BIND, IF and DO clasue
        line - the line at which the rule starts in it's rule script
        file - the path to the file containing the rule
        compileToBytecode - true if the rule should be compiled otherwise false
    • Method Detail

      • nextId

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

        public java.lang.String getName()
      • getTargetClass

        public java.lang.String getTargetClass()
      • isInterface

        public boolean isInterface()
      • getTargetHelper

        public java.lang.String getTargetHelper()
      • getImports

        public java.lang.String[] getImports()
      • getTargetMethod

        public java.lang.String getTargetMethod()
      • isOverride

        public boolean isOverride()
      • getTargetLocation

        public Location getTargetLocation()
      • getRuleText

        public java.lang.String getRuleText()
      • getLine

        public int getLine()
      • getFile

        public java.lang.String getFile()
      • isCompileToBytecode

        public boolean isCompileToBytecode()
      • getRuleKey

        public java.lang.String getRuleKey​(java.lang.String triggerClassName,
                                           java.lang.String triggerMethodName,
                                           java.lang.String triggerMethodDescriptor,
                                           java.lang.ClassLoader loader)
      • getTransformSets

        public java.util.List<TransformSet> getTransformSets()
        getter for list of transforms applied for this script. must be called synchronized on the script.
        Returns:
        the list of transforms
      • getTransformSetsCount

        public int getTransformSetsCount()
        return a count of the number of transforms applied for this script. must be called synchronized on the script.
        Returns:
        the size of the list of transforms
      • allTransforms

        public java.util.List<Transform> allTransforms()
      • setDeleted

        public boolean setDeleted()
        invoked by the scriptmanager when a rule is redefined to inhibit further transformations via this script
        Returns:
        the previous setting of deleted
      • isDeleted

        public boolean isDeleted()
        called when indexing a script to ensure that it has not already been deleted. it must only be called when synchronized on the script. This avoids a race where a script can be added by thread A, deleted by thread B, unindexed -- unsuccessfully -- by thread B then indexed by thread A
        Returns:
        the previous setting of deleted
      • recordFailedTransform

        public boolean recordFailedTransform​(java.lang.ClassLoader loader,
                                             java.lang.String internalClassName,
                                             java.lang.Throwable th)
        record the fact that an error was thrown when attempting to transform a given class using this rule script
        Parameters:
        loader - the loader of the class for which injection was attempted
        internalClassName - the internal Java name of the class
        th - the Throwable reocrding details of the failure
        Returns:
        true if the failure was recorded false if not
      • recordTransform

        public boolean recordTransform​(java.lang.ClassLoader loader,
                                       java.lang.String internalClassName,
                                       java.lang.String triggerMethodName,
                                       java.lang.String desc,
                                       Rule rule,
                                       java.lang.Throwable th)
        record the fact that a trigger call has succeeded or else failed to install into bytecode associated with a specific class and loader
        Parameters:
        loader - the loader of the class for which injection was attempted
        internalClassName - the internal Java name of the class
        triggerMethodName - the name of the method injected into
        desc - the descriptor of the method injected into
        rule - the rule which was injected
        th - throwable generated during the attempt to parse the rule text or inject code at the trigger point
        Returns:
        true if the successful injection was recorded false if not
      • hasTransform

        public boolean hasTransform​(java.lang.Class<?> clazz)
        check whether a rule has been used to transform a specific class. this can be used when rules are redefined to decide whether or not a class needs to be retransformed. Note that it must only be called after the script has been deleted by calling setDeleted.
        Parameters:
        clazz - the class for which a transform is being sought.
        Returns:
        true if the class has been transformed using this script otherwise false.
      • recordCompile

        public boolean recordCompile​(Rule rule,
                                     java.lang.String triggerClass,
                                     java.lang.ClassLoader loader,
                                     boolean successful,
                                     java.lang.String detail)
        record the fact that a rule has been compiled with or without success
        Parameters:
        triggerClass - the name of the trigger class to which the rule is attached
        loader - the classloader of the trigger class
        successful - true if the rule compiled successfully and false if it suffered from parse, type or compile errors
        detail - text describing more details of the compilation outcome
        Returns:
        true if the rule needs to be installed otherwise false
      • purge

        public void purge​(java.lang.ClassLoader loader,
                          java.lang.String triggerClassName)
        delete any transforms associated with a specific trigger class and loader for deletion. this is called just before any attempt to retransform the class to inject the script's associated rule. it ensures that records of previous transforms associated with a prior retransformation of the class are removed before any new ones are added
      • purge

        public void purge()
        uninstall all transforms associated with this script. this is called after marking the script as deleted and regenerating the methods for any associated transformed class to ensure that it does not cause a rule trigger call to fail.
      • ensureTransformSet

        public TransformSet ensureTransformSet​(java.lang.ClassLoader loader,
                                               java.lang.String triggerClass,
                                               Rule installedRule)
      • lookupTransformSet

        public TransformSet lookupTransformSet​(java.lang.ClassLoader loader,
                                               java.lang.String triggerClass)
      • toString

        public java.lang.String toString()
        Overrides:
        toString in class java.lang.Object
      • writeTo

        public void writeTo​(java.io.PrintWriter writer)