9 Reusing the MAF Application Content

This chapter describes using the MAF Application Editor and MAF Features Editor to define the display behavior of the mobile application's springboard and navigation bar and how to designate content by embedding application features.

This chapter includes the following sections:

Section 9.1, "Working with Feature Archive Files"
Section 9.2, "What Happens When You Add a FAR as a View Controller Project"
Section 9.3, "What You May Need to Know About Enabling the Reuse of Feature Archive Resources"

9.1 Working with Feature Archive Files

The MAF Application Editor references at least one application feature. These application features, when packaged into a JAR file known as a Feature Archive file (FAR), provide the reusable content that can be consumed by other mobile applications. A FAR is essentially a self-contained collection of everything that an application feature requires, such as icon images, resource bundles, HTML files, JavaScript files, or other implementation-specific files. A mobile application can reference one FAR, several of them, or none at all.

You can add a FAR to a MAF application using the MAF Application editor. Once added, the features it contains are available for referencing. Unless you reference them, the FAR features are not used. When referenced, any connections that the FAR uses must be set in the consuming application. You cannot customize the FAR's contents, nor can you reuse its individual artifacts. A mobile application consumes the FAR in its entirety. For example, a FAR's task flow cannot be the target of a task flow call activity.

Note:

If the feature archive contains an AMX page that uses Geographic Map, you need to set a number of properties in the application's adf-config.xml file. See Section 13.5.18.1, "Configuring Geographic Map Components With the Map Provider Information."

9.1.1 Importing a FAR as an Application Library

You can import a FAR as an application library to make its features accessible to your MAF application.

To import a FAR as an application library:

In the Project Explorer, expand the folder for the top-level assembly project, then expand the MAF folder.
Double-click MAF Application Editor to open it.
Right-click on the Feature Archives folder and choose New > Feature Archive.
Click the Browse button for the URI field to open the Mobile Feature Archive Location dialog, then type in the URI at which the FAR can be located. Oracle Enterprise Pack for Eclipse verifies that the selected file contains feature definitions, and that the location is accessible.
When you have specified the URI and Oracle Enterprise Pack for Eclipse has verified it, click OK.

9.1.2 What You May Need to Know About Using a FAR to Update the sync-config.xml File

The sync-config.xml file enables the mobile application to not only cache the data retrieved from server-side resources accessed through various types of web services (SOAP, or REST with JSON payloads) to the embedded SQLite database, but also enables the application to update this data within the cache and to the server-side resource.

The sync-config.xml file is included in the Feature Archive file when the view controller project is deployed as a FAR. Like the connections.xml file, MAF merges the contents of the sync-config.xml file in the FAR (jar-sync-config.xml) with those of the consuming application's sync-config.xml file after you add the FAR to the application. Because the sync-config.xml file describes the web service endpoints used by the mobile application, you can update the endpoints for all of the web services used by the application features that comprise a mobile application by adding a FAR.

After you add the FAR to the application, MAF logs messages that prompt you to verify and, if needed, modify the application's sync-config.xml and connections.xml files. As illustrated in Figure 9-1, these messages reflect the state of the sync-config.xml file in the consuming application.

Figure 9-1 The Messages Log

This image is described in the surrounding text

If the consuming application lacks the sync-config.xml file, then MAF adds the file to the application and writes a message similar to the following:

oracle.adfmf.framework.dt.deploy.features.deployers.SyncConfigMerger _logNoSyncConfigInAppUsingFar

WARNING: The application does not contain a synchronization file, "sync-config.xml". Creating one containing the synchronization configuration in the Feature Archive.

MAF writes a log message similar to the following that requests that you verify (or create) a connection if the sync-config.xml file's <ServerGroup> elements do not have corresponding <Reference> elements defined in the consuming application's connections.xml file:

oracle.adfmf.framework.dt.deploy.features.deployers.SyncConfigMerger _logAddedServerGroups

WARNING: The following server groups were added sync-config.xml by the Add to Application operation:{ ServerGroup1 - there is no existing application connection defined for this server group. Please create the connection. ServerGroup2 - verify its configuration.}

If the <ServerGroup> definitions in the consuming application's config-sync.xml file duplicate those of the counterpart config-sync.xml file included in the FAR, then MAF writes the following SEVERE-level message to the log:

oracle.adfmf.framework.dt.deploy.features.deployers.SyncConfigMerger _logDuplicateServerGroups

SEVERE: Cannot merge the server groups from the Feature Archive because the following definitions already exist:

ServerGroup1

ServerGroup2

9.2 What Happens When You Add a FAR as a View Controller Project

When you add a FAR as a view controller project:

MAF generates a view controller project that bears the same name as the imported FAR. This view controller project contains the default structure and metadata files of a MAF view controller project. In particular, the FAR view controller project includes the maf-feature.xml file. If the MAF application contains other view controller projects, you must ensure that none of these projects include application features with the same ID.
As with a FAR imported as a library, the information in the connections.xml file located in the Feature Archive JAR is merged into the consuming application's connections.xml file. MAF will create a connections.xml file if one does not already exist in the target application. Likewise, the sync-config.xml file is merged into the consuming applications's sync-config.xml file.
MAF makes any .class and JAR files included in the FAR available as a library to the view controller project by copying them into its lib directory (such as C:\workspace\application\FAR view controller project\lib). MAF compiles these files into a file called classesFromFar.jar.
Unlike a FAR imported as a library, you can customize the files of a view controller project.
Like a FAR imported as a library, every application feature declared in the FAR's maf-feature.xml file becomes available to the consuming application.

9.3 What You May Need to Know About Enabling the Reuse of Feature Archive Resources

To ensure that the resources of a FAR can be used by an application, both the name of the FAR and its feature reference IDs must be globally unique; ensure there are no duplicate feature reference IDs in the maf-application.xml file. Within the FAR itself, the DataControl.dcx file must be in a unique package directory. Rather than accepting the default names for these package directories, you should instead create a unique package hierarchy for the project. You should likewise use a similar package naming system for the feature reference IDs.