3 Getting Started with Mobile Application Development

3.2.1 How to Create a Workspace for a Mobile Application

You create an application using the application creation wizard.

Before you begin:

You must download the MAF application extension. For more information, see Section 2.3, "Setting Up JDeveloper." You may need to download and configure the MAF application extension for all target platforms.

To create a mobile application:

1. Choose File, then New, and then Application.

   Figure 3-1 Selecting the MAF Application Template

   
   

2. In the New Gallery, shown in Figure 3-1, choose Mobile Application Framework and click OK.

3. In the Application Name field, enter a name for the application, such as MobileApplication in Figure 3-2. If needed, enter a new location for the project in the Directory field. Make sure that the application package is unique by entering a prefix for it in the Application Package Prefix field. Click Next.

   The application is the top-level structure of the MAF application. It organizes the different tiers of projects that you define in the subsequent pages of this wizard.

   Figure 3-2 Naming the MAF Application

   
   

4. In the Project 1 Name page, change the name and location of the application controller project (if needed), as shown in Figure 3-3. Otherwise, accept the default name of the project, ApplicationController. This Project Feature window of the page lists the technologies available to the application controller project.

   This project stores all of the application-wide resources. For more information, see Table 3-1.

   Figure 3-3 Application Controller Project and Its Project Features

   
   

5. Click Next to go to the Java Settings page for the application controller project (Project 1 Java Settings, shown in Figure 3-4). Accept, or change, the default package name for the application controller project (application) and the location for the Java SOURCEPATH directory (src) and the Java output directory (classes).

   Figure 3-4 Configuring the Java Settings for the Application Controller Project

   
   

6. Click Next to go to the Project 2 Name page, where you can, if needed, rename the view controller project. The page's Project Features window, shown in Figure 3-5, lists the technologies available to the MAF view controller project. For information on the artifacts created within the view controller project, see Table 3-2.

   Figure 3-5 MAF View Controller Project

   
   

7. Click Next. In the Java settings page for the view controller project, shown in Figure 3-6, accept (or change) the default package name for the application controller project (mobile), the location for the project's Java SOURCEPATH directory (src) and the Java output directory (classes).

   Figure 3-6 Java Settings for the View Controller Project

   
   

8. Click Finish to complete the creation of the MAF application and its projects.

3.2.2 What Happens When You Create a MAF Application

After you create a MAF application project, JDeveloper adds application-level and project-level artifacts, which you access from the Applications window shown in Figure 3-7. These artifacts include two stub descriptor files: one used for configuring the MAF application itself, such as its name, the application lifecycle listener (LifeCycleListenerImpl.java), the login server connections for the embedded application features, and another that describes which application features comprise the MAF application. These files, which are called maf-application.xml and maf-feature.xml, are described in Section 3.2.2.1, "About the Application Controller Project-Level Resources" and Section 3.2.2.2, "About the View Controller Project Resources," respectively.

JDeveloper also creates the DeviceFeatures data control. The Apache Cordova Java API is abstracted through this data control, thus enabling the application features implemented as MAF AMX to access various services embedded on the device. JDeveloper also creates the ApplicationFeatures data control, which enables you to build a springboard page. By dragging and dropping the operations provided by the DeviceFeatures data control into a MAF AMX page (which is described in Section 7.11, "Using the DeviceFeatures Data Control"), you add functions to manage the user contacts stored on the device, create and send both e-mail and SMS text messages, ascertain the location of the device, use the device's camera, and retrieve images stored in the device's file system.

Figure 3-7 JDeveloper-Generated MAF Application Artifacts

3.2.2.1 About the Application Controller Project-Level Resources

JDeveloper generates the files for the MAF application in the application controller project. These files, described in Table 3-1, contain configuration information describing the metadata of the MAF application. You access these files from the Application Resources pane of the Applications window, shown in Figure 3-8.

Figure 3-8 Mobile Application Artifacts Accessed from the Application Resources Pane

