25 Deploying MAF Applications

This chapter describes how to deploy MAF applications for testing and for publishing.

This chapter includes the following sections:

25.1 Introduction to Deployment of MAF Applications

Before you can publish an application for distribution to end users, you must test it on a device or virtual device to assess its behavior and ease of use. MAF provides ready-to-use deployment profiles for each platform to facilitate deployment of your MAF application.

Use the ready-to-use deployment profile or create your own to deploy your MAF application to the device or virtual device (emulator or simulator) where you want to test your MAF application.

MAF uses the deployment profile to execute the deployment of an application by copying a platform-specific template application to a temporary location, updating that application with the code, resources, and configuration defined in the MAF project. MAF then builds and deploys the application using the tools of the target platform. You can deploy a mobile application as the platform-specific package which you can make available from a download site or application marketplace (for example, the Apple App Store). For testing and debugging, you can deploy to a device or virtual device. You can reuse the application features by deploying the view controller projects as a feature archive (FAR). You also have the option to reuse the entire mobile application by deploying it as a Mobile Application Archive (.maa) file.

Each MAF deployment profile (Android, iOS, Windows) includes a set of different libraries that are specific to the type of deployment (release or debug) in combination with the deployment target (simulators or actual devices). In addition, each set of these libraries includes a JVM JAR file. The application binding layer resides within this virtual machine, which is a collection of Objective-C libraries. For example, MAF deploys a JVM JAR file and a set of libraries for a debug deployment targeted at an iOS simulator, but deploys a different JVM JAR file and set of libraries to a debug deployment targeted to an actual iOS-powered device. The libraries that you declare for the project are included in the deployment artifacts for the project.

We recommend that you invoke JDeveloper’s Build > Clean All command in a number of scenarios prior to deploying your application so that JDeveloper removes artifacts and settings left over from previous builds in order to begin a fresh build process. These scenarios are:

Changes to deployment profile settings, such as build mode or application name.
Adding or removing a Cordova plugin.
Changes to preferences for the Android platform, such as Gradle proxy settings, Android SDK location, or signing credentials.

25.2 Working with Deployment Profiles

For MAF application deployment, you can either create a ready-to-use deployment profile or use a customized deployment profile. A deployment profile defines how an application is packaged into the archive that will be deployed to the platform-specific device or virtual device.

You deploy a MAF application to the platform that you want your application to run on using a deployment profile. MAF provides a ready-to-use deployment profile for each platform that it supports (Android, iOS, Windows) or you can create a customized deployment profile. A deployment profile defines how an application is packaged into the archive that will be deployed to the platform device (for example, an Android-powered device or Android emulators). The deployment profile does the following:

Specifies the format and contents of the archive.
Lists the source files, deployment descriptors, and other auxiliary files that will be packaged into the archive file.
Describes the type and name of the archive file to be created.
Highlights dependency information, platform-specific instructions, and other information.

In addition to the platform-specific deployment profiles, MAF also provides a deployment profile that enables you to package the MAF application as a MAF 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. By default, this deployment file bears the name of the MAF application followed by _archive. See Creating a Mobile Application Archive File.

25.2.1 About Automatically Generated Deployment Profiles

MAF generates deployment profiles that are seeded with default settings and image files when you create an application. 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.

Figure 25-1 Default Deployment Profiles

Description of "Figure 25-1 Default Deployment Profiles"

Using the Deployment Action page, shown in the figure below, you then select the appropriate deployment target.

Figure 25-2 Selecting a Deployment Target

Description of "Figure 25-2 Selecting a Deployment Target"

Each deployment profile has distinct environment set up and configuration requirements. See:

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. The figure illustrates the Android Options page for a default Android application profile.

Figure 25-3 Editing a Default Deployment Profile

Description of "Figure 25-3 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 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, shown in the figure below.

Note:

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

Figure 25-4 Editing FAR Contents from MAF Projects

Description of "Figure 25-4 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 the figure below. For information on the Project Properties dialog, see the Oracle JDeveloper online help and Configuring Deployment Profiles in Developing Applications with Oracle JDeveloper.

Figure 25-5 Editing the FAR of the View Controller Project

Description of "Figure 25-5 Editing the FAR of the View Controller Project "

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

25.2.2 How to Create a Deployment Profile

MAF creates a set of deployment profiles when you create a mobile application. You can deploy an application using these profiles, edit them, or construct new ones using the MAF-specific deployment profile pages.

The Create Deployment Profile wizard, shown in Figure 25-6, enables you to create a default deployment profile from these pages. You can create as many deployment profiles as needed. For information on these standard deployment profile pages, click Help to see the JDeveloper online help.

Note:

MAF application deployment only requires the creation of an application-level deployment profile; you do not have to create a view controller-level deployment profile.

Before you begin:

To enable JDeveloper to deploy mobile applications, you must designate the SDKs for the target platforms, as described in Configuring the Development Environment for Platforms and Form Factors of Installing Oracle Mobile Application Framework.

Tip:

For iOS deployments, run the iOS Simulator at least once before you configure the directory location.

To create a deployment profile:

Select Application and then Deploy.
Select New Deployment Profile.
Select the profile for the platform that you want to target from the Profile Type dropdown list.

Figure 25-6 The Create Deployment Profile Wizard

Description of "Figure 25-6 The Create Deployment Profile Wizard"
Accept the default name for the profile or enter a new one. Click OK.
If needed, use the Options and Application Images pages as required for the applications and then click OK.

25.2.3 What Happens When You Create a Deployment Profile

After you complete the Create Deployment Profile wizard, JDeveloper creates a deployment profile and opens the Deployment Profile Properties editor. When an application is deployed, JDeveloper creates a deployment directory and the related subdirectory in addition to FAR files for the default projects.

After you complete the wizard, JDeveloper creates a deployment profile and opens the Deployment Profile Properties editor.

Table 25-1 lists the MAF-specific pages in the Deployment Profile Properties editor, shown in Table 25-1.

Table 25-1 MAF-Specific Deployment Profile Pages

Page	Function
iOS Options	Enables you to modify the settings for an application to be deployed on an iOS-powered device or iOS simulator.
Android Options	Enables you to modify the settings for an application deployed to an Android-powered device or Android emulator.
Windows Options	Enables you to modify the settings for an application that you deploy to the Universal Windows Platform.
Application Images	Enables you to assign custom icons to an application by adding the appropriate graphics file.
Device Orientations	Enables you to restrict the display of an application to certain device orientations. This page is used only for iOS deployment profiles.

Note:

Deployment depends on the needs of your application. You can deploy an application using the default values seeded in the pages listed in Table 25-1.

When you deploy an application, JDeveloper creates a deployment directory and related subdirectory. It also creates Feature Archive files (FARs) for the view controller projects (which must have different names) and application controller project. In addition to these two FARs, JDeveloper creates copies of any FARs that were imported into the project. Changes to the compilation profiles require the removal of the deployment directory. You can remove this directory, as well as the deployment directory within the view controller project that contains the FAR, by selecting Build and then Clean All.

25.3 Deploying a MAF Application to the Android Platform

MAF applications can be deployed to an Android device, an emulator, or to a deployment package that you or end users then use to install the application on an Android device or emulator.

MAF provides two build modes for an application that you deploy to the Android platform. Use debug mode to test and debug your application as you go through the development cycle. Use release mode to deploy an application that is release ready and can be published to end users through an application marketplace, such as Google Play.

MAF provides a ready-to-use deployment profile (Android1) that deploys your MAF application. You can use this ready-to-use deployment profile or create one or more other deployment profiles to deploy your MAF application to the Android platform. Using a deployment profile, you can deploy your MAF application in debug mode or release mode.

Creating a new deployment profile or editing an existing profile, you can:

Specify additional library and profile dependencies for your application
Choose between debug or release build modes
Specify options such as the application name and version
Specify the images that the application uses to render its logo in the splash screen and the icon that appears on the user’s device.
Specify the preferred storage location for the MAF application when installed on the Android device.
Choose the logging level for the Gradle build tool that MAF uses to build the MAF application. For information about these log levels, see Gradle’s documentation.
Specify the minimum SDK API level that determines the minimum version of Android your MAF application can run on.
Disable multidex support in your MAF application. By default, MAF enables multidex support so that your MAF application can contain multiple Dalvik Executable (DEX) files. You can disable this support if your application does not exceed the size described in the Configure Apps with Over 64K Methods page of the Android Developer’s website. If you see references to com.android.dex.DexIndexOverflowException during a compilation failure for your MAF application, it may indicate that your application is too large and you need to enable multidex support.
Disable backup. By default, MAF applications participate in Android’s backup and restore infrastructure. If you clear the Allow Backup checkbox, no backup or restore of the application will ever be performed, even by a full-system backup that would otherwise cause all application data to be saved via adb.

For information about how to edit or create a deployment profile, see Working with Deployment Profiles. Click Help in the deployment profile dialogs to view information about the respective tasks that you can perform in each dialog.

Before you deploy a MAF application using a deployment profile, you download the Android SDK and reference it from the Android Platform dialog in MAF Preferences, as described in Configuring the Development Environment for Target Platforms and Setting Up Development Tools for the Android Platform in Installing Oracle Mobile Application Framework.

