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 a the ADF Mobile Persistence extension created by the A-team 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”. At the bottom of this article, you can find a link to download the extension and links to some videos that illustrate the development process.
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 extension in this article. Since then we have enhanced this extension 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. 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. 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. 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. You will typically modify the class name for each data object to get descriptive, singular class names generated. 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. On the child accessors page, you can specify attribute mappings for parent-child relationships between data objects. 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. 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. 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. On the last page of this wizard, you can enter some generator settings. When clicking finish, you can check the log window for the files that have been generated. 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
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. On the next page, you can specify REST resources that will be used by the wizard to discover candidate data objects. 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. 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. 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. 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. 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. 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. 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. 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. 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.
Getting Started with the A-Team Mobile Persistence Sample
The A-Team ADF Mobile Persistence Sample is packaged as a JDeveloper extension. It is powerful and sophisticated sample code that you can (partially) reuse, extend or copy as desired. You can use it at your own risk, there is no support channel available, but we are always interested in feedback that you can provide by commenting on this article. The easiest way to get started is to install the extension and watch the videos that come with the extension. Here are the files you need for this:
- adf-mobile-persistence-sample-install.zip (build 18.104.22.168.78, last updated may 23, 2014): This zip file is the JDeveloper extension. Download it, start JDeveloper 22.214.171.124, go to the Help menu, choose “Check for Updates” and then choose the option “Install from local file”. Select this zip file, and the mobile persistence sample code will be installed.
- Creating a Mobile Application Using SOAP Web Service: This video demonstrates how to generate a fully functional ADF Mobile application that reads and writes data using an ADF BC SOAP web service. All data retrieved through web service calls is stored locally on the device in the SQLite database, allowing you to use the application in offline mode. The video also demonstrates the data synchronization functionality that is provided to process transactions made in offline mode.
- Creating the Business Objects Layer in a Mobile Application Using REST Web Service: This video demonstrates how to generate the business objects layer when using REST-JSON a web service. Generation of the mobile user interface layer is not included in this video as the process is the same as shown in the previous video.
- Creating a Mobile Application Using AuraPlayer Web Service: This video demonstrates how to generate an ADF Mobile application on top of AuraPlayer web services. AuraPlayer is a third-party product that allows you to record Oracle Forms scenario’s and publish them as web services, allowing you to reuse Oracle Forms business logic in a mobile application. For more information see the AuraPlayer website.
The sample applications from the videos can also be downloaded:
- HrCrudMobile.zip: This zip contains the finished application as created in the video ‘Creating a Mobile Application Using SOAP Web Service’. After unzipping, open HrCrudMobile.jws in JDeveloper to view and run the application. This application uses the HRDemoSOAP and HrDemoRest applications as remote persistence providers. Make sure you change the IP addresses in connections.xml before you run the sample. You can switch from SOAP (the default) to REST persistence providers by changing the persistence.mapping.xml entry in mobile-persistence-config.properties and instantiating the REstJSONPersistenceManager instead of the DataControlPersistenceManager in the DepartmentService class. (The RegionService is only provided as SOAP web service)
- HRDemoRest.zip: This is a “bigADF” web application that exposes ADF BC CRUD functionality as RESTful web services. To use this application, unzip the HRDemoRest zip file, open the HRDemoRest.jws in JDeveloper and modify the connection details as needed to connect to your local HR schema. Run the HRDemoRest web application by clicking the Run button while selecting the ViewController project node. This will start the ADF Faces web application. There is a ReadMe.txt file in the root directory that describes the REST services provided by this application.
- HrDemoSOAP.zip: This is an ADF BC application that exposes ADF BC CRUD functionality as SDO SOAP web services. To use this application, unzip the HrDemoSOAP zip file. Open the HrDemoSoap.jws in JDeveloper and modify the connection details as needed to connect to your local HR schema. Deploy the HRDemoSoap Model application by right-mouse-clicking on HRServiceServiceImpl.java (inside serviceinterface package) and choosing Run. To test the deployed web service, right-mouse-click on HRServiceService.wsdl and choose Test Web Service. The HTTP Analyzer window will appear. Select the findDepartments method in the Operations field, and click the Send Request button. The departments and its employees should now be displayed in response window.
Note that the sample code requires at least ADF Mobile extension build 126.96.36.199.39.64.62 that has become available in January 2014. You can also take a look at this presentation which includes some more screenshots to illustrate the development process when using the ADF Mobile Persistence extension..
All site content is the property of Oracle Corp. Redistribution not allowed without written permission