momelog.listener
Class LogFile

java.lang.Object
  momelog.listener.LogFile

All Implemented Interfaces:

FileSystemListener, Configurable, LogListener

public class LogFile
extends Object
implements Configurable, LogListener, FileSystemListener

LogListener implementation intended to collect logging information in the destination file. It can be used only on devices or emulators that support FileConnection API.

LogFile resembles very much corresponding class in log4J framework. All logging events are converted to strings and written to the destination text file separated by new-line character ('\n'). By using setPrefix(String) and/or setSuffix(String) setter methods it is possible to specify strings to be putted at the start and/or at the end of each logging line respectively. It is also possible to specify first (header) and last (footer) line of the destination file by calling setHeader(String) and setFooter(String) setter methods respectively. Footer line is written , when close() method is called at the end of the application's run. Header line is only written, if LogFile creates or rewrites the destination file.

The location of the destination file can be set by calling setOutfile(String) setter method. It is specified via 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. By default, the location of the destination file is set to "momelog" in first root returned from FileSystemRegistry.listRoots() static method.

The character encoding used for writing file can be specified by setEncoding(String) setter method. By default UTF-8 encoding is used. It is also possible to specify whether destination file should be rewritten on open, if it already exists by using setAppend(boolean) setter method. It is rewritten by default.

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 application's run (e.g. from MIDlet.destroyApp(boolean unconditional) method). Besides it is recommended, users need to do this only, if they are interesting in footer line to be written at the end of the file, because destination file is flushed after every logging line.

LogFile implements FileSystemListener interface. Root, where destination file is located, can be unmounted between logging. To eliminate I/O errors, no logging information is written at that time. After next root mount, new logging lines will be appended to the destination file (destination file will be not rewritten and skipped logging lines will be lost).

LogFile implements Configurable interface. It can be configured declaratively from initialization file (recommended) and/or programmatically by invoking setter methods. LogFile provides meaningful default values for all properties and doesn't require configuration.

See LogFile Guide for more details.

Version:

1.0

Author:

Sergio Morozov

Field Summary

static String	DEFAULT_DESTINATION_FILENAME Default filename of the destination file ("momelog.log").
static String	DEFAULT_ENCODING Default character encoding to be used for writing the destination file (UTF-8).

Fields inherited from interface javax.microedition.io.file.FileSystemListener

ROOT_ADDED, ROOT_REMOVED

Constructor Summary

LogFile()
Instantiates LogFile with default character encoding and no outfile.

LogFile(String outFile)
Instantiates LogFile initialized with the given location of the destination file and default encoding (UTF-8).

LogFile(String outFile, String encoding)
Instantiates LogFile initialized with the given location of the destination file and encoding.

Method Summary

void	close() Writes footer line (if there is some) and then closes connection to the destination file and all it's streams.
void	configure(char[] lines, int offset, int length) Configures LogFile instance from the given character sequence.
String	getEncoding() Returns character encoding used for writing the destination file.
String	getFooter() Returns footer line to be written at the end of the destination file or null, if no line should be written.
String	getHeader() Returns header line to be written at the start of the destination file or null, if no line should be written.
String	getOutFile() Returns location of the destination file.
String	getPrefix() Returns string to be written at the start of each logging line or null, if no string should be written.
String	getSuffix() Returns string to be written at the end of each logging line or null, if no string should be written.
boolean	isAppend() Returns append flag, that indicates whether destination file is rewritten on open, if it already exists.
void	onLog(LogEvent event) Appends formatted logging lines to the destination file and then flushes the buffer.
void	rootChanged(int eventType, String root)
void	setAppend(boolean append) Sets append flag, that controls whether destination file should be rewritten on open, if it already exists.
void	setEncoding(String encoding) Sets character encoding to be used for writing the destination file.
void	setFooter(String footer) Sets footer line to be written at the end of the destination file.
void	setHeader(String header) Sets header line to be written at the start of the destination file.
void	setOutfile(String outFile) Sets location of the destination file.
void	setPrefix(String prefix) Sets string to be written at the start of each logging line.
void	setSuffix(String suffix) Sets string to be written at the end of each logging line.

Methods inherited from class java.lang.Object

equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

DEFAULT_DESTINATION_FILENAME

public static final String DEFAULT_DESTINATION_FILENAME

Default filename of the destination file ("momelog.log").

See Also:

Constant Field Values

DEFAULT_ENCODING

public static final String DEFAULT_ENCODING

Default character encoding to be used for writing the destination file (UTF-8).

See Also:

Constant Field Values

Constructor Detail

LogFile

public LogFile()

Instantiates LogFile with default character encoding and no outfile.

LogFile

public LogFile(String outFile)

Instantiates LogFile initialized with the given location of the destination file and default encoding (UTF-8). The location of destination file is 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.

Parameters:

outFile - location of the destination file.

Throws:

NullPointerException - if outFile is null.

IllegalArgumentException - if outFile is empty or doesn't start with a slash (/).

LogFile

public LogFile(String outFile,
               String encoding)

Instantiates LogFile initialized with the given location of the destination file and encoding. The location of destination file is 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.

Parameters:

outFile - location of the destination file.

encoding - character encoding to be used for writing destination file.

Throws:

NullPointerException - if outFile or encoding is null.

IllegalArgumentException - if outFile is empty or doesn't start with a slash (/).

Method Detail

isAppend

public boolean isAppend()

Returns append flag, that indicates whether destination file is rewritten on open, if it already exists.

Returns:

false if the destination file is rewritten on open, if it already exists, true otherwise.

setAppend

public void setAppend(boolean append)

