25 Deploying MAF Applications
This chapter includes the following sections:
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.
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.
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.
Using the Deployment Action page, shown in the figure below, you then select the appropriate 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 follows Description of Figure 25-3 follows](img/editing_default_deployment_profile.png)
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). You can include or exclude FARs 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 follows Description of Figure 25-4 follows](img/edit_autoprofile.png)
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 follows Description of Figure 25-5 follows](img/edit_defaultfar.png)
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.
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 requires the creation of an application-level deployment profile and configuration of relevant dependencies. Default deployment profiles and associated dependencies are automatically created only when you create a new MAF application. If you update an existing MAF application with a new application-level deployment profile or deploy an application-level deployment profile, Jdeveloper does not create associated project-level FAR deployment profiles or setup any dependencies.
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:
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 any project-level FAR files specified as dependencies to the application-level profile.
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.
Table 25-1 MAF-Specific Deployment Profile Pages
Page | Function |
---|---|
iOS Options |
Enables you to modify the settings for an application to be deployed to an iOS-powered device or iOS simulator. |
Android Options |
Enables you to modify the settings for an application to be deployed to an Android-powered device or Android emulator. |
Windows Options |
Enables you to modify the settings for an application to be deployed 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.
Note:
If you update an existing MAF application with a new application-level deployment profile or deploy an application-level deployment profile, no automatic changes are made. MAF doesn't automatically create project deployment profiles and manage dependencies for existing applications. To successfully deploy an existing application using a new application-level profile, configure the newly-created application-level deployment profile to reference a new or existing project-level deployment profile.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 the CPU type for deployment (ARM, x86, or both)
-
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 follows Description of Figure 25-7 follows](img/releasemode.png)
Description of "Figure 25-7 Release Mode in Deployment Profile Properties"
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.
-
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.
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 (https://www.oracle.com/technetwork/java/javase/documentation/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.
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.
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.
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
andmaf-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 follows Description of Figure 25-9 follows](img/deployment-debugmode.png)
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.
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.
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 follows Description of Figure 25-11 follows](img/android_prtimage.png)
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.
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) |
---|---|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
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.
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 follows Description of Figure 25-12 follows](img/iosdeployaction.png)
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.
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.
-
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:
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:
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 follows Description of Figure 25-13 follows](img/deployment-debugmode-ios.png)
Description of "Figure 25-13 MAF Application Deployed in Debug Mode"
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:
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.
To limit the display of an application to a specific device orientation:
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:
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.
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:
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.
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.
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.
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.
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.
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.
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:
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 follows Description of Figure 25-19 follows](img/windows_pref_vs2017.png)
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.
-
Modify the background color of the splash screen.
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 atC:\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.
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.
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 follows Description of Figure 25-20 follows](img/windeploy.png)
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 follows Description of Figure 25-21 follows](img/windowsoptions.png)
Description of "Figure 25-21 Windows Options Dialog for Deployment Profile"
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.
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
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.
-
Root access if deploying to an Android emulator.
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
-
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
-
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.
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.
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.
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 follows Description of Figure 25-22 follows](img/createfardialog.png)
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:
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.
To deploy the Feature Archive deployment profile:
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 follows Description of Figure 25-26 follows](img/resourcepalette.png)
Description of "Figure 25-26 Deployed Feature Archive JARs in the Resources Window"
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 |
---|---|
|
Contains the
|
|
Contains a JAR file for each project in the workspace. For example, a |
|
Contains the application-level libraries (including FARs) that are external to the original mobile application. |
|
Includes the |
|
Includes the following directories:
|
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.
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:
-
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" -
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" -
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" -
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.
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:
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.
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:
-
Enter a name for the mobile application derived from the
.maa
file in the Application File field. -
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.
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 asrc
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
, andadfmsrc
. -
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 aclasslib
directory, then MAF adds all of the JAR files from this directory as library dependencies in the newly created mobile application.
-
-
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 |
---|---|
|
The name of the Android, Windows, or iOS deployment profile. For example: ojdeploy deployToSimulator -profile iosDeployProfile ... |
|
The full path to the mobile application workspace container ( ... -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 |
|
For the ojdeploy deployToFeatureArchive -profile farProfileName -project ViewController ... |
|
The full path to a build file for batch deploy. |
|
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 |
---|---|
|
Deletes all files from the project output directory before compiling. For example: ojdeploy deployToSimulator -profile iosDeployProfile -workspace /usr/jsmith/jdeveloper/mywork/Application1.jws -clean |
|
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 |
---|---|
|
The name of the application workspace container file (without the |
|
The directory of the application workspace container ( |
|
The name of the profile being deployed. |
|
The default deployment directory for the profile. |
|
Override the current OJDeploy directory using this parameter. You can also override the current OJDeploy directory using the basedir attribute in the build script. |