Connecting to services¶

More often than not, you will want to connect to Snorky from Javascript in a web application. For this purpose, there is an official connector, Snorky.js.

Dependencies¶

Snorky.js has a few dependencies that must be included before it:

my.class.js: A lightweight class library for Javascript. Javascript does not have a declarative syntax to define classes, which makes writing them a tedious and error-prone process. This is one of many libraries trying to fill that gap.

Once initialized, this class factory is stored in Snorky.Class().

js-signals: An event library for Javascript. All events defined in Snorky are created with this, which allows you to easily add and remove any number of handlers for each event.

Once initialized, the event class is stored in Snorky.Signal(). Although in vanilla usage this class will be the same as js-signal’s signals.Signal(), additional initialization code may replace it with a subclass which provides additional functionality.

For example, Angular-Snorky does this in order to request a $digest cycle to AngularJS every time an event is dispatched in order to update the view.

Promises¶

Additionally, Snorky returns promises for service requests. In order for this to work, Snorky needs a Promise class.

By default it will use the Promise class defined in ECMAScript 6, but it can be changed to any other class with a similar interface running the following code after snorky.js has been included:

Snorky.Promise = <your promise class>;

Particularly, Angular-Snorky does this as part of its initialization in order to make Snorky work with Angular promises instead of ES6 promises.

If you choose to use ES6 promises, chances are you will need a polyfill since, at the time of writing, most browsers don’t support them out of the box yet. Jake Archibald has published such polyfill at GitHub.

Socket class¶

Snorky needs a socket class in order to connect to the server. This class must have the WebSocket interface.

Nowadays most browsers in use support WebSocket natively, making it an excellent choice for a number of applications. In cases where older browser support is needed (e.g. IE9 or older) SockJS provides a viable alternative, providing fallback transports for old browsers but using WebSocket under the hood in modern browsers.

Connecting¶

Once snorky.js and all the dependencies needed have been included, the Snorky class will be available in the global namespace.

class Snorky(socketClass, address, services[, options])¶

Manages a connection to Snorky and its associated service connectors. Connection is automatically made on object creation.

Arguments:

socketClass (class) –
The socket class which will be used for the connection.

It must provide the same interface as WebSocket(). It’s usually either WebSocket or SockJS.

Note that this parameter requests the class itself, not an instance.
address (String) – The URL which will be passed to the constructor of socketClass. Note that WebSocket uses ws:// or wss:// as protocol while SockJS uses http:// or https:// instead.
services (Object) – A dictionary matching each service name with a class. Those classes will be used to interact with the services from Javascript.
options (Object) –
An optional dictionary with additional options. At the moment only one option is supported:

debug¶

Whether to print debugging information to the console when the connection is made or lost.

address¶: The address to which the socket has been connected.

socketClass¶: The socket class used.

debug: Whether the debug mode is enabled.

services¶: Dictionary of service instances available, indexed by name.

isConnected¶: Whether there is an active connection to the server.

isConnecting¶: Whether a connection to the server is being attempted.

logDebug(format[, ...])¶

Logs text in the console, but only if the debug mode is active.

Accepts either any object or a format string with arguments like console.debug().

Events

connected¶: Event raised when a connection is successfully made to the server.

disconnected¶: Event raised when a connection is closed, either voluntarily or due to a network failure.

Service connectors¶

Snorky.js has a number of classes which provide an interface to the Snorky services from the client side. They should inherit from Snorky.Service(), or, more frequently, from Snorky.RPCService().

class Snorky.Service(name, snorky)¶

Provides an interface to a Snorky service.

Usually you don’t need to create instances of this class directly, Snorky() does automatically.

Arguments:	name (String) – The name of the service instance in the server side. snorky (Snorky) – The Snorky object this service connector belongs.

name¶: The service name.

snorky¶: The Snorky object this service connector belongs.

init()¶: Initialization hook. You usually extend it in your subclasses in order to listen for events, register attributes or do other initialization work.

sendMessage(message)¶: Sends a message to the service. message must be serializable to JSON.

Events

packetReceived¶: Event raised when a new message arrives to this service.

class Snorky.RPCService(name, snorky)¶

Provides a convenient connector for RPC services.

If you are writing a connector to an RPC service you should subclass this class instead of Snorky.Service().

rpcCall(command, params)¶

Arguments:

command (String) – The command to request
params (Object) – A dictionary of parameters.

Returns:

An A+ Promise.

If the remote call is successful, the promise will be fulfilled with the value returned from the remote call.

If the remote call fails, the promise will be rejected with the error message sent by Snorky.

Makes an RPC call.

addRPCMethods(methods)¶

Arguments:	methods (Array) – A list of command names

This is an static method.

Adds the specified RPC commands as methods to the class. For each command a method with the same name will be generated which will accept one argument with the RPC parameters and will return a Promise.

Internally these methods will call to Snorky.RPCService.addRPCMethods().

Events

notificationReceived¶: Event raised when a notification is received; that is, a message whose type is neither response or error.

SimplePubSub connector¶

The following service connector makes easy to use the SimplePubSubService example service described in example-pubsub:

var SimplePubSub = new Snorky.Class(Snorky.RPCService, {
  init: function() {
    // Call the superclass init()
    Snorky.RPCService.prototype.init();

    // Listen notificationReceived events
    this.notificationReceived.add(this.onNotification, this);

    // Create new event
    this.publicationReceived = new Snorky.Signal();
  },

  onNotification: function(notification) {
    if (notification.type == "publication") {
      // Dispatch the publicationReceived event
      this.publicationReceived.dispatch(notification.message);
    }
  }
});
SimplePubSub.addRPCMethods([
  "subscribe",
  "unsubscribe",
  "publish"
]);

Connection example¶

The following example connects to an Snorky server with the SimplePubSub service described above.

var snorky = new Snorky(WebSocket, "ws://localhost:8001/ws", {
    "pubsub": SimplePubSub
});

snorky.services contains the instantiated services. The following code would request a subscription.

snorky.services.pubsub.subscribe({ /* no parameters */ })
  .then(function (returnValue) {
    console.log("Subscribed!");
  });

Note

The services can be used even before the connection has been established. Snorky will store the messages in a buffer and send them when the connection is made.

Event handlers can be added too at this stage. The following would log messages published.

snorky.services.pubsub.publicationReceived.add(
  function(publishedText) {
    console.log(publishedText)
  });

Conclusion¶

This chapter has shown the basics of the Javascript Snorky connector, including how to include it, how connect to it and how services connector can be written and used.

The following chapter will cover the backend interface.