2 Setting Up the ADF Mobile Client Environment

2.2.1 What You Need to Get Started With the ADF Mobile Client Sample Application

Before you start working with the mobile client sample application (see Chapter 3, "Introduction to the ADF Mobile Client Sample Application"), ensure that you have the following components installed:

• Oracle JDeveloper (see Section 2.3, "Setting Up JDeveloper")

• Oracle JDeveloper extension for ADF Mobile client (see Section 2.3, "Setting Up JDeveloper")

• Oracle Database (Standard or Enterprise Edition) (see Section 2.4, "Setting Up Oracle Database")

• Oracle Database Lite (see Section 2.5, "Setting Up Oracle Database Lite")

• Fusion Order Demo Mobile Client application (see Section 2.9, "Setting Up the Fusion Order Demo Mobile Client Application")

• The sample application deployed to a smartphone, mobile device, or emulator (see Section 3.4, "Running the Fusion Order Demo Mobile Client Application")

In addition:

• If Windows Mobile is your target platform, the following is required:

  • Java Runtime Environment (JRE) in the form of Oracle Java Micro Edition Connected Device Configuration HotSpot Implementation (Oracle Java ME CDC HI)

  • Windows Mobile SDK.

    Note that this software is required if you are planning to use a Windows Mobile device emulator only.

  • Windows Mobile device or device emulator

  For more information, see Section 2.6, "Setting Up Development Tools for Windows Mobile Platform."

• If BlackBerry is your target platform, the following is required:

  • BlackBerry JDE

  • BlackBerry smartphone or simulator.

    Note that BlackBerry JDE download includes a number of smartphone simulators. You only need to install a separate, standalone simulator if the JDE does not include a simulator for your target device.

  • BlackBerry Desktop Software

  For more information, see Section 2.7, "Setting Up Development Tools for BlackBerry Platform."

2.2.2 What You Need to Create an ADF Mobile Client Application

Before you start creating a mobile client application (see Chapter 4, "Getting Started with ADF Mobile Client"), ensure that you have the following components installed:

• Oracle JDeveloper (see Section 2.3, "Setting Up JDeveloper")

• Oracle JDeveloper extension for ADF Mobile client (see Section 2.3, "Setting Up JDeveloper")

• Oracle Database (Standard or Enterprise Edition) (see Section 2.4, "Setting Up Oracle Database")

• Oracle Database Lite (see Section 2.5, "Setting Up Oracle Database Lite")

• An existing ADF application: because you are extending an application to a mobile device, you cannot begin application development by creating a standalone mobile client application. An ADF application must first exist and stand as the base (server) application for the mobile client. The view objects and entity objects used by the mobile client application are likewise based on the view objects and entity objects of the base application. For more information, see Section 4.5, "Extending the Base Application for the Mobile Client Application."

• Synchronization initiated using mSync (see Section 9.3, "Initiating Data Synchronization").

In addition:

• If Windows Mobile is your target platform, the following is required:

  • Java Runtime Environment (JRE) in the form of Oracle Java Micro Edition Connected Device Configuration HotSpot Implementation

  • Windows Mobile SDK

    Note that this software is required if you are planning to use a Windows Mobile device emulator only

  • Windows Mobile device or device emulator

  For more information, see Section 2.6, "Setting Up Development Tools for Windows Mobile Platform."

• If BlackBerry is your target platform, the following is required:

  • BlackBerry JDE

  • BlackBerry smartphone or simulator.

    Note that BlackBerry JDE download includes a number of smartphone simulators. You only need to install a separate, standalone simulator if the JDE does not include a simulator for your target device.

  • BlackBerry Desktop Software

    Note that this software is required if you are planning to use a BlackBerry smartphone only.

  For more information, see Section 2.7, "Setting Up Development Tools for BlackBerry Platform."

2.2.3 What You Need to Deploy an ADF Mobile Client Application to a Development Environment

Before you start deploying your mobile client application (see Chapter 4, "Getting Started with ADF Mobile Client"), ensure that you have the following components installed:

