By Frank Nimphius-Oracle on Aug 28, 2015
With the recent release of Oracle MAF 2.1.3 a new utility becomes available that simplifies access to Oracle Mobile Cloud Services (MCS) from Oracle MAF applications. Oracle MAF MCS Utility (MAF MCS Utility in short) is a Java library for Oracle MAF applications and exposes MCS client platform REST API calls as native Java calls. This blog post introduces Oracle MAF MCS Utility, explains what it does, how it works and where to find it.
Oracle Mobile Cloud Service client API
Oracle MCS is all about REST! Any mobile client that is capable of sending REST requests and to handle JSON responses can invoke MCS mobile platform functionality exposed on a mobile backend (MBE). This includes calls to Analytics, Notification, Storage, User Information and Custom API.
About MCS client SDK
REST is a good choice for Oracle MCS and ensures an understandable and very easy to use application development interface.
From the perspective of mobile application developers however, accessing REST interfaces from mobile applications is a mental mismatch. To access REST APIs from a mobile application developers need to "think REST" though their comfort zone is within their favorite programming language, which for mobile usually means Objective-C, Java or scripting.
To address this lack of developer comfort and to improve developer productivity, Oracle MCS provides development language specific client SDKs. The MCS client SDK provides a native language abstraction to the underlying REST calls (for Android and Objective-C at current, as well as Xamarin), plus handy infrastructure functionality like offline synchronization and support for push notification registration and handling.
The image below shows the basic architecture pattern implemented by all Oracle MCS SDKs. All in all, using the MCS SDK makes developers more productive, requiring them to write less code.
A MBE Manager object, a singleton, is configured with information required to access mobile backend(s) exposed on an Oracle Mobile Cloud Service instance. Mobile applications access the MBE Manager to obtain an instance of an MBE object representing a specific mobile backend in MCS.
The MBE object itself exposes Service Proxy objects that abstract the MCS platform API access. When using the service proxy objects to read and write to the remote mobile backend on the remote MCS instance, the MCS SDK takes care for all required request headers to be added (e.g. Oracle-Mobile-Backend-Id, Authorization, etc.), thus reducing the error surface for application developers.
You can tell from the above description and image that the MCS client SDK is a simple but effective solution for mobile application developers to stay in their comfort zone.
About MAF MCS Utility
Oracle MAF is a Java based framework that uses Apache Cordova to deploy mobile applications to the Android and iOS platform (and Windows in a future release). MAF uses Java as a shared language across mobile platforms. The use of Java and the cross platform nature of MAF don't allow the use of one of the existing MCS client SDKs. This is where MAF MCS Utility comes in.
MAF MCS Utility provides functionality similar to those of the Oracle MCS client SDKs with some minor differences explained in the following with the help of the image below.
MAF MCS Utility needs to be added as a JAR file to MAF applications and is deployed to the mobile device as part of the application. For this, MAF application developers add the mafmcsutility.jar file to the ApplicationController and/or ViewController project.
The MBE Manager, a singleton, manages MBE object instances that are created from a MBE configuration object. A copy of the MBE configuration object is stored and updated within the MBE instance. MAF application developers can access the MBE configuration object at runtime to e.g. dynamically enable or disable MBE specific logging or to enable or disable collecting analytic events. Service Proxy objects in MAF MCS Utility expose MCS platform REST API calls as typed native Java method calls.
To issue REST requests and handle JSON reponses, MAF MCS Utility wraps the MAF framework RestServiceAdapter class to benefits from MAF features like the security framework and the declarative REST connection framework.
MAF MCS Utility exampleThe code snippet below creates a MBE configuration object to then obtain a MBE instance from the MBE Manager to showcase how easy MCS integration becomes with MAF MCS Utility
MBEConfiguration mbeConfiguration = new MBEConfiguration( <mbe rest connection>,<mobileBackendId>, <anonymous key string>,<application key string>, MBEConfiguration.AuthenticationType.BASIC_AUTH);
MBE mobileBackend = MBEManager.getManager(). createOrRenewMobileBackend(<mobile backend Id>, mbeConfiguration);
As you can see, the majority of the code lines above are to define the mobile backend specific information like the MCS MBE id, its base URL, as well as the anonymous key (for public access) and the application client key, which allows MAF MCS Utility to register a MAF application with MCS to receive push notifications from MCS. Once you have a handle to the MBE object you call service proxy objects for a specific MCS platform interface as shown below.
UserInfo userInfo = mobileBackend.getServiceProxyUserInfo();
Analytics analyticsProxy = mobileBackend.getServiceProxyAnalytics();
Storage storageProxy = mobileBackend.getServiceProxyStorage();
CustomAPI customApiProxy = mbe.getServiceProxyCustomApi();
Where to get MAF MCS Utility
MAF MCS Utility ships as part of the MAF 2.1.3 public samples. The sample contains the MAF MCS Utility source code, a compiled ready-to-use mafmcsutility.jar library file and a MAF application that demonstrate how to use MAF MCS Utility.
The MAF MCS Utility sample application (shown in the image below) is a generic Oracle MCS tester that can be configured to run against any MCS public cloud instance.
MAF MCS Utility Positioning
MAF MCS Utility provides MCS SDK functionality for Oracle MAF application developers to easily integrate calls to Oracle Mobile Cloud Services in their mobile applications. It improves developer productivity by shifting the "think REST" development style to "think Java" when accessing Oracle MCS platform APIs from MAF applications, which also means less code to write.
Because MAF MCS Utility implements the same architecture access pattern as the existing (and future) MCS SDK there is no extra learning curve to it. If you can do it in Android and iOS, you can do it in MAF as well (and vice versa).
MAF MCS Utility Developer Guide
MAF MCS Utility is further explained in a developer guide, which also covers the MAF MCS Utility public sample application. For each service proxy, the developer guide points you to where in the public sample you find sample code to study and reuse.