19 Deploying Mobile Applications

19.1.1 MAF Deployment Options

MAF executes the deployment 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. 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.

19.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 19-1, are included in the deployment artifacts for the project. This dialog enables the application features to access these libraries at runtime.

Figure 19-1 Adding Libraries to the Project

19.2.1 How to Create a Deployment Profile

As described in Section 3.2.2.3, "About Automatically Generated Deployment Profiles," MAF creates a set of deployment profiles when you create a mobile application. You can deploy an application using these profiles, edit them, or construct new ones using the MAF-specific deployment profile pages. The Create Deployment Profile wizard, shown in Figure 19-2, enables you to create a default deployment profile from these pages. You can create as many deployment profiles as needed. For more information on these standard deployment profile pages, click Help to see the JDeveloper online help.

Before you begin:

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

To create a deployment profile:

1. Choose Application and then Deploy.

2. Choose New Deployment Profile.

3. Depending on the target platform, select either MAF for Android, MAF for iOS, or MAF Application Archive, as shown in Figure 19-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 19-2 The Create Deployment Profile Wizard

   
   

19.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 19-1 lists the MAF-specific pages in the Deployment Profile Properties editor, shown in Figure 19-5.

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

19.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 (.apk) file.

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 2.5, "Setting Up Development Tools for Android Platform."

To enable the deployment framework to compile files required for push notifications, install the package for the Google Cloud Messaging Library (Revision 3 and later) and also the Android Support Library in the Android SDK Manager, as shown in Figure 19-3.

Figure 19-3 The Google Cloud Messaging For Android Library Package

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 Android platform SDKs (accessed by choosing Tools, then Preferences, then MAF, then Platforms, and then Android) to the locations for the SDK and platform, which are part of the Android SDK package download. Figure 19-4 shows these locations.

The SDK and platform locations for Android 4.4.2 (API 19), which are illustrated in Figure 19-4, differ from earlier versions.

• For Android SDK Location, the path is:

  <SDK Installation>\adt-bundle-windows-x86\sdk
  

  For example, enter:

  C:\adt-bundle-windows-x86\sdk
  

• For Android Platform Location, the path is:

  <SDK Installation>\adt-bundle-windows-x86\sdk\platforms\android-19
  

  For example, enter:

  C:\adt-bundle-windows-x86\sdk\platforms\android-19
  

  Note:

  The structure of the SDK tools is changed in the release of Revision 22, with the build tools components relocated from the platform-tools directory to the build-tools directory. To enable deployment, the Android Build Tools Location field must reference the location of the build tools, the aapt file (appt.exe on Windows systems). The location of this file differs depending on the SDK revision. For Revision 22, this file is located within the build-tools directory (such as SDK Installation\adt-bundle-windows-x86\sdk\build-tools\Android-4.n). For earlier revisions, it is located within the platform-tools directory (such as SDK Installation\adt-bundle-windows-x86\platfrom-tools).

  MAF queries the Android SDK for the location of the appt file and populates the Android Build Tools Location field accordingly. For Revision 22 of the SDK, MAF populates the field with the latest version of the build-tools directory that is installed on the development computer. For revisions prior to 22, MAF populates the field with the location of the platform-tools directory. In this case, the field is read-only.

Figure 19-4 Setting the Android SDK, Platform, and Signing Properties

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 a mobile application's release type as either debug or release. You only need to define the signing key properties once. For more information, see Section 19.2.3.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).

19.2.3.1 Setting the Options for the Application Details

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

