11 Customizing MAF Application Artifacts with MDS

This chapter describes how to use Oracle Metadata Services (MDS) to customize MAF application-level artifacts.

This chapter includes the following sections:

• Introduction to Applying MDS Customizations to MAF Files

• Configuring Customization Layers

• Creating Customization Classes

• Consuming Customization Classes

• Understanding a Customization Developer Role

• Enabling Customizations in Resource Bundles

• Upgrading a MAF Application with Customizations

Introduction to Applying MDS Customizations to MAF Files

MDS can be used to adapt an application to different industries, locations, or user groups by means of rebranding, customization, and personalization.

Use Oracle Metadata Services (MDS) to re-brand, customize, and personalize a MAF application at design time. With MDS, an application adapts to different industries, locations, or user groups. For example, MDS can tailor the application look and feel to a user group or user responsibility.

A customized application contains a base application along with one or more layers of customization. Each layer can have multiple layer values. These layer values can be applied in a specified order, in terms of precedence, on top of the base metadata.

MAF supports the MDS seeded customization pattern. By defining layers of customization that are applied at design time, a general application is adapted to a particular group, such as a specific industry or a site. These seeded customizations exist as part of the deployed application, and persist for the life of a given deployment.

Use MDS to customize the following artifacts of a MAF application:

• The maf-feature.xml file

• The maf-skins.xml file

• The maf-application.xml file

• The maf-config.xml file

• MAF AMX files and metadata files (see Customizing MAF AMX Application Feature Artifacts).

Customizing MAF Applications with MDS

Customize a MAF application using MDS by defining global or application-specific customization layers, creating a customization class, and packaging it as a JAR file for JDeveloper to access. Use the procedure to customize a MAF application using MDS.

To customize a MAF application using MDS, perform the following:

1. Define one or more global or application-specific customization layers. See Configuring Customization Layers.

2. Create a customization class that MDS uses to determine which customization to apply to the base application. Each customization class defines a base customization layer. See Creating Customization Classes.

3. Enable JDeveloper design time to access the customization by packaging the customization class (a .java file) as a JAR file. Then add the JAR file to one of the projects of the MAF application. See Consuming Customization Classes .

4. Add the customization class to the cust-config section of the adf-config.xml file to register the customization classes in the order of precedence.

5. Launch JDeveloper in the Customization Developer role (or switch to that role). See Understanding a Customization Developer Role.

6. Modify the files as required. The changes are recorded by MDS in the mdssys directory of the ViewController project.

   Figure 11-1 ViewController Project

   
   Description of "Figure 11-1 ViewController Project "

7. Select the customization layer from the Customization Context window.

   Figure 11-2 Selecting the Customization Layer (Tip Layer)

   
   Description of "Figure 11-2 Selecting the Customization Layer (Tip Layer)"

   Note:

   When working in the Customization Developer role, the layer and layer value that you select in the Customization Context window is called the tip layer. The changes made while in the Customization Developer role are applied only to this layer.

8. Deploy the application to a device, emulator, or as a platform-specific application package. The Customization Developer role must be used to deploy a customized application, as follows:

   1. Launch the application in the Customization Developer role.

   2. In the Customization Context window, shown in Figure 11-2, select the layer and value for which you want to implement customizations.

   3. Click Application , and then click Deploy to select the deployment option and the deployment profile. See Deploying MAF Applications .

   4. Deploy each customization context separately.

   During deployment, the base file and the delta files are merged to create the customized version of the application at runtime. The deployed application has no MDS dependencies.

   Tip:

   To perform additional customization and upgrades, deploy the customized application as a MAF Application Archive (.maa) file, and then import it into an application. The delta files included in the .maa file are merged with the base files after deployment. See Upgrading a MAF Application with Customizations.

   When the customization process is complete, JDeveloper creates both a metadata file for the customizations and a subpackage to store them. The metadata file contains the customizations for the customized object, which are applied over the base metadata at runtime. JDeveloper gives the new metadata file the same name as the base file for the object, but includes an additional .xml extension, as illustrated by maf-feature.xml.xml in the figure.

   Figure 11-3 maf-feature.xml Metadata File

   
   Description of "Figure 11-3 maf-feature.xml Metadata File"

