8 Deploying ADF Mobile Client Components

8.1.1 Application Deployment Prerequisites

Before you deploy applications, you must obtain and configure the software appropriate to the target deployment platform and the Oracle database, Oracle Database Lite, and SQLite databases as described in Chapter 2, "Setting Up the ADF Mobile Client Environment."

8.2.1 How to Deploy the Runtime Components

The Deploy to ADF Mobile Client Runtime options enable you to deploy the ADF client runtime, along with the Mobile Sync (mSync) to a Windows Mobile device or emulator or to a BlackBerry smartphone or simulator. For Windows Mobile, you can also deploy the Java Virtual Machine (Java Micro Edition Connected Device Configuration HotSpot Implementation).

Before you begin:

Configure the environment for Windows Mobile emulators or BlackBerry Smartphone simulators as described in Section 2.6, "Setting Up Development Tools for Windows Mobile Platform" and Section 2.7, "Setting Up Development Tools for BlackBerry Platform." For deployment to a BlackBerry smartphone, you must connect the smartphone to the development computer using a compatible USB cable.

To deploy the ADF Mobile client runtime and mSync to BlackBerry smartphones and simulators:

1. Choose Tools and then choose Deploy ADF Mobile Client Runtime.

2. Depending on the deployment target, select either to BlackBerry Smartphone or to BlackBerry Simulator.

3. Select the runtime components. Choose either ADF Mobile Client Runtime or Data Sync (which deploys mSync), or both.

4. Click Deploy.

5. View the entries written to JDeveloper's Deployment-Log. Example 8-1 illustrates a deployment log to a BlackBerry Smartphone simulator:

   Example 8-1 Deployment-Log Entries for Runtime Component to a BlackBerry Smartphone Simulator

   [03:41:22 PM] Copying files to simulator located at: C:\Program Files\Research In Motion\BlackBerry Smartphone Simulators 4.7.1\4.7.1.65 (9630)
   [03:41:23 PM] Files copied successfully. You must restart the simulator before running the Mobile Client application.
   

6. Restart the BlackBerry smartphone simulator (for deployment to a simulator).

To deploy the ADF Mobile client runtime, mSync, and JVM to Windows Mobile devices and emulators:

1. Choose Tools and then choose Deploy ADF Mobile Client Runtime.

2. Choose to Windows Mobile.

3. Select a runtime component, such as ADF Mobile Client Runtime, Data Sync, or Java Virtual Machine.

   Note:

   For Windows Mobile, you must deploy runtime components one after another; you must wait for deployment of one component to complete before you can select the next one.

4. Click Deploy.

5. Monitor the component's deployment progress on the Windows Mobile device or emulator.

6. If needed, select another runtime component and then click Deploy.

7. Click Close.

8. View the entries written to JDeveloper's Deployment-Log. Example 8-2 illustrates deployment of mSync (resulting from selecting the Data Sync option):

   Example 8-2 Deployment of Data Sync (mSync) to a Windows Mobile Emulator

   [01:00:25 PM] Copying file: C:\JDev\jdeveloper\jdev\extensions\oracle.adfnmc.core\WindowsMobile\deploy\wm6\sqlite.us.ppc60.armv4i.CAB
   [01:02:18 PM] Data Sync file copied. Monitor installation progress from the device or emulator...
   

8.3.1 How to Create Data Sync Publications

The Sync Publication page (Figure 8-4) enables you to create the connection to the Mobile Server.

Before you begin:

You must install Oracle Database Lite Mobile Server. (Mobile Server). For more information, see Section 2.5, "Setting Up Oracle Database Lite."

You must create the following two types of connections:

• A database connection for the Oracle Lite Mobile Server Repository schema. If you installed Mobile Server with the default settings, this database schema belongs to the MOBILEADMIN user. See also "Installation of Mobile Server" in Oracle Database Lite Getting Started Guide.

• A connection to a local database that synchronizes with the back-end database using Mobile Server. You create this connection using the Create Database Connection dialog illustrated in Figure 8-3.

To create data sync publications

1. Right-click the Model project in the Application Navigator, choose New and then Deployment Profiles.

2. Choose ADF Mobile Client Sync Publication as shown in Figure 8-1 and then click OK.

   Figure 8-1 Selecting the Mobile Client Sync Publication Profile

   
   

3. Enter a name for the data sync publication (or accept the default name, as shown in Figure 8-2) and then click OK.

   Figure 8-2 Naming the Data Sync Publication

   
   

4. In the Sync Publication page, select the connection used by the client database that synchronizes with the back-end database through Mobile Server. If no such connection exists:

   1. Click Add.

   2. In the Create Database Connection dialog, enter the name for the connection for the synchronized application, such as MySynchronizedConnection shown in Figure 8-3.

   3. Select ADF Mobile Client as the connection type.

   4. Select Synchronized Database on Client.

   5. Enter the name of the local (client) database that synchronizes with a back-end database through Mobile Server.

   6. Click OK. For more information on the Create Database Connection dialog, click Help to see the JDeveloper online help

   Figure 8-3 Creating a Synchronized Connection

   
   

5. Enter the following:

   • The User Name and Password parameters specify the account associated with this sync publication. This is the same user name and password combination that users enter on the device when prompted for credentials for data synchronization. If this account does not exist on Mobile Server, it will be created automatically when you publish synchronization artifacts.

   • The Database Connection for Oracle Mobile Server Repository Schema parameters represent the Oracle database schema where the Mobile Server artifacts are stored.

     Note:

     This is not the same schema for the base application as described in Section 5.2, "Extending an ADF Application to Mobile Client."

     Click Add to create a connection if one does not already exist or click Edit to update the connection information.

6. Click OK.

   Figure 8-4 The Sync Publication Page

   
   

8.3.2 What Happens When You Create a Database Connection

After you create an ADF Mobile client connection using the Create Database Connection dialog, JDeveloper stores the connection information in the connections.xml file, a file that is created when you create a new connection using JDeveloper. This file is packaged with other meta-data files and deployed to the actual device or simulator. The ADF Mobile client runtime reads the connection.xml file as needed. connections.xml is located in the Application Navigator's Application Resources panel, under either the Descriptors or ADF META-INF nodes.

8.4.1 How to Create a Deployment Profile for BlackBerry Applications

ADF Mobile client applications are deployed to BlackBerry smartphones as COD files. ADF Mobile client enables you to create a deployment profile.

Before you begin:

Set up the BlackBerry environment as described in Chapter 2, "Setting Up the ADF Mobile Client Environment." Deployment requires that you complete this configuration, which includes:

• To enable users to add an application using the ALX file, download BlackBerry Desktop Manager (for the development environment) and BlackBerry Enterprise Server (if you plan on posting the COD to a server in a production environment).

• Download BlackBerry Java Development Environment (JDE 5.0) and a BlackBerry simulator. (The simulator is optional, as you typically use the simulator included in the JDE.) If the application synchronizes with the back-end database using Oracle Database Lite Mobile Server, download the Oracle Database Lite 10g Mobile Development Kit (MDK). Using the ADF Mobile client preferences dialog (accessed by clicking Tools then Preferences then ADF Mobile Client), you set the locations for the JDE and the simulator. When you deploy an application to a BlackBerry smartphone simulator, JDeveloper places the resulting COD file in the simulator's directory. If the application uses Mobile Server, entering the location of the MDK directory adds osync_rim.jar and mSync.jar which enable on-device synchronization. You do not need to specify the MDK location for standalone applications or for applications using web servers for server communications.

• If you deploy to an actual device (that is, a BlackBerry smartphone), you must connect the smartphone to the development computer using a compatible USB cable.

To Create a BlackBerry Deployment Profile

1. Select Application then Application Properties.

2. Click New in the Deployment Page and then choose ADF Mobile Client for BlackBerry as the Archive Type.

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

8.4.1.1 Setting and Modifying Application Details

The Options page enables you to edit the properties of a deployment file and to set the behavior of the BlackBerry Signature tool.

Figure 8-5 The BlackBerry Options Page

To edit the deployment file options:

1. Choose BlackBerry Options.

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

   • Name—The name of the BlackBerry application. This value is populated by default and matches the name of the application workspace.

   • Description—A description of the application.

   • Version—The version number of the application.

     Note:

     You cannot overwrite the same application installed on a BlackBerry smartphone that has the same or higher version number.

   • Vendor—The name of the application vendor.

   • Copyright—The copyright year.

   • ID—An ID for the application.

3. If needed, set the digital signature options as described in Section 8.4.1.2, "Setting the BlackBerry Digital Signature Tool Options" and then click OK.

8.4.1.3 Adding a Customized Icon to a BlackBerry Application

BlackBerry applications require two image files, one for a standard icon and one for showing that the application has focus. RIM recommends using images measuring 80x80 pixels for both of these images. See "Default Themes and Dimensions for Screens and Application Icons on BlackBerry Devices" in BlackBerry Smartphones UI Guidelines Version: 2.4. available at:

http://docs.blackberry.com/

See also "Icons and Indicators" in BlackBerry Smartphones UI Guidelines Version: 2.4 for design guidelines.

Note:

Oracle recommends a size limit under 16K.

8.4.1.3.1 How to Add Custom Icons to a BlackBerry Application

The Application Icons page of the ADF Mobile Client for BlackBerry Deployment Profiles Properties dialog enables you to add custom icons by adding the PNG- or GIF-formatted images for the main and focus icons. If you do not add a custom image file, then the default Oracle icon is used.

Figure 8-6 Adding Custom Icons to a BlackBerry Application

Before you begin:

Obtain the images in the file format, dimensions, pixels, and components appropriate to the BlackBerry theme as described icons in BlackBerry Smartphones UI Guidelines Version: 2.4, available at:

http://docs.blackberry.com/

You must also add the image files to the view controller (MobileClient) project. For example, copy the file containing the application icon PNG and GIF files to:

