Package org.jboss.byteman.contrib.dtest

Class RuleConstructor

java.lang.Object

org.jboss.byteman.contrib.dtest.RuleConstructor

public final class RuleConstructor
extends Object

Provides a fluent API for creating Byteman rules without needing to mess around with String concatenation.

Example:

RuleConstructor rb = RuleConstructor.createRule("myRule")
.onClass("org.jboss.byteman.ExampleClass")
.inMethod("doInterestingStuff")
.atEntry()
.ifTrue()
.doAction("myAction()");
System.out.println(rb.build());

will print:

RULE myRule
CLASS org.jboss.byteman.ExampleClass
METHOD doInterestingStuff
AT ENTRY
IF true
DO myAction()
ENDRULE

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
class	RuleConstructor.ActionClause
class	RuleConstructor.ClassClause
class	RuleConstructor.ConditionClause
class	RuleConstructor.LocationClause
class	RuleConstructor.MethodClause

Method Summary

Modifier and Type	Method	Description
String	build()	Builds the rule defined by this instance of RuleConstructor and returns its representation as string.
static RuleConstructor.ClassClause	createRule(String ruleName)	This is where you start.
static Instrumentor	getDefaultInstrumentor()	Returning value of the previously set default Instrumentor instance.
RuleConstructor	install()	Installing/submitting rule to the Byteman agent via instance of instrumentor defined as default to the RuleConstructor class.
RuleConstructor	install(Instrumentor instrumentor)	Installing/submitting rule to the Byteman agent via instance of instrumentor.
static void	setDefaultInstrumentor(Instrumentor instrumentor)	Setting default initialize instance of Instrumentor class that will be used when install()/submit() method is used for the created rule. You can define this default Instrumentor which could be used whenever the new rule is submitted to the Byteman agent. null is permitted then install() method throws exception
RuleConstructor	submit()	Facade to method install().
RuleConstructor	submit(Instrumentor instrumentor)	Facade to method install(Instrumentor).
static void	undefineDefaultInstrumentor()	Undefinining value of default instrumentor.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

setDefaultInstrumentor

public static final void setDefaultInstrumentor(Instrumentor instrumentor)

Setting default initialize instance of Instrumentor class that will be used when install()/submit() method is used for the created rule.
You can define this default Instrumentor which could be used whenever the new rule is submitted to the Byteman agent.
null is permitted then install() method throws exception

Parameters:

instrumentor - initiated instrumentor instance or null

undefineDefaultInstrumentor

public static final void undefineDefaultInstrumentor()

Undefinining value of default instrumentor. Methods install()/submit() are illegal to be used from now up to time it's set again.

getDefaultInstrumentor

public static final Instrumentor getDefaultInstrumentor()

Returning value of the previously set default Instrumentor instance.

Returns:

instrumentor instance or null, when was not set

createRule

public static final RuleConstructor.ClassClause createRule(String ruleName)

This is where you start.

Byteman rule builder initialization method.

Parameters:

ruleName - name of rule is required to construct any rule

Returns:

a rule constructor ready to have its class or interface specified

install

public RuleConstructor install()

Installing/submitting rule to the Byteman agent via instance of instrumentor defined as default to the RuleConstructor class.

Internally this:

• build the rule where build() is called to generate rule as String
• calling submit of the rule over instance of Instrumentor

Prerequisite: you need set up the instrumentor by call setDefaultInstrumentor(Instrumentor)

Returns:

rule constructor if expected to be used later again

Throws:

IllegalStateException - if default instrumentor is not set

RuntimeException - if error happens during installation rule via default instrumentor instance

install

public RuleConstructor install(Instrumentor instrumentor)

Installing/submitting rule to the Byteman agent via instance of instrumentor.

Internally this:

• build the rule where build() is called to generate rule as String
• calling submit of the rule over instance of Instrumentor

Parameters:

instrumentor - instance of instrumentor to be used to submit the rule to

Returns:

rule constructor if expected to be used later again

Throws:

NullPointerException - if instrumentor param is provided as null

RuntimeException - if error happens during installation rule via default instrumentor instance

submit

public RuleConstructor submit()

Facade to method install().

Returns:

rule constructor, if expected to be used later again

Throws:

IllegalStateException - if default instrumentor is not set

RuntimeException - if error happens during installation rule

submit

public RuleConstructor submit(Instrumentor instrumentor)

Facade to method install(Instrumentor).

Parameters:

instrumentor - instance of instrumentor to be used to submit the rule to

Returns:

rule constructor, if expected to be used later again

Throws:

NullPointerException - if instrumentor param is provided as null

RuntimeException - if error happens during installation rule

build

public String build()

Builds the rule defined by this instance of RuleConstructor and returns its representation as string.

Returns:

the rule as a string