• Denote the version of the application. For more information, refer to the "Versioning Your Applications" document, available from 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, see the "zipalign" document, available from the Android Developers website (http://developer.android.com/tools/help/zipalign.html).

• Set the logging level output as either non-verbose or debug (verbose).

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

Figure 19-5 The Deployment Profile Properties Editor (Android Options Page)

To set the application options:

1. Choose Android Options, as shown in Figure 19-5.

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 maf-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 4.3, "Setting the Basic Information for a 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. This element is described in the document entitled "The AndroidManifest.xml File," which is available from 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.

   • Application Archive Name—If needed, enter the name for the .apk file created by MAF. Otherwise, accept the default name.

     By default, MAF bases the name of the .apk file on the application id attribute configured in the maf-application.xml file. For more information, see Section 4.3, "Setting the Basic Information for a Mobile Application."

   • Version Name—The release version of the application code that displays for the user. See also Section 4.3, "Setting the Basic Information for a 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.

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

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

Figure 19-8 Setting Custom Images for an Android Application

Before you begin:

Obtain the images in the PNG, JPEG, or GIF file format that use the dimensions, density, and components that are appropriate to Android theme and that can also support multiple screen types. 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:

1. Click Application Images.

2. Use the Browse function to select the splash screen and icon image files from the project file. Figure 19-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.

3. Click OK.

19.2.4 How to Create an iOS Deployment Profile

For iOS, 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 (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 JDeveloper.

Because Xcode is used during deployment, you must install it on the Apple computer before you deploy the mobile application from JDeveloper.

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 Chapter 2, "How to Configure the Development Environment for Platforms and Form Factors."

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 19.2.4.2, "Setting the Device Signing Options."

To create a deployment profile:

1. Choose iOS Options, as shown in Figure 19-9.

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 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 19.4.4.3, "Registering an Application ID." See also Section 4.3, "Setting the Basic Information for a Mobile Application."

     Note:

     The application bundle ID cannot contain spaces.

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

   • Application Archive Name—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 19-22. It creates an .app file when you select the Deploy application to simulator option. Otherwise, accept the default name. For more information, see Section 19.4.2, "How to Deploy an Application to an iOS-Powered Device" and Section 19.4.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 4.3, "Setting the Basic Information for a 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.

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

   • 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 19-9 Setting the iOS Options

   
   

19.2.4.3 Adding a Custom Image to an iOS 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 19-11, 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 "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 19-11 Adding Custom Images

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.

3. Choose Browse to 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 19.2.4.4, "What You May Need to Know About iTunes Artwork."

4. Select the version and device type to display the available image types in the tree. By default, MAF displays all of the image styles and types available to iPad and iPhone devices. However, you can narrow the selection by selecting the device type and an operating system version, as shown in Figure 19-3. Within the Icon Folder field, MAF displays the location within the application's Resources directory that houses these image files.

   Figure 19-12 Selecting the Image Type

   
   

5. Select an image type from the tree.

6. In the File field, choose Browse to select another image, as shown in Figure 19-13. This image file must exist within the current application.

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

   Figure 19-13 Adding a Custom Image

   
   

   If the name of the JDeveloper notes errors to safeguard against selecting an incorrect (or nonexistent) image file, as shown in Figure 19-14. See also Section 4.10.2, "What You May Need to Know About Selecting External Resources."

   Figure 19-14 Nonexistent Image Warning

   
   

7. Click OK.

19.2.4.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 19-15 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 19-15 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.

19.2.4.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 19-16

Figure 19-16 Select a Device Orientation

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

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

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

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

   
   

3. Click OK.

19.3.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 debug password in the Android Platform preference page (accessed by choosing Tools > Preferences > Mobile Application Framework).

  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 Android Platform preferences page must be configured with the password that is used to generate the keystore and key for debug-mode deployment. See Section 19.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 19-18, 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 19-18 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 19-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 19-19 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 19-19 Summary for Android Emulator Deployment

   
   

4. Review the deployment log, as shown in Figure 19-20. 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 19.3.6, "What You May Need to Know About Using the Android Debug Bridge."

   Figure 19-20 The Deployment Log

   
   

19.3.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 JDeveloper, as described in Section 2.5.2, "How to Set Up an Android-Powered Device."

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

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.

19.3.3 How to Publish an Android Application

After you have tested and debugged the application, as described in Chapter 22, "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:

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

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 19-19. Click Back or Next.

4. Click Finish.

5. Publish the application to an application marketplace.

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

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

• logging.properties file

• The JVM 1.4 files

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

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

Figure 19-21 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).

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

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

• 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 iOS Platform page (accessed by choosing Tools > Preferences > Mobile Application Framework). For more information, refer to Section 19.2.4.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:

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 19-23, which displays the following values. Click Finish.

   • Application Bundle Id—The unique name that includes a Java language-like package name (com.<organization name>.<application name>) prefixed with the Bundle Seed that is generated from the iOS Provisioning Portal.

   • File—The file name of the final image deployed to an iOS target.

   • 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 19-23 The Deployment Actions Summary Dialog

   
   

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

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

  Figure 19-24 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 19.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.

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

1. Choose Applications, then Deploy, and 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>) 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 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 the iOS-powered device to the development computer.