Sets append flag, that controls whether destination file should be rewritten on open, if it already exists.

Parameters:

append - false if the destination file should be rewritten on open, if it already exists, true otherwise.

getEncoding

public String getEncoding()

Returns character encoding used for writing the destination file.

Returns:

the character encoding used for writing the destination file.

setEncoding

public void setEncoding(String encoding)

Sets character encoding to be used for writing the destination file. This method, to take effect, should be called before opening the destination file.

Parameters:

encoding - character encoding to be used for writing to the destination file.

Throws:

NullPointerException - if encoding is null.

getOutFile

public String getOutFile()

Returns location of the destination file.

Returns:

file path of the destination file.

setOutfile

public void setOutfile(String outFile)

Sets location of the destination file. The location of destination file is 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.

Note: If this method is called, when some other file is already open, it is closed (footer line, if there is some, is written) and connection to a new one is opened on new logging.

Parameters:

outFile - the location to the destination file.

Throws:

NullPointerException - if outFile is null.

IllegalArgumentException - if outFile is empty or doesn't start with a slash (/).

onLog

public void onLog(LogEvent event)

Appends formatted logging lines to the destination file and then flushes the buffer. Opens file, if it is not already open.

Specified by:

onLog in interface LogListener

Parameters:

event - LogEvent instance containing information about logging event.

See Also:

LogListener.onLog(momelog.LogEvent)

close

public void close()

Writes footer line (if there is some) and then closes connection to the destination file and all it's streams.

rootChanged

public void rootChanged(int eventType,
                        String root)

Specified by:

rootChanged in interface FileSystemListener

getFooter

public String getFooter()

Returns footer line to be written at the end of the destination file or null, if no line should be written.

Note: footer line is written only when close() method is called at the end of application's run (e.g. from MIDlet.destroyApp(boolean unconditional) method).

Returns:

footer line to be written at the end of the destination file or null, if no line should be written.

setFooter

public void setFooter(String footer)

Sets footer line to be written at the end of the destination file.

Note: footer line is written only when close() method is called at the end of application's run (e.g. from MIDlet.destroyApp(boolean unconditional) method).

Parameters:

footer - footer line to be written at the end of the destination file or null, if no line should be written.

getHeader

public String getHeader()

Returns header line to be written at the start of the destination file or null, if no line should be written.

Note: header line is written only, if LogFile creates or rewrites the destination file.

Returns:

header line to be written at the start of the destination file or null, if no line should be written.

setHeader

public void setHeader(String header)

Sets header line to be written at the start of the destination file.

Note: header line is written only, if LogFile creates or rewrites the destination file.

Parameters:

header - line to be written at the start of the destination file or null, if no line should be written.

getPrefix

public String getPrefix()

Returns string to be written at the start of each logging line or null, if no string should be written.

Returns:

string to be written at the start of each logging line or null, if no string should be written.

setPrefix

public void setPrefix(String prefix)

Sets string to be written at the start of each logging line.

Parameters:

prefix - string to be written at the start of each logging line or null, if no string should be written.

getSuffix

public String getSuffix()

Returns string to be written at the end of each logging line or null, if no string should be written.

Returns:

string to be written at the end of each logging line or null, if no string should be written.

setSuffix

public void setSuffix(String suffix)

Sets string to be written at the end of each logging line.

Parameters:

suffix - string to be written at the end of each logging line or null, if no string should be written.

configure

public void configure(char[] lines,
                      int offset,
                      int length)

Configures LogFile instance from the given character sequence. Character sequence should consist of lines separated by new-line character ('\n'). Each line should contain the name-value pair separated by equal sign (=). Spaces around properties names are allowed and ignored. Spaces around properties values are allowed.

LogFile supports following properties. All properties names are in lower-case. If some property is specified more than one time, the last occurrence prevails.

Property Name	Description	Default Value
"outfile"	Specifies the location of the destination file. It is specified as 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. The default value is set to the "momelog.log" file in first root returned from FileSystemRegistry.listRoots() method. Note: Spaces around value of this property are ignored. Since version 1.0	"/<1st-root>/momelog.log"
"append"	If false, destination file is rewritten on open, if it already exists. If true and destination file exists, no header is written and logging lines are appended to the end of the destination file. The default value is false. Note: Spaces around value of this property are ignored. Since version 1.0	false
"encoding"	Specifies character encoding to be used for writing the destination file. The default value is UTF-8. Note: Spaces around value of this property are ignored. Since version 1.0	UTF-8
"footer"	Specifies line to be written at the end of the destination file. The default value is null (i.e. no line is written). Note: footer line is only written, if method close() is called at the end of the application's run (e.g. from MIDlet.destroyApp(boolean unconditional) method). Note: Spaces around value of this property are significant. Since version 1.0	null (no line is written).
"header"	Specifies line to be written at the start of the destination file. The default value is null (i.e. no line is written). Note: header line is only written, if LogFile creates or rewrites the destination file. Note: Spaces around value of this property are significant. Since version 1.0	null (no line is written).
"prefix"	Specifies string to be written at the start of each logging line. The default value is null (i.e. no string is written). Note: Spaces around value of this property are significant. Since version 1.0	null (no string is written).
"suffix"	Specifies string to be written at the end of each logging line. The default value is null (i.e. no string is written). Note: Spaces around value of this property are significant. Since version 1.0	null (no string is written).

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 =]
 

Specified by:

configure in interface Configurable

Parameters:

lines - char array containing character sequence.

offset - position of the first character of sequence in given array.

length - length of the sequence in characters.

See Also:

Configurable.configure(char[], int, int)