• All components listed in Section 2.2.2, "What You Need to Create an ADF Mobile Client Application"

• The mobile client application

• Various database connections and login credentials

• The server application's model project deployed as an ADF library. This library contains ADF Business Components from the base ADF application that you are extending to the mobile client application (see Section 4.3, "Deploying the Model Project of the Base Application as an ADF Library").

In addition, if you are deploying to Windows Mobile devices, install the following:

• Microsoft ActiveSync 4.5 or Microsoft Windows Mobile Device Center 6.1 or later: this component connects a mobile device or emulator to your computer and transfers your application to the device or emulator once it is running (see Section 2.6.3, "How to Connect the Mobile Device or Emulator").

• Microsoft Device Emulator 3.0: this component represents a program that can emulate Window Mobile devices (see Section 2.6.2, "How to Install and Set Up the Windows Mobile Emulator").

• One or more Microsoft emulator images that enable functionality of Microsoft Device Emulator (see Section 2.6.2, "How to Install and Set Up the Windows Mobile Emulator").

For more information, see Section 2.6, "Setting Up Development Tools for Windows Mobile Platform."

2.2.4 What You May Need to Know About Pre-Installed Components

There is a number of additional components that are part of the mobile client environment setup with the purpose of the application development and deployment. However, these components do not require explicit installation as they are installed by default during installation of other components. These pre-installed components include the following:

• SQLite database: this component comes with Oracle Database Lite and is preinstalled on BlackBerry smartphones. For Windows Mobile devices, the required files are installed as part of the synchronization and runtime installation. Moreover, the sample application includes an SQL script to automatically generate the database.

• SQLite Mobile Client installed on the mobile device or emulator (see Section 2.8, "Installing SQLite Mobile Sync Client on BlackBerry Smartphone or Simulator"): this component comes with Oracle Database Lite.

• BlackBerry Desktop Manager pack: this component is included in the BlackBerry Desktop Software installation (see Section 2.7.2, "How to Install BlackBerry Desktop Software").

• Microsoft Device Emulator Manager: this component is installed as part of Microsoft Device Emulator 3.0 package. The Device Emulator Manager simulates an ActiveSync connection. It connects the emulator for file synchronization using Microsoft ActiveSync (see Section 2.6.2, "How to Install and Set Up the Windows Mobile Emulator").

• Oracle Java Micro Edition Connected Device Configuration HotSpot Implementation: this component is included in the ADF Mobile client extension as the Windows Mobile JVM (see Section 2.6.5, "How to Install Java Runtime Environment on the Mobile Device or Emulator").

• Oracle Database Lite Mobile Server: this component is a part of Oracle Database Lite and enables data synchronization (see Section 2.5, "Setting Up Oracle Database Lite").

• BlackBerry Mobile Data Service Simulator (MDS simulator): this component installs with the BlackBerry JDE and represents the BlackBerry network access server (see Section 2.7.1.1, "What You May Need to Know About BlackBerry Mobile Data Service Simulator").

2.6.1 How to Set Up the Windows Mobile Device

ADF Mobile client supports the following Windows Mobile devices:

• Windows Mobile 6.0 Professional

• Windows Mobile 6.1 Professional

• Windows Mobile 6.5 Professional

To set up your mobile device, you simply have to connect it to the USB port of the computer running JDeveloper. At this point, either Microsoft ActiveSync or Microsoft Windows Mobile Device Center establishes a connection from the mobile device to your development computer (see Section 2.6.3, "How to Connect the Mobile Device or Emulator").

2.6.2 How to Install and Set Up the Windows Mobile Emulator

During development, you can use the mobile device emulator instead of an actual device (see Section 2.2, "Prerequisites for Developing ADF Mobile Client Applications") to test your application.

ADF Mobile client supports the following device emulators:

• Windows Mobile 6 Professional

• Windows Mobile 6.1 Professional

• Windows Mobile 6.5 Professional

Before you begin:

Download and install one of the following Windows Mobile SDK packages:

