Event-Driven Architecture

This Servoy Tutorial is a discussion on how to build an application using an event-driven architecture, employing a loosely coupled modular design. This Servoy tutorial is an extension of the prior tutorial on Encapsulation. You should read that tutorial first before attempting to understand why we would use an approach like this. You also might want to familiarize yourself with object-oriented programming in Servoy, a topic for which I have written numerous Servoy tutorials.

Let’s take a real-world scenario, and assume for a moment we are building a dashboard. The dashboard can contain an unspecified number of widgets, each showing different information. One might be a chart, another a table view showing sales data, another showing order summary information, etc. The user has the ability to add and remove widgets, so you don’t know which ones will be there on the dashboard at any given time. On the dashboard, the user can set filter criteria, like a date range, sales territory, sales rep, etc. When the user makes a filter change, you would not want to have the entire dashboard rebuild with the onDataChange() event, where each widget looks to globals (or form variables) that were set in order to determine what information they need to display. Nor would you want to fire off forms.refresh() methods on all your widgets with the onDataChange() event. A loosely coupled, well architected system, would “broadcast” that a date filter change just happened, letting any of the widgets that are interested in that message, and “listening” for it, receive the message and respond. Other widgets that are not affected by a date filter change, would not be “listening” for that event, and hence would not respond. Does that make sense?

You might be wondering how we can do event-driven programming in Servoy, since it has no native EventHandler api, like many other development tools (not yet, anyways). Well, we can build our own. Let’s give it a try, shall we?

The first step is to create a table where we will store all our registered events. This will allow us to maintain the events from session to session. We can also build a nice UI for managing the events if we want, but that is beyond the scope of this Servoy tutorial. Here is a simple event table.

The next step is to create some global relations, so we can quickly locate a foundset of records for an event by name (you do recall from the Servoy Tutorial: Optimizing Code Performance that a relation is the fastest way to get the records from the table, right?). I’m actually going to need three variables to do this:

/**
 * @type {String}
 */
var EVENT_CALL = '';

/**
 * @type {String}
 */
var EVENT_MODULE = '';

/**
 * @type {String}
 */
var EVENT_NAME = '';

And two relationships:

This first relationship allows me to quickly check to see if an event registration already exists, by event name, the callback method, and the module attempting to register the event.

The second relationship allows me to quickly pull a foundset of all events that are registered for the event that has been fired.

Now that we have our table and some relations in place, we can create a new object in scopes.events, that will intercept all fired events from anywhere in the application. We are going to keep the example simple here, so this event listener has only a minimum of methods, register, remove and post.

The register method will set the globals with the module, event name, and callback method, and then check to see if it is already registered in the event table. If not, then it adds the event to the table. It always returns the event record in case the caller registering the event needs some information like its ID.

The remove method, removes the event from the event table, if it exists. It returns true or false to the caller.

The post method does all the work when an event is fired. It first pulls from the event table a foundset of records containing all the registered callbacks for that event name. In the example of our dashboard widgets, these could be all widgets that have registered to be notified if the date filter has changed. It loops through all the registered callbacks, splits them into an array, and then checks to see if they call a “forms” method or a “scopes” method. You could also run the string as a function using “eval” if you are comfortable with that (I commented it out), in which case you would not need to do the workaround to determine the type of method to call.  The method being called is a single public eventHandler method on the form, and it is passed arguments that allow the eventHandler to route the call to private form methods (good place to check all parameters are valid). The post method also traps for any errors, allowing for some centralized error handling. By the way, you could fire error events from anywhere in your system and have them handled this way as well, by one central eventListener.

var EventListener = {
	/**
	 * @param {String} sModuleName
	 * @param {String} sEventName
	 * @param {String} sFunctionName
	 * @return {JSRecord<db:/test/t_event>}*
	 * */
	register: function(sModuleName, sEventName, sFunctionName){
		var rEvent;
		EVENT_MODULE = sModuleName;
		EVENT_NAME = sEventName;
		EVENT_CALL = sFunctionName;

		// if not registered yet, then add
		if (!utils.hasRecords(_to_t_event$name_module_call)){
			rEvent = _to_t_event$name_module_call.getRecord(_to_t_event$name_module_call.newRecord(false, true));
			rEvent.t_event_module = sModuleName;
			rEvent.t_event_name = sEventName;
			rEvent.t_event_call = sFunctionName;
			rEvent.sequence_nr = _to_t_event$name.getSize() + 1;
			databaseManager.saveData(rEvent);
		}else{
			rEvent = _to_t_event$name_module_call.getRecord(1);
		}
		return rEvent;
	},
	/**
	 * @param {String} sModuleName
	 * @param {String} sEventName
	 * @param {String} sFunctionName
	 * @return {Boolean}*
	 * */
	remove: function(sModuleName, sEventName, sFunctionName){
		EVENT_MODULE = sModuleName;
		EVENT_NAME = sEventName;
		EVENT_CALL = sFunctionName;

		// if the event exists, remove it
		if (utils.hasRecords(_to_t_event$name_module_call)){
			return _to_t_event$name_module_call.deleteAllRecords();
		}
		return false;
	},
	/**
	 * @param {String} eventName
	 * @param {Array} aArgs
	 * @return {Boolean}*
	 * */
	post: function(eventName, aArgs){
		var i = 0,
			iSize = 0,
			/***@type{JSRecord<db:/test/t_event>} **/
			rEvent,
			sMethod = "",
			aMethod = []; 

		// Fire all methods listening for this event
		EVENT_NAME = eventName;
		if(utils.hasRecords(_to_t_event$name)){
			_to_t_event$name.sort("sequence_nr asc");
			iSize = _to_t_event$name.getSize();
			for (i = 1; i <= iSize; i++) {
				rEvent = _to_t_event$name.getRecord(i);
				sMethod = rEvent.t_event_call;
				if (sMethod.length > 0 && sMethod.search(/\./g) > -1){
					aMethod = sMethod.split(".");
					try{
						if (aMethod[0] === "forms"){
							forms[aMethod[1]][aMethod[2]](eventName, aArgs);
						}else if (aMethod[0] === "scopes"){
							scopes[aMethod[1]][aMethod[2]](eventName, aArgs);
						}
						// Took out eval because I know some people think using it is "evil"
	//					eval(method)(eventName, aArgs);
					}catch(ex){
						// Could do some real nice error handling here, since all method calls go through here
						application.output("ERROR: Callback " + rEvent.t_event_call + "()  for event " + rEvent.t_event_name + " with module " + rEvent.t_event_module + " failed");
					}
				}
			}
		}
	}
}

