PlaceLab Phone Utilities HOWTO

Table of Contents

1. Introduction
2. Using Event Logger
3. Viewing Events
4. Storage Data

Introduction

Developing for the J2ME phone platform presents many difficulties, especially when using functionality that can only be tested on the actual device. Since not all device functionality is implemented in an emulator, when prototyping software on the device, crucial debugging functionality such as print lines or stack traces are lost. Place Lab is packaged with an Utilities application that assist developers in debugging J2ME applications for the Series 60 phone platform.

There are two utilities bundled together. The first is an Event Logger that displays events a program has explicitly asked it to log. The second is a storage utility for handling Place Lab preferences.

Using the Event Logger

The following piece of code demonstrates how to use the Event Logger. In this example, we are trying to make a localhost connection to gain access to GSM information. If the attempt is unsuccessful an IOException will be thrown. If this piece of code were running in the emulator, the line ioe.printStackTrace() would print the stack trace to standard error. However, if this piece of code were to run on the actual device, an error that occurs would be transparent, making it difficult to debug.

  try {
    //native server runs on port 4040
    sc = (SocketConnection) Connector.open("socket://127.0.0.1:4040");
    ...    
  } catch (IOException ioe) {
    EventLogger.logError("Cannot open stream to native GSM spotter");
    ioe.printStackTrace();
  }

A static call is made to the EventLogger passing in the Exception as an argument. The EventLogger will log the class name of the exception, and also the message that give by the call ioe.getMessage().

The Event Logger can also log String messages for debugging such as the following:

  if(map.isEmpty()) {
    EventLogger.logError("ERROR: map is empty");
  } else {
    ...
  }

The Event Logger is flexible enough to allow you to define your own types. The method call EventLogger.add(int,String) takes an eventType as the first argument, and the message to log as the second argument. This can be helpful if you do not want to log all messages as errors.

Viewing Events

The Place Lab Utilities MIDlet is the entry points for viewing events logged by the EventLogger. Since the EventLogger uses the RMS as persistent storage, creating the record store object to be publicly accessible, all events written to the logger are accessible from the Place Lab Utilities MIDlet.

The screenshot above (Introduction) shows the main screen to Place Lab Utilities. Select Event Log Utilities. On the next screen select Show Event Log. This will list the events 5 at a time on the screen. To browse through all the events, there is an option on from the left soft key menu for Next 5, which will list the next 5 events on the screen.

Viewing a large set of events on the phone can be time consuming and difficult considering the screen size constraints. There is an option to upload the event logs to a Place Lab server, via Bluetooth. This will allow you to view the events in a text file on your PC. The upload process is exactly the same as other Bluetooth transfers, and is documented in the Bluetooth Transfer HOWTO.

Storage Data

The Storage utility provides a persistent space for developers to set preferences. For instance, a section of code that should only run in the emulator could check the Storage to see if the value for the emulator preference is true or false.

The Storage class has two methods of interest:

  Storage.add(String type, String key, String value)
  Storage.get(String type, String key)