• Windows Mobile 6 Professional SDK from Microsoft download site at http://www.microsoft.com/downloads/en

• Windows Mobile 6.5 Developer Tool Kit from Microsoft download site at http://www.microsoft.com/downloads/en

To complete the set-up:

• Download and install Microsoft Device Emulator 3.0 from Microsoft download site at http://www.microsoft.com/downloads/en

  For information on how to use Microsoft Device Emulator, search http://msdn.microsoft.com site for "Step by Step: Using Microsoft Device Emulator In-Depth in Your Application Development Experience".

• Download one or more Microsoft emulator images that enable functionality of Microsoft Device Emulator 3.0:

  • For Windows Mobile 6: http://www.microsoft.com/downloads/en

  • For Windows Mobile 6.1: http://www.microsoft.com/downloads/en

  • For Windows Mobile 6.5: http://www.microsoft.com/downloads/en

Figure 2-3 shows a Windows Mobile device emulator.

Figure 2-3 Windows Mobile Device Emulator

After you install the Windows Mobile device emulator, you have to connect it to your computer (see Section 2.6.3, "How to Connect the Mobile Device or Emulator").

2.6.3 How to Connect the Mobile Device or Emulator

To connect your development computer to the mobile device or emulator and enable transfer of your mobile client application to the mobile device or emulator once it is running, you use one of the following utilities:

• Microsoft ActiveSync 4.5: This installation is required for Microsoft Windows XP and 2000 systems and is available from Microsoft download site (see also http://www.microsoft.com/windowsphone/en-ca/apps/65-downloads.aspx).

• Microsoft Windows Mobile Device Center 6.1 or later: This installation is required for Microsoft Windows Vista and 7 systems and is available from Microsoft download site (see also http://www.microsoft.com/downloads/en).

Once installed, this utility starts automatically when you plug in the mobile device or cradle the emulator.

To connect to the Windows Mobile device emulator using Microsoft ActiveSync:

1. From the Windows Start menu, select Program Files > Windows Mobile 6 SDK > Standalone Emulator Images, and then select an emulator.

2. From the Windows Start menu, choose Program Files > Windows Mobile 6 SDK > Tools > Device Emulator Manager.

3. From the Device Emulator Manager, click Refresh, and then select the preferred simulator, as Figure 2-4 shows.

   Figure 2-4 The Device Emulator Manager

   
   

4. Choose Actions, and then select Cradle from the context menu. ActiveSync will automatically appear upon successful connection.

   Note:

   If you are prompted by ActiveSync to establish a partnership, you can dismiss this dialog by clicking Cancel.

5. Ensure that Allow connections to one of the following and DMA are both selected, as Figure 2-5 shows, and then click OK.

   Figure 2-5 Setting the Connection in Microsoft ActiveSync

   
   

To connect to the Windows Mobile device emulator using Windows Mobile Device Center:

1. From the Windows Start menu, select Program Files > Windows Mobile Device Center to open the Windows Mobile Device Center dialog (see Figure 2-6).

   Figure 2-6 Windows Mobile Device Center

   
   

2. Select Mobile Device Settings, and then click Connection Settings (see Figure 2-7).

   Figure 2-7 Connections Settings Dialog

   
   

3. On the Connection Settings dialog, select Allow connections to one of the following, and then select DMA.

4. Click OK.

2.6.4 How to Install the Oracle Database Lite Client on the Mobile Device or Emulator

You must install the Oracle Database Lite client on the mobile device or emulator in order to synchronize data and access SQLite databases.

Before you begin:

Ensure that your computer and mobile device are connected (see Section 2.6.3, "How to Connect the Mobile Device or Emulator").

To install the Oracle Database Lite client:

1. In JDeveloper, from the main menu select Tools > Deploy ADF Mobile Client Runtime > to Windows Mobile device/emulator.

2. On the Deploy to Windows Mobile dialog that Figure 2-8 shows, select Data Sync > Deploy, and then click OK.

   Figure 2-8 Deploy to Windows Mobile Dialog

   
   

3. To complete the installation, follow the instructions that appear on the screen of your device or emulator.

2.6.5 How to Install Java Runtime Environment on the Mobile Device or Emulator

To run ADF Mobile client applications, you must have Oracle Java Micro Edition Connected Device Configuration HotSpot Implementation (Oracle Java ME CDC HI) installed on the mobile device or emulator.

Before you begin:

Ensure that your computer and mobile device or emulator are connected (see Section 2.6.3, "How to Connect the Mobile Device or Emulator").

To install JRE:

1. In JDeveloper, from the main menu select Tools > Deploy ADF Mobile Client Runtime > to Windows Mobile device/emulator.

2. On the Deploy to Windows Mobile dialog that Figure 2-8 shows, select Java Virtual Machine > Deploy, and then click OK.

3. To complete the installation, follow the instructions that appear on the screen of your device or emulator.

2.6.6 What You May Need to Know About Limitations of Windows Mobile Platform Usage

There is a number of limitations that are associated with the usage of Windows Mobile platform in the current release of ADF Mobile client:

• Windows Mobile Standard and Windows Mobile 7 (Windows Phone 7) device emulators are not supported.

• At any given time, only a single Windows Mobile device or emulator can be connected to your development computer. If ActiveSync or Microsoft Windows Mobile Device Center does not automatically initiate a connection to the device, you have to ensure no other device is attached and no emulator is running. You may also try selecting or deselecting the Enable advanced network functionality option on your device. This option is accessible through the Settings >USB to PC menu.

• The Window Mobile JVM does not function properly if installed to the device emulator's storage card. Instead, it must be installed to the internal main memory of the emulator.

2.7.1 How to Install BlackBerry JDE

BlackBerry JDE includes all of the Java libraries and development tools that you need to build applications for a BlackBerry smartphone.

ADF Mobile client provides support for BlackBerry JDE 5.0 and 6.0.

To install BlackBerry JDE:

Download BlackBerry JDE from http://na.blackberry.com/eng/developers/javaappdev/javadevenv.jsp

Figure 2-9 shows a BlackBerry smartphone simulator.

Figure 2-9 BlackBerry Smartphone Simulator Screen

2.7.2 How to Install BlackBerry Desktop Software

BlackBerry Desktop Software connects physical BlackBerry smartphones to your development computer and enables you to install applications to those smartphones.

To install BlackBerry Desktop Software:

1. Download BlackBerry Desktop Software from the download site.

2. Run the installer and follow its on-screen instructions.

2.7.3 How to Set Up a BlackBerry Smartphone

In your mobile client application development and deployment, you can use either the BlackBerry smartphone itself, or its simulator (see Section 2.7.4, "How to Set Up a BlackBerry Smartphone Simulator"). If you are planning to use the smartphone, you simply need to connect it to your computer in order to establish a link between the two devices.

2.7.4 How to Set Up a BlackBerry Smartphone Simulator

In your mobile client application development and deployment, you can use either the BlackBerry smartphone itself (see Section 2.7.3, "How to Set Up a BlackBerry Smartphone") or its simulator. Deploying to a simulator is usually much faster than deploying to a device, and it also means that you do not have to sign the application first.

If you are planning to use one of the smartphone simulators included with JDE, you do not need to download and install a separate smartphone simulator. In case JDE does not contain a simulator for your target BlackBerry smartphone and you need to download a standalone simulator, see the how-to section of the ADF Mobile page on Oracle Technology Network (OTN) at http://www.oracle.com/technetwork/developer-tools/adf/overview/adf-mobile-096323.html for instructions on installing these simulators.

To set up the BlackBerry smartphone simulator:

1. Start the BlackBerry Mobile Data Service (MDS) simulator by double-clicking the run.bat file, which is typically located in C:\Program Files\Research In Motion\BlackBerry JDE <version number>\MDS directory.

   Note:

   For information on how to configure MDS simulator to work behind a proxy, see Section 2.7.6, "How to Configure Proxy Settings."

2. Start the smartphone simulator.

   To activate the default simulator, double-click the defaultSimulator.bat file that is typically located in C:\Program Files\Research In Motion\BlackBerry JDE <version number>\simulator\ directory.

2.7.5 How to Configure JDeveloper for BlackBerry Development

After you install the following components, you have to configure JDeveloper to make use of them:

• BlackBerry JDE (see Section 2.7.1, "How to Install BlackBerry JDE")

• Optionally: standalone BlackBerry smartphone simulators, if the JDE does not contain a simulator for your target BlackBerry smartphone (see Section 2.7.4, "How to Set Up a BlackBerry Smartphone Simulator")

• Optionally: Oracle Database Lite 10g MDK, if your application requires data synchronization (see Section 2.5, "Setting Up Oracle Database Lite")

To configure JDeveloper for BlackBerry development:

1. In JDeveloper, select Tools > Preferences > ADF Mobile Client from the main menu.

2. Set the directory of the BlackBerry JDE. Because the default BlackBerry simulator installs with the JDE, the location of the BlackBerry simulator is populated automatically when you enter the location for the BlackBerry JDE.

3. If you use a simulator that is not part of BlackBerry JDE, then enter the location of this simulator.

4. Enter the root location of the MDK installation.

5. Click OK.

   Figure 2-10 shows the locations set for BlackBerry JDE, the included simulator, and Oracle Database Lite MDK installation directory.

Figure 2-10 Set BlackBerry JDE Location for Deployment

2.7.6 How to Configure Proxy Settings

You might need to configure network proxy settings by modifying the rimpublic.property file that is typically located in the C:\Program Files\Research In Motion\BlackBerry JDE <version number>\MDS\config directory. The configuration settings vary depending on the proxy server that is required to access the network, and may include any of the following:

[HTTP HANDLER]
application.handler.http.logging = true
application.handler.http.CookieSupport = true
application.handler.http.AuthenticationSupport = true
application.handler.http.AuthenticationTimeout = 3600000
application.handler.http.device.connection.timeout = 120000
application.handler.http.server.connection.timeout = 120000
application.handler.http.proxyEnabled = true
application.handler.http.proxyAutoConfig = true
application.handler.http.proxyAutoConfigURL=http://wpad.us.oracle.com/wpad.dat
application.handler.http.proxyAutoConfig.ScriptCacheTime=0

For more information on how to configure MDS simulator to work behind a proxy, see BlackBerry Developers Knowledge Base page at http://www.blackberry.com/knowledgecenterpublic

2.7.7 What You May Need to Know About BlackBerry File Browser System

The BlackBerry file browser may not display the true path to a file. For instance, /Media Card is displayed for /SDCard directory, and /Device Memory is displayed for /store directory. Therefore, when referencing paths on the BlackBerry file system, either in code or in configuration files (such as adf-config.xml and connections.xml), ensure that you use the actual directory names.

2.7.8 What You May Need to Know About Limitations of BlackBerry Platform Usage

Even though the mobile client supports both BlackBerry JDE 5.0 and 6.0, there is a number of issues that are associated with the usage of these environments:

• BlackBerry JDE 5.0: It is not possible to close a BlackBerry smartphone simulator from the UI on Microsoft Windows Vista or 7 systems. The only means available to terminate the simulator is to use the End Task utility of the Microsoft Windows Task Manager on the fledge.exe file to force stop the program. When this happens, the state of the simulator is not saved, resulting in the loss of information as the data is not saved on the simulator between the restarts. In addition, exceptions occur and the simulator is left in a faulty state.

• BlackBerry JDE 6.0: The standalone synchronization of data is not possible. To transfer data to the smartphone, you can only rely on the integrated synchronization that is invoked by the application when data is not found on the smartphone. For more information, see Chapter 9, "Synchronizing ADF Mobile Client Data and Transactions."

Table 2-1 summarizes compatibility of BlackBerry components and specific Microsoft Windows platforms.