com.lightysoft.logmx.mgr

Class LogFileManager

java.lang.Object

com.lightysoft.logmx.mgr.LogFileManager

All Implemented Interfaces:

Cloneable

Direct Known Subclasses:

LogStreamManager

public abstract class LogFileManager
extends Object
implements Cloneable

Abstract class that each LogMX Manager must extend. A Manager is used by LogMX to get the bytes that will be read by the log parser. For example, you can define your own Manager reading log content from a database, an internal system, or anything else.

This class contains abstract methods to be implemented by Managers, and final methods to be called by Managers.

• Managers MUST NOT overload their default Constructor (i.e. define a new Constructor with new parameters). Doing so will produce an error when LogMX will try to clone this Manager.
• Managers may not override their default Constructor (i.e. redefine it, without any parameter). If you override a Constructor, do not allocate resources or perform time-consuming operations in it, since LogMX can call it any time without calling releaseResources().


Here is how LogMX uses a classic Manager (i.e. not a live stream Manager or an entries-extraction Manager):

1. Calls init(LogURL, String)
2. Calls getCurrentURL()
3. Calls setEncoding() (non-public method used to set the Encoding returned by getEncoding())
4. Calls prepareForReading()
5. Calls supportHeaderReading()
6. Calls readFileHeader(int) (if Manager returned true to supportHeaderReading())
7. Calls setEncoding() and newEncodingDetected() if a new encoding was detected by LogMX and if Manager supports Encoding auto-detection
8. Calls readLine() until it returns null
9. Calls getCurrentFileLastModifDate() periodically (through getCurrentFileInfo())
10. Calls getCurrentFileSize() periodically (through getCurrentFileInfo())
11. Calls releaseResources(boolean)

To support Auto Refresh, a Manager must:

• return true in supportHeaderReading()
• return true in supportRandomAccess()
• implement readFileHeader(int)
• implement readLineAtOffset(long)
• implement getCurrentOffset()
• implement at least one of getCurrentFileSize() or getCurrentFileLastModifDate(). The unimplemented method should always return the same value

To support Encoding auto-detection, a Manager must:

• return true in supportHeaderReading()
• implement readFileHeader(int)

To support on-the-fly decompression (e.g. ZIP, GZIP, ...), a Manager must (since LogMX v5.2.0):

• call getDecompressedStream(String, InputStream) with its current input stream as parameter, to get an uncompressed stream to read from
• call getCompressFormat() to know which compression method is used (e.g. ZIP, GZIP, ...), if any

To support live stream reading (no random access to a given offset, like when reading sockets, pipe, serial bus, ...), a Manager must (since LogMX v5.2.0):

• extend LogStreamManager
• implement LogStreamManager.setHasReadTimeout(boolean) to enable or disable read timeout

To support log entries extraction (i.e. Manager directly creates log entries without the use of a LogFileParser), a Manager must (since LogMX v5.2.0):

• return true in supportLogEntriesExtraction()
• return a valid LogEntriesInfoProvider in getLogEntriesInfoProvider() to provide LogMX with extracted entries extra information (date format, user-defined fields)
• implement readEntry() to read the next log entry from the underlying resource
• call createNewEntryForExtraction() to create an instance of a new, initialized log entry instance to enrich in readEntry()

Here are a few links to get more information on LogMX managers:

• Manager development guide: https://logmx.com/manager-dev
• Manager implementation example: "managers/src" directory of your LogMX distribution
• Manager development forum: https://logmx.com/forum/viewforum.php?f=2

Since:

LogMX v1.2.2, Manager Specification Version 1.0

Author:

LightySoft

See Also:

ManagerSpecVersion

Field Summary

Fields

Modifier and Type	Field and Description
Object	READ_MUTEX Mutex used by LogMX and the Manager to ensure that only one thread makes this Manager read from the underlying resource, at the same time.

Constructor Summary

Constructors

Constructor and Description
LogFileManager() Default constructor. Managers should not override it.

Method Summary

