Going Mobile with ADF – Implementing Data Caching and Syncing for Working Offline Part II

Introduction

When building ADF Mobile applications that go beyond displaying read-only data, you quickly find yourself programming Java code. If you want to use the on-device SQLite database to store data locally, for example to cache data or to enable working in off-line mode, the amount of code you have to write quickly increases, and while programming you probably realize that you are repeating the same coding patterns for each web service that you want to call to read or write data. This article introduces the second release of the A-Team Mobile Persistence Accelerator which avoids most of these coding patterns by using highly generic Java code driven by metadata. In addition, the few Java classes that are still needed are auto-generated for you, and a default mobile user interface can also be generated. This extension takes ADF Mobile development to the next level, effectively allowing you to create within a few minutes a fully functional ADF Mobile application that reads and writes data using a remote web service. In addition all data is stored locally on the device in the SQLite database, allowing you to use the application in offline mode. Basic data synchronization functionality is also provided to process transactions made in offline mode. This article explains how to use the three main wizards from this extension that do all the “magic”. Download and getting started instructions for the Oracle MAF version of this extension can be found here.

Main Article

In the first part of this article, Going Mobile with ADF – Implementing Data Caching and Syncing for Working Offline Part I, written in October 2013, we described the architecture and programming effort required to implement data caching and data syncing functionality to your mobile application. We also introduced the first release of the A-Team ADF Mobile Persistence accelerator in this article. Since then we have enhanced this accelerator significantly by adding four powerful design-time wizards. After installing the new version of this extension, you will notice a new category “ADF Mobile” in the New gallery under Business Tier. NewGallery

The three wizards in this category all create a persistence layer of business objects, including a SQLite database and persistence mapping XML file, enabling the same runtime architecture as introduced in part 1 of this article. PersistenceArchitecture The new wizards allow you to generate all the artifacts needed for this runtime architecture. The first part of this article has been updated to explain the structure of the runtime artifacts generated by these wizards.This second part explains how to run the design-time wizards.

Running The ADF Mobile Business Objects From Web Service Data Control Wizard

The starting point of this wizard is the selection of a SOAP web service data control that you created using the standard JDeveloper Web Service Data Control (SOAP/REST) wizard. SelectDataControl When clicking Next,the wizard will inspect the payload of the various methods in the web service data control and present a list of candidate data objects that you might want to use in your application. SelectDataObjects You will typically modify the class name for each data object to get descriptive, singular class names generated. SelectDataObjectsClean On the next wizard page, the attributes of each selected data object are presented, You can change the key, required, name, Java type and DB column type of each attribute as desired. However, since the type information is based on the XSD of the web service, you typically can leave the defaults values as they are. DataObjectAttributes On the child accessors page, you can specify attribute mappings for parent-child relationships between data objects. ChildAccessors The suggested parent-child relations are based on the structure of the web service payload. This relationship is used at runtime to query detail collections from the SQLIte database so parent-child relationships can be restored when working with cached data. In the screen shot above, we map the countryId from the Location data object to the countryId attribute from the Country data object. Note that the wizard allows you to only select a parent attribute. This is useful when the child data object does not include the attribute that refers to the parent. This is quite common as the web service payload is sent in hierarchical format and including the countryId in the Location data object is redundant. If no child attribute is selected, clicking the Add button will add an additional attribute to the child data object which will be auto-populated at runtime by the generic ADF Mobile Persistence Sample code. On the CRUD Methods page you specify which data control method should be invoked for each of the CRUD operations. The drop down lists shows all the available data control methods. CrudMethods In addition, you can specify the sort order and the the format for date and datetime attributes included in the payload. The CRUD method information is read at runtime by the generic runtime code included in the extension. For example, when inserting or updating a data object in the mobile user interface, the runtime code will execute the appropriate SQL statement against the local SQLIte database and will invoke the corresponding data control method when online. In offline mode, a pending data sync action will be registered that can be used later on to synchronize the data with the remote server when the user is online again. On the CRUD Method parameters page, you specify the how each parameter of the data control methods selected on the previous wizard page must be populated. CrudMethodParameters In this example we use an ADF BC SDO SOAP web service, where the create, update and remove methods all take just one parameter which contains the data object serialized into XML format. For more complex web service methods, you can also choose to populate the parameter with the value of a data object attribute, a literal value, the value produced by an EL expression, or the value of the quick search field. Here is a screen shot of a the same wizard page when using an AuraPlayer web service. CrudMethodParametersAuraPlayer On the last page of this wizard, you can enter some generator settings. GeneratorSettings When clicking finish, you can check the log window for the files that have been generated. GeneratorLog The structure of the generated files is explained in the first part of this article. You can now create a data control for the DepartmentService and RegionService classes and use these data controls to create the ViewController layer of your mobile application. You can do this manually using drag-and-drop from the data controls, or use the ADF Mobile User Interface Generator discussed in the last section of this article.

Running The ADF Mobile Business Objects From REST Web Service Wizard

This part is obsolete, see the article A-Team Mobile Persistence Accelerator for Oracle MAF for a description of the new and improved version of this wizard.

