@stomp/ng-stomp-x

@stomp/ng2-stompjs

An Angular (Angular2, Angular4, ...) style wrapper for @stomp/stompjs.

Compatibility

There were compatibility issues reported, so this project has now switched to source distribution. In case it does not work for your setup, please raise a ticket.

Tested with Angular2 (2.4.0), Angular4 (4.0.0), Angular (5.0.0), and ionic projects created with Angular CLI.

See notes below for Angular 5 and ionic.

Changelog

0.4.3

• Ability to delay initialization.
• Angular 5 compatibility

0.4.2

Initial SockJS Support. Sample at https://github.com/stomp-js/ng4-stompjs-demo/tree/sockjs

0.4.0

Updated to make it compliant to possible use of APP_INITIALIZER. Please note that way to initiate the service has changed. It no longer uses StompConfigService. StompConfig is directly injected as dependency into StompService.

0.3.8

• Switched to source distribution. The npm bundle now only has .ts files.

0.3.5

• Test case at https://github.com/stomp-js/ng2-stompjs-testbed these will be merged into main repository in future. Currently unable to configure Karma correctly in the main project. Any help appreciated.

0.3.4

• added references to GitHub pages.

0.3.0

• Configuration structure has changed, user/password are not part of header.
• Support for headers in connect, subscribe, and publish.
• Typedoc for API documentation.

Installation

To install this library, run:

$ npm install @stomp/ng2-stompjs --save

or, if using yarn

$ yarn add @stomp/ng2-stompjs

This will addtionally install @stomp/stompjs from https://github.com/stomp-js/stomp-websocket

Usage

• See API documentation at https://stomp-js.github.io/ng2-stompjs/classes/stompservice.html and https://stomp-js.github.io/ng2-stompjs/index.html
• See https://github.com/stomp-js/ng4-stompjs-demo for a working sample using Angular4 and Angular CLI.
• See https://github.com/stomp-js/ng2-stompjs-demo for a working sample using Angular2 and Angular CLI. This version also demonstrates fetching Stomp configuration using an http call (APP_INITIALIZER).
• See SockJS Support. https://github.com/stomp-js/ng4-stompjs-demo/tree/sockjs for a sample using SockJS.

Agular 5 & Ionic

This project is distributed as ts files. You need to instruct the compiler to include files from this library to be compiled as part of the build process.

Angular 5

• Sample at https://github.com/stomp-js/ng5-stompjs-demo
• In src/tsconfig.app.json place the following in compilerOptions:

    "paths": {
        "@stomp/ng2-stompjs": ["../node_modules/@stomp/ng2-stompjs"]
    }

See: https://github.com/stomp-js/ng5-stompjs-demo/blob/3594c458f98e7c4523b7d274c6dbf94e600f2c8c/src/tsconfig.app.json#L7

Ionic

• Sample at https://github.com/sjbwylbs/ionic-ng2-stompjs
• In tsconfig.json ensure the following:

{
  "compilerOptions": {
    ...
    "baseUrl": "./src",
    "paths": {
      "@stomp/ng2-stompjs": ["../node_modules/@stomp/ng2-stompjs"]
    },
    ...
  }
  ...
}

• See: https://github.com/sjbwylbs/ionic-ng2-stompjs/blob/c0bd2e0d216c289fbb0225992969d826ee8d2459/tsconfig.json#L15

Prerequisites

