• View
• Edit
• History
• Print

Vertx

Vert.x is a rich Java-based library with many other language bindings, including JavaScript, that provides an event-driven style of concurrent and distributed programming, a publish-and-subscribed event bus, and a library of communication utilities. Vert.x is developed under the Eclipse foundation and is open source using the Apache 2.0 license.

Event Bus

The vertxbus module supports publishing and subscribing via a Vert.x event bus. A Vert.x bus is configured and runs on some accessible host. Clients (which are not required to run Vert.x) may then connect to this bus and send and receive messages.

This page covers:

• Overview and configuration options
• Messaging paradigms
• Client API
• Publish and subscribe accessors
• Server-side bus startup
• Browser host client
• Node.js host client
• (TODO) Java host client (Ptolemy - already implemented - needs writeup and testing with latest)
• (TODO) Vert.x host client

All source files are checked into the swarmos respository.
For repository access, see: https://www.terraswarm.org/swarmos/wiki/Main/SwarmOSRepository

Overview and options

The Vert.x event bus offers a few different configuration options. Here's a brief overview:

• Addresses

Messages are sent to an address, which can be any string, although a naming scheme is recommended.
Some examples of valid addresses are " europe.news.feed1, acme.games.pacman, sausages, and X."

• Handlers

"A handler is a thing that receives messages from the bus. You register a handler at an address."
A single handler can be registered at multiple addresses, and multiple handlers can be registered at a single address.

• Security: Screening traffic

The event bus can be setup to allow traffic only to certain address patterns or message patterns. See the "Server" section for more details.

Messaging paradigms

Vert.x supports different messaging strategies. All messages are transient. A persistent work queue model can be used to store messages if needed.

• Publish / subscribe

Messages are published to an address and delivered to all handlers registered at that address.

• Point to point

Messages are sent to an addresses. One of the handlers registered at that address will receive it, using a round-robin algorithm.

• Request / response

This adds a reply handler to point to point scheme. The sender specifies a reply handler, which the recipient calls upon handling the message. The recipient can again supply a reply handler, which the sender uses. This facilitates a request / response pattern.

Client API

The client API is based on the Vertx event bus bridge library vertxbus.js. This library is discussed here and can be downloaded here as part of Vert.x distribution.

The client requires an implementation of the webSocket module. Note that the implementation may emulate websockets in lieu of supporting true websockets. For example, the SockJS library uses the browser host to establish the connection, and will establish a non-websocket connection if the browser does not support websockets.

The Vertx bus client provides the following methods:

• EventBus(url, opts): Create a new Vertx bus connection to the given url with the given options.
• login(username, password, replyHandler): Login with the given credentials. A callback handler may be specified.
• send(address, message, replyHandler): Send a message to the given address using the point-to-point paradigm. (A single recipient is chosen). A callback handler may be specified.
• publish(address, message): Publish a message to the given address using the pub/sub paradigm. (All handlers registered at this address will receive the message).
• registerHandler(address, handler) : Register a handler at the given address to receive messages.
• unregisterHandler(address, handler) : Unregister a handler at the given address to stop receiving messages.
• readyState(): Returns one of EventBus.CONNECTING, EventBus.OPEN, EventBus.CLOSING, EventBus.CLOSED.

The Vertx bus client defines the following methods with no implementation, for callback purposes:

• onopen(): Called when a connection is established
• onclose(): Called when a connection is closed

The Vertx bus client provides implementations for these webSocket methods:

• WebSocket.onopen() : Called when the WebSocket connection is established.
• WebSocket.onclose() : Called when the WebSocket connection is closed.
• WebSocket.onmessage() : Called when the a message is received over the connection.

It requires these methods from webSocket:

• WebSocket(url) : Create a new WebSocket connection to the given url.
• WebSocket.send(message) : Send a message over the WebSocket connection.
• WebSocket.close() : Close the WebSocket connection.

Publish and subscribe accessors

The latest accessors are in the swarmos repository under:

/hosts/browser/public/accessors, VertxBusPublish.xml and VertxBusSubscribe.xml.

Each accessor may define inputs and outputs, the initialize(), fire(), and wrapup() methods plus any additional local code.

The accessors may be used on any supported host. No changes to the accessor are required. These accessors are written in Javascript.

Server-side bus startup

A Vert.x instance is needed to host the bus. Code for a simple bus server can be found in the swarmos repository at:
/hosts/vertx/simpleeventbus.js

This script will start the event bus and bridge (for connecting to non-Vert.x clients) and register a listener at the address x. It accepts traffic from all hosts bound for all addresses. It does not implement any of the many security features available.

To run, install Vert.x, then type:

Messages published to address x will be echoed to the screen.

Browser host client

Together with a few helper files, the accessor files can be opened with a browser.

The latest accessors are in the swarmos repository under:
/hosts/browser/public/accessors, VertxBusPublish and VertxBusSubscribe.

The browser uses the stylesheet renderHTML.xsl, located in the same directory, to load script libraries and render the accessor as a web page. See Browser Accessor Hosts on the wiki for more info. This is the procedure used to render accessors on the TerraSwarm accessors page.

To run,

1. Open the accessor file in a browser.
2. Enter an address to publish/subscribe to, such as x.
3. Click the "initialize" button to connect to the bus.
4. For the publisher, enter a message and click "fire" to send it.
5. For the subscriber, click "fire" once to subscribe to messages. Received messages will appear under "Outputs" in the "message" field.
6. Click "wrapup" to disconnect from the bus.

These clients will send messages to and receive messages from any other clients connected to the bus.

renderHTML.xsl loads the following Javascript libraries for these accessors:

• basicFunctions.js, which defines methods for establishing HTTP connections and reading URLs
• browserHost.js, which defines base implementations of initialize(), fire(), wrapup(), get() and send()
• sockjs.js, a websocket and emulator connection library from the SockJS CDN
• vertxbus.js, part of the Vert.x distribution

Node.js host client

The swarmos repository also contains code for hosting accessors on Node.js. Two Javascript scripts /hosts/node/pubhost.js and /hosts/node/subhost.js will connect to the bus and allow the user to publish messages and subscribe to messages using standard input and ouput.

Node uses the vertx-eventbus-client package to interface with the bus. This package will be automatically downloaded during the setup step below.

To run,

Back to Optional JavaScript Modules