MAF uses Gradle to build and deploy MAF applications to the Android platform. MAF downloads and installs the Gradle build tool the first time that you deploy a MAF application. If your development machine is located behind a corporate firewall, configure the Gradle proxy settings so that MAF can successfully download, install, and configure Gradle. See How to Configure Gradle Proxy Settings.

After you finish development of your MAF application, you can publish it to an application marketplace, such as Google Play. Before you publish the application, make sure that the build mode in the deployment profile you use to deploy the application is in release mode, as shown in the figure. You access the Android Options dialog from JDeveloper’s Application > Application Properties > Deployment menu. To deploy in release mode, you also need to sign the application, as described in How to Sign a MAF Application that You Deploy to the Android Platform.

For information about publishing an application to Google Play, see http://developer.android.com/tools/publishing/publishing_overview.html.

Figure 25-7 Release Mode in Deployment Profile Properties

Description of "Figure 25-7 Release Mode in Deployment Profile Properties"

25.3.1 How to Configure Gradle Proxy Settings

If your computer is in a corporate network, configure proxy settings in the Gradle Proxy Settings dialog so that MAF can download and install the Gradle tools required to build MAF applications that you deploy to the Android platform.

To configure Gradle proxy settings:

In JDeveloper, click Tools, Preferences, Mobile Application Framework, Android Platform, and Gradle Proxy Settings to open the dialog.

Figure 25-8 Gradle Proxy Settings

Description of "Figure 25-8 Gradle Proxy Settings"
As necessary, complete the fields in the HTTP Proxy and HTTPS Proxy sections of the dialog:
- Host Name: Enter the URI of the proxy server.
- Port Number: Enter the port number that the proxy server uses.
- No proxy for: Enter a | delimited list of URIs to ignore. For example, *.nonproxyrepos.com|*.oracle.com|localhost.
- Proxy Authentication: Select if the proxy server requires authentication credentials and enter these credentials in the Login and Password fields.
- Enable HTTPS Proxy: Select if you need to specify details (host name, port number, and so on) for a HTTPS Proxy server. This makes the subsequent input fields writable.
Click OK.

25.3.2 How to Sign a MAF Application that You Deploy to the Android Platform

An application must be signed before it can be deployed to an Android device or emulator. Android does not require a certificate authority; an application can instead be self-signed.

Defining how the deployment signs a MAF application is a two-step process: within the Android Platform page of the MAF preferences, you first define debug and release properties for a key that is used to sign Android applications. You only need to configure the debug and release signing properties once. After you define these options, you configure the deployment profile to designate if the application should be deployed in the debug or release mode.

If no keystore file exists, you can create one using the keytool utility, as illustrated in the following example.

keytool -genkeypair
        -v
        -keystore c:\jdeveloper\mywork\releasesigning.keystore
        -alias releaseKeyAlias
        -keyalg RSA
        -keysize 2048
        -validity 10000