The application controller project, which contains the application-wide resources, provides the presentation layer of the MAF application in that it includes metadata files for configuring how the application will display on a mobile device. This project dictates the security for the MAF application and can include the application's login page, an application-wide resource. The application controller project is essentially a consumer of the view controller project, which defines the application features and their content. For more information, see Section 3.2.2.2, "About the View Controller Project Resources."

Tip:

Place code that supports application-wide functionality, such as an application-level lifecycle listener, in the application controller project.

Table 3-1 Mobile Application-Level Artifacts Accessed Through Application Resources

Artifact(s)	File Location	Description
maf-application.xml	application workspace directory\.adf\Meta-INF For example: JDevloper\mywork\application name\.adf\META-INF	An XML file that defines application-level information. You can define the content for an application, its navigation behavior, and its user authentication requirements. For more information, see Section 4.2, "About the Mobile Application Configuration File."
maf-config.xml	application workspace directory\.adf\Meta-INF For example: JDeveloper\mywork\application name\.adf\META-INF	Use to configure the default skin used for MAF applications. For more information, see Section 4.12, "Skinning Mobile Applications."
Application images	application workspace directory\Application Resources\resources\ios For example: JDeveloper\mywork\application name\resources\ios	A set of images required for the deployment of iOS and Android applications. These include PNG images for application icons and splash screens. Deployment to an iOS-powered device, such as an iPhone, requires a set of images in varying sizes. The default iOS images provided with the project include: images used when the device is in both landscape and portrait orientations images used for retina displays (that is, icon.png and icon@2x.png) an iPad image (icon-72.png) To override these images, see Section 19.2.4.3, "Adding a Custom Image to an iOS Application."
cacerts	application workspace directory\Application Resources\resources\Security\cacerts For example: JDeveloper\mywork\application name\resources\Security\cacerts	The cacerts certificate file, a system-wide keystore that identifies the CA certificates to JVM 1.4. You can update this file using the Java keytool utility. You can create a custom certificate file using keytool as described in Section 21.8, "Supporting SSL." Any certificate file must reside within the Security directory.
logging.properties	application workspace directory\ src\.META-INF\logging.properties For example: JDeveloper\mywork\application name\src\META-INF\logging.properties	Enables you to set the application error logging, such as the logging level and logging console. For more information, see Section 22.4, "Using and Configuring Logging."
cvm.properties	application workspace directory\src\.META-INF\cvm.properties For example: JDeveloper\mywork\application name\src\META-INF\cvm.properties	The configuration file for the Java virtual machine, JVM 1.4. Use this file to configure the application startup and heap space allotment, as well as Java and JavaScript debugging options. For more information, see Section 22.3.5, "How to Enable Debugging of Java Code and JavaScript."
adf-config.xml	application workspace directory\.adf\META-INF For example: JDeveloper\mywork\application\.adf\META-INF	Used to configure application-level settings, including the Configuration Service parameters. See also Chapter 9, "Configuring End Points Used in MAF Applications."
connections.xml	application workspace directory\.adf\META-INF For example: JDeveloper\mywork\application name\.adf\META-INF	The repository for all of the connections defined in the MAF application.
wsm-assembly.xml	application workspace directory\.adf\META-INF For example: JDeveloper\mywork\application name\.adf\META-INF	Stores the web service policy definitions used for secured web services.

Within the application controller project itself, shown in Figure 3-9, JDeveloper creates the following artifacts, listed in Table 3-2.

Figure 3-9 Application Controller Project

Table 3-2 Application Controller Artifacts

Artifact(s)	File Location	Description
LifeCycleListenerImpl.java	application workspace directory\ApplicationController\src\application For example: JDeveloper\mywork\application name\ApplicationController\src\application	The default application lifecycle listener (ALCL) for the MAF application. For more information, see Section 4.7, "Using Lifecycle Listeners in a Mobile Application."
maf-skins.xml	application workspace directory\ApplicationController\src\META-INF For example: JDeveloper\mywork\application name\ApplicationController\src\META-INF	Defines the available skins and also enables you to define new skins. For more information, see Section 4.12, "Skinning Mobile Applications."
adfm.xml	application workspace directory \ApplicationController\adfmsrc\META-INF For example: JDeveloper\mywork\application name\ApplicationController\adfmsrc\META-INF	Maintains the paths (and relative paths) for the .cpx, .dcx, .jpx, and .xcfg files (registries of metadata).
DataControls.dcx	application workspace directory\ApplicationController\adfmsrc\ For example: JDeveloper\mywork\application name\ApplicationController\adfmsrc\	The data controls registry. For information on using the DeviceFeatures data control, which leverages the services of the device, see Section 7, "Using Bindings and Creating Data Controls." For information on the ApplicationFeatures data control, which enables you to create a springboard page that calls the embedded application features, see Section 4.5.5, "What You May Need to Know About Custom Springboard Application Features with MAF AMX Content."

