Client side library using VertX Event Bus as an Angular Service module
Branch | Stability | Status |
---|---|---|
Canary | unstable | |
Master | stable |
Either download it manually or install it automatically with Bower: bower install angular-vertxbus --save
Then only import dist/angular-vertxbus.js
or dist/angular-vertxbus.min.js
. The file itself comes with a CJS header.
Alternatively you can use the cdnjs: cdnjs.com/libraries/angular-vertxbus.
The source code is written using newer JavaScript 2015 (partly) and is using the JavaScript transpiler BabelJS.
Depending on your target clients, you probably need to include a browser polyfill (for ES5 clients). BabelJS itself
recommends the requirement of its own polyfill. Either you use the explained
way using npm modules and/or browserify, or you can use the alternative artifact variant dist/angular-vertxbus.withpolyfill.js
.
This library is being developed against AngularJS 1.4, and additional tests are performed against AngularJS 1.2 and AngularJS 1.3.
This library is being developed against the eventbus.js
from Vert.x 3.
An Api Documentation is available.
You have to define the module dependency, this module is named knalli.angular-vertxbus
.
angular.module('app', ['knalli.angular-vertxbus'])
.controller('MyCtrl', function(vertxEventBus, vertxEventBusService) {
// using the EventBus directly
vertxEventBus.send('my.address', {data: 123});
// using the service
vertxEventBusService.send('my.address', {data: 123})
});
vertxEventBusService.on('myaddress', function(err, message) {
console.log('Received a message: ', message);
});
vertxEventBusService.publish('myaddress', {data: 123});
vertxEventBusService.send('myaddress', {data: 123})
.then(function(reply) {
console.log('A reply received: ', reply);
})
.catch(function() {
console.warn('No message');
});
// The "No reply message found" is controlled via a timeout (default 10000ms)
vertxEventBusService.send('myaddress', {data: 123}, {timeout: 3000})
.then(function(reply) {
console.log('A reply received: ', reply);
})
.catch(function() {
console.warn('No message within 3 seconds');
});
// If the reply is an error, this will be the payload
vertxEventBusService.send('myaddress', {data: 123})
.then(function(reply) {
console.log('A reply received: ', reply);
})
.catch(function(err) {
console.warn(err);
});
The module has some advanced configuration options. Perhaps you do not have to change them, but at least you should know them!
Each module configuration option must be defined in the run
phase, i.e.:
angular.module('app', ['knalli.angular-vertxbus'])
.config(function(vertxEventBusProvider) {
vertxEventBusProvider
.enable()
.useReconnect()
.useUrlServer('http://live.example.org:8888');
});
Please have a look at the API documentation for vertxEventBusProvider and vertxEventBusServiceProvider for further options.
The module contains two items: the stub holder vertxEventBus
for the Vert.x EventBus and a more comfortbale high level service vertxEventBusService
.
The stub is required because the Vert.x Event Bus cannot handle a reconnect. The reason is the underlaying SockJS which cannot handle a reconnect, too. A reconnect means to create a new instance of SockJS
, therefore a new instance of EventBus
. The stub ensures only one single instance exists. Otherwise a global module was not possible.
More or less the stub supports the same API calls like the original EventBus
.
Based on the stub, the high level service vertxEventBusService
detects disconnects, handles reconnects and ensures re-registrations of subscriptions. Furthermore, the service provides some neat aliases for the usage of handlers.
// Same as EventBus.registerHandler()
service.registerHandler('myaddress', callback);
service.on('myaddress', callback);
service.addListener('myaddress', callback);
// Same as EventBus.unregisterHandler()
service.unregisterHandler('myaddress', callback);
service.un('myaddress', callback);
service.removeListener('myaddress', callback);
// Same as EventBus.send()
service.send('myaddress', data)
// Same as EventBus.publish
service.publish('myaddress', data)
service.emit('myaddress', data)
// Same as EventBus.readyState()
service.readyState()
In addition to this, when sending a message with an expected reply:
// Same as EventBus.send() but with a promise
service.send('myaddress', data)
.then(function(reply) {})
.catch(function(err) {})
For each connect or disconnect, a global broadcast will be emitted (on $rootScope
with 'vertx-eventbus.system.connected'
, 'vertx-eventbus.system.disconnected'
)
Note: Check that dependencies are be installed (npm install
).
The unit tests are available with npm test
which is actually a shortcut for grunt test
. It performs tests under the current primary target version of AngularJS. Use npm run test-scopes
for testing other scoped versions as well.
Note: Check that dependencies are be installed (npm install
).
The end-to-end tests start and utilize a full Vert.x node and a NodeJS based web server.
npm run install-it-vertx-server
downloads and installs a Vert.x locally.npm run start-it-vertx-server
starts Vert.x on port8080
.npm run start-it-web-server
starts a web server on port3000
.- Open http://localhost:3000/ in your browser.
Copyright 2016 by Jan Philipp. Licensed under MIT.