27 Deploying Mobile Applications

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

This chapter includes the following sections:

Section 27.1, "Introduction to Deployment of Mobile Applications"
Section 27.2, "Working with Deployment Configurations"
Section 27.3, "Deploying Feature Archive Files (FARs)"
Section 27.4, "Creating a Mobile Application Archive File"
Section 27.5, "Creating Unsigned Deployment Packages"
Section 27.6, "Deploying with Oracle Mobile Security Suite"

27.1 Introduction to Deployment of Mobile Applications

Before you can publish an application for distribution to end users, you must test it on a simulator or on an actual device to assess its behavior and ease of use. By deploying an iOS application bundle (.ipa and .app files) or Android application package (.apk) file to the platform-appropriate device or simulator, MAF enables you to test applications before publishing them to the App Store (Apple iTunes), or to an application marketplace, such as Google Play.

27.1.1 How OEPE Deploys Applications

MAF executes the deployment of a project 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 (.ipa, .h for Android) which you can make available from a download site or application marketplace, such as the Apple App Store or Google Play. For testing and debugging, you can deploy to a simulator or to a device.

The actual process of deployment consists of three steps:

First, you register the SDK for the platform (Android or iOS) in the Preferences dialog. For more information, see Oracle Enterprise Pack Installing Oracle Enterprise Pack for Eclipse.
For each MAF application, define a target. The target is a combination of a platform (Android or iOS) and a specific version of the MAF runtime. By default, when you create an application, OEPE creates a target for each of the SDK platforms registered. You can define additional targets through the Project Properties dialog, available from the context menu of the assembly project. Choose Mobile Application Framework, and define a new target by clicking Add.
Create a debug or run configuration, and execute it.

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.

27.1.1.1 Deployment of Project Libraries

The libraries that you declare for the project using the Properties dialog, shown in Figure 27-1, are included in the deployment artifacts for the project. This dialog enables the application features to access these libraries at runtime.

Open the Properties dialog by right-clicking the view project and choosing Properties. In the dialog, choose Java Build Path, then click the Libraries tab, as shown in Figure 27-1.

Figure 27-1 Adding Libraries to the Project

This image is described in the surrounding text

27.1.1.2 Deployment of the JVM 1.4 Libraries

For both Android and iOS applications, each MAF deployment includes a set of a 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 JAR file of JVM 1.4. The application binding layer resides within this virtual machine, which is a collection of Objective-C libraries. For example, MAF deploys a JVM 1.4 JAR file and a set of libraries for a debug deployment targeted at an iOS simulator, but deploys a different JVM 1.4 JAR file and set of libraries to a debug deployment targeted to an actual iOS-powered device.

27.2 Working with Deployment Configurations

Preparing mobile applications for deployment begins with the creation of platform-specific deployment configurations. The configuration defines how an application is packaged into the archive that will be deployed to iOS- or Android-powered devices, iOS simulators, or Android emulators.

You can choose between debug configurations and production configurations. During development, you should choose debug in order to use the default keystore.

The configuration does the following:

Selects the assembly project to package and deploy.
Selects the Target to deploy to. The target is a combination of a platform (Android or iOS) and a specific version of the MAF runtime.
Selects the device profile, that is the emulator or device, to deploy to.
Selects platform-specific, that is Android or iOS, advanced options.
Specifies the application to deploy.

27.2.1 How to Create a Deployment Configuration

As described in Section 2.2.2.3, "About Deployment Configurations,"when you create an application you choose the deployment targets for the application. Later, when you create the deployment configuration you choose the deployment targets to use. You can deploy an application using these configurations, edit them, or construct new ones using the MAF-specific configurations dialog. The Create, manage, and run configurations dialog also called the deployment configurations dialog, shown in Figure 27-2, enables you to create a default deployment. You can create as many deployment configurations as needed.

Before you begin:

To enable OEPE to deploy mobile applications, you must designate the SDKs for the target platforms using the MAF Preferences page.

Tip:

For iOS deployments, run iTunes and the iOS Simulator at least once before you configure their directory locations in the MAF Platforms preferences page.

To create a deployment configuration:

For development, choose Run and then Debug Configurations.

For production, choose Run and then Run Configurations
Navigate to MAF Application, and right-click and choose New to create a new configuration (see Figure 27-2).
Do the following:
- Accept the default name for the configuration or enter a new one.
- Choose the Assembly project.
- Choose the target from the list of those available and the device or emulator from the list of those available. If necessary, refresh the list.
- If necessary, select the keystore and key alias for the device you are deploying to.
If you want to deploy immediately, click Run. To save the configuration click Apply. Alternatively click Close and in the Save Changes dialog, click Yes.

Figure 27-2 Creating a Run Configuration

27.2.2 What Happens When You Create a Deployment Configuration

When you deploy an application by clicking the Run button or the Debug button, it triggers the packaging and deployment of the application. OEPE creates a deployment directory and related subdirectory. It also creates Feature Archive files (FARs) for the view projects (which must have different names) and assembly project. In addition to these two FARs, OEPE creates copies of any FARs that were imported into the project. Finally, the package is deployed to the device or emulator.

To clean the deploy artifacts, use the Clean dialog to just one set of projects, or all projects. You can clean:

Just one set of projects. This is the fastest way to do a clean-rebuild.

Select Clean projects selected below then select the assembly project you want to clean, and click OK.
All projects. This ensures that all user artifacts get rebuilt before being re-staged and deployed.

Choose Clean all projects, and click OK.

Once you have created a run configuration, you can select it by clicking the green Run arrow from the menu bar. Clicking the arrow will select the last-used run configuration. You can select a different run configuration by clicking the drop-down selector next to the green arrow and choosing the configuration you wish to run from the context menu.

27.2.3 Differences Between Run Configurations and Debug Configurations

The Run Configurations and Debug Configurations are both invoked from the Run menu, and they differ in that Debug Configurations has an additional tab, the Debug tab, where you set debug options. For more information, see Chapter 30, "Testing and Debugging MAF Applications.".