Configuring Customization Layers

Customize an application by specifying the customization layers and their values in the CustomizationLayerValues.xml file so that they are recognized by JDeveloper.

When you open a customizable application in the Customization Developer role, JDeveloper reads the adf-config.xml file to determine the customization classes to use and their order of precedence. JDeveloper also reads the CustomizationLayerValues.xml file to determine the layer values to make available in the Customization Context window. If there are layer values defined in the CustomizationLayerValues.xml file that are not defined in the customization classes listed in the adf-config.xml file, they are not displayed in the Customization Context window.

Therefore, you can have a comprehensive list of layer values for all of your customization projects in the CustomizationLayerValues.xml file, and only those appropriate for the current application are available in the Customization Context window. Conversely, you could have a comprehensive list of customization classes for a MAF application in the adf-config.xml file, and only the subset of layer values on which you would work in your CustomizationLayerValues.xml file.

Note:

At design time, JDeveloper retrieves customization layer values from the CustomizationLayerValues.xml file. However, at runtime the layer values are retrieved from the customization class.

The names of the layers and layer values that you enter in the CustomizationLayerValues.xml file must be consistent with those specified in your customization classes. The following example shows the contents of a sample CustomizationLayerValues.xml file.

<cust-layers  xmlns="http://xmlns.oracle.com/mds/dt">
   <cust-layer name="industry" id-prefix="i">
      <cust-layer-value value="financial"
                        display-name="Financial"
                        id-prefix="f"/>
      <cust-layer-value value="healthcare"
                        display-name="Healthcare"
                        id-prefix="h"/>
   </cust-layer>
   <cust-layer name="site" id-prefix="s">
      <cust-layer-value value="headquarters"
                        display-name="HQ"
                        id-prefix="hq"/>
      <cust-layer-value value="remoteoffices"
                        display-name="Remote"
                        id-prefix="rm"/>
   </cust-layer>
</cust-layers>

For each layer and layer value, you can add an id-prefix token. This helps to ensure the uniqueness of the id, so that customizations are applied accurately. When you add a new element during customization, JDeveloper adds the id-prefix of the layer and layer value (determined by the selected tip layer) to the auto-generated identifier for the element to create an id for the newly added element in the customization metadata file. In the preceding example, the site layer has an id-prefix of s and the headquarters layer value has an id-prefix of hq . Therefore, when you select site/headquarters as the tip layer and add an element, the id of that element will be set to shqel in the metadata customization file.

For each layer value, you can also add a display-name token to provide a human-readable name for the layer value. When you are working in the Customization Developer role, the value of the display-name token is shown in the Customization Context window for that layer value.

For each layer, you can optionally provide a value-set-size token that defines the size of the value set for the customization layer. This can be useful, for example, when using a design-time, application-specific CustomizationLayerValues.xml file. By setting value-set-size to no_values you can exclude runtime-only layers at design time.

<cust-layer name="runtime_only_layer" value-set-size="no_values"/>

You can either define the customization layer values globally for JDeveloper, or in an application-specific file. If you use an application-specific file, it takes precedence over the global file. For information on configuring layer values globally for JDeveloper, see How to Configure the Layer Values Globally. For information on configuring application-specific layer values, see Using the Studio Developer Role.

How to Configure the Layer Values Globally

Customization layer values are configured globally for JDeveloper in design time in the CustomizationLayerValues.xml file located in the jdev subdirectory of the JDeveloper installation directory. Use the procedure to configure design time customization layer values globally for JDeveloper.

Before you begin:

• Create your customization classes, as described in Creating Customization Classes.

• Make your classes available to JDeveloper, as described in Consuming Customization Classes .

