com.lightysoft.logmx.mgr
Class LogFileManager

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

public abstract class LogFileManager
extends Object

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 a Manager reading log content from an Oracle DB, POP3, FTP, or anything else.

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

Managers should not have a Constructor. If you define a Constructor, don't 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 Manager:

1. Calls init(LogURL, String)
2. Calls getCurrentURL()
3. Calls setEncoding(String)
4. Calls prepareForReading()
5. Calls readLine() until it returns null
6. Calls getCurrentFileLastModifDate() periodically (through getCurrentFileInfo())
7. Calls getCurrentFileSize() periodically (through getCurrentFileInfo())
8. 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)

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

• Manager development guide: http://www.logmx.com/p_manager_dev.php
• Manager implementation example: "managers/src" directory of your LogMX distribution
• Manager development forum: http://www.logmx.com/forum/viewforum.php?f=2

Since:

LogMX v1.2.2, Manager Specification Version 1.0

Author:

LightySoft

See Also:

ManagerSpecVersion

Field Summary

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

LogFileManager()
Default constructor.

Method Summary

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.
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.
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.
static Icon	getIconFile(String pImageFileName) Called by the Manager to get the image contained in file named pImageFileName in LogMX "pics/" directory.
abstract String	getName() Called by LogMX to get the name of this Manager.
String	getOrAskUserPassword(String pLogin, String pHost) Called by the Manager to get a user password saved in LogMX password repository, or by asking the user his 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.
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.
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).
abstract byte[]	readFileHeader(int pNbBytes) Called by LogMX to read the first pNbBytes 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 Manger can delete (i.e. remove from disk) the current file.
abstract boolean	supportFileFlush() Called by LogMX to know if this Manger 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).
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://www.logmx.com:80/myscript.php?p=4
• http://www.logmx.com:80/mypage.html
• http://www.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 shouldn't try to open the resource yet, but should only save URL parameters for further use.

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 won't 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. As 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 couldn't 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)

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()

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, it may return 0, but file-change detection will be affected.

Returns:

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

Since:

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

getCurrentFileSize

public abstract long getCurrentFileSize()

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 timestamp, it may return -1, but file-change detection will be affected.

Returns:

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

Since:

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

getCurrentFileInfo

public LogFileInfo getCurrentFileInfo()

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)

Since:

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

readFileHeader

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

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

Parameters:

pNbBytes - 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 Manger 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 Manger 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, or null to use a default icon.

Since:

LogMX v1.2.2, Manager Specification Version 1.0 (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)

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 String getOrAskUserPassword(String pLogin,
                                         String pHost)

Called by the Manager to get a user password saved in LogMX password repository, or by asking the user his password if the password is not saved in LogMX password repository yet.

Parameters:

pLogin - User login

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

Returns:

User password

Since:

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