Automatically creating Sequences
When the application does not use the Sandesha Client API, the Sandesha runtime will automatically manage the WSRM Sequences. A Sequence will be created for each unique To address and Sandesha Sequence Key. The Sandesha Sequence Key allows applications to isolate themselves from other users of the Sandesha engine.
The first time that a message is sent to a (To address, sequence key) tuple, the Sandesha engine will automatically create a Sequence. If that Sequence is Closed then the Sandesha engine will stop accepting messages for that Sequence, and will return exceptions back to the client. Once the Sequence is Terminated then the Sandesha engine will create a new Sequence as and when needed.
When automatically creating WSRM Sequences, there are two behaviours, controlled by Sandesha2SequenceCreationOption:
- Fail fast (the default). This option causes the Create Sequence to be performed before the send returns control to the application. If the Create Sequence processing fails then an exception will be returned to the application. Using this model, the application can be sure that the remote endpoint is capable of performing RM, and that there is likely to be successful transmission of the application message in the near future. This option cannot be used when sending the message under a transaction.
- Deferred creation. This option causes the the application message to be stored within the Sandesha engine, and control returns to the application. The Sandesha engine will handle Sequence creation using its own threads and resources. If the Create Sequence processing fails then the failure will be stored, and the application may use the Sandesha Client API to check on the state of the Sequence. This option is appropriate when using a storage manager that is capable of persisting the message, and retrying sequence creation over a period of time. This handles transient communication failures, and supports sending the application message under a transaction.
Note, if you are using the SandeshaClient API to create a sequence, then the behaviour is always Fail Fast, and an exception will be thrown if a sequence already exists for this tuple (to, key).
It is possible for an application to send messages from more than one thread at once. If Fail fast is enabled, then one of the threads will attempt sequence creation as described above. The other thread will be blocked until the first thread has finished, and if sequence creation failed then the second thread will retry sequence creation. If deferred creation is enabled then both messages will be queued within the Sandesha engine.
It is not recommended to use different behaviours across threads using the same endpoint. However, we have documented all possible outcomes to be clear about Sandesha's behaviour. Consider the following table:
First thread |
Second thread |
Outcome |
|---|---|---|
Fail Fast |
Fail fast |
First thread will attempt sequence creation. If this fails then an exception will be returned to the application. The second thread will not re-attempt creation, if needed. |
Fail Fast |
Deferred |
First thread will attempt sequence creation. If this fails then an exception will be returned to the application. The second thread will schedule deferred creation, if needed. |
Deferred |
Fail fast |
First thread will schedule deferred creation. Second thread will add the message into the Sequence, it will not attempt creation (even if the deferred creation has not yet succeeded) |
Deferred |
Deferred |
First thread will schedule deferred creation. Second thread will add the message into the Sequence, it will not attempt creation (even if the deferred creation has not yet succeeded) |