To configure design time customization layer values globally for JDeveloper:

1. Open the CustomizationLayerValues.xml file located in the jdev subdirectory of your JDeveloper installation directory (jdev_install\jdev\CustomizationLayerValues.xml).
2. For each layer, enter a cust-layer element, as shown in the following example:

   <cust-layers xmlns="http://xmlns.oracle.com/mds/dt"> 
      <cust-layer name="company" id-prefix="c"> 
        <!-- Generated id-prefix would be "c1" and "c2" for values 
    "company1" and "company2".--> 
        <cust-layer-value value="company1" display-name="Acme Inc" 
    id-prefix="1"/> 
        <cust-layer-value value="company2" display-name="My Corp" id-prefix="2"/> 
        <!-- Generated id-prefix would be "s" for value "site" 
       since no prefix was specified on the value --> 
      </cust-layer> 
    </cust-layers>

3. For each layer value, enter a cust-layer-value element, as shown in the preceding example.
4. Save and close the CustomizationLayerValues.xmlfile.
5. After you have made changes to the global CustomizationLayerValues.xml file, restart JDeveloper.

Note:

For procedures to configure the CustomizationLayerValues.xml file for a specific application, see Using the Studio Developer Role and Using the Customization Developer Role.

How to Configure the Application-Level Layer Values

Application-level customization layer values can be configured using either the Studio Developer role or the Customization Developer role.

When configuring layer values for an application, you can use either the Studio Developer role (see Using the Studio Developer Role) or the Customization Developer role (see Using the Customization Developer Role). Note that when you configure an application-specific CustomizationLayerValues.xml file, you can create and modify layer values, but you cannot create additional customization layers. It is not necessary to restart JDeveloper to pick up changes made to the application-specific layer values.

When you create an application-specific CustomizationLayerValues.xml file, JDeveloper stores it in an application-level directory (for example, workspace-directory\.mds\dt\customizationLayerValues\CustomizationLayerValues.xml). You can access this file in the Application Resources window of the Applications window, under the MDS DT node.

Using the Studio Developer Role

After you have created customization classes that are available to JDeveloper, use the procedure to configure the CustomizationLayerValues.xml file for a specific application from the Studio Developer role.

The following procedure describes how to configure the CustomizationLayerValues.xml file for a specific application from the Studio Developer role.

Before you begin:

• Create your customization classes, as described in Creating Customization Classes

• Make your classes available to JDeveloper, as described in Consuming Customization Classes

To configure design-time customization layer values at the workspace level from the Studio Developer role:

1. In the Application Resources window, expand the Descriptors > ADF META-INF node, and then double-click adf-config.xml.
2. In the Overview editor, click the MDS Configuration navigation tab.
3. On the MDS Configuration page, below the table of customization classes, click Configure Design Time Customization Layer Values to open the workspace-level CustomizationLayerValues.xml file in the Source editor.

   Note:

   If the override file does not exist, JDeveloper displays a confirmation dialog. Click Yes to create and open a copy of the global file.

4. In the file, specify layer values as necessary, as described in Configuring Customization Layers.
5. Save your changes.

Using the Customization Developer Role

After you have created customization classes and made them available to JDeveloper, use the procedure to configure the CustomizationLayerValues.xml file for a specific application from the Customization Developer role.

The following procedure describes how to configure the CustomizationLayerValues.xml file for a specific application from the Customization Developer role.

Before you begin:

• Create your customization classes, as described in Creating Customization Classes

• Make your classes available to JDeveloper, as described in Consuming Customization Classes

To configure design-time customization layer values at the workspace level from the Customization Developer role:

1. In the Customization Context window, click Configure application layer values to open the CustomizationLayerValues.xml file in the Source editor.

   Note:

   If the override file does not exist, JDeveloper displays a confirmation dialog. Click Yes to create and open a copy of the global file.

2. In the file, specify layer values as necessary, as described in Configuring Customization Layers.
3. Save your changes.

