Contents


Build a DB2 for z/OS mobile application using DB2 Adapter for z/OS Connect, Part 2

Consume a DB2 Adapter service

Comments

Content series:

This content is part # of # in the series: Build a DB2 for z/OS mobile application using DB2 Adapter for z/OS Connect, Part 2

Stay tuned for additional content in this series.

This content is part of the series:Build a DB2 for z/OS mobile application using DB2 Adapter for z/OS Connect, Part 2

Stay tuned for additional content in this series.

To create effective, enterprise-ready mobile applications, you need to make the back-end data easier to consume. APIs in IBM DB2 Adapter for z/OS expose DB2 for z/OS functionality to applications. In Part 2 of the series, learn how to build a mobile application using IBM MobileFirst Developer Edition by consuming a DB2 Adapter service.

In the following sections, we will discuss how to:

  • Do client-side development
  • Create and test an HTTP adapter
  • Use the result from server-side
  • Build, deploy, and test using the MobileFirst Console
  • Run Android emulator (optional)

Software requirements and prerequisites

To follow along with the examples in this article, you need to meet the following software requirements:

  • A DB2 adapter service called GetXMLString. To create the service, follow the instructions in Part 1.
  • IBM MobileFirst Developer Edition V7.0 and optional Android SDK. See the "Installation and Configuration" section of the Build a DB2 for z/OS mobile application using IBM MobileFirst
  • A SSL certificate for the DB2 Adapter service with the correct common name (CN) (not localhost)

IBM MobileFirst Platform overview

IBM MobileFirst Platform provides an integrated development and testing environment for mobile applications. The development environment combines multiple sets of tools, frameworks, and code bases into one single development environment, giving users one code base to develop and maintain. The MobileFirst Platform provides an Eclipse-based studio and command-line interface (CLI) for:

  • Native applications development for iOS, Android, Windows Phone 8, and Windows 8
  • Hybrid development, which combines native apps and web apps development
  • Server-side development (adapters), including SQL adapter, HTTP adapters, Java adapters, and the like
  • Testing and debugging with a mobile console browser

Architecture

The scenario in this article retrieves a string from string ID from the SYSIBM.SYSXMLSTRINGS table using regular SQL statements. SYSIBM.SYSXMLSTRINGS is a catalog table that contains mapping between the string and string ID that are used inside XML storage.

Figure 1 is a simplified architecture of the mobile solution we are going to implement. The mobile application accesses the HTTP Adapter in MobileFirst, which calls a DB2 Adapter service via a RESTful URL and JSON payload (exposed by DB2 Adapter for z/OS Connect) to do a SELECT in DB2 for z/OS.

Figure 1. Mobile application architecture
Mobile application architecture
Mobile application architecture

Client-side development

Launch Eclipse with MobileFirst Developer Studio installed.

To create a new MobileFirst Project, follow these instructions:

  1. Click File>New>MobileFirst Project
  2. Enter Hello3 as the Project name.
  3. Select Hybrid Application.
  4. Click Next.
  5. Enter Hello3 as the Application name.
  6. Click Finish .

Figure 2 illustrates the files layout for a newly created project. The front-end display is defined in index.html under Hello3>apps>Hello3>common.

Figure 2. Files layout for a newly created project
Files Layout for a newly created project
Files Layout for a newly created project

Listing 1 shows how to define a text field inside index.html for the user to enter a string ID value.

Listing 1. Embed an image file
<div data-role="content" style="padding: 15px">
  <!--application UI goes here-->
  <img src="images/db2v11Image5.png"/>
  <br/>

Find DB2 for z/OS XML String from String ID using the REST API provided by DB2 Adapter for z/OS.

Listing 2. Define a text field to enter a string ID value and call loadFeeds in main,js
<label for="text">String id:</label>
<input type="text" name="text" id="stringid">
<input type="button" value="Submit" src="js/main.js"  
     onclick="loadFeeds(document.getElementById('stringid').value)">
<div id="wrapper">
<ul id="itemsList"></ul>
</div>

From Listing 2, when you click Submit, it calls the loadFeeds function in main.js, which is found in the Hello3>apps>Hello3>common>js folder.

Listing 3. Call the loadFeeds function in main.js
function loadFeeds(stringid){
      WL.Logger.debug("Inside loadFeeds"); 
      busyIndicator.show();
      stringidInput = stringid;
   
      // Use HTTP Adapter
      WL.Logger.debug("Inside loadFeeds(): using HTTP Adapter"); 
      var invocationData = {
                  adapter : 'Hello3HTTPAdapter',
                  procedure : 'getXMLString',
                  parameters : [stringid]
      };
   
      WL.Client.invokeProcedure(invocationData,{
            onSuccess : loadFeedsSuccess,
            onFailure : loadFeedsFailure
      }); 
}

As Listing 3 demonstrates, inside loadFeeds a procedure called getXMLString inside Hello3HTTPAdapter is called.

Create an HTTP adapter

To create an HTTP adapter, follow these steps. Inside Eclipse:

  1. Click File > New > MobileFirst Adapter.
  2. Select Hello3 as the project name.
  3. Select HTTP Adapter.
  4. Enter Hello3HTTPAdapter as the adapter name.
  5. Click Finish .