You use this wizard when you want to build (part of) your mobile application against a REST web service which either uses JSON or XML as payload format. Note that while you can use the standard JDeveloper Web Service Data Control (SOAP/REST) wizard to create a REST-XML data control, you can skip that step by directly using this wizard. The structure of this wizard is very similar to the ADF Mobile Business Objects from Web Service data Control wizard. The main difference is that we do not have a data control to inspect to identify candidate data objects, nor do we have a list of data control methods to map to CRUD methods. The starting point for this wizard is a page where you can specify the URL connection for your RESTful web services. URLConnection On the next page, you can specify REST resources that will be used by the wizard to discover candidate data objects. DataObjectRESTResources When clicking Next, the wizard will execute the specified REST web service calls and parse the sample payload returned for candidate data objects. The wizard will then show the same pages for selecting data objects and setting data object attribute properties as used in the  ADF Mobile Business Objects from Web Service data Control wizard. DataObjectAttributesREST Note that with REST web services, you usually need to modify the Java type for the attributes as they typically will show up as java.lang.String. When using JSON payload, some attributes may show up as java.math.BigDecimal when the value is not enclosed in double quotes. Anyway, you can easily change the Java types using the class picker, and the DB column type will automatically be updated based on the Java type you selected. The child accessors page is the same as in the first wizard. The CRUD Methods page is called CRUD Resources page in this wizard, and allows you to enter additional REST resource URI’s and its corresponding request type to specify the CRUD methods. CRUDResources Note that you can include a query string to pre-populate the next wizard page with resource parameter names. The last two wizard pages are again the same as in the first wizard discussed in this article. Clicking finish will generate the same files as the first wizard.

Running the Mobile User Interface Generator Wizard

When selecting the existing ADF Mobile category under the Client Tier, you will notice a fourth option that has been added after installing this extension: the Mobile User Interface Generator wizard. MobileUIGenerator This wizard allows you to generate a default CRUD user interface that you can modify as desired later on using the JDeveloper design-time tools. It generates features, task flows, AMX pages and page definitions, just like the artifacts that are created when you would create the user interface manually. On the first page of the wizard, you select a data control that you created from the service objects that were created by one of the “business objects” wizards. SelectUIDC Only data controls which are based on such a service class, extending from the oracle.ateam.sample.mobile.persistence.service.EntityCRUDService class are shown in the drop down list. You also can specify the feature security, either local or remote. Using this security options requires that you have set up a login server as documented in the ADF Mobile developer’s guide. On the second and last page of this wizard you can specify a number of user interface settings. UISettings For each data object a list and form page (fragment) will be generated, and you can configure whether a list for a child data object should be included on the same page as the form fields of the parent data object. The generated user interface is optimized for rendering on mobile phones, but can easily be adapted to take advantage of additional screen real estate when your target device is a (mini-) tablet. Note that generation of the AMX pages, page definitions and task flows is generated by Velocity templates, located in the templates sub-directory of the mobile persistence extension directory. TemplatesDir If you are familiar with the Velocity template language, you can modify these templates as desired to get a default user interface that comes closer to your desired look and feel.      

Running the Generated Mobile Application

When starting the application for the first time, you will see the department list page with an empty list. In the background, the findAll web service method is invoked and after a few seconds the screen refreshes and the list of departments is shown on the screen. You can click on a department to navigate to the form page, and then click on one the employees in the department to see the employee details. DepartmentPages All departments are also stored in the on-device SQLite database allowing you to use the application in offline mode. When you make changes, for example updating or creating new departments in offline mode, these transactions are stored as pending data sync action.You can use the overflow menu to navigate to a reusable feature that comes with this extension, to look at these pending data sync actions. Clicking on a pending sync action shows the details. SyncForms When you are online again, you can explicitly process the pending data sync actions by choosing the Synchronize menu option, or you can do it implicitly by making another change to a department. The runtime code will first process the pending data sync actions before processing your latest transaction.

 

 

Comments

  1. Veeresh Gandhaveedi says:

    Hi Steven,

    One more question.

    My webservice method is input specific, Meaning it will return results only for the input entered while execution. Example as show below.

    Public Company getCompanyDetails(int compId){
    Company company= new Company();
    if(1=compId){
    company.setname(“ABC”);
    }
    return company;
    }

    How can I achieve this use case using this posts.

    Please suggest.

    thanks,
    Veeresh

  2. Steven Davelaar says:

    Veeresh,

    I just downloaded the zip file and installed it without any problems on a Mac.
    Can you retry, and if it fails provide the steps you perform and the error you get.

    Also, the file is named adf-mobile-persistence-sample-install.zip, so looks like something went wrong with your download.

    Steven.

    • Veeresh Gandhaveedi says:

      Hi Steven,

      I have tried once again by downloading the zip file from this site and resulted in same error as follows.

      “Zip File adf-mobile-persistence-sample-install.zip does not contain bundle manifest in META-INF/bundle.xml”.

      When I download in MAC, the file is automatically unzipped, I am compressing it to zip file and then trying to install it in JDeveloper. thats where I am getting the above error.

      Please suggest how to resolve this issue.

      thanks,
      Veeresh

      • Steven Davelaar says:

        Veeresh,

        OK, then the problem is caused most likely by the unzip action.
        Use Google Chrome on your Mac, or if you want to stick with Safari, go to preferences > general, uncheck [] “Open safe files after downloading”

        Steven.

  3. Veeresh Gandhaveedi says:

    Hi A-Team,

    great work.

    I am trying to use the same in IOS, when I do that it gives me the following error.

    “Zip File adf-mobile-persistence-sample2-install.zip does not contain bundle manifest in META-INF/bundle.xml”.

    Please let me know how to resolve this issue.

    thanks,
    Veeresh

Add Your Comment