3.2.2.2 About the View Controller Project Resources

The view controller project (which is generated with the default name, ViewController, as illustrated in Figure 3-10) houses the resources for the application features. Unlike the application controller project described in Section 3.2.2.1, "About the Application Controller Project-Level Resources," the view controller project's metadata files describe the resources at the application feature-level, in particular the various application features that can be aggregated into a MAF application so that they can display on a mobile device within the springboard of the MAF application itself or its navigation bar at runtime. Further, the application feature metadata files describe whether the application feature is comprised of HTML or MAF AMX pages. In addition, the view controller project can include these application pages as well as application feature-level resources, such as icon images to represent the application feature on the springboard and navigation bar defined for the MAF application.

Tip:

Store code specific to an application feature within the view controller project. Use the application controller project as the location for code shared across application features, particularly those defined in separate view controller projects.

The view controller project can be decoupled from the application controller project and deployed as an archive file for reuse in other mobile applications as described in Section 4.13, "Working with Feature Archive Files." In rare cases, an application controller project can consume more than one view controller project.

Note:

Adding a MAF view controller project as a dependency of another MAF view controller project, or as a dependency of a MAF application controller project, prevents the deployment of a MAF application. For more information, see Section 4.6.2, "What You May Need to Know About Feature Reference IDs and Feature IDs."

Figure 3-10 View Controller Project

As shown in Table 3-3, these resources include the configuration file for application features called maf-feature.xml.

Table 3-3 View Controller Artifacts

Artifact(s)	File Location	Description
maf-feature.xml	application workspace directory\src\META_INF\maf-feature.xml For example: JDeveloper\mywork\application name\ViewController\src\META-INF	A stub XML descriptor file that enables you to define application features. For more information, see Section 4.8, "About the Mobile Application Feature Configuration File." After you have configured the Mobile Preferences as described in Section 2.3.1, "How to Configure the Development Environment for Platforms and Form Factors," you can deploy this application using the default deployment profile settings. For more information, see Chapter 19, "Deploying Mobile Applications."
Application-Specific Content	application workspace directory\ViewController\public_html For example: JDeveloper\mywork\application name\ViewController\public_html	The application features defined in maf-feature.xml display in the public_html directory. Mobile content can include MAF AMX pages, CSS files, and task flows. Any custom images that you add to an application feature must be located within this directory. For more information, see Section 4.10.2, "What You May Need to Know About Selecting External Resources."

3.2.2.3 About Automatically Generated Deployment Profiles

A deployment profile defines the way the application is packaged into the archive that will be deployed to the target environment (such as a mobile device, an emulator, or an application marketplace, such as the iOs App Store). The deployment profile:

• Specifies the format and contents of the archive file that will be created

• Lists the source files, deployment descriptors, and other auxiliary files that will be packaged

• Describes the type and name of the archive file to be created

• Highlights dependency information, platform-specific instructions, and other information

After you create an application, MAF generates deployment profiles that are seeded with default settings and image files. Provided that you have configured the environment correctly, you can use these profiles to deploy a MAF application immediately after creating it by choosing Application and then Deploy, as shown in Figure 3-11.

Figure 3-11 Default Deployment Profiles

Using the Deployment Action page, shown in Figure 3-12, you then select the appropriate deployment target.

Figure 3-12 Selecting a Deployment Target

Note:

iOS and Android application deployments to simulators and devices have distinct environment set up and configuration requirements. For more information, see Section 19.3, "Deploying an Android Application," and Section 19.4, "Deploying an iOS Application."

