16 Deploying ADF Mobile Applications

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

This chapter includes the following sections:

• Section 16.1, "Introduction to Deployment of Mobile Applications"

• Section 16.2, "Working with Deployment Profiles"

• Section 16.3, "Deploying an Android Application"

• Section 16.4, "Deploying an iOS Application"

• Section 16.5, "Deploying Feature Archive Files (FARs)"

• Section 16.6, "Deploying ADF Mobile Applications from the Command Line"

16.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 (an .ipa file) or Android application package file (.apk) to the platform-appropriate device or simulator, ADF Mobile enables you to test applications before publishing them to the App Store (Apple iTunes), or to an application marketplace, such as Google Play.

16.1.1 How ADF Mobile Deploys Applications

Deployment of an ADF Mobile project is accomplished by copying a platform-specific template application to a temporary location, updating that application with the code, resources, and configuration defined in the ADF Mobile project, and then building and deploying the application using the tools of the target platform. The tasks that comprise deployment, are as follows:

1. Validate that the platform-specific build tools are available from the specified platform SDK.

2. Validate the application's content, including the XML files.

3. If necessary, unzip the platform-dependent template file to a temporary location.

   Note:

   The template file may not be present if you selected Build > Clean All.

4. Copy default images to the proper location in the template.

5. Copy custom images to the proper location in the template.

6. Copy the web content (including any images related to feature application) to the template location.

7. Copy the libraries of the Java Virtual Machine 1.4 (JVM 1.4) and any support libraries to the proper location in the template. For more information, see Section 16.1.1.2, "Deployment of the JVM 1.4 Libraries."

8. Copy custom content into the proper location in the template (this includes libraries and JAR files that have been included in the project properties).

9. Copy, or update, the metadata files in the template with preferences defined in the deployment profiles and the adfmf-application.xml and adfmf-feature.xml files.

10. Run the platform-specific build tools on the template project.

11. Run the platform-specific tools on the template project to sign the project (if necessary) and package the project for the chosen deployment.

For a detailed description of the deployment flow for Android applications, see Section 16.2.3.6, "What Happens in JDeveloper When You Deploy an Application to an Android Emulator or Android-Powered Device." For iOS applications, see Section 16.4.5.1, "What Happens in JDeveloper When You Deploy an Application to an iOS Simulator or iOS-Powered Device."

16.1.1.1 Deployment of Project Libraries

The libraries that you declare for the project using the Customize Libraries and Classpaths Dialog, shown in Figure 16-1, are included in the deployment artifacts for the project. This dialog enables the application features to access these libraries at runtime.

Figure 16-1 Adding Libraries to the Project

16.1.1.2 Deployment of the JVM 1.4 Libraries

For both Android and iOS applications, each ADF Mobile 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, ADF Mobile 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.

16.2 Working with Deployment Profiles

Preparing ADF Mobile applications for deployment begins with the creation of platform-specific deployment profiles. A deployment profile defines how an application is packaged into the archive that will be deployed to iOS- or Android-powered devices, iOS simulators, or Android emulators. The deployment profile does the following:

• Specifies the format and contents of the archive. For iOS, the archive format is an .ipa file, known as an application bundle. For Android, the format is an Android application package file (.apk).

  Note:

  The .apk file is archive-compatible, meaning that you can view its contents using an archiving tool such as WinZip or 7-Zip.

• 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.

16.2.1 How to Create a Deployment Profile

The ADF Mobile extension adds ADF Mobile-specific pages (described in Table 16-1) for both iOS and Android deployments to the standard ADF deployment pages that include:

• File Groups

• Library Dependencies

• Profile Dependencies

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

Note:

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

Before you begin:

To enable JDeveloper to deploy ADF Mobile applications, you must designate the SDKs for the target platforms using the ADF Mobile Preferences page as described in Section 3.3.1, "How to Configure the Development Environment for Platforms and Form Factors."

To create a deployment profile:

1. Choose Application and then Deploy.

2. Choose New Deployment Profile.

3. Depending on the target platform, select either ADF Mobile for Android or ADF Mobile for iOS, as shown in Figure 16-2.

4. Accept the default name for the profile or enter a new one. Click OK.

5. If needed, use the Options and Application Images pages as required for the applications and then click OK.

   Figure 16-2 The Create Deployment Profile Wizard

   
   

16.2.2 What Happens When You Create a Deployment Profile

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

Table 16-1 lists the ADF Mobile-specific pages in the Deployment Profile Properties editor, shown in Figure 16-6.

Table 16-1 ADF Mobile-Specific Deployment Profile Pages

Page	Function
iOS Options	Enables you to modify the settings for an application to be deployed on an iOS-powered device or iOS simulator.
Android Options	Enables you to modify the settings for an application deployed to an Android-powered device or Android emulator.
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 16-1.

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

Using the Filters panel, shown in Figure 16-3, you can exclude any selected artifact from being deployed. In particular, you can use the Filters panel to exclude any artifact that does not match the target deployment platform. For more information, refer to the online help for Oracle JDeveloper.

Figure 16-3 Removing Files from Deployment Using the Filters Panels

16.2.3 How to Create an Android Deployment Profile

