An Angular (Angular2, Angular4, Angular5 ...) style wrapper for @stomp/stompjs.
Recently documentation has been switched to Compodoc from TypeDoc. Please raise an issue if you find broken links or inconsistency in documentation.
Tested with Angular CLI generated Angular2 (2.4.0), Angular4 (4.0.0), Angular (5.0.0). It has been reported to work with ionic projects as well.
To install this library, run:
$ npm install @stomp/ng2-stompjs --save
or, if using yarn:
$ yarn add @stomp/ng2-stompjs
This will additionally install @stomp/stompjs from https://github.com/stomp-js/stomp-websocket
- See API documentation at https://stomp-js.github.io/ng2-stompjs/injectables/StompService.html, https://stomp-js.github.io/ng2-stompjs/injectables/StompRService.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 a http call (APP_INITIALIZER)
- See SockJS Support. https://github.com/stomp-js/ng4-stompjs-demo/tree/sockjs for a sample using SockJS
You must read https://stomp-js.github.io/ng2-stompjs/additional-documentation/sock-js.html
- You will need to have a Stomp broker running.
- The 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.)
- 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 it See https://angular.io/docs/ts/latest/guide/dependency-injection.html for background reading - Sample configuration:
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 provideStompService
andStompConfig
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
In your constructor (typically of a component or a service), inject
StompService
as a dependency:
constructor(private _stompService: StompService) { }
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/injectables/StompRService.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';
You will need to unsubscribe from stomp_subscription (which is an Observer), it will then internally unsubscribe from the underlying STOMP queue subscription.
Call publish(queueName: string, message: string, headers: StompHeaders = {})
(details at: https://stomp-js.github.io/ng2-stompjs/injectables/StompRService.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()
)
stompService.state
is aBehaviorSubject
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
- DISCONNECTING
- The following code will subscribe to
stompService.state
and convert 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
.
It is usually possible to use 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
The initialization process can be manually controlled with the additional
class StompRService
which is injected
instead of StompService
. This has a few additional
methods to assign a configuration and manually initiate the connection to the STOMP Broker.
// 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();
}
}
The methods subscribe
and publish
can be called even before call to initAndConnect
.
However these will be queued till the actual connection is successful.
For the curious - initAndConnect
may be called more than once with a potentially
updated configuration.
- Sam Finnigan
- Jimi (Dimitris) Charalampidis
- Deepak Kumar
- Astha Deep
- Michel Promonet
- Everyone involved at https://github.com/stomp-js/stomp-websocket
MIT