5. Open iTunes and then synchronize the device.

19.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 19-15 after a successful deployment.

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

Figure 19-25 The iOS Provisioning Portal

19.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 4.3.1, "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 19-26 illustrates an application ID that is unique, one that does not share files or the Keychain with any other applications.

Figure 19-26 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.

19.4.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 19-24, enter the location of the Automatically Add to iTunes directory.

  Tip:

  Run iTunes at least once before entering this location. See also Section 19.4.2, "How to Deploy an Application to an iOS-Powered Device."

• Test the application on an actual iOS device. See Section 19.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 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:

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

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.

19.5.1 How to Create a Deployment Profile for a Feature Archive

Use the Create Deployment Profile dialog, shown in Figure 19-27.

Figure 19-27 Create MAF Feature Archive Dialog

Before you begin:

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

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 MAF 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 4.13.4, "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 19-28.

   Figure 19-28 Selecting a Connection for the FAR

   
   

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

19.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 19-29, includes only one deployment option, Deploy to feature archive JAR file.

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

   Figure 19-30 Deployment Summary Page

   
   

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

After you complete the deployment action dialog, MAF 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 19-31 (and described in Section 4.13.1, "How to Use FAR Content in a MAF Application") by creating a connection to the location of the Feature Archive JAR. Figure 19-31 shows Feature Archives that can be made available to a mobile application through a file system connection.

Figure 19-31 Deployed Feature Archive JARs in the Resource Palette

19.6.1 How to Create a Mobile Application Archive File

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

To create a Mobile Application Archive file:

1. Click Application, then Deploy, then New Deployment Profile.

2. In the Create Deployment Profile dialog, choose MAF Application Archive and then click OK, as shown in Figure 19-32.

   Figure 19-32 Creating an MAA Deployment Profile

   
   

3. If needed, enter a name for the Mobile Application Archive in the Application Archives Options page, shown in Figure 19-33, or accept the default name (and path). Click OK.

   Figure 19-33 Entering a Name and Path for the Mobile Application Archive File

   
   

4. If needed, perform the following:

   1. In the Application Descriptors page, shown in Figure 19-34, enter the file group name (or accept the default name) used for the contents of the META-INF folder (application_workspace\src\META-INF).

      Figure 19-34 Entering a File Group Name for the META-INF Contents

      
      

   2. Select the Contributors sub-page of this Application Descriptors page to edit the list of directories and JAR files that provide the contents for the file group.

      Figure 19-35 Editing Contributors to the Mobile Application Archive File

      
      

   3. Use the Filters page, shown in Figure 19-36 to edit the files that will be included in the .maa file or set the content inclusion or exclusion rules.

      Figure 19-36 Including (or Excluding) Files and Directories

      
      

   4. Use the Profile Dependencies page, shown in Figure 19-37, to specify dependent profiles within the project.

      Figure 19-37 Selecting Deployment Profiles

      
      

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

1. Choose Application, then Deploy and then choose the MAF Application Archive deployment profile.

2. In the Deployment Action wizard, select Deploy application to MAA, as shown in Figure 19-38.

   Figure 19-38 Deployment to a MAF Application Archive File

   
   

