PART - Pervasive Applications RunTime


Logging

PART provides support for creating event logs, which can for instance be saved on files or in a database. The logging service is implemented via log managers, where each manager can use a different log format, way of storing the log (e.g., file or database), which type of events are logged and so on.

All log managers will implement a common API, defined by the IpLogManager interface:

public interface IpLogManager {

    /**
     * Write a message to the log. The message that ends up on
     * the log will have the following form:
     * <p>
     * <code>TT:MM:SS - message</code>
     *
     * @param message The message to write to the log
     *
     * @exception IOException If an IO exception occurs while
     * writing the message
     */
    public void log(String message)
        throws IOException;
}

The interface defines only one method, log, which takes a string message to add to the log. Specific log manager classes that implements this interface can of course add additional methods.

The PART 1.2 release comes with two different log managers classes, the file log manager and the Lat log manager, described in the following sections.

The File log manager

The file log manager logs messages to ordinary file system files. The manager is represented by the class IpFileLogManager. Apart from many other PART classes, the IpFileLogManager class is supposed to be instantiated explicitly by the application code. In fact, it's not unusual to create several instances of this class, since each instance will log messages to a specific file, and sometimes it's desirable to have more than one log file.

When creating an IpFileLogManager instance, the programmer must supply a number of parameters:
  • the name of the directory where log files are to be created
  • the name of the log file
  • the maximum size of each log file (in bytes)
  • the maximum number of log files to be used (explained below)
  • a name which will be written in the log file header (used to identify the application that created the log file).
For instance:

// Create log files name 'partlog' in the current directory (.),
// the maximum size of the log files are 300KB, and we use a maximum
// of 3 files
mgr = new IpFileLogManager(".", "partlog", 300000, 3, "myApplication");

The file log manager uses a file rotation schema to handle the case when the size of the current log file exceeds the maximum size (as given by the constructor parameter). If the size of the current file exceeds the size limit, the manager will allocate a new file and continue to write messages to this file instead. The maximum log file count parameter above determines how many files the manager is allowed to use when rotating. If this limit is exceeded, the oldest log file is deleted when a new file is allocated.

The naming of the log files will be NAME, NAME.1, NAME.2, …, where NAME is the name specified with the constructor's file name parameter. Messages will always be written to the file called NAME. If this file is full, a rotation will occurs, causing NAME to be renamed NAME.1, old NAME.1 will be renamed NAME.2, etc, and a new file called NAME will be created where the message will written.

For example, assume that the log file name given to the constructor is 'partlog', and that the file size limit is 300KB, and the maximum number of log file is 3. As the application generates log messages, the following events will occur at various points in time (T1 < T2 < T3 …):
  1. T1 - The first log message is generated, the manager creates the file 'partlog' and writes the log message to this file. At this stage there is only one log file, 'partlog'.
  2. T2 -> T3 - The application continues to generate log messages, which are written to 'partlog'.
  3. T4 - The application generates a new log message and the manager discovers that 'partlog' is "full", i.e., its size if close to the limit of 300KB. The manager then renames 'partlog' to 'partlog.1' and creates a new file called 'partlog' on which it writes the new log message. There are now 2 log files, 'partlog' and 'partlog.1'.
  4. T5 -> T6 - The application continues to generate log messages
  5. T7 - The application generates a new log message and the manager discovers once again that 'partlog' is "full". The manager then renames 'partlog.1' to 'partlog.2' and 'partlog' to 'partlog.1 and creates a new file called 'partlog' on which it writes the new log message. There are now 3 log files, 'partlog', 'partlog.1' and 'partlog.2'.
  6. T8 -> T9 - The application continues to generate log messages
  7. T10 - The application generates a new log message and the manager discovers yet again that 'partlog' is "full". Since the maximum number of log files, 3, has been reached, the oldest log file, 'partlog.2' is first deleted. The manager then renames 'partlog.1' to 'partlog.2' and 'partlog' to 'partlog.1 and creates a new file called 'partlog' on which it writes the new log message. There are now 3 log files

Step 7 is then repeated each time the manager discovers that the current log file is full.

The file log manager is available on J2SE, J2ME, TINI and SNAP platforms. However, the J2ME version requires that the phone supports JSR75 (file system access) in order to use logging. For practical reasons, using file logging on mobile phones also requires the midlet to be signed, since otherwise the phone will ask the user to accept each file write operation. By signing the midlet it's possible to set its permission so that file IO is always allowed, thus removing the need to query the user.

For instance, the following code used in a PART midlet will create log files in the 'c:/other' directory which exists in many modern phones from SonyEricsson:

mgr = new IpFileLogManager("c:/other", "partlog", 20000, 3, "myMidlet");

The Lat log manager

The Lat log manager logs events to files in a format recognised by the IPerG Logfile Analysis and Evaluation Tool. This log manager is a little bit different than other log managers in that it only logs property events, e.g., property adds or updates. Another difference is that the manager is actually able to catch and log these event by itself, and doesn't need the application to call the log method. In fact, if the application code does call log, an exception is thrown. The reason for this is that the log format has to follow a strict syntax, and allowing the application to produce arbitrary log messages using the log method would surely lead to the production of incorrect log files, not understood by the log file analysis tool.

The manager is represented by the class IpLatLogManager. When creating a Lat log manager, all that needs to be supplied is the log directory and the name of the log file. If the file already exists, it will be overwritten.

IpLatLogManager mgr = new IpLatLogManager("c:\\temp\\", "partlog");  

The log manager will add the extension '.lat' to the filename given as a constructor parameter, so the file created in the example above will be c:\\temp\\partlog.lat. Even though it's possible to create many instances of the Lat log manager, and for instance supplying different values for the directory and/or log file parameters, it doesn't really make sense since the all managers will log the same events.

Instructions on how to use the  Logfile Analysis and Evaluation Tool to analyse a log file generated by PART can be found here.

theme by Chris M