Package org.jboss.byteman.contrib.bmunit
Annotation 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 ElementsModifier and TypeOptional ElementDescriptionagentHost specifies the hostname which will be used when opening a client connection to the Byteman agent listener.agentPort specifies the port which will be used when opening a client connection to the Byteman agent listener.boolean
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 configures the BMUnit verbose setting which controls printing of trace related to the operation of the BMUnit packageboolean
debug configures the Byteman debug setting which controls printing of debug trace statements embedded in Byteman rulesboolean
dumpGeneratedClasses configures whether or not the Byteman agent dumps transformed bytecode to a class file.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 configures whether or not the Byteman agent dumps intermediate versions of transformed bytecode to a class file.boolean
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 requests that the Byteman agent not be auto-loaded into the current JVM on behalf of this test.loadDirectory identifies a directory relative to which rule rule script files should be loaded.boolean
policy configures whether or not to set a security policy when loading the agent.resourceLoadDirectory identifies a resource path relative to which rule script resources should be loaded.boolean
verbose configures the Byteman verbose setting which controls printing of trace related to the operation of Byteman
-
Element Details
-
enforce
boolean enforceif 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
String agentHostagentHost 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
String agentPortagentPort 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 inhibitAgentLoadinhibitAgentLoad requests that the Byteman agent not be auto-loaded into the current JVM on behalf of this test.- Returns:
- inhibitAgentLoad
- Default:
false
-
loadDirectory
String loadDirectoryloadDirectory 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
String resourceLoadDirectoryresourceLoadDirectory 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 allowAgentConfigUpdateallowAgentConfigUpdate 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 verboseverbose configures the Byteman verbose setting which controls printing of trace related to the operation of Byteman- Returns:
- verbose
- Default:
false
-
debug
boolean debugdebug configures the Byteman debug setting which controls printing of debug trace statements embedded in Byteman rules- Returns:
- debug
- Default:
false
-
bmunitVerbose
boolean bmunitVerbosebmunitVerbose configures the BMUnit verbose setting which controls printing of trace related to the operation of the BMUnit package- Returns:
- bmunitVerbose
- Default:
false
-
policy
boolean policypolicy configures whether or not to set a security policy when loading the agent.- Returns:
- policy
- Default:
false
-
dumpGeneratedClasses
boolean dumpGeneratedClassesdumpGeneratedClasses configures whether or not the Byteman agent dumps transformed bytecode to a class file.- Returns:
- dumpGeneratedClasses
- Default:
false
-
dumpGeneratedClassesDirectory
String dumpGeneratedClassesDirectorydumpGeneratedClassesDirectory 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 dumpGeneratedClassesIntermediatedumpGeneratedClassesIntermediate 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
-