X

Best Practices from Oracle Development's A‑Team

Migrating AMPA Apps to Oracle MAF 2.3.1 Client Data Model

Introduction

Oracle MAF 2.3.1 has just been released. This release contains a major new feature, the client data model (CDM). CDM is the productized version of the A-Team Mobile Persistence Accelerator (AMPA). This article explains how you can migrate your existing MAF app that uses AMPA to MAF 2.3.1 with CDM. We recommend to perform this migration as soon as possible since Oracle A-Team will no longer maintain the AMPA open source project in GitHub. The migration steps are pretty straightforward and risk-free since the complete code base of AMPA has been integrated "as is" with MAF, the biggest change is the renaming of Java packages.

Main Article

If you are migrating from MAF 2.3.0, you need to decide whether you want to upgrade your existing JDeveloper 12.2.1 installation to MAF 2.3.1 or you prefer to install another fresh instance of JDeveloper 12.2.1 which allows you to run both MAF 2.3.0 and MAF 2.3.1 apps side by side.

See the article How do I install 2 versions of the same version of JDeveloper for more info.

If want to upgrade you need to perform the following steps after you installed the MAF 2.3.1 extension:

  • Upgrade the MAF JDK 1.8 Compact profile 2
  • Remove AMPA extension

If you do no want to upgrade, or you are coming from an older MAF version that required JDeveloper 12.1.3, you can start with a fresh install of JDeveloper 12.2.1 and install the MAF extension as documented here. You can then proceed with the migration steps:

  • Perform General Migration Steps (not AMPA specific)
  • Change Namespace in persistence-mapping.xml
  • Rename Java packages
  • Change AMPA EL Expressions
  • Change Reusable Feature Archive References
  • Configure Database to be Unencrypted

The next sections will explain all of these steps in detail. The last section will discuss the available CDM documentation.

Upgrade the MAF JDK 1.8 Compact Profile 2

When you install the MAF 2.3.1 extension over the MAF 2.3.0 extension, the MAF JDK 1.8 Compact Profile 2 is not updated automatically. Since the CDM functionality is added to MAF through new jar files that are not automatically added to this profile, JDeveloper will not be able to find the CDM classes. This will cause compilation errors like
package oracle.maf.api.cdm.persistence.model does not exist

Note that you will also get these errors when you create a new app using CDM, not just when migrating an AMPA app.

To fix this you need to upgrade the JDK profile as follows:

  • In JDeveloper, go to Tools > Manage Libraries
  • Click on the tab Java SE Definitions
  • Select the MAF JDK 1.8 Compact 2 Profile library and click the Remove button
  • Restart JDeveloper

The MAF JDK 1.8 Compact 2 Profile should now be re-added automatically with the correct jar files. Here is a screen shot of the correct profile definition:

profile

To test whether JDeveloper can find the CDM classes you can use Go to Java File option (Ctrl-Minus on Windows, Cmd-J on Mac) and enter InitDB in it. This should bring up the oracle.maf.impl.cdm.lifecycle.InitDbLifecyleListner class.

Remove AMPA Extension

To remove the AMPA extension from JDeveloper, you go to the Tools -> Features menu option. Then click on Installed Updates. Select the A-Team Mobile Persistence Accelerator and click the Uninstall button.

RemoveAMPA

This removes the AMPA extension registration and jar files. However, it does not remove the oracle.ateam.mobile.persistence folder in the jdeveloper/jdev/extensions folder.

RemoveAMPAFolder2

You can remove this folder manually.

Perform General Migration Steps (not AMPA specific)

General migration steps are documented in the MAF developer's guide, section Migration your Application to MAF 2.3.1. That section also includes a paragraph about migrating AMPA apps, this blog article is a more comprehensive version of that paragraph, with more background info, and some additional steps.

One general migration step is not documented there, the network access plugin has been renamed. If you open the maf-plugins.xml file, you will see that the network pluginId is now invalid:

NetworkPluginError

To fix this, you need to change the pluginId to maf-cordova-plugin-network-access. Or you can remove the network plugin line, go to the Overview tab of maf-application.xml and check the Network Access checkbox on the Plugins tab.

Change Namespace in persistence-mapping.xml

Open the persistence-mapping.xml, located in META-INF directory of your ApplicationController project and change the namespace to http://xmlns.oracle.com/adf/mf/amx/cdm/persistenceMapping.

namespace

Rename Java Packages

All non-deprecated AMPA classes have been included in MAF 2.3.1. MAF makes a distinction between public classes and internal implementation classes. Public classes are included in a package name starting with oracle.maf.api. Implementation classes are included in a package name starting with oracle.maf.impl. The signature of public classes is guaranteed to ensure upwards compatibility, implementation classes might change over time and might break your custom code if you use these classes and then migrate to a newer MAF version. This is why Oracle recommends to only use public MAF framework classes in your custom code. For this first release of CDM, the AMPA code has been included "as is" but over time the code base will be improved to support new features. To keep flexibility in improving and refactoring the code over time, a number of the AMPA classes have been moved into implementation packages starting with oracle.maf.impl.cdm. While Oracle generally recommends to avoid use of implemntation classes in your custom code, it is fine and even inevitable to do so with some of the CDM implementation classes. For example, all your service classes will now extend from oracle.maf.impl.cdm.persistence.service.EntityCRUDService.   