After an HTTP adapter is created, there will be two files under the newly created adapter: Hello3HTTPAdapter.xml and Hello3HTTPAdapter-impl.js. Figure 3 shows this configuration.

Figure 3. File layout after creating a HTTP Adapter
How data might move, transparently between storage tiers
How data might move, transparently between storage tiers

Edit Hello3HTTPAdapter.xml to

  1. Add the correct protocol, domain, or port of DB2 Adapter service under <connectionPolicy>
  2. Add a procedure call getXMLString

Listing 4 shows how to do this:

Listing 4. Edit the Hello3HTTPAdapter.xml
<connectionPolicy xsi:type="http:HTTPConnectionPolicyType">
 <protocol>https</protocol><domain>dtec207.vmec.svl.ibm.com</domain><port>9443</port>  ….
</connectionPolicy>

<!-- Below is added by Jane -->
<procedure name="getXMLString"/>

Edit Hello3HTTPAdapter-impl.js to implement getXMLString, as in Listing 5.

Listing 5. Implement getXMLString
function getXMLString(stringid) {
        var path = "/zosConnect/services/GetXMLString?action=invoke";
        var stringidInt = parseInt(stringid);
        var input = {
                  method : 'post',
                  returnedContentType : 'JSON',
                  path : path,
                  headers: {
            Authorization: "Basic xxxxxxxxxxxxxxxxxxxx"
                    }, 
                  body : {
                    contentType: 'application/json',
		         	content:  {"1": stringidInt}		      	}		      
       }; 
    
  return WL.Server.invokeHttp(input);
}

Please note:

  1. xxxxxxxxxxxxxxxxxxxx is base64encoded of the authorized user name and password of the DB2 Adapter service. For debugging purposes, you can copy the information from the developer view of the browser when you test or query your DB2 Adapter service.
  2. The format of body.content in the input should be same as the input parameter of your DB2 Adapter service.

Add the SSL certificate to the MobileFirst Server

Before you can test your HTTP Adapter, you need to add the SSL certificate of the DB2 Adapter service into the server of the project (Hello3).

Since the HTTP Adapter is unlikely to coexist in the same system as your DB2 Adapter service. We need a certificate for the DB2 Adapter service with the correct CN (not localhost).

If you have not done so, follow the instructions in Generating your own SSL Certificate section in Part 1 to generate a certificate with the correct CN. Once you have an SSL certificate with the correct CN, follow these instructions:

  1. Export the certificate.

    Assume your certificate is in /tmp/usr/servers/test/resources/security/key.jks
    cd /tmp/usr/servers/test/resources/security
    format of the keytool is: keytool -export -alias backend -keystore key.jks -rfc -file backend.crt

    I use the following command to export the certificate to a file called dtec207.crt:
    keytool -export -alias default -keystore key.jks -rfc -file dtec207.crt

    You will be prompted to enter the keystore password, which is the password in the sescurityUtility (when you generate your own SSL certificate).

  2. FTP the certificate file (dtec207.crt) to the server/conf directory of the MobileFirst project. In my case, this is C:\Eclipse\workspace\Hello3\server\conf.
  3. Import the exported certificate into your MobileFirst Server mfp-default.keystore file in the server/conf directory of the MobileFirst project. The format should be: keytool -import -alias backend -file backend.crt -storetype JKS -keystore mfp-default.keystore

    In my case,

    Listing 6. Import the exported certificate into your MobileFirst Server
    C:\Eclipse\workspace\Hello3\server\conf>"C:\Program Files\Java\jre7\bin\keytool"
    -import -alias dtec207 -file dtec207.crt -storetype JKS -keystore mfp-default.keystore

    Note: We change the alias name when we import.

    You may be prompted for the mfp-default.keystore password, which you get from the sever\config\worklight.properties <ssl.keystore.password> field, which is unique to each project.

    Listing 7. Enter your mfp-default.keystore password
    Enter keystore password:        
    ….
          
    Trust this certificate? [no]: yes
    Certificate was added to keystore
  4. Check whether the certificate is correctly imported in the keystore.

    The format should be: keytool -list -keystore mfp-default.keystore

    The command I use is as follows:

    Listing 8. Check if the certificate is imported correctly
    "C:\Program Files\Java\jre7\bin\keytool" -list -keystore
    mfp-default.keystore

    The output is a long list of entries, but you should able to see the one you just imported, as Listing 9 shows:

    Listing 9. Output
    dtec207, Dec 19, 2015, trustedCertEntry,
    Certificate fingerprint (SHA1):
    1F:61:D6:15:94:96:83:1D:CB:24:81:7A:9C:53:20:27:8A:FE:03:C7

For more information, see Configuring SSL between MobileFirst adapters and back-end servers by using self-signed certificates.

Deploy and test an HTTP adapter

To deploy and test an HTTP adapter, follow theses steps:

  1. Right-click the Hello3HTTPAdapter > Run As > Deploy MobileFirst Adapter.
  2. Right-click Hello3THTTPAdapter > Run As > Call MobileFirst Adapter.
  3. In the Call MobileFirst Procedure GUI, enter the value of the parameter, then click Run.

