10 Testing and Debugging ADF Mobile Client Applications

10.3.1 How to Configure a Window Mobile Device or Emulator for Debugging

Prior to debugging a mobile client application, you have to configure a mobile device or emulator by performing the following:

• Increasing the Internal Storage Capacity of the Device or Emulator

• Configuring the Device or Emulator for Network Access

10.3.2 How to Deploy the Application to the Window Mobile Device or Emulator for Debugging

To deploy the mobile client application to a Windows Mobile device or emulator for debugging, you start with establishing a connection between you development computer and the device or emulator. For more information, see Section 2.6.3, "How to Connect the Mobile Device or Emulator."

If, at any point, you find that you cannot ping the emulator from your development computer, perform the following steps:

• Start Device Emulator Manager. This functionality is typically accessible through the execution of the dvcemumanager.exe file located in the C:\Program Files\Microsoft Device Emulator\1.0 directory.

• Click Refresh, and then scroll through the list of emulators to find one with a green arrow icon beside it.

• Right-click this entry and select Uncradle.

To deploy and install your application to the device or emulator:

1. In JDeveloper, create a Windows Mobile deployment profile for your application:

   • In Application Navigator, right-click the application name, and then select Deploy > New Deployment Profile.

   • In the New Gallery dialog, select ADF Mobile Client for Windows Mobile to create your deployment profile.

   • Accept all the default settings of subsequent screens by clicking OK until you reach the ADF Mobile Client for Window Mobile Deployment Profile Properties screen and make a selection of Windows Mobile Options from the tree on the left.

   • On the ADF Mobile Client for Window Mobile Deployment Profile Properties > Windows Mobile Options screen that Figure 10-1 shows, select Generate Debug Launcher, and then click OK (see Section 10.3.3, "What Happens When You Choose to Generate the Debug Launcher").

     Figure 10-1 Generating Debug Launcher

     
     

   • Continue accepting the default settings on subsequent screens by clicking OK until the deployment profile is created.

2. In the Application Navigator, right-click the application name, and then select Deploy > <DEPLOYMENT PROFILE NAME>.

3. Click Finish to complete the deployment.

Upon successful deployment, you should see messages in the Deployment - log window in JDeveloper, similar to the following:

[10:50:12 AM] Window Mobile package successfully 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.  --- 

In addition, you should see a screen that Figure 10-2 shows appear on the device or emulator, prompting you to select installation to Storage Card or Device, and select Device.

Figure 10-2 Installing Application to a Device

10.3.3 What Happens When You Choose to Generate the Debug Launcher

When you select Generate Debug Launcher in the Windows Mobile Options page (see Figure 10-1, "Generating Debug Launcher"), the ADF Mobile client runtime generates an executable debug file and a corresponding options file in addition to the application launcher and options files described in Section 8.4.2.1, "Setting the JAR File Options." Like those files, the debug files are named for the application and are also included in the CAB file. These files are designated as follows: Debug_<Application Name>.exe and Debug_<Application Name>.options. If the end user clicks <Application Name>.exe, the application launches in regular mode. If the end user clicks Debug_<Application Name>.exe the application starts in debug mode.

The contents of the debug options file are identical to those of the regular options file, with the exception of additional command line option which is used to start an application in debug mode:

-Xdebug "-agentlib:jdwp=transport=dt_socket,server=y,address=4041"

10.3.4 How to Debug the Application on the Windows Mobile Platform

After configuring the mobile device or emulator for debugging, and then deploying your mobile client application, you can start the debugging as follows:

1. In JDeveloper, open the Project Properties by selecting Application > Project Properties from the main menu.

2. On the Project Properties dialog that Figure 10-3 shows, select Run/Debug/Profile

   Figure 10-3 Run Configurations Settings for Windows Mobile

   
   

3. Click Edit to open the Edit Run Configuration dialog and to start editing the default configuration.

   Note:

   If no configurations are listed under Run Configurations, add a new configuration by clicking New.

4. On the Edit Run Configuration dialog that Figure 10-4 shows, select Launch Settings from the tree control on the left, and then select Remote Debugging.

   Figure 10-4 Launch Settings Dialog

   
   