• You will need to have a Stomp broker running.
• Sample code on this page assumes you have RabbitMQ running with default settings and Web STOMP plugin activated. (see: https://www.rabbitmq.com/web-stomp.html).

All the Hard Work

• The main service is StompService, which will need to be provided.
• The STOMP Broker connection details will need to be provided via
  class StompConfig. See the samples for several ways to configure. See https://angular.io/docs/ts/latest/guide/dependency-injection.html for background reading.
• Sample config:

    const stompConfig: StompConfig = {
      // Which server?
      url: 'ws://127.0.0.1:15674/ws',
    
      // Headers
      // Typical keys: login, passcode, host
      headers: {
        login: 'guest',
        passcode: 'guest'
      },
    
      // How often to heartbeat?
      // Interval in milliseconds, set to 0 to disable
      heartbeat_in: 0, // Typical value 0 - disabled
      heartbeat_out: 20000, // Typical value 20000 - every 20 seconds
    
      // Wait in milliseconds before attempting auto reconnect
      // Set to 0 to disable
      // Typical value 5000 (5 seconds)
      reconnect_delay: 5000,
    
      // Will log diagnostics on console
      debug: true
    };

• See https://github.com/stomp-js/ng4-stompjs-demo/blob/master/src/app/app.module.ts for a sample code file with configuration passed from a local hash. Feel free to copy and modify this file.
• See https://github.com/stomp-js/ng2-stompjs-demo/blob/master/src/app/app.module.ts for a sample code file with configuration fetched from a http resource.
• Assuming the config specified as a const, code sample to provide StompService and StompConfig will look like:

  providers: [
    StompService,
    {
      provide: StompConfig,
      useValue: stompConfig
    }
  ]

• See https://github.com/stomp-js/ng4-stompjs-demo/blob/master/src/app/app.module.ts for a sample file.

Reap the Benefits

Inject StompService

In your constructor (typically of a component or a service), inject StompService as a dependency:

constructor(private _stompService: StompService) { }

Subscribe to a queue

The queue name structure and semantics vary based on your specific STOMP Broker, see: https://www.rabbitmq.com/stomp.html for RabbitMQ specific details.

Call subscribe(queueName: string, headers: StompHeaders = {}) with name of the queue which returns an Observable (details at: https://stomp-js.github.io/ng2-stompjs/classes/stompservice.html#subscribe). Any of Observable specific operators (map, filter, subscribe, etc.) can be applied on it. This can also be set into a template with async pipe.

Example:

    let stomp_subscription = this._stompService.subscribe('/topic/ng-demo-sub');

    stomp_subscription.map((message: Message) => {
      return message.body;
    }).subscribe((msg_body: string) => {
      console.log(`Received: ${msg_body}`);
    });

The Message class comes from @stomp/stompjs. So, you will need the following import in the classes where you consume messages:

import {Message} from '@stomp/stompjs';

Unsubscribe from a queue

Not a likely chance that you would need it.

You will need to unsubscribe from stomp_subscription (which is an Observer), it will then internally unsubscribe from the underlying STOMP queue subscription.

Publishing messages

Call publish(queueName: string, message: string, headers: StompHeaders = {}) (details at: https://stomp-js.github.io/ng2-stompjs/classes/stompservice.html#publish). Example:

this._stompService.publish('/topic/ng-demo-sub', 'My important message');

Please note that message is actually string. So, if you need to send JSON you will need to convert it into string (typically using JSON.stringify())

Watching for Stomp connection status

• stompService.state is a BehaviorSubject which maintains and switches its value as per the underlying Stomp Connection status.
• The value is from an enum with these possible values: CLOSED, TRYING, CONNECTED, and DISCONNECTING.
• The following code will subscribe to stompService.state and covert the enum value (which is a number) to the corresponding string value:

    this._stompService.state
      .map((state: number) => StompState[state])
      .subscribe((status: string) => {
      console.log(`Stomp connection status: ${status}`);
    });

If you are interested in watching only when connection is established, you can subscribe to this._stompService.connectObservable.

Delayed initialization

While often it is possible using Angular dependency injection techniques and APP_INITIALIZER to delay the initialization till the configuration is ready (may be fetched using an API call). See a sample at: https://github.com/stomp-js/ng2-stompjs-demo

If a manual control is needed on the initialization process there is an additional class StompRService, inject it instead of StompService. This has few additional methods to assign a configuration and manually connect.

// Do not provide StompService or StompConfig, only provide StompRService

  providers: [
    StompRService
  ]

class YourClass {}
    constructor(private _stompService: StompRService) { }
    
    public initStomp() {
      StompConfig config;
  
      cofig = this.fetchConfigFromSomeWhere();
      
      this._stompService.config = config;
      this._stompService.initAndConnect();
    }
}

subscribe and publish can be called even before call to initAndConnect. These however will be interally queued till actual connection is successful.

For the curious - initAndConnect may be called more than once with potentially updated config.

Development

After checking out, install the dependencies:

$ npm install

or, if using yarn

$ yarn

To generate documentation:

$ npm run doc

To lint all *.ts files:

$ npm run lint

Contributors

• Sam Finnigan
• Jimi (Dimitris) Charalampidis
• Deepak Kumar
• Everyone involved at https://github.com/stomp-js/stomp-websocket

License

MIT