C:\JDeveloper\mywork\<application_name>\MobileClient\<icon_image file>

To add custom main and focus icons to a BlackBerry application:

1. Click Application Icons.

2. Use the Browse function to select the main and focus icon image files from the project file.

3. Click OK.

8.4.1.4 Deploying BlackBerry Applications

The Deployment Action page, shown in Figure 8-7, enables you to deploy an application to a BlackBerry smartphone or simulator or deploy to a JAR file. It also enables you to deploy the application to a package that end users can manually add to smartphones or simulators by copying it directly or by using the BlackBerry's ALX application loader file. When you package an application, JDeveloper creates an ALX file along with other application objects.

Figure 8-7 The Deployment Action Page with Application-Level Deployment Options

Before you begin:

Set up the BlackBerry environment as described in Section 2.7, "Setting Up Development Tools for BlackBerry Platform."

To deploy an ADF Mobile application to a Blackberry smartphone or simulator:

1. From the main menu, select Application then Deploy, and then choose the BlackBerry deployment profile you created earlier. For more information on creating a deployment profile, see Section 8.4.1, "How to Create a Deployment Profile for BlackBerry Applications."

2. Select Deploy application to device or Deploy application to a simulator. Click Next.

3. Review the Summary page, which lists the name of output JAR, main class and compression level. Click Finish.

4. View the Deployment-Log in JDeveloper. JDeveloper writes lines similar to the following for a successful deployment of a BlackBerry application to a simulator.

   [14:15:55 PM] Deploying Mobile Client application to BlackBerry simulator located at C:\Program Files\Research In Motion\BlackBerry JDE 5.0.0\simulator.
   [14:15:55 PM] Mobile Client application successfully deployed to BlackBerry simulator. Please start or restart the simulator before running the Mobile Client application.
   [14:15:55 PM] Elapsed time for deployment: 5 second
   [14:15:55 PM]  --- Deployment finished. ---
   

To deploy an ADF Mobile application directly to BlackBerry smartphone or simulator:

You can deploy an application directly by copying the application files to the BlackBerry smartphone or simulator. Depending on what files are in use at the time, installing the application may trigger a restart on the smartphone. On the simulator, the application files that you deploy are available when you next start the simulator.

Selecting the Deploy Application to Package option results in the creation of COD and ALX files.

To deploy an ADF Mobile application directly to an ALX file:

1. Choose Deploy Application to Package.

2. If you are deploying to the actual smartphone, connect the smartphone to the computer using a compatible USB cable.

3. In the Main Menu of BlackBerry Desktop Manager, select Application Loader.

4. Select Add/Remove Applications.

5. Click Browse to locate ALX file. It is at the same location where JDeveloper created the package.

6. Select the ALX file.

7. Click Next in the Application Loader screen.

8. Click Finish.

8.4.1.4.1 Selecting 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. Figure 8-8, for example, shows shortcuts to recently used deployment profiles called FodMobile_BB1 to BlackBerry device and FodMobile_BB1 to BlackBerry simulator that were created as a result of choosing the Deploy application to device and Deploy application to simulator options. Choosing these shortcuts redeploys the application.

Figure 8-8 Deployment Shortcuts

8.4.2 How to Create a Deployment Profile for Windows Mobile

ADF Mobile client applications are deployed to Windows Mobile devices and emulators as CAB (cabinet) files.

Before you begin:

Set up the Windows Mobile environment as described in Chapter 2, "Setting Up the ADF Mobile Client Environment."

To create a deployment profile:

1. Open the deployment properties for the application by clicking Application then Application Properties and then Deployment.

2. Click New in the Deployment page.

3. In the Create Deployment Profile Dialog, choose ADF Mobile Client for Windows Mobile.

4. Enter a name for the deployment profile, click OK.

5. Click OK.

8.4.2.1 Setting the JAR File Options

The CAB file includes an application JAR file, a launcher executable file, and an options file. These components bear the same name as the deployment profile. For example, the CAB for a profile called MyApplication would include MyApplication.exe (the launcher), MyApplication.options, and MyApplication.jar.

8.4.2.1.1 About the Launcher Executable File

The launcher executable (the launcher) simplifies the configuration of ADF Mobile client applications by dynamically building a command line that starts the Oracle Java Micro Edition Connected Device Configuration HotSpot Implementation (a JVM) and launches the application JAR, thus eliminating the need to specify this information at buildtime. The launcher contains the application icon in Windows Mobile applications. When you specify an application icon using the deployment profile's Application Icon page, it is embedded in the application's copy of the launcher executable before it is packaged.

The launcher has its own set of command line arguments (listed in Table 8-2) and can use the classpath-related Java command line arguments to rewrite the classpath. The launcher passes all other command line arguments (that is, those not specific to a Java class path or to the launcher itself) directly to Java unaltered. These arguments can be entered on the command line, or specified in the options file.

Note:

The typical ADF Mobile client application does not require these arguments.

Table 8-2 Command Line Arguments