5. On the Edit Run Configuration dialog that Figure 10-5 shows, select Debugger > Remote from the tree on the left, and then enter the IP address of the device or emulator in the Host field.

   You can determine the IP address as follows:

   • On the device or emulator screen, click Start > Settings.

   • Select the Connections tab, and then Network Cards.

   • Select NE2000 Compatible Ethernet Driver to display the IP address.

6. Ping the device or emulator's IP address and ensure that the ping succeeds.

   Note:

   You might have to uncradle the device or emulator in order to ping it, and then recradle when deploying the application from JDeveloper.

7. On the Remote screen of the Edit Run Configuration dialog, enter the port number 4041 (see Figure 10-5), and then click OK.

   Figure 10-5 Remote Settings Dialog

   
   

8. Open your application's Deployment Profile Properties, select Windows Mobile Options, and then ensure that Generate Debug Launcher is selected (see Figure 10-1 and Section 10.3.3, "What Happens When You Choose to Generate the Debug Launcher").

   -Xdebug "-agentlib:jdwp=transport=dt_socket,server=y,address=4041"
   

9. With the debug settings configured, deploy your application to the mobile device or emulator (see Section 10.3.2, "How to Deploy the Application to the Window Mobile Device or Emulator for Debugging").

10. Using the File Explorer application on the device or emulator, navigate to the application folder, which is typically located in the \Program Files directory, and then launch your application by clicking on it. At this point, the application is waiting for a debugger to attach before it will start running.

11. Connect JDeveloper's debugger to the application by selecting the Debug configuration that you created earlier.

12. Start debugging by selecting the edited run configuration from the debug icon drop-down list in JDeveloper.

Upon completion of the preceding steps, you should be able to set breakpoints, suspend execution, and inspect variables, just as you can with an ADF Faces application.

10.3.5 How to Enable Error Logging on a Window Mobile Device or Emulator

You can enable logging of errors while running the mobile client application on a device or emulator as follows:

1. In JDeveloper, in your application project, create a directory called store in a location such as C:\JDeveloper\mywork\<application_name>

2. In the store directory, create another directory called logs in which the device or emulator will record error log information and share it with your computer.

   You enable sharing of the logs directory as follows:

   1. On the emulator, select File > Configure.

   2. In the Emulator Properties screen, edit the location of the Shared folder field to point to the location on your computer: C:\JDeveloper\mywork\<application_name>\store

   3. Click OK.

You have enabled logging when you run the application.

Note that the log file is recreated each time you run the application.

10.4.1 How to Configure a BlackBerry Smartphone Simulator for Debugging

Since debugging of Java applications on BlackBerry platform occurs over the standard Java Debug Wire Protocol (JDWP) using TCP sockets as the transport mechanism, both the simulator and the development computer must have network access and be visible to one another on the network.

Prior to debugging a mobile client application, you have to configure the smartphone simulator as follows:

1. In the <BLACKBERRY JDE PATH>\bin directory, double-click the JDWP.bat file to start the BlackBerry Remote Debug Server.

   Note:

   JDWP is used for establishing a connection between JDeveloper and the simulator.

2. In the BlackBerry Remote Debug Server dialog, in the Communications tab (see Figure 10-6), make note of the JDWP port number. By default, this value is 8000, but you can change it if necessary.

   Figure 10-6 BlackBerry Remote Debug Server

   
   

3. In the Simulator tab, ensure that Launch simulator when debugger connects is selected.

   Note:

   If you prefer to start the simulator manually, do not select this option, but instead on the Communications tab select Attach to > Running simulator. In this case, you have to ensure that a simulator instance has been started prior to attempting a connection.

10.4.2 How to Deploy the Application to the BlackBerry Simulator for Debugging

To deploy the mobile client application to a BlackBerry simulator for debugging, you start with establishing a connection between you development computer and the simulator. For more information, see Section 10.4.1, "How to Configure a BlackBerry Smartphone Simulator for Debugging."

To deploy and install your application to the simulator:

1. In JDeveloper, create a BlackBerry deployment profile for your application:

   • In the Application Navigator, right-click the application name, and then select Deploy > New Deployment Profile.

   • In the New Gallery dialog, select ADF Mobile Client for BlackBerry to create your deployment profile, and then accept all the default settings of subsequent screens by clicking OK until the deployment profile is created.

2. In the Application Navigator, right-click the application name, and then select Deploy > <DEPLOYMENT PROFILE NAME>.

3. Select the Deploy Application to Simulator deployment action.

4. Click Finish to complete the deployment.

Upon successful deployment, you should see messages in the Deployment-Log window in JDeveloper, similar to the following:

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

If you want to hit breakpoints defined in any classes in your application, you can instruct JDeveloper to deploy the application's .debug file(s) to the simulator. To do so, select Deploy debug files with the application in the BlackBerry Options page of the ADF Mobile Client for BlackBerry Deployment Profile Properties dialog that shows. For more information, see Section 8.4.1.2, "Setting the BlackBerry Digital Signature Tool Options."

Figure 10-7 Deploying Debug Files With Application

10.4.3 How to Debug the Application on BlackBerry Platform

After configuring the smartphone simulator for debugging, and then deploying your mobile client application, you can start debugging as follows:

1. In JDeveloper, open the Project Properties by selecting Application > Project Properties from the main menu.

2. On the Project Properties dialog that Figure 10-8 shows, select Run/Debug/Profile

   Figure 10-8 Run Configurations Settings for BlackBerry

   
   

3. Click Edit to open the Edit Run Configuration dialog and to start editing the default configuration.

   Note:

   If no configurations are listed under Run Configurations, add a new configuration by clicking New.

4. On the Edit Run Configuration dialog that Figure 10-9 shows, select Launch Settings from the tree control on the left, and then select Remote Debugging.

   Figure 10-9 Launch Settings Dialog

   
   

5. On the Edit Run Configuration dialog that Figure 10-8 shows, select Debugger > Remote from the tree on the left, and in the Host field enter the IP address of the computer on which the simulator is running, or 127.0.0.1

   Specify the same port as you provided in the Communications tab of the BlackBerry Remote Debug Server dialog (see Figure 10-6), which is 8000 by default.

   In addition, increase the time-out to 30000.

6. On the Remote screen of the Edit Run Configuration dialog, enter the same port as you provided in the Communications tab of the BlackBerry Remote Debug Server dialog (see Figure 10-10).

   In addition, increase the time-out to 30000, and then click OK.

   Figure 10-10 Remote Settings Dialog

   
   

7. In your application, set breakpoints as needed.

8. Select the edited run configuration from the debug icon drop-down list in JDeveloper.

9. Start debugging by running your application in the simulator.

At this point, you should be able to suspend execution and inspect variables, just as you can with an ADF Faces application.

10.4.4 What You May Need to Know About Modifying the Deployment and Run Configurations

At certain times, you may find it necessary to modify the deployment and run configurations of your mobile client application.

You might need to modify your run configuration to debug a mobile device or its emulator, or a smartphone or its simulator that is not connected to the default location or port.

For information on how to modify the run configuration, see the following:

• Figure 10-7, "How to Debug the Application on BlackBerry Platform"

• Figure 10-8, "Run Configurations Settings for BlackBerry"

You might need to modify your deployment options for some of the following reasons:

• To deploy the client application to a non-default location on the device.

• To configure the client to access custom code or libraries on the device.

You can change deployment options from the deployment profile as follows:

1. Open the Application Properties dialog and select Deployment from the tree on the left.

2. On the Deployment panel (see Figure 10-11), select the deployment profile that you want modify from the Deployment Profiles list, and then click Edit to open the Deployment Profile Properties dialog.

   Figure 10-11 Modifying Deployment Options

   
   

3. On the Deployment Profile Properties dialog, perform the required modifications, and then click OK.

10.4.5 How to Enable Error Logging on a BlackBerry Simulator

You can enable logging of errors while running the mobile client application on the BlackBerry smartphone simulator as follows:

