Invoking a service asynchronously from a Rich UI application

In Rich UI, you invoke a service asynchronously by declaring a binding variable and then accessing a call statement version that is described in the current topic.

For background detail, see Resource bindings.

Here is the asynchronous version of the call statement:

call 	InterfaceTypeName.operationName(argumentList)
   using bindingVariable
   returning to myCallbackFunction
   onException myExceptionHandler;
InterfaceTypeName
The name of an Interface type or, for dedicated services, of a Service or Interface type.
operationName
The name of the operation; either the name of a function in a Service type or the name of a function prototype in an Interface type.
argumentList
A list of arguments, one separated from the next by a comma

For restrictions on arguments, see “Restrictions in the prototypes used for service access.”

bindingVariable
A variable that holds the access detail:
  • When you access a REST or REST-RPC service, the variable type is HTTPRest.
    In this case, the primary way to declare the variable is to include a Resource annotation that refers to an EGL deployment descriptor entry:
    myBindingVar HttpRest {@Resource {uri = "binding:myEntry"}};
  • When you access a dedicated service, the variable type is HTTPProxy, and no deployment descriptor is involved:
    myBindingVar HttpProxy;
    Here is code that declares a binding-variable value in the call statement itself:
    call MyInterface.myOperation() using new HttpProxy
                                   returning to myCallBackFunction
                                   onException myExceptionHandler;
myCallbackFunction
The name of a callback function or delegate that is available to the call statement. In most cases, the function or delegate is in the same Rich UI handler or in a library. The callback function is described later in this topic.
myExceptionHandler
The name of an exception handler or a delegate that is available to the call statement. In most cases, the exception handler or delegate is in the same Rich UI handler or in a library. The exception handler is described later in this topic.

Keystroke assistance for the call statement

In the workbench, the following kinds of keystroke assistance are available:
  • After you type the returning to or onException keyword in the call statement, you can request content assist by pressing Ctrl+Space. A list of functions is displayed, and you can select one.
  • If you type the call statement with the ending semicolon and include a reference to a callback or an onException function that does not exist, you can request that the workbench create the missing logic. The keystroke is Ctrl+1.

Callback function

The callback function receives the values, if any, that are in the response sent by the service. The callback itself has no return value.

If the callback function is invoked from a third-party REST service, the function can have zero or one parameter. If a parameter is specified, its type must match the type of the return value that is specified in the Interface part, and the parameter modifier is IN.

If the callback function is invoked from a SOAP service or from an EGL REST-RPC service, the relationship of the function parameters and the service-invocation parameters is best described by an example:
  • Consider the following function prototype in an Interface part:
    Interface EmployeeService {}
       Function GetEmployeeDetail(employeeCode STRING IN, 
                                  employeeSalary FLOAT OUT, 
                                  employeeStatus STRING INOUT) 
                returns(myEmployeeRecordPart);
    end
    
  • This example shows a binding-variable declaration and call statement used to invoke the service:
    myBindingVar HttpRest{@Resource{uri="binding:myEntry"}};
    call MyInterface.GetEmployeeDetail("A123", 25.8, "Full-time")
       using myBindingVar
       returning to myCallback 
       onException myExceptionHandler;
    
  • Here is the outline of a callback function:
    Function myCallBack(salary FLOAT IN, 
                        status STRING IN, 
                        myRecord myEmployeeRecordPart IN)
        // statements here
    end

    The function includes one parameter for each service-operation parameter that is OUT or INOUT. The order of those parameters in the callback function is the same as the order in the service operation. The service-operation return value is represented as the last parameter in the callback function.

In general, the rules for designing the callback function for a web SOAP service or an EGL REST-RPC service are as follows:
  • The function has a series of parameters that are in the same order as the OUT and INOUT parameters in the service invocation.
  • If the service invocation has a return value, the callback function includes an additional parameter to accept the return value.
  • The callback function can include an optional final parameter that provides access to the HTTP request and response data. The parameter is of type IHTTP, as described in the language reference topic named “eglx.http package.”
  • Each parameter in the function has the IN modifier.

onException function

The onException function has the following characteristics:
  • No return value
  • The function accepts an Exception record of type AnyException, and you can test that record to determine the specific type received

Here is the outline of an onException function:

Function myExceptionHandler(exp AnyException)
   case 
      when (exp isa ServiceBindingException)
         ;
      when (exp isa ServiceInvocationException)
         ;
      otherwise
         ; 
   end
end
Errors might occur in the following places:
  • In a service binding; that is, in how the service access is specified in your code. This error might involve a problem in the deployment descriptor.
  • In the communication of the Rich UI application with the EGL Rich UI Proxy
  • In the EGL Rich UI Proxy
  • In the communication of the EGL Rich UI Proxy with the service
  • In the service

A problem in a service binding results in a ServiceBindingException. Other problems result in a ServiceInvocationException or a RuntimeException, which is less likely.

For more examples