After you make changes to the application-specific CustomizationLayerValues.xml file while you are in the Customization Developer role, any tip layer you have selected in the Customization Context window is deselected. You can then select the desired tip layer.

Creating Customization Classes

Customizations are used to adapt a MAF application for a specific industry domain. Create a Java application for the customization class, complete the Java class, import it into the MAF application, and then use the procedure to create a customization class.

A customization class is a POJO class that extends oracle.mds.cust.CustomizationClass. It evaluates the current context and returns a String result. This String result is used to locate the customization layer.

The customization class provides the following information:

• A name that represents the name of the layer.

• An IDPrefix, for objects created in the layer. When new objects are created in a customization layer, they need a unique ID. The IDPrefix is added to the auto-generated identifier for the object to create an ID for the newly added object. Each layer needs a unique IDPrefix so that objects created at different customization layers have unique IDs.

• A cache hint (CacheHint), for the layer defined by the customization class. In MAF, the cache hint defines a static customization layer and the getCacheHint method always returns ALL_USERS which means the customization is applied globally (unconditionally) for a given deployment.

Note:

Since customization classes are likely to be executed frequently, once for each document being accessed to get the layer name and layer value, you must ensure their efficiency.

Customizations can be used to tailor a MAF application to suit a specific industry domain (verticalization). Every such domain denotes a customization layer and is depicted using a customization class.

Static customizations have only one layer value, in effect, for all executions of the application. A static customization has the same value for all users executing the application.

In the customization class used in a MAF application, the getCacheHint method always returns ALL_USERS meaning that the customization layer is always static.

All objects could have a static customization layer, depending on how the customization classes are implemented.

Do not create the customization file in the MAF application that you plan to customize. Instead, create a separate Java application for the customization class. After you complete the Java class, import it into the MAF application to be customized.

To create a customization class:

1. Create a Java application.

2. On the File menu, click New, and then Project.

3. In New Gallery, select Java Application Project, and then complete the wizard.

4. In the Applications window, right-click the Java application project, and then select Project Properties.

5. In the Project Properties dialog, select Libraries and Classpath, and then click Add Library.

6. In the Add Library dialog, select MDS Runtime and then click OK. Click OK to close the Project Properties dialog.

7. In the Applications window, right-click the Java application project and then select New and then Java Class.

8. In the Create Java Class dialog, enter the name of the class and package.

9. In the Extends field, browse the class hierarchy and retrieve oracle.mds.cust.CustomizationClass, as shown in the figure, and then click OK.

   Note:

   Implement Abstract Methods (the default setting) must be selected in the Create Java Class dialog.

   Figure 11-4 Creating the Customization Class

   
   Description of "Figure 11-4 Creating the Customization Class"

10. Update the stub file. The following example illustrates a customization class.

    package mobile;
    import java.io.IOException;
    import java.io.InputStream;
    import java.util.Properties;
    import oracle.mds.core.MetadataObject;
    import oracle.mds.core.RestrictedSession;
    import oracle.mds.cust.CacheHint;
    import oracle.mds.cust.CustomizationClass;
     
    public class SiteCC extends CustomizationClass { 
     
       public SiteCC() { 
             super(); 
         } 
     
         public CacheHint getCacheHint() 
            { 
                return CacheHint.ALL_USERS; 
            } 
     
     
            /** {@inheritDoc} */ 
            public String getName() 
            { 
     
                return "company"; 
            } 
     
     
            /** {@inheritDoc} */ 
            public String[] getValue(RestrictedSession rs, 
                                     MetadataObject metadataObject) 
            { 
                String sites[] = {"company1", "company2"}; 
                return sites; 
            } 
     } 

11. Rebuild the Java application project.

Consuming Customization Classes

Customization classes that have been created are available at design time in the Customization Developer role, and at runtime in the application. Use the procedures to add customization classes to a JAR, register the customization class with the MAF application, and to identify customization classes in the adf-config.xml file.