The deployment profile creates the template for the application deployment to an Android device or emulator, or for creating an application as an Android application package file (.apk).

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 Section 3.5, "Setting Up Development Tools for Android Platform." 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 on the Android Developers website (http://developer.android.com/tools/devices/index.html). In creating an Android Virtual Device (AVD), ensure that the CPU/ABI value reflects an ARM system image, such as ARM (armeabi-v7a) in Figure 16-4. In addition, set the size of the AVD's SD card image file to a large RAM size, such as the value of 1024 MB (1 GB) set for the Device ram size property in Figure 16-4. You can, however, opt for a smaller size.

Note:

ADF Mobile only supports the ARM EABI v7a System Image. Although ADF Mobile supports Android-powered devices that run on the Android 2.3.n platform (API Level 9), it does not support deployment to emulators running on this platform because they are based on the ARM926EJ-S rev 5 (v51) processor. Further, JVM 1.4 cannot run properly when deployed to Android emulators for the 2.n platform.

Figure 16-4 Creating an Android Virtual Device

You must also set the ADF Mobile preferences for the Android platform SDKs (accessed by choosing Tools, then Preferences, then ADF Mobile, then Platforms, and then Android) to the locations for the SDK and platform, which are part of the Android SDK package download. Figure 16-5 shows these locations. Using the Platforms page, you also define the debug and release properties for a key that is used to sign the Android applications. Within the deployment profile, you subsequently designate an ADF Mobile application's release as either debug or release. You only need to define the signing key properties once. For more information, see Section 16.2.3.3, "Defining the Android Signing Options." See also the application publishing information available on the Android Developers website (http://developer.android.com/tools/publishing/app-signing.html).

Note:

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

Figure 16-5 Setting the Android SDK, Platform and Signing Properties

16.2.3.1 Setting the Options for the Application Details

The Android Options page, shown in Figure 16-6, enables you to do the following:

• Denote the version of the application. For information on versioning an Android application, refer to the Android Developers website (http://developer.android.com/tools/publishing/versioning.html).

• Configure the Android zipalign tool, an archive alignment tool that optimizes the packaging of .apk files. Data files stored in each application package, such as data manifests, are continually accessed by multiple processes within the Android operating environment. For more information on the zipalign tool, refer to the Android Developers website (http://developer.android.com/tools/help/zipalign.html).

• Set the logging level output as either verbose or debug.

• Set the signing options appropriate to the deployment target (emulator or device). For more information, see Section 16.2.3.3, "Defining the Android Signing Options."

Figure 16-6 The Deployment Profile Properties Editor (Android Options Page)

To set the application options:

1. Choose Android Options, as shown in Figure 16-6.

2. Accept the default values, or define the following options:

   • Application Bundle ID—A unique ID for the application, as set in the id attribute of the adfmf-application.xml file. Each application deployed to an Android device has a unique ID, one that cannot start with a numeric value. For more information, see Section 5.3, "Setting the Basic Information for an ADF Mobile Application."

     If needed, you can override this value in the deployment file. However, for the application to deploy, this name must follow the <manifest> element's package attribute of the Android manifest file, which is described on the Android Developers website (http://developer.android.com/guide/topics/manifest/manifest-intro.html). Specifically, the ID uses a reverse package format of an internet domain (com.company.application). To avoid naming collisions, the package name reflects domain ownership, such as com.oracle.application.

     Note:

     The application bundle ID cannot contain spaces.

   • Version Name— The release version of the application code that displays for the user. See also Section 5.3, "Setting the Basic Information for an ADF Mobile Application."

   • Version Code—An integer value that represents the version of the application code, which is checked programmatically by other applications for upgrades or downgrades. The minimum and default value is 1. You can select any value and increment it by 1 for each successive release.

16.2.3.2 Setting Deployment Options

The Options page enables you to set values that are passed in by the javac compiler tool options, set the zipalign options, and also the Android API revisions.

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

1. Select the JDK-compatibility level from the Source Files dropdown list. The default value is 1.5. The value is specified when the deployment runs the javac tool to compile R.java, the Android-generated file for referencing application resources, using the javac -source option. Available values include:

   • 1.5

   • 1.6

   For information on R.java, see the Android Developers website (http://developer.android.com/guide/topics/resources/accessing-resources.html).

2. Select the JDK version compatibility for the compiled .class files from the Class Files dropdown list. The value is specified when the deployment runs the javac tool to compile the R.java file using the javac -target option. The default value is 1.5. Available values include:

   • 1.5

   • 1.6

3. 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 of the Android manifest file, available through the Android Developers website (http://developer.android.com/guide/topics/manifest/manifest-intro.html).

4. 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 9, which corresponds to Android 2.3.n platform.

5. Select the native-encoding name that controls how the compiler interprets characters beyond the ASCII character set from the Character Encoding dropdown list. The default is UTF-8.

To set the ZIP alignment options:

Select the byte alignment (32-bit or 64-bit). Selecting 32-bit (the default) provides 4-byte boundary alignment.

To set the logging level:

Select Verbose Output for the Android deployment to log the full output provided by each of the command-line tools invoked by the deployment while building the .apk. If you do not select this option, then the deployment does not log the full output.

16.2.3.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 an ADF Mobile application is a two-step process: within the ADF Mobile Platforms preference page, 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.

Before you begin:

Refer to the signing in release and debug mode described on the Android Developers website (http://developer.android.com/tools/publishing/app-signing.html).

To configure the key options for debug or release modes:

1. Choose Tools, then Preferences, and then ADF Mobile.

2. Choose Platforms.

3. Select the Debug tab, shown in Figure 16-7.

   Figure 16-7 Configuring a Debug Deployment

   
   

4. 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.

5. Select the Release tab, shown in Figure 16-5, and then define the following:

   • Keystore Location—Enter the directory of the keystore containing the private key.

   • Keystore Password—Enter the password for the keystore.

   • Key Alias—Enter an alias for the key. Only the first eight characters of the alias are used.

   • Key Password—Enter the password for the key.

     In addition to designating how the application will be signed, these parameters designate how the R.Java classes are compiled. For more information, see Section 16.2.3.6, "What Happens in JDeveloper When You Deploy an Application to an Android Emulator or Android-Powered Device."

6. Click OK.

To Set the Android build mode:

1. Select either Debug or Release as the build mode:

   • Select Debug for developing and testing an application. 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.

     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.

   • 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.

2. Click OK.

   After the .apk file is signed in either the debug or release modes, you can deploy it to a device or emulator.

16.2.3.4 How to Add a Custom Image to an Android Application

Enabling ADF Mobile 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. ADF Mobile 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 16-8, 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. When creating custom images, follow the icon design guidelines described on the Android Developers website (http://developer.android.com/guide/practices/ui_guidelines/icon_design.html).

Figure 16-8 Setting Custom Portrait 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, as described on the Android Developers website (http://developer.android.com/guide/practices/screens_support.html).

To add custom images:

1. Click Application Images.

2. Use the Browse function to select the splash screen and icon image files from the project file. Figure 16-8 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. Figure 16-9 shows the Landscape tab selected for splash screen images, which enables you to add the landscape-orientation splash screen images that applications use for devices with low-, medium-, high- and extra-high density displays. These files can be located anywhere within the ADF Mobile application.

3. Click OK.

   Figure 16-9 Setting Landscape Splash Screen Images

   
   

16.2.3.5 What Happens When JDeveloper Deploys Images for Android Applications

During deployment, ADF Mobile enables JDeveloper to copy the images from their source location to a temporary deployment folder. For the default images that ship with the ADF Mobile extension (located at workspace_directory\Application Resources\Resources\images), JDeveloper copies them from their seeded location to a deployment subdirectory of the view controller project (workspace_directory\ViewController\deploy). As shown in Table 16-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, and xhdpi) 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.png.

Table 16-2 Deployment File Locations for Seeded Application Images

Source File (...\resource\Android)	Temporary Deployment File (...ViewController\deploy)
display-ldpi-icon.png	drawable-ldpi\adfmf_icon.png
display-mdpi-icon.png	drawable-mdpi\adfmf_icon.png
display-hdpi-icon.png	drawable-hdpi\adfmf_icon.png
display-xhdpi-icon.png	drawable-xhdpi\adfmf_icon.png
display-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, JDeveloper copies the set of application icons from their specified location to the corresponding density and orientation subdirectory of the temporary deployment location.

16.2.3.6 What Happens in JDeveloper When You Deploy an Application to an Android Emulator or Android-Powered Device

For the runtime deployment to an Android-powered device, the deployer performs the following:

1. Validates all selected deployment options.

2. Deletes any pre-existing template for this deployment profile.

3. Unzips Android template from Oracle_ADFmf_Framework.zip.

4. Creates an AndroidManifest.xml file from an AndroidManifest.template.xml file that is provided in the template.

5. Generates the Android preferences.xml, strings.xml and arrays.xml files from the content in the adfmf-application.xml and adfmf-feature.xml files. For more information, see Section B.2, "Converting Preferences for Android."

6. Invokes the Android Asset Packaging Tool (aapt.exe on Windows, appt on Mac) to generate an R.java file and initial Android application package file (.apk).

7. Compiles the R.java file by invoking javac externally from the JDeveloper project compilation process. This file must be compiled with a JDK version compatibility of 1.5 or greater because the file runs within the Android JVM.

8. Analyzes and evaluates dependencies. Compiles user-added .java code using the JVM 1.4 JDK. These files must be compiled with the JDK and are executed in the JVM 1.4.

9. Invokes the Android tool that generates Dalvik byte code (dex.bat) from .class files or archive compatible files containing .class files. The content in the Android template JAR files is included as well (phonegap.jar, container.jar, and ksoap.jar).

10. Invokes the Android Asset Packaging Tool (aapt.exe) tool to update the application file created in Step 6 with the Dalvik byte code file.

11. Creates a keystore and key for debug-mode deployment.

12. Signs the Android application file.

13. Aligns application (for a release-mode deployment).

14. Invokes the Android Debug Bridge (adb.exe on Windows, adb on Mac) tool to deploy the application to an Android-powered device.

16.2.4 How to Create an iOS Deployment Profile

For iOS, you can use the Deployment Profiles Properties Editor 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 4.2 or later, which includes the Xcode IDE, performance analysis tools, the iOS simulator, the Mac OS X and iOS SDKs, to the Apple computer that also runs JDeveloper. Because Xcode is used during deployment, you must install it on the Apple computer before you deploy the ADF Mobile application from JDeveloper. For instructions on downloading Xcode, refer to

http://developer.apple.com/xcode/

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 ADF Mobile Platforms preference page. For more information, see Chapter 3, "How to Configure the Development Environment for Platforms and Form Factors."

To deploy an ADF 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 16.2.4.2, "Setting the Device Signing Options."

To create a deployment profile:

1. Choose iOS Options, as shown in Figure 16-10.

2. Accept the default values, or define the following:

   • Application Bundle Id—If needed, enter a bundle ID to use for this application that identifies the domain name of the company. The application bundle Id must be unique for each application installed on an iOS device and must adhere to the reverse-package style naming conventions described in the "Application ID Errors" section in iOS Development Workflow Guide (that is, com.<organization name>.<company name>). For information on obtaining the Bundle Seed Id using the iOS Provisioning Portal, see Section 16.4.4.3, "Registering an Application ID." See also Section 5.3, "Setting the Basic Information for an ADF Mobile Application."

     Note:

     The application bundle ID cannot contain spaces.

     Because each application bundle ID is unique, you can deploy multiple ADF Mobile applications to the same device. Two applications can even have the same name as long as their application bundle IDs are different. Mobile applications deployed to the same device are in their own respective sandboxes. They are unaware of each other and do not share data (they have only the Device scope in common).

   • Application Archive Name—If needed, enter the name for the .ipa file created by ADF Mobile 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 16-21. Otherwise, accept the default name. For more information, see Section 16.4.2, "How to Deploy an Application to an iOS-Powered Device" and Section 16.4.5, "How to Distribute an iOS Application to iTunes."

     By default, ADF Mobile bases the name of the .ipa file on the application id attribute configured in the adfmf-application.xml file. For more information, see Section 5.3, "Setting the Basic Information for an ADF Mobile Application."

   • 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. The minimum version supported by ADF Mobile is 5.0.

   • Simulator Target 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 5.0. The default setting is <Highest Available>. See also the "Using iOS Simulator" chapter in Tools Workflow Guide for iOS, 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.

   • Target Family—Select the family of iOS products on which the application is intended to run. The default option is for both iPad and iPhone.

   Figure 16-10 Setting the iOS Options

   
   

16.2.4.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 16.4.4, "What You May Need to Know About Deploying an Application to an iOS-Powered Device." In addition, you must enter the location for a provisioning profile and the name of the certificate in the ADF Mobile Platforms preference page, as described in Section 16.2.4.2, "Setting the Device Signing Options."

How to set the build options:

1. Chose iOS Options, as shown in Figure 16-10.

2. Select one of the following build options.

   • Debug—Select this option for development builds. Designating a debug build results in the inclusion of debugging symbols. See also Section 18.3.1, "How to Debug on iOS Platform."

   • Release—Select to compile the build with release bits and libraries.

16.2.4.2 Setting the Device Signing Options

The ADF Mobile Platforms 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.

Note:

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

To set the signing options:

1. Choose Tools, then Preferences, and then ADF Mobile.

2. Choose Platforms and then choose iOS.

3. In the Device Signing section of the page, shown in Figure 16-11, enter the location of the provisioning profile in the Provisioning Profile field.

4. In the Certificate field, enter the name of the developer or distribution certificate that identifies the originator of the code (such as a developer or a company). You can view the name of the certificate using the Keychain Access utility (accessed from the Applications folder). Copy the entire name from the Keychain Access utility. The name entered into Certificate field must be in the following format:

   iPhone Developer: John Smith (PN3ENLQ3DU)
   

   Figure 16-11 The Device Signing Section of the ADF Mobile Platforms 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 "Configuring Development and Distribution Assets" chapter in Tools Workflow Guide for iOS, which is available from the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).

16.2.4.3 Adding a Custom Image to an iOS Application

The Application images page enables you to override the default Oracle image used for application icons with custom images. The options in this page, shown in Figure 16-13, enable you to enter the locations of custom images used for different situations, device orientation, and device resolutions. For more information on iOS application icon images, see the "Application Icons" and "Providing Launch Images for Different Orientations" sections in iOS App Programming Guide and the "Custom Icon and Image Creation Guidelines" section in iOS Human Interface Guidelines. These documents are available from the iOS Developer Library (http://developer.apple.com/library/ios/navigation/).

Note:

All images must be in the PNG format.

To add custom images:

1. Click Application Images.

2. Select Do Not Add Gloss Effect to Icons if the default iOS-style icon, which has a shine effect over the top of the icon is not used. Figure 16-12 illustrates the gloss effect.

   Figure 16-12 An Icon with the Default Gloss Effect

   
   

3. Chose Browse to select images for the following:

   • iTunes Artwork—Browse to, and select, an icon image to override the default Apple image that iTunes assigns to .ipa files. This image is required for all applications and must be 512 x 512 pixels for both iPhone and iPad applications. For more information, see Section 16.2.4.4, "What You May Need to Know About iTunes Artwork."

   • Application Icons—Enter the location of the icon images for iPhones and iPads, or for the versions of these images used for devices equipped with Retina displays. The file names must be the same for both the Retina and non-Retina version of the icon. For iPhone icons, the ADF Mobile deployment framework differentiates between the two by adding the @2x modifier to the file name of the Retina image. For iPad Retina displays, the deployment framework adds -144 to the file name to reflect the dimensions of its associated image (144 x 144, in pixels). For non-Retina iPad displays, the deployment framework likewise denotes the image dimensions (72 x 72, in pixels) by adding the -72 modifier to the iPad icon file name. Table 16-3 lists the required dimensions, in pixels, for the device-specific application images.

     Table 16-3 Dimensions for Application Icons

     Device	Dimension (in Pixels)
     iPhone	57 x 57
     iPhone Retina	114 x 114
     iPad	72 x 72
     iPad Retina	144 x 144

     
     

   • Splash Screen Images—Enter the location of the image used when the application launches. For the iPhone, this image must be named Default.png. Depending on the device type and orientation, this image can be overridden by the images selected for its portrait or landscape versions. The ADF Mobile deployment framework attaches the Portrait and Landscape modifiers to the file names, as well as @2x for images used on Retina displays. Table 16-4 lists the required dimensions, in pixels, for the splash screen images.

     Table 16-4 Dimensions for Splash Screen Images

     Device	Portrait	Landscape
     iPhone	320 x 480	N/A
     iPad	768 x 1004	1024 x 748
     iPad Retina	640 x 960	2048 x 1496
     iPhone Retina	1536 x 2008	N/A

     
     

4. Click OK.

Figure 16-13 Adding Custom Images

16.2.4.4 What You May Need to Know About iTunes Artwork

By default, ADF Mobile applications deployed to an iOS device through iTunes, or deployed as an archive (.ipa file) for download, use the default Oracle image, shown in Figure 16-12 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 16-14 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 16-14 Custom and Default Application Icons

During deployment, ADF Mobile 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.

16.2.4.5 How to Restrict the Display to a Specific Device Orientation

By default, ADF Mobile 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 16-15

Figure 16-15 Select a Device Orientation

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

1. Choose Device Orientations, as shown in Figure 16-15.

2. Clear all unneeded orientations from among those listed in Table 16-5. By default, ADF Mobile deploys to all of these device orientations. By default, all of these orientations are selected.

   Table 16-5 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.

   
   

3. Click OK.

16.2.4.6 What Happens When You Deselect Device Orientations

Deselecting a device orientation updates the source .plist file.

16.3 Deploying an Android Application

After you define the deployment profile, you can deploy an ADF Mobile application to the Android platform using the Deployment Action dialog, shown in Figure 16-16. Using this 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, this dialog enables you to bundle the ADF Mobile application as an Android application package file (.apk) so that it can be published to end users through an application marketplace, such as Google Play.

Tip:

As an alternative to the Deployment Action dialog, you can deploy an ADF Mobile application to the Android platform manually using the OJDeploy command line tool as described in Section 16.6, "Deploying ADF Mobile Applications from the Command Line."

Figure 16-16 Deployment Action Dialog for Android Applications

16.3.1 How to Deploy an Android Application to an Android Emulator

You can deploy the ADF Mobile application directly to an Android emulator.

Before you begin:

Deployment to an Android emulator requires the following:

• Configure the debug password in the ADF Mobile Platforms preference page (accessed by choosing Tools > Preferences > ADF Mobile).

  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.

• In the Android Options page of the deployment profile:

  1. Ensure that Debug is selected.

  2. Click OK.

  Note:

  The ADF Mobile Platforms preferences page must be configured with the password that is used to generate the keystore and key for debug-mode deployment. See Section 16.2.3.3, "Defining the Android Signing Options."

• Start the Android emulator before you deploy an application.

  You can start the emulator using the Android Virtual Device Manager, as illustrated in Figure 16-17, 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 during a deployment.

  Figure 16-17 Starting an Emulator Using Android Virtual Device Manager

  
  

To deploy an application to an Android emulator:

1. Choose Applications, then Deploy, and then select an Android deployment profile.

2. Choose Deploy application to emulator and then choose Next.

3. Review the Summary page, shown in Figure 16-2, choose Back to select another deployment activity or choose Finish. The Summary page displays the following parameters from the deployment profile:

   • Application Bundle Id—The unique, Java language-like package name identifying the application.

     Note:

     The Summary page shown in Figure 16-18 shows that the application bundle ID is in the reverse package format required for a successful deployment to an emulator. Deploying an application that does not follow the reverse-package format causes the emulator to shut down, which prevents the deployment from completing.

   • File—The name of the .apk that is deployed to an Android target.

   • Deploy Mode—The build mode. This value is either Release or Debug, depending on the value set in the deployment profile.

   Figure 16-18 Summary for Android Emulator Deployment

   
   

4. Review the deployment log, as shown in Figure 16-19. The deployment log notes that the deployer starts the Android Debug Bridge server when it detects a running instance of an Android emulator. See also Section 16.3.6, "What You May Need to Know About Using the Android Debug Bridge."

   Figure 16-19 The Deployment Log

   
   

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

You can deploy an ADF 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 JDeveloper, as described in Section 3.5.3, "How to Set Up an Android-Powered Device."

In the Deployment Options page, shown in Figure 16-6, select Debug as the build mode. Ensure that the debug signing credentials are configured in the ADF Mobile Platforms Preferences page, shown in Figure 16-7.

To deploy an application to an Android device:

1. Choose Applications, then Deploy, then select an Android deployment profile.

2. Choose Deploy application to device and then choose Next.

3. Review the Summary page. Click Back or Next.

4. Click Finish.

16.3.3 How to Publish an Android Application

After you have tested and debugged the application, as described in Chapter 18, "Testing and Debugging ADF Mobile 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:

In the Android Options page of the deployment profile, select Release as the build mode.

Note:

You must configure the signing options in the ADF Mobile Platforms preferences page (accessed by choosing Tools > Preferences > ADF Mobile) as described in Section 16.2.3.3, "Defining the Android Signing Options."

To deploy an application as an .apk file:

1. Choose Applications, then Deploy, then select an Android deployment profile.

2. Choose Deploy application to package and then choose Next.

3. Review the Summary page, shown in Figure 16-18. Click Back or Next.

4. Click Finish.

5. Publish the application to an application marketplace.

16.3.4 What Happens in JDeveloper 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

• adfmf-application.xml and adfmf-feature.xml files

• logging.properties file

• The JVM 1.4 files

Table 16-6 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

16.3.5 Selecting the Most Recently Used Deployment Profiles

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.

16.3.6 What You May Need to Know About Using the Android Debug Bridge

The deployment 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 Figure 16-20.

Figure 16-20 Deployment Terminated

If you are using the Android Debug Bridge command line tool prior to deployment, then you must enter the same command again after the deployment has completed. For example, if you entered adb logcat to view logging information for an emulator or device prior to deployment, you would have to enter adb logcat again after the application has been deployed to resume the retrieval of the logging output. For more 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).

16.4 Deploying an iOS Application

The Deployment Action dialog, shown in Figure 16-21, 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.

Figure 16-21 The Deployment Action Dialog (for iOS Applications)

Tip:

As an alternative to the Deployment Action dialog, you can deploy an ADF Mobile application to the Android platform manually using the OJDeploy command line tool as described in Section 16.6, "Deploying ADF Mobile Applications from the Command Line."

16.4.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:

• Set the location of the SDK of the iOS simulator in the ADF Mobile Platforms preference page, shown in Figure 16-23.

• In the iOS Options page of the deployment profile, select Debug, and then click OK.

  Note:

  You must enter the location of the provisioning profile and the name of the certificate in the ADF Mobile Platforms page (accessed by choosing Tools > Preferences > Platforms). For more information, refer to Section 16.2.4.2, "Setting the Device Signing Options."

• 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.

  Refer to the "Using iOS Simulator" section in iOS Development Workflow Guide. The iOS simulator is installed with Xcode. For deployment to an actual device, refer to the "Managing Devices and Digital Identities" section in iOS Development Workflow Guide.

• Shut down the iOS simulator (if it is running).

To deploy an application to an iOS simulator:

1. Choose Applications, then Deploy, then select an iOS deployment profile.

2. Choose Deploy application to simulator and then choose Next.

3. Review the Summary page, shown in Figure 16-22, which displays the following values. Click Finish.

   • Application Bundle Id—The unique name that includes a Java language-like package name (com.<organization name>.<application name>) prepended 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 developer or company that authored the application. If this value has not been configured in the Options 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 Options page of the deployment profile, then the Summary page displays <Not Specified>.

   Note:

   Deployment to an iOS simulator does not require that the values for Certificate and Provisioning profile be defined. In this deployment scenario, the Summary page displays <Not Specified> for these values.

   Figure 16-22 The Deployment Actions Summary Dialog

   
   

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

The Deploy to iTunes for Synchronization to device option enables you to deploy an ADF Mobile application to an Apple device for debugging and testing.

Before you begin:

You cannot deploy an application directly from JDeveloper 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 set the location of the Automatically Add to iTunes folder (the location used for application deployment) in the ADF Mobile Platforms preference page, shown in Figure 16-23.

  Tip:

  Although your user home directory (/User/<username>/Music/iTunes/iTunes Media/Automatically Add to iTunes) 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 ADF Mobile Platforms preference page.

• Set the location of the Xcode folder where the xcodebuild tool is invoked, such as /Developer/usr/bin in Figure 16-23.

  Figure 16-23 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 ADF Mobile Platforms 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. ADF Mobile logs applications that fail to deploy under such circumstances. For more information, see Section 16.4.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 Debug as the build mode and then OK.

To deploy an application to an iOS-powered device:

1. Choose Applications, then Deploy, then select an iOS deployment profile.

2. Choose Deploy to iTunes for Synchronization to device and then choose Next.

3. Review the Summary page, which displays the following values. Click Finish.

   • Application Bundle Id—The unique name that includes a Java language-like package name (com.<organization name>.<application name>) prepended 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 developer (or company) who authored the application. If this value has not been configured in the Options 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 Options page of the deployment profile, 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 deployment to iTunes.

4. Connect your iOS device to the development computer.

5. Open iTunes and then synchronize your device.

16.4.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 16-14 after a successful deployment.

16.4.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 to 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 Development Program. You enter the location of the provisioning profile and the name of the certificate in the Options page as described in Section 16.2.4.2, "Setting the Device Signing Options."

As noted in the "Distributing Apps" chapter in Tools Workflow Guide for iOS, 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 16-24 The iOS Provisioning Portal

16.4.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.

16.4.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).

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

Figure 16-25 An Explicit Application ID

Applications that share files or Keychains (or do not use a Keychain), however, substitute a wildcard character (*) for the application name, such as 8E549T7128.com.oracle.*. Using this format, a suite of applications can share an application ID. For example, if the administrator names com.oracle.ADF.* on the iOS Provisioning Portal, it enables you to specify different applications (com.oracle.ADF.application1 and com.oracle.ADF.application2).

16.4.5 How to Distribute an iOS Application to iTunes

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 iTunes, 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:

• Test the application on an actual iOS device. See Section 16.4.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 "Distributing Apps" section in Tools Workflow Guide for iOS and iTunes Connect Developer Guide. These guides are both available through iOS Developer Library (http://developer.apple.com/library/ios/navigation/).

• 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 iTunes:

1. Choose Applications, then Deploy, and then select an iOS deployment profile.

2. Choose Deploy to Distribution Package.

3. Review the Summary page, which displays the following values. Click Finish.

   • Application Bundle Id—The unique name that includes a Java language-like package name (com.<organization name>.<application name>) prepended 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 Options 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 Options page of the deployment profile, 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.

4. Log in to iTunes Connect.

5. 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.

6. 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.

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

16.4.5.1 What Happens in JDeveloper When You Deploy an Application to an iOS Simulator or iOS-Powered Device

JDeveloper performs the following tasks after you complete the deployment wizard:

1. Validates that the necessary software prerequisites are installed. For example, such tasks include:

   1. Validating that the path to the iOS SDK that was set in Preferences is valid and accessible.

   2. Validating that the path to the xcodebuild tool (which is set in the ADF Mobile Platforms page) that was set in Preferences is valid and accessible. The xcodebuild tools is an Apple utility that compiles iOS projects.

   3. Performing other validation as needed.

2. Deletes any pre-existing template for this deployment profile to ensure that any new deployment does not use configuration set for previous deployments.

3. Validates the applications and all of the XML content of both the applications and the projects.

4. For a first-time deployment (or after you select Build > Clean), JDeveloepr unzips the Oracle_ADFmc_Container_Template file for iOS to a temporary location. That is, modules\adf-mobile\dist\jdev\extensions\oracle.adf.mobile\Oracle_ADFmc_Container_Template.zip is unpackaged to a profile sub-directory in the deploy directory.

   Tip:

   Selecting Build > Clean enables you to modify the Xcode project settings, which provide additional options to those available in JDeveloper.

   JDeveloper also unzips the necessary ADF Mobile libraries from modules\adf-mobile\dist\jdev\extensions\oracle.adf.mobile\Oracle_ADFmc_Framework_Libraries.zip to the Framework directory in the previously unzipped template.

   Note:

   Any libraries dependent on the type of deployment (that is, debug, release, or deployment to a simulator, device, or as an archive) are added to the template at a later stage.

5. Copies custom images selected by the user to the template location. If custom images have been selected in the deployment profile, JDeveloper copies those images and renames them to the appropriate name. The iOS template internally uses the names icon.png, icon-2x.png, icon-72.png, Default.png, Default-Landscape.png and Default-Portrait.png for the application icon names and splash screen names. For any image that has not been customized, JDeveloper copies the default image to the template.

6. Copies the web content (including any images related to features) to the template location. As a result, the public_html folder and its subdirectories within the ADF Mobile project are copied to the www folder in the template.

7. Copies the metadata files to the template location:

   1. Copies the adfmf-application.xml file.

   2. Combines all of the adfmf-feature.xml files into one file and places it in the template.

8. Creates and updates the .plist files. See also Section B.3, "Converting Preferences for iOS."

   1. Creates the preferences .plist files from the metadata files. These files create the preferences that are available from the iOS Settings application.

   2. Updates the root.plist file with the application name, the bundle identifier, the version, and the flag that determines the use of pre-rendered icons. The application name, bundle identifier, and version are retrieved from the adfmf-application.xml file and the iOS Options page, shown in Figure 16-10, "Setting the iOS Options".

9. Runs the xcodebuild utility with the correct flags for the chosen deployment. For example, a debug build deployed to an iOS simulator (Version 5.0) is as follows:

   xcodebuild clean install -configuration Debug -sdk iphonesimulator5.0
   

10. Deploys the newly built application to the proper location.

    1. Copies the iOS application bundle to a unique application directory, as required for deployment to the iOS simulator.

    2. Runs the xcrun command to package the application into the .ipa file. This command creates an .ipa that has a folder entitled Payload, which contains the application. It also adds the provisioning profile and signs the application with the developer's name. An example of the xcrun command is as follows:

       /usr/bin/xcrun -sdk iphoneos PackageApplication -v "%PROJECT_BUILDDIR%/SampleApp.app" -o "SampleApp.ipa" --sign "iPhone Developer: John Doe (A1BC2DEFGH)" --embed "/Users/jdoe/Desktop/my_profile.mobileprovision"
       

11. If this is a deployment to a device, JDeveloper moves the .ipa file to the iTunes Media/Automatically Add to iTunes directory.

16.5 Deploying Feature Archive Files (FARs)

To enable re-use by ADF Mobile view controller projects, application features— typically, those implemented as ADF Mobile AMX or Local HTML— are bundled into an archive known as a Feature Archive (FAR). A FAR is essentially a self-contained collection of application feature elements that can be consumed by ADF Mobile applications, such as icon images, resource bundles, HTML, JavaScript, or other implementation-specific files. (A FAR can also contain Java classes, though these classes must be compiled.) Example 16-1 illustrates the contents of a FAR, which includes a single adfmf-feature.xml file and a connections.xml file. For more information on connections.xml, see the "connections.xml" and "Reusing Application Components" sections in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

Example 16-1 Contents of a Feature Archive File

connections.xml (or some form of connection metadata)
 
  META-INF
     adfm.xml
     adfmf-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 is comprised of the following tasks:

1. Creating a Feature Archive file—You create a Feature Archive by deploying a feature application as a library JAR file.

2. Using the Feature Archive file when creating an ADF Mobile application—This includes importing FARs and re-mapping the imported connection.

3. Deploying an ADF Mobile application that includes features from FARs—This includes unpacking the FAR to a uniquely named folder within the deployment template.

   Note:

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

16.5.1 How to Create a Deployment Profile for a Feature Archive

Use the Create Deployment Profile dialog, shown in Figure 16-9.

Figure 16-26 Create ADF Mobile Feature Dialog

Before you begin:

Create the appropriate connections for the application. See the "Naming Considerations for Connections" section in Oracle Fusion Middleware Fusion Developer's Guide for Oracle Application Development Framework.

How to create a deployment profile for a Feature Archive:

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

   Note:

   You do not need to create a separate, application-level deployment profile.

2. Select ADF Mobile Feature Archive in the Create Deployment Profile dialog.

3. Enter a profile name, or accept the default, and then click OK.

   Note:

   Name the profile appropriately. Otherwise, you may encounter problems if you upload more than one application feature with the same archive name. For more information, see Section 5.12.3, "What You May Need to Know About Enabling the Reuse of Feature Archive Resources."

4. Select the connections that you want to include in the Feature Archive JAR file, as shown in Figure 16-27.

   Figure 16-27 Selecting a Connection for the FAR

   
   

5. Click Next, review the options, and then click Finish.

16.5.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, shown in Figure 16-28, includes only one deployment option, Deploy to feature archive JAR file.

Figure 16-28 Deployment Actions

How to deploy the Feature Archive deployment profile:

1. Right-click the view controller project and then select the Feature Archive deployment profile.

2. Click Finish. The Summary page, shown in Figure 16-29, displays the full path of where the Feature Archive file's JAR path is deployed.

   Figure 16-29 Deployment Summary Page

   
   

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

After you complete the deployment action dialog, ADF Mobile creates a library JAR in the path shown in the Summary page. To make this JAR available for consumption by other applications, you must first make it available through the Resource Palette, shown in Figure 16-30 (and described in Section 5.12.1, "How to Use FAR Content in an ADF Mobile Application") by creating a connection to the location of the Feature Archive JAR. Figure 16-30 shows Feature Archives that can be made available to an ADF Mobile application through a file system connection. For more information, see "Working with the Resource Palette" in Oracle Fusion Middleware User's Guide for Oracle JDeveloper.

Figure 16-30 Deployed Feature Archive JARs in the Resource Palette

16.6 Deploying ADF Mobile Applications from the Command Line

You can deploy iOS or Android deployment files from JDeveloper without starting the JDeveloper IDE 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 iOS or Android deployment files using Deployment Profile Properties editor, you can use OJDeploy to deploy applications to iOS simulators and iOS-powered devices (through iTunes), or as iOS bundles (.ipa 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 Android application package files (.apk files) or as Feature Archive JAR files. For information on OJDeploy, see "Deploying from the Command Line" in Oracle Fusion Middleware User's Guide for Oracle JDeveloper.

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

16.6.1 Using OJDeploy to Deploy ADF Mobile Applications

The following commands enable you to deploy ADF Mobile deployment profiles:

• deployToDevice—Deploys an application to iOS- or Android-powered devices. For iOS applications, this command is used in debugging scenarios where the application is deployed to a device using iTunes. For more information, see Section 16.4.5, "How to Distribute an iOS Application to iTunes."

• deployToSimulator—Deploys an application to an iOS simulator or Android emulator. You can only deploy an ADF Mobile application to an iOS simulator on an Apple computer.

• deployToPackage—Deploys an iOS application as an .ipa file or an Android application as an .apk file. You can only package an application as an .ipa file on an Apple computer.

• deployToFeatureArchive—Deploys a Feature Archive to a JAR file.

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

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

Note:

OJDeploy commands and arguments are case-sensitive.

Table 16-7 lists the OJDeploy arguments that you use to modify the ADF Mobile deployment commands.

Tip:

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

Table 16-7 OJDeploy Arguments for ADF Mobile Deployments

Argument	Description
-profile	The name of the Android or iOS deployment profile. For example: ojdeploy deployToSimulator -profile iosDeployProfile ...
-workspace	The full path to the ADF Mobile application file (.jws). For example: ... -workspace /usr/jsmith/mywork/Application1/Application1.jws
-project	For the deployToFeatureArchive command, you must provide the name of the project (that is, a view controller project) that contains the Feature Archive deployment profile. For example: ojdeploy deployToFeatureArchive -profile farProfileName -project ViewController ...

In addition to the arguments listed in Table 16-7, you can also use OJDeploy options described in the "Command Usage" section of Oracle Fusion Middleware User's Guide for Oracle JDeveloper.

Note:

The following options are not supported:

• -forcerewrite

• -nocompile

• -nodatasources

• -nodepdendents

• -outputfile

• -updatewebxmlejbrefs

Table 16-8 provides examples of how to use the OJDeploy options with the ADF Mobile deployment commands.

Table 16-8 OJDeploy Options for ADF Mobile Deployments

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