Best Practices from Oracle Development's A‑Team

A-Team Mobile Persistence Accelerator Release Now Available!


A new release of the open source A-Team Mobile Persistence Accelerator (AMPA) has been made available on GitHub. AMPA is a productivity toolkit that works on top of Oracle's Mobile Application Framework (MAF) and auto-implements a range of best practices in MAF development with a focus on mobile persistence. In this article we will discuss the main new features of release If you are new to the AMPA, you first might want to read the introductionary "Getting Started" article.

Main Article

RAML Support

Restful API Modeling Language (RAML) is an emerging standard for describing and documenting RESTful API's. RAML is easy to read for humans, and at the same time structured enough for computers to parse the API definitions. The existing AMPA wizard that generates the MAF persistence layer and data objects based on sample resources has been extended to support RAML. You can now choose to specify a sample resource or sample resource payload as before, or you specify a RAML document and then the wizard will suggest the data objects, parent-child relations and CRUD resources based on the content of the RAML document.


For this to work, the RAML document must contain payload specifications, either in the form of a JSON schema reference, or a sample payload included in the RAML document or a referenced RAML payload template file using the !include syntax.

Oracle's Mobile Cloud Services (MCS) product, to be released later this year, also uses RAML, API's specified within MCS can be consumed seemlessly by the combination of Oracle MAF and AMPA, without the need for any Java coding.

Support for Logging REST Calls

The area where you typically have most problems during mobile app development is the invocation of your RESTful services. If request payloads or request headers are not specified correctly, the service call will fail. If the response payload has a different structure than expected, processing of the return payload will fail. Troubleshooting these issues around your RESTful services can be cumbersome. Adding logging statements and/or debugging the RestPersistenceManager.invokeRestService method line-by-line are typically the best way to fix these issues, but can be time-consuming. This new AMPA release will make your life much easier when it comes to debugging REST calls. There is a new property logWebServiceCalls which by default is is set to true by when you create the persistence-mapping.xml using the REST wizard.


When this property is set to true, AMPA logs the details of all REST calls into a database table in the SQLIte database. AMPA also includes a reusable feature archive that you can add to your application to easily view the details of the REST calls at runtime. This includes the request headers, request and response payload, any invocation error messages and last but not least the duration of the REST call in milliseconds. To add this reusable feature to your application, you simply add the feature archive WebServiceCallsFeature.jar as an application library:


This jar file can be found under jdev_home/jdev/extensions/oracle.ateam.mobile.persistence. After you added the feature archive file, you can add the feature to your maf-application.xml file:


An even easier way is to use the MAF User Interface Generator that comes with AMPA. If you generate a default CRUD interface for your bean data controls, the web service call feature will be automatically added to your application. You then start your app, test the CRUD functionality of your own features, and then you can switch to the "WS Calls" feature to see all the REST calls that have been made, including any errors that might have occurred during invocation.


In the list view you can use the quick search to filter on a specific HTTP method or on a specific resource. Do not forget to hit the search button again when you are switching back and forth between your own features and this logging feature. New REST calls will not appear automatically after you launched the logging feature. If you prefer to build your own logging feature, you can simple create a bean data control from class oracle.ateam.sample.mobile.logging.WebServiceCallService as shown below.


Obviously, you will typically only use this kind of loggin during development, so we recommend to set this property to false when deploying your app into production. Having said that, you might want to temporarily switch on this feature at runtime to help debugging end user problems. You can do so by setting the application-scoped variable logWebServiceCalls (#{applicationScope.logWebServiceCalls}) to true.

Editing of Persistence Mappings

A new visual editor is provided that allows you to more easily edit existing data object mappings. The editor can be invoked by right-mouse-clicking on a project node in the application navigator of your MAF application and then choosing Edit Persistence Mapping from the popup menu.


This editor is basically a simplified version of the REST wizard. You will only run the REST wizard if you need to add new data objects based on sample resources or a RAML document to your application.The Resource Details page is an enhanced version of the old Resource Parameters page.


In addition to the resource parameters, there are new fields to configure the structure of the response payload (in case of GET resources), or the request payload (in case of non-GET resources). Previously this configuration could only be done by directly editing the persistence-mapping.xml file.

Automatic Invocation of Canonical Resource

The Canonical Resource is the RESTful service to get all details about a specific data object instance. To reduce size of payloads as much as possible, it is good practice to have two separate RESTful resources, one to return a list of say departments, which only includes "summary" attributes that are needed to populate the list view page. Then, when the user selects one department and navigates to a detail page, a second REST resource is invoked which returns all additional "detail" attributes of the department and possible some child collections like the list of employees in the department that are shown on the detail page. This second "detail" resource is called the canonical resource in AMPA.

We now added the ability to have AMPA automatically invoke the canonical resource by specifying a triggering attribute in the REST wizard and Edit Persistence Mapping dialog.

Canonical Trigger Attribute

If the triggering attribute is specified, AMPA will generate code in the getter method of this attribute to invoke the getCanonical method. This way UI developers no longer have to worry about invoking the getCanonical method when navigating from a list view to a more detailed form view, the method call is now handled transparently within the model layer. By default, the canonical method is executed in the background and the UI will be refreshed once the REST response has been processed.

Support for Custom Resources in REST Wizard

In addition to CRUD resources, you can now also specify custom resources in the REST wizard or Edit Persistence Mapping dialog. AMPA will generate a corresponding method in your service class for each custom resource and will take care of the low-level code required to invoke the REST resource. The Resource Details page (see above for screen shot) now includes an iconic plus button which launches a dialog to specify the custom resource:


You can then drag and drop the custom method as a button onto your page to invoke the custom resource. By using this custom resource facility,your custom REST calls will be included in the standard AMPA data synchronization cycle: if the REST calls fails because the device is offline or some other service invocation error occurs, the custom resource invocation is marked as pending data sync action and will be replayed the next time the user tries to perform some remote write action.

See the release notes for a complete list of all enhancements and bug fixes in release

If you have any questions about the use of AMPA, then please use the Oracle MAF Discussion forum and mention the versions of MAF and AMPA you are using.

Be the first to comment

Comments ( 0 )
Please enter your name.Please provide a valid email address.Please enter a comment.CAPTCHA challenge response provided was incorrect. Please try again.Captcha

Recent Content