By Chris Muir
September/October 2017
Experiencing zero connectivity when you use mobile applications is exceedingly annoying, but a more frustrating experience might be connectivity that keeps dropping in and out, causing mobile apps to stutter and fail without an always-on data connection. Adding the ability for apps to cache data when connected, and rely on the cache when disconnected, allows for a much smoother user experience.
Fetching and maintaining data in the local cache is a significantly different coding challenge from just fetching remote data. Building code to store and maintain data in a cache can be a time-consuming and complex task. Ideally, mobile developers would flip a switch and this caching would happen automatically.
With its JavaScript and Apache Cordova SDKs, Oracle Mobile Cloud Service provides mobile developers with this exact switch, known as Sync Express. Sync Express is an extension to the JavaScript and Cordova SDKs that—when turned on (“flipped”) and configured for a remote REST API—will cache the data on the mobile client, without requiring extra coding.
In this article, you will use an example application to explore how to configure an existing Oracle JavaScript Extension Toolkit (Oracle JET) application to make use of the Oracle Mobile Cloud Service Sync Express feature. The example application is one you’ve used in previous Oracle Magazine articles: a simple employees’ phone book application that gets its data from a remote API hosted by Oracle Mobile Cloud Service.
Setup
For the article, you will first need to install Oracle JET. The Oracle JET documentation covers this task in detail; follow the instructions for installing both the web and mobile tooling components.
Note for this article that the steps assume you are developing on a Microsoft Windows PC and deploying to the Android Emulator on a PC.
After installing Oracle JET, you need to configure Oracle Mobile Cloud Service. This article is based on exactly the same setup instructions from the January/February 2017 Oracle Magazine article “Too Much of a Good Thing.” Perform Step 1 through Step 8 under the “Deploying a Running Demo Application” section of that article; however, use the demo download file for this article instead of the download file provided in Step 1 of the earlier article. These steps will configure the required Oracle Mobile Cloud Service remote APIs for the mobile application you will see in a moment, supplying the employee details for the employees’ phonebook app.
You must also enable cross-origin resource sharing (CORS) for the Oracle Mobile Cloud Service server:
*.*.Security_AllowOrigin=disallowReplace the line with the following:
*.*.Security_AllowOrigin=http://10.0.2.2:8000, http://localhost:8000
cd cd Desktop mkdir test cd test yo oraclejet:hybrid OraMagDemo --template=navbar --platform=android cd OraMagDemo rd /s srcThis creates the application scaffold. Note that you just deleted the src directory of the application, leaving the raw scaffold for adding new code.
Testing the Vanilla App
With the previous steps completed, you are now ready to test the vanilla application before you include Sync Express.
grunt serve --platform=android
The application runs and displays the employees’ data extracted from the remote Oracle Mobile Cloud Service API.
One feature of the app is the pull-to-refresh-the-list view. Data on the screen is updated via another remote call to the Oracle Mobile Cloud Service custom API. Because the employees’ details don’t change frequently, refreshing the data won’t often result in a visible change to the list. But in a moment, when you start to refresh the data when the app is online and offline, you will need a way to see when fresh data is coming down from the server.
To present this fresh data, I’ve “hacked” the Oracle Mobile Cloud Service remote API that I provided and mapped the phone numbers to the current time in milliseconds and incremented each number by the record ID value. As such, each time you refresh the list view, the server updates all the phone numbers of all the employees, and this proves the data is getting updated via the server at each refresh, in turn proving your mobile device is currently online.
Now let’s watch what happens when you switch from online to airplane mode, and the app can no longer access the remote API provided by Oracle Mobile Cloud Service.
Adding Sync Express
There are three steps you must complete to utilize Sync Express in this app.
First, add a script element to the HTML file to load the associated mcs.sync.js library that contains the Sync Express functionality. This file must be the first script the app fetches and loads. Typically, in an Oracle JET app, you would use RequireJS to load the other JavaScript libraries, but the Sync Express library needs to work at a lower level than that so it can capture all remote HTTP calls. That’s why you need to add it to the main index.html page as the first script to run.
<script type="text/javascript" src="js/mcs.sync.js"> </script>
The tag refers to the js/mcs.sync.js library, and for this article, I’ve taken a shortcut and provided the library for you in the src directory you copied over earlier from the downloaded zip file. Typically, this JavaScript library is downloaded from Oracle Mobile Cloud Service as part of the JavaScript or Cordova SDK.
Now add the Cordova Network Information plugin to give the sync library the ability to know if the app and device are online or not.
cd hybrid cordova plugin add cordova-plugin-network-information
Now configure the Cordova SDK to specify which remote APIs to cache data from when fetched. You do this through the mcsconfig options you pass to the Cordova SDK when you first initialize it. In the mcsconfig options of the src/mcsconfig.js file you modified earlier, add a new element—syncExpress—at the end, including a policies element and a path element with every path you want Sync Express to cache data from.
,"syncExpress": { "policies": [ { "path": '/mobile/custom/hr/employees/:employeeId(\\d+)?' } ] }
You’ve added a path from the Oracle Mobile Cloud Service custom API URL for fetching phone book data from /mobile/custom/hr/employees/:employeeId.
Note the syntax in the path example: a colon followed by “employeeId.” This implies “employeeId” is a variable part of the URL path and does change. In addition, the question mark indicates the employeeId is optional, implying sometimes it will just fetch all the employees, as it is doing for this app. Finally, the odd syntax inside the parentheses—two backslashes, “d,” and a plus mark—says the employeeId is a decimal rather than a string (the default). If it is a string, you can drop this notation.
Having configured Sync Express, what do you have to do with the code to make it work with Sync Express?
Nothing. As long as you include in the mcsconfig.js file the paths you want to cache, under the covers Sync Express intercepts HTTP calls and will automatically cache the data for you when it is first returned from the server.
Let’s look at the outcome.
cd .. grunt serve --platform=android
Once the app has been redeployed and started, it initially fetches data from the server because the device is online. Now switch to airplane mode to move the device and the app offline, and refresh the data again by performing a pull. Rather than getting stuck at the refresh screen, the app’s call to fetch the remote data returns the previously cached data instead. Now switch out of airplane mode and again pull to refresh the data. The data—pulled from the server—starts updating because the device is online again.
Summary
Oracle Mobile Cloud Service Sync Express allows you to quickly add offline capabilities to your mobile applications. As you’ve seen in this article, the name “Sync Express” fits the feature well, because adding it to your mobile apps is a relatively painless and turnkey-like process that doesn’t require you to extensively modify your source code.
Next Steps
READ
more about Oracle Mobile Cloud Service.
WATCH Oracle Mobile Cloud Service YouTube training.
TRY Oracle Mobile Cloud Service.
Photograph by iStock.com/ottawa
Chris Muir is a senior principal product manager of mobility and development tools at Oracle.