Invoking a service asynchronously from a Rich UI application

In Rich UI, the call statement is used to invoke a service asynchronously:
call serviceName.operationName(argumentList)
   returning to myCallbackFunction onException myExceptionHandler
   {timeout = milliseconds};
serviceName
Name of a variable that is based on an Interface part
operationName
Name of the Interface part function prototype
argumentList
List of arguments, each of which is separated from the next by a comma

A change made to a parameter value in the service does not affect the value of the argument variable that is provided in the call statement.

For details about the restrictions on parameters that are sent to a third-party REST service, see "Specifying parameters for service access in Rich UI."

myCallbackFunction
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
Optional. Name of a exception handler or 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.
If you do not have your own exception handler, you can specify the following delegate: serviceLib.serviceExceptionHandler. Specifying that delegate has the following implications:
  • By default, specifying that delegate automatically invokes a system function that writes the content of the exception message field to the standard output. In the product, the standard output is the console view. In an external browser, the standard output is the bottom of the Web page.
  • Alternatively, you can make customized exception handling consistent throughout a set of applications. Assign a different exception handler to the delegate; for example, by writing a setup function in your own library, such as in myLibrary, and by including the following statement in that function:
    serviceLib.serviceExceptionHandler = myLibrary.myExceptionHandler;

    Invoke the setup function in Rich UI handler on-construction functions. For every service that is invoked by a call statement (if the statement includes serviceLib.serviceExceptionHandler), the EGL runtime code responds to a runtime exception by running the customized exception handler; in this case, by running myLibrary.myExceptionHandler.

milliseconds
The maximum valid number of milliseconds that elapse between when the EGL Rich UI Proxy (on the Web server) invokes a service and when the proxy receives a response. If more time elapses, the EGL runtime code throws a ServiceInvocationException.
To set a timeout:
  • Take into account a variety of factors, such as local network traffic, internet traffic, and server response time. Those factors mean that two invocations of the same service are likely to take a different amount of time under different conditions.
  • Consider the nature of your application. If your code is waiting for a credit approval, you might set a high timeout value to avoid charging the user twice. If your code is making a bid in an online auction bid, you might set a low timeout value so that the user can make an additional bid quickly.
  • Use timeout values that vary from one another by one or more seconds.

You can set a default value for milliseconds in the defaultServiceTimeout build descriptor option. The defaultServiceTimeout build descriptor option has no default value set, meaning that if you do not specify a value for either defaultServiceTimeout or for milliseconds, the service call will not time out. For more information, see “defaultServiceTimeout.”

Keystroke assistance for the call statement

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. In each case, a list of functions is displayed and you can select one.
  • If you type the call statement with the ending semicolon and include reference to a callback or onException function that does not exist, you can request the Workbench to create the missing logic:
    • Press Ctrl+1
    • Alternatively, right click after the semicolon and select Create Callback Functions

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 Web SOAP service or from an EGL REST service, the relationship of the function parameters and the service-invocation parameters is best described by 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 an interface declaration and call statement used to invoke the service:
    myInterface EmployeeService;
    
    call myInterface.GetEmployeeDetail("A123", 25.8, "Full-time")
         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, and 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 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, last parameter to accept the return value
  • 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 (less likely) a RuntimeException.


Feedback