For an Android application deployment to a simulator, make sure to install the package for the Google Cloud Messaging Library (Revision 3 and later) in the Android SDK Manager. For more information, Section 19.2.3, "How to Create an Android Deployment Profile."

As illustrated in Figure 3-11, MAF creates application-level profiles for both supported platforms (iOS and Android) and names them iOS1 and Android1.

Note:

MAF increments the name of each new deployment profile by 1. For example, iOS2, iOS3.

You can accept the default values used for these profiles, or edit them by selecting the profile from the Deployment page of the Application Properties dialog and then clicking Edit. Figure 3-13 illustrates the Options page for a default Android application profile. For information on the values configured for MAF application profiles, see Section 19.2.3, "How to Create an Android Deployment Profile" and Section 19.2.4, "How to Create an iOS Deployment Profile."

Figure 3-13 Editing a Default Deployment Profile

MAF packages the application and view controller projects as separate Feature Archive (FAR) files. These JAR files of MAF files are used as resources for other applications and are described in Section 19.5, "Deploying Feature Archive Files (FARs)." Because MAF creates these FAR files as dependencies to the MAF application profile, you can include or exclude them using the Profile Dependencies page of the Application Properties dialog, as illustrated in Figure 3-14.

Note:

The application controller project must contain a single FAR profile dependency; otherwise, the deployment will fail.

Figure 3-14 Editing FAR Contents from MAF Projects

Using the File Groups-related pages of the Project Properties dialog, you can customize the contents of the view controller FAR file, as shown in Figure 3-15. For more information on the Project Properties dialog, see the Oracle JDeveloper online help and also the "Configuring Deployment Profiles" in Oracle Fusion Middleware Developing Applications with Oracle JDeveloper.

Figure 3-15 Editing the View Controller Project's FAR

In addition to the platform-specific deployment profiles, MAF also creates a deployment profile that enables you to package the MAF application as a Mobile Application Archive (.maa) file. Using this file, you can create a new MAF application using a pre-existing application that has been packaged as an .maa file. For more information, see Section 19.6, "Creating a Mobile Application Archive File" and Section 19.7, "Creating Unsigned Deployment Packages."

By default, this deployment file bears the name of the MAF application followed by _archive. As illustrated in Figure 3-11, this profile is called Employees_archive and, if needed, can be edited using the Application Properties dialog.

Figure 3-16 Editing the Default Deployment Profiles Using the Application Properties Dialog

For more information on editing deployment profiles using the Application Properties dialog pages, see the "Viewing and Changing Deployment Profile Properties" section in Oracle Fusion Middleware Developing Applications with Oracle JDeveloper and the Oracle JDeveloper online help for the Application Properties and Project Properties dialogs.

3.2.3 What You May Need to Know About Editing MAF Applications and Application Features

Creating an application results in the generation of the maf-application.xml file, which enables you to configure the mobile application and also the maf-feature.xml file, which you use to add, remove, or edit the application features embedded within the mobile application. The MAF extension provides you with overview editors for both of these files, enabling you to declaratively change them. Figure 3-17 shows an example of the overview editor of the maf-application.xml file.

Figure 3-17 Overview Editor of the Mobile Application

As shown in Figure 3-17, the maf-application.xml file is located in the Applications window in the Application Resources panel, under the Descriptors and ADF META-INF nodes. You can open this file by double-clicking it from this location. When you access this file, JDeveloper not only opens the associated overview editor, but also displays the pertinent page components in the Components window, which you can drag and drop into either the Source page of the editor or the Structure window, as shown in Figure 3-18. Section 4.2, "About the Mobile Application Configuration File" describes the components of the maf-application.xml page.

Figure 3-18 Using the Source Editor, Structure Window, and Properties Editor for the MAF Application

As illustrated in Figure 3-19, the maf-feature.xml configuration file is located in the Applications window in the Project panel under the view controller and META-INF nodes. You use this file to compose the content for the MAF application.

Figure 3-19 Overview Editor for Application Features

