Replaying from the Replay Log in the Solace JCSMP API

This section describes how a client application using the Solace JCSMP API should handle an event broker initiated message replay, and how a client application may initiate a message replay entirely on its own behalf.

If you're not familiar with message replay, take a look at Message Replay for a high-level introduction, and for detailed information on how to configure and use the feature on the event broker have a look at Configuring Message Replay.

There is also a Solace JCSMP API tutorial that shows you how a client can initiate and process a replay.

Event Broker Initiated Replay

If flow reconnect is enabled, when an event broker initiates message replay on an endpoint, whether it's a queue or a durable topic endpoint, with a client bound to it, the first thing the client application will see is an event broker unbind of its guaranteed message flow. The API specific flow event handler will receive a FLOW_RECONNECTING event. If the event subcode is REPLAY_STARTED, then this indicates that the event broker has initiated a replay on the flow.

The API then automatically attempts to reconnect the flow based on this event subcode. If the flow is successfully reconnected, the API generates a FLOW_RECONNECTED event. Once this event is generated, the application can then expect to start receiving replayed messages that it may, or may not, have seen before, depending on why the replay was initiated.

For more information, refer to Flow Reconnect.

If flow reconnect is disabled or not supported in the API version, when an event broker initiates message replay on an endpoint, whether it's a queue or a durable topic endpoint, with a client bound to it, the first thing the client application will see is an event broker unbind of its guaranteed message flow. The API specific flow event handler will receive a FLOW_DOWN event. If the event subCode is REPLAY_STARTED, then this indicates that the event broker has initiated a replay on the flow.

Flow reconnection with the Solace JCSMP API

If the application wishes to reconnect the flow, it must disconnect the encompassing session to connect the session again. The flow will automatically rebind when the session is reconnected. The application can then expect to start receiving replayed messages that it may, or may not, have seen before, depending on why the replay was initiated.

Client Initiated Replay

A client can initiate message replay for a variety of reasons including that it may be able to detect that it needs to replay messages from the replay log, or there may be a start-up condition in the client that requires that messages are replayed from a certain point-in-time.

Message replay may be initiated by a client whenever it binds to a queue or topic endpoint. You may want to consult the Solace Messaging API for JCSMP reference for specific details on how to bind to a queue or topic endpoint. When creating a guaranteed message receiver, either flow or consumer, the application may specify a replay start location, to indicate the starting point of the message replay.

The different types of replay starting points supported are:

  • Replay from the beginning of the replay log.

  • Replay all messages starting from a specified timestamp.

  • Replay all messages after a specified replication group message ID.

To set the replay start location of a flow, use the ConsumerFlowProperties.setReplayStartLocation(...) method. The following code snippet shows a simple example: 

if (dateStr != null) {
    Date date = simpleDateFormat.parse(dateStr);
    loc = JCSMPFactory.onlyInstance().createReplayStartLocationDate(date);
} else {
    loc = JCSMPFactory.onlyInstance().createReplayStartLocationBeginning();
}

consumerProps.setReplayStartLocation(loc);

For more information on how to specify these different replay starting points, see the Solace Messaging API for JCSMP reference.

You should keep in mind that replay attempts from a timestamp earlier than when the replay log was created will fail. When the flow is successfully bound, it will receive all messages from the replay log starting from the specified replay start location.

Restrictions on client initiated replays

  • Not supported on non-exclusive endpoints.
  • Can't be initiated from a non-active flow.
  • Can't be initiated on a browser flow.
  • Can't be done using the JMS API.

If your application wishes to replay messages for a certain topic to a queue

When connecting to a topic-endpoint, the topic to be replayed from the replay log is set in the flow properties when the flow is created. If connecting to a queue, the messages published to the queue, that match subscriptions that exist on the queue prior to creating a flow, will be replayed. If the application wishes to replay messages for a certain topic to a queue, it must be sure to add a subscription to the queue before connecting the flow.

Replay failure

If a message replay fails, the event broker closes the client's flow, and notifies the application with a flow down event. The following code snippet shows a sample implementation of FlowEvent.FLOW_DOWN and the different subcodes that your application can receive:

public void handleEvent(Object source, FlowEventArgs event) {
    System.out.println("Flow " + flowName + " (" + source + ") received flow event: " + event);

    if (event.getEvent() == FlowEvent.FLOW_DOWN) {
        if (event.getException() instanceof JCSMPErrorResponseException) {
            JCSMPErrorResponseException ex = (JCSMPErrorResponseException) event.getException();
            
            switch (ex.getSubcodeEx()) {
                case JCSMPErrorResponseSubcodeEx.REPLAY_STARTED:
                case JCSMPErrorResponseSubcodeEx.REPLAY_FAILED:
                case JCSMPErrorResponseSubcodeEx.REPLAY_CANCELLED:
                case JCSMPErrorResponseSubcodeEx.REPLAY_LOG_MODIFIED:
                case JCSMPErrorResponseSubcodeEx.REPLAY_START_TIME_NOT_AVAILABLE:
                case JCSMPErrorResponseSubcodeEx.REPLAY_MESSAGE_UNAVAILABLE:
                case JCSMPErrorResponseSubcodeEx.REPLAYED_MESSAGE_REJECTED:
                case JCSMPErrorResponseSubcodeEx.REPLAY_START_MESSAGE_UNAVAILABLE:
                    break;
                default:
                    break;
            }
        }
    }
}

For more information on the different subcodes that could be received, see the Solace Messaging API for JCSMP reference.