Calling a Data Service

Mapping rules typically define how to contact a data service and process the input and output messages. To simplify this common use case, the XML Mapping Utility generates the function code that invokes the service, which you add to your project in an included JavaScript file.

Generating Function Code

To generate the function code that invokes the service and add it to your application, follow these steps:

1. Double-click the rules file in the Project Files palette to open it in the XML Mapping Utility.
2. Click the Generate button and choose the operation from the drop-down list. This copies the JavaScript code that implements the function to the clipboard. Click OK in the Code Generator prompt.
3. Minimize the XML Mapping Utility and open logic.js or any included JavaScript file in your project.
4. Position the cursor in the JavaScript file and press Ctrl+v to paste the function code into the JavaScript file. The function code has the following format:

   jsx3.lang.Package.definePackage(
      //the full name of the package to create
      "eg.service",
      //name the argument of this function
      function(service) {
   
      //call this method to begin the service call
      //(eg.service.callGetHistoricalQuotes();\)
      service.callOperation_Name = function() {
         var objService = Server_Name.loadResource("Project_Resource_File_Id");
         objService.setOperation("Operation_Name");
   
   
         //subscribe and call
         objService.subscribe(jsx3.net.Service.ON_SUCCESS,
            service.onOperation_NameSuccess);
         objService.subscribe(jsx3.net.Service.ON_ERROR,
            service.onOperation_NameError);
         objService.subscribe(jsx3.net.Service.ON_INVALID,
            service.onOperation_NameInvalid);
         objService.doCall();
      };
   
      service.onOperation_NameSuccess = function(objEvent) {
         //var responseXML = objEvent.target.getInboundDocument();
         objEvent.target.getServer().alert("Success","The service call was
            successful.");
      };
   
      service.onOperation_NameError = function(objEvent) {
         var myStatus = objEvent.target.getRequest().getStatus();
         objEvent.target.getServer().alert("Error","The service call failed.The HTTP
            Status code is: " + myStatus);
      };
   
      service.onOperation_NameInvalid = function(objEvent) {
         objEvent.target.getServer().alert("Invalid","The following message node just
            failed validation:\n\n" + objEvent.message);
      };
   
     }
   );

   where Operation_Name is the name of the SOAP operation to invoke and Project_Resource_File_Id is the ID of the rules file. Function names and alert text can be customized.
   The function, service.call _Operation_Name_Success, is called when the data service responds. Communication between the application and the data service is asynchronous, so this function can be used for notification of a response.

5. Save the JavaScript file.

Generated Code Package Structure

The code generated by the XML Mapping Utility demonstrates how to use packages to encapsulate the callback methods. By using definePackage (as well as defineClass), you can author web pages with the same architectural constructs used in developing the application back-end.

In addition to providing a mechanism for good coding practices, definePackage is also useful because it allows the code to be introspected. This means that when an error occurs in code, a stack trace can be run with relevant information about the call. Without this, only rudimentary error messages provided by the browser are available.

For example, if you were to use definePackage and an error occurred somewhere in your code, the System Log palette would display this information:

10:31:36.431 global (ERROR) - Uncaught Exception: 'xp' is undefined
(line: 47, file: file://C:\tibco\gi\GI_Builder.hta)
    at eg.service#doCallYetAgain()
    at eg.service#doCallAgain()
    at eg.service#call()

From the above information, you know that an error occurred on line 47, within the function eg.service#doCallYetAgain(). You also know the order of the call stack and whether it involved static or instance methods. Had you not used definePackage, the output to the error log would look something like this:

10:36:13.443 global (ERROR) - Uncaught Exception: 'xp' is undefined
  (line: 47, file: file://C:\tibco\gi\GI_Builder.hta)
    at anonymous()
    at anonymous()
    at anonymous()

For more information on how to use General Interface package APIs, see jsx3.lang.Package in General Interface API Reference (Help > API Documentation).

Invoking Function Code

To invoke this function code with a component event, enter the fully qualified name of the function into the appropriate field of the Events Editor palette:

1. Select the component in the work area or the Component Hierarchy palette.
   For example, in the WSDL Mapping 2 sample, select the Query button component.
2. Choose Palettes > Events Editor to open the Events Editor palette.
3. Enter the JavaScript statement that calls the function in the Execute field in the Events Editor palette. Be sure to enter the fully qualified name of the function:

   eg.service.callOperation_Name();

   For example, in the WSDL Mapping 2 sample, enter:

   eg.wsdl2.callGetHistoricalQuotes();