Monday, March 16, 2015

REST Service Access with A-Team Mobile Persistence Accelerator

A-Team Mobile Persistence Accelerator (AMPA) works on top of Oracle Mobile Application Framework (MAF) and provides tools to simplify consumption of REST services. It enables transparent persistent layer usage on the device with the option of synchronising offline data with the server side. In this post, I will be testing AMPA in the context of the use case implemented previously - MAF 2.1 Alta Mobile UI and Oracle Mobile Suite. Working MAF application, where REST service calls are coded by hand, will be changed to fetch REST service data through AMPA - reusing existing Data Control. This is unusual approach, most of the tutorials related to AMPA describe end-to-end scenario, where Data Control is generated on top of AMPA service class and UI is generated with AMPA wizard. Mobile UI in most of the cases will be custom made and we rarely generating it. This is why it is important to explain, how to use AMPA with custom UI and Data Control.

You could read more about AMPA and find installation instructions in Steven Davelaar post - Getting Started with the A-Team Mobile Persistence Accelerator.

I will be using my sample application from the MAF 2.1 Alta UI post mentioned above. You can download application updated with AMPA support here (this includes ADF BC SOAP service, OSB transformation to REST and MAF application with AMPA) -

As soon as REST connection is defined, AMPA wizard offers you to define REST resources. In my case I have to different resources, though working with the same Employees data schema. Both require to provide parameter:

Wizard is going to ask you to provide sample parameters to retrieve a response from REST resources. This is how AMPA retrieves metadata required to generate service representation in MAF:

Data Objects will be constructed automatically for each resource path. In my case, both resources are based on the same schema Employees. If this is the case for you, make sure to change the names in the wizard to be unique, otherwise AMPA fails to generate proper SQL scripts and service classes.

In this example I don't want to persist any data on the device. My use case requires to retrieve latest data from the server, therefore there is no need to keep a copy on the device - this is why Persistent checkbox is not set:

Next you will get similar wizard as in ADF BC, where all attributes for the service will be listed along with types, etc.:

I don't have any create/update/delete operations in the example, therefore only mapping present if for find operation:

Both REST resources were defined with attributes. We need to set the values later, for this purpose we could define ELExpression value provider for the attribute and type actual expression into Literal Value field. You could use any scope, I'm using applicationScope in this example. Variable defined by EL expression must be initialised before executing REST operation - this will be done later, in the code:

Six easy steps and AMPA persistence layer for MAF is generated. Let's take a quick look, what was actually generated. There is SQLite script with on device DB structure - two different tables will be created, each per REST service defined in the beginning:

In this example, I'm not really using on device DB, tables are not mandatory. Persistence mapping file is generated, this is where on device persistence structure and REST service mapping is defined. This mapping is used as a metadata resource to describe how data retrieved from REST service should be translated into on device persistence layer. I have set the option not to persist data, this will only retrieve it:

AMPA does a remote read in background by default - this means it reads data from REST, populates it into local SQLite DB and doesn't wait until operation is completed. This is good for performance optimisation reasons in some use cases, but is not suitable, when we want to see data immediately in the same request (especially when we are integrating AMPA into our own custom service class). Remote read in background can be turned off through persistence mapping:

Service class is generated, it extends from AMPA service. We could generate Data Control on top of this class and use it from MAF UI. However, I would like to integrate it into existing service class and consume from existing Data Control:

You could generate Data Control through JDEV menu, as displayed below.

In my case, I have Data Control already - generated on top of ServiceHelper class, I will reuse it. Here is the service class - ServiceHelper. In order to use AMPA generated service class and POJO types from existing service class, I have changed types for service class variables. Names and POJO structure remains the same, this means Data Control will continue to work:

Method responsible to search for employees by name is changed to invoke AMPA functionality. Instead of calling REST service and transforming response - I'm initialising EmployeeService generated by AMPA and calling findAllEmployeesRemote method. Remote method works with REST service, this is what we need - always fetch latest available data from the service:

You should notice how REST service variable is initialized - through EL Expression in application scope. This is the same expression as we have defined in resource mapper.

Here you can see how it look on UI. List of employees is filtered and displayed on the mobile device screen. Data from REST service is retrieved through AMPA, UI remains exactly the same as it was implemented in the previous version of the application:

Very important thing to mention - MAF Data Control is able to cache data by itself. Once you fetch data and if you don't require offline support, MAF Data Control is able to keep fetched rows in memory, without requiring them from the service.

For example, we fetch a set of rows with David Austin in the list:

There are two different MAF fragments (List and Edit), attached to the same Data Control. When we navigate to Edit and back to List, there is no REST call executed - MAF is using previously fetched data from Data Control (there is no need to use AMPA to handle such use cases):

Detail data for David Audit is retrieved from MAF Data Control:

You need to ensure - getter in service class implementing Data Control is not triggering a call to the REST service. REST service call must be invoked from Method Call, before MAF fragment is loaded - this will allow to prepare data in advance (see Task Flow diagram above):

No comments: