|
| 1 | +--- |
| 2 | +layout: features |
| 3 | +title: Message Replay |
| 4 | +summary: Learn how to make use of Message Replay via the Solace JavaScript client library |
| 5 | +links: |
| 6 | + - label: MessageReplay.html |
| 7 | + link: /blob/master/src/features/MessageReplay/MessageReplay.html |
| 8 | + - label: MessageReplay.js |
| 9 | + link: /blob/master/src/features/MessageReplay/MessageReplay.js |
| 10 | +--- |
| 11 | + |
| 12 | +In this introduction we show you how a client can initiate and process the replay of previously published messages, as well as deal with an externally initiated replay. |
| 13 | + |
| 14 | +## Feature Overview |
| 15 | + |
| 16 | +During normal publishing, guaranteed messages will be removed from the message broker's [queue or topic endpoint]({{ site.docs-endpoints }}) once the consumer acknowledges their receipt or successful processing. When Message Replay is initiated for an endpoint, the message broker will re-publish a requested subset of previously published and logged messages, which enables the client to process these messages again. |
| 17 | + |
| 18 | +Message Replay can be used if a client needs to catch up with missed messages as well as for several other [use cases]({{ site.docs-replay-use-cases }}). |
| 19 | + |
| 20 | +Message Replay for an endpoint can be initiated programmatically from an API client connected to an exclusive endpoint, or administratively from the message broker. After the replay is done, the connected client will keep getting live messages delivered. |
| 21 | + |
| 22 | +It's important to note that when initiating replay, the message broker will disconnect all connected client flows, active or not. A new flow needs to be started for a client wishing to receive replayed and subsequent messages. The only exception is that in the client initiated case the flow initiating the replay will not be disconnected. |
| 23 | + |
| 24 | +## Prerequisite |
| 25 | + |
| 26 | +A replay log must be created on the message broker for the Message VPN using [Message Replay CLI configuration]({{ site.docs-replay-cli-config }}) or using [Solace PubSub+ Manager]({{ site.docs-psplus-manager }}) administration console. Another option for configuration is to use the [SEMP API]({{ site.docs-semp-api }}). |
| 27 | + |
| 28 | +NOTE: Message Replay is supported on Solace PubSub+ 3530 and 3560 appliances running release 9.1 and greater, and on the Solace PubSub+ software message broker running release 9.1 and greater. Solace JavaScript API version 10.2.1 or later is required. |
| 29 | + |
| 30 | + |
| 31 | +<br> |
| 32 | + |
| 33 | +## Code |
| 34 | + |
| 35 | +### Checking for Message Replay capability |
| 36 | + |
| 37 | +Message Replay must be supported on the message broker, so this should be the first thing the code checks: |
| 38 | + |
| 39 | +```javascript |
| 40 | +if (!consumer.session.isCapable(solace.CapabilityType.MESSAGE_REPLAY)) { |
| 41 | + consumer.log('Message Replay is not supported on this message broker, disconnecting...'); |
| 42 | + try { |
| 43 | + consumer.session.disconnect(); |
| 44 | + } catch (error) { |
| 45 | + consumer.log(error.toString()); |
| 46 | + } |
| 47 | +} |
| 48 | +``` |
| 49 | + |
| 50 | +### Initiating replay |
| 51 | + |
| 52 | +First, a `replayStartLocation` object needs to be created to specify the desired subset of messages in the replay log. |
| 53 | + |
| 54 | +There are two options: |
| 55 | +* use `createReplayStartLocationBeginning()` to replay all logged messages |
| 56 | +* use `createReplayStartLocationDate(Date date)` to replay all logged messages received starting from a specified `date`. Note the different possible formats in the example including how to specify the time zone. |
| 57 | + |
| 58 | +Note: The `date` can’t be earlier than the date the replay log was created, otherwise replay will fail. |
| 59 | + |
| 60 | +```javascript |
| 61 | +consumer.replayStartLocation = solace.SolclientFactory.createReplayStartLocationBeginning(); |
| 62 | +/*************************************************************** |
| 63 | + * Alternative replay start specifications to try instead of |
| 64 | + * createReplayStartLocationBeginning(). |
| 65 | + */ |
| 66 | +/* Milliseconds after the Jan 1st of 1970 UTC+0: */ |
| 67 | +// consumer.replayStartLocation = solace.SolclientFactory.createReplayStartLocationDate( |
| 68 | +// new Date(1554331492)); |
| 69 | + |
| 70 | +/* RFC3339 UTC date with timezone offset 0: */ |
| 71 | +// consumer.replayStartLocation = solace.SolclientFactory.createReplayStartLocationDate( |
| 72 | +// new Date(Date.parse('2019-04-03T18:48:00Z'))); |
| 73 | + |
| 74 | +/* RFC3339 date with timezone: */ |
| 75 | +// consumer.replayStartLocation = solace.SolclientFactory.createReplayStartLocationDate( |
| 76 | +// new Date(Date.parse('2019-04-03T18:48:00-05:00'))); |
| 77 | +``` |
| 78 | + |
| 79 | +Indicate that replay is requested by setting a non-null `replayStartLocation` in `solace.MessageConsumerProperties`, which is then passed to `createMessageConsumer()` as a parameter. |
| 80 | + |
| 81 | +The target endpoint (`queueDescriptor`) for replay is also set in `ConsumerFlowProperties` below, which is the normal way of setting an endpoint for a consumer flow. |
| 82 | + |
| 83 | +```javascript |
| 84 | +consumer.replayStartLocation = solace.SolclientFactory.createReplayStartLocationBeginning(); |
| 85 | +: |
| 86 | +// Create a message consumer |
| 87 | +consumer.messageConsumer = consumer.session.createMessageConsumer({ |
| 88 | + // solace.MessageConsumerProperties |
| 89 | + queueDescriptor: { name: consumer.queueName, type: solace.QueueType.QUEUE }, |
| 90 | + acknowledgeMode: solace.MessageConsumerAcknowledgeMode.CLIENT, // Enabling Client ack |
| 91 | + replayStartLocation: consumer.replayStartLocation, |
| 92 | +}); |
| 93 | +: |
| 94 | +consumer.messageConsumer.connect(); |
| 95 | +``` |
| 96 | + |
| 97 | +### Replay-related events |
| 98 | + |
| 99 | +If a replay-related event occurs, the consumer flow is disconnected and a `solace.MessageConsumerEventName.DOWN_ERROR` event is generated with a specific Subcode, which can be processed in an event handler. |
| 100 | + |
| 101 | +Some of the important Subcodes: |
| 102 | +* REPLAY_STARTED - a replay has been administratively started from the message broker; the consumer flow is being disconnected. |
| 103 | +* REPLAY_START_TIME_NOT_AVAILABLE - the requested replay start date is before when the replay log was created or in the future, which is not allowed |
| 104 | +* REPLAY_FAILED - indicates that an unexpected error has happened during replay |
| 105 | + |
| 106 | +For the definition of additional replay-related Subcodes refer to `solace.ErrorSubcode` in the [JavaScript API Reference]({{ site.docs-api-errorresponse-subcode-ex }}) (search for REPLAY). |
| 107 | + |
| 108 | +Here we will define the event handler to process events with some more example Subcodes. |
| 109 | + |
| 110 | +```javascript |
| 111 | +consumer.messageConsumer.on(solace.MessageConsumerEventName.DOWN_ERROR, function (details) { |
| 112 | + consumer.consuming = false; |
| 113 | + consumer.log('Received "DOWN_ERROR" event - details: ' + details); |
| 114 | + switch(details.subcode) { |
| 115 | + case solace.ErrorSubcode.REPLAY_STARTED: |
| 116 | + : |
| 117 | + break; |
| 118 | + case solace.ErrorSubcode.REPLAY_START_TIME_NOT_AVAILABLE: |
| 119 | + : |
| 120 | + break; |
| 121 | + // Additional events example, may add specific handler code under each: |
| 122 | + case solace.ErrorSubcode.REPLAY_FAILED: |
| 123 | + case solace.ErrorSubcode.REPLAY_CANCELLED: |
| 124 | + case solace.ErrorSubcode.REPLAY_LOG_MODIFIED: |
| 125 | + case solace.ErrorSubcode.REPLAY_MESSAGE_UNAVAILABLE: |
| 126 | + case solace.ErrorSubcode.REPLAY_MESSAGE_REJECTED: |
| 127 | + break; |
| 128 | + default: |
| 129 | + consumer.log('=== An error happened, the message consumer is down ==='); |
| 130 | + } |
| 131 | +``` |
| 132 | +
|
| 133 | +In this example two specific Subcodes are handled: |
| 134 | +
|
| 135 | +* REPLAY_STARTED is handled by creating a new flow with no client-initiated message replay. |
| 136 | +* REPLAY_START_TIME_NOT_AVAILABLE is handled by adjusting `replayStartLocation` to replay all logged messages. |
| 137 | +
|
| 138 | +``` |
| 139 | +case solace.ErrorSubcode.REPLAY_STARTED: |
| 140 | + consumer.log('Router initiating replay, reconnecting flow to receive messages.'); |
| 141 | + consumer.replayStartLocation = null; // Client-initiated replay is not neeeded here |
| 142 | + consumer.createFlow(); |
| 143 | + break; |
| 144 | +case solace.ErrorSubcode.REPLAY_START_TIME_NOT_AVAILABLE: |
| 145 | + consumer.log('Replay log does not cover requested time period, reconnecting flow for full log instead.'); |
| 146 | + consumer.replayStartLocation = solace.SolclientFactory.createReplayStartLocationBeginning(); |
| 147 | + consumer.createFlow(); |
| 148 | + break; |
| 149 | +``` |
| 150 | +
|
| 151 | +## Running the Sample |
| 152 | +
|
| 153 | +Follow the instructions to [check out and run the samples]({{ site.repository }}/blob/master/README.md#checking-out ). |
| 154 | +
|
| 155 | +Before running this sample, be sure that Message Replay is enabled in the Message VPN. Also, create an exclusive queue with the name "tutorial/queue" and messages must have been published to the replay log for this queue: |
| 156 | +
|
| 157 | +* Use the "QueueProducer" sample from `src/basic-samples/QueueProducer` in your cloned repo to create and publish one message to the queue. To start, simply load `QueueConsumer.html` into you browser. |
| 158 | +* Use the "QueueConsumer" sample from `src/basic-samples/QueueConsumer` to drain the queue so that replay is performed on an empty queue and observed by this sample. Both samples are from the [Persistence with Queues]({{ site.baseurl }}/persistence-with-queues) tutorial and they are using "tutorial/queue" by default. Note: after draining, disconnect the "QueueConsumer" from the queue because there can be only one consumer flow active on an exclusive queue at any time and the replay sample will need to connect a new one. |
| 159 | +
|
| 160 | +At this point the replay log has one message. |
| 161 | +
|
| 162 | +You can now run this sample and observe the following, particularly the "messageId"s listed. |
| 163 | +
|
| 164 | +1. First, use "MessageReplay" from `src/features/MessageReplay` for a client initiated replay. All messages are requested and replayed from the replay log. |
| 165 | +2. After replay the application is able to receive live messages. Try it by publishing a new message using the "QueueProducer" sample. Note that this message will also be added to the replay log. |
| 166 | +3. Now start a replay from the message broker. The "MessageReplay" flow event handler monitors for a replay start event. When the message broker initiates a replay, the flow will see a DOWN_ERROR event with cause REPLAY_STARTED. This means an administrator has initiated a replay, and the application must destroy and re-create the flow to receive the replayed messages. |
| 167 | +This will replay all logged messages including the live one published in step 2. |
| 168 | +
|
| 169 | + |
| 170 | +<br> |
| 171 | +
|
| 172 | +## Learn More |
| 173 | +
|
| 174 | +<ul> |
| 175 | +{% for item in page.links %} |
| 176 | +<li>Related Source Code: <a href="{{ site.repository }}{{ item.link }}" target="_blank">{{ item.label }}</a></li> |
| 177 | +{% endfor %} |
| 178 | +<li><a href="https://docs.solace.com/Features/Message-Replay.htm" target="_blank">Solace Feature Documentation</a></li> |
| 179 | +</ul> |
| 180 | +
|
0 commit comments