Modifier and Type	Method and Description
boolean	canUseParser(LogFileParser pParser) Called by LogMX to know if the given parser can be used to parse the data returned by this LogFileManager.
protected ParsedEntry	createNewEntryForExtraction() Called by the Manager to create and return a new blank log entry to be used by this Manager during entry extraction (see supportLogEntriesExtraction()).
abstract boolean	deleteFile() Called by LogMX to delete (i.e. remove from disk) the current file.
abstract boolean	flushFile() Called by LogMX to flush (i.e. empty) the current file.
int	getAutoRefreshDelay() Called by LogMX to know the delay (in ms) to wait between each automatic refresh, for all logs opened with this LogFileManager.
String	getCompressFormat() Called by the Manager to get the name of the compression method that was detected during previous call to getCompressFormatFromFileName(String) and getDecompressedStream(InputStream, String).
String	getCompressFormatFromFileName(String pFileName) Called by the Manager to know the compression format that should be used for the given file name (guessed from its extension: ZIP, GZIP or others).
int	getConnectionTimeout() Called by the Manager to get the current value (in seconds) for the user setting "Connection timeout", according to LogMX user preferences set in LogMX GUI.
LogFileInfo	getCurrentFileInfo() Called periodically by LogMX to get the current file size and date.
abstract long	getCurrentFileLastModifDate() Called by LogMX to know when the opened resource was modified for the last time.
abstract long	getCurrentFileSize() Called by LogMX to get the current resource size in bytes.
abstract long	getCurrentOffset() Called by LogMX to know the current position in file.
abstract String	getCurrentURL() Called by LogMX to get the current opened URL, matching this Manager URL template.
InputStream	getDecompressedStream(InputStream pInputStream, String pCompressFormat) Called by the Manager to get, if needed, a stream of uncompressed data for the specified logs stream and specified compression format.
InputStream	getDecompressedStream(String pFileName, InputStream pInputStream) Called by the Manager to get, if needed, a stream of uncompressed data for the specified logs stream (case of file compressed with ZIP, GZIP or others).
String	getEncoding() Called by the Manager to get the Encoding to use when reading bytes.
abstract Icon	getFileTypeIcon() Called by LogMX to get this Manager icon, which must be a 16x16 icon.
Icon	getFileTypeIcon32x32() Called by LogMX to get this Manager icon, which must be a 32x32 icon.
static Icon	getIconFile(String pImageFileName) Called by the Manager to get the image contained in file named pImageFileName in LogMX "pics/" directory.
LogEntriesInfoProvider	getLogEntriesInfoProvider() Called by LogMX to request the Manager to provide an object that will enrich extracted log entries (like Parsers do): log entry date conversions, user-defined fields management.
abstract String	getName() Called by LogMX to get the name of this Manager.
char[]	getOrAskUserPassword(String pLogin, String pHost) Called by the Manager to get a user password saved in LogMX password repository, or by asking the user their password if the password is not saved in LogMX password repository yet.
abstract String	getProtocolName() Called by LogMX to get the Protocol handled by this Manager.
ProxySettings	getProxySettings(String pHost) Called by the Manager to get the proxy settings to use to connect to a host, according to LogMX user preferences set in LogMX GUI.
String	getShortFilename() Called by LogMX to get a shorter version of current URL, in order to display it in GUI file tab.
abstract ManagerSpecVersion	getSpecificationVersion() Called by LogMX to get the Manager Specification version supported by this Manager.
abstract LogURL	getTemplateLogURL() Called by LogMX to get a template of LogURL used by this Manager.
static String	getURLFromLogURL(LogURL pLogURL, String pURLPattern) Called by the Manager to construct a string URL from a LogURL and a URL pattern.
abstract String	getURLPattern() Called by LogMX to know how to display a URL handled by this Manager.
abstract void	init(LogURL pLogURL, String pURLString) Called by LogMX to initialize the Manager for the specified resource.
boolean	isLiveStream() Called by LogMX to know if this Manager reads log entries from a live stream (e.g.
void	newEncodingDetected() Called by LogMX after prepareForReading() and before readLine() if and only if the encoding to use (to read bytes from the underlying resource) has changed.
abstract LogFileInfo	prepareForReading() Called by LogMX to open the resource previously specified by init(LogURL, String) to get ready to read this underlying resource, and return information on this resource (size and date).
ParsedEntry	readEntry() Called by LogMX to request the Manager to extract the next log entry.
abstract byte[]	readFileHeader(int pNumBytes) Called by LogMX to read the first pNumBytes bytes from the underlying file or resource.
abstract String	readLine() Called by LogMX to get the next line of text from the underlying Manager resource (file, stream, socket,...).
abstract AutoRefreshLineInfo	readLineAtOffset(long pOffset) Called by LogMX to read the line of text starting at the specified offset.
abstract void	releaseResources(boolean pSoftRelease) Called by LogMX when it doesn't need to use this Manager anymore.
abstract boolean	supportFileDelete() Called by LogMX to know if this Manager can delete (i.e. remove from disk) the current file.
abstract boolean	supportFileFlush() Called by LogMX to know if this Manager can flush (i.e. empty) the current file.
abstract boolean	supportHeaderReading() Called by LogMX to know if this Manager support header reading (read a specified number of bytes from the beginning of the file).
boolean	supportLogEntriesExtraction() Called by LogMX to know if this Manager can extract log entries itself, without the use of any Log Parser (e.g.
abstract boolean	supportRandomAccess() Called by LogMX to know if this Manager support random access (read bytes starting at a specified offset).

Methods inherited from class java.lang.Object

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

Field Detail

READ_MUTEX

public final Object READ_MUTEX

Mutex used by LogMX and the Manager to ensure that only one thread makes this Manager read from the underlying resource, at the same time. Managers can synchronize with this Mutex if they don't want getCurrentFileLastModifDate() or getCurrentFileSize() to be called by LogMX during a specific code execution.

Since:

LogMX v1.2.4, Manager Specification Version 1.1

Constructor Detail

LogFileManager

public LogFileManager()

Default constructor.
Managers should not override it. Don't allocate resources or perform time-consuming operations in it, since LogMX can call it any time without calling releaseResources().

Since:

LogMX v1.2.2, Manager Specification Version 1.0

Method Detail

getName

public abstract String getName()

Called by LogMX to get the name of this Manager. This name can contain any character and is displayed in LogMX GUI.

Returns:

Manager name

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getTemplateLogURL

public abstract LogURL getTemplateLogURL()

Called by LogMX to get a template of LogURL used by this Manager.

The returned LogURL can (should) be a static shared instance for better performance. LogMX will not use it directly but will use a clone of it.

Returns:

LogURL used by this Manager

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

See Also:

LogURL

getURLPattern

public abstract String getURLPattern()

Called by LogMX to know how to display a URL handled by this Manager. The syntax is:

• SimpleText to denote text "SimpleText"
• {MyParam} to denote the value of LogURLParameter named "MyParam"
• [SimpleOptionalPart] to denote an optional part containing free text, LogURLParameter value, or both.

Here are a few examples of patterns this method can return and URLs matching this pattern:

• scp://{Login}@{Host}:[{Port}:]{File}
  • scp://john@myhost:22:/mydir/myfile.log
  • scp://john@myhost:/myfile.log
• http://{Host}[:{Port}][/{File}]
  • http://logmx.com:80/myscript.php?p=4
  • http://logmx.com:80/mypage.html
  • http://logmx.com

Returns:

URL Pattern used by this Manager

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

init

public abstract void init(LogURL pLogURL,
                          String pURLString)
                   throws Exception

Called by LogMX to initialize the Manager for the specified resource.
This method should not try to open any resource yet, but should only save URL parameters for further use (resources may be opened later in prepareForReading()).

Parameters:

pLogURL - LogURL for the resource this Manager will have to open

pURLString - String representation for this URL (may be helpful for the Manager, especially to implement getCurrentURL()

Throws:

Exception - If the Manager is not able to process this URL

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getProtocolName

public abstract String getProtocolName()

Called by LogMX to get the Protocol handled by this Manager.
This protocol can be any string, like "http", "jdbc", "ftp", "myprotocol", ...
LogMX will use it to find the Manager to use for a given a URL (eg: "jdbc:oracle:thin:@host:1521:db")

Returns:

Protocol handled by this Manager

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

readLine

public abstract String readLine()
                         throws Exception

Called by LogMX to get the next line of text from the underlying Manager resource (file, stream, socket,...).
Manager must return null if there is no more byte to read.

Returns:

Next line, or null if there is no more byte to read.

Throws:

Exception - If an error occurred while reading bytes. Managers should not handle Exceptions but should throw them instead, so that LogMX can catch them.

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

releaseResources

public abstract void releaseResources(boolean pSoftRelease)

Called by LogMX when it doesn't need to use this Manager anymore.
This method should release all resources allocated by this Manager (e.g. close file, socket,...)
Once this method is called, LogMX will not call readLine() anymore if pSoftRelease was false.

Parameters:

pSoftRelease - Used for Auto-Refresh feature: if true, the Manager must not release resources needed to read next line of text.

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

prepareForReading

public abstract LogFileInfo prepareForReading()
                                       throws Exception

Called by LogMX to open the resource previously specified by init(LogURL, String) to get ready to read this underlying resource, and return information on this resource (size and date).
If the Manager is not able to get the number of bytes to read, it can return a negative number. Since this number is used to display a progress bar while the Manager is loading the resource, returning a negative number will make the progress bar stays at "100%" all the time.

Returns:

File information structure (containing file size/date).

Throws:

Exception - If the resource could not be opened (this Exception message will be displayed in LogMX GUI)

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getCurrentURL

public abstract String getCurrentURL()

Called by LogMX to get the current opened URL, matching this Manager URL template.
This method may return the URL string received by init(LogURL, String), or use getURLFromLogURL(LogURL, String) to construct the URL.

Returns:

Current opened URL

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

See Also:

getShortFilename()

getShortFilename

public String getShortFilename()

Called by LogMX to get a shorter version of current URL, in order to display it in GUI file tab.
This method is not abstract or final, so that most Managers may not have to override (i.e. redefine) it, but some others can. The default implementation returns null which means that LogMX will guess a shorter version of current URL (like "myfile" for URL "ftp://john@server/mydir/myfile").

Overriding this method is useful, for example, if URLs can end with some parameters like in "ftp://john@server/mydir/myfile?p=1", so that only "myfile" is displayed in GUI file tab instead of "myfile?p=1".

Returns:

Shorter version of current URL (to be displayed in GUI file tab), or null if not implemented (shorter version of URL will be guessed)

Since:

LogMX v4.0.0, Manager Specification Version 1.1 (see ManagerSpecVersion)

See Also:

getCurrentURL()

deleteFile

public abstract boolean deleteFile()

Called by LogMX to delete (i.e. remove from disk) the current file.
If this Manager doesn't support this feature (supportFileDelete() returns false), this method may only contain "return false;".

Returns:

true if deletion succeeded, or false it didn't.

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

flushFile

public abstract boolean flushFile()

Called by LogMX to flush (i.e. empty) the current file.
If this Manager doesn't support this feature (supportFileFlush() returns false), this method may only contain "return false;".

Returns:

true if flush succeeded, or false it didn't.

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getCurrentFileLastModifDate

public abstract long getCurrentFileLastModifDate()
                                          throws Exception

Called by LogMX to know when the opened resource was modified for the last time.
The expected result is a standard Java timestamp (number of milliseconds since 01/01/1970, 00:00:00 GMT). For example, if you have a Java Date, you can get such a timestamp using Date.getTime().

This method may be called periodically, so it should be rather fast (e.g. no socket connection, but fast I/O operations).

If the Manager is not able to get this timestamp (or if it only implements getCurrentFileInfo() for performances reason) it may return -1, but file-change detection will be affected if getCurrentFileInfo() also returns -1 as timestamp.

Returns:

A Java-based timestamp of last modification, or -1 if Manager can't get this timestamp

Throws:

Exception - If the Manager should be able to get the timestamp but could not due to an unexpected event (e.g. I/O error, authentication failure, timeout, ...)

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getCurrentFileSize

public abstract long getCurrentFileSize()
                                 throws Exception

Called by LogMX to get the current resource size in bytes.

This method may be called periodically, so it should be rather fast (e.g. no socket connection, but fast I/O operations).

If the Manager is not able to get this size (or if it only implements getCurrentFileInfo() for performances reason), it may return -1, but file-change detection will be affected if getCurrentFileInfo() also returns -1 as file size.

Returns:

Current resource size in bytes, or -1 if Manager can't get this size

Throws:

Exception - If the Manager should be able to get the file size but could not due to an unexpected event (e.g. I/O error, authentication failure, timeout, ...)

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getCurrentFileInfo

public LogFileInfo getCurrentFileInfo()
                               throws Exception

Called periodically by LogMX to get the current file size and date.
This method is not abstract or final, so that most Managers may not have to override (i.e. redefine) it, but some others can. The default implementation returns a LogFileInfo containing the file size and date returned by getCurrentFileSize() and getCurrentFileLastModifDate(). Manager must override this new method if getting the file size and file date are both time-consuming and if they both need a same connection, transaction, context, ... For example, if getting both file size/date can be performed via a single SFTP "STAT" command, the Manager shall override getCurrentFileInfo() so that only one "STAT" command is performed. Note: this method appeared in Manager Specification Version v1.1 is called periodically for file change detection and Auto-Refresh.

Returns:

Information on file (current size and date)

Throws:

Exception - If the Manager should be able to get file info but could not due to an unexpected event (e.g. I/O error, authentication failure, timeout, ...)

Since:

LogMX v1.2.4, Manager Specification Version 1.1 (see ManagerSpecVersion)

readFileHeader

public abstract byte[] readFileHeader(int pNumBytes)
                               throws Exception

Called by LogMX to read the first pNumBytes bytes from the underlying file or resource.
Only Managers supporting Auto Refresh must implement this method, others should return null.

Parameters:

pNumBytes - Number of bytes to read. If negative, Manager must read as much bytes as possible (for example, up to the end of file)

Returns:

Read bytes, or null if Manager doesn't support header reading

Throws:

Exception - If Manager could not read bytes

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

readLineAtOffset

public abstract AutoRefreshLineInfo readLineAtOffset(long pOffset)
                                              throws Exception

Called by LogMX to read the line of text starting at the specified offset.
Only Managers supporting Auto Refresh must implement this method, others should return null.

Parameters:

pOffset - Starting offset

Returns:

Information on read line (text and EOF flag), or null if Manager doesn't support header reading

Throws:

Exception - If Manager could not read bytes

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getCurrentOffset

public abstract long getCurrentOffset()

Called by LogMX to know the current position in file.
Only Managers supporting Auto Refresh must implement this method, others should return 0.

Returns:

Current offset in file

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

supportFileFlush

public abstract boolean supportFileFlush()

Called by LogMX to know if this Manager can flush (i.e. empty) the current file.
If false is returned, LogMX will not call flushFile()

Returns:

true if this Manager can flush the current file, or false if it can't.

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

supportFileDelete

public abstract boolean supportFileDelete()

Called by LogMX to know if this Manager can delete (i.e. remove from disk) the current file.
If false is returned, LogMX will not call deleteFile()

Returns:

true if this Manager can delete the current file, or false if it can't.

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

supportRandomAccess

public abstract boolean supportRandomAccess()

Called by LogMX to know if this Manager support random access (read bytes starting at a specified offset).
Used for Auto Refresh feature only. If false is returned, LogMX will not call readLineAtOffset(long)

Returns:

true if this Manager support random access, or false if it doesn't.

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

supportHeaderReading

public abstract boolean supportHeaderReading()

Called by LogMX to know if this Manager support header reading (read a specified number of bytes from the beginning of the file).
Used for Auto Refresh and Auto detect encoding features. If false is returned, LogMX will not call readFileHeader(int)

Returns:

true if this Manager support header reading, or false if it doesn't.

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getFileTypeIcon

public abstract Icon getFileTypeIcon()

Called by LogMX to get this Manager icon, which must be a 16x16 icon.
Manager may use getIconFile(String) to get an icon file contained in LogMX pictures directory, in order to avoid relative file path issues.
This icon may (should) be cached, the same instance may be returned for each call for better performances.
If null is returned, a default icon will be used.

Returns:

Manager icon (16x16), or null to use a default icon.

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getFileTypeIcon32x32

public Icon getFileTypeIcon32x32()

Called by LogMX to get this Manager icon, which must be a 32x32 icon.
For compatibility reason, this method is not abstract so that exiting user-defined Managers don't have to implement this new method appeared in LogMX v5.2.0. This default implementation calls getFileTypeIcon() so that an icon is retrieved, even if it's smaller (16x16) than expected.

Manager may use getIconFile(String) to get an icon file contained in LogMX pictures directory, in order to avoid relative file path issues.
This icon may (should) be cached, the same instance may be returned for each call for better performances.
If null is returned, a default icon will be used.

Returns:

Manager icon (32x32), or null to use a default icon.

Since:

LogMX v5.2.0, Manager Specification Version 1.2 (see ManagerSpecVersion)

getSpecificationVersion

public abstract ManagerSpecVersion getSpecificationVersion()

Called by LogMX to get the Manager Specification version supported by this Manager. For example, this method can return ManagerSpecVersion.V1_0

Returns:

Supported Manager Specification version

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

newEncodingDetected

public void newEncodingDetected()

Called by LogMX after prepareForReading() and before readLine() if and only if the encoding to use (to read bytes from the underlying resource) has changed.
Managers can get this new encoding using getEncoding().

If the user chose to auto-detect encoding from LogMX GUI, LogMX will perform this auto-detection after the call to prepareForReading(). If the encoding found during this auto-detection is different from the one set while prepareForReading() was called, this method newEncodingDetected() will be called so that the Manager can re-create its Input Stream Reader before readLine() is called.

Default implementation of this method does nothing. A Manager should override this method if it calls getEncoding() in prepareForReading() to initialize its Input Stream Reader, or if the Input Stream Reader used in readFileHeader(int) is also used in readLine()

Since:

LogMX v1.2.4, Manager Specification Version 1.1 (see ManagerSpecVersion)

isLiveStream

public boolean isLiveStream()

Called by LogMX to know if this Manager reads log entries from a live stream (e.g. socket, serial port, ...)
If this Manager reads log entries from a live stream, it shall then extend LogStreamManager.

This default implementation always returns false.

If true is returned, LogMX will consider that this Manager cannot access random locations in its underlying stream (e.g. no rewind, no look-ahead, no file header, ...), so LogMX will not call methods readFileHeader(int), readLineAtOffset(long), getCurrentOffset().

Returns:

true if this Manager reads log entries from a live stream, false if it doesn't.

Since:

LogMX v5.2.0, Manager Specification Version 1.2 (see ManagerSpecVersion)

supportLogEntriesExtraction

public boolean supportLogEntriesExtraction()

Called by LogMX to know if this Manager can extract log entries itself, without the use of any Log Parser (e.g. case of log entries received as a non-textual stream, like when reading a database, or reading binary data).

This default implementation always returns false.

If Manager returns true, LogMX will call readEntry() and getLogEntriesInfoProvider() to make the Manager extract entries.

Returns:

true if this Manager supports log entries extraction, false if it doesn't.

Since:

LogMX v5.2.0, Manager Specification Version 1.2 (see ManagerSpecVersion)

getAutoRefreshDelay

public int getAutoRefreshDelay()

Called by LogMX to know the delay (in ms) to wait between each automatic refresh, for all logs opened with this LogFileManager.

If this method returns -1, then LogMX will use the user settings to determine this delay (in Managers Options, several delays are tunable depending on Manager type: local file, socket, others).

This default implementation always returns -1.

Returns:

Delay (in ms), or -1 to use value given by user settings

Since:

LogMX v5.4.0

readEntry

public ParsedEntry readEntry()
                      throws Exception

Called by LogMX to request the Manager to extract the next log entry.

This default implementation always returns null.

LogMX will call this method only if Manager returned true in supportLogEntriesExtraction(). Note: the Manager shall use createNewEntryForExtraction() to get an instance of ParsedEntry to enrich.

Returns:

Extracted log entry, or null if no entry can be extracted at this time

Throws:

Exception - If the Manager couldn't extract the next log entry

Since:

LogMX v5.2.0, Manager Specification Version 1.2 (see ManagerSpecVersion)

getLogEntriesInfoProvider

public LogEntriesInfoProvider getLogEntriesInfoProvider()

Called by LogMX to request the Manager to provide an object that will enrich extracted log entries (like Parsers do): log entry date conversions, user-defined fields management.

This default implementation always returns null.

LogMX will call this method only if Manager returned true in supportLogEntriesExtraction(). Note: the Manager shall use createNewEntryForExtraction() to get an instance of ParsedEntry to enrich.

Returns:

LogEntriesInfoProvider to be used by LogMX to convert log entry timestamp, and handle user-defined fields

Since:

LogMX v5.2.0, Manager Specification Version 1.2 (see ManagerSpecVersion)

canUseParser

public boolean canUseParser(LogFileParser pParser)

Called by LogMX to know if the given parser can be used to parse the data returned by this LogFileManager.

If this method returns false, then LogMX will not attempt to parse the logs with the given parser when reading content with this LogFileManager.

This default implementation always returns true.

Parameters:

pParser - Parser that LogMX would like to use to parse logs out of this LogFileManager's returned content

Returns:

true if LogMX can attempt to parse logs with the given parser, or false if LogMX should NOT attempt to parse logs with the given parser

Since:

LogMX v8.0.0

getEncoding

public final String getEncoding()

Called by the Manager to get the Encoding to use when reading bytes.
All Managers should call this method to use the right encoding.
The returned string is a valid Java encoding you can use for Java API methods, like:
new InputStreamReader(myStream, getEncoding());

Returns:

Encoding name to use

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getIconFile

public static final Icon getIconFile(String pImageFileName)

Called by the Manager to get the image contained in file named pImageFileName in LogMX "pics/" directory.
The Manager should use this method to avoid relative file path issues.

Parameters:

pImageFileName - File name, without path (e.g. "my_pic.png")

Returns:

Image contained in file pImageFileName

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getURLFromLogURL

public static final String getURLFromLogURL(LogURL pLogURL,
                                            String pURLPattern)

Called by the Manager to construct a string URL from a LogURL and a URL pattern.

Parameters:

pLogURL - LogURL containing parameters and their value

pURLPattern - URL Pattern as described for getURLPattern()

Returns:

URL String

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getOrAskUserPassword

public final char[] getOrAskUserPassword(String pLogin,
                                         String pHost)

Called by the Manager to get a user password saved in LogMX password repository, or by asking the user their password if the password is not saved in LogMX password repository yet.
The password is returned as a char[] for security reasons, so that you can flush it efficiently from memory.

Parameters:

pLogin - User login

pHost - Host to access (used to save a password per host, and per protocol using getProtocolName())

Returns:

User password (char array for security reasons, so that you can flush it efficiently from memory). Method returns null if password couldn't be retrieved from LogMX password repository, or if user dismissed password request dialog.

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (see ManagerSpecVersion)

getProxySettings

public final ProxySettings getProxySettings(String pHost)

Called by the Manager to get the proxy settings to use to connect to a host, according to LogMX user preferences set in LogMX GUI.

Note: the returned object does not contain any password, even if a login/password is set for proxy in LogMX preferences (for security reasons).

Note: since proxy settings also depend on the used protocol (e.g. HTTP, FTP, ...), LogMX gets this protocol by calling getProtocolName() on this Manager.

Parameters:

pHost - Host to access

Returns:

Proxy settings to use for this Manager and given host

Since:

LogMX v4.0.0, Manager Specification Version 1.1 (see ManagerSpecVersion)

getConnectionTimeout

public final int getConnectionTimeout()

Called by the Manager to get the current value (in seconds) for the user setting "Connection timeout", according to LogMX user preferences set in LogMX GUI.

Returns:

Number of seconds before considering an awaiting connection has failed (as set in user preferences)

Since:

LogMX v5.2.0, Manager Specification Version 1.2 (see ManagerSpecVersion)

getDecompressedStream

public final InputStream getDecompressedStream(String pFileName,
                                               InputStream pInputStream)

Called by the Manager to get, if needed, a stream of uncompressed data for the specified logs stream (case of file compressed with ZIP, GZIP or others).
WARNING: As of LogMX v6.0.3, you may want to use getCompressFormatFromFileName(String) and then getDecompressedStream(InputStream, String), instead of this method, because it may be wrong to detect if a decompressed stream is required, after opening an InputStream: if the Manager tries to open this InputStream at an offset different than 0 (e.g. for AutoRefresh or Tail), it will be impossible to construct a decompressed stream from this InputStream (compression algorithms usually need to read the file header before seeking an offset).

If no compression was detected, the specified InputStream is returned.
LogMX will consider a file as compressed if its extension matches an handled compression method (see getCompressFormat()).

Note that user preferences (set in LogMX GUI) can disable all decompression features (see 'General' tab in Options).

The calling Manager should not have to keep a reference to pInputStream: for example, closing the returned stream will also close the specified underlying stream even if it contains compressed data.

Parameters:

pFileName - Log file name (used to recognize compression method in its extension, like .gz, .zip, ...)

pInputStream - Stream used to read logs from. Decompression process will read from this stream.

Returns:

If a known compression method was detected in file name (and user preferences allow decompression), returns a stream that contains the uncompressed data. Else, the specified pInputStream will be returned, as is.

Since:

LogMX v5.2.0, Manager Specification Version 1.2 (see ManagerSpecVersion)

getCompressFormatFromFileName

public final String getCompressFormatFromFileName(String pFileName)

Called by the Manager to know the compression format that should be used for the given file name (guessed from its extension: ZIP, GZIP or others).
If no compression should be used, then null is returned.
LogMX will consider a file as compressed if its extension matches an handled compression method (see getCompressFormat()).

Note that user preferences (set in LogMX GUI) can disable all decompression features (see 'General' tab in Options): in this case, this method returns null.

Parameters:

pFileName - Log file name (used to recognize compression method in its extension, like .gz, .zip, ...)

Returns:

If a known compression method was detected in file name (and user preferences allow decompression), then returns one of the String constants described in Javadoc of getCompressFormat(), otherwise, returns null

Since:

LogMX v6.0.3

getDecompressedStream

public final InputStream getDecompressedStream(InputStream pInputStream,
                                               String pCompressFormat)

Called by the Manager to get, if needed, a stream of uncompressed data for the specified logs stream and specified compression format.
If (pInputStream == null), then the specified InputStream is returned.
Note that user preferences (set in LogMX GUI) can disable all decompression features (see 'General' tab in Options): in this case, the specified InputStream is returned.

The calling Manager should not have to keep a reference to pInputStream: for example, closing the returned stream will also close the specified underlying stream even if it contains compressed data.

Parameters:

pInputStream - Stream used to read logs from. Decompression process will read from this stream.

pCompressFormat - Compression format to use (one of the String constants described in Javadoc of getCompressFormat(), usually obtained from getCompressFormatFromFileName(String))

Returns:

Returns a stream that contains the uncompressed data, or returns the specified InputStream if the given pCompressFormat cannot be used (error while creating decompressed stream, or decompression deactivated in user preferences).

Since:

LogMX v6.0.3

getCompressFormat

public final String getCompressFormat()

Called by the Manager to get the name of the compression method that was detected during previous call to getCompressFormatFromFileName(String) and getDecompressedStream(InputStream, String).
If the input stream was not considered as compressed, it will return null.

The possible values that can be returned are:

• "ZIP"
• "GZIP"
• "TAR-GZIP"
• "BZ2"
• "TAR-BZ2"
• "LZMA"
• "TAR-LZMA"
• "XZ"
• "TAR-XZ"
• "ZLIB"

Returns:

Returns the name of the compression method that was detected during previous call to getCompressFormatFromFileName(String) and getDecompressedStream(InputStream, String), or null if the input stream was not considered as compressed (or if getCompressFormatFromFileName(String) was not called yet)

Since:

LogMX v5.2.0, Manager Specification Version 1.2 (see ManagerSpecVersion)

createNewEntryForExtraction

protected final ParsedEntry createNewEntryForExtraction()

Called by the Manager to create and return a new blank log entry to be used by this Manager during entry extraction (see supportLogEntriesExtraction()).

Managers should not try to directly create entries instead of calling this method.

Returns:

New blank Entry to be used by the Manager

Since:

LogMX v5.2.0, Manager Specification Version 1.2 (see ManagerSpecVersion)