com.lightysoft.logmx.mgr
Class LogFileParser

java.lang.Object
  com.lightysoft.logmx.mgr.LogFileParser

public abstract class LogFileParser
extends Object

Abstract class that each LogMX Parser must extend.
Contains abstract methods to be implemented by Parsers, and final methods to be called by parsers.

Since:

LogMX v1.0

Author:

LightySoft

See Also:

ParsedEntry

Constructor Summary

LogFileParser()
Default constructor.

Method Summary

protected void	addEntry(ParsedEntry pParsedEntry) Called by the Parser for each entry it has successfully parsed.
protected ParsedEntry	createNewEntry() Called by the Parser to create and return a new blank log entry to be used by this Parser.
abstract Date	getAbsoluteEntryDate(ParsedEntry pEntry) Called by LogMX to get the Date of the specified entry, or null if this Parser could not return the Date for this entry.
String	getDescriptionForUser() Called by LogMX to get a complete description of this parser to build error messages.
protected Locale	getLocale() Called by the Parser to get the Locale to use by this Parser (useful for Date & Time format handling).
protected String	getParsedFileName() Called by the Parser to get the name of the file to be parsed by this Parser.
abstract String	getParserName() Called by LogMX to get the name of this Parser.
abstract Date	getRelativeEntryDate(ParsedEntry pEntry) Called by LogMX to get a timestamp for entry pEntry, or null if this Parser doesn't support relative timestamps.
abstract String	getSupportedFileType() Called by LogMX to get a short description of supported file type(s).
List<String>	getUserDefinedFields() Called by LogMX to get the ordered list of user-defined fields to display (given by their key), for each entry.
protected abstract void	parseLine(String pLine) Called by LogMX each time a new line is read from the underlying media by the LogFileManager (eg: a line is read from a local file).

Methods inherited from class java.lang.Object

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

Constructor Detail

LogFileParser

public LogFileParser()

Default constructor.
Parsers don't have to override this constructor.

Since:

LogMX v1.0

Method Detail

parseLine

protected abstract void parseLine(String pLine)
                           throws Exception

Called by LogMX each time a new line is read from the underlying media by the LogFileManager (eg: a line is read from a local file).
LogFileManager contract implies this line contains no line terminator (\n or \r).
All Parsers must implement this method and process all lines given by this method.

Parameters:

pLine - New line to process by Parser (should not contain \n or \r).
If this parameter is null, that means the LogFileManager has no more line to read.

Throws:

Exception - If an unexpected error occurs while Parser processed new line. LogMX will then notify the user with a dialog box and will try to parse the file with the next parser

Since:

LogMX v1.0

getRelativeEntryDate

public abstract Date getRelativeEntryDate(ParsedEntry pEntry)
                                   throws Exception

Called by LogMX to get a timestamp for entry pEntry, or null if this Parser doesn't support relative timestamps.
A relative timestamp is a timestamp relative to any arbitrary start date (in many cases, T0 matches the launch of the process that writes the log file).
Parser should try to get this timestamp from the data given by pEntry.getExtraInfo() or pEntry.getDate(). This timestamp can be a complete Date (from milliseconds to year), or a simple number of milliseconds relative to this entry (e.g.: new Date(125)).

This method is called by LogMX to compute elapsed time between two entries.

The general contract of this method is:
If two entries e1 and e2 are 'separated' by X milliseconds, then
| getRelativeEntryDate(e1).getTime() - getRelativeEntryDate(e2).getTime() |
must be equal to X.

Note that LogMX will only call this method on the Parser that parsed entry pEntry.

Parameters:

pEntry - Entry which timestamp must be computed

Returns:

Relative timestamp for pEntry, or null if this Parser doesn't support relative timestamps

Throws:

Exception - If an unexpected error occurs while computing timestamp (should not happen: if Parser can't compute timestamp for this entry, it should return null)

Since:

LogMX v1.0

getAbsoluteEntryDate

public abstract Date getAbsoluteEntryDate(ParsedEntry pEntry)
                                   throws Exception

Called by LogMX to get the Date of the specified entry, or null if this Parser could not return the Date for this entry.
Parser should try to get this Date from the String given by pEntry.getDate(). This Date must be a complete one, from Year to Milliseconds (or seconds if file format is not accurate enough).
This method is called by LogMX to compute elapsed time since an entry was generated (i.e. elapsed time between entry's date and now).

Note that LogMX will only call this method on the Parser that parsed entry pEntry.

Parameters:

pEntry - Entry which Date must be computed

Returns:

Date for pEntry, or null if this Parser could not return its Date

Throws:

Exception - If an unexpected error occurs while computing Date

Since:

LogMX v1.0

getParserName

public abstract String getParserName()

Called by LogMX to get the name of this Parser.
All Parsers must implement this method to return a short name (~3 words maximum) that will be displayed in LogMX GUI.

Returns:

Parser name

Since:

LogMX v1.0

getSupportedFileType

public abstract String getSupportedFileType()

Called by LogMX to get a short description of supported file type(s).
All Parsers must implement this method to return a short description (~3 words maximum) of supported file type(s) (will be displayed in LogMX GUI).

Returns:

Parser supported file type(s) description

Since:

LogMX v1.0

getDescriptionForUser

public String getDescriptionForUser()

Called by LogMX to get a complete description of this parser to build error messages.
Implementing this method is optional for Parsers (default provided implementation returns the String returned by getParserName()

Returns:

Complete description of this parser

Since:

LogMX v1.2.5

getUserDefinedFields

public List<String> getUserDefinedFields()

Called by LogMX to get the ordered list of user-defined fields to display (given by their key), for each entry.
The default implementation for this class is to return an empty list (i.e. no user-defined field by default). Each parser should override this method if it wants to use entries user-defined fields. User-defined fields are stored in each entry Map ParsedEntry.getUserDefinedFields()

Returns:

Ordered list of user-defined fields to display, for each entry

Since:

LogMX v2.0.0

createNewEntry

protected final ParsedEntry createNewEntry()

Called by the Parser to create and return a new blank log entry to be used by this Parser.
Parsers should not try to directly create entries instead of calling this method.

Returns:

New blank Entry to be used by the Parser

Since:

LogMX v1.0

addEntry

protected final void addEntry(ParsedEntry pParsedEntry)
                       throws Exception

Called by the Parser for each entry it has successfully parsed.
Calling this method several consecutive times with the same pParsedEntry produces no effect.

Parameters:

pParsedEntry - Entry parsed by Parser

Throws:

Exception - If pParsedEntry.getLevel() is an invalid Level and user wants to abort this Parser process (LogMX will then switch to next Parser). Parser should NOT catch this Exception: its method parseLine(String) should simply 'propagate' this Exception so that LogMX can process it.

Since:

LogMX v1.0

getLocale

protected final Locale getLocale()

Called by the Parser to get the Locale to use by this Parser (useful for Date & Time format handling).
Parsers should not call this method in constructor (will return null).

Returns:

Locale to use by this Parser

Since:

LogMX v2.0.0

getParsedFileName

protected final String getParsedFileName()

Called by the Parser to get the name of the file to be parsed by this Parser.
Parsers should not call this method in constructor (will return null).

Returns:

Name of the file to be parsed by this Parser

Since:

LogMX v3.0.2