Customization classes are reusable components. Create a separate project to store them, and package them in their own JAR file. To make the customization classes available to JDeveloper, import the JAR into the consuming application.

Package the customization class as a JAR file, and then register the class with the MAF application. To package the customization class and any related artifacts into a JAR file, create a deployment profile using the Create Deployment Profile wizard. See About Automatically Generated Deployment Profiles.

To add customization classes to a JAR:

1. In the Applications window, right-click the Java application project and select New, and then From Gallery.

2. In New Gallery, expand General, select Deployment Profiles, then select JAR File, and click OK.

   Tip:

   Click the All Features tab if the Deployment Profiles node does not appear in the Categories tree.

3. In the Create Deployment Profile -- JAR File dialog, enter a name for the project deployment profile (for example, SiteCC in the figure) and then click OK.

   Figure 11-5 Creating the Deployment Profile for the Customization Class

   
   Description of "Figure 11-5 Creating the Deployment Profile for the Customization Class"

4. In the Edit JAR Deployment Profile Properties dialog, select JAR Options.

5. If needed, enter a location for the JAR file. Otherwise, accept the default location.

6. Expand Files Groups, then Project Output, and then Filters to list the files that can be selected to be included in the JAR.

7. On the Filters page, under the Files tab, select the customization classes that you want to add to the JAR file.

   Figure 11-6 Including the Customization Class in the JAR File

   
   Description of "Figure 11-6 Including the Customization Class in the JAR File"

8. Click OK to exit the Edit JAR Deployment Profile Properties dialog.

9. Click OK again to exit the Project Properties dialog.

10. In the Applications window, right-click the Java application project and then select the deployment profile. On the Deployment Action page, Deploy to JAR file is selected by default. Click Next.

    Figure 11-7 Deploying the Customization Class to a JAR File

    
    Description of "Figure 11-7 Deploying the Customization Class to a JAR File"

11. Review the confirmation for the output location of the JAR file. Click OK.

    Figure 11-8 Summary Page (Showing the Output Location for the JAR File)

    
    Description of "Figure 11-8 Summary Page (Showing the Output Location for the JAR File)"

    The log file window, shown in the figure below, displays the status of the deployment.

    Figure 11-9 Deployment Log

    
    Description of "Figure 11-9 Deployment Log"

Use the following procedure to make the customization classes visible to the application, and then add the customization classes to the cust-config section of the adf-config.xml file.

Note:

The following procedure is not required if you had created your customization classes in the data model project of the consuming application.

Before you begin:

• Create your customization classes in an external project.

• Create a JAR file that includes the customization classes.

• Launch JDeveloper using the Studio Developer role, and open the application that you want to customize.

To register the customization class with the MAF application:

1. In the Applications window, click the Application Menu icon and select Application Properties.

2. In the Application Properties dialog, select Libraries and Classpath, and click Add JAR/Directory.

3. In the Add Archive or Directory dialog, select the JAR file you created that contains the customization classes, and click Open.

4. Click OK.

The next step is to add the customization class to the adf-config.xml file. The adf-config.xml file of the application must have an appropriate cust-config element in the mds-config section. The cust-config element allows clients to define an ordered and named list of customization classes. Use the Overview editor for the adf-config.xml file to add customization classes (see Figure 11-10).

To identify customization classes in the adf-config.xml file:

1. In the Application Resources window, expand the Descriptors and ADF META-INF nodes, and then double-click adf-config.xml.

2. In the Overview editor, select MDS navigation tab and then click Add ( + ).

3. In the Edit Customization Class dialog, search for or navigate to the customization classes you have already created.

4. Select the appropriate classes and click OK.

5. After you have added all of the customization classes, you can use the arrow icons to arrange them in the appropriate order.

The figure shows the Overview editor for the adf-config.xml file with two customization classes added.

Figure 11-10 adf-config.xml Overview Editor