3. Click Next to review the deployment summary, as shown in Figure 19-39.

   Figure 19-39 MAF Application Archive Deployment Summary

   
   

4. Click Finish.

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

1. Choose File and then New.

2. In the New Gallery, choose Applications and then MAF Application from Archive File.

   Note:

   Alternatively, you can choose File, then Import, and then MAF Application from Archive File.

3. In the Location page, choose Browse in the MAA File field.

4. In the Select MAA File to Import page, highlight the .maa file, as shown in Figure 19-40, and then click Open.

   Figure 19-40 Selecting the .maa File

   
   

5. If needed, perform the following, or accept the default values:

   1. Enter a name for the mobile application derived from the .maa file in the Application File field, as shown in Figure 19-41.

   2. Click Browse to retrieve the directory of the mobile application.

   Figure 19-41 Entering the Directory Location

   
   

6. Click Next.

7. Review the import summary information and then click Finish.

   Figure 19-42 Summary of MAF Application Archive Contents

   
   

19.7.2 What Happens When You Import a MAF Application Archive File

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

1. Creates an application folder.

2. Unpacks the workspace container (.jws) file from the .maa file to the application file and renames it per the user-specified value.

3. Unpacks the adf directory and its contents to the application folder. This directory is renamed .adf.

4. Unpacks the META-INF directory and its contents and places them in a src directory in the application folder.

5. Unpacks the ExternalLibs directory and its contents to the application folder.

   Note:

   While any of the external resources contained in this directory are available in the mobile application that has been packaged as an .maa file (and imported into the application), the references to these resources will be invalid for a mobile application derived from the .maa file.

6. Unpacks the resources directory to the application folder.

7. Unpacks all folders that contain FARs (or other libraries) that are internal to the original mobile application. MAF preserves the original locations of these artifacts.

8. For each JAR file within the original mobile application's Projects directory, MAF performs the following:

   • Creates a project folder under the application directory that corresponds to the name of the JAR file (but without the .jar extension).

   • Unpacks the contents of the JAR files into the appropriate project folder. MAF includes the following in these project folders:

     • The original .jpr file.

     • The standard directories, such as META-INF, public_html, src, and adfmsrc.

     • The contents of the ExternalLibs directory.

       Note:

       While any of the external resources contained in this directory are available in the MAF project that has been packaged with the imported .maa file, the references to these resources will be invalid for an existing project, or a project created by importing the .maa file.

     • The classlib directory, which contains any Java classes packaged in a JAR file.

       Note:

       If the .maa file includes a classlib directory, then MAF adds all of the JAR files from this directory as library dependencies in the newly created mobile application.

19.8.1 Using OJDeploy to Deploy Mobile Applications

The following commands enable you to deploy MAF 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 19.4.5, "How to Distribute an iOS Application to the App Store."

• deployToSimulator—Deploys an application to an iOS simulator (as an .app file) or Android emulator. You can only deploy a mobile application to an iOS simulator on an Apple computer.

• deployToPackage—Deploys an iOS application as an .ipa file 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.

• deployToApplicationArchive—Packages a mobile application as a MAF Application Archive (.maa) file.

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

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

Table 19-6 lists the OJDeploy arguments that you use to modify the MAF deployment commands.

ojdeploy deployToSimulator -profile iosDeployProfile ...

... -workspace /usr/jsmith/mywork/Application1/Application1.jws

ojdeploy deployToApplicationArchive
         -profile applicationArchiveProfile
         -workspace /usr/jdoe/Application1/application1.jws

ojdeploy deployToFeatureArchive
         -profile farProfileName
         -project ViewController
         ...

In addition to the arguments listed in Table 19-6, you can also use OJDeploy options described in the "Command Usage" section of Oracle Fusion Middleware Developing Applications with Oracle JDeveloper.

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

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

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

Table 19-8 lists the macros used with the deployToApplicationArchive command: