Subscribe

Share

Mobile

Too Much of a Good Thing?

Use Oracle Mobile Cloud Service custom APIs in Oracle JET.

By Chris Muir

January/February 2017

If you’ve followed recent Oracle Magazine mobile development articles, you’ve seen articles on mobile client technologies such as Oracle Javascript Extension Toolkit (Oracle JET), which creates web and hybrid mobile apps, and articles on mobile server technologies, particularly Oracle Mobile Cloud Service, which provides web services for mobile and web apps to consume. I’m sure it’s no surprise when, as an Oracle employee, I say that each and every developer tool Oracle offers is designed to simplify the tasks of developers who need to deliver mobile products to market.

But can there be too much of a good thing? Oracle JET provides the Common Model and Collection API to make consuming remote REST web services easy for developers. Oracle Mobile Cloud Service, which publishes REST web services, also provides client SDKs to make consuming REST APIs easier. When combining these technologies, which “easy” option should you use? Can you have the best of both worlds?

In this article, I first explore the concepts for each development platform and then conclude with a working demo you can explore to learn more.

Oracle JET Common Model and Collection API

A cornerstone of sharing data between modern systems is undoubtedly HTTP-based REST web services. This extremely popular approach, where a client such as a mobile app requests a URL across HTTP, using a verb (GET, PUT, POST, PATCH, or DELETE) to retrieve or act upon a resource—possibly a JSON file or image or another resource type—on a server is surprisingly easy for developers to learn and utilize, as this video describes.

To avoid large volumes of boilerplate code for apps that have many remote web services to work with, Oracle JET provides the Common Model and Collection API. This JavaScript API is designed to enable Oracle JET developers to simply write some mapping code to the remote service, after which the API takes care of working with the resource across HTTP.

The following code works with a remote HR web service to retrieve employees:

self.EmployeeModelDef = oj.Model.extend({
 url: "http://<myserver>/custom/hr/employees",
 parse: function(response) {
          return { id:response["id"], 
                   name:response["name"] }; },
 parseSave: function(record) {
          return { id:record["id"], 
                   name:record["name"] }; },
 idAttribute: "id"
});
self.EmployeesCollectionDef = oj.Collection.extend({
 url: "http://<myserver>/custom/hr/employees"
 model: new self.EmployeeModelDef(),
 comparator: "id"
});
var employees = new self.EmployeesCollectionDef();

In the code, I first create an oj.Model object to represent a single object in the remote REST collection. The oj.Model object’s URL maps to the remote service, the parsers enable me to transform the incoming and outgoing JSON payloads for my needs, and the idAttribute helps uniquely identify each object.

Next I create a Common Model and Collection API oj.Collection object pointing to the same remote URL. I identify that the oj.Model object I just created is used to represent each individual object in the collection and that the idAttribute can be used to compare different objects in the collection.

With these objects set up, when the Oracle JET UI components act upon the collection at runtime to retrieve the list of employees, the Common Model and Collection API makes the appropriate REST call to the remote hr/employees web service—a GET/POST/PUT/PATCH/DELETE call—depending on what operations I perform on the collection.

Oracle Mobile Cloud Service and the Cordova SDK

The previous HR service is an overly simplistic REST service for educational purposes. Oracle Mobile Cloud Service supports multiple authentication schemes over multiple requests, and it uses several custom HTTP headers, which can make the task of calling the service more work for the client-side developer. To make this task easier, Oracle Mobile Cloud Service provides several client SDKs, including an Apache Cordova SDK, which is relevant to Oracle JET hybrid mobile apps.

As I mentioned earlier, the availability of both the Oracle JET Common Model and Collection API and Oracle Mobile Cloud Service SDKs means two competing mechanisms for calling the remote REST web service. Which do I use? Luckily the authors of the Oracle JET Common Model and Collection API considered this, so developers can override the default behavior to plug in such SDKs. For the oj.Model object you saw earlier, I can define my own oj.sync method that can intercept and override the REST GET/POST/PUT/PATCH/DELETE behavior, as shown in the following code:

function employeesSync(method, model, options) {
 var url = "hr/employees";
 var verb = "UNKNOWN";
 var payload = null;
 if (method == "read") {
  url = (model instanceof oj.Model) ? url + "/" + model.id : url;
  verb = "GET";
  payload = null;
 } else if (method == "create") {
  verb = "POST";
  payload = model.toJSON();
 } else { /* similar logic for "patch", "update", "delete" */ }
 // Assumption: mbe is already authenticated against MCS
 mcsconfig.MobileBackend.
  CustomCode.invokeCustomCodeJSONRequest(url, verb, payload,
   function(statusCode, data, headers) {
     options["success"](data, null, options); },
   function(statusCode, data) {
     options["error"](data, null, options);} );
 return {};
}

I then plug this employeesSync function into my previous oj.Model definition as follows:

self.EmployeeModelDef = oj.Model.extend({
   // include previous attributes
  sync: employeesSync
});

Now when the collection object calls Oracle Mobile Cloud Service rather than handling the GET/POST/PUT/PATCH/DELETE calls itself, it will delegate the responsibility to the employeesSync method, which has the ability to change the logic and call the Oracle Mobile Cloud Service SDK CustomCode.invokeCustomCodeJSONRequest method to take care of the call to the Oracle Mobile Cloud Service REST API.

Deploying a Running Demo Application

Let’s conclude this article with a live demo app so you can look at the real Oracle JET source code and see how it interacts with Oracle Mobile Cloud Service.

To access Oracle Mobile Cloud Service, you need a trial account. You can obtain one by clicking the Try It button on the Oracle Cloud Mobile page and filling out the required trial request details. After your trial request has been submitted and approved, watch the following video on how to set up and provision your Oracle Mobile Cloud Service instance and follow the instructions.

With the service set up and provisioning complete, set up the Oracle Mobile Cloud Service artifacts:

  1. Download this article’s demo zip file, which contains the prebuilt Oracle Mobile Cloud Service REST API and other artifacts for this article.
  2. Log in to Oracle Mobile Cloud Service as demonstrated in the video.
  3. Select Applications -> Packages from the hamburger menu, and click the New Import button and the Choose a package file link. In the resulting open-file dialog box, select the zip file you just downloaded for this article and click Open. Complete the steps in the wizard by clicking Next and finally Finish.
  4. From the hamburger menu, under Applications, select Mobile Backends, OraMagDemoMBE, and then Open. The mobile back end represents the package of existing code you just imported.
  5. Click the Settings link, and on the resulting page, copy the values for Mobile Backend Name, Base URL, mobile backend ID, and anonymous key to your favorite text editor. To see anonymous key, click the Show link.
  6. Click the Clients link and New Client button.
  7. In the resulting dialog box, enter Demo for both Client Display Name and Client Name, select Web as the platform, enter 1.0 as the version, and click the Create button.
  8. Once the client is created, copy the Application Key value to your text editor.

Later in this article, you will test the app by running it in the Android Emulator on your desktop or via a web browser. For this to work, you must enable cross-origin resource sharing (CORS) for the Oracle Mobile Cloud Service server:

  1. From the hamburger menu, select Administrator.
  2. In the Policies section, click the Export button. This will download a policies.properties file to your desktop.
  3. Open this file in your favorite text editor.
  4. Locate the line *.*.Security_AllowOrigin=disallow. Replace the line with the following:
    *.*.Security_AllowOrigin=http://10.0.2.2:8000, http://localhost:8000

You’re now ready to work with the Oracle JET demo app. If you don’t already have Oracle JET installed on your development PC, first read the previous Oracle Magazine article and watch the install instructions video to set up your PC to develop Android applications via Oracle JET.

With the artifacts set up and registered, set up the demo Oracle JET app:

  1. In your file system, create a new directory and then, via the command line in the new empty directory, type
    yo oraclejet:hybrid OraMagDemo --template=navbar --platform=android
    cd OraMagDemo
  2. Download this application source zip file, and unzip it. Copy the unzipped “src” directory over the identically named “src” directory in the OraMagDemo directory you just created with Yeoman. This Oracle JET app is the same app as the one in the previous Oracle Magazine article and is built on the Oracle JET “navbar” template, which includes several modules, such as an empty dashboard and an incidents tab. The “src” code you are adding substitutes the logic for a new employees module that replaces the generated blank customers tab.
  3. With your favorite text editor, open the /src/js/mcsconfig.js file. Within this file, locate the “config” variable, substitute in the five values you recorded earlier for your specific Oracle Mobile Cloud Service instance, and save the file. Copy the values exactly; make sure not to include any accidental spaces.
  4. If you have set up the Oracle JET tooling, including the Android SDK, type
    grunt serve

    You can also run the app in your browser by typing the following, which is faster than starting the Android Emulator, so it is often the preferred option:

    grunt serve --browser
  5. Once the app is running, select the Employees tab to see the employees data returned from Oracle Mobile Cloud Service.
Exploring the Oracle JET Code

The fact that the app is running and returning data confirms that Oracle JET and Oracle Mobile Cloud Service can be connected, but how was this achieved? For the purposes of this article, there are four key files worth exploring to help build your understanding of how Oracle JET and Oracle Mobile Cloud Service work together. Each file includes comments for further reading:

  1. src/js/mcsconfig.js. This file includes the configuration settings for your Oracle Mobile Cloud Service instance as well as the settings for instantiating the McsConfig object used by the Oracle JET application to access the Oracle Mobile Cloud Service SDK objects. For demo purposes, there is hardcoded logic at the end of this file for logging in anonymously to Oracle Mobile Cloud Service. In a real application, you would provide a login screen to enable your mobile users to do so.
  2. src/js/mcs.js. This is the Oracle Mobile Cloud Service Cordova SDK bundled with the app, and it is accessed via the McsConfig object at runtime.
  3. src/js/views/employees.html. This is the HTML page that displays the employees list view. It includes a <ul id=”listview”>, which retrieves a collection of employee rows from the datasource and then, for every row retrieved via the Knockout <script> containing the <li> tag, displays the individual attributes of the employee, such as that person’s first name and last name.
  4. src/js/views/employees.js. Here you will see the oj.Model and oj.Collection objects and the oj.sync function employeesSync described in this article.

If you’re running the app via your browser, you also have the option of discovering what is happening at the network layer between the Oracle JET app and Oracle Mobile Cloud Service. Each modern browser has a “development tools” option that enables you to inspect not just the source code of the client application but also what is happening at the network layer. With the network options open, switch back to the dashboard in the running app in your browser and then to the Employees option again. You should see, among other traffic, the GET call to Oracle Mobile Cloud Service, and then you can dig into the actual request and response objects to watch what is passed between your Oracle JET app and the Oracle Mobile Cloud Service SDK to the service itself.

Summary

By design, Oracle JET’s Common Model and Collection API attempts to make working with REST web services simple. By design, the Oracle Mobile Cloud Service SDKs also make working with REST web services simple. Luckily—or, more correctly, by design—both solutions can coexist to give you, the developer, the best of both worlds. You can never have too much of a good thing.

Next Steps

READ more about Oracle JET.

READ more about Oracle Mobile Cloud Service.

TRY Oracle Mobile Cloud Service.

FOLLOW Oracle Mobile Cloud Service on Twitter.

FOLLOW Oracle JET on Twitter.

 

Photography by Sergey Nivens, Shutterstock