API Tutorial Lesson 12 - Adding Methods to a Solution
Once a solution has been defined, the next step is adding functionality to it that is called 'methods'. This operation is depicted in this lesson's sample code: its first step consists in the usage of the 'MethodAddAllow', 'MethodAddParameterAddAllow' and 'MethodAddCommit' APIs to define the method in detail: each method has the same attributes as any of the APIs defined by our transaction manager, like a name, a return type (with minimum and maximum length), cost to be charged to the user, maximum running duration, and so on. Adding parameters must be done one by one (in the example, we have three parameters), informing the parameter's name, numeric ID, type, and minimum and maximum length. If the 'MethodAddCommit' API call succeeds, then the method has been created. Each solution can include as many methods as necessary.
The example operation shown in the Figure includes adding a callback (provided by a back-end server) to the example method shown. Note that it is not compulsory that each method has associated callbacks (it is allowed, however, that one method has as many callbacks associated to it as necessary). The example shows how the calls to the 'CallbackAddAllow', 'CallbackParameterAddAllow' and 'CallbackAddCommit' APIs are used to define one callback for the method.
The 'CallbackAddAllow' API is used to define the callback's name and ID, its return type, and, most important, the communication protocol to be used to access the callback (which implies in choosing the correct back-end connector when this callback gets called during run-time).
The 'CallbackParameterAddAllow' API is called only once per callback definition, and it just defines the subset of the method's parameters that this callback requires (they are a subset of the parameters of the method the callback is associated to): in our example, the callback receives parameters with IDs 1 and 2, but the 'Add2Positives' method's third parameter (named 'Z' in the example) is not passed into this callback (but could be passed into other callbacks associated to this same method).
The 'CallbackAddCommit' API, as any other '…Commit' API on our transaction manager, when successfully ending the transaction, returns the only parameter it received: the operation handle returned by its corresponding '…Allow' API call.
US Patent Requested