You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
You can find samples at [https://github.com/stomp-js/samples/](https://github.com/stomp-js/samples/).
14
15
15
16
## The STOMP Broker
16
17
17
-
Ensure that your STOMP broker supports STOMP over WebSockets. While some messaging brokers support it out of the box, a few may need additional configuration or activating plugins.
18
+
Ensure that your STOMP broker supports STOMP over WebSockets. While some messaging brokers support it out of the box, a
19
+
few may need additional configuration or activating plugins.
18
20
19
21
## Include stompjs
20
22
21
-
This npm distribution has a UMD package and ES6 modules. The web browsers will use the UMD via a script tag, and Node's `require` and ES `import` will use the appropriate versions.
23
+
This npm distribution has a UMD package and ES6 modules. The web browsers will use the UMD via a script tag, and Node's
24
+
`require` and ES `import` will use the appropriate versions.
22
25
23
26
### Polyfills
24
27
@@ -28,8 +31,9 @@ _Important: For NodeJS and React Native, please check [Polyfills]._
28
31
29
32
- Download and include directly from the `bundles/` folder.
-`StompJs` object will now be available. Read along to learn how to use it.
34
38
35
39
### In NodeJS, TypeScript or ES6
@@ -39,7 +43,7 @@ These libraries have been developed using typescript, and the typings are includ
39
43
You can import classes like the following:
40
44
41
45
```javascript
42
-
import {Client, Message} from'@stomp/stompjs';
46
+
import {Client, Message} from'@stomp/stompjs';
43
47
```
44
48
45
49
You can use these classes without prefixing with `StompJs.`.
@@ -105,10 +109,11 @@ client.deactivate();
105
109
106
110
## Send messages
107
111
108
-
When the client is connected to the server, it can send STOMP messages using the [Client#publish](/api-docs/latest/classes/Client.html#publish) method.
112
+
When the client is connected to the server, it can send STOMP messages using
113
+
the [Client#publish](/api-docs/latest/classes/Client.html#publish) method.
The STOMP client must first subscribe to a destination to receive messages.
145
150
146
-
To subscribe to a destination, you can use the [Client#subscribe](/api-docs/latest/classes/Client.html#subscribe) method. The method takes two mandatory arguments: `destination`, a String corresponding to the
147
-
destination and `callback`, a function with one message argument and an optional argument `headers`, a JavaScript object for additional headers.
151
+
To subscribe to a destination, you can use the [Client#subscribe](/api-docs/latest/classes/Client.html#subscribe)
152
+
method. The method takes two mandatory arguments: `destination`, a String corresponding to the
153
+
destination and `callback`, a function with one message argument and an optional argument `headers`, a JavaScript object
@@ -154,7 +161,8 @@ The `subscribe` method returns an object with one attribute, `id`,
154
161
that correspond to the client subscription ID and one method `unsubscribe`
155
162
that can be used later on to unsubscribe the client from this destination.
156
163
157
-
Every time the broker sends a message to the client, the client will, in turn, invoke the callback with a [Message](/api-docs/latest/interfaces/IMessage.html) object.
164
+
Every time the broker sends a message to the client, the client will, in turn, invoke the callback with
165
+
a [Message](/api-docs/latest/interfaces/IMessage.html) object.
158
166
159
167
```javascript
160
168
callback=function (message) {
@@ -167,10 +175,11 @@ callback = function (message) {
167
175
};
168
176
```
169
177
170
-
The `subscribe` method takes an optional headers argument to specify additional `headers` when subscribing to a destination:
178
+
The `subscribe` method takes an optional headers argument to specify additional `headers` when subscribing to a
Not every broker will support binary messages out of the box.
196
-
For example, RabbitMQ (see: https://www.rabbitmq.com/web-stomp.html) will need the following to be added to the server configuration:
205
+
For example, RabbitMQ (see: https://www.rabbitmq.com/web-stomp.html) will need the following to be added to the server
206
+
configuration:
197
207
198
208
```
199
209
web_stomp.ws_frame = binary
200
210
```
201
211
202
212
### Publishing binary messages
203
213
204
-
Use parameter `binaryBody` of [Client#publish](/api-docs/latest/classes/Client.html#publish) to send binary data of a type [Uint8Array].
214
+
Use parameter `binaryBody` of [Client#publish](/api-docs/latest/classes/Client.html#publish) to send binary data of a
215
+
type [Uint8Array].
205
216
206
217
See [Send messages](#send-messages) for an example.
207
218
208
219
### Receiving binary messages
209
220
210
221
The library does not guess whether the incoming datum is text/binary.
211
-
To access the message body as a string, please use [Message#body](/api-docs/latest/interfaces/IFrame.html#body) and to access it as binary, please use [Message#binaryBody](/api-docs/latest/interfaces/IFrame.html#binaryBody).
222
+
To access the message body as a string, please use [Message#body](/api-docs/latest/interfaces/IFrame.html#body) and to
223
+
access it as binary, please use [Message#binaryBody](/api-docs/latest/interfaces/IFrame.html#binaryBody).
212
224
213
-
There is no generally accepted convention in STOMP (actually messaging in general) to indicate binary messages. Therefore, the message senders and receivers must agree on the required convention. For example, you may choose to set a `content-type` header to indicate a binary message.
225
+
There is no generally accepted convention in STOMP (actually messaging in general) to indicate binary messages.
226
+
Therefore, the message senders and receivers must agree on the required convention. For example, you may choose to set a
227
+
`content-type` header to indicate a binary message.
214
228
215
229
```javascript
216
230
// within message callback
@@ -225,10 +239,11 @@ if (message.headers['content-type'] === 'application/octet-stream') {
225
239
226
240
## JSON support
227
241
228
-
The body of a STOMP message must be a String or a [Uint8Array]. If you want to send and receive [JSON](http://json.org/) objects, you can use `JSON.stringify()` and`JSON.parse()` to transform the JSON object to a String and vice versa.
242
+
The body of a STOMP message must be a String or a [Uint8Array]. If you want to send and receive [JSON](http://json.org/)
243
+
objects, you can use `JSON.stringify()` and`JSON.parse()` to transform the JSON object to a String and vice versa.
229
244
230
245
```javascript
231
-
constquote= {symbol:'AAPL', value:195.46};
246
+
constquote= {symbol:'AAPL', value:195.46};
232
247
client.publish({
233
248
destination:'/topic/stocks',
234
249
body:JSON.stringify(quote),
@@ -244,9 +259,11 @@ client.subscribe('/topic/stocks', function (message) {
244
259
245
260
By default, the server will automatically acknowledge STOMP messages before the message is delivered to the client.
246
261
247
-
Instead, the client can choose to handle message acknowledgment by subscribing to a destination with the `ack` header set to `client` or `client-individual`.
262
+
Instead, the client can choose to handle message acknowledgment by subscribing to a destination with the `ack` header
263
+
set to `client` or `client-individual`.
248
264
249
-
In that case, the client must use the [Message#ack](/api-docs/latest/interfaces/IMessage.html#ack) method to inform the broker that it has processed the message.
265
+
In that case, the client must use the [Message#ack](/api-docs/latest/interfaces/IMessage.html#ack) method to inform the
The [Message#ack](/api-docs/latest/interfaces/IMessage.html#ack) method accepts `headers` argument for additional headers. For example, to acknowledge a message as part of a transaction and request a receipt:
281
+
The [Message#ack](/api-docs/latest/interfaces/IMessage.html#ack) method accepts `headers` argument for additional
282
+
headers. For example, to acknowledge a message as part of a transaction and request a receipt:
The client should [Message#nack](/api-docs/latest/interfaces/IMessage.html#nack) to inform STOMP 1.1 or higher brokers that the client did not consume the message. It takes the same arguments as the [Message#ack](/api-docs/latest/interfaces/IMessage.html#ack) method.
290
+
The client should [Message#nack](/api-docs/latest/interfaces/IMessage.html#nack) to inform STOMP 1.1 or higher brokers
291
+
that the client did not consume the message. It takes the same arguments as
292
+
the [Message#ack](/api-docs/latest/interfaces/IMessage.html#ack) method.
273
293
274
294
## Transactions
275
295
276
296
Messages can be sent and acknowledged _in a transaction_.
277
297
278
-
The client starts a transaction using the [Client#begin](/api-docs/latest/classes/Client.html#begin) method, which takes an optional `transaction_id`.
298
+
The client starts a transaction using the [Client#begin](/api-docs/latest/classes/Client.html#begin) method, which takes
299
+
an optional `transaction_id`.
279
300
280
301
This method returns an object with an `id` attribute corresponding to the transaction ID and two methods:
281
302
282
303
-[Client#commit](/api-docs/latest/classes/Client.html#commit) to commit the transaction, and,
283
304
-[Client#abort](/api-docs/latest/classes/Client.html#abort) to abort the transaction.
284
305
285
-
The client can then send and acknowledge messages in the transaction by specifying a `transaction` indetified by the transaction `id`.
306
+
The client can then send and acknowledge messages in the transaction by specifying a `transaction` indetified by the
307
+
transaction `id`.
286
308
287
309
```javascript
288
310
// start the transaction
289
311
consttx=client.begin();
290
312
// send the message in a transaction
291
313
client.publish({
292
314
destination:'/queue/test',
293
-
headers: {transaction:tx.id},
315
+
headers: {transaction:tx.id},
294
316
body:'message in a transaction',
295
317
});
296
318
// commit the transaction to effectively send the message
297
319
tx.commit();
298
320
```
299
321
300
-
_If you forget to add the `transaction` header when calling [Client#publish](/api-docs/latest/classes/Client.html#publish), the message will not be part of the transaction, and it will be sent directly without waiting for the completion of the transaction._
322
+
_If you forget to add the `transaction` header when
323
+
calling [Client#publish](/api-docs/latest/classes/Client.html#publish), the message will not be part of the transaction,
324
+
and it will be sent directly without waiting for the completion of the transaction._
301
325
302
326
```javascript
303
327
// start the transaction
@@ -312,7 +336,10 @@ tx.abort(); // Too late! the message has been sent
312
336
313
337
## Heart-beating
314
338
315
-
For a connection with STOMP protocol 1.1 or higher, heart-beating is enabled by default. Options [Client#heartbeatIncoming](/api-docs/latest/classes/Client.html#heartbeatIncoming) and [Client#heartbeatOutgoing](/api-docs/latest/classes/Client.html#heartbeatOutgoing) can be used to control heart-beating (default value for both is 10,000ms). The client can disable heart beating by setting these to 0.
339
+
For a connection with STOMP protocol 1.1 or higher, heart-beating is enabled by default.
and [Client#heartbeatOutgoing](/api-docs/latest/classes/Client.html#heartbeatOutgoing) can be used to control
342
+
heart-beating (default value for both is 10,000ms). The client can disable heart beating by setting these to 0.
316
343
317
344
```javascript
318
345
client.heartbeatOutgoing=20000; // client will send heartbeats every 20000ms
@@ -322,7 +349,9 @@ client.heartbeatIncoming = 0; // client does not want to receive heartbeats
322
349
323
350
## Auto Reconnect
324
351
325
-
The `client` supports automatic reconnecting in case of a connection failure. It is controlled by a option [Client#reconnectDelay](/api-docs/latest/classes/Client.html#reconnectDelay). The default value is 5000ms, which indicates that an attempt to connect will be made 5000ms after a connection drop.
352
+
The `client` supports automatic reconnecting in case of a connection failure. It is controlled by a
353
+
option [Client#reconnectDelay](/api-docs/latest/classes/Client.html#reconnectDelay). The default value is 5000ms, which
354
+
indicates that an attempt to connect will be made 5000ms after a connection drop.
326
355
327
356
```javascript
328
357
// Add the following if you need automatic reconnect (delay is in milliseconds)
reconnectDelay:200, // It will wait 200, 400, 800 ms...
369
+
maxReconnectDelay:10000, // Optional, when provided, it will not wait more that these ms
370
+
})
371
+
```
372
+
334
373
## Debug
335
374
336
375
On a busy system, the volume of logs can be overwhelming. Therefore, by default, the debug messages are ignored.
337
376
338
-
[Client#debug](/api-docs/latest/classes/Client.html#debug) property can be set to a function (which will receive a `String` argument) to enable debug statements:
377
+
[Client#debug](/api-docs/latest/classes/Client.html#debug) property can be set to a function (which will receive a
378
+
`String` argument) to enable debug statements:
339
379
340
380
```javascript
341
381
client.debug=function (str) {
342
382
console.log(str);
343
383
};
344
384
```
345
385
346
-
Usually, headers of the incoming and outgoing frames are logged. Set [Client#logRawCommunication](/api-docs/latest/classes/Client.html#logRawCommunication) to log entire frames.
386
+
Usually, headers of the incoming and outgoing frames are logged.
387
+
Set [Client#logRawCommunication](/api-docs/latest/classes/Client.html#logRawCommunication) to log entire frames.
347
388
348
389
## Callbacks
349
390
350
391
### Lifecycle callbacks
351
392
352
-
-[Client#beforeConnect](/api-docs/latest/classes/Client.html#beforeConnect) - invoked each time before connection to STOMP broker is attempted. You can modify connection parameters and other callbacks. On v6+ you can set an async function for this callback.
353
-
-[Client#onConnect](/api-docs/latest/classes/Client.html#onConnect) - invoked for each time STOMP broker connects and STOMP handshake is complete.
354
-
-[Client#onDisconnect](/api-docs/latest/classes/Client.html#onDisconnect) - invoked after each graceful disconnection. If the connection breaks because of an error or network failure, it will not be called.
393
+
-[Client#beforeConnect](/api-docs/latest/classes/Client.html#beforeConnect) - invoked each time before connection to
394
+
STOMP broker is attempted. You can modify connection parameters and other callbacks. On v6+ you can set an async
395
+
function for this callback.
396
+
-[Client#onConnect](/api-docs/latest/classes/Client.html#onConnect) - invoked for each time STOMP broker connects and
397
+
STOMP handshake is complete.
398
+
-[Client#onDisconnect](/api-docs/latest/classes/Client.html#onDisconnect) - invoked after each graceful disconnection.
399
+
If the connection breaks because of an error or network failure, it will not be called.
355
400
-[Client#onStompError](/api-docs/latest/classes/Client.html#onStompError) - invoked when the broker reports an Error.
356
-
-[Client#onWebSocketClose](/api-docs/latest/classes/Client.html#onWebSocketClose) - when the WebSocket closes. It is the most reliable way of knowing that the connection has terminated.
401
+
-[Client#onWebSocketClose](/api-docs/latest/classes/Client.html#onWebSocketClose) - when the WebSocket closes. It is
402
+
the most reliable way of knowing that the connection has terminated.
357
403
358
404
### Frame callbacks
359
405
360
-
-[Client#onUnhandledMessage](/api-docs/latest/classes/Client.html#onUnhandledMessage) - typically brokers will send messages corresponding to subscriptions. However, brokers may support concepts beyond the standard definition of STOMP - for example, RabbitMQ supports concepts of temporary queues. This callback will be invoked if any message is received that is not linked to a subscription.
361
-
-[Client#onUnhandledReceipt](/api-docs/latest/classes/Client.html#onUnhandledReceipt) - you should prefer [Client#watchForReceipt](/api-docs/latest/classes/Client.html#watchForReceipt). If there is any incoming receipt for which there is no active watcher, this callback will be invoked.
362
-
-[Client#onUnhandledFrame](/api-docs/latest/classes/Client.html#onUnhandledFrame) - it will be invoked if broker sends a non standard STOMP Frame.
406
+
-[Client#onUnhandledMessage](/api-docs/latest/classes/Client.html#onUnhandledMessage) - typically brokers will send
407
+
messages corresponding to subscriptions. However, brokers may support concepts beyond the standard definition of
408
+
STOMP - for example, RabbitMQ supports concepts of temporary queues. This callback will be invoked if any message is
409
+
received that is not linked to a subscription.
410
+
-[Client#onUnhandledReceipt](/api-docs/latest/classes/Client.html#onUnhandledReceipt) - you should
411
+
prefer [Client#watchForReceipt](/api-docs/latest/classes/Client.html#watchForReceipt). If there is any incoming
412
+
receipt for which there is no active watcher, this callback will be invoked.
413
+
-[Client#onUnhandledFrame](/api-docs/latest/classes/Client.html#onUnhandledFrame) - it will be invoked if broker sends
414
+
a non standard STOMP Frame.
363
415
364
416
## Advanced notes
365
417
366
418
Version 5+ of this library has taken significant variation from the previous syntax.
367
419
368
-
It is possible to alter configuration options and callbacks. New values will take effect as soon as possible. For example:
420
+
It is possible to alter configuration options and callbacks. New values will take effect as soon as possible. For
421
+
example:
369
422
370
-
- Altered values of [Client#onUnhandledMessage](/api-docs/latest/classes/Client.html#onUnhandledMessage) or [Client#onDisconnect](/api-docs/latest/classes/Client.html#onDisconnect) will be effective immediately.
371
-
- New values of [Client#heartbeatIncoming](/api-docs/latest/classes/Client.html#heartbeatIncoming) and [Client#heartbeatOutgoing](/api-docs/latest/classes/Client.html#heartbeatOutgoing) will be used next time STOMP connects.
423
+
- Altered values of [Client#onUnhandledMessage](/api-docs/latest/classes/Client.html#onUnhandledMessage)
424
+
or [Client#onDisconnect](/api-docs/latest/classes/Client.html#onDisconnect) will be effective immediately.
425
+
- New values of [Client#heartbeatIncoming](/api-docs/latest/classes/Client.html#heartbeatIncoming)
426
+
and [Client#heartbeatOutgoing](/api-docs/latest/classes/Client.html#heartbeatOutgoing) will be used next time STOMP
427
+
connects.
372
428
373
-
The callback sequences are arranged in a way that most expected operations should work. For example, it is possible to call [Client#deactivate](/api-docs/latest/classes/Client.html#deactivate) within [Client#onStompError](/api-docs/latest/classes/Client.html#onStompError) or [Client#onWebSocketClose](/api-docs/latest/classes/Client.html#onWebSocketClose).
429
+
The callback sequences are arranged in a way that most expected operations should work. For example, it is possible to
within [Client#onStompError](/api-docs/latest/classes/Client.html#onStompError)
432
+
or [Client#onWebSocketClose](/api-docs/latest/classes/Client.html#onWebSocketClose).
374
433
375
-
The above also allows adjusting [Client#reconnectDelay](/api-docs/latest/classes/Client.html#reconnectDelay) in [Client#onWebSocketClose](/api-docs/latest/classes/Client.html#onWebSocketClose). You can implement exponential back-off using a series of such adjustments.
434
+
The above also allows adjusting [Client#reconnectDelay](/api-docs/latest/classes/Client.html#reconnectDelay)
435
+
in [Client#onWebSocketClose](/api-docs/latest/classes/Client.html#onWebSocketClose). You can implement exponential
436
+
back-off using a series of such adjustments.
376
437
377
-
Even [Client#brokerURL](/api-docs/latest/classes/Client.html#brokerURL) or [Client#connectHeaders](/api-docs/latest/classes/Client.html#connectHeaders) can be altered which would get used in a subsequent reconnect.
438
+
Even [Client#brokerURL](/api-docs/latest/classes/Client.html#brokerURL)
439
+
or [Client#connectHeaders](/api-docs/latest/classes/Client.html#connectHeaders) can be altered which would get used in a
440
+
subsequent reconnect.
378
441
379
442
[Polyfills]: {% link _posts/2018-06-28-polyfills-for-stompjs.md %}
The largest number of tickets raised for these projects is related to using these libraries with React Native.
16
+
There are some platform issues in React Native that cause these libraries to fail.
17
+
Unfortunately, the React Native team is not inclined to resolve these issues.
18
+
Please follow the advice on this page to effectively use these libraries with React Native.
19
+
20
+
## Prefer [rx-stomp]
21
+
22
+
This advice is not specific to React Native, but in general, to Single Page Applications.
23
+
Your code is going to be far less convoluted and will handle edge cases much better.
24
+
Managing the Client objest and state can be tricky with React hooks.
25
+
Please see
26
+
[How to Use RxStomp with React](https://www.freecodecamp.org/news/build-chat-app-with-stomp-and-react/) and [Sample](https://gitlab.com/harsh183/rxstomp-react-tutorial).
27
+
28
+
## Polyfills
16
29
17
30
Before you proceed, ensure you have [polyfills for
18
31
TextEncoder/TextDecoder]({% link _posts/2018-06-28-polyfills-for-stompjs.md %}).
19
32
20
-
# Insecure connection issue in Android
33
+
##Insecure connection issue in Android
21
34
22
35
Recent versions of Android SDK do not allow insecure (not HTTPS) HTTP connections.
23
36
This is likely to show up in production builds only.
@@ -27,7 +40,7 @@ To bypass the checks, please follow suggestions at
and [https://blog.usejournal.com/6-daily-issues-in-android-cleartext-traffic-error-52ab31dd86c2](https://blog.usejournal.com/6-daily-issues-in-android-cleartext-traffic-error-52ab31dd86c2).
29
42
30
-
# Null Chopping
43
+
##Null Chopping
31
44
32
45
Some versions of React Native (including the current production
33
46
version as on April 26, 2024) have an underlying issue that prevents these libraries
@@ -85,3 +98,8 @@ If your broker supports forcing binary frames, you may try this approach.
85
98
86
99
The approach is completely safe — it will not cause any data loss
0 commit comments