LogFile Guide

Sergio Morozov

Contents

1. Overview
2. Description
3. Usage
4. Configuration
   1. Declarative Configuration
   2. Programmatical Configuration

Overview

Description

LogFile is a LogListener implementation. It is intended to collect logging information in the destination file. It resembles very much corresponding class in log4J framework. LogFile can be used only on devices or emulators that support FileConnection API.

LogFile creates the text file encoded using specified encoding (UTF-8 by default). All logging events are converted to strings and then written to the given file (separated by new-line character ('\n')). If prefix and/or suffix configuration properties are specified (they are null by default), each logging line starts with prefix and/or finishes with suffix. If header property is specified (it is null by default), it is written at the beginning of the file, if it is created by LogFile. There is also the footer property, that specifies the line to be written at the end of the destination file.

Destination file is specified via it's fully qualified path-name, that includes starting slash (/) and root's name. In other words, it is a file url without protocol and host specifiers (i.e. file://). For example file identified by url file:///SDCard/logs/myapp/log.txt can be specified by path-name /SDCard/logs/myapp/log.txt.

As J2ME architecture doesn't define finalize() method in class Object, LogFile class defines close() method intended to explicitly close connection and streams. This method actually writes footer line (if there is some) and then closes connection (and all streams, of course). This method is intended to be called at the end of the application's run (e.g. from MIDlet.destroyApp(boolean unconditional) method). Users need to do this only, if they are interesting in footer line to be written at the end of the destination file, because destination file is flushed after every logging line.

LogFile can be configured declaratively from initialization file (recommended) and/or programmatically by invoking setter methods. All configuration properties have meaningful default values and don't require configuration.

Usage

Usage of LogFile is very simple. It should be instantiated and configured declaratively or programmatically. See Configuration chapter for details.

There is one exception. If users are interesting in footer line to be written at the end of the destination file, method close() should be called at the end of the application's run (e.g. from MIDlet.destroyApp(boolean unconditional) method). Besides it is recommended, users don't need to do this in other cases, because destination file is flushed after every logging line.

Configuration

1. Declarative Configuration
2. Programmatical Configuration

LogFile can be configured programmatically by invoking respective setter methods and/or declaratively from configuration file. Configuration from initialization file takes place at Logger class loading time, and programmatical configuration, of course, overrides declarative.

LogFile is preconfigured. All configuration properties have meaningful default values. It is possible to set location and character encoding of the destination file, whether existent file should be rewritten on open or not and properties, that define the format of the destination file (i.e. header, footer, prefix and suffix). If location of destination file is unspecified, it is set to the "momelog.log" file in first root returned from FileSystemRegistry.listRoots() method and respective warning message indicating this file path is printed to the standard error output.

Declarative Configuration

LogFile can be configured declaratively from initialization file. All configuration properties names are in lower-case. If some property is specified more than one time, the last occurrence prevails.

For example: following configuration file snippet configures LogFile to append all logging to the existent file "/root2/logs/my-app.log" using UTF-16 encoding, sets header and footer to ' *** Logging from MyApp *** ', prefix to '[' and suffix to ']'.

  #setting LogListener
  listener = momelog.listener.LogFile

  #setting log file.
  listener.outfile = /root2/logs/my-app.log

  #don't rewrite
  listener.append = true

  #encoding setting.
  listener.encoding = UTF-16

  #header setting. spaces are significant.
  listener.header =   ***  Logging from MyApp   ***
  #footer setting. spaces are significant.
  listener.footer =   ***  Logging from MyApp   ***
  #prefix setting. spaces are significant.
  listener.prefix =[
  #suffix setting. spaces are significant.
  listener.suffix =]

Programmatical Configuration

LogFile can be configured programmatically by using setter methods.

LogFile contains configuration property outfile that specifies destination file, where all logging information should be written. It can be set by using setOutfile(String outfile) method. After this method returns, connection to the previously opened destination file (if there was some) is closed and new logging information will be written to the specified file. File can be designated by it's fully qualified path-name, that includes starting slash (/) and root's name. In other words, it is a file's url without protocol and host specifiers (i.e. file://). For example file identified by url file:///SDCard/logs/myapp/log.txt can be specified by path-name /SDCard/logs/myapp/log.txt. This method can be called at any time. Of course, it is recommended to invoke this method at the start of the application's run (e.g. from MIDlet.startApp()). The default value is set to the "momelog.log" file in first root returned from FileSystemRegistry.listRoots() method.

The character encoding of the destination file can be set by invoking setEncoding(String encoding) method. The default encoding is UTF-8. The character encoding to take effect should be specified before the destination file is open.

LogFile can be configured to write some header line at the beginning of the file and some footer - at the end. Header and/or footer lines can be defined by respective header and footer configuration properties. These properties can be set by using setHeader(String encoding) and setFooter(String encoding) respective setter methods. These methods can be called at any time. Of course, it has sense to call setHeader(String encoding) method only before the destination file is open. It is recommended to invoke the above methods at the start of the application's run (e.g. from MIDlet.startApp()).

Each logging line can start and/or finish with specified by the user strings. prefix property defines string to be putted at the start of each logging line and suffix - at the end. These properties can be set by using setPrefix(String encoding) and setSuffix(String encoding) respective setter methods. These methods can be called at any time. Of course, it is recommended to invoke them at the start of the application's run (e.g. from MIDlet.startApp()).

For example in MIDlet SomeMIDlet.

    // In a case MoMELog is configured declaratively to use LogFile
    // private LogFile logFile = (LogFile) Logger.getLogListener());

    // LogFile instance initialized with destination file of /CDCard/logs/someapp/log.txt
    private LogFile logFile = new LogFile( "/CDCard/logs/someapp/log.txt");

    ...

    protected void startApp()
    {
      if( !started)
      {
        // encoding setting
        logFile.setEncoding("UTF-16");

        // append property setting
        logFile.setAppend( true);

        // setting header and footer to '   *** Logging of SomeApp ***   '
        logFile.setHeader("   *** Logging of SomeApp ***   ");
        logFile.setFooter("   *** Logging of SomeApp ***   ");

        // setting prefix and suffix
        logFile.setPrefix("[");
        logFile.setSuffix("]");

        // If MoMELog is configured declaratively to use LogFile
        // setting location of destination file.
        // logFile.setOutfile( "/CDCard/logs/someapp/log.txt");

        // if MoMELog is configured declaratively to use LogFile, it is redundant
        Logger.setLogListener( logFile);

        ...

        started = true;
      }

      ...

    }

    ...

    protected void destroyApp( boolean unconditional)
    {

      ...

      //logFile closing
      logFile.close();

      ...
    }

    ...

}

Sergio Morozov. 2007