Debugging BlackBerry Applications: A Simple Debug Console Class

Debug.java

/**

Debugging a BlackBerry application can be done on a simulator, 
when the bug permits that sort of thing, or on the device itself. 
If you’re in a situation where you must debug your code while it 
runs on a real device, your can sometimes take advantage of the 
tethering debugger provided by the JDE; connecting the device to 
the PC via a USB cable, and then hoping everything is stable 
enough for you to catch a breakpoint and find your bug.

This is all fine and good, but there are times when you 
find yourself in a situation where neither of these 
techniques gives good results.

At Antair, during development of our BlackBerry applications, 
we often include a debug console in the dev builds of our apps.

With the debug console, all debug output hits the output 
screen when the dev build is running in the simulator, 
and when the dev build runs on a physical test device, 
the debug output is automatically persisted and is 
available to view on a dedicated screen that can be 
pulled up via a menu option or button.

The code below is a stripped-down version of the 
debug console we use at our company.

Using the console is easy. Include the code in your 
project, fill out the PERSISTENCE_GUID for your application, 
set the TAGID string to identify your application name in the 
debug logs, and when you want to output a debug statement, 
simply call Debug.print(“Something happened here…“);

Each line of the debug output, both in the output window when 
running in a simulator, and in the debug console screen when 
viewed on a device, will contain your debug message, the 
thread number on which the call was made (useful for thread/ui debugging), 
and the date/time of the log statement, with a millisecond 
timestamp for performance profiling.

To view the debug console on a real device, simple put in a 
call to pushScreen(new AntairLogScreen()). The screen has a 
built-in menu item to clear the persisted log messages, and 
will dismiss itself like a regular application screen.

If you’re running the RIM compiler preprocessor to switch 
between development, QA, and production builds, you can 
simply put in a call to set Debug.ENABLED = false for 
everything but the development builds, and the debug console 
will be there when you need to debug and go away quietly 
when you don’t need it.

- Andrey Butov ( andreybutov.com )

**/

// -----------------------------------------------------------------------------
//
// Antair Debug Log (for the BlackBerry API)
// Copyright (c) 2005 - 2010, Antair Corporation. All Rights Reserved.
// http://www.antair.com
//
// BlackBerry is a registered trademark of Research in Motion.
//
// -----------------------------------------------------------------------------
 
package com.antair.examples.debug;
 
import net.rim.device.api.i18n.SimpleDateFormat;
import java.util.Date;
import net.rim.device.api.collection.util.BigVector;
import net.rim.device.api.system.PersistentObject;
import net.rim.device.api.system.PersistentStore;
import net.rim.device.api.ui.MenuItem;
import net.rim.device.api.ui.component.Menu;
import net.rim.device.api.ui.component.RichTextField;
import net.rim.device.api.ui.container.MainScreen;
import net.rim.device.api.util.Persistable;
 
final class Debug implements Persistable
{
    final static boolean ENABLED = true;
    final static String TAGID = "MY_PROJECT";
    final static long PERSISTENCE_GUID = /* YOUR OWN PERSISTENCE GUID */;
 
    private BigVector _messages = new BigVector();
 
    static String print(String str)
    {
        if ( Debug.ENABLED )
        {
            StringBuffer sb = new StringBuffer();
            sb.append(TAGID);
        	sb.append("\n");
            sb.append(Thread.currentThread().toString());
        	sb.append("\n");
            sb.append(new SimpleDateFormat("MM/dd/yy HH:mm:ss:SSS").format(new Date()));
        	sb.append("\n");
            sb.append(str); sb.append("\n");
            str = sb.toString();
 
            System.out.println(str);
            System.out.flush();
 
            Debug d = load();
            d._messages.addElement(str);
            save(d);
        }
 
        return str;
    }
 
    static BigVector getPersistedMessages()
    {
        return load()._messages;
    }
 
    static void clearPersistedMessages()
    {
        save(new Debug());
    }
 
    private static Debug load()
    {
        Debug d = null;
 
        try
        {
            PersistentObject po = PersistentStore.getPersistentObject(Debug.PERSISTENCE_GUID);
 
            synchronized(po)
            {
                Object obj = po.getContents();
                d = (obj == null) ? new Debug() : (Debug)obj;
            }
        }
 
        catch ( Exception e )
        {
            d = new Debug();
        }
 
        return d;
    }
 
    private static void save(Debug d)
    {
        try
        {
            PersistentObject po = PersistentStore.getPersistentObject(Debug.PERSISTENCE_GUID);
 
            synchronized(po)
            {
                po.setContents(d);
                po.commit();
            }
        }
        catch ( Exception e )
        {
        }
    }
}
 
final class ClearAntairLogScreenMenuItem extends MenuItem
{
    ClearAntairLogScreenMenuItem(int position)
    {
        super("Clear Log", position, 0);
    }
 
    public void run()
    {
        Debug.clearPersistedMessages();
    }
}
 
final class AntairLogScreen extends MainScreen
{
    AntairLogScreen()
    {
        super(MainScreen.DEFAULT_CLOSE|MainScreen.DEFAULT_MENU);
 
        StringBuffer text = new StringBuffer();
 
        BigVector logItems = Debug.getPersistedMessages();
 
        for ( int i = 0 ; i < logItems.size() ; ++i )
        {
            text.append((String)logItems.elementAt(i) + "\n");
        }
 
        add(new RichTextField(text.toString()));
    }
 
    protected void makeMenu ( Menu menu, int instance )
    {
        menu.add(new ClearAntairLogScreenMenuItem(100000));
    }
}