Description of "Figure 11-10 adf-config.xml Overview Editor"

The order of the customization-class elements defines the precedence of customization layers. For example, in the following code that represents the customization class order in the adf-config.xml file, the IndustryCC class is listed before the SiteCC class. This means that customizations at the industry layer are applied to the base application, and then customizations at the site layer are applied.

<adf-config xmlns="http://xmlns.oracle.com/adf/config"> 
   <adf-mds-config xmlns="http://xmlns.oracle.com/adf/mds/config"> 
      <mds-config xmlns="http://xmlns.oracle.com/mds/config" version="11.1.1.000">
         <cust-config> 
            <match path="/">
               <customization-class name="com.mycompany.IndustryCC"/>
               <customization-class name="com.mycompany.SiteCC"/>
            </match> 
         </cust-config>
      </mds-config>
   </adf-mds-config>
</adf-config>

Upon completion, the customization classes are available to JDeveloper for customization and for running your project locally in JDeveloper. The customization classes will also be packaged to the EAR class path when you package the application.

Understanding a Customization Developer Role

Customization features are available only in the Customization Developer role that is used to customize the metadata in a project.

In JDeveloper, the Customization Developer role is used to customize the metadata in a project. Customization features are available only in this role. When working in a Customization Developer role, you can do the following:

• Create and update customizations.

• Select and edit the tip layer of a customized application.

• Remove existing customizations.

When you use JDeveloper in the Customization Developer role, the Source editor is read-only and the following JDeveloper features are disabled:

• Workspace migration.

• Creation, deletion, and modification of application and IDE connections. You must configure connections in the Default role before opening an application in Customization Developer role.

When working with an application in the Customization Developer role, new objects and files cannot be created, and noncustomizable objects cannot be modified. In addition, you cannot edit noncustomizable files, such as Java classes, resource bundles, security policies, deployment descriptors, and configuration files.

Note:

When you are working in the Customization Developer role, noncustomizable files are indicated by a lock icon .

You are also restricted from modifying project settings, and you cannot refactor or make changes to customizable files that would, in turn, necessitate changes in noncustomizable files.

See the Working with JDeveloper Roles in Developing Applications with Oracle JDeveloper.

How to Switch to the Customization Developer Role in JDeveloper

Users who did not select the Customization Developer role when starting JDeveloper can follow the given steps to switch to the role even after JDeveloper has been started.

The customization features of JDeveloper are available to you in the Customization Developer role. To work in this role, you can either select it when you start JDeveloper or, if JDeveloper is already running, you can use the Switch Roles menu to switch to the Customization Developer role.

To switch to the Customization Developer role in JDeveloper:

From the main menu in JDeveloper, select Tools, then Switch Roles, and then Customization Developer.

Optionally, you can select Tools, and then Switch Roles to toggle the Always Prompt for Role Selection at Startup menu to specify whether or not you want to select the role when JDeveloper is launched. If deselected, JDeveloper launches in the role in which it was last closed.

What You May Need to Know About the Tip Layer

Changes made by users in the Customization Developer role are applied to the tip layer, the combination of the layer and layer value that is selected in the Customization Context window.

When working in the Customization Developer role, the layer and layer value combination that is selected in the Customization Context window is called the tip layer. The changes you make while in the Customization Developer role are applied to this layer.

Note:

When working in the Customization Developer role, if the Customization Context window is not displayed, you can access it from the JDeveloper Window menu.

The metadata displayed in the JDeveloper editors is a combination of the base metadata and the customization layers up to and including the tip layer, according to the precedence set in adf-config.xml, with the values specified in the Customization Context window for each layer.

When working in the Customization Developer role, you can also see the noncustomized state of the application. When you select View without Customizations in the Customization Context window, there is no current tip layer. Therefore, what you see is the noncustomized state. While you are in this view, all customizable files show the lock icon (in the Applications window), indicating that these files are read-only.