Like the overview editor for the maf-application.xml file, JDeveloper presents the MAF components used for building the elements of the maf-features.xml configuration file, which are described in Section 4.8, "About the Mobile Application Feature Configuration File." You can use the Overview page or you can drag and drop components from the Components window into the Structure window or into the Source editor itself. When you select the maf-feature.xml file, JDeveloper populates the Components window with MAF Feature components.

Figure 3-20 Using the Source Editor, Structure Window, and Components Window for Application Features

3.2.4 Creating an Application Workspace for a MAF AMX Application

As described in Chapter 5, "Creating MAF AMX Pages," the MAF AMX components enable you to build pages that run identically to those authored in a platform-specific language. MAF AMX pages enable you to declaratively create the user interface using a rich set of components. Figure 3-21 illustrates the declarative development of a MAF AMX page.

Figure 3-21 Creating a MAF AMX Page

These pages may be created by the application assembler, who creates the MAF application and embeds application features within it, or they can be constructed by another developer and then incorporated into the MAF application either as an application feature or as a resource to a MAF application.

The project in which you create the MAF AMX page determines if the page is used to deliver the user interface content for a single application feature, or be used as a resource to the entire MAF application. For example, a page created within the application controller project, as shown in Figure 3-25, would be used as an application-wide resource.

