readme.txt

MIDP LOGGER used to log log Messags

MIDPLogger
----------
MIDPLogger is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.

MIDPLogger is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with MIDPLogger; if not, write to the Free Software
Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Author: [e-mail]
http://www.woolleynet.com
http://mobilelandscape.co.uk


About MIDPLogger
----------------
Developing J2ME/MIDP applications has its challenges. Not least amongst these challenges is the reliance of emulators for testing and the usual compliance issues that exist with the J2ME devices themselves. When developing a MIDP application using an emulator, a number of possibilities exist:

1. Your MIDlet works perfectly in the emulator....and works perfectly on a real device. Fantastic!
2. Your MIDlet doesn't work quite as expected in the emulator, but works perfectly on a real device. Not bad at all!
3. Your MIDlet works perfectly in the emulator....but doesn't work as expected on a real device. Bad. Very bad!
4. Your MIDlet doesn't work anywhere. Definitely not good!

MIDPLogger is really designed to help with scenario (3), although it may well be useful in (4) as well.

To help debug issues that exist when running a MIDlet on device, MIDPLogger provides an on-device log file, log writer and log viewer capability. By integrating the MIDPLogger class within your MIDLet, you can write debug/trace information to an on-device database (and also to the console if you like, for when you are running in your emulator). You can browse and otherwise manage the on-device log file using the MIDPLogViewer MIDlet, by adding it to your MIDlet suite.


Instructions for using MIDPLogger
---------------------------------

First, ensure the two source files MIDPLogger.java and MIDPLogViewer.java are included in your application's source
directory.

Then, there are two steps to consider:

1. Using MIDPLogger to write log file entries.

1.1 In a suitable place in your MIDlet, create an instance of MIDPLogger:

    public MIDPLogger log;
    ......
    // and then....
    try {
     log = new MIDPLogger(MIDPLogger.DEBUG,true,false);
    }
    catch (Exception e) { 
     System.out.println("Exception creating MIDPLogger");
     e.printStackTrace();
    }

    Note that the constructer arguments are as follows:

    public MIDPLogger(int this_log_level, 
                      boolean this_log_to_console,
                      boolean this_include_level_name) throws RecordStoreException

    Set this_log_level to any of: MIDPLogger.DEBUG, MIDPLogger.INFO, MIDPLogger.WARNING, MIDPLogger.ERROR, 
    MIDPLogger.EXPRESS or MIDPLogger.NONE. This controls the level of information written to the log file.
   
    Set this_log_to_console to true if you want log entries displayed to the console as well as written to
    the device log file.
   
    Set this_include_level_name to true if you want the level of log entry (DEBUG, INFO etc) included in the log entry.
   
1.2 Wherever you want a message written to the log or console, include an entry like the following:

    log.write("paint: About to copy image",MIDPLogger.DEBUG);
    
    Obviously you need a reference to your MIDPLogger object to be available in whatever class you are implementing
    the calls to the write method.
    

1.3 In your MIDlet's destroyApp method include a call to the MIDPLogger close method e.g.:

    log.close();
    
    
2. Using MIDPLogViewer to view and manage the on-device log file.

2.1 MIDPLogger includes a MIDLet called MIDPLogViewer. Add this MIDlet to your MIDlet suite by editing the JAD file in
    the normal way.
    
    
3. Build and Deploy

3.1 Build and deploy your MIDlet suite, including the MIDPLogger classes in the usual way. When testing on a real device,
    log entries will be written to a database on the devices as you test your MIDLet. Use the MIDPLogViewer MIDlet
    to browse the log file.