Annotation Type BMUnitConfig


  • @Retention(RUNTIME)
    @Target({METHOD,TYPE})
    public @interface BMUnitConfig
    annotation to allow configuration of BMUnit operation directly from test classes rather than via use of system variables a BMUnitConfig annotation may be attached to a test method (or test class) to specify the BMUnit and Byteman configuration which should be employed when the associated test(s) is (are) run. Certain configuration options only take effect when the first BMUnitConfig annotation encounterd during the run is encountered as the associated configuration values may not be reset once set. If multiple annotations are encountered in a given test run then it may not always be possible to honour all the specified settings. For example, if the agent has been autoloaded into the current VM using a given hostname (e.g. "192.168.0.254") then it will not be possible to upload rules to the autoloaded agent using the configured hostname "localhost". In such cases tests will normally proceed using the existing configuration. It is possible to force an error and fail a test in these cases through use of the enforce attribute.
    • Optional Element Summary

      Optional Elements 
      Modifier and Type Optional Element Description
      java.lang.String agentHost
      agentHost specifies the hostname which will be used when opening a client connection to the Byteman agent listener.
      java.lang.String agentPort
      agentPort specifies the port which will be used when opening a client connection to the Byteman agent listener.
      boolean allowAgentConfigUpdate
      allowAgentConfigUpdate determines whether or not the various Byteman property settings specified when the agent is uploaded can be reconfigured while the agent is running.
      boolean bmunitVerbose
      bmunitVerbose configures the BMUnit verbose setting which controls printing of trace related to the operation of the BMUnit package
      boolean debug
      debug configures the Byteman debug setting which controls printing of debug trace statements embedded in Byteman rules
      boolean dumpGeneratedClasses
      dumpGeneratedClasses configures whether or not the Byteman agent dumps transformed bytecode to a class file.
      java.lang.String dumpGeneratedClassesDirectory
      dumpGeneratedClassesDirectory identifies a directory path to locate the root directory for class files created when the Byteman agent dumps transformed bytecode to a class file.
      boolean dumpGeneratedClassesIntermediate
      dumpGeneratedClassesIntermediate configures whether or not the Byteman agent dumps intermediate versions of transformed bytecode to a class file.
      boolean enforce
      if enforce is true then every element of the configuration specified in the annotation must be configured as specified and if it cannot be so configured (or reconfigured) then an exception will be thrown by the test runner.
      boolean inhibitAgentLoad
      inhibitAgentLoad requests that the Byteman agent not be auto-loaded into the current JVM on behalf of this test.
      java.lang.String loadDirectory
      loadDirectory identifies a directory relative to which rule rule script files should be loaded.
      boolean policy
      policy configures whether or not to set a security policy when loading the agent.
      java.lang.String resourceLoadDirectory
      resourceLoadDirectory identifies a resource path relative to which rule script resources should be loaded.
      boolean verbose
      verbose configures the Byteman verbose setting which controls printing of trace related to the operation of Byteman
    • Element Detail

      • enforce

        boolean enforce
        if enforce is true then every element of the configuration specified in the annotation must be configured as specified and if it cannot be so configured (or reconfigured) then an exception will be thrown by the test runner. By default unavailable configuration settings are ignored.
        Returns:
        enforce
        Default:
        false
      • agentHost

        java.lang.String agentHost
        agentHost specifies the hostname which will be used when opening a client connection to the Byteman agent listener. if BMUnit needs to load the agent into the local JVM then the same hostname will be passed to the agent for it to use when opening the agent listener server socket. An empty String (the default) means use the Byteman default (i.e. "localhost").
        Returns:
        agentHost
        Default:
        ""
      • agentPort

        java.lang.String agentPort
        agentPort specifies the port which will be used when opening a client connection to the Byteman agent listener. if BMUnit needs to load the agent into the local JVM then the same port will be passed to the agent for it to use when opening the agent listener server socket. An empty String (the default) means use the Byteman default (i.e. 9999).
        Returns:
        agentPort
        Default:
        ""
      • inhibitAgentLoad

        boolean inhibitAgentLoad
        inhibitAgentLoad requests that the Byteman agent not be auto-loaded into the current JVM on behalf of this test.
        Returns:
        inhibitAgentLoad
        Default:
        false
      • loadDirectory

        java.lang.String loadDirectory
        loadDirectory identifies a directory relative to which rule rule script files should be loaded. it is only effective when a BMScript annotation fails to specify a dir="..." value. An empty String (the default) means use the current working directory.
        Returns:
        loadDirectory
        Default:
        ""
      • resourceLoadDirectory

        java.lang.String resourceLoadDirectory
        resourceLoadDirectory identifies a resource path relative to which rule script resources should be loaded. it is only effective when a BMScript annotation fails to specify a dir="..." value. An empty String (the default) means use the value of loadDirectory or, if that is not set, no resource path
        Returns:
        resourceLoadDirectory
        Default:
        ""
      • allowAgentConfigUpdate

        boolean allowAgentConfigUpdate
        allowAgentConfigUpdate determines whether or not the various Byteman property settings specified when the agent is uploaded can be reconfigured while the agent is running. In particular, this flag allows Byetman's verbose tracing mode to be reset. Byteman normally disables this setting for performance reasons. In particular, by disabling configuration of the verbose setting Byteman avoids the many frequent tests which occur during rule injection and rule execution to determine whether or not to print trace output. The BMUnitConfig annotation default setting for this attribute enables configuration update. The assumption is that most tests are not performance critical while the ability to reset Byteman's behaviour for individual tests is highly desirable. If your test really needs to run as close as possible to normal conditions then you should specify this attribute as false and set attribute enforce to true.
        Returns:
        allowAgentConfigUpdate
        Default:
        true
      • verbose

        boolean verbose
        verbose configures the Byteman verbose setting which controls printing of trace related to the operation of Byteman
        Returns:
        verbose
        Default:
        false
      • debug

        boolean debug
        debug configures the Byteman debug setting which controls printing of debug trace statements embedded in Byteman rules
        Returns:
        debug
        Default:
        false
      • bmunitVerbose

        boolean bmunitVerbose
        bmunitVerbose configures the BMUnit verbose setting which controls printing of trace related to the operation of the BMUnit package
        Returns:
        bmunitVerbose
        Default:
        false
      • policy

        boolean policy
        policy configures whether or not to set a security policy when loading the agent.
        Returns:
        policy
        Default:
        false
      • dumpGeneratedClasses

        boolean dumpGeneratedClasses
        dumpGeneratedClasses configures whether or not the Byteman agent dumps transformed bytecode to a class file.
        Returns:
        dumpGeneratedClasses
        Default:
        false
      • dumpGeneratedClassesDirectory

        java.lang.String dumpGeneratedClassesDirectory
        dumpGeneratedClassesDirectory identifies a directory path to locate the root directory for class files created when the Byteman agent dumps transformed bytecode to a class file. Each class file sits below this root directory in a subdirectory tree corresponding to the class's package. This attribute is only taken into account when attribute dumpGeneratedClasses has value true. An empty String means use the current working directory.
        Returns:
        dumpGeneratedClassesDirectory
        Default:
        ""
      • dumpGeneratedClassesIntermediate

        boolean dumpGeneratedClassesIntermediate
        dumpGeneratedClassesIntermediate configures whether or not the Byteman agent dumps intermediate versions of transformed bytecode to a class file. It is only of relevance where multiple rules target the same class. In such cases Byteman will inject rules one after the other. This attribute is only taken into account when attribute dumpGeneratedClasses has value true. Successive intermediate class files are written with the same name as the final transformed file except that the base name is modified by adding suffixes _1, _2, ..., etc.
        Returns:
        dumpGeneratedClassesIntermediate
        Default:
        false