MAF enables you to arrange MAF AMX view pages and other activities into an appropriate sequence through the MAF task flow. As described in Section 5.2, "Creating Task Flows," a MAF task flow is visual representation of the flow of the application. It can be comprised of MAF AMX-authored user interface pages (illustrated by such view activities, such as the WorkBetter sample application's default List page and the Detail page in Figure 3-22) and nonvisual activities that can call methods on managed beans. The non-visual elements of a task flow can be used to evaluate an EL expression or call another task flow. As illustrated by Figure 3-22, MAF enables you to declaratively create the task flow by dragging task flow components onto a diagrammer. MAF provides two types of task flows: a bounded task flow, which has a single point of entry, such as the List page in the WorkBetter sample application, and an unbounded task flow, which may have multiple points of entry into the application flow. The WorkBetter sample application is located in the PublicSamples.zip file within the jdev_install/jdeveloper/jdev/extensions/oracle.maf/Samples directory on your development computer.

Figure 3-22 MAF Task Flow

Figure 3-23 shows wizards that MAF provides to add MAF task flows, AMX pages, reusable portions of MAF AMX pages called MAF page fragments, and application features. To access these wizards, select a view controller or application controller project within the Applications window and choose File > New. Select one of the wizards after selecting Mobile Application Framework within the Client Tier.

Figure 3-23 Wizards for Creating Resources for Application Features

3.2.4.3 What Happens When You Create MAF AMX Pages and Task Flows

JDeveloper places the MAF AMX pages and task flows in the Web Content node of the view controller project, as shown by custom_springboard.amx and ViewController-task-flow.xml (the default name for a task flow created within this project) in Figure 3-27. These artifacts are referenced in the maf-feature.xml file as described in Section 4.6, "Configuring the Application Features within a Mobile Application." Other resources, such as the customized application splash screen (or launch) images and navigation bar images, are also housed in the Web Content node. For more information, refer to Table 3-3. To manage the unbounded task flows, JDeveloper generates the adfc-mobile-config.xml file. Using this file, you can declaratively create or update a task flow by adding the various task flow components, such as a view (a user interface page), the control rules that define the transitions between various activities, and the managed beans to manage the rendering logic of the task flow.

Figure 3-27 MAF AMX Pages and Task Flows within Application Controller and View Controller Projects

JDeveloper places the MAF AMX page and task flow as application resources to the mobile application in the Web Content node of the application controller project. As illustrated in Figure 3-27, the file for the MAF AMX page is called application_resource.amx and the task flow file is called ApplicationController-task-flow.xml (the default name).

3.3.1 What Happens When You Migrate an ADF Mobile Application

Table 3-4 describes how migration affects ADF Mobile artifacts.

<skin-family>mobileAlta</skin-family>  <skin-version>v1.1</skin-version>

The application migrates from the ADF Mobile Framework technology to use the Mobile Application Framework technology as a project feature. Figure 3-30 shows the Features page for an application controller project that uses the Mobile Application Framework technology. Choose Project Properties > Features to view this dialog.

Figure 3-30 Mobile Application Framework Project Feature

MAF does not override the icon, splash screen, or navigation bar images created for the ADF Mobile application; the image files within the application controller's resources file are retained. Likewise, any images used for application features are also retained. See also Section 3.2.2.1, "About the Application Controller Project-Level Resources."

<policy-references xmlns="http://oracle.com/adf">policy-reference category="security"
                   uri="oracle/wss_username_token_client_policy"
                   enabled="true"
                   id="oracle/wss_username_token_client_policy" xmlns=""/>
</policy-references>

<wsp:PolicyReference xmlns:wsp="http://www.w3.org/ns/ws-policy"                    
                     DigestAlgorithm="http://www.w3.org/ns/ws-policy/Sha1Exc"
                     URI="oracle/wss_username_token_client_policy"
                     orawsp:status="enabled"
                     orawsp:id="2"/>

3.3.2 What You May Need to Know About FARs in Migrated Applications

MAF does not migrate the adfmf-feature.xml file packaged within a Feature Archive (FAR) file. You replace the ADF Mobile FARs used by a migrated application to make sure that the credentials attribute has been replaced by securityEnabled=true in the FAR's maf-feature.xml file.

After you migrate the application:

1. Choose Application Properties > Libraries and Classpath.

2. Select the FAR and click Remove.

3. Import the FAR containing the migrated view controller as described in Section 4.13.1, "How to Use FAR Content in a MAF Application."

4. Migrate the ADF Mobile application that contains the view controller project that was packaged as a FAR.

   Note:

   A FAR cannot include both an adfmf-feature.xml file and a maf-feature.xml file.

   1. Deploy the view controller project as a FAR.

   2. Import the FAR into the migrated application as described in Section 4.13.1, "How to Use FAR Content in a MAF Application."

3.3.3 Migrating Applications in Headless Mode

Oracle JDeveloper provides a set of migrators that enable you to migrate applications using the ojmigrate command line utility. To migrate a workspace (.jws) file (and all of its project files), first navigate to the jdev\bin directory (Oracle_Home\jdeveloper\jdev\bin) of the Oracle JDeveloper 12c installation, then enter the following at the command prompt:

ojmigrate workspace.jws

You can migrate one or more workspaces using this command. For example, enter the .jws file locations as follows:

ojmigrate C:\JDeveloper\mywork\ADFMobileApp1\ADFMobileApp1.jws

          C:\JDeveloper\mywork\ADFMobileApp2\ADFMobileApp2.jws

While you can migrate a small number of workspace files using this method, you can migrate several files using a text file listing the .jws file locations. The syntax is as follows, with the location of the text file prefixed with an at sign (@):

ojmigrate @file

For example, enter ojmigrate @C:\migrate.txt.

Example 3-3 illustrates the contents of the text file, where each file location must be on a new line:

C:\JDeveloper\mywork\ADFMobileApp1\ADFMobileApp1.jws
C:\JDeveloper\mywork\ADFMobileApp2\ADFMobileApp2.jws
C:\JDeveloper\mywork\ADFMobileApp3\ADFMobileApp3.jws
C:\JDeveloper\mywork\ADFMobileApp4\ADFMobileApp4.jws
C:\JDeveloper\mywork\ADFMobileApp5\ADFMobileApp5.jws

After you run this command, verify that the applications have been migrated.

Use the -failFast option (ojmigrate -failFast @file) to stop the migrators after the first application listed in the text file fails to migrate. Using this command you can analyze the errors that prevent the migration.

If the application requires additional data, you can create an output file that lists them as name-value pairs by using the -generateDefaults option as follows:

ojmigrate -generateDefaults @migrate.txt

If the application file requires additional defaults, the -generateDefaults option creates a property file named for the .jws file (workspacefilename.migration.properties). After you examine the .properties file and change the values accordingly, migrate the workspace using the ojmigrate command without the -generateDefaults option (for example, ojmigrate @file).