Blueprint
Search…
Messaging Framework
Publish and subscribe to events
Overview
Blueprint has a built-in messaging framework that helps you to design a reactive application. The messaging framework is similar to events in Node.js, but events are handled asynchronously by default. This design approach allows controllers to fire off events without waiting for background tasks to complete—returning control as quick as possible to the client.
Object Events
The
BaseObject class (see The Object Model) has methods for emitting and consuming events specific to the corresponding object instance. To emit an event from the object, use the emit(...args) method. Use either the once(name, ...args) or on(name, ...args) method to consume the corresponding event a single time or any time it is emitted, respectively. Here is an example for emitting and consuming an event on an object.1
const { BO } = require ('@onehilltech/blueprint');
2
3
const Connection = BO.extend ({
4
open (opts) {
5
// do something..
6
7
this.emit ('opened', this);
8
}
9
});
10
11
// ...
12
13
let conn = new Connection ();
14
conn.on ('opened', conn => {
15
console.log ('The connection is open');
16
});
Copied!
As shown in the example above, the
Connection.open() method emits the opened event on the object instance. We can then register to receive the event, which is illustrated with we call the conn.on() method. You can also use the conn.once() if you only want to listener to be notified once when a connection is opened, and not every time the connection is opened.Application Events
Application events are events emitted through the Blueprint application. This should not be confused with the actual application event types. Unlike the object events discussed above, the implementation logic for both application emitters and consumers is different.
Implementing a Listener
All application event listeners are implemented in
app/listeners/[EVENT_NAME] were EVENT_NAME is the name of the event you are listening. The application event listeners must also extend the Listener class in Blueprint. Here is an example of an application event listener responding to connection open events.app/listeners/conn.open/console.js
1
const { Listener } = require ('@onehilltech/blueprint');
2
3
module.exports = Listener.extend ({
4
handleEvent (conn) {
5
console.log ('The connection is open');
6
}
7
});
Copied!
The event listener must implement the
handleEvent() method. Similar to the object events, the handleEvent() method takes a variable number of parameters. This count depends on the number of parameters passed to the emit() method.Emitting an Event
You emit an application event in a similar manner as emitting object events. The main different is you use
blueprint.emit() method instead of directly emitting on the local object instance. Here is an example emitting the connection open event as an application event.1
const blueprint = require ('@onehilltech/blueprint');
2
const { BO } = blueprint;
3
4
const Connection = BO.extend ({
5
open (opts) {
6
// do something..
7
8
this.emit ('opened', this);
9
blueprint.emit ('conn.opened', this);
10
}
11
});
Copied!
As shown in this example, the first
emit() method is publishing the event a local object instance. The second emit() is publishing the event on through the Blueprint application.The Application Instance
If you are implementing a Blueprint entity, such as a controller, listener, or policy, then you have access to the application instance as a data property. If you already have direct access to the application class, then you do not need to use
blueprint.emit() and blueprint.on() or blueprint.once() to send and receive application events. Instead, you can use the emit(), once(), and on() method on the application instance.Predefined Events
The following events are predefined to the Blueprint application.
blueprint.app.init- Called after the application is initialized.blueprint.app.started- Called after the application is started.
Inter-Module Communication
One key feature of the messaging framework is entities can communicate with listeners in different Blueprint modules. We call this inter-module communication. This allows modules to be loosely coupled with other modules in an application. It also allows listening modules to react to module events without the source module knowing the listening module is dependent on its behavior.
Synchronous Messaging
Emitters
By default, emitting an event is an asynchronous operation. This means the client does not wait for all listeners to process the event before continuing. To make event processing a synchronous operation, the client to wait for the event to be processed. You do this by waiting for the
Promise returned from the emit() method to be resolved.1
conn.emit ('opened', this); // asynchronous
2
3
conn.emit ('opened', this).then (() => { // synchronous
4
5
});
Copied!
Listeners
The listener also can be asynchronous. If the listener is performing background processing, then it can return a
Promise. If the emitter is asynchronous, then it will not continue until the listener's promise is either resolved or rejected.1
const { Listener } = require ('@onehilltech/listener');
2
3
module.exports = Listener.extend ({
4
handleEvent (conn) {
5
return new Promise ((resolve, reject) => {
6
// Add background processing code here
7
});
8
}
9
});
Copied!
Last modified 4yr ago