1. In JDeveloper, in your application project, create a directory (called mystore, for example) in a location such as C:\JDeveloper\mywork\<application_name>.

2. In the mystore directory, create another directory called logs in which the device or emulator will record error log information and share it with your computer.

   You enable sharing of the logs directory as follows:

   1. On the simulator, select Simulate > Change SD Card.

   2. In the SD Card screen, click Add Directory, and then select the location of the logs directory.

   3. Click OK.

Upon completion of the preceding procedure, when you run the application, the logging will be enabled. Note that the log file is recreated each time you run the application.

10.6.1 How to Use the ADF Mobile Client Logging Facility

ADF Mobile client makes extensive use of log messages throughout an application's execution for informational and diagnostic purposes. These messages can be selectively enabled or disabled by different priority levels across the framework or for specific areas of functionality within the framework for both performance and easier processing of log output.

You can add log messages to your own code, using logging channels and logging output mechanisms defined within ADF Mobile client, or creating your own.

The ADF Mobile client logging facility is a lightweight adaptation of the Java platform's core logging facility implemented in the java.util.logging package.

The following are the key elements used in ADF Mobile client logging:

• Logger: A configurable logical channel with which different groups of log messages are associated. Loggers are named and organized hierarchically, where sub-loggers can inherit or override settings of their parent loggers. A logger directs messages to one or more associated handlers, which control how the messages are output.

  All ADF Mobile client framework classes log their messages through the following named loggers according to their various functional areas within the framework:

  Note:

  You can configure these loggers declaratively through the ADF Mobile client settings facility as well as add your own.

  • adfnmc.util: Logs messages from low-level Utility classes.

  • adfnmc.model: Logs messages associated with the ADF Mobile client Model layer.

  • adfnmc.bindings: Logs messages associated with the ADF Mobile client data-binding layer.

  • adfnmc.ui: Logs messages associated with the ADF Mobile client UI layer.

  • adfnmc.test: A channel that can be used for test messages and test output.

  • adfnmc.profiling: Logs messages used for outputting performance metrics.

  • adfnmc: The parent logger for all ADF Mobile client loggers.

• Handler: A configurable object responsible for exporting messages to various destinations including memory, output streams, consoles, files, and sockets. The subclass of the handler determines the destination type that it supports.

  ADF Mobile client includes the following Handler types:

  • oracle.adfnmc.java.util.logging.FileHandler: Writes messages to a file.

  • oracle.adfnmc.java.util.logging.ConsoleHandler: Writes messages to the standard output stream.

  • oracle.adfnmc.java.util.logging.StreamHandler: Writes messages to an OutputStream.

  • oracle.adfnmc.java.util.logging.DevNullHandler: Messages sent to this handler are not exported.

• Level: Loggers and handlers can be configured with priority levels to show or suppress messages. All messages are assigned a priority level when they are logged. If the level for a given message is lower than the level assigned to the logger or handler the message is sent to, it will be suppressed.

  The levels in descending order, along with their uses in the different areas of the Mobile client framework are:

  • SEVERE (highest value): Logs errors.

  • WARNING: Logs warnings; provides information that may indicate a problem in the framework or the application.

  • INFO: Logs user actions in the UI area; logs PageDef loads in the bindings area; logs view objects' read and writes, as well as EA/VL movements in the Model area; helps in resolving of objects at load time, as well as checkpoints.

  • CONFIG: This level is not supported by ADF Mobile client.

  • FINE: Logs EL evaluations in the binding area. Used for loading and parsing, sets and gets.

  Child loggers can override the level threshold for their messages to a higher or lower level than that of their parent loggers. Note, however, that the highest level threshold in a logger-handler chain will be applied. For example, if a logger is configured with a level of INFO and has two handlers, configured with levels of SEVERE and FINE, respectively, only SEVERE messages will be output from the first handler, while SEVERE, WARNING, and INFO messages will be output from the second handler. Neither will output FINE messages.