When you make customizations in a tip layer, these customizations are indicated by an orange icon in the Properties window. A green icon indicates non-tip layer customizations. When you see an orange icon beside a property, you have the option of deleting that customization by selecting Remove Customization from the drop-down menu for that property.

Enabling Customizations in Resource Bundles

In the Studio Developer role, create an application resource bundle or a project resource bundle, and then edit it to customize it.

To implement customization for resource keys, you must create additional resource bundle files (You cannot use the base resource bundle file.).

In the Studio Developer role, create one of the following:

• An application resource bundle (see How to Create an Application Resource Bundle).

• A project resource bundle (see How to Create a Project Resource Bundle).

Edit the bundle that you create to define string values for resource keys.

Before you begin:

See How to Use Multiple Resource Bundles in Developing Fusion Web Applications with Oracle Application Development Framework.

How to Create an Application Resource Bundle

In the Studio Developer role, use the procedure to create an application resource bundle from the Resource Bundle page.

To create an application resource bundle:

1. In the Studio Developer role, click Application, then Application Properties, and then Resource Bundles.
2. In the Resource Bundles page, click Application Bundle Search, then click the drop-down menu icon to the right of the Add bundle icon and select Create Application Bundle.

   Figure 11-11 Creating an Application Resource Bundle

   
   Description of "Figure 11-11 Creating an Application Resource Bundle"
3. In the Create Xliff File dialog that appears, enter a name for the resource bundle and click OK.
4. Edit the resource bundle, as described in Editing Resources in Resource Bundles.

   Note:

   MAF does not support the Overridden property in the application-level Resource Bundle page.

5. In the Customization Developer role, open the Select Text Resource dialog and select from among the resource bundles that contain the appropriate string. Because you cannot change strings or create new ones in the Customization Developer role, you can only select from the strings in the selected bundle.

   Note:

   Do not select strings from the base resource bundle in the Customization Developer role, as doing so may cause problems when upgrading the application.

How to Create a Project Resource Bundle

Use the procedure to create a project resource bundle by selecting the General XML option from the New Gallery menu.

To create a project resource bundle:

1. In the Studio Developer role, right-click the project where you want to create the resource bundle and select New, then From Gallery, followed by General XML, and XML Localization File (XLIFF).

2. In the Create Xliff File dialog that appears, enter a name for the resource bundle and click OK.

3. Edit the resource bundle, as described in Editing Resources in Resource Bundles.

4. In the Bundle Search tab of the Resource Bundle page, register the resource bundle by selecting a project (.jpr) file.

   Figure 11-12 Selecting a Resource Bundle

   
   Description of "Figure 11-12 Selecting a Resource Bundle"

   Registering a resource bundle includes it in the Select Text Resource dialog, shown in the figure below.

   Figure 11-13 Selecting a Resource Bundle for a Text Resource

   
   Description of "Figure 11-13 Selecting a Resource Bundle for a Text Resource"

5. Use the Select Text Resource dialog to define the key as follows:

   1. Select the bundle from the Resource Bundle drop-down list.

      The dialog displays the strings that are currently defined in the selected resource bundle.

   2. Enter a new string and then click Save and Select.

      JDeveloper writes the string to the selected resource bundle.

6. In the Customization Developer role, open the Select Text Resource dialog and select from among the resource bundles that contain the appropriate string. Because you cannot change strings or create new ones in the Customization Developer role, you can only select from the strings in the selected bundle.

   Note:

   Do not select strings from the base resource bundle in the Customization Developer role, as doing so may cause problems when upgrading the application.

Upgrading a MAF Application with Customizations

Use the procedure to use the Upgrade Mobile Application from Archive wizard and upgrade an application to a higher version while retaining the customizations.

Customizations are upgrade-safe because they are saved separately from the base applications. Because customizations retain changes, they enable you to upgrade an application by applying these changes to newer versions of the application. The MAF Application Archive (.maa) file provides the mechanism for upgrading MAF applications. When you create an application from an .maa file, you can upgrade the application using an updated version of the .maa file.