Now lets turn our attention to the imaginary widget that is going to go on the dashboard. The widget will be interested in several events that could fire, like a date filter change, sales rep change, etc. In this case, we are simply going to listen for generic events called EVENT_1 to EVENT_4, but in the real-world you would call the events something like “DBRD_DATE_FILTER_CHANGE”, etc. In the widget’s form .js file, I setup an object which will be used to route specific events to private functions (preserving encapsulation).

/**
 * @private
 * The object map for routing
 */
var EventHandler = {
	EVENT_1: function(aEventArgs){
		// Check all parameters are good
		return eventMethod_1(aEventArgs);
	},
	EVENT_2: function(aEventArgs){
		// Check all parameters are good
		return eventMethod_2(aEventArgs);
	},
	EVENT_3: function(aEventArgs){
		// Check all parameters are good
		return eventMethod_3(aEventArgs);
	},
	EVENT_4: function(aEventArgs){
		// Check all parameters are good
		return eventMethod_4(aEventArgs);
	}
};

When a widget is added to the dashboard, it will initialize, and register for the events it needs to respond to. The eventListener which receives the events, will then know to notify this widget when one of its registered events is fired. Notice that in the example below, I am registering a second callback for EVENT_1 in a completely different part of the system other than my form callbacks. When EVENT_1 is fired, two methods will be called.

scopes.events.EventListener.register("boxTest","EVENT_1", "forms.frmWidget1.eventHandler");
scopes.events.EventListener.register("boxTest","EVENT_2", "forms.frmWidget1.eventHandler");
scopes.events.EventListener.register("boxTest","EVENT_3", "forms.frmWidget1.eventHandler");
scopes.events.EventListener.register("boxTest","EVENT_4", "forms.frmWidget1.eventHandler");

scopes.events.EventListener.register("boxTest","EVENT_1", "scopes.events.notImplementedYet");

While we are at it, here is how the widget would un-register itself, if it where removed from the dashboard by the user.

scopes.events.EventListener.remove("boxTest","EVENT_1","forms.frmClosure.eventHandler");
scopes.events.EventListener.remove("boxTest","EVENT_2","forms.frmClosure.eventHandler");
scopes.events.EventListener.remove("boxTest","EVENT_3","forms.frmClosure.eventHandler");
scopes.events.EventListener.remove("boxTest","EVENT_4","forms.frmClosure.eventHandler");

I created the following eventHandler for the widget in the .js file, which relies on the object map shown earlier.

/**
 * @public
 * @param {String} eventName - the event name
 * @param {Array} aEventArgs - array of arguments
 * This actually routes the incoming calls using the object map
 */
function eventHandler(eventName, aEventArgs){
	EventHandler[eventName](aEventArgs);
}

And finally, here is how you would fire an event, from anywhere in the system. The fired event will be received by the eventListener in scopes.events, and all the registered callback methods for that event will be processed. You can pass as many arguments as you want in an array, which I used in this example, but obviously you could pass an object(s) as well, which would give you even more flexibility.

scopes.events.EventListener.post("EVENT_1",["test1", "test2"]);

I created four methods that fire the different events, and hooked them up to buttons on a form, along with a Register Events and Remove Events buttons.

Here is one of the simple callback methods I created. I created four of these, one for each of the events that will get fired. These methods are only accessed by the eventHandler which routes the call through the object.

/**
 * @private
 * @param {Array} aEventArgs
 */
function eventMethod_1(aEventArgs){
	application.output("eventMethod_1: " + aEventArgs.join(","));
	return true;
}

Here is my simple form for testing the event-driven model.

First I press the Register Events button, so the callbacks are registered for the events. Then I press “Fire Event 1” button, and I see the following in the console:

eventMethod_1: test1,test2
Have not yet implemented handler for: EVENT_1

The first output is from the method I created on the form, and the second is the additional event I registered for the same event, so that I could demonstrate multiple callbacks firing off the same event.

So there you have it; a simple event-driven system that preserves encapsulation. This approach is loosely coupled, easy to maintain and expand. In fact, if you think about it, our imaginary widgets could be used anywhere in the system, and still function exactly the same, because they are listening for the events that affect them, and ignoring everything else. Perhaps in the future, all Servoy applications will function like this.

That concludes this Servoy tutorial. It was an interesting exercise in using an event-driven architecture, demonstrating how to preserve encapsulation and use a loosely coupled modular design. I hope you enjoyed it, and I look forward to bringing you more Servoy tutorials in the future.