LogFileParser (LogMX Parser & Manager Development API)

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

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

LogEntriesInfoProvider
```
public abstract class LogFileParser
extends Object
implements Cloneable
```
Abstract class that each LogMX Parser must extend.
A LogMX Parser gets lines of text as input (parseLine(String)), and shall parse these lines into log entries (addEntry(ParsedEntry)).

This class 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

Constructors
Constructor and Description

LogFileParser()
Default constructor.
Parsers don't have to override this constructor.

Constructors
Constructor and Description
`LogFileParser()` Default constructor. Parsers don't have to override this constructor.

Method Summary

All Methods Instance Methods Abstract Methods Concrete Methods
Modifier and Type	Method and Description
`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.
`String`	`getEntryStringRepresentation(ParsedEntry pEntry)` Called by LogMX to get a textual description of the given Log entry.
`String`	`getGUIName()` Called by the Parser to get the name of this parser, as set in LogMX GUI options (may be used to build error messages for example).
`int`	`getLastParsedLineNumber()` Called by the Parser to get the last parsed line number.
`protected Locale`	`getLocale()` Called by the Parser to get the Locale to use by this Parser (useful for Date & Time format handling).
`protected LogFileManager`	`getLogFileManager()` Called by the Parser to get the `LogFileManager` currently used to read the current log.
`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).
`String`	`getUserDefinedFieldDesription(String pField)` Called by LogMX to get a textual description of the given user-defined field (see `getUserDefinedFields()`).
`List<String>`	`getUserDefinedFields()` Called by LogMX to get the ordered list of user-defined fields to display (given by their key), for each entry.
`List<Class<?>>`	`getUserDefinedFieldsClasses()` Called by LogMX to get the type of each user-defined field (see `getUserDefinedFields()`).
`String`	`getVersionInfo()` Called by LogMX to get a Parser version info message to display.
`void`	`init()` Called by the Parser Tests to initialize this Parser.
`boolean`	`isEmitterFieldProvided()` Called by LogMX to detect invalid/incomplete log entries and to decide whether emitters tree shall be displayed.
`boolean`	`isLevelFieldProvided()` Called by LogMX to detect invalid/incomplete log entries: if this method returns `true` but this Parser produces an entry without any Level (i.e. `ParsedEntry.getLevel()` `null` or empty), then LogMX will consider this entry as invalid.
`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).
`protected void`	`removeLastEntry()` Called by the Parser to remove the last entry previously added using `addEntry(ParsedEntry)`.

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, T₀ 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 a complete Parser description (user name and content), or the String returned by getParserName(), depending on the available information.
    
    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). Parser should override this method if it wants to use entries user-defined fields. Each log entry stores its user-defined fields in its Map ParsedEntry.getUserDefinedFields().
    
    Returns:
    
    Ordered list of user-defined fields to display, for each entry
    
    Since:
    
    LogMX v2.0.0
    
    See Also:
    
    getUserDefinedFieldsClasses()
  - getUserDefinedFieldsClasses
```
public List<Class<?>> getUserDefinedFieldsClasses()
```
    Called by LogMX to get the type of each user-defined field (see getUserDefinedFields()).
    The default implementation for this class is to return an empty list, which means that LogMX will assume that all user-defined fields are String. The order of these types must match the order given by getUserDefinedFields(). Parser should override this method if it wants to use entries user-defined fields that should not be treated as String values (for example, if a user-defined field is declared as an Integer, sorting log entries by this field will produce the order {1, 2, 10} instead of {1, 10, 2}).
    
    Returns:
    
    Type of each user-defined field
    
    Since:
    
    LogMX v5.5.1
    
    See Also:
    
    getUserDefinedFields()
  - getUserDefinedFieldDesription
```
public String getUserDefinedFieldDesription(String pField)
```
    Called by LogMX to get a textual description of the given user-defined field (see getUserDefinedFields()).
    The default implementation for this class returns null, which means that the given field doesn't have any description.
    The returned description, if any, will be used to display a tooltip in the GUI when the mouse is hovering the field column's header (on the log entries table). Basic HTML formatting is supported for this description String (i.e. bold text, font color, ...).
    
    Parameters:
    
    pField - Field for which the textual description should be returned
    
    Returns:
    
    Textual description for the user-defined field pField
    
    Since:
    
    LogMX v7.9.0
    
    See Also:
    
    getUserDefinedFields()
  - getEntryStringRepresentation
```
public String getEntryStringRepresentation(ParsedEntry pEntry)
```
    Called by LogMX to get a textual description of the given Log entry.
    The default implementation for this class returns null, which means that LogMX will use its default formatter to build a textual description for the given Log entry.
    If the returned String is null, LogMX will use the user settings (i.e. which entry fields to display, in which order) to build a textual description in the "Entry details" GUI panel (below the log entries table).
    If the returned String is NOT null, this String will be used in this GUI panel, ignoring all user settings concerning this GUI panel. It's possible to tell LogMX to display some text in bold using the syntax [[B]]...[[/B]] (HTML formatting NOT supported).
    
    Parameters:
    
    pEntry - Log entry for which the textual description should be returned
    
    Returns:
    
    Textual description for the log entry pEntry
    
    Since:
    
    LogMX v7.9.0
  - getVersionInfo
```
public String getVersionInfo()
```
    Called by LogMX to get a Parser version info message to display.
    Implementing this method is optional for Parsers. Default provided implementation always returns null.
    Versioning your parser may be useful if you often upgrade your parser, so that LogMX can display in its graphical interface the current version in use for your parser (in Parsers options dialog).
    
    Returns:
    
    Parser version info message (e.g. "v1.0-21/05/2013")
    
    Since:
    
    LogMX v4.1.1
  - isEmitterFieldProvided
```
public boolean isEmitterFieldProvided()
```
    Called by LogMX to detect invalid/incomplete log entries and to decide whether emitters tree shall be displayed.
    If this method returns true:
    - If this Parser produces an entry without any Emitter (i.e. ParsedEntry.getEmitter() null or empty), then LogMX will consider this entry as invalid, and may then decide to ignore it.
    If this method returns false:
    - The emitters tree in main window will be empty (will not try to find emitters for log entries)
    Implementing this method is optional for Parsers (useful for multi-lines log formats in AutoRefresh and log formats without any emitter). Default provided implementation returns true.
    Returns:
    
    true if this Parser usually sets entries 'Emitter' field (false if it never uses emitters)
    
    Since:
    
    LogMX v5.0.0
  - isLevelFieldProvided
```
public boolean isLevelFieldProvided()
```
    Called by LogMX to detect invalid/incomplete log entries: if this method returns true but this Parser produces an entry without any Level (i.e. ParsedEntry.getLevel() null or empty), then LogMX will consider this entry as invalid.
    Implementing this method is optional for Parsers (useful for multi-lines log formats in AutoRefresh). Default provided implementation returns true.
    
    Returns:
    
    true if this Parser usually sets entries 'Level' field (false otherwise)
    
    Since:
    
    LogMX v5.0.0
  - init
```
public final void init()
```
    Called by the Parser Tests to initialize this Parser.
    If developers implement Unit Tests for their Parsers, they will need to call this method before using this parser. But this method should not be called when the Parser is used by LogMX. Calling this method multiple times will have no effect.
    
    Since:
    
    LogMX v8.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 in most cases. However, when used for AutoRefresh, this method can be called for the same pParsedEntry each time this entry has been enriched by this Parser (e.g: new line of text available for 'Message' entry field). In this case, LogMX will update this entry on each call.
    
    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
  - removeLastEntry
```
protected final void removeLastEntry()
```
    Called by the Parser to remove the last entry previously added using addEntry(ParsedEntry).
    Calling this method when no entry was added has no effect.
    
    Since:
    
    LogMX v5.0.2
  - 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 from their constructor (will return null).
    
    Returns:
    
    Name of the file to be parsed by this Parser
    
    Since:
    
    LogMX v3.0.2
  - getLogFileManager
```
protected final LogFileManager getLogFileManager()
```
    Called by the Parser to get the LogFileManager currently used to read the current log.
    LogMX may return null in some cases (internal parsing, Parser test wizard, ...). This method may be useful to get more technical information on the underlying data source in order to enrich parsed log entries (e.g. remote IP/port sending the logs, database version, ...)
    
    Returns:
    
    LogFileManager currently used to read the current log, or null if no Manager at this time
    
    Since:
    
    LogMX v5.4.0
  - getLastParsedLineNumber
```
public final int getLastParsedLineNumber()
```
    Called by the Parser to get the last parsed line number.
    
    Returns:
    
    Last parsed line number (or -1 if no line number found)
    
    Since:
    
    LogMX v3.1.0
  - getGUIName
```
public final String getGUIName()
```
    Called by the Parser to get the name of this parser, as set in LogMX GUI options (may be used to build error messages for example).
    
    Returns:
    
    Name of this parser, as set in LogMX GUI options
    
    Since:
    
    LogMX v4.0.0

LogMX The universal log analyzer
logmx.com

LogMX The universal log analyzer
logmx.com

Class LogFileParser

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Constructor Detail

LogFileParser

Method Detail

parseLine

getRelativeEntryDate

getAbsoluteEntryDate

getParserName

getSupportedFileType

getDescriptionForUser

getUserDefinedFields

getUserDefinedFieldsClasses

getUserDefinedFieldDesription

getEntryStringRepresentation

getVersionInfo

isEmitterFieldProvided

isLevelFieldProvided

init

createNewEntry

addEntry

removeLastEntry

getLocale

getParsedFileName

getLogFileManager

getLastParsedLineNumber

getGUIName