Using the Upgrade Mobile Application from Archive wizard, you can upgrade an application to a higher version while retaining the customizations made prior to the upgrade.

Before you begin:

You may want to familiarize yourself with the MAF Application Archive (.maa) file. See Creating a Mobile Application Archive File and Creating a New Application from an Application Archive.

Ensure that the application that is packaged into the .maa file and used for the upgrade has the same application ID as the application to which it will be applied. It must also have a higher version number than the application targeted for the upgrade.

To upgrade a MAF application:

1. Create a MAF application from an .maa file.

2. Apply customization to the MAF application, as described in Enabling Customizations in Resource Bundles.

3. Click Application, and then select Select Mobile Application from Archive.

4. Browse to and select the .maa file. The wizard discontinues the upgrade if the application packaged in the .maa has the same (or lower) version number than the current application, or a different application ID.

   Figure 11-14 Selecting the .maa File

   
   Description of "Figure 11-14 Selecting the .maa File"

5. Review the Summary page for files that require a manual merge. As shown in the figure below, MAF saves the initial version (Version 1) of the application in the Temp directory. The Summary page also notes the temporary location of the log files.

   Figure 11-15 Application Upgrade Information

   
   Description of "Figure 11-15 Application Upgrade Information"

6. If the upgrade completes successfully, restart JDeveloper. JDeveloper notifies you if different versions of a configuration file require reconciliation.

   Figure 11-16 Manual Merge Notification

   
   Description of "Figure 11-16 Manual Merge Notification"

During the upgrade, MAF copies a set of files that cannot be customized for both Version 1 of the application and Version 2 (the upgraded version of the application). These files include the connections.xml and adf-config.xml files. If MAF detects differences between Version 1 and Version 2 connections.xml and adf-config.xml files, it retains both copies of these files and writes an entry to the merge log file. MAF differentiates Version 1 by appending a version number to the file name if version numbers exist. If version numbers do not exist, MAF adds _old to the file name, as illustrated by connections_old.xml in Figure 11-16. If needed, you can manually merge the differences into the new version. As shown in the figure, MAF places the merge file log in the temporary location noted in the Summary page. MAF names the files as workspace name_timestamp.

Figure 11-17 The Merge Log File

Description of "Figure 11-17 The Merge Log File"

What Happens in JDeveloper When You Upgrade Applications

When an application is upgraded with the Upgrade Mobile Application from Archive wizard, JDeveloper saves, imports, copies, and updates relevant files.

In addition to copying Version 1 to the Temp directory and creating Version 1 and Version 2 copies of the non-upgradable configuration files, MAF also performs the following when you upgrade an application using the Upgrade Mobile Application from Archive wizard:

• Saves the libraries and resource bundles settings for each project in a map keyed with the project file name.

• Saves the resource bundle settings for the workspace.

• Saves the registered customization class in the adf-config.xml file.

• Imports the Version 2 .maa file to the temporary directory.

• Copies the application from the .maa file used for the upgrade to Version 1.

• Updates each Version 2 project (.jpr) file with the registered resource bundle and library dependency map. The new version of the library overrides the previous version. However, the Version 1 library remains unchanged if it shares the same name as the library used in Version 1.

• Updates the Version 2 workspace (.jws) file with the registered resource bundle settings.

• Updates the Version 2 adf-config.xml file to register the customization class.

What You May Need to Know About Upgrading FARs

A FAR file that was not included in the .maa file that was used to create or upgrade an application must be upgraded separately, by itself.

If the application includes a FAR file that was not packaged in the original .maa file that was used to create the application (or included in the .maa file that is used to upgrade the application), then you must upgrade the FAR file separately. For example, you can create an application from a .maa file, add a FAR file, and then perform customization. You can upgrade the application to use a newer version of the FAR by adding the updated FAR from the Resources window as described in Using FAR Content in a MAF Application.