29 Reusing MAF Application Content with a Feature Archive File

This chapter introduces Feature Archive (FAR) files and describes how you can package application feature content into these files for reuse in one or more MAF applications.

This chapter includes the following sections:

29.1 Introduction to Feature Archive Files

A Feature Archive file is a JAR file that is packaged with application features for reuse by other MAF applications. A Feature Archive file contains components of application features, and it can be added as an application library or as a view controller project.

Application features, when packaged into a JAR file known as a Feature Archive file (FAR), provide reusable content that can be consumed by other MAF applications. A MAF application can consume one or more FAR files. A FAR file contains everything that an application feature requires, such as icon images, resource bundles, HTML files, JavaScript files, and other implementation-specific files.

A FAR also contains one maf-feature.xml file, which identifies each of the packaged application features by a unique ID. You can edit this file to update application feature properties, such as content implementation (MAF AMX, Local HTML, Remote URL), display properties based on such factors as user roles and privileges, or device properties.

You can either add a FAR as an application library or as a view controller project. You cannot customize the contents of a FAR when you add it as project library, nor can you reuse its individual artifacts. A MAF application consumes the FAR in its entirety when it is added as a library file. For example, the task flow of a FAR cannot be the target of a task flow call activity. Adding a FAR as a view controller project, however, enables you to customize its artifacts, as described in Customizing MAF Application Artifacts with MDS .

29.2 Using FAR Content in a MAF Application

An application feature is made available to a MAF application by adding it to the class path of the consuming application.

Note:

You can only add the FAR to the application controller project; you cannot add a FAR to the view controller project.

If the FAR defines a connection in the connections.xml file that is also defined in the consuming application’s connections.xml, no connections will be added to the consuming application and the FAR will not be added to the application.

Before you begin:

Deploy the application feature as a Feature Archive file, as described in How to Deploy the Feature Archive Deployment Profile.

How to add application feature content to a MAF application as a library:

  1. Open the Resources window, and click New, then IDE Connections, and then File System.

  2. Complete the File Systems Connection dialog to create a file connection to the directory that contains the Feature Archive JAR file. For more information, refer to the Oracle JDeveloper Online help.

  3. Right-click the Feature Archive file (which is noted as a JAR file) in the Resources window.

  4. Click Add to Application As, and then Library to add the classpath of the consuming application, as shown in Figure 29-1.

    Figure 29-1 Adding a FAR to a MAF Application as a Library

    This image is described in the surrounding text

    Tip:

    Click Remove Library from Application to remove the feature archive JAR from the classpath of the consuming application.

How to add a FAR as a view controller project:

  1. Open the Resources window and click New, then IDE Connections, and then File System.
  2. Complete the File Systems Connection dialog to create a file connection to the directory that contains the Feature Archive JAR file. For more information, refer to the Oracle JDeveloper Online help.
  3. Right-click the Feature Archive file (which is noted as a JAR file) in the Resources window.
  4. Click Add to Application As, and then ViewController Project as shown in Figure 29-2.

    Figure 29-2 Adding a FAR to a MAF Application as a View Controller Project

    This image is described in the surrounding text

29.3 What Happens When You Add a FAR as a Library

A FAR file can either be added manually to the classpath of the application, or features may be added to Resources to make them available to applications. Use the procedure to add or remove an application feature from the Resources window.

After you add a FAR as a library (or manually to the classpath of the application ):

  • The contents of the FAR display in the Application Resources under the Libraries node, as shown in Figure 29-3.

    Figure 29-3 The FAR JAR File in the Application Resources of the Consuming Application

    This image is described in the surrounding text
  • Every application feature declared in the maf-feature.xml files included in the JARs becomes available to the consuming application, as illustrated by Figure 29-4 where the drop-down list IDs of the available application features in the JAR in addition to the one that has already been defined in the application.

    Figure 29-4 Referencing the Application Features Defined in Various maf-feature.xml Files

    This image is described in the surrounding text

    Tip:

    Manually adding the Feature Archive JAR to the application classpath also results in the application features displaying in the Insert Feature Reference dialog.

    Alternatively, you can add or remove an application feature from the Resources window as follows:

    1. Expand the feature archive JAR in the Resources window.

    2. From the MAF Features folder, right-click an application feature.

    3. Choose Add Feature Reference to maf-application.xml, as shown in Figure 29-5, or Remove Feature Reference from maf-application.xml, shown in Figure 29-6. Figure 29-5 illustrates adding an application feature called People from MAF_DevGuideExample.jar.

      Figure 29-5 Adding a Feature Reference

      This image is described in the surrounding text

    Figure 29-6 illustrates removing an application feature reference from the maf-application.xml file.

    Figure 29-6 Removing a Feature Reference

    This image is described in the surrounding text

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

A FAR, when added as a view controller project, generates a view controller project, causes the creation of a connections.xml file, and includes .class and JAR files in the FAR available to the 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. Figure 29-7 illustrates how MAF creates a view controller project (a .jpr file) for an imported FAR file called StockTracker (which is illustrated as StockTrackerFAR.jar in Figure 29-2). This view controller project contains the default structure and metadata files of a MAF view controller project, as described in About the View Controller Project Resources. 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. See also What You May Need to Know About Enabling the Reuse of Feature Archive Resources.

    Figure 29-7 The Imported FAR as a View Controller Project within a MAF Application

    This image is described in the surrounding text
  • 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 connections.xml file of the consuming application. MAF will create a connections.xml file if one does not already exist in the target application.

  • 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:\jdeveloper\mywork\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.

    Note:

    Because the original resource bundles included in FAR might not be usable in the generated view controller project, you must create new resources bundles within the project as described in Enabling Customizations in Resource Bundles.

  • Like a FAR imported as a library, every application feature declared in the maf-feature.xml file of the FAR becomes available to the consuming application.

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

Resources of a FAR can be used by an application only if some conditions, such as a unique package hierarchy for the project, and unique package naming system for the feature reference IDs, are satisfied.

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 that 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. Instead of accepting the default names for these package directories, create a unique package hierarchy for the project. Use a similar package naming system for the feature reference IDs too.