0.5.0 • Published 8 years ago

@stomp/ng-stomp-x v0.5.0

Weekly downloads
1
License
MIT
Repository
github
Last release
8 years ago

@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

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

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

    "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

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

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

    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
    };
  providers: [
    StompService,
    {
      provide: StompConfig,
      useValue: stompConfig
    }
  ]

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

License

MIT

stompjsangular2angular4angular5rabbitmqwebsocketangularstomp
@stomp/stompjs
@everything-registry/sub-chunk-874
0.5.0

8 years ago