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 APIA 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 SDKThe 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 ApplicationLet’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:
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:
*.*.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:
yo oraclejet:hybrid OraMagDemo --template=navbar --platform=android cd OraMagDemo
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
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:
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.
SummaryBy 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.
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