Using Broadway

It's easy to start using the Broadway Monitor components to create your own monitor of in-memory local VM objects. Once you have added necessary files to your class path, you are ready to start using Broadway. Here is a simple example that shows in detail how to wire the different Broadway components to monitor several POJO's properities.

A Simple Example

This example shows how you can wire all necessary components to create start monitoring your objects state changes.

The latter part of the code sets up a thread that runs continuously and call Monitor.scan() method. The majority of the sample code is really concerned with simulating a real world environment where POJO states will change. The main areas of the code to concentrate on are:

...
    // instantiate Broadway components
    public SimplePojoMonitor() {
		monitor = new BeanMonitor();
		resources = new MappedResourceCollector();
		monitor.setResourceCollector(resources);

		engine = new BsfScriptEngine();
		engine.setLanguage("groovy");

		eval = new StringExpressionEvaluator();
		eval.setScriptEngine(engine);
		monitor.setEvaluator(eval);
	}

       // setup monitor to run
	public void startMonitor() {
		System.out.println("Monitoring ...");

		// register pojo's with resource collector
		resources.putResource("pojo1", pojo1);
		resources.putResource("pojo2", pojo2);
		resources.putResource("pojo3", pojo3);
		
		monitor.setAutoAction(true);
		monitor.setActWhen(true);
		action = new ScriptedAction("org/broadway/demo/simple/pojo_script.groovy");
		monitor.setAction(action);
		
		// monitor average
		monitor.setMonitorExpression(
			"((context.resources.pojo1.interger + context.resources.pojo2.interger + context.resources.pojo3.interger) / 3) > 40"
		);

 ...

• The SimplePojoMonitor() constructor instantiates explicitly all of the Broadway components and wire them together.
• The startMonitor() method is where Broadway is used to setup the monitoring
• First the pojo instances are registered with the MappedResourceCollector component.
• Here we use a Scripted Action component to specify the script file to run when the monitor expression evaluates to true.
• Next we have the expression that the monitor evaluates. If that expression evaluates to true (or false depending on method setActWhen()), the monitor triggers the action.

This example uses Groovy as default expression language for the monitoring condition. When the condition evaluates to a predetermined value (in this case true) the ScriptedAction class executes a Groovy script file.

View entire example.

Another Simple Example

In this example, we tone down the verbosity of the code. Broadway will use its internal defaults to setup all necessary components. Groovy is assumed to be the default expression language for the monitoring condition and for the ScriptedAction script files. This example is the same as before except the constructor only has one statement that instantiates the monitor object.

public class SimplePojoMonitor2 {
	private BeanMonitor monitor;

	private ScriptedAction action;

	private Pojo pojo1, pojo2, pojo3;

	public SimplePojoMonitor2() {
		monitor = new BeanMonitor();
	}
...

}

Here, note that constructor SimplePojoMonitor2() has been reduced to just one line of code. Broadway uses its internal defaults to configure the necessary components. The rest of the code is same as above.

View entire example.

Create A Custom Action

If you do not want to use a scripting language to handle the action for your monitor, you can create a custom monitor and pass it to the BeanMonitor component. This level of flexibility allows you to override the Broadway's defaults and provide your own Action implementation. Here is a simple Action that stops the program after executing the Action 4 times:

...
class MyCustomAction implements Action{
	private static int MAX_EXEC_COUNT = 4;
	
	public Object execute(Context ctx) throws ActionException {
		System.out.println("Average too high.  Invoking custom Java action ...");
		
		//BeanMonitor mon = (BeanMonitor)ctx.getValue(MonitorConstants.MonitorKeys.MONITOR_OBJECT);

		Integer count = 1;
		if(ctx.getValue("count") != null){
			count = (Integer) ctx.getValue("count");
			count = count + 1;
		}
				
		System.out.printf(">>> Executing %d times <<< \n", count);
		
		if(count >= MAX_EXEC_COUNT){
			System.out.printf("Maximum exec count of %d reached.\n", MAX_EXEC_COUNT);
			System.out.println("Shutting down program.");
			System.exit(0);
		}else{
			ctx.putValue("count", count);
		}
		
		return null;
	}

...

Here, rather than using a script file, we use Java directly to implement an action. This gives the developer the flexibility to choose how to create action handlers for the monitor. The an instance of that action can then be passed to the monitor same as in previous examples. When the monitor evaluates the expression to an expected value, it will call the action.

View entire example.

Switching Scripting Language

Broadway can use any scripting language that is supported by the Apache Bean Scripting Framework. In order to use a selected script language, just add its jar files to your classpath and set the script language name using the ScriptEngine class. This example shows Broadway using BeanShell scripting language as the expression language and the scripted action handler.

	private BsfScriptEngine engine;
	private StringExpressionEvaluator eval;

	public SimplePojoMonitor4() {
	
    ...
    
        engine = new BsfScriptEngine();
		engine.setLanguage("beanshell");
		
		eval = new StringExpressionEvaluator();
		eval.setScriptEngine(engine);
		monitor.setEvaluator(eval)		
    ...
    
	}



	public void startMonitor() {
		System.out.println("Monitoring ...");
		
		monitor.setAutoAction(true);
		monitor.setActWhen(true);
		action = new ScriptedAction("org/broadway/demo/simple/pojo_script.bsh");
		action.getScriptRunner().setScriptEngine(engine);
		
		monitor.setAction(action);
		
		// using beanshell
		monitor.setMonitorExpression(
			"( (context{\"resources\"}{\"pojo1\"}{\"interger\"} + " +
			" context{\"resources\"}{\"pojo2\"}{\"interger\"} + " +
			" context{\"resources\"}{\"pojo3\"}{\"interger\"})   " +
			" / 3) > 40;"
		);
		
		...
    }
    
    ...
    

Notice that using the BsfScriptEngine object, you can specify your language. As long as the necessary jar files are on the classpath, Broadway will invoke the proper scripting language. You can even combine your languages at runtime by setting the engine's language.

View entire example.

The Broadway DSL

Broadway also provides a small domain specific language that makes it easier to program Broadway monitors.

	private BeanMonitor monitor;
	private BeanMonitorDsl monDsl;

    ...
    
	public void startMonitor() {
		
		monDsl
			.observe(new ObservedBean("pojo1", pojo1))
			.observe(new ObservedBean("pojo2", pojo2))
			.observe(new ObservedBean("pojo3", pojo3))
			.forCondition(
				When.thisIsTrue(
					"((context.resources.pojo1.interger + context.resources.pojo2.interger + context.resources.pojo3.interger) / 3) > 40"
				)
			);
			
		...
		
		monDsl.execute(action);
    }

The DSL reduces the verbosity of boiler plate code. It exposes a small vocabulary to build broadway monitors.

View entire example.