With this explanation, we are ready to rename the AMPA java packages. The table below lists the global search and replace actions you should perform in order on all files in your application.

Search Text Replace With
oracle.ateam.sample.mobile.v2.persistence.service.EntityCRUDService oracle.maf.impl.cdm.persistence.service.EntityCRUDService
oracle.ateam.sample.mobile.v2.persistence.manager.MCSStoragePersistenceManager oracle.maf.impl.cdm.persistence.manager.MCSStoragePersistenceManager
oracle.ateam.sample.mobile.v2 oracle.maf.api.cdm
oracle.ateam.sample.mobile.mcs.storage oracle.maf.api.cdm.mcs.storage
oracle.ateam.sample.mobile oracle.maf.impl.cdm

You can perform these global search and replace actions in JDeveloper by navigating to the Search -> Replace in Files option.

SearchReplace

Make sure you set the Scope field to your entire application, not just to one of the projects.

If you now try to compile your application, you still might get a few compilation errors. This is because classes in the same AMPA package might have been divided over both the implementation and public CDM packages. Easiest way to fix these errors is to double-click on the error to jump to the Java class, and rename the .api. part of the import to .impl. or vice versa. Alternatively, you can remove the invalid import statement and let JDeveloper automatically suggest the correct import.

There is one remaining change you have to make manually in maf-application.xml because this file is in a directory that is not scanned for global search and replace actions, you need to change the Lifecycle Event Listener property from oracle.ateam.sample.mobile.lifecycle.InitDBLifeCycleListener to oracle.maf.impl.cdm.lifecycle.InitDBLifeCycleListener. If you are using a custom lifecycle listener that extends InitDBLifecyleListener, you don't have to do anything because your custom class is already updated to point to the CDM package.

If your application compiles successfully, you can do a final check by doing a global search in your application on the string oracle.ateam.sample which should no longer return any hits.

Change AMPA EL Expressions

AMPA comes with some standard EL expressions around background tasks and pending data sync actions. To update these expressions for CDM you should perform the following global search and replace actions:

Search Text Replace With
applicationScope.ampa_bgtask_running applicationScope.maf_bgtask_running
applicationScope.ampa_hasDataSyncActions applicationScope.maf_hasDataSyncActions
applicationScope.ampa_dataSyncActionsCount applicationScope.maf_dataSyncActionsCount
applicationScope.[entityName]_hasDataSyncActions applicationScope.maf_hasDataSyncActions

The last entry in this table is applicable when you are migrating from an earlier AMPA release, not the latest 12.2.1.0.68 release. In previous releases, the data synchronization happened in the context of an Entity CRUD service, it only synchronized the data object of the entity CRUD service and its child data objects (if applicable). Therefore the expression to check whether an entity (data object) had pending data sync actions included the entity name as prefix instead of the general ampa_ prefix used in latest AMPA release.

Change Reusable Feature Archive References

AMPA shipped with two reusable feature archives to inspect web service calls and to view pending synchronization actions. While the web service calls feature is not yet documented in the CDM chapter, both feature archives are included with CDM. If you run the MAF User Interface Generator they wil be automatically added to your application, just like AMPA did.  If your existing AMPA application is using one or both of these features, you need to do two things:

  • Change the feature archive library reference
  • Change the feature reference in maf-application.xml

To change the library reference, go to Application -> Application Properties menu option, and click on the Libraries and Classpath option at the left.

FeatureArchives

Remove both jar files, and click the Add Jar/Library button. Navigate to the directory where the CDM feature archives can be found, which is jdeveloper/jdev/extensions/oracle.maf/FARs/CDM.

AddCDMFeatures

Select both jar files and click Open button to add them to the application.

Now, go to the Overview tab of maf-application.xml and update the invalid feature references oracle.ateam.sample.mobile.datasynch and oracle.ateam.sample.mobile.wscalls with the new CDM id's of these features.

NewFeatureRef

Configure Database to be Unencrypted

Unfortunately, during the integration of AMPA to CDM a minor code change has introduced an issue which currently prevents you from encrypting the SQLite database. This will be fixed with the next MAF release. For now, you should disable DB encryption by adding the following line to the mobile-persistence-config.properties file, located in the META-INF directory of tour ApplicationController project:

db.encryption=false

If you don't have this entry, or you change the value to true, your application will hang at application start up and the log will display the following error:

CDM Database key is null

MAF Client Data Model Documentation

The CDM chapter in the MAF developer's guide currently contains a subset of the information that you can find in the AMPA Developer's guide. Sections which refer to AMPA classes that ended up in the implementation packages (see previous section Rename Java Packages for more info) have not been include yet. In subsequent MAF releases the remaining documentation topics will be added once final decisions have been made about the location of all CDM classes and methods

For now, you can continue to consult the AMPA Developer's guide for those topics, because all of the content is still valid. Most notably, you might want to check out the following sections:

 

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