• Formatter: Handlers can be configured with different formatting options to apply to messages.

  ADF Mobile client includes the following Formatter types:

  • oracle.adfnmc.java.util.logging.SimpleFormatter: Writes brief "human-readable" summaries of log message records.

  • oracle.adfnmc.java.util.logging.NmcPatternFormatter: Writes messages modified according to a supplied format string. Note that this formatter does not fully parse format strings. See Table 10-3 for the fixed formats that are supported.

    Table 10-3 Formats Supported by NmcPatternFormatter

    Pattern String	Message Format
    "[%p - %c - %C{1} - %M] %m%n"	"[messageLevel - LoggerName - sourceClassname - sourceMethodName] message"
    "[%p - %c - %C{1} - %M - %d{ABSOLUTE}] %m%n"	"[messageLevel - LoggerName - sourceClassname - sourceMethodName - timeStamp] message"
    "[%c] %m%n"	"[LoggerName] message"

    
    

<amc:setting
     name="declare-logger-<loggerIdentifier>"
     value="<loggerName>"/>

<amc:setting name="<loggerIdentifier>-level"
             value="<level>"/>

<amc:setting name="<loggerIdentifier>-handlers"
             value="<handlerIdentifiers>"/>

<amc:setting
     name="<loggerIdentifier>-useParentHandlers"
     value="<true or false>"/>

<amc:setting
     name="declare-handler-<handlerIdentifier>"
     value="<handlerClass>"/>

<amc:setting name="<handlerIdentifier>-level"
             value="<level>"/>

<amc:setting name="<handlerIdentifier>-formatter"
             value="<formatterClass>"/>

<amc:setting
     name="<handlerIdentifier>-formatterPattern"
     value="<patternString>"/>

<amc:setting name="<handlerIdentifier>-pattern"
             value="<path to log file>"/>

For more information, see Oracle Fusion Middleware Java API Reference for Oracle ADF Mobile Client.

10.6.2 How to Configure Logging Using the Settings Facility

Most elements in the ADF Mobile client logging facility can be configured declaratively through the ADF Mobile client settings facility. See Table 10-1, "ADF Mobile Client Framework Settings" for a complete list of the settings and their descriptions.

Consider the following examples:

• To change the root ADF Mobile client framework logger level to FINE:

  <amc:setting name="declare-logger-adfnmc" value="adfnmc"/>
  <amc:setting name="adfnmc-level" value="FINE"/>
  

• To change the Model layer logger level to WARNING:

  <amc:setting name="declare-logger-adfnmc-model" value="adfnmc.model"/>
  <amc:setting name="adfnmc-model-level" value="WARNING"/>
  

• To specify a FileHandler and set its level and file path (per platform):

  <amc:setting name="declare-handler-FILE1"
               value="oracle.adfnmc.java.util.logging.FileHandler"/>
  <amc:setting name="FILE1-level" value="FINEST"/>
  <amc:setting name="FILE1-pattern" platform="wm"
               value="\Storage Card\Logs\logfile.txt"/>
  <amc:setting name="FILE1-pattern" platform="bb"
               value="/SDCard/Logs/logfile.txt"/>
  

• To associate a handler with a logger:

  <amc:setting name="adfnmc-handlers" value="FILE1"/>
  
  <!-- use a space delimiter to specify multiple handlers -->
  <amc:setting name="adfnmc-handlers" value="FILE1 FILE2"/>
  

10.6.3 How to Enable Logging in Java Code

ADF Mobile client includes a utility class, oracle.adfnmc.java.util.logging.Trace, which wraps most of the details that you might need to use the logging facility.

For example, the following code logs an informational message:

Trace.log(Trace.TEST_LOGNAME, Level.INFO,  
          this.getClass(),"someMethod", "my message");

The message can also be formatted with parameters, as in the following example:

Trace.log(Trace.TEST_LOGNAME, Level.INFO, this.getClass(),
          "someMethod", "my message with param: {0} and another param:
          {1}", new Object[] {param0, param1});

In the preceding methods, the first parameter is the name of the logger through which to send the message, and the second parameter is the level to apply to the message.

For more information, see Oracle Fusion Middleware Java API Reference for Oracle ADF Mobile Client.