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
For more examples, see
the following topics: