@stomp/ng-stomp v0.5.0
@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 incompilerOptions
:
"paths": {
"@stomp/ng2-stompjs": ["../node_modules/@stomp/ng2-stompjs"]
}
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"]
},
...
}
...
}
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 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.
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 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, 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
6 years ago