Tutorial 04 05 Add Dispatcher Classes

Tutorial 4: Add Dispatcher Classes

For each traditional Synergy routine, you must add a dispatcher, which is a class that inherits from the RoutineStub class which is defined in the Traditional Bridge library code, and which has helper methods for serializing and deserializing, exception handling, and logging (see RoutineDispatcher.dbl for more information).

Each method dispatcher class does these things:

• De-serializes any in or inout parameters from a JSON-RPC request message into suitable variables, and prepares variables for any out parameters and function return values.
• Calls the underlying subroutine or function, passing the parameter variables.
• Serializes any inout parameters, out parameters or function return values into a JSON-RPC response message.

This is what the generic code for each dispatcher class looks like:

;;*****************************************************************************
;;
;; Title:       <ROUTINE>Dispatcher.dbl
;;
;; Description: Dispatcher class for calls to <ROUTINE>
;;
;;*****************************************************************************

import Harmony.TraditionalBridge
import Json
import System
import System.Collections

.ifdef DBLV11
import System.Text.Json
.define JSON_ELEMENT @JsonElement
.else
.define JSON_ELEMENT @JsonValue
.endc

namespace TraditionalBridge.Dispatchers

    ;;; <summary>
    ;;; Dispatcher for <ROUTINE>
    ;;; </summary>
    public class <ROUTINE>Dispatcher extends RoutineStub

        ;;; <summary>
        ;;; Dispatch to <ROUTINE>
        ;;; </summary>
        ;;; <param name="name">Name of routine to call.</param>
        ;;; <param name="callFrame">Current JSON-RPC request.</param>
        ;;; <param name="serializer">Outbound data serializer.</param>
        ;;; <param name="dispatcher">Inbound routine dispatcher.</param>
        protected override method DispatchInternal, void
            required in name,       string
            required in callFrame,  JSON_ELEMENT
            required in serializer, @DispatchSerializer
            required in dispatcher, @RoutineDispatcher

            ;;Declare data for any parameters and/or return value
            record
                arguments,          JSON_ELEMENT
            endrecord
        proc
            ;;------------------------------------------------------------
            ;;Process inbound arguments

            arguments = callFrame.GetProperty("params")

            ;TODO: Add code for to de-serialize inbound parameters here

            ;;------------------------------------------------------------
            ;; Call the underlying routine

            ;TODO: Call the underlying routine here

            ;;------------------------------------------------------------
            ;;Process any outbound return value and/or parameters

            ;TODO: Serialize any outbound return value and/or parameters here

        endmethod

    endclass

endnamespace

We recommend organizing all dispatcher classes in a project folder and namespace path.

1. In Solution Explorer, right-click on the TraditionalBridge, select Add > Folder, and name the folder Dispatchers.

Your next task is to create a dispatcher class for each of the three routines being exposed.

2. Right-click on the Dispatchers folder, select Add > Class, and name the new file GetEnvironmentDispatcher.dbl.

3. Replace the current code in the file with the sample scaffolding code shown above.

4. Replace all instances of the token <ROUTINE> with the word GetEnvironment.

   TIP: The Visual Studio shortcut key for "Find and Replace" is Ctrl+H.

The routine being called has no parameters, but it is a function that returns an alpha value. This means we need to do the following:

• Declare an appropriate variable to store the return value from the function.
• Call the function and assign the return value to the variable.
• Serialize the return value into the JSON-RPC response to the caller.

5. In the data division of the DispatchInternal method, add a new string variable named returnValue to the existing record, like this:

   ;;Declare data for any parameters and/or return value
   record
       arguments,          JSON_ELEMENT
       returnValue,        string
   endrecord
   

6. As we have no inbound parameters, remove the TODO comment Add code for to de-serialize inbound parameters here.

7. Locate the TODO comment Call the underlying routine here and replace it with a call to the synergy function:

   returnValue = %GetEnvironment
   

8. Locate the TODO comment Serialize any outbound return value and/or parameters here and replace it with the following code:

   ;;Argument 0 is the return value
   serializer.ArgumentData(0, returnValue,FieldDataType.AlphaField,returnValue.Length,0,true)
   

   This code essentially adds the return value to the JSON-RPC response that will be returned to the caller. The parameters to the ArgumentData method are:

   • The argument number, 0 representing the return value of a function.
   • The actual value to be returned.
   • The data type of the value being returned, using the ENUM FieldDataType. Possible values are:
     • AlphaField
     • DecimalField
     • ImpliedDecimal
     • ImpliedDecimalField
     • IntegerField
     • DataObjectField
     • DataObjectCollectionField
     • EnumField
     • HandleField
     • BinaryHandleField
     • StringField
     • AlphaArrayField
     • DecimalArrayField
     • ImpliedDecimalArrayField
     • IntegerArrayField
     • StringArrayField
   • The length of the data being returned.
   • The number of decimal places (for implied decimal fields).
   • A boolean value indicating whether the value contains any binary data.

---

Next topic: Add Main Dispatcher Class

---