VersaCloud's Callbacks

The callback concept in our cloud-based time-limited transaction manager represents the request sent by our single entry point engine to some back-end server to run a specific piece of code on behalf of a call of the 'MethodInvokeAllow' API received from some end-user software.

The piece of code to be called inside the back-end server could be any stored procedure, web service or any other remotely callable functionality. This remotely callable functionality could already exist, or be created specifically to be used with our cloud-based time-limited transaction manager – according to the solution developers' needs and the software architecture of the existing server and code.

In any case, the functionality to be called has to be registered by solution developers into our finite state automaton by calling the 'CallbackAddAllow' and 'CallbackAddCommit' APIs: each callback has a name (names' usage can be verified by means of calls of the 'CallbackValid' API) and is associated to a specific solution's method. As part of the 'CallbackAdd…' transaction, additional calls to the 'CallbackParameterAddAllow' API can be made to define which of the method's parameters will be passed on to the callback.

At the moment of this association, one of the protocols for which back-end connectors are available must be chosen (and will be used to invoke the callback whenever necessary), the type of the return value must be defined, and all needed data to connect to the back-end (which depends upon the protocol). The callback also receives a name and a numeric ID, to refer to it afterwards in various situations (to be described shortly).

Callbacks validity can be limited in time by calls to the 'CallbackSinceSetAllow', 'CallbackSinceSetCommit', 'CallbackUntilSetAllow' and 'CallbackUntilSetCommit' APIs. The current values for initial and final Valid times can be retrieved through calls to the 'CallbackSinceGet' and 'CallbackUntilGet' APIs.

Note that this way of associating callbacks to existing solutions' methods allows for each method to have any number of callbacks associated. In the most simple of end-user software, where no back-end servers are involved, solution methods are used just to charge users for calling them (and no callbacks are necessary). However, this same model fits the most complex cloud-based transactions, where the end-user demand represented by a single method call requires interaction with a significant variety of different back-end servers.

Hence, when having various callbacks involved in one method call, it is necessary to define the order of calling these associated callbacks. The transaction corresponding to a method call is started with a call to the 'MethodInvokeAllow' API, followed by a call to the 'MethodInvokeParameterAdd' API (to define the method's parameters values for this call) and ends with the call to the 'MethodInvokeCommit' API, as depicted on Fig. 3). Once the transaction is running, specific callbacks can be invoked, in any order desired by the solution developer, by calling the 'CallbackInvoke' API.

When the transaction is confirmed by calling the 'MethodInvokeCommit' API, our transaction manager automatically invokes all the method's callbacks not yet invoked during the current transaction, following the order of the callbacks' numeric IDs. This means that in simpler cases (like when only one callback exists, or when they can always be run in a pre-defined order) using 'CallbackInvoke' can be completely avoided.

The last aspect related to callbacks was conceived to handle the situation when one of these callbacks does not succeed, which it can signal to our transaction manager by returning an error code instead of a value of the type defined for its return values. When our single entry point engine is informed in this way that the transaction cannot succeed, it ends the specific transaction automatically.

However, in case previous callbacks' execution have already succeeded for the specific transaction now being ended, the back-end servers handling these successful calls might need to be informed of the transaction's failure (so that they can undo changes they made to their internal state).

To handle this special situation, our definition of callbacks (using the 'CallbackAddAllow' API) has one optional parameter that can be used to mark callbacks as being callbacks to be called only after an error occurred while processing a transaction. We refer to these special callbacks as 'rollback callbacks': they share their name and ID with a previously defined 'normal' callback, and are called automatically when ending transactions in error only if the 'normal' callback was run successfully before the error was detected. Hence, there is no way to manually invoke rollback callbacks.

Three informative APIs complete the callback management needs: the 'CallbackInfoGet' API call is available to retrieve information about a specific callback (allowing to retrieve all of the 'CallbackAddAllow' API's parameters), the number of active calls to a specific method can be retrieved through the 'MethodActiveTransactionsCount' API call, while the 'CallbackInvokeGet' API call can be used to retrieve the return values of callbacks executed as part of a specific method invocation.

US Patent Requested