In this example, the keystore contains a single key, valid for 10,000 days. As described in the Signing Your Applications document, available from the Android Developers website (http://developer.android.com/tools/publishing/app-signing.html), the keytool prompts you to provide passwords for the keystore and key, and to provide the Distinguished Name fields for your key before it generates the keystore. Refer to Java SE Technical Documentation (http://download.oracle.com/javase/index.html) for information on how to use the keytool utility.

To configure the key options for the debug mode:

Click Tools, then Preferences, and then Mobile Application Framework.
Select Android Platform and, in the Signing Credentials section, enter a password used by the deployment to create a keystore file and key needed for a debug deployment in the Key and Keystore Password field. This password, which generates a keystore and keyfile for deployment to an Android-powered device or emulator, can be any value, but must be at least six characters long. The default password is Android.

To configure the key options for the release mode:

Click Tools, Preferences, and Mobile Application Framework.
Select Android Platform, then the Release tab, and then define the following:
- Keystore Location—Enter, or browse to and retrieve, the directory of the keystore containing the private key used for signing the application for distribution.
- Keystore Password—Enter the password for the keystore. This password allows access to the physical file.
- Key Alias—Enter an alias for the key. This is the value set for the keytool's -alias argument. Only the first eight characters of the alias are used.
- Key Password—Enter the password for the key. This password allows access to the key (identified by the alias) within the keystore.
  
  Tip:
  
  Enter the password and key password requested by the keytool utility before it generates the keystore.
Click OK.

25.3.3 What You May Need to Know About Credential Storage

MAF stores passwords for the key and keystore in the file-based credential store, cwallet.sso. This file, which manages credential storage and retrieval, is located within the o.maf folder in the user's JDeveloper system folder.

For example, in a Windows environment, the cwallet.sso file is located at C:\Users\jsmith\AppData\Roaming\JDeveloper\system12.2.1.0.42.170530.0315\o.maf.2.4.2.0.42.170930.0315.

See About Oracle Wallet in Administering Oracle Fusion Middleware.

Note:

MAF stores the key and keystore credentials in a file called product-preferences.xml. MAF migrates these credentials to the cwallet.sso file if you preserve the preference settings by clicking Yes in the Confirm Import Preferences dialog during the installation process of the current version of JDeveloper and MAF. However, the cwallet.sso file is not migrated to other installations of the current version of Oracle JDeveloper with MAF. If you reinstall (or create a separate installation), you must either copy the cwallet.sso file to the o.maf folder or reconfigure the release mode credentials in the Platforms preferences page.

25.3.4 How to Deploy a MAF Application to the Android Platform

Deploy the application to the Android platform using a MAF for Android deployment profile.

To deploy a MAF application to the Android platform:

Select Applications, then Deploy, then select an Android deployment profile.
Select the appropriate deployment option from the list in the dialog that appears:
- Deploy application to device
  
  Before you select this option that deploys directly to an Android-powered device, connect the device to the development computer that hosts JDeveloper, set the device to developer mode, and turn on USB debugging. For information about these tasks, see Set Up Your Android Device to Install an App from Your Development Machine in Installing Oracle Mobile Application Framework.
- Deploy application to emulator
  
  Before you select this option that deploys directly to an Android emulator, set up and start the Android emulator. For information about this task, see Setting Up Development Tools for the Android Platform in Installing Oracle Mobile Application Framework.
- Deploy application to package
  
  Deploys the MAF application to an .APK file that you can then distribute for installation on an Android device or emulator.
Review the Summary page and click Finish.

25.3.5 What Happens When You Deploy a MAF Application to the Android Platform

MAF generates an .APK file that it uses to install the MAF application on a device or emulator if either of these deployment options were chosen. If you chose the deploy application to package option, navigate to the directory where MAF generated the .APK file to retrieve it.

MAF includes the following in the .APK file.

The content in the adfmsrc
The content in the .adf folder
maf-application.xml and maf-feature.xml files
logging.properties file
The JVM files

For deployment to device or emulator options, MAF installs and launches the MAF application. If you deployed the MAF application in debug mode, a red icon appears on each screen of the MAF application, as shown in the upper-left portion of the figure. MAF applications that you deploy in release mode do not render this icon.

Figure 25-9 MAF Application Deployed in Debug Mode

Description of "Figure 25-9 MAF Application Deployed in Debug Mode"

MAF uses the Android Debug Bridge to connect to the device or emulator where you want to deploy the MAF application. If the deployment does not detect a device, it restarts the Android Debug Bridge server five times until it detects a device (if deploying to a device) or emulator (if deploying to an Android emulator). If it detects neither, then it ends the deployment process, as shown in the figure below.

Figure 25-10 Deployment Terminated

Description of "Figure 25-10 Deployment Terminated"

If you are using the Android Debug Bridge command line tool prior to deployment, then you must enter the same command again after the deployment has completed. For example, if you entered adb logcat to view logging information for an emulator or device prior to deployment, you would have to enter adb logcat again after the application has been deployed to resume the retrieval of the logging output. For information about the Android Debug Bridge command line tool, which is located within (and executed from) the platform-tools directory of the Android SDK installation, refer to the Android Developers website (http://developer.android.com/tools/help/adb.html).

After you select a deployment action, JDeveloper creates a shortcut on the Deploy menu that enables you to easily redeploy the application using that same deployment action.

By default, MAF applications are installed on an Android-powered device's internal storage after they have been deployed from JDeveloper to a device, or downloaded from an application marketplace, such as Google Play. The following options, which are available from the Preferred Storage Location dropdown list, enable you to specify a preferred storage location for the MAF application.

Internal—Forces the MAF application to be installed on the device's internal storage.
External—Allows the application to be installed on the device's SD card. However, if the Android system determines that the application cannot be installed on the SD card (for example, no SD card has been mounted, or the SD card exists but has insufficient space), then it installs the application on the device's internal storage instead. The mobile device user can move the application between internal and external storage using the system settings.
Auto—Specifies that the application may be installed on the device's external or internal storage. The mobile device user can move the application between internal and external storage using the system settings.

Selecting the External or Auto options enables the deployment framework to update the <manifest> element in the AndroidManifest.xml file with an android:installLocation attribute and a value of "preferExternal" or "auto". Populating the AndroidManifest.xml file with this attribute enables MAF applications to be stored on an external SD card or internal storage. For information, see the "App Install Location" chapter in Data Storage Guide, available from the Android Developers website (http://developer.android.com/guide/topics/data/install-location.html) or from the Android SDK documentation.

25.3.6 How to Add a Custom Image to an Android Application

Enabling MAF application icons to display properly on Android-powered devices of different sizes and resolutions requires low, medium, high, extra-high, extra-extra-high density, and extra-extra-extra-high density versions of the same images. MAF provides default Oracle images that fulfill these display requirements.

However, if the application requires custom icons, you can use the Application Images page, shown in the figure below, to override default images by selecting PNG-formatted images for the application icon and for the splash screen. For the latter, you can add portrait and landscape images. If you do not add a custom image file, then the default Oracle icon is used instead. MAF provides 9-patch images for the default Android splash screens. The 9-patch images indicate which areas of the image may be stretched, and which may not. These images can be stretched to fit any size while maintaining the integrity of designated portions within the image (such as the logo and copyright notice in the default MAF splash screen images).

To create custom images, refer to the Iconography document, available from the Android Developers website (http://developer.android.com/design/style/iconography.html).

Figure 25-11 Setting Custom Images for an Android Application

Description of "Figure 25-11 Setting Custom Images for an Android Application"

Before you begin:

Obtain the images in the PNG, JPEG, or GIF file format that use the dimensions, density, and components that are appropriate to Android theme and that can also support multiple screen types. See the Supporting Multiple Screens document, available from the Android Developers website (http://developer.android.com/guide/practices/screens_support.html).

To add custom images:

Click Application Images.
Use the Browse function to select the splash screen and icon image files from the project file. The figure above shows selecting images for application icons and portrait orientation splash screen images that applications use for displaying on devices with low, medium, high, extra-high, extra-extra-high density, and extra-extra-extra-high density displays.
Click OK.

25.3.7 What Happens When JDeveloper Deploys Images for Android Applications

During deployment, MAF enables JDeveloper to copy the images from their source location to a temporary deployment folder.

For the default images that ship with the MAF extension (located at application workspace directory\Application Resources\Resources\images), JDeveloper copies them from their seeded location to a deployment subdirectory of the view controller project (application workspace\ViewController\deploy). As shown in Table 25-2, each image file is copied to a subdirectory called drawable, named for the drawable object, described on the Android Developers website (http://developer.android.com/reference/android/graphics/drawable/Drawable.html). Each drawable directory matches the image density (ldpi, mdpi, hdpi, xhdpi, xxhdpi, and xxxhdpi) and orientation (port, land). Within these directories, JDeveloper renames each icon image file as adfmf_icon.png and each splash screen image as adfmf_loading.9.png or adfmf_loading.png (depending on whether 9-patch images are used).

Table 25-2 Deployment File Locations for Seeded Application Images

Source File (...\resource\Android)	Temporary Deployment File (...ViewController\deploy)
`display-ldpi-icon.png`	`drawable-ldpi\adfmf_icon.png`
`display-mdpi-icon.png`	`drawable-mdpi\adfmf_icon.png`
`display-hdpi-icon.png`	`drawable-hdpi\adfmf_icon.png`
`display-xhdpi-icon.png`	`drawable-xhdpi\adfmf_icon.png`
`display-xxhdpi-icon.png`	`drawable-xxhdpi\adfmf_icon.png`
`display-xxxhdpi-icon.png`	`drawable-xxxhdpi\adfmf_icon.png`
`display-port-ldpi-splashscreen.9.png`	`drawable-port-ldpi\adfmf_loading.9.png`
`display-port-mdpi-splashscreen.9.png`	`drawable-port-mdpi\adfmf_loading.9.png`
`display-port-hdpi-splashscreen.9.png`	`drawable-port-hdpi\adfmf_loading.9.png`
`display-port-xhdpi-splashscreen.9.png`	`drawable-port-xhdpi\adfmf_loading.9.png`
`display-port-xxhdpi-splashscreen.9.png`	`drawable-port-xxhdpi\adfmf_loading.9.png`
`display-land-ldpi-splashscreen.9.png`	`drawable-land-ldpi\adfmf_loading.9.png`
`display-land-mdpi-splashscreen.9.png`	`drawable-land-mdpi\adfmf_loading.9.png`
`display-land-hdpi-splashscreen.9.png`	`drawable-land-hdpi\adfmf_loading.9.png`
`display-land-xhdpi-splashscreen.9.png`	`drawable-land-xhdpi\adfmf_loading.9.png`
`display-land-xxhdpi-splashscreen.9.png`	`drawable-land-xxhdpi\adfmf_loading.9.png`

For custom images, JDeveloper copies the set of application icons from their specified location to the corresponding density and orientation subdirectory of the temporary deployment location.

25.4 Deploying an iOS Application

MAF provides a Deployment Action dialog that enables you to deploy an iOS application directly to an iOS simulator or to a package.

You can only deploy an iOS application from an Apple computer. Deployment to the iOS simulator does not require membership to either the iOS Developer Program or the iOS Developer Enterprise Program. Registration as an Apple developer will suffice. For information on iOS developer programs, which are required for deployment to iOS-powered devices (and are described at How to Deploy an Application to an iOS-Powered Device, and How to Distribute an iOS Application to the App Store), see https://developer.apple.com/programs/.

Figure 25-12 The Deployment Action Dialog (for iOS Applications)

Description of "Figure 25-12 The Deployment Action Dialog (for iOS Applications)"

Tip:

As an alternative to the Deployment Action dialog, you can deploy a mobile application to the iOS platform manually using the OJDeploy command line tool as described in Deploying MAF Applications from the Command Line.

25.4.1 How to Create an iOS Deployment Profile

Use the Deployment Profiles Properties dialog to define the iOS application build configuration as well as the locations for the application icons.

Before you begin:

Download Xcode (which includes the Xcode IDE, performance analysis tools, the iOS simulator, and iOS SDKs) to the Apple computer that also runs JDeveloper. Refer to the Certification and Support Matrix on Oracle Technology Network (http://www.oracle.com/technetwork/developer-tools/maf/documentation) for the minimum supported version required to compile applications.
Because Xcode is used during deployment, you must install it on the Apple computer before you deploy the mobile application from JDeveloper.
To deploy a mobile application to an iOS-powered device (as opposed to deployment to an iOS simulator), you must obtain both a provisioning profile and a certificate as described in Setting the Device Signing Options.

To create a deployment profile:

Select Application, Application Properties, and then Deployment.
On the Deployment page, double-click an iOS deployment profile.
Select iOS Options.
Accept the default values, or define the following:
- Bundle Id—If needed, enter a bundle ID to use. The application bundle Id must be unique for each application installed on an iOS device and must adhere to reverse-package style naming conventions (that is, com.<organization name>.<company name>). For information, see the App Distribution Guide available through the iOS Developer Library.
  
  Note:
  
  The application bundle ID cannot contain spaces.
  
  Because each application bundle ID is unique, you can deploy multiple mobile applications to the same device. Two applications can even have the same name as long as their application bundle IDs are different. Mobile applications deployed to the same device are in their own respective sandboxes. They are unaware of each other and do not share data (they have only the Device scope in common).
- Archive Name—If needed, enter the name for the .ipa file or the .app file. MAF creates an .ipa file when you select the Deploy to distribution package option in the Deployment Action dialog, shown in Figure 25-12. It creates an .app file when you select the Deploy application to simulator option. Otherwise, accept the default name. See How to Deploy an Application to an iOS-Powered Device and How to Distribute an iOS Application to the App Store.
  
  By default, MAF bases the name of the .ipa file (or .app file) on the application Name attribute configured in the maf-application.xml file. See Setting Display Properties for an Application Feature.
- Version—Specify the release version number for the MAF application. This version number is displayed to the end users and identifies a released iteration of the application. It is a string made up of three non-negative and period-separated integers, such as 3.1.2. The string should only contain numeric (0-9) and period (.) characters.
  - The first integer indicates a major revision to the MAF application and is updated for new features or major changes.
  - The second integer represent a revision that implements less prominent features.
  - The third integer represents a maintenance release revision.
- Build—Enter the build number for the MAF application. The build identifies an iteration (released or unreleased) of the MAF application and must be incremented each time the application is uploaded to iTunes Connect. The build version is typically a string made up of three non-negative and period-separated integers, such as 3.1.2. The string should only contain numeric (0-9) and period (.) characters.
  - The first number represents the most recent major release and must be greater than zero. The integer is limited to a maximum length of four digits.
  - The second number represents the most recent significant revision and is limited to a maximum length of two digits.
  - The third number represents the most recent minor bug fix and is limited to a maximum length of two digits. If the value of the third number is 0, you can omit it and the second period.
    
    Note:
    Leading zeros are truncated from each integer and will be ignored. For example, 1.02.3 is equivalent to 1.2.3.
- Minimum iOS Version—Indicates the earliest version of iOS to which an end user can deploy the application. The default value is the earliest version supported by MAF.
- Simulator—Select the hardware and iOS version of the simulator to which you intend to deploy the application. Available versions are displayed in the drop-down list along with the device ID. For information, see the Simulator User Guide, which is available through the iOS Developer Library.
- Family—Select the family of iOS products on which the application is intended to run. The default option is for both iPad and iPhone.

25.4.1.1 Defining the iOS Build Options

The iOS build options enable you to deploy an application with debug or release bits and libraries.

To set the build options:

Select Application, then Application Properties, and then Deployment.
On the Deployment page, double-click an iOS deployment profile.
Select iOS Options.
Select from the following build options.
- Push Notification Environment – Select Production if your deployed application is to use production Apple Push Notification service (APNs) servers or Development if it is to use development APNs servers. MAF ignores the value of Push Notification Environment if you do not select the PushPlugin plugin to enable push notifications, as described in Enabling Push Notifications.
- Disable Application Transport Security —App Transport Security (ATS) is a security policy that restricts network requests from the application to use only approved secured transport protocols. MAF enables ATS by default. Select Disable Application Transport Security to deploy your MAF application without ATS enabled.
- Debug—Select this option for development builds. Designating a debug build results in the inclusion of debugging symbols. See also How to Debug on the iOS Platform and How to Enable Debugging of Java Code and JavaScript.
- Release—Select to compile the build with release libraries and without debug symbols.
  
  Tip:
  
  Use the release mode, not the debug mode, to test application performance.
- Additional Build Arguments—Specify additional arguments that Xcode can use when it builds the MAF application.

When you deploy the MAF application in debug mode, a red icon appears on each screen of the MAF application, as shown in the upper-left portion of the figure. MAF applications that you deploy in release mode do not render this icon.

Figure 25-13 MAF Application Deployed in Debug Mode

Description of "Figure 25-13 MAF Application Deployed in Debug Mode"

25.4.1.2 Adding a Custom Image to an iOS Application

The Application Images page enables you to rebrand an application by overriding the default Oracle images used for application icons and artwork with custom images that you provide.

The figure below shows the Application Images page where you enter the locations of custom images used for different devices. For information on iOS application icon images, see Icon and Image Design section in iOS Human Interface Guidelines. This document is available from the iOS Developer Library.

Note:

All images must be in the PNG format.

To add custom images:

Select Application, Application Properties, and then Deployment.
On the Deployment page, double-click an iOS deployment profile.
Select iOS Options, and then Application Images from the tree on the left of the iOS Deployment Profile Properties editor.
Select Browse to select a custom marketing icon to override the default marketing icon provided by MAF. This image is required for all applications and must be 1024 x 1024 pixels for both iPhone and iPad applications.
Select the device type to display the available image types in the tree. By default, MAF displays all of the image styles and types available to iPad and iPhone devices. However, you can narrow the selection by selecting the device type, as shown in the figure. In the Icon Folder field, MAF displays the location within the Resources directory of the application where these image files are stored.

Figure 25-14 Selecting the Application Images

Description of "Figure 25-14 Selecting the Application Images"
Select an image type from the tree.
In the File field, select Browse to select another image. This image file must exist within the current application.

During deployment, JDeveloper copies the custom image file into the deployment profile and renames it to match the name of the default image.
Click OK.

25.4.1.3 How to Restrict the Display to a Specific Device Orientation

By default, MAF applications support all orientations for both iPhone and iPad. If, for example, an application must display only in portrait and in upside-down orientations on iPads, you can limit the application to rotate only to these orientations.

The figure shows the Device Orientation page where you select the device orientations that you want your MAF application to support.

Figure 25-15 Select a Device Orientation

Description of "Figure 25-15 Select a Device Orientation"

To limit the display of an application to a specific device orientation:

Select Device Orientations, as shown in the figure above.

Clear all unneeded orientations from among those listed in Table 25-3. By default, MAF deploys to all of these device orientations. By default, all of these orientations are selected.

Table 25-3 iPhone Device Orientations

Icon	Description
	iPad, portrait—The home button is at the bottom of the screen.
	iPad, upside-down—The home button is at the top of the screen.
	iPad, landscape left—The home button is at the left side of the screen.
	iPad, landscape right—The home button is at the right side of the screen.
	iPhone, portrait—The home button is at the bottom of the screen.
	iPhone, upside-down—The home button is at the top of the screen.
	iPhone, landscape left—The home button is at the left side of the screen.
	iPhone, landscape right—The home button is at the right side of the screen.

Click OK.

25.4.2 How to Set Device Signing and Export Options

The Preferences page for the iOS Platform includes fields for the location of the provisioning profile on the development computer, the identifier of the team, the name of the signing identity and the export method.

You must define these parameters if you deploy an application to a distribution package. You use a signing identity to code sign your application. A certificate and its public key are stored in the Member Center, and the corresponding signing identity (the certificate with its public and private key) is stored in your keychain. You will not be able to code sign without this private key.

Note:

You do not need to specify a signing identity, a provisioning profile, or an export method if you deploy an application to an iOS simulator.

To set the device signing and export options:

In JDeveloper, select Preferences, Mobile Application Framework, and then iOS Platform.
From the Provisioning Profile dropdown list, select the appropriate provisioning profile for your application.
In the Team field, enter the identifier of your team. MAF automatically populates this input field with a value that it extracts from the provisioning profile that you select in Step 2.
In the Signing Identity field, enter the name of the developer or distribution certificate that identifies the originator of the code (such as a developer or a company). You can view the name of the certificate using the Keychain Access utility (accessed from the Applications folder). Copy the entire name from the Keychain Access utility. The name entered into this field may look similar to the following example.
```
iPhone Developer: John Smith (Oracle123)
```
Figure 25-16 Device Signing and Export Options Sections of the iOS Platform Preferences Page

Description of "Figure 25-16 Device Signing and Export Options Sections of the iOS Platform Preferences Page"
From the Method dropdown list, choose the option that describes how you want Xcode to export the archive for your application.
- Ad Hoc if you use an ad hoc provisioning profile to distribute your application to devices where it can be tested. The devices must be registered in your developer account.
- Application Store if you use a distribution provisioning profile to publish your application to the Apple App Store.
- Development if you use a developer provisioning profile to deploy your application to your developer account's registered device for debugging.
- Enterprise if you use an enterprise provisioning profile to distribute your application within your enterprise.

Note:

There are provisioning profiles used for both development and release versions of an application. While a provisioning profile used for the release version of an application can be installed on any device, a provisioning profile for a development version can only be installed on the devices whose IDs are embedded into the profile. See the App Distribution Guide available through the iOS Developer Library.

25.4.3 How to Deploy an iOS Application to an iOS Simulator

The Deployment Actions dialog enables you to deploy an iOS application directly to an iOS simulator.

Before you begin:

To enable deployment to an iOS simulator, you must perform the following tasks:

Run Xcode after installing it, agree to the licensing agreements, and perform other post-installation tasks, as prompted.

Note:

You must run Xcode at least once before you deploy the application to the iOS simulator. Otherwise, the deployment will not succeed.
Review the Simulator User Guide, available in the iOS Developer Library. The iOS simulator is installed with Xcode.

To deploy an application to an iOS simulator:

Select Applications, then Deploy, then select an iOS deployment profile.
Select Deploy application to simulator and then select Next.
Review the Summary page which displays the following values. Click Finish.
- Application Bundle Id—The unique name that includes a Java language-like package name (com.<organization name>.<application name>) prefixed with the Bundle Seed that is generated from the iOS Provisioning Portal.
- File—The file name of the final image deployed to an iOS target.
- Signature—The developer or company that authored the application. If this value has not been configured in the iOS Platform preferences page, then the Summary page displays <Not Specified>.
- Provisioning Profile—The name of the provisioning profile that associates one or more development certificates and devices with an application ID. If this value is not configured in the iOS Platform preferences page, then the Summary page displays <Not Specified>.
Note:

Deployment to an iOS simulator does not require that the values for Signing Identity and Provisioning Profile to be defined.

25.4.4 How to Deploy an Application to an iOS-Powered Device

The Deploy to distribution package option deploys a MAF application to an .ipa file. You can then use the .ipa file to install the application to an iOS-powered device for debugging and testing.

Deployment to an iOS-powered device or to a distribution site requires membership of the iOS Developer Program or the iOS Developer Enterprise Program. For information about these programs, see https://developer.apple.com/programs/.

Deployment to an iOS-powered device requires the installation of iTunes, see https://www.apple.com/itunes/download/.

Before you begin:

Review and complete the steps in Setting the Device Signing and Export Options.
Refer to the App Distribution Guide available through the iOS Developer Library.

To deploy an application to an iOS-powered device:

Select Applications, then Deploy, and then select an iOS deployment profile.
Select Deploy to distribution package and then choose Next.
Review the Summary page, which displays the following values, before you click Finish.
- Application Bundle Id—The unique name that includes a Java language-like package name (com.<organization name>.<application name>).
- File—The file name of the final image.
- Signature—The developer (or company) who authored the application. If this value has not been configured in the iOS Platform preferences page, then the Summary page displays <Not Specified>.
- Provisioning Profile—The name of the provisioning profile that associates one or more development certificates and devices with an application ID. If this value is not configured in the iOS Platform preferences page, then the Summary page displays <Not Specified>.
Connect the iOS-powered device to your development computer.
Open iTunes.
Locate the .ipa file generated by the Deploy to distribution package deployment action.
Drag the .ipa file into iTunes and drop on your iOS device’s name listed under Devices on the left.

25.4.5 What You May Need to Know About Deploying an Application to an iOS-Powered Device

A provisioning profile must be created using the iOS Provisioning Portal before an application can be deployed to an iOS-powered device.

You cannot deploy an iOS application (that is, an .ipa file) to an iOS-powered device or publish it to either the App Store or to an internal hosted download site without first creating a provisioning profile using the iOS Provisioning Portal, which is accessible only to members of the iOS Developer Program.

As noted in the App Distribution Guide available through the iOS Developer Library, a provisioning profile associates development certificates, devices, and an application ID. The iOS Provisioning Portal enables you to create these entities as well as the provisioning profile.

Tip:

After you download the provisioning profile, double-click this file to add it to your Library/MobileDevice/Provisioning Profile directory.

Figure 25-17 The iOS Provisioning Portal

Description of "Figure 25-17 The iOS Provisioning Portal"

25.4.5.1 Creating iOS Development Certificates

An iOS Development Certificate electronically associates a developer identity with a public key and private key. Download and install a certificate on the development computer to sign applications for deployment.

A certificate is an electronic document that combines information about a developer's identity with a public key and private key. After you download a certificate, you essentially install your identity into the development computer, as the iOS Development Certificate identifies you as an iOS developer and enables the signing of the application for deployment. In the iOS operating environment, all certificates are managed by the Keychain.

Using the Certificates page in the iOS Provisioning Portal, you log a CSR (Certificate Signing Request). The iOS Provisioning Portal issues the iOS Development Certificate after you complete the CSR.

25.4.5.2 Registering an Apple Device for Testing and Debugging

To debug a MAF application on an iOS-powered device, you must use a developer provisioning profile that is associated with the device. The device must be included in the Current Available Devices list on the Devices page of the iOS Provisioning Portal and must be added to the developer provisioning profile.

In order to deploy a MAF application to multiple devices for testing, you must add each of these devices to the ad hoc provisioning profile that you intend to use.

25.4.5.3 Registering an Application ID

Application IDs uniquely identify applications on a device. An application ID consists of a Bundle ID, identical to the application ID on the Preferences page for the iOS Platform, and a 10-character alpha-numeric prefix from Apple.

An application ID is a unique identifier for an application on a device. An application ID is comprised of the administrator-created reverse domain name called a Bundle Identifier in the format described in Setting Display Properties for a MAF Application prefixed by a ten-character alpha-numeric string called a bundle seed, which is generated by Apple. The figure illustrates an application ID that is unique, one that does not share files or the Keychain with any other applications.

Figure 25-18 An Explicit Application ID

Description of "Figure 25-18 An Explicit Application ID"

Using a wildcard character (*) for the application name, such as 8E549T7128.com.oracle.*, enables a suite of applications to share an application ID. For example, if the administrator names com.oracle.MAF.* on the iOS Provisioning Portal, it enables you to specify different applications (com.oracle.MAF.application1 and com.oracle.MAF.application2).

Note:

For applications that receive push notifications, the application ID must be a full, unique ID, not a wildcard character; applications identified using wildcards cannot receive push notifications. See Provisioning and Development of Local and Push Notification Programming Guide, available in the iOS Developer Library.

When applications share the same prefix, such as 8E549T7128, they can share files or Keychains.

Note:

The Bundle ID must match the application ID set in the iOS Platform preferences page.

25.4.6 How to Distribute an iOS Application to the App Store

After you test and debug an application on an iOS device, you can distribute the application to a wider audience through the App Store or an internal download site.

To publish an application to the App Store, you must submit the .ipa file to iTunes Connect, which enables you to update applications and create test users.

Before you begin:

Before you distribute the application, you must perform the following tasks:

In the iOS Platform preference page, choose App Store or Enterprise from the Export dropdown list in the Export Options section.
Test the application on an actual iOS device. See How to Deploy an Application to an iOS-Powered Device.
Obtain a distribution certificate through the iOS Provisioning Portal.

Note:

Only the Team Agent can create a distribution certificate.
Obtain an iTunes Connect account for distributing the .ipa file to the Apple App Store. For information, refer to the App Store distribution guidelines at http://developer.apple.com/.
You may want to review the iTunes Connect Developer Guide available through the iOS Developer Library.
In the iOS Options page of the deployment profile, select Release as the build mode and then click OK.

To distribute an iOS application to the App Store:

Select Applications, then Deploy, and then select an iOS deployment profile.
Select Deploy to Distribution Package.
Review the Summary page, which displays the following values. Click Finish.
- Application Bundle Id—The unique name that includes a Java language-like package name (com.<organization name>.<application name>).
- File—The file name of the final image deployed to an iOS target.
- Signature—The application's author. If this value has not been configured in the iOS Platform preference page of the deployment profile, then the Summary page displays <Not Specified>.
- Provisioning Profile—The name of the provisioning profile that associates one or more development certificates and devices with an application ID. If this value is not configured in the iOS Platform preference page, then the Summary page displays <Not Specified>.
Log in to iTunes Connect.
Submit the .ipa file to iTunes Connect for consideration. See iTunes Connect Developer Guide for information.
See iTunes Connect Developer Guide for information on updating the binary.

25.5 Deploying a MAF Application to the Universal Windows Platform

MAF applications can either be deployed to the local machine on which you develop the application, or to an installation package that you use to install the application on a supported UWP device.

MAF provides two build modes for an application that is to be deployed to the UWP. Use the debug mode to test and debug your application as you go through the development cycle. Use the release mode to deploy an application that is release ready.

Release ready applications cannot be published to the Windows Store. Choose another mechanism to distribute your application. MAF provides a PowerShell script in the installation package that, when executed, installs the application on the UWP device.

Perform the following setup and configuration tasks before you attempt to deploy an application to the UWP:

Verify that your development machine meets the requirements to deploy a MAF application to the UWP. The UWP device that you use must run the Windows 10 operating system. You must enable Developer mode on this machine.

See Installation Requirements for MAF Applications to be Deployed to the Windows Platform in Installing Oracle Mobile Application Framework.
Install the Visual Studio software from Microsoft. The Visual Studio package contains the Windows SDKs required to deploy applications to the UWP.

See Setting Up Development Tools for the Universal Windows Platform in Installing Oracle Mobile Application Framework.
Create a certificate (a personal information exchange file) to digitally sign the application you want to deploy.

See Creating a PFX File for MAF Applications in Installing Oracle Mobile Application Framework.
Enter the following values in the Windows Platform dialog shown below:
- The location of the Windows SDK that is installed with the Visual Studio software.
- The location and password (if required) for the certificate that you use to sign the application. Do this in both the Debug and Release dialogs if you intend to deploy your MAF application in both modes.
You access the Windows Platform dialog from the JDeveloper Tools menu by clicking Preferences, and then clicking Mobile Application Framework as shown in the figure.

Figure 25-19 Windows Platform Preferences to Deploy a MAF Application

Description of "Figure 25-19 Windows Platform Preferences to Deploy a MAF Application"

MAF provides a ready-to-use deployment profile (Windows1) to deploy a MAF application in the debug mode. Provided your development machine and environment meet the setup and configuration requirements, you can deploy the application either to a local machine or to a package.

You can edit this ready-to-use deployment profile or create one or more new deployment profiles. By creating a new deployment profile, or by editing an existing profile, you can:

Specify additional library and profile dependencies for your application.
Choose either the debug or release build modes.
Specify options such as the application bundle ID, the archive name and version.
Specify the images that the application uses to render its logo on the splash screen and the icon that appears on the user’s device.

For information about how to edit or create a deployment profile, see Working with Deployment Profiles. Click Help in the deployment profile dialogs for information about the fields that you can configure in each dialog.

Before you deploy your application, note the following issues that can prevent deployment:

Microsoft Windows imposes a maximum length for the path to directories and files. MAF application deployment fails if the path for a MAF application exceeds the maximum path length. To work around this issue, place the MAF application in a location where the directory path length is less than the maximum length mandated by Windows. For information about the maximum path length limitation, see Microsoft’s documentation.
Ensure no other process uses the MAF application’s data folder before you deploy the MAF application using the Deploy application to local machine option. The application data folder is typically located at C:\Users\[userName]\AppData\Local\Packages\[appBundleId]_[id]. An example of a scenario where another process uses this folder is if you have a file in the folder open with an application, such as Notepad. If you cannot determine what application process is using the directory/file(s), reboot your machine to resolve the issue.
When an application, which uses the Contacts plugin, is deployed to the UWP, ensure that the Contacts plugin is listed first in the list of plugins in the maf-plugins.xml file.

For information about how to debug an application that you deploy in the debug mode, see How to Debug Java Code on the Universal Windows Platform.

25.5.1 How to Deploy a MAF Application to the Universal Windows Platform

Deploy the application using a MAF for Windows deployment profile that deploys the application to the UWP.

To deploy a MAF application to the UWP:

From JDeveloper’s main menu, select Application, then Deploy, and then Windows1.
Where Windows1 is a MAF for Windows deployment profile.
Select the appropriate deployment option from the list in the dialog that appears.
Click Finish.

25.5.2 What Happens When You Deploy a MAF Application to the Universal Windows Platform

Depending on whether you select the Deploy application to local machine option, or the Deploy application to package option, MAF deploys the application to a computer or to an installation package.

If you select the Deploy application to local machine option, MAF deploys the application to the machine that you are using and installs the application there. In the foreground of the figure below is an instance of the WorkBetter sample application that has been deployed to a local machine in release mode. In the background of the figure below, you can view the WorkBetter sample application listed among the installed applications on the Apps & features page of the Windows 10 computer.

A red icon appears in the upper-left of a MAF application screen that you deploy in debug mode to indicate that the application is in debug mode. As with the application deployed in release mode, you can view and uninstall this application in the Apps & features page of the Windows 10 computer.

Figure 25-20 MAF Application Deployed in Release Mode on Windows Local Machine

Description of "Figure 25-20 MAF Application Deployed in Release Mode on Windows Local Machine"

If you select the Deploy application to package option, MAF deploys the application to an installation package in the following directory:

C:\path\to\appRoot\deploy\[DeploymentProfileName]\[deployMode]\MafTemplate\AppPackages

For example, the WorkBetter sample application, shown in the figure above, that deployed in release mode using the Windows1 deployment profile deployed to the following directory:

C:\...\PublicSamples\WorkBetter\deploy\Windows1\release\MafTemplate\AppPackages

The AppPackages directory contains another directory (MafTemplate_*_Test). Distribute the contents of this latter directory to the end users with supported UWP devices who want to install your MAF application. The directory includes a PowerShell script (Add-AppDevPackage.ps1) that end users execute to install the application. In addition to the script, the directory contains the application package, dependent packages, and the certificate that signed the application. The following example lists the contents:

Add-AppDevPackage.ps1                                 
Add-AppDevPackage.resources
Dependencies
MafTemplate_1.0.0.0_x64.appx
MafTemplate_1.0.0.0_x64.appxsym
MafTemplate_1.0.0.0_x64.cer

The name of the MafTemplate_*_Test directory and files depends on the Version number and Build mode that you specify in the Windows Options dialog, shown in the figure below. You access this dialog from JDeveloper’s Deployment page when you edit a deployment profile. To access the Deployment page, click Application and then Application Properties.

For example, if you specify 2 as the Version number and select the Debug build mode, the directory name is MafTemplate_2.0.0.0_x64_Debug_Test. A version number of 3 and the Release build mode produces a MafTemplate_3.0.0.0_x64_Test directory.

Figure 25-21 Windows Options Dialog for Deployment Profile

Description of "Figure 25-21 Windows Options Dialog for Deployment Profile"

25.6 Overview of MAF Quick Deployment of Applications

A quick deployment skips some deployment steps to save deployment time. Quick deployment saves time by passing only new or changed file content to an emulator or a simulator.

MAF quick deployment ensures developer productivity by providing competitive deployment times without deterioration of performance.

Quick Deployment of Applications

A quick deployment, as opposed to the normal full deployment, saves deployment time by skipping some deployment steps. A quick deployment passes only new or changed file content to an emulator or a simulator.

To use quick deployment on an Android emulator, select the Deploy application to emulator deployment action. For example, for a deployment profile named Android2, on the Application menu, select Deploy, then Android2, and then select a deployment action. See Deploy an Android Application to an Android Emulator. To use quick deployment on an iOS simulator, for a deployment profile named iOS2, from the Application menu, select Deploy, then iOS2, and then select a deployment action. See Deploy an iOS Application to an iOS Simulator.

Note:

The first deployment is a full deployment. A quick deployment may follow an initial full deployment.

The deployment of an application to an emulator or a simulator starts a Quick Deployment Session Analysis. The results of the analysis decide whether the deployment must be a quick deployment or a full deployment.

The Quick Deployment Session Analysis is initiated to detect application file changes. The MAF tool that analyzes application file changes triggers a quick deployment. If the analysis fails to find deployment artifacts from a previous Quick Deployment Session that used the same deployment profile, a full deployment is triggered.

MAF simplifies the deployment functionality. When you make changes to application files in JDeveloper, those changes are moved to the application that is deployed to an emulator or a simulator, thus removing the need for redeployment.

Key Features of Quick Deployment

The following features define quick deployment.

Quick deployment is supported for applications that are deployed to an Android emulator or an iOS simulator.
Virtual box images can be used for quick deployment provided that root access is configured for the images.
Changes made to an application in JDeveloper pushes the changes to the application deployed to an emulator or a simulator, without a full deployment, for example, changes to AMX pages or task flows. For the complete list of application changes, see Artifacts That Support Quick Deployment.
Deletion of files triggers a full deployment.
The quick deployment of an application only updates new or modified files. Quick deployment does no additional deployment processing.

25.6.1 About the Artifacts That Support Quick Deployment

Changes to certain artifacts, AMX pages, binding changes, and others, support MAF quick deployment.

Artifact Changes That Support MAF Quick Deployment

The following artifact changes support quick deployment:

Changes to AMX pages
Changes to task flows
Changes to bindings
Changes to maf-skins.xml
Addition of new style sheets and referencing them in maf-skins.xml
Changes to maf-config.xml
Changes to adf-config.xml
Changes to connections.xml
Changes to wsm-assembly.xml

25.6.2 About Requirements for Quick Deployment

A quick deployment is only initiated if the listed prerequisites are met.

Prerequisites for the Quick Deployment of a MAF Application

The quick deployment of an application starts when the following requirements are met:

An installed application is available on the target Android emulator or iOS simulator.
A unique bundle id for the MAF application.
An initial, full deployment must have been completed.

25.6.3 What Happens During a Quick Deployment Session

A Quick Deployment Session analyzes and determines whether a deployment must be a quick deployment or a full deployment. The session is initiated when an application is deployed.

The deployment of an application to an emulator or a simulator starts a Quick Deployment Session. The session analyzes and decides whether the deployment must be a quick deployment or a full deployment.

MAF Quick Deployment Session and Analysis

A quick deployment session proceeds as follows:

Conducts an initial quick deployment session analysis
Notes the application file changes:
- Since the last quick deployment session
- With the same deployment profile
If the changed files support quick deployment, the following steps for a quick deployment are completed. Otherwise, a full deployment follows.
- Copies the modified files to the emulator or simulator
- Restarts the application on the emulator or simulator

25.6.4 How to Start the Full Deployment of an Application

Certain actions can trigger the full deployment of an application. If you want the full deployment of an application, initiate an action from the list.

Actions That Trigger the Full Deployment of an Application

The following actions trigger the full deployment of an application:

JDeveloper is restarted.
Files are changed in non-MAF projects.
Java files in a MAF feature project are created, changed, or deleted.
Files are changed in a non-MAF project, and a Clean All is performed before deployment.
Files are deleted in the application, outside of MAF feature projects.
An application is deployed using a different deployment profile, a profile other than the one used in the previous quick deployment.
Some artifacts at the application level can trigger a full deployment. Changes to the following artifacts trigger a full deployment:
- maf-application.xml
- maf-feature.xml
- maf-plugins.xml
- maf.properties
- logging.properties

25.6.5 How to Force the Full Deployment of an Application

Certain actions, when initiated, can force the full deployment of an application. Initiate an action from the list to start a full deployment.

Certain user actions force the full deployment of a MAF application.

Actions That Force the Full Deployment of a MAF Application

The full deployment of an application can be forced in multiple ways. Use any of the following actions to trigger the full deployment of a MAF application:

Change any file that does not support quick deployment.
Click Build, and then click Clean All.
Uninstall an application on the Android emulator or iOS simulator.
Restart JDeveloper.

25.6.6 What You May Need to Know About Quick Deployment Limitations

Some limitations are associated with the quick deployment of MAF applications. The lists enumerate the limitations.

Quick Deployment Limitations: Files Deployment and User Actions

The following files cannot be deployed by means of quick deployment because they need additional processing during deployment:

Files that are created, updated, or deleted in any project other than a MAF ViewController or ApplicationController project
Application files that are deleted outside MAF feature projects
Files that are deleted from within any MAF feature project
New, changed, or deleted Java files
Changes to the following artifacts at the application level trigger a full deployment:
- maf-application.xml
- maf-feature.xml
- maf-plugins.xml
- maf.properties
- logging.properties

A quick deployment cannot be initiated in the context of the following user actions:

Changes or removes the emulator application that was installed by the previous quick deployment.
Deploys an application using a deployment profile other than the one used in the previous quick deployment.

Quick deployment neither detects nor handles the following changes:

The quick deployment of an application to a different emulator.
JDeveloper restart. After JDeveloper restarts, the first deployment is a full deployment. No user action is needed to ensure a full deployment after the restart. A quick deployment may follow an initial full deployment.

25.7 Deploying Feature Archive Files (FARs)

To enable re-use by MAF view controller projects, application features— typically, those implemented as MAF AMX or Local HTML— are bundled into an archive known as a Feature Archive (FAR).

A FAR is a JAR file that contains the application feature artifacts that can be consumed by mobile applications, such as icon images, resource bundles, HTML, JavaScript, or other implementation-specific files. (A FAR may contain Java classes, though these classes must be compiled.) The following example illustrates the contents of a FAR, which includes a single maf-feature.xml file and a connections.xml file.

/* Contents of a Feature Archive File */
connections.xml (or some form of connection metadata)
 
  META-INF
     adfm.xml
     maf-feature.xml
     MANIFEST.MF
     task-flow-registry.xml
 
  oracle
    application1
      mobile
         Class1.class
         DataBindings.cpx
         pageDefs
           view1PageDefs
 
  model
     adfc-mobile-config.adfc.diagram
     ViewController-task-flow.adfc.diagram
 
  public_html
     adfc-mobile-config.xml
       index.html
       navbar-icon.html
       springboard-icon.html
     view1.amx
     ViewController-task-flow.xml

Working with Feature Archive files involves the following tasks:

Creating a Feature Archive file—You create a Feature Archive by deploying a feature application as a library JAR file.
Using the Feature Archive file when creating a mobile application—This includes importing FARs and re-mapping the imported connection.
Deploying a mobile application that includes features from FARs—This includes unpacking the FAR to a uniquely named folder within the deployment template.

Note:

MAF generates FARs during the deployment process. You only need to deploy a view controller project if you use the FAR in another application.

25.7.1 How to Create a Deployment Profile for a Feature Archive

Create connections for the application, and then follow the steps in the task to create a deployment profile for a feature archive.

Use the Create Deployment Profile dialog.

Figure 25-22 Create MAF Feature Archive Dialog

Description of "Figure 25-22 Create MAF Feature Archive Dialog"

Before you begin:

Create the appropriate connections for the application. Because FARs may be used in different MAF applications with different connection requirements, choose a connection name that represents the connection source or the actual standardized connection name.

To create a deployment profile for a Feature Archive:

Right-click a view controller project, choose New, then Deploy, and then New Deployment Profile.

Note:

You do not need to create a separate, application-level deployment profile.
Select MAF Feature Archive in the Create Deployment Profile dialog.
Enter a profile name, or accept the default, and then click OK.

Note:

Name the profile appropriately. Otherwise, you may encounter problems if you upload more than one application feature with the same archive name. See What You May Need to Know About Enabling the Reuse of Feature Archive Resources.
Select the connections that you want to include in the Feature Archive JAR file.

Figure 25-23 Selecting a Connection for the FAR

Description of "Figure 25-23 Selecting a Connection for the FAR"
Click Next, review the options, and then click Finish.

25.7.2 How to Deploy the Feature Archive Deployment Profile

MAF provides the Deploy to feature archive JAR file option so that you can deploy a FAR as a JAR file. Follow the steps in the task to deploy the Feature Archive deployment profile.

The Deployment Actions dialog enables you to deploy the FAR as a JAR file. This dialog, shown in the figure below, includes only one deployment option, Deploy to feature archive JAR file.

Figure 25-24 Deployment Actions

Description of "Figure 25-24 Deployment Actions"

To deploy the Feature Archive deployment profile:

Right-click the view controller project and then select the Feature Archive deployment profile.
Click Finish. The Summary page, shown in the figure, displays the full path of where the JAR path of the Feature Archive file is deployed.

Figure 25-25 Deployment Summary Page

Description of "Figure 25-25 Deployment Summary Page"

25.7.3 What Happens When You Deploy a Feature Archive File Deployment Profile

MAF packages the content of the application feature into a JAR file (FAR) that it creates in the AppRoot/ViewController/deploy directory. This FAR includes AMX pages, task flows, icons, and the other resources that comprise the application feature.

The FAR does not include any shared libraries that the application feature consumed. Review the output in JDeveloper’s Deployment – Log window (Window > Log). If the application feature that you deployed to the FAR includes a shared library, MAF logs a message to notify you that the shared library has been excluded from the FAR. Notify MAF application developers who want to consume the FAR in their applications that they need to obtain the shared library separately if they want to use the shared library resources in their applications when they consume the FAR. For information about shared libraries, see Reusing MAF Application Content with a MAF Shared Library.

MAF application developers who consume a FAR in their MAF application need to create a file system connection to the directory that contains the FAR. Once they create this connection, the FAR and the application feature(s) it packages appear in the Resources window, as shown in the figure. For information about consuming a FAR in a MAF application, see Using FAR Content in a MAF Application.

Figure 25-26 Deployed Feature Archive JARs in the Resources Window

Description of "Figure 25-26 Deployed Feature Archive JARs in the Resources Window"

25.8 Creating a Mobile Application Archive File

A new mobile application can be created from an existing mobile application by packaging the original mobile application as a Mobile Application Archive (.maa) file or by creating a new mobile application from the .maa file.

You can create a new mobile application from an existing mobile application by:

Packaging the original mobile app as a Mobile Application Archive (.maa) file
Create a new mobile application from the .maa file, as described in Creating a New Application from an Application Archive.

An .maa file preserves the structure of the mobile application. Table 25-4 describes the contents of this file.

Table 25-4 Contents of a Mobile Application Archive File

Directory	Description
`adf`	Contains the `META-INF` directory, which contains the metadata files, including: The `adf-config.xml` file The `maf-application.xml` file The `maf-config.xml` file Other applicable application-level files, such as the `connections.xml`file
`Projects`	Contains a JAR file for each project in the workspace. For example, a `ViewController.jar` file and a `ApplicationController.jar` file are located in this directory when you deploy a default mobile application to an `.maa` file. The `Projects` directory of the `.maa` file does not include the `.java` files from the original project. Instead, the `.java` files are compiled and the resulting `.class` files are placed in a separate JAR file that is contained in the project JAR file (such as `ApplicationController.JAR/classlib/mobileApplicationArchive.jar`).
`ExternalLibs`	Contains the application-level libraries (including FARs) that are external to the original mobile application.
`META-INF`	Includes the `maf.properties` and `logging.properties` files.
`resources`	Includes the following directories: `android`—Contains Android-specific image files for application icons and splash screens. `ios`—Contains iOS-specific image files for application icons. security—Includes the `cacerts` file (the keystore file).

In addition to the artifacts listed in Table 25-4, the .maa file includes any folder containing FARs or JAR files that are internal to the original mobile application, as well as its control (.jws)file. See also What Happens When You Import a MAF Application Archive File.

Note:

Importing an .maa file into an existing application overwrites the workspace and project container files (the.jws and .jpr files, respectively). As a result, all prior changes to MAF AMX pages and configuration files, such as maf-application.xml, maf-config.xml, connections.xml, and adf-config.xml, will not be retained.

25.8.1 How to Create a Mobile Application Archive File

Follow the steps in the task to use Mobile Application Archive wizard to create a .maa file. You can also create a .maa file using OJDeploy.

JDeveloper creates a default MAF Application Archive deployment profile after you create a mobile application. Using the Mobile Application Archive wizard, you can create the .maa file.

Tip:

You can also create an .maa file using OJDeploy, as described in Deploying MAF Applications from the Command Line.

To create a Mobile Application Archive file:

Click Application, then Deploy, then New Deployment Profile.
In the Create Deployment Profile dialog, select MAF Application Archive and then click OK.

Figure 25-27 Creating an MAA Deployment Profile

Description of "Figure 25-27 Creating an MAA Deployment Profile"
If needed, enter a name for the Mobile Application Archive in the Application Archives Options page, or accept the default name (and path). Click OK.

Figure 25-28 Entering a Name and Path for the Mobile Application Archive File

Description of "Figure 25-28 Entering a Name and Path for the Mobile Application Archive File"
If needed, perform the following:
1. In the Application Descriptors page, enter the file group name (or accept the default name) used for the contents of the META-INF folder (application_workspace\src\META-INF).
  
  Figure 25-29 Entering a File Group Name for the META-INF Contents
  
  Description of "Figure 25-29 Entering a File Group Name for the META-INF Contents"
2. Select the Contributors sub-page of this Application Descriptors page to edit the list of directories and JAR files that provide the contents for the file group.
  
  Figure 25-30 Editing Contributors to the Mobile Application Archive File
  
  Description of "Figure 25-30 Editing Contributors to the Mobile Application Archive File"
3. Use the Filters page to edit the files that will be included in the .maa file or set the content inclusion or exclusion rules.
  
  Figure 25-31 Including (or Excluding) Files and Directories
  
  Description of "Figure 25-31 Including (or Excluding) Files and Directories"
4. Use the Profile Dependencies page to specify dependent profiles within the project.
  
  Figure 25-32 Selecting Deployment Profiles
  
  Description of "Figure 25-32 Selecting Deployment Profiles"

To package a mobile application as a MAF Application Archive file:

Choose Application, then Deploy and then choose the MAF Application Archive deployment profile.
In the Deployment Action wizard, select Deploy application to MAA.

Figure 25-33 Deployment to a MAF Application Archive File

Description of "Figure 25-33 Deployment to a MAF Application Archive File"
Click Next to review the deployment summary.

Figure 25-34 MAF Application Archive Deployment Summary

Description of "Figure 25-34 MAF Application Archive Deployment Summary"
Click Finish.

25.9 Creating a New Application from an Application Archive

Use an application archive file to create a new MAF application that facilitates various customizations.

You or others (for example, a colleague or a partner) can create a new MAF application using an application archive file (.maa) as a starting point. By deriving a mobile application from an .maa file, you enable various customizations, which include:

Giving an application a unique application ID (to enable push notifications, for example).
Signing an application with a company-specific credential or certificate.
Replacing the resources with customized splash screens and application icons.

The MAF Application Archive (.maa) file format enables you to provide third-parties with an unsigned mobile application.

Note:

25.9.1 How to Create a New Application from an Application Archive

Follow the steps in the task to use the MAF Application from Archive File option and import a.maa file into a new mobile application.

You import an .maa file into a new mobile application.

To create a new application from an application archive:

Select File and then New.
In the New Gallery, select Applications and then MAF Application from Archive File.

Note:

Alternatively, you can select File, then Import, and then MAF Application from Archive File.
In the Location page, select Browse in the MAA File field to navigate to the location of the MAA file.
If needed, perform the following, or accept the default values:
1. Enter a name for the mobile application derived from the .maa file in the Application File field.
2. Click Browse to retrieve the directory of the mobile application.
Figure 25-35 Entering the Directory Location

Description of "Figure 25-35 Entering the Directory Location"
Click Next to review the import summary information and then click Finish.

25.9.2 What Happens When You Import a MAF Application Archive File

MAF creates an application folder into which it unpacks relevant directories and their contents. For every JAR file within the Projects directory, MAF creates a project folder, and unpacks the contents of the JAR files into the appropriate project folder.

MAF performs the following after you import an .maa file:

Creates an application folder.
Unpacks the workspace container (.jws) file from the .maa file to the application file and renames it per the user-specified value.
Unpacks the adf directory and its contents to the application folder. This directory is renamed .adf.
Unpacks the META-INF directory and its contents and places them in a src directory in the application folder.
Unpacks the ExternalLibs directory and its contents to the application folder.

Note:

While any of the external resources contained in this directory are available in the mobile application that has been packaged as an .maa file (and imported into the application), the references to these resources will be invalid for a mobile application derived from the .maa file.
Unpacks the resources directory to the application folder.
Unpacks all folders that contain FARs (or other libraries) that are internal to the original mobile application. MAF preserves the original locations of these artifacts.
For each JAR file within the Projects directory of the original mobile application, MAF performs the following:
- Creates a project folder under the application directory that corresponds to the name of the JAR file (but without the .jar extension).
- Unpacks the contents of the JAR files into the appropriate project folder. MAF includes the following in these project folders:
  - The original .jpr file.
  - The standard directories, such as META-INF, public_html, src, and adfmsrc.
  - The contents of the ExternalLibs directory.
    
    Note:
    
    While any of the external resources contained in this directory are available in the MAF project that has been packaged with the imported .maa file, the references to these resources will be invalid for an existing project, or a project created by importing the .maa file.
  - The classlib directory, which contains any Java classes packaged in a JAR file.
    
    Note:
    
    If the .maa file includes a classlib directory, then MAF adds all of the JAR files from this directory as library dependencies in the newly created mobile application.

25.10 Deploying MAF Applications from the Command Line Using OJDeploy

You can deploy MAF applications to Android, iOS, and UWP devices using the OJDeploy command line tool. Command line deployment can serve as a tool for testing, as well as a means of deploying applications using a script.

After you have created deployment profiles, you can use OJDeploy to deploy applications in the headless mode to iOS simulators or as iOS bundles (.ipa and .app files), or Feature Archive JAR files. Likewise, OJDeploy enables you to deploy applications to both Android emulators and Android-powered devices, or deploy them as an Android application package (.apk) file or as Feature Archive JAR files. Similarly, OJDeploy enables you to deploy Windows applications to a local machine or as an application installation package (.appx file).

Note:

To use OJDeploy on a Mac, add the following line to the ojdeploy.conf file:

SetSkipJ2SDKCheck true

This file is located at: jdev_install/jdeveloper/jdev/bin

MAF downloads and installs the Gradle build tool the first time that you deploy a MAF application to the Android platform. If your development machine is located behind a corporate firewall, configure the Gradle proxy settings so that MAF can successfully download, install, and configure Gradle. See How to Configure Gradle Proxy Settings.

The following commands enable you to deploy MAF deployment profiles:

deployToDevice—Deploys an application to an Android-powered device.
deployToSimulator—Deploys an application to an iOS simulator (as an .app file) or Android emulator. You can only deploy a mobile application to an iOS simulator on an Apple computer.
deployToPackage—Deploys an iOS application as an .ipa file, an Android application as an .apk file, or a UWP application as an installation package (.appx file). You can only package an application as an .ipa file on an Apple computer. You can only package an application as an .appx file on a Microsoft Windows 10 computer.
deployToLocalMachine—Deploys a MAF application to a Windows local machine.
deployToFeatureArchive—Deploys a Feature Archive to a JAR file.
deployToApplicationArchive—Packages a mobile application as a MAF Application Archive (.maa) file.

You use these commands in conjunction with the ojdeploy command line tool, OJDeploy arguments, and OJDeploy options as follows:

ojdeploy deployToSimulator -profile <profile name> -workspace <jws file location>

Note:

OJDeploy commands and arguments are case-sensitive.

Table 25-5 lists the OJDeploy arguments that you use to modify the MAF deployment commands.

Tip:

Using the -help option with any command (such as ojdeploy deployToSimulator -help) retrieves usage and syntax information.

Table 25-5 OJDeploy Arguments for MAF Deployments

Argument	Description
`-profile`	The name of the Android, Windows, or iOS deployment profile. For example: ojdeploy deployToSimulator -profile iosDeployProfile ...
`-workspace`	The full path to the mobile application workspace container (`.jws`) file. For example: ... -workspace /usr/jsmith/mywork/Application1/Application1.jws To package a mobile application as a mobile Application Archive: ojdeploy deployToApplicationArchive -profile applicationArchiveProfile -workspace /usr/jdoe/Application1/application1.jws
`-project`	For the `deployToFeatureArchive` command, you must provide the name of the project (that is, a view controller project) that contains the Feature Archive deployment profile. For example: ojdeploy deployToFeatureArchive -profile farProfileName -project ViewController ...
`-buildfile`	The full path to a build file for batch deploy.
`-buildfileschema`	Print XML Schema for the build file.

In addition to the arguments listed in Table 25-5, you can also use OJDeploy options described in Deploying from the Command Line of Developing Applications with Oracle JDeveloper.

Note:

The following options are not supported:

-forcerewrite
-nocompile
-nodatasources
-nodepdendents
-outputfile
-updatewebxmlejbrefs

Table 25-6 provides examples of how to use the OJDeploy options with the MAF deployment commands.

Table 25-6 OJDeploy Options for MAF Deployments

Option Description

Option	Description
`-clean`	Deletes all files from the project output directory before compiling. For example: ojdeploy deployToSimulator -profile iosDeployProfile -workspace /usr/jsmith/jdeveloper/mywork/Application1.jws -clean
`-stdout, -stderr`	Redirects the standard output and error logging streams to a file for each profile and project. For example: ojdeploy deployToSimulator -profile iosDeployProfile -workspace /usr/jsmith/jdeveloper/mywork/Application1.jws -clean -stdout /usr/jsmith/stdout/stdout.log -stderr /usr/jsmith/stderr/stderr.log

-clean

Deletes all files from the project output directory before compiling. For example:

ojdeploy deployToSimulator 
         -profile iosDeployProfile
         -workspace /usr/jsmith/jdeveloper/mywork/Application1.jws 
         -clean

-stdout, -stderr

Redirects the standard output and error logging streams to a file for each profile and project. For example:

ojdeploy deployToSimulator -profile iosDeployProfile
         -workspace /usr/jsmith/jdeveloper/mywork/Application1.jws 
         -clean
         -stdout /usr/jsmith/stdout/stdout.log
         -stderr /usr/jsmith/stderr/stderr.log

Table 25-7 lists the macros used with the deployToApplicationArchive command:

Table 25-7 Macros Used with MAF Application Archive Packaging

Macros	Description
`workspace.name`	The name of the application workspace container file (without the `.jws` extension).
`workspace.dir`	The directory of the application workspace container (`.jws`) file.
`profile.name`	The name of the profile being deployed.
`profile.dir`	The default deployment directory for the profile.
`base.dir`	Override the current OJDeploy directory using this parameter. You can also override the current OJDeploy directory using the basedir attribute in the build script.