Argument	Description
-options <filename>	Instructs the launcher file to read a file containing command line options. This argument cannot be placed in the options file itself.
-adfmc <directory>	Specifies the directory where ADF Mobile client is installed. Use this argument to override the value configured by the registry.
-java <directory>	Specifies the directory where Java is installed. Use this argument to override the value configured by the registry.
-olite <directory>	Specifies the directory where Oracle Database Lite is installed. Use this argument to override the default directory.
-stdout <filename>	Specifies the file that receives the standard output stream.
-stderr <filename>	Specifies the file that receives the standard error output stream.
-wait	Use this argument to instruct the launcher to wait until the Java process has exited before it itself exists.
-silent	Use this argument to instruct the launcher to not use a modal message box to report errors. This argument is useful for running applications in a scripted environment.

8.4.2.1.2 About the Options File

The options file contains the command line arguments used at application startup. The launcher automatically finds this file. Example 8-3 illustrates a typical options file called MyApplication.options. This example shows that a full path is not required for the JAR file (MyApplication.jar) because it resides in the same directory as both the launcher and options files. The launcher expands the path and adds it to the classpath when invoking the Java executable.

Tip:

Because the options file is regenerated each time you deploy an application, enter command line arguments in the Command Line Options or Additional Java Options fields of the Window Mobile deployment profile's Options page instead of the options file itself.

Example 8-3 The Options File

-classpath MyApplication.jar
oracle.adfmc.Main

Example 8-4 shows an options file that uses JDWP (Java Debugging Wireline Protocol) interface to debug an application running on a device.

Note:

You can also set these arguments using the Additional Java Options field as described in Section 8.4.2.1.4, "How to Set the JAR Options."

Example 8-4 Debugging Running Applications with JDWP

-classpath MyApplication.jar
-Xdebug -agentlib:jdwp=transport=dt_socket, server=y, address=4041
oracle.adfmnc.Main

In the options file, all options before the startup class name are issued to either Java or the launcher itself. To pass arguments to the application instead, supply them after the startup class, as illustrated by "argument one" in Example 8-5.

Example 8-5 Setting Application-Specific Arguments

-classpath MyApplication.jar
oracle.adfmc.Main
"argument one" arg2 arg3

These options are set using the Application Command Line Parameters field in the Windows Mobile Options page. For more information, see Section 8.4.2.1.4, "How to Set the JAR Options."

8.4.2.1.3 About Debugging A Windows Mobile Application

ADF Mobile client enables you to run an application in debug mode on both Windows Mobile devices or emulators. When you select Generate Debug Launch Shortcut in the Windows Mobile Options page. For more information, see Section 10.3.3, "What Happens When You Choose to Generate the Debug Launcher."

8.4.2.1.4 How to Set the JAR Options

The Windows Mobile Options page, shown in Figure 8-9, enables you to set the information for the information for the application JAR as well as application start-up or JVM debugging commands.

Figure 8-9 Windows Mobile Options

To set the JAR file options:

1. Choose Windows Mobile Options.

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

   • Application Name—The name of the application on the device. When the CAB installer runs, this value clarifies which application, if any, that you are overriding.

   • Application Directory—The location for the directory on the Windows Mobile device or emulator.

   • Company Name—The name of the company that created the ADF Mobile client application.

   • Additional Java Options—Typically, you use this field for the Java Micro Edition Connected Device Configuration HotSpot Implementation debugging options. These options include -Xdebug, the command for running JVM in debugger mode, and -Xrunjdwp, which loads the Java Debugger Wireline Protocol (JDWP) and its suboptions. Enter -Xrunjdwp and its subotptions using the following format:

     -Xrunjdwp:transport=dt_socket,server=y,address=<port>.

     Using the -classpath option, you can also use this field update application classpaths with additional JARs.

     For more information about the debugging options and Java SE-command line options, refer to "Application Debugging Command-Line Options" and "Options" in CDC Runtime Guide, which is included in the ADF Mobile client extension ZIP at adfmc_bundle.zip\jdev\extensions\oracle.adfnmc.core\doc and also available from the Oracle Technology Network (http://www.oracle.com/technetwork/index.html)

   • Application Commandline Parameters—Enter the application-specific command line arguments for such functions as setting the path to the database directory or writing to the log file.

   • Generate Debug Launcher—Generates the executable and a corresponding options file that enable you to run the application in debug mode. For more information see Section 10.3.3, "What Happens When You Choose to Generate the Debug Launcher."

3. Click OK.

8.4.2.3 How to Add Custom Icons to a Windows Mobile Application

The Application Icons page, shown in Figure 8-10, of the ADF Mobile Client for Windows Mobile Deployment Profiles Properties dialog enables you to add an ICO file. If you do not add a custom image file, then the default Oracle icon is used.

Figure 8-10 Adding Custom Icons to a Windows Mobile Application

Before you begin:

Create, or obtain, an ICO file for Windows Mobile devices. The ICO file must contain an icon resource that includes the image files appropriate to the Windows Mobile device.

You must also add the image files to the view controller (MobileClient) project. For example, copy the file containing the ICO files to:

C:\JDeveloper\mywork\<application_name>\MobileClient\<icon_image file>

To add a custom icon to a Windows Mobile application:

1. Click Application Icons.

2. Use the Browse function to select the ICO files from the project file.

3. Click OK.

   Note:

   If you deploy an application using the default Oracle icon and then subsequently re-deploy the application with a custom icon, you must restart the Windows Mobile device or emulator for the custom icon to appear.

8.4.2.4 Deploying a Windows Mobile Application

The Deployment Action page enables you to deploy an application directly to a Windows Mobile device or to create a CAB file by selecting the Deploy application to package option.

Figure 8-11 Windows Mobile Deployment Actions

Before you begin:

Connect a Windows Mobile device to your computer, or start an emulator. Also ensure that ActiveSync or Windows Mobile Device Center has established a link with the device or emulator. For more information, see Section 2.6, "Setting Up Development Tools for Windows Mobile Platform."

To deploy an application to a Windows Mobile device or emulator:

1. Click Application then Deploy and then choose the Windows Mobile deployment profile.

2. Select Deploy Application to Device. Click Next.

3. Review the Summary page, which lists the name of output JAR, the main class, and the compression level. Click Finish.

4. View Deployment-Log in JDeveloper. JDeveloper writes lines similar to the following for a successful deployment of a Windows Mobile application.

   [10:50:12 AM] Windows Mobile package successully deployed.
   [10:50:12 AM] If installing to a physical device, please refer to device to complete installation.
   [10:50:12 AM] Elapsed time for deployment: 1 second
   [10:50:12 AM]  --- Deployment finished. ---
   

5. Complete the installation using the Windows Mobile device or emulator.

To deploy an application directly to the Windows Mobile device or emulator

1. Click Application then Deploy.

2. Select the Window Mobile profile.

3. Select Deploy to Application Package and then click Next.

4. Click Finish.

5. Copy the CAB file to the Mobile device or simulator.

6. Click the CAB file.

7. Follow the prompts to complete the installation.

8.5.1 How to Specify the Client Database Location

You can override the default behavior by specifying the client database location in the Deployment Profile Properties dialog. The fields that appear on this page depend on the type of connection selected for the application. Figure 8-12, for example, shows properties for a synchronized connection used for an application that synchronizes with a back-end server through Mobile Server.

Figure 8-12 The Client Database Page for a Synchronized Connection

Figure 8-13 shows the Client Database page for applications that use a standalone connection and therefore do not synchronize using Mobile Server.

Figure 8-13 Client Database Page for a Standalone Connection

You can use the Client Database page to select the type of connection used by the application or create or edit the connection using the Create Database Connection Dialog, shown in Figure 8-14. See Figure 8-3 for an illustration of using the Create Database Connection page to create a synchronized connection, the default connection type.

Figure 8-14 Creating a Standalone Connection

Before you begin:

For applications that use a custom (local) database and use a SQL script to initialize the database, you may add initialization-related parameters and also provide the SQL script itself. The SQL script is described in Chapter 11, "Working Directly with the Database."

If you select ADF Mobile Client in the Create Database Connection page as shown in Figure 8-3, then you enable the ADF Mobile client framework to use Mobile Server-enabled data synchronization to populate the device's local database when you start an application.

To specify the client database location for synchronizing applications:

1. Accept the default values that appear in the Client Database page, or click Edit (or Add) to define the following properties in the Create Database Connection dialog:

   • Connection Name—Enter a name for the connection, such as one denoting synchronization illustrated by MySynchronizedConnection in Figure 8-3.

   • Connection Type—Select ADF Mobile Client.

   • Synchronized Database on Client—Select this option if the application uses a client (local) database that synchronizes with a back-end database using Mobile Server.

2. In the Client Database page, select one of the following options for retrieving the credentials:

   • Always Prompt for Credentials—Select this option to prompt the user for synchronization credentials each time before initiating synchronization. Although this mode is less convenient for end users, use it if multiple users share a single device and each user requires his or her own subset of data.

   • Use Credentials from Last Login—Select this option to direct the ADF Mobile client framework to use the last-known parameters to automatically initiate synchronization and only prompt the user if synchronization has never been run before. Use this mode in scenarios where each end user has a separate device.

   • Application Provides Credentials—Select this option so that the user is never prompted for synchronization parameters. The application developer provides these credentials in program code instead.

3. Click OK.

To specify the client database location for standalone applications:

1. Accept the default values that appear in the Client Database page, or click Edit (or Add) to define the following properties in the Create Database Connection dialog:

2. Connection Name—Enter a name for the connection, such as one denoting the use of a standalone database illustrated by MyStandaloneConnection in Figure 8-14.

3. Connection Type—Select ADF Mobile Client.

4. Standalone Database on Client—Select this option if the application uses a custom database that is not synchronized using Mobile Server.

   In the Device Database File field, enter the fully qualified path to the database on the device's file system. For BlackBerry, the leading character for this path must be a forward slash (/) character. Table 8-3 lists example path specifications for different usage scenarios:

   Table 8-3 Fully Qualified Paths for BlackBerry

   Usage Scenario	Path Format in Device Database File Field
   BlackBerry with a database on an internal file system	/store/home/user/SAMPLE.db
   BlackBerry with a database on an external SD card	/SDCard/SAMPLE.db

   
   

   Note:

   The name of the removable storage card on Windows Mobile devices is not always Storage Card. On some device models, it may be SD Card, or it may be translated to another language (SD-Karte). Check your target device for the actual name.

   Note:

   In general, SQLite databases on BlackBerry smartphones can only be created on an SD card. While some BlackBerry smartphones permit databases on internal flash memory, you should always specify a database that resides on an SD card to ensure maximum compatibility.

   For Windows Mobile, enter this fully qualified path using a back slash (\) as the leading character for the path. Table 8-4 lists example path specifications for different usage scenarios:

   Table 8-4 Fully Qualified Paths for Windows Mobile

   Usage Scenario	Path Format in Device Database Field
   Windows Mobile device with a database on an internal file system	\SAMPLE.db
   Windows Mobile device with a database on an external storage card	\Storage Card\SAMPLE.db

   
   

   Note:

   In general, you can only create SQL databases in flash memory on Windows Mobile emulators, not on the storage card. Windows Mobile devices, however, do not have this limitation.

5. Click OK.

6. In the Client Database page, select Run Database Initialization Script for applications that do not synchronize with Mobile Server but still require a database. This option enables these applications to use a database created by a simple SQL initialization script that uses a subset of SQL syntax. For more information, see Section 11.2, "Enabling Applications to Use SQL Initialization Scripts."

   • Choose Always if the application should run the specified SQL initialization script every time it starts.

   • Choose if no database if the application should only run the SQL script when the required database does not exist. This is useful in cases where you want the SQL script to initialize the database only when the application starts for the first time.

   The Initialization script field specifies the location of the SQL script. Because this script is embedded as a resource in the application's JAR file during deployment, specify a path relative to the root of this JAR file. For example, if you added a file called SqlScript.sql to the res subfolder of the application, then enter /res/SqlScript.sql.

7. Click OK.

8.5.2 What Happens When You Specify a Client Database

When you deploy an ADF Mobile client application, the settings you entered are written to the adf-config.xml file as a series of key-value pairs. When you run the application, it attempts to connect to the database in one of the following ways:

• Synchronized—The default setting. The Client Database Name field specifies a database that is managed by Mobile Server. At runtime, the ADF Mobile client framework receives the location of this database from the Oracle Database Lite library. The framework invokes data synchronization to populate the database if necessary. For more information, see Section 8.5.3, "What Happens When Oracle Database Lite Mobile Server Manages an Application's Database" and Section 8.5.4, "How the ADF Mobile Client Framework Retrieves Mobile Server Credentials at Application Startup."

• Standalone, with Device Database File parameter specified—The local database will not be synchronized with a back-end database. The Device Database File field specifies an absolute path to the SQLite database on the device's file system. At runtime, the ADF Mobile client framework will open a connection to this database file and optionally initialize it according to the specified Run Database Initialization Script parameters. For more information, see Section 8.5.1, "How to Specify the Client Database Location."

• Standalone, (you do not enter a value into the Device Database File field)—This indicates the application does not require a database at all, and the Mobile client framework will not attempt to open one.

8.5.3 What Happens When Oracle Database Lite Mobile Server Manages an Application's Database

Oracle Database Lite manages the location of the Mobile Server-managed database. The general form for this location is: SQLite.DATA_DIRECTORY/sqlite_db/syncUsername/applicationName.db, where:

• SQLite.DATA_DIRECTORY is a value stored in OSE.TXT, which is found in a platform-dependent location:

  • BlackBerry—/store/home/user/oracle/sync

    Note:

    In general, SQLite.DATA_DIRECTORY points to /SDCard/Databases/oracle on BlackBerry.

  • Windows Mobile—mobile_client_install_root\sqlite, where mobile_client_install_root is usually "\Program Files\ADFmc"

    Note:

    In general, SQLite.DATA_DIRECTORY will be the same as mobile_client_install_root.

• syncUsername is a value gathered at runtime.

When the application requests data for the first time, it attempts to connect to the database at SQLite.DATA_DIRECTORY/sqlite_db/syncUsername/applicationName.db. If this database exists at the specified location, then the application connects to it and continues running. Otherwise, the user is prompted to enter synchronization credentials to allow Mobile Server to connect to the back-end database and perform an initial synchronization to populate the mobile database.

8.5.4 How the ADF Mobile Client Framework Retrieves Mobile Server Credentials at Application Startup

To enable synchronization between Mobile Server and multiple mobile devices, the ADF Mobile client framework requires that users provide the following authentication credentials supplied at runtime:

• Sync username

• Sync password

• Mobile Server hostname/IP address

• Whether to save the password

After a user starts an application on a smartphone, device, simulator, or emulator, the ADF Mobile client framework collects the username, password, Mobile Server URL, and password saving option that it prompts from the user when the application attempts to synchronize data with the Mobile Server. Figure 8-15 shows the page on a BlackBerry simulator that prompts users for these credentials.

Figure 8-15 Prompting User-Provided Mobile Server Credentials

The type of authentication policy you select in the Client Database page dictates which, if any, of the credentials that users must provide to synchronize application data. Figure 8-15, for example, illustrates how selecting the Always Prompt for Credentials option requires users to enter the username, password, and Mobile Server URL credentials when running an ADF Mobile client application on a BlackBerry simulator.

8.6.1 How to Select the Language Resource Bundles for an ADF Mobile Client Application

The Localization page of the Deployment Profile Properties dialog enables you to set the locales for the deployment profile.

Figure 8-16 The Localization Page

Before you begin:

Create a mobile client application comprised of the business components from the base application as described in Section 5.2.1, "How to Create Subsets of Entity Objects and View Objects." This base application must include multi-language resource bundles.

Figure 8-16 shows the project structure of a base application called BaseApp whose language resource bundles include:

• ModelBundle_de.properties

• ModelBundle_en_GB.properties

• ModelBundle_en_US.properties

• ModelBundle_fr.properties

Figure 8-17 Project Structure of a Multi-Language Base (Server) Application

To select language resource bundles:

1. Open the deployment properties for the application by clicking Application then Application Properties and then Deployment.

2. Click New in the Deployment page.

3. In the Create Deployment Profile Dialog, choose either ADF Mobile Client for BlackBerry or ADF Mobile Client for Windows Mobile.

4. Enter a name for the deployment profile and then click OK.

5. For Windows Mobile applications, define the Windows Mobile Options and Client Database options as needed.

6. Click Localization.

7. Choose the appropriate language resource bundle taken from the base application's JAR. Figure 8-18 shows the Localization page lists the resource bundles of the base application JAR. Using the base application called BaseApp shown in Figure 8-17 as an example, an ADF Mobile client application derived from this application would include its language resource bundles, including ModelBundle_de.properties, ModelBundle_en_GB.properties, ModelBundle_en.US.properties, and ModelBundle_fr.properties.

   As shown in Figure 8-18, selecting a folder (such as English (en) in this illustration) automatically selects the locale-specific child nodes.

   Figure 8-18 Selecting Resource Bundles

   
   

8. Click OK.

9. Deploy the application as described in Section 8.4.1.4 and Section 8.4.2.4.

8.6.2 What Happens When You Add Language Resource Bundles to a Deployment Profile

The ADF Mobile client runtime automatically deploys ModelBundle.properties, the base language resource bundle to a JAR file. When you deploy an application, this base language resource bundle, along with the resource bundles selected in the Localization page, are deployed the archive file.

Figure 8-19 shows the JAR file of an ADF Mobile client application called LocAppDemo, which was created from the base application called BaseApp. The resulting JAR file created by deploying LocAppDemo demonstrates that the base resource bundle, ModelBundle.properties along with the language resource bundles selected in the Localization page shown in Figure 8-18 (ModelBundle_en.properties, ModelBundle_en_CA.properties, ModelBundle_en_GB.properties, and ModelBundle_en_US.properties) and were deployed to a JAR file called LocAappDemo_BB1.jar.

Figure 8-19 Localization Bundles Deployed to a JAR

8.6.3 Adding Language Resource Bundles for Multiple Base Application JAR Files

As stated in Section 7.4.2, "Supporting Localization through XLFF Resource Bundles," ADF Mobile client supports both XLIFF (XML Localization Interchange File Format) and .properties resource bundles.

8.6.3.1 How to Add Language Resource Bundles from Another Base Application

Using the Localization page, you can integrate the resource language bundles from different base application JARs.

Figure 8-20 shows a base application JAR called adflibLocalization.jar that contains XLFF-formatted resource bundles localizationBundle_el.xlf and localizationBundle_en_US.xlf as well as the base language resource bundle, localizationBunlde.xlf. ADF Mobile client's support of this format enables you to import these resource bundles into an application that also supports .properties.

Figure 8-20 Base Application JAR with XLFF-Formatted Resource Bundles

To add language resource bundles from another base application JAR file:

1. In the Application Navigator, right-click the MobileClient project.

2. Click New, select the All Technologies tab and then choose Business Components from ADF Library (located under Business Tier).

3. Complete the Create Business Components from ADF Library wizard as described in Section 5.2.1, "How to Create Subsets of Entity Objects and View Objects."

4. Select Application and then Application Properties.

5. Choose Deployment and the choose a deployment profile and then click Edit.

6. Choose Localization and check the resource bundles imported from the new base application JAR as well as those from the first base application JAR.

   As shown in Figure 8-21, the Localization page for the deployment profile of the LocAppDemo application displays resource bundles for Greek, French, and second En_us resource bundle from the second base application, adflibLocalization.jar. Figure 8-21 also shows how the tooltip displays the sources that contributed both of these en_us resource bundles:

   Contributed from:
   C:/JDeveloper/mywork/BaseApp/Model/deploy/BaseApp_Model_adflibBaseAppl.jar
   C:/JDeveloper/mywork/adflibLocalization1.jar
   

   As shown in this figure, the Localization page for LocAppDemo application shows that the United States English Language bundle was imported from resource bundles contributed by adflibLocalization1.jar and BaseApp_Model_adflibBaseApp1.jar.

   Figure 8-21 Tooltips Showing Origin of Resource Bundle

   
   

7. Select the resource bundle and then click OK.

8. Redeploy the application.

8.6.3.1.1 What Happens When You Add Language Resource Bundles from Another Base Application JAR

As shown in Figure 8-22, the resulting JAR file contains deployed language resource bundles from both base application JARs; it contains both base language bundles (localizationBundle.xlf and ModelBundle.properties). The JAR also contains the XLFF bundles from the second base application JAR as well as the English resource bundles (ModelBundle_en.properties, ModelBundle_en_CA.properties, ModelBundle_en_GB.properties, and ModelBundle_en_US.properties) from the first JAR.

As shown in Figure 8-22, LocAppDemo's JAR now has two United States English (en_US) resource bundles after the second deployment: because there are two corresponding language resource bundles for en_US from two different base application JARs, ADF Mobile client added localizationBundle_en_US.xlf along with ModelBundle_en_US.properties.

Figure 8-22 JAR Containing XLFFs and .properties Resource Bundles

8.6.3.2 Manually Adding Resource Bundles

You can add a base language resource bundle to a MobileClient project and use it for a component, such as command button, using the Resource Bundle page accessed through Project Properties.

To add a resource bundle manually:

1. In the Application Navigator, right-click the MobileClient project.

2. In Project Properties, choose Resource Bundles.

3. Click the Bundle Search tab.

4. Click Add and then choose MobileClient.jpr.

   Figure 8-23 shows selecting the MobileClient project as the source of the resource bundle.

   Figure 8-23 Selecting MobileClient.jpr

   
   

5. Browse to the base bundle label within the JAR and then click Open.

   As shown in Figure 8-24, the base JAR contains the following five language resource bundles:

   
   myBaseAppBundle_en.properties
myBaseAppBundle_en_CA.properties
myBaseAppBundle_en_GB.properties
myBaseAppBundle_en_US.properties
myBaseAppBundle_en_it.properties
   

   Figure 8-24 Selecting Language Resource Bundles

   
   

6. Click OK.

   Figure 8-25 shows the resource bundle added from the MobileClient project.

   Figure 8-25 Adding the Resource Bundle from the MobileClient Project

   
   

8.6.3.2.1 What Happens When You Manually Add a Resource Bundle

As shown in Figure 8-26, the Localization panel of the application deployment profile is updated to show the addition of the new resource bundle. This figure shows the Italian language resource bundle was imported from the base JAR, as was another en_US resource bundle.

Tip:

Using the tooltip enables you to see the origin of the resource bundle.

Figure 8-26 Localization Panel Updated with Manually Added Resource Bundles

Using the tooltips, as shown in Figure 8-27, reveals that en_US has been contributed from the following three sources, including the MobileClient project (myBassApp.jar):

C:/JDeveloper/mywork/BaseApp/Model/deploy/BaseApp_Model_adflibBaseApp1.jar
C:/JDeveloper/mywork/adflibLocalization1.jar
C:/JDeveloper/mywork/BaseApp/Model/myBaseApp.jar

Figure 8-27 Tooltips Showing Source of Manually Added Resource Bundle

After you redeploy the application, the updated JAR will contain all of the added resource bundles.

As shown in Figure 8-28, the various en_US resource bundles are those included in the deployed JAR file.

Figure 8-28 JAR Containing Resource Bundles from Various Sources

8.6.3.3 Adding Local Resource Bundles

If an ADF Mobile client application includes local resource bundles, such as Persian (MobileCientBundle_fa.properties, shown in Figure 8-29), the Localization page also displays these resource bundles.

Figure 8-29 A MobileClient Project with Local Language Resource Bundles

You can verify the origin of the local resource bundle using the tooltip as shown in Figure 8-30. For example, the tooltips in this figure reveal the local source for the en_US resource bundle as Application50:

Contributed from:
C:/JDeveloper/mywork/BaseApp/Model/deploy/BaseApp_Model_adflibBaseApp1.jar C:/JDeveloper/mywork/Application50/MobileClient/src/mobile C:/JDeveloper/mywork/adflibLocalization1.jar C:/JDeveloper/mywork/BaseApp/Model/myBaseApp.jar

Figure 8-30 Verifying the Origins of the Resource Bundles Using Tooltips

When you deploy the application, the resulting JAR includes the local language bundles. As shown in Figure 8-31 includes four different en_US resource bundles.

Figure 8-31 Local Resource Bundles Included in JAR