vertx_dart_sockjs 3.5.0

  • Readme
  • Changelog
  • Installing
  • 10

vertx_dart_sockjs #

Library to connect either to plain SockJS or Vert.x event bus server.

Usage #

This library do embrace two cases and contains separate implementations for each of them.

Load JS files in index.html #

There 1 or 2 JS file necessary. The one for SockJS and at the other hand Vert.x event bus.

For sure, you can get at least the SockJS file also from many CDN platforms. I personally suggest to use the one from this library, specially when use Vert.x on the server side.

    <script defer src="packages/vertx_dart_sockjs/src/js/sockjs-0.3.4.min.js"></script>
    <script defer src="packages/vertx_dart_sockjs/src/js/vertx-eventbus-3.4.1.min.js"></script>

Plain SockJS #

Use this if you need more low level functionality for the communication with Vert.x or you work with an other SockJS server.

Developed and tested is this library with Vert.x as server Vert.x SockJS server But it should work with any SockJS server thats' compatible to version 0.3.4.

SockJS Configuration #

You can configure the SockJS instance for your needs. For more details about the protocol white list, please visit the SockJS documentation

class SockJSOptions {
  external bool get debug;
  external bool get devel;
  external List<String> get protocols_whitelist;

Create SockJS instance #

For a new SockJS connection just provide the server url and optional it's configuration.

import 'package:vertx_dart_sockjs/sockjs.dart';

SockJS sockJS = await SockJS.create("serverUrl", configuration);

Send message through the socket #

Any String data can be send over SockJS.


Receive message from socket #

To receive you have to register a callback.

Stream API support may in the future.

sockJS.onMessage((SockJsMessageEvent event) {
     // do anything

On close socket event #

You can define a callback that get called when SockJS lost the connection.

void onClose( OnCloseCallback callback );

Vert.x SockJS event bus bridge #

This implementation is a counterpart for the Vert.x SockJS bridge

Please visit this documentation for further information and the configuration on the server side.

A goal was to provide a server like API where it makes sense.

Configuration #

You can configure it with the SockJS configurations above and the following additional:

  • enablePing : Enables pinging direct when the connection got established
  • pingInterval : Ping interval that should be send to the server
  • autoReconnect : When the event bus lost its connection, the connection will be tried to get established again.
  • autoReconnectInterval : Interval the reconnect get tried. Makes only sense when autoReconnect is enabled. Default 5 seconds
  • reopenedCallback : callback function that get called after reconnect (Not on initial connect)

Entry class for this configuration is EventBusOptions

Execution delegate (context) #

Since many part of this library are async, the Dart zone can become very important, for example within AngularDart. When consumers or other callbacks get called not within the Angular zone, the re-rendering can be broken.

To ensure that any of them are called within the correct zone or other context, you can define your own execution delegate.

typedef void ConsumerExecutionDelegate(Function f);
AngularDart Example #
void delegate(Function f) {
  ngZone.runGuarded(() => f());

This delegator can be applied as parameter to the event bus create method.

Reconnect #

The event bus can be configured to reconnect automatically after connection lost. All consumers and other callbacks will reattached too. Just set the configuration properties autoReconnect to true and optional set the autoReconnectInterval and reopenedCallback.

Encoding / Decoding #

JSON and plain basic types are supported out of the box. But many times you want or have to use your own protocol ... like Google Protobuf. In this case you must tell the event bus how to encode and decode the data from and to the wire.

Decoding #

Decoder can defined on consumer registration and on message send when a reply is expected.

typedef T EventBusBodyDecoder<T>(dynamic body);
Encoding #

After you got an instance of the event bus you can access the EncoderRegistry

typedef dynamic EventBusBodyEncoder<T>(T dto);

On this instance you can register encoders by type of your dto's. So this encoder get used to encode anytime you send a event with an dto instance of this type.

Create client event bus instance #

To get an instance of the event bus you must provide:

  • Server url

and you can provide:

  • consumer execution delegate : To ensure consumers and other callbacks get called within the correct zone for example.
  • option : Options for SockJS and the event bus itself. Description above.
import 'package:vertx_dart_sockjs/vertx_eb.dart';

EventBus eventBus = await EventBus.create( "serverUrl", consumerExecDelegate: myExecutionDelegate, options: myBusOptions );

Send / publish message over the event bus #

* For one way messages.
eventbus.send( "address", body: body, headers: headers );

* For message with reply. This one expect a consumer reference as callback
eventbus.sendWithReply( "address", consumer, body: body, headers: headers, decoder: decoder );

* For message with reply. On this async await is used to receive messages asynchronously.
Future<VertxEventBusMessage> future = eventbus.sendWithReplyAsync( "address", body: body, headers: headers, decoder: decoder );

eventbus.publish( "address", body: body, headers: headers );

Consume messages from the event bus #

Usual consumer can be registered together with its responsible decoder.

ConsumerRegistry reg = eventBus.consumer( "address", consumer, decoder: decoder );

* Unregister this way.
reg.unregister( );

Upcomings / planned #

  • Improvements on the SockJS API like Stream and / or async await
  • Refactor file / class structure

Lifecycle and updates #

New versions of this library will be initiated by new Vert.x version.

Features and bugs #

Please submit them on issue tracker

Changelog #

3.5.0 #

  • Vertx 3.5.0
  • Upgrade all Dart dependencies
  • Logger version constraint
  • Increase minimum Dart SDK to 1.24.2 (next release would be probably for 2.0)

3.4.1 #

  • Arrange version to Vert.x version
  • JS-interopt fixed / rewritten. Should now work on any browsers (IE / Edge and Opera not tested)
  • API improvements like more optional parameters
  • Auto reconnect
  • Small encoder / decoder API
  • Improve tests
  • More complete readme

0.3.4 #

  • Initial version, corresponds to SockJS 0.3.4 / Vert.x 3.3.2

Use this package as a library

1. Depend on it

Add this to your package's pubspec.yaml file:

  vertx_dart_sockjs: ^3.5.0

2. Install it

You can install packages from the command line:

with pub:

$ pub get

Alternatively, your editor might support pub get. Check the docs for your editor to learn more.

3. Import it

Now in your Dart code, you can use:

import 'package:vertx_dart_sockjs/event_bus_codec.dart';
import 'package:vertx_dart_sockjs/event_bus_message.dart';
import 'package:vertx_dart_sockjs/sockjs.dart';
import 'package:vertx_dart_sockjs/vertx_event_bus.dart';
Describes how popular the package is relative to other packages. [more]
Code health derived from static analysis. [more]
Reflects how tidy and up-to-date the package is. [more]
Weighted score of the above. [more]
Learn more about scoring.

The package version is not analyzed, because it does not support Dart 2. Until this is resolved, the package will receive a health and maintenance score of 0.

Analysis issues and suggestions

Support Dart 2 in pubspec.yaml.

The SDK constraint in pubspec.yaml doesn't allow the Dart 2.0.0 release. For information about upgrading it to be Dart 2 compatible, please see


Package Constraint Resolved Available
Direct dependencies
Dart SDK >=1.24.2 <2.0.0