The output should be similar to Listing 10.

Listing 10. Output of testing an HTTP adapter
{
    "ResultSet Output": [
       {
   
          "STRING": "space                                            "
       }
    ],
    "StatusCode": 200,
    "StatusDescription": "Execution Successful",
    "isSuccessful": true,
    "responseHeaders": {
….
    },
    "responseTime": 824,
    "statusCode": 200,
    "statusReason": "OK",
    "totalTime": 829
}

Use the result from the server side

As shown in the Client-side development section, when the invokeProcedure() runs correctly, loadFeedsSuccess is called.

To use the result after calling an adapter or external resource, you need to edit main.js and implement loadFeedsSuccess. Listing 11 shows how to do this.

Listing 11. Edit main.js to implment loadFeedsSuccess
function loadFeedsSuccess(result){
      WL.Logger.debug("Feed retrieve success");
      busyIndicator.hide();
      
      WL.Logger.debug("status= " + status); 
      WL.Logger.debug("result.responseJSON.StatusDescription= "
        + result.responseJSON.StatusDescription);
      WL.Logger.debug("result.responseJSON[ResultSet Output]= "
        + result.responseJSON["ResultSet Output"]);
        
      if (result.responseJSON["ResultSet Output"] != null)
            displayFeeds(result);
      elseif (result.responseJSON["ResultSet Output"] == null)
            loadFeedsNotFound();
      else
            loadFeedsFailure();
}

Note the result from an HTTP adapter is a result.responseJSON object. If the result.responseJSON["ResultSet Output"] is not null, we call displayFeeds() with the result object as parameter.

Inside displayFeeds(), we call WL.SimpleDialog.show() to display the first value, as Listing 12 demonstrates.

Listing 12. Call WL.SimpleDialog.show() to display the first value
function displayFeeds(result){
      var ul = $('#itemsList');
      WL.Logger.debug("Inside displayFeeds, result= "
        + JSON.stringify(result));	
      var ResultSetOutput = result.responseJSON["ResultSet Output"]; 
      var description = ResultSetOutput[0].STRING; 
      WL.SimpleDialog.show(description , "String id for "
        + stringidInput + " is found.",
                  [{
                        text : 'Reload',
                        handler : WL.Client.reloadApp
                   }
                  ]
            );
      WL.Logger.debug("Inside Exiting displayFeeds successsfully…");
}

Create new environments

To create a new mobile environment, follow these steps:

  1. Right-click the app, in this case Hello3\apps\Hello3. Then click >New>Other, then select MobileFirst Environment . Click Next .
  2. Check iPhone, iPad, Android phones and tablets. Then click Finish.

Build and deploy

Right-click your app, which in this case is Hello3\apps\Hello3. Then click >Run As>Build All Environments.

After a successful build, you should see folders for android, ipad, and iphone, as in Figure 4. A project called Hello3Hello3Android is created as well. Note: the first Hello3 is the original project name and the second Hello3 is the original application name.

Figure 4. Folders after building all the environments
Folders after building all the environments
Folders after building all the environments

Test by using the MobileFirst Console

1. Right-click the project, in this case Hello3. Then click > Open MobileFirst Console
A browser similar to Figure 5 will appear.

Figure 5. MobileFirst Console
How data might move, transparently between storage tiers
How data might move, transparently between storage tiers

2. Click Applications.

3. Click the Android button for Hello3, as in Figure 6.

Figure 6. Console for Hello3 application
Console for Hello3 application
Console for Hello3 application

4. To view the mobile browser simulator, click Preview.

Figure 7. Figure7
How data might move, transparently between storage tiers
How data might move, transparently between storage tiers

A mobile browser simulator like Figure 8 will appear, and you can test the Hello3 application you created.

Figure 8. Android simulator
How data might move, transparently between storage tiers
How data might move, transparently between storage tiers

Run Android emulator (Optional)

If the Android SKD, ADT Eclipse plug-in has been installed and an Android virtual device is defined, you can run the Android emulator as well.

Right-click Hello3Hello3Android>Run As>Android Application.

Figure 9 shows the screen that you will see on the Android emulator. Depending on the CPU of your machine, the response time may vary.

Figure 9. Android emulator
Android emulator
Android emulator

Summary

This article discussed how to build a DB2 for z/OS mobile application using the DB2 functionality exposed by DB2 Adapter for z/OS Connect. In Part 1, we illustrated how to create, deploy, query, start, and test a DB2 Adapter service. In Part 2, we show how to build a mobile application to invoke this REST API using IBM MobileFirst.

Acknowledgments

Thanks to Tom Toomire and Xavier Yuen for their comments and assistance with this paper.


Downloadable resources


Related topics


Comments

Sign in or register to add and subscribe to comments.

static.content.url=http://www.ibm.com/developerworks/js/artrating/
SITE_ID=1
Zone=Information Management
ArticleID=1028169
ArticleTitle=Build a DB2 for z/OS mobile application using DB2 Adapter for z/OS Connect, Part 2: Consume a DB2 Adapter service
publish-date=03052016