Debug—Select this option for development builds. Designating a debug build results in the inclusion of debugging symbols.

During development, you should choose debug in order to use the default keystore.

At runtime, MAF indicates that an application has been deployed in the debug mode by overlaying a debugging symbol that is represented by an exclamation point within a red triangle.
Run—Select to compile the build ready for release, with libraries, and so on. release bits and libraries, and so on.

Tip:
Use the run mode, where the application is compiled for release, not the debug mode, to test application performance.

27.2.4 How to Create an Android Deployment Configuration

To create the deployment profile for Android, you must define the signing options for the application, the behavior of the javac compiler, and if needed, override the default Oracle images used for application icons with custom ones.

Before you begin:

Install and download the Android SDK as described in Oracle Enterprise Pack Installing Oracle Enterprise Pack for Eclipse.

If you deploy to an Android emulator, you must create a virtual device for each emulator instance using the Android Virtual Device Manager, as described in the "Managing Virtual Devices" document, available from the Android Developers website (http://developer.android.com/tools/devices/index.html).

You must also set the MAF preferences for the locations for the SDK and platform, which are part of the Android SDK package download

To set the MAF preferences for the Android platform SDKs

Choose Window > Preferences to open the Preferences dialog.
Navigate to Oracle > Mobile Application Framework > Android to open the Android preferences page, as show in Figure 27-3.

Figure 27-3 Setting Android Preferences
Click Add to open the Select SDK dialog, and navigate to the location of the Android SDK. Click OK.

The SDK information for Android 4.4.2 (API 19), which is illustrated in Figure 27-4, differs from earlier versions.

Note:

Push notifications require devices and emulators running Android 2.2 platform (or later). The Google Play store must be installed on these devices. The Google API must be installed in the SDK to enable push notifications on emulators. Users must create a Google account (and be logged in) on devices running platforms earlier than 4.0.3 (API 15).

See also "GCM Architectural Overview" chapter in Google Cloud Messaging for Android, available from the Android Developers website (http://developer.android.com/index.html) and Section 27.2.4, "How to Create an Android Deployment Configuration."

To create the configuration

Select Run > Run Configurations to open the Configurations dialog.
In the Configurations dialog, shown in Figure 27-4, enter a name for the configuration.
Choose the assembly Project from the list of those available.
If you want to change the application ID, enter a new one in Deployed Bundle Id.

Note:
To ensure that an application deploys successfully to an Android-powered device or emulator, the ID must begin with a letter, not with a number or a period. For example, an ID comprised of a wholly numeric value, such as 925090 (com.company.925090) will prevent the application from deploying. An ID that begins with letters, such as hello925090 (com.company.hello925090) will enable the deployment to succeed.
Choose the target, which is combination of the platform version and the MAF runtime version.
Choose the target configuration, that is, the device or emulator where the application is to be deployed.
Note:
Sometimes OEPE cannot detect an Android emulator because the daemon associated with the adb server is not running. When the daemon is not running, OEPE displays an error message:
Either the target device is not set or the selected device is invalid. Click Refresh if your device doesn't show in the dropdown. If you do not see your device, run the command 'adb devices' to check the status of your device.

Running adb devices from the SDK/platform-tools directory starts the daemon as below:
```
<sdk-install>\adt-bundle-windows-x86_64-20130717\sdk\platform-tools>adb devices
* daemon not running. starting it now on port 5037 *
* daemon started successfully *
List of devices attached
emulator-5554 device
```
OEPE will then detect the emulator.
Enter the keystore. If necessary, click Select Keystore which opens the Android Keystores page of the Preferences dialog where you can add a keystore. For more information, see Section 27.2.4.3, "Defining the Android Signing Options." See also the application publishing information in the "Signing Your Applications" document, available from the Android Developers website (http://developer.android.com/tools/publishing/app-signing.html).

Figure 27-4 Setting the Android SDK and Signing Properties

Note:
To deploy an application to an Android emulator, you must install API 14 or later (that is, Platform 4.0.n)

27.2.4.1 Setting Advanced Options

The Advanced Android Options page, shown in Figure 27-4, enables you to do the following:

Set a number of advanced options, including the minimum SDK API level, the target SDK API level, the version code, source files, class files, zip alignment, and preferred storage location, as shown in Figure 27-5

Figure 27-5 Setting SDK Levels
Change the default application images, as shown in Figure 27-6.

Figure 27-6 Setting Application Images

27.2.4.2 Setting Deployment Options

The Main and Common tabs of the deployment configurations dialog, and the Advanced Android Options dialog, invoked from the Advanced Options button, enable you to set values that are passed in by the javac compiler tool options, and also the Android API revisions.

To set the JDK-Compatibility level for the R.java and .class files:

In the deployment configuration dialog, click the Options button to open the Advanced Options dialog.
Select the minimum API Level on which the application is able to run from the Minimum SDK API Level dropdown list. The minimum and default value is 15, which corresponds to Android 4.0.3 platform.
Select the intended API Level on which the application is designed to run from the Target SDK API Level dropdown list. The minimum (and default) value is API Level 9, which corresponds to the Android 2.3.n platform. For more information, refer to the description of the <uses-sdk> attribute in the document entitled "The AndroidManifest.xml File," available through the Android Developers website (http://developer.android.com/guide/topics/manifest/manifest-intro.html).

27.2.4.3 Defining the Android Signing Options

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 mobile application is a two-step process: within the MAF Platforms preference page, you first define release properties for a key that is used to sign Android applications. You only need to configure the release signing properties once. After you define these options, you configure the deployment profile to designate if the application should be deployed in the release mode.

Before you begin:

OEPE creates a keystore if one does not exist. In addition, you can create one using the keytool utility, as illustrated in the next example.

keytool -genkey
        -v
        -keystore c:\oepe\workspace\releasesigning.keystore
        -alias releaseKeyAlias
        -keyalg RSA
        -keysize 2048
        -validity 10000

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. In the example above, the keystore contains a single key, valid for 10,000 days. Refer to Java SE Technical Documentation (http://download.oracle.com/javase/index.html) for information on how to use the keytool utility.

Tip:

Use the -genkeypair instead of the -genkey command for Java Platform Standard Edition (Java SE) 7.

To configure the key options:

Choose Window > Preferences > Oracle > Mobile Application Framework > Android Keystore.
Click Add and in the Select Keystore dialog, navigate to the location of the keystore, as shown in Figure 27-7 and click OK.

Figure 27-7 Selecting the Keystore Location
Enter the password for the keystore. When you enter a correct password, the Add button is enabled.
Click Add to open the Select Key Alias dialog, as shown in Figure 27-8.

Figure 27-8 Selecting the Key Alias
Enter the password for the key alias and click OK.

The keystore and key alias are now available to be used in the deployment configuration dialog.

To Set the Android build mode:

Do one of the following:
- From the Run menu, select Debug Configurations. Select Debug for developing and testing an application (such as Java and JavaScript debugging). This option enables you to deploy an application on the Android platform without having to provide a private key. Use this option when deploying an application to an Android emulator or to an Android-powered device for testing. See also Section 30.3.5, "How to Enable Debugging of Java Code and JavaScript."
  
  Note:
  You cannot publish an application signed with the debug keystore and key; this keystore and key are used for testing purposes only and cannot be used to publish an application to end users.
- From the Run menu, select Run Configurations. When the application is ready to be published, select Release. Use this option when the application is ready to be published to an application marketplace, such as Google Play.
In the deployment configuration dialog, after the .apk file is signed in either debug or release mode, you can deploy it to a device or to an emulator. At runtime, MAF indicates that an application has been deployed in debug mode by overlaying a debugging symbol that is represented by an exclamation point within a red triangle, as shown in Figure 27-9.

Figure 27-9 Deployment Modes

27.2.4.4 What You May Need to Know About Credential Storage

Credentials for keystore access are stored in Eclipse Secure Storage, which stores data outside the workspace. The location is usually in your home directory, although the specific location varies depending on the OS platform.

To find the Secure Storage Location

From the main menu, choose Window > Preferences to open the Preferences dialog.
Expand the nodes General > Security > Secure Storage to display the Secure Storage page.
Click the Contents tab. The storage location is displayed at the bottom of the dialog, for example, user-home/.eclipse/org.elipse.equinox.security/secure_storage.
You can see the passwords that are stored by expanding nodes oracle > eclipse > tools > oepe > maf > android > keystores.

There is a node for each keystore that is declared in the Oracle > Mobile Application Framework > Android > Android Keystores page of the Preferences dialog.

Click on the node to show the data (the password is obfuscated).

Note:

Because iOS keys are Mac-specific, there is no need to store them in Eclipse. The iOS XcodeBuild will extract them directly from the Mac Keychain based on the mobileprovision that is specified at launch (configured from the Oracle >Mobile Application Framework > Android > Android Keystores page of the Preferences dialog).

27.2.4.5 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-, and 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 Figure 27-10, 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. To create custom images, refer to the "Iconography" document, available from the Android Developers website (http://developer.android.com/design/style/iconography.html).

Figure 27-10 Setting Custom Images for an Android Application

Figure 27-10 shows selecting images for application icons and portrait orientation splash screen images that applications use for displaying on devices with low-, medium-, high- and extra-high density displays.

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. The default location for images in assembly directory\res\android For more information, see "Supporting Multiple Screens" document, available from the Android Developers website (http://developer.android.com/guide/practices/screens_support.html).

To add custom images:

Click Run > Run Configurations to open the deployment configuration dialog.
Click Options to open the Advanced Android Options dialog, and then click the Application Images tab.

Choose the density of the image you want to change, then expand the appropriate node to choose the image you want to change.
Click Browse to select the new image you want to use and click OK.

27.2.4.6 What Happens When OEPE Deploys Images for Android Applications

As shown in Table 27-1, 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, and xhdpi) and orientation (port, land). Within these directories, OEPE renames each icon image file as adfmf_icon.png and each splash screen image as adfmf_loading.png.

Note:

In order to view the contents of assembly project\.main.android, you must change the default view of the Project Explorer. For more information, see Section 2.2.2, "What Happens When You Create an MAF Application."

Table 27-1 Deployment File Locations for Seeded Application Images

Source File (...\res\android)	Temporary Deployment File (...\.main.android\build\release\res)
`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-port-ldpi-splashscreen.png`	`drawable-port-ldpi\adfmf_loading.png`
`display-port-mdpi-splashscreen.png`	`drawable-port-mdpi\adfmf_loading.png`
`display-port-hdpi-splashscreen.png`	`drawable-port-hdpi\adfmf_loading.png`
`display-port-xhdpi-splashscreen.png`	`drawable-port-xhdpi\adfmf_loading.png`
`display-land-ldpi-splashscreen.png`	`drawable-land-ldpi\adfmf_loading.png`
`display-land-mdpi-splashscreen.png`	`drawable-land-mdpi\adfmf_loading.png`
`display-land-hdpi-splashscreen.png`	`drawable-land-hdpi\adfmf_loading.png`
`display-land-xhdpi-splashscreen.png`	`drawable-land-xhdpi\adfmf_loading.png`

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

27.2.5 Deploying an Android Application

After you define the deployment configuration, you can deploy a mobile application to the Android platform from the run configuration dialog or debug configuration dialog, as shown in Figure 27-11.

Using debug configuration dialog, you can deploy the completed application to an Android emulator or to an Android-powered device for testing. After you have tested and debugged the application, you can use the run configuration dialog to bundle the mobile application as an Android application package (.apk) file so that it can be published to end users through an application marketplace, such as Google Play.

Figure 27-11 Deployment Configuration Dialog for Android Applications

27.2.5.1 How to Deploy an Android Application to an Android Emulator

You can deploy the mobile application directly to an Android emulator.

Before you begin:

Deployment to an Android emulator requires the following:

Configure the keystore password and key alias details in the Android Platform preference page (accessed by choosing Window > Preferences > Oracle > Mobile Application Framework > Android > Android Keystore).

Note:
You must install the Android 4.0.n platform (API 14 or later).
Ensure that the Android Virtual Device instance configuration reflects the ARM system image.
Start the Android emulator before you deploy an application.

You can start the emulator using the Android Virtual Device Manager, as illustrated in Figure 27-12, or from the command line by first navigating to the tools directory (located in Android\android-sdk) and then starting the emulator by first entering emulator -avd followed by the emulator name (such as -avd AndroidEmulator1).

Note:
You can run only one Android emulator at a time.

Figure 27-12 Starting an Emulator Using Android Virtual Device Manager

To deploy an application to an Android emulator:

Choose either Run, then Run Configurations or Run, then Debug Configurations. Under the MAF Applications node select an Android deployment profile.
Check that the target is the one you want to use, and click either Run or Debug.

Occasionally the deployment process may hang. In this case, kill the adb server then restart it, and retry the deployment.
Review the deployment log in the console, as shown in Figure 27-13. The deployment log notes that the deployer starts the Android Debug Bridge server when it detects a running instance of an Android emulator.

Figure 27-13 The Deployment Log

27.2.5.2 How to Deploy an Application to an Android-Powered Device

You can deploy a mobile application directly to an Android-powered device that runs on a platform of 2.n (API Level 9) or later.

Before you begin:

Connect the device to the development computer that hosts OEPE, as described in Oracle Enterprise Pack Installing Oracle Enterprise Pack for Eclipse.

In the Deployment Options page, shown in Figure 27-4, select Debug as the build mode. Ensure that the debug signing credentials are configured in the Android Platform preference page, shown in Figure 27-4.

To deploy an application to an Android device:

Choose Run, then Run Configurations to open the Run Configurations dialog. Under the MAF Applications node select an Android deployment profile.
Check that the target is the one you want to use, and click Run.
Review the deployment log in the console, as shown in Figure 27-13. The deployment log notes that the deployer starts the Android Debug Bridge server when it detects a running instance of an Android emulator.

Figure 27-14 The Deployment Log

Choose either Run, then Run Configurations or Run, then Debug Configurations. Under the MAF Applications node select an Android deployment profile.
Check that the target is the one you want to use, and click either Run or Debug.

27.2.5.3 How to Publish an Android Application

After you have tested and debugged the application, as described in Chapter 30, "Testing and Debugging MAF Applications," you can publish it to an application marketplace (such as Google Play) by following the instructions provided on the Android Developers website (http://developer.android.com/tools/publishing/publishing_overview.html).

Before you begin:

Create a Run Configuration.

Note:

You must configure the signing options in the Android Platform preference page (accessed by choosing Window > Preferences > Mobile Application Framework) as described in Section 27.2.4.3, "Defining the Android Signing Options."

To deploy an application as an .apk file:

Choose Run, then Run Configurations to create a run configuration. Under the MAF Applications node select an Android deployment profile.
Check that the target is the one you want to use, and click Run.
Review the deployment log in the console.
Publish the application to an application marketplace.

27.2.5.4 What Happens in OEPE When You Create an .apk File

Deploying an application results in the following being deployed in an .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 1.4 files

Table 27-2 Contents of the .apk File

Content	Location Within the .apk File
The content in the `.adf` folder	The root folder of the Android application file (`[apkRoot]\.adf`)
The content in the `adfmsrc` folder	The deployment packages the content in the `adfmsrc` folder into the default JAR file, which is located in a folder called `user` (`[apkRoot]\user`). This JAR file is added to the `.apk` using the Android Asset Packaging Tool (AAPT) and has a default name of the form `ANDROID_MOBILE_NATIVE_archiveN` where `N` is the nth Android created profile (you can override this name when creating the profile). This JAR file contains the following: Any `.class` files generated from `.java` files that are added to the view controller project, as well as the `adfmsrc` content. The `.java` files are compiled using the JVM 1.4 JDK `javac` tool. Contains data binding and pagedef metadata files. This JAR file is not processed by the Dalvik virtual machine. Because the `.class` files run in the JDK, they do not need to be converted into the Dalvik bytecode format (`.dex`).
`adfmf_application.xml` and `adfmf_feature.xml` files	Located in a file called Configuration (`[apkRoot]\Configuration`).
`logging.properties` file	Located in the root of the application file.
JVM 1.4 files	The JVM files are packaged into two separate folders: The library file (`\framework\build\java_res\libs\` ) in the template will be packaged into a `lib` folder in the `APK - [apkRoot]\lib`. The `\framework\build\java_res\assets\storage` file is packaged in the `assets\storage` directory in the `APK - [apkRoot]\assets\storage`.

27.2.5.5 Selecting the Most Recently Used Deployment Configurations

After you select a deployment action, OEPE creates a shortcuts on the Debug and Run buttons on the main toolbar, as shown in Figure 27-15. Click the down-arrow, and choose the configuration that enables you to easily redeploy the application using that same deployment action.

Figure 27-15 Choosing a Recently Used Configuration

27.2.5.6 Viewing the Device/Emulator Log in the Console

In OEPE, the log output from the device or emulator is streamed inside the console, as shown in Figure 27-16. This is very useful for debugging. For more information, see Section 30.4.1, "How to Configure Logging Using the Properties File."

Figure 27-16 Viewing the Device or Emulator Log

27.2.6 How to Create an iOS Deployment Configuration

For iOS, use the Debug Configuration dialog to define the iOS application build configuration as well as the locations for the splash screen images and application icons.

Before you begin:

Download Xcode (which includes the Xcode IDE, performance analysis tools, the iOS simulator, the Mac OS X, and the iOS SDKs) to the Apple computer that also runs OEPE.

Tip:

Refer to the Certification and Support Matrix on Oracle Technology Network (http://www.oracle.com/technetwork/developer-tools/maf/documentation/index.html) 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 OEPE.

Tip:

While the current version of Xcode is available through the App Store, you can download prior versions through the following site:

https://developer.apple.com/xcode/

Access to this site requires an Apple ID and registration as an Apple developer.

After you download Xcode, you must enter the location of its xcodebuild tool and, for deployment to iOS simulators, the location of the iOS simulator's SDK, in the iOS Platform preference page. For more information, see Oracle Enterprise Pack Installing Oracle Enterprise Pack for Eclipse.

Note:

Run both iTunes and the iOS simulator at least once before entering their locations in the iOS Platform preference page.

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 certification from the iOS Provisioning Profile as described in Section 27.2.6.2, "Setting the Device Signing Options."

To create a deployment configuration:

Choose Run > Debug Configurations, as shown in Figure 27-17.

Figure 27-17 Setting the iOS Options
Accept the default values, or define the following:
- Assembly Project—Choose from the list of those available.
- Deployed Bundle Id—If needed, enter a Bundle Id to use for this application that identifies the domain name of the company. The deployed 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 more information, see the App Distribution Guide, which is available through the iOS Developer Library at http://developer.apple.com/library/ios/navigation/). For information on obtaining the Bundle Seed Id using the iOS Provisioning Portal, see Section 27.2.7.4.3, "Registering an Application ID." See also Section 3.3, "How to Define the Basic Information for an Application Feature."
  
  Note:
  The deployed bundle Id cannot contain spaces.
  
  Because each deployed 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 deployed 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).
- Target—Choose from the list of targets configured in the Preferences dialog, or click Target to add a new target.
- Target Configuration
  - iOS Deploy Target—Choose device or simulator.
  - iOS Simulator Version—When you select Simulator as the deploy target, select the version of the emulator to which you are deploying the application. To find the available target versions, select Hardware and then Version on an iPhone simulator. The minimum version is 6.0. The default setting is <Highest Available>. For more information, see the iOS Simulator User Guide, which is available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).
    
    Note:
    Older versions of the iOS target version are usually available in the simulator for testing.
  - Select Mobile Provisioning Profile—
  - iOS Distribution Package (ipa)—If needed, enter the name for the .ipa file or the .app file. MAF creates an .ipa file when you select either the Deploy to distribution package or Deploy to iTunes for synchronization to device options in the Deployment Action dialog, shown in Figure 27-23. It creates an .app file when you select the Deploy application to simulator option. Otherwise, accept the default name. For more information, see Section 27.2.7.2, "How to Deploy an Application to an iOS-Powered Device" and Section 27.2.7.5, "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 id attribute configured in the maf-application.xml file. For more information, see Section 3.3, "How to Define the Basic Information for an Application Feature."
  - Advanced Options—Click Options to open the Advanced Option dialog, where you can set various options, as shown in Figure 27-18.
    
    Figure 27-18 Setting the Minimum iOS Version
    
    Minimum iOS Version—Indicates the earliest version of iOS to which you can deploy the application. The default value is the current version. The version depends on the version of the installed SDK.

27.2.6.1 Defining the iOS Build Options

The iOS build options enable you to deploy an application with debug or release bits and libraries. The Options page presents the configuration options for the iOS signing modes, debug and release modes.

Before you begin:

Deployment of an iOS application (that is, an .ipa file) to an iOS-powered device requires a provisioning profile, which is a required component for installation, and also a signed certificate that identifies the developer and an application on a device. You must obtain these from the iOS Provisioning portal as described in Section 27.2.7.4, "What You May Need to Know About Deploying an Application to an iOS-Powered Device." In addition, you register the provisioning profile in the Oracle > MAF > iOS page of the Preferences dialog (available from the Window menu). Select the provisioning profile in the Debug configuration or Run configuration when you select the iTunes or Package for the iOS Deploy target.

Once you select the provision profile in the run configuration or debug configuration, the prefix for the deployed bundle id is inferred from it.

In addition, you must enter the location for a provisioning profile and the name of the certificate in the iOS Platform preference page, as described in Section 27.2.6.2, "Setting the Device Signing Options."

How to set the build options:

Open the deployment configuration dialog, as shown in Figure 27-17.
Choose one of the following options:
- Run > Debug Configurations—Select this option for development builds. Designating a debug build results in the inclusion of debugging symbols. See also Section 30.3.2, "How to Debug on iOS Platform" and Section 30.3.5, "How to Enable Debugging of Java Code and JavaScript"
- Run > Run Configurations—Select this to compile the built with the files, artifacts, and libraries needed for release.
  
  Tip:
  Use the release mode, not the debug mode, to test application performance.

At runtime, MAF indicates that an application has been deployed in the debug mode by overlaying a debugging symbol that is represented by an exclamation point within a red triangle, as shown in Figure 27-9, "Deployment Modes".

27.2.6.2 Setting the Device Signing Options

The iOS Platform preference page for iOS includes fields for the location of the provisioning profile on the development computer and the name of the certificate. You must define these parameters if you deploy an application to an iOS device or as a MAF Application Archive.

Note:

Neither a certificate nor a provisioning profile are required if you deploy a mobile application to an iOS simulator.

To set the signing options:

Choose Window, then Preferences, and then Mobile Application Framework.
Choose iOS and then choose iOS Mobile Provisions.
In the Mobile Provision Info section of the page, shown in Figure 27-19, enter the location of the provisioning profile in Mobile Provisioning File.
OEPE enters the Certificate.

Figure 27-19 The Device Signing Section of the iOS Platform Preference Page

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. For more information, see the App Distribution Guide, which is available from the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).

27.2.6.3 Adding a Custom Image to an iOS Application

You can add your own custom images to the application.

The Application Images page enables you to rebrand an application by overriding the default Oracle image used for application icons and artwork with custom images. The options in this page, shown in Figure 27-20, enable you to enter the locations of custom images used for different situations, and device resolutions. For more information on iOS application icon images, see the "Icon and Image Design" section in iOS Human Interface Guidelines. This document is available from the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).

Note:

All images must be in the PNG format.

Figure 27-20 Adding Custom Images

To add custom images:

Open the deployment configuration by choosing Run > Debug Configurations.
Click Options to open the Advanced iOS Options dialog.
Click the Application Images tab, and choose whether you want to change the image for iPhone or iPod.
Choose the image you want to change, and Browse to select the image file you want to use. This image file must exist within the current application.

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

For more information, see Section 27.2.6.4, "What You May Need to Know About iTunes Artwork."
Click OK.

27.2.6.4 What You May Need to Know About iTunes Artwork

By default, mobile applications deployed to an iOS device through iTunes, or deployed as an archive (.ipa file) for download, use the default Oracle image unless otherwise specified.

By selecting an iTunes artwork image as the icon for the deployed application, you override the default image. You can use an image to differentiate between versions of the application. Figure 27-21 illustrates the difference between the default image and a user-selected image, where Application4 is displayed with the default image and Application6 is displayed with a user-selected image (the Oracle icon, scaled to 512 x 512 pixels).

Figure 27-21 Custom and Default Application Icons

During deployment, MAF ensures that the icon displays in iTunes by adding the iTunes artwork image to the top-level of the .ipa file in a file called iTunesArtwork.

27.2.6.5 How to Restrict the Display to a Specific Device Orientation

By default, MAF supports 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 using the Device Orientation page, shown in Figure 27-22

Figure 27-22 Select a Device Orientation

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

Choose Device Orientations, as shown in Figure 27-22.

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

Table 27-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.

27.2.7 Deploying an iOS Application

The deployment configuration dialog, shown in Figure 27-23, enables you to deploy an iOS application directly to an iOS simulator or to a device through iTunes. 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, which provides access to versions of Xcode that are not available through the App Store, will suffice. For more information on iOS developer programs, which are required for deployment to iOS-powered devices (and are described at Section 27.2.7.2, "How to Deploy an Application to an iOS-Powered Device," and Section 27.2.7.5, "How to Distribute an iOS Application to the App Store"), see https://developer.apple.com/programs/.

Figure 27-23 The Deployment Configuration Dialog (for iOS Applications)

27.2.7.1 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.
Run the iOS simulator at least once after installing Xcode.
Set the location of the SDK of the iOS simulator in the iOS Platform preference page, shown in Figure 27-25.

Note:
You must enter the location of the provisioning profile and the name of the certificate in the iOS Platform page (accessed by choosing Window > Preferences > Mobile Application Framework). For more information, refer to Section 27.2.6.2, "Setting the Device Signing Options."
Before you deploy an application, shut down the iOS simulator if it is running. If you do not shut down the simulator, the deployment will do it for you.
Refer to the iOS Simulator User Guide, available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/). The iOS simulator is installed with Xcode.

To deploy an application to an iOS simulator:

Choose Run > Run Configurations, to open the Run Configurations dialog, as shown in Figure 27-24.

Figure 27-24 Run Configurations Dialog
Accept the default values, or define the following:
- Assembly Project—Choose from the list of those available.
- Deployed Bundle Id—If needed, enter a Bundle Id to use for this application that identifies the domain name of the company. The deployed 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 more information, see the App Distribution Guide, which is available through the iOS Developer Library at http://developer.apple.com/library/ios/navigation/). For information on obtaining the Bundle Seed Id using the iOS Provisioning Portal, see Section 27.2.7.4.3, "Registering an Application ID." See also Section 3.3, "How to Define the Basic Information for an Application Feature."
  
  Note:
  The deployed bundle Id cannot contain spaces.
  
  Because each deployed 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 deployed 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).
- Target—Choose from the list of targets configured in the Preferences dialog, or click Target to add a new target.
- Target Configuration
  - iOS Deploy Target—Choose Simulator.
  - iOS Simulator Version—Select the version of the emulator to which you are deploying the application. To find the available target versions, select Hardware and then Version on an iPhone simulator. The minimum version is 6.0. The default setting is <Highest Available>. For more information, see the iOS Simulator User Guide, which is available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).
    
    Note:
    Older versions of the iOS target version are usually available in the simulator for testing.
  - Select Mobile Provisioning Profile—
  - iOS Distribution Package (ipa)—If needed, enter the name for the .app file. MAF creates an .app file when you select the Deploy application to simulator option. Otherwise, accept the default name.
    
    By default, MAF bases the name of the .ipa file on the application id attribute configured in the maf-application.xml file. For more information, see Section 3.3, "How to Define the Basic Information for an Application Feature."
  - Advanced Options—Click Options to open the Advanced Option dialog, where you can set various options.
    
    Minimum iOS Version—Indicates the earliest version of iOS to which you can deploy the application. The default value is the current version. The version depends on the version of the installed SDK.

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

The Deploy to iTunes for Synchronization to device option enables you to deploy a mobile application to an iOS-powered device for debugging and testing. Deployment to an iOS-powered device or to a distribution site requires membership to either the iOS Developer Program or the iOS Developer Enterprise Program. For more information, see https://developer.apple.com/programs/.

Before you begin:

You cannot deploy an application directly from OEPE to a iOS device; an application must instead be deployed from the Applications folder in Apple iTunes. To accomplish this, you must perform the following tasks:

Download Apple iTunes to your development computer and run it at least once to create the needed folders and directories.
Set the location of the Automatically Add to iTunes folder (the location used for application deployment) in the iOS Platform preference page, shown in Figure 27-25.
Tip:
Although your user home directory (/User/<username>/Music/iTunes/iTunes Media/Automatically Add to iTunes.localized) is the default directory for the iTunes Media folder, you can change the location of this folder as follows:
1. In iTunes, select Edit, Preferences, then Advanced.
2. Click Change and then browse to the new location.
3. Consolidate the library.
4. Delete the original iTunes Media folder.
For instructions, refer to Apple Support (http://support.apple.com).

You must also update the location in the iOS Platform preference page.
Set the location of the Xcode folder where the xcodebuild tool is invoked, such as /Developer/usr/bin in Figure 27-25.

Figure 27-25 Setting the Locations for the iTunes Media Folder and the xcodebuild System
Enter the name of the certificate and the location of the provisioning profile in the iOS Platform preference page. The OS Provisioning Portal generates the certificate and provisioning profile needed for deployment to iOS devices, or for publishing .ipa files to the App Store or to an internal download site.

Note:
The deployment will fail unless you set the iOS provisioning profile and certificate to deploy to a device or to an archive. MAF logs applications that fail to deploy under such circumstances. For more information, see Section 27.2.7.4, "What You May Need to Know About Deploying an Application to an iOS-Powered Device."
In the iOS Options page of the deployment profile, select Run as the build mode and then OK.
Refer to the App Distribution Guide, which is available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).

To deploy an application to an iOS-powered device:

Choose Run > Debug Configurations, as shown in Figure 27-17.

Figure 27-26 Setting the iOS Options
Accept the default values, or define the following:
- Assembly Project—Choose from the list of those available.
- Deployed Bundle Id—If needed, enter a Bundle Id to use for this application that identifies the domain name of the company. The deployed 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 more information, see the App Distribution Guide, which is available through the iOS Developer Library at http://developer.apple.com/library/ios/navigation/). For information on obtaining the Bundle Seed Id using the iOS Provisioning Portal, see Section 27.2.7.4.3, "Registering an Application ID." See also Section 3.3, "How to Define the Basic Information for an Application Feature."
  
  Note:
  The deployed bundle Id cannot contain spaces.
  
  Because each deployed 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 deployed 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).
- Target—Choose from the list of targets configured in the Preferences dialog, or click Target to add a new target.
- Target Configuration
  - iOS Deploy Target—Choose device or simulator.
  - iOS Simulator Version—When you select Simulator as the deploy target, select the version of the emulator to which you are deploying the application. To find the available target versions, select Hardware and then Version on an iPhone simulator. The minimum version is 6.0. The default setting is <Highest Available>. For more information, see the iOS Simulator User Guide, which is available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).
    
    Note:
    Older versions of the iOS target version are usually available in the simulator for testing.
  - Select Mobile Provisioning Profile—
  - iOS Distribution Package (ipa)—If needed, enter the name for the .ipa file or the .app file. MAF creates an .ipa file when you select either the Deploy to distribution package or Deploy to iTunes for synchronization to device options in the Deployment Action dialog, shown in Figure 27-23. It creates an .app file when you select the Deploy application to simulator option. Otherwise, accept the default name. For more information, see Section 27.2.7.2, "How to Deploy an Application to an iOS-Powered Device" and Section 27.2.7.5, "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 id attribute configured in the maf-application.xml file. For more information, see Section 3.3, "How to Define the Basic Information for an Application Feature."
  - Advanced Options—Click Options to open the Advanced Option dialog, where you can set various options, as shown in Figure 27-18.
    
    Figure 27-27 Setting the Minimum iOS Version
    
    Minimum iOS Version—Indicates the earliest version of iOS to which you can deploy the application. The default value is the current version. The version depends on the version of the installed SDK.

27.2.7.3 What Happens When You Deploy an Application to an iOS Device

The application appears in the iTunes Apps Folder, similar to the one illustrated in Figure 27-21 after a successful deployment.

27.2.7.4 What You May Need to Know About Deploying an Application 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. You enter the location of the provisioning profile and the name of the certificate in the Options page as described in Section 27.2.6.2, "Setting the Device Signing Options."

As noted in the App Distribution Guide, (which is available through the iOS Developer Library at http://developer.apple.com/library/ios/navigation/), 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 27-28 The iOS Provisioning Portal

27.2.7.4.1 Creating iOS Development Certificates

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.

27.2.7.4.2 Registering an Apple Device for Testing and Debugging

After you install a certificate on your development computer, review the Current Available Devices tab (located in the iOS Provisioning Portal's Devices page) to identify the Apple devices used by you (or your company) for testing or debugging. The application cannot deploy unless the device is included in this list, which identifies each device by its serial number-like Unique Device Identifier (UDID).

27.2.7.4.3 Registering an Application ID

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 Section 3.4, "How to Set the ID and Display Behavior for a Mobile Application" prefixed by a ten-character alpha-numeric string called a bundle seed, which is generated by Apple. Figure 27-29 illustrates an application ID that is unique, one that does not share files or the Keychain with any other applications.

Figure 27-29 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. For more information, see the "Provisioning and Development" section of Local and Push Notification Programming Guide, available from the iOS Developer Library (http://developer.apple.com/library/ios/navigation/)

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 Options page of the deployment profile.

27.2.7.5 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 add .ipa files to iTunes, as well as 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, shown in Figure 27-25, enter the location of the Automatically Add to iTunes directory.

Tip:
Run iTunes at least once before entering this location. See also Section 27.2.7.2, "How to Deploy an Application to an iOS-Powered Device."
Test the application on an actual iOS device. See Section 27.2.7.2, "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 iTunes. For information, see "Prepare App Submission" in the iOS Development Center's App Store Resource Center. Specifically, review the App Store Review Guidelines to ensure acceptance by the App Review Team.
You may want to review both the and iTunes Connect Developer Guide. These guides are both available through the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).
In the iOS Options page of the deployment profile, select App Distribution Guide Release as the build mode and then click OK.

To distribute an iOS application to the App Store:

Choose Run > Run Configurations, and then select an iOS deployment configuration.
Choose Deploy to Distribution Package.
Review the Summary page, which displays the following values. Click Finish.
- Deployed 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.
- Certificate—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>.
Note:
The Certificate and Provisioning Profile values cannot be noted as <Not Specified>; you must specify these values in the Options page to enable the .ipa file to be accepted by iTunes.
Log in to iTunes Connect.
Submit the .ipa file to iTunes Connect for consideration using the Manage Your Applications module and the Application Loader described in the "Adding New Apps" and "Using Application Loader" sections in iTunes Connect Developer Guide.
After the application has been approved, refer to the "Creating Test Users" section in iTunes Connect Developer Guide for information on using the Manage Users module. For testing multi-language applications, create a test user account for the regions for which the application is localized.
Refer to the "Editing and Updating App Information" section in iTunes Connect Developer Guide for information on updating the binary using the Managing Your Application module.

27.3 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. A FAR may contain Java classes, though these classes must be compiled. The example below illustrates the contents of a FAR, which includes a single maf-feature.xml file and a connections.xml file.

connections.xml (or some form of connection metadata)
 
  META-INF
     jar-connections.xml
     jar-adf-config.xml
     adfm.xml
     maf-feature.xml
     MANIFEST.MF
     task-flow-registry.xml
 
  oracle
    application1
      mobile
        DataControls.dcx
         DataBindings.cpx
         pageDefs
           view1PageDefs
 
  model
     Class1.class
 
  public_html
     adfc-mobile-config.xml
       index.html
       navbar-icon.html
       springboard-icon.html
     view1.amx
     task-flow-definition.xml

Working with Feature Archive files involves the following tasks:

Creating a Feature Archive file—You create a Feature Archive by exporting the view project as a FAR.
Using the Feature Archive file when creating a mobile application—This includes registering a FAR with the application, and then registering the features in the FAR with the application.
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 project if you use the FAR in another application.

27.3.1 How to Create a Mobile Feature Archive FIle

Use the OEPE Export wizard to create the .far file.

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.

How to package mobile features as a Feature Archive File:

Click File then choose Export.
In the Export wizard, expand Oracle, then Mobile Application Framework, and choose Mobile Feature Archive (FAR), as shown in Figure 27-30.

Figure 27-30 Creating a Mobile Feature Archive File
Click Next, and choose the view project containing the features you want to archive, and enter a name for the archive file, as shown in Figure 27-31.

Note:
Name the profile appropriately. Otherwise, you may encounter problems if you upload more than one application feature with the same archive name.

Figure 27-31 Entering a Name and Path for the Mobile Feature Archive File
Click Finish. The Summary page, shown in Figure 27-32, displays the full path of where the Feature Archive file's JAR path is deployed.

27.3.2 How to Deploy the Feature Archive Deployment Profile

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

How 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 Figure 27-32, displays the full path of where the Feature Archive file's JAR path is deployed.

Figure 27-32 File Export Summary Page

27.3.3 What Happens When You Create a Feature Archive File Deployment Profile

To use a FAR from an external application, you need to register the FAR in your application's maf-application.xml file. Figure 27-33 shows Feature Archives that can be made available to a mobile application through a file system connection.

Figure 27-33 Deployed Feature Archive JARs in the MAF Application Editor

27.4 Creating a Mobile Application Archive File

You can create a new mobile application from an existing mobile application by first packaging the original mobile application as a Mobile Application Archive (.maa) file and then by deriving a new mobile application from this file. An .maa file can be used by third parties, as described in Section 27.5, "Creating Unsigned Deployment Packages."

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

Table 27-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`). The `.maa` file created in OEPE can be imported only in OEPE. It cannot be imported into JDeveloper.
`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 and splash screens. security—Includes the `cacerts` file (the keystore file).

In addition to the artifacts listed in Table 27-4, the .maa file includes any folder containing FARs or JAR files that are internal to the original mobile application. See also Section 27.5.2, "What Happens When You Import a MAF Application Archive File."

27.4.1 How to Create a Mobile Application Archive File

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

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

Click File then choose Export.
In the Export wizard, expand Oracle, then Mobile Application Framework, and choose Mobile Application Archive (MAA), as shown in Figure 27-34.

Figure 27-34 Creating a Mobile Application Archive File
Click Next, and choose the name of the application you want to archive and enter a name for the Mobile Application Archive, as shown in Figure 27-35.

Figure 27-35 Entering a Name and Path for the Mobile Application Archive File
Click Finish

27.5 Creating Unsigned Deployment Packages

The MAF Application Archive (.maa) file format enables you to provide third-parties with an unsigned mobile application. By deriving a mobile application from an imported .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.

Note:

You cannot import an .maa file into a workspace that already contains one or more of the same projects. Instead, you must import the .maa file into a different workspace.

27.5.1 How to Create an Unsigned Application

You create an unsigned application by importing an .maa file into a new mobile application.

To create an unsigned application:

Choose File then choose Import.
In the Import wizard, expand Oracle and choose Mobile Application Archive (MAA). Click Next.
In the Import Mobile Application Archive (MAA) page, click Browse and navigate to the MAA file. Click Next.
In the Configure Deployment Targets page, select the targets you will want to deploy to, and click Finish.

27.5.2 What Happens When You Import a MAF Application Archive File

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

Creates a project for each of the assembly project, the application project and the view projects.
Unpacks files from the .maa file.

27.6 Deploying with Oracle Mobile Security Suite

Oracle Mobile Security Suite (OMSS) provides enterprise-level security for mobile applications. It offers encryption of application data and database contents and prevents data leakage during use.

Note:

At present, OMSS is only available on iOS devices.

27.6.1 What You Need To Know Before Using OMSS

OEPE requires that you run version 3.0.2 of OMSS.

You can download OMSS and read instructions on installation on the Oracle Technology Network:

http://www.oracle.com/technetwork/middleware/id-mgmt/overview/default-2099033.html

27.6.2 How to Encrypt your Content Using Containerization

OMSS uses containerization at deployment time to encrypt your application content. Containerization is controlled from the Run Configurations menu (see Figure 27-36).

Figure 27-36 Selecting OMSS Containerization from the Run Configurations menu

To containerize an app using Oracle Mobile Security Suite:

Select Run > Run Configurations.
In the Target Configuration pane, select iTunes (for device deploy) from the iOS Target drop-down.

Note:
Containerization is only supported from the iTunes deployment. The iOS simulator does not support containerization.
In the Containerization pane, select Enable Oracle Mobile Security Suite. This displays the Containerize dialog from the Preferences menu (see Figure 27-37).

Figure 27-37 Specifying the location of the Containerization tool
Click the Browse icon and browse to the location of the Oracle Mobile Security App Containerization tool on your local file system.
Click OK to select the containerization tool.
From the Run Configurations dialog, select Run.