com.isti.util
Class LogFile

java.lang.Object
  com.isti.util.logging.AbstractIstiLogger
      com.isti.util.logging.IstiConsoleLogger
          com.isti.util.LogFile

All Implemented Interfaces:

com.isti.util.logging.IstiLogger

public class LogFile
extends com.isti.util.logging.IstiConsoleLogger

Class LogFile provides log file output services. The 'initLogObj()' and 'getLogObj()' functions support the use of a single "global" log file object. Other "local" log file objects may also be created and used. Each log message is received with one of the the following message levels: ERROR - An error which causes the program to abort. WARNING - An unexpected condition, but the program continues. INFO - An informational message. DEBUG - A debug message, for developers only. DEBUG2-5 - Debug messages of increasing detail, for developers only. The console and log file outputs are configurable such that only messages at or beyond a set message level are retained. The message level is shown on each output message, and the date & time are shown on each message sent to the log file. Options are available for adding a date code to the filename and creating new log files as the date code changes, as well as automatic deletion of old log files.

Field Summary

static boolean	DEFAULT_GMT_FLAG Default for 'gmtFlag'.
static boolean	DEFAULT_USE_DATE_IN_FNAME_FLAG Default for 'useDateInFnameFlag'.
static java.lang.String	FILE_DATE_PATTERNSTR Pattern string for "file" date formatter ("yyyyMMdd").
static java.lang.String	FNAME_DATE_SEPSTR Separator used between file name and date code ("_").
static java.lang.String	LONG_DATE_PATTERNSTR Pattern string for "long" date formatter ("MMMM dd, yyyy HH:mm:ss z").
static int	NO_LEVEL A message level value used to specify that no log-level indicator is to be output with the message (998).
static java.lang.String	SHORT_DATE_PATTERNSTR Pattern string for "short" date formatter ("MMM dd yyyy HH:mm:ss").

Fields inherited from interface com.isti.util.logging.IstiLogger

ALL_MSGS, ALL_MSGS_STR, DEBUG, DEBUG_STR, DEBUG2, DEBUG2_STR, DEBUG3, DEBUG3_STR, DEBUG4, DEBUG4_STR, DEBUG5, DEBUG5_STR, ERROR, ERROR_STR, INFO, INFO_STR, NO_MSGS, NO_MSGS_STR, WARNING, WARNING_STR

Constructor Summary

LogFile(java.lang.String fName, int logFileLevel, int consoleLevel)
Creates a new LogFile object, using the local timezone for timestamps.

LogFile(java.lang.String fName, int logFileLevel, int consoleLevel, boolean gmtFlag)
Creates a new LogFile object.

LogFile(java.lang.String fName, int logFileLevel, int consoleLevel, boolean gmtFlag, boolean useDateInFnameFlag)
Creates a new LogFile object.

LogFile(java.lang.String fName, int logFileLevel, int consoleLevel, boolean gmtFlag, boolean useDateInFnameFlag, boolean writeHdrFdrFlag)
Creates a new LogFile object.

Method Summary

void	addTrackedMsgListener(DataChangedListener listenerObj) Adds the given tracked-message listener.
void	close() Closes the log file.
static LogFile	getConsoleLogObj() Gets a handle to the console log file object.
java.text.DateFormat	getDateFormat() Gets the date formatter for log file entries.
java.lang.String	getFileName() Returns the current log file name in use.
static LogFile	getGlobalLogObj() Gets a handle to the "global" log file object.
static LogFile	getGlobalLogObj(boolean consoleFlag) Gets a handle to the "global" log file object.
static java.lang.String[]	getLevelNamesArray() Returns an array containing all the valid log-level name strings.
static java.lang.String	getLevelNamesDisplayStr() Returns an array containing all the valid log-level name strings.
static java.util.Vector	getLevelNamesVector() Returns a Vector containing all the valid log-level name strings.
int	getLogFileLevel() Gets the current level for log file output messages.
LogOutputStream	getLogOutputStream() Returns an 'OutputStream' object whose output is directed to this log file.
int	getMaxLogFileAge() Gets the maximum log file age.
protected java.lang.String	getMessage(int level) Gets the message for the level.
int	getMinLevel() Get the minimum level for all output messages.
static LogFile	getNullLogObj() Gets a handle to the null log file object.
java.lang.String[]	getTrackedMessages() Returns an array of strings containing the tracked messages.
java.lang.String[]	getTrackedMessages(int maxAgeMs) Returns an array of strings containing the tracked messages.
java.lang.String	getTrackedMsgsAsString(java.lang.String sepStr) Returns a string containing the tracked messages.
java.lang.String	getTrackedMsgsAsString(java.lang.String sepStr, int maxAgeMs) Returns a string containing the tracked messages.
static LogFile	initGlobalLogObj(LogFile logObj) Initializes the "global" log file object.
static LogFile	initGlobalLogObj(java.lang.String fName, int logFileLevel, int consoleLevel) Initializes the "global" log file object, using the local timezone for timestamps.
static LogFile	initGlobalLogObj(java.lang.String fName, int logFileLevel, int consoleLevel, boolean gmtFlag) Initializes the "global" log file object.
static LogFile	initGlobalLogObj(java.lang.String fName, int logFileLevel, int consoleLevel, boolean gmtFlag, boolean useDateInFnameFlag) Initializes the "global" log file object.
boolean	isOpen() Determines if the log file is open.
protected boolean	logMessage(int level, java.lang.String str, java.lang.Throwable t) Sends the given string to the log file.
boolean	println(java.lang.String str) Sends the given string to the log file.
void	removeTrackedMsgListener(DataChangedListener listenerObj) Removes the given tracked-message listener.
void	setLogFileLevel(int level) Sets the current level for console output messages.
void	setLogFileSwitchIntervalDays(int numDays) Sets the minimum number of days between log file switches via date changes.
void	setMaxLogFileAge(int maxAge) Sets the maximum log file age, in days.
void	setupMessageTracking(int msgLevel, int msgCount) Sets up message tracking.
void	setWriteDatePrefixFlag(boolean flgVal) Sets whether or not a date-code prefix is inserted before each entry in the log file.

Methods inherited from class com.isti.util.logging.IstiConsoleLogger

getConsoleLevel, getConsoleOutput, setConsoleLevel, setConsoleOutput

Methods inherited from class com.isti.util.logging.AbstractIstiLogger

debug, debug2, debug3, debug4, debug5, error, error, getLevelString, getLevelStringNull, getMessage, getMessage, info, isLoggable, levelStringToValue, println, println, warning

Methods inherited from class java.lang.Object

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

Field Detail

NO_LEVEL

public static final int NO_LEVEL

A message level value used to specify that no log-level indicator is to be output with the message (998). May be used with the 'println(level,msg)' method.

See Also:

Constant Field Values

DEFAULT_GMT_FLAG

public static final boolean DEFAULT_GMT_FLAG

Default for 'gmtFlag'.

See Also:

Constant Field Values

DEFAULT_USE_DATE_IN_FNAME_FLAG

public static final boolean DEFAULT_USE_DATE_IN_FNAME_FLAG

Default for 'useDateInFnameFlag'.

See Also:

Constant Field Values

FNAME_DATE_SEPSTR

public static final java.lang.String FNAME_DATE_SEPSTR

Separator used between file name and date code ("_").

See Also:

Constant Field Values

FILE_DATE_PATTERNSTR

public static final java.lang.String FILE_DATE_PATTERNSTR

Pattern string for "file" date formatter ("yyyyMMdd").

See Also:

Constant Field Values

SHORT_DATE_PATTERNSTR

public static final java.lang.String SHORT_DATE_PATTERNSTR

Pattern string for "short" date formatter ("MMM dd yyyy HH:mm:ss").

See Also:

Constant Field Values

LONG_DATE_PATTERNSTR

public static final java.lang.String LONG_DATE_PATTERNSTR

Pattern string for "long" date formatter ("MMMM dd, yyyy HH:mm:ss z").

See Also:

Constant Field Values

Constructor Detail

LogFile

public LogFile(java.lang.String fName,
               int logFileLevel,
               int consoleLevel,
               boolean gmtFlag,
               boolean useDateInFnameFlag,
               boolean writeHdrFdrFlag)

Creates a new LogFile object.

Parameters:

fName - log file name to use (if a path name then any needed parent directories will be created), or null for none.

logFileLevel - minimum level of messages to send to the log file, such as NO_MSGS, INFO, etc.

consoleLevel - minimum level of messages to send to the console, such as NO_MSGS, INFO, etc.

gmtFlag - true to use GMT for timestamps, false to use the local timezone.

useDateInFnameFlag - true to use the date in the file name (and create a new log file everytime the date changes).

writeHdrFdrFlag - true to write header and footer messages to log file; false for no header and footer messages.

LogFile

public LogFile(java.lang.String fName,
               int logFileLevel,
               int consoleLevel,
               boolean gmtFlag,
               boolean useDateInFnameFlag)

Creates a new LogFile object.

Parameters:

fName - log file name to use (if a path name then any needed parent directories will be created), or null for none.

logFileLevel - minimum level of messages to send to the log file, such as NO_MSGS, INFO, etc.

consoleLevel - minimum level of messages to send to the console, such as NO_MSGS, INFO, etc.

gmtFlag - true to use GMT for timestamps, false to use the local timezone.

useDateInFnameFlag - true to use the date in the file name (and create a new log file everytime the date changes).

LogFile

public LogFile(java.lang.String fName,
               int logFileLevel,
               int consoleLevel,
               boolean gmtFlag)

Creates a new LogFile object.

Parameters:

fName - log file name to use (if a path name then any needed parent directories will be created).

logFileLevel - minimum level of messages to send to the log file, such as NO_MSGS, INFO, etc.

consoleLevel - minimum level of messages to send to the console, such as NO_MSGS, INFO, etc.

gmtFlag - true to use GMT for timestamps, false to use the local timezone.

LogFile

public LogFile(java.lang.String fName,
               int logFileLevel,
               int consoleLevel)

Creates a new LogFile object, using the local timezone for timestamps.

Parameters:

fName - log file name to use (if a path name then any needed parent directories will be created).

logFileLevel - minimum level of messages to send to the log file, such as NO_MSGS, INFO, etc.

consoleLevel - minimum level of messages to send to the console, such as NO_MSGS, INFO, etc.

Method Detail

getMaxLogFileAge

public int getMaxLogFileAge()

Gets the maximum log file age.

Returns:

the maximum age (in days) or 0 if disabled.

setMaxLogFileAge

public void setMaxLogFileAge(int maxAge)

Sets the maximum log file age, in days. If 'useDateInFnameFlag' is enabled then anytime a new log file name is put into use, any matching log files older than the given number of days are deleted. If 'useDateInFnameFlag' is not enabled then old log files will not be deleted. Note also that when this method is called, any matching log files older than the given age are deleted immediatedly (if 'useDateInFnameFlag' is enabled.)

Parameters:

maxAge - maximum age (in days) or 0 to disable.

setLogFileSwitchIntervalDays

public void setLogFileSwitchIntervalDays(int numDays)

Sets the minimum number of days between log file switches via date changes. This setting only has an effect if the log file was constructed with the 'useDateInFnameFlag' parameter set to 'true'. The default value is 1 day.

Parameters:

numDays - if > 0 then the minimum number of days between log file switches; otherwise the log file switching feature is disabled.

setWriteDatePrefixFlag

public void setWriteDatePrefixFlag(boolean flgVal)

Sets whether or not a date-code prefix is inserted before each entry in the log file.

Parameters:

flgVal - true to have a date-code prefix inserted before each entry in the log file; false for not.

setupMessageTracking

public void setupMessageTracking(int msgLevel,
                                 int msgCount)

Sets up message tracking. The 'getTrackedMessages()' method will return the last 'msgCount' number of messages with a message level of 'msgLevel' or greater.

Parameters:

msgLevel - minimum message level to be tracked, or NO_MSGS for none.

msgCount - number of messages to be tracked.

getTrackedMessages

public java.lang.String[] getTrackedMessages(int maxAgeMs)

Returns an array of strings containing the tracked messages. See the 'setupMessageTracking()' method for details.

Parameters:

maxAgeMs - maximum age (in milliseconds) of messages returned, or 0 for all messages.

Returns:

An array of strings containing the tracked messages, or null if message tracking is not set up.

getTrackedMessages

public java.lang.String[] getTrackedMessages()

Returns an array of strings containing the tracked messages. See the 'setupMessageTracking()' method for details.

Returns:

An array of strings containing the tracked messages, or null if message tracking is not set up.

getTrackedMsgsAsString

public java.lang.String getTrackedMsgsAsString(java.lang.String sepStr,
                                               int maxAgeMs)

Returns a string containing the tracked messages. See the 'setupMessageTracking()' method for details.

Parameters:

sepStr - separator to be placed between each item.

maxAgeMs - maximum age (in milliseconds) of messages returned, or 0 for all messages.

Returns:

A string containing the tracked messages, or null if message tracking is not set up.

getTrackedMsgsAsString

public java.lang.String getTrackedMsgsAsString(java.lang.String sepStr)

Returns a string containing the tracked messages. See the 'setupMessageTracking()' method for details.

Parameters:

sepStr - separator to be placed between each item.

Returns:

A string containing the tracked messages, or null if message tracking is not set up.

addTrackedMsgListener

public void addTrackedMsgListener(DataChangedListener listenerObj)

Adds the given tracked-message listener. The listener's 'dataChanged()' method is called whenever a new log message is tracked.

Parameters:

listenerObj - the 'DataChangedListener' object to be added.

removeTrackedMsgListener

public void removeTrackedMsgListener(DataChangedListener listenerObj)

Removes the given tracked-message listener.

Parameters:

listenerObj - the 'DataChangedListener' object to be removed.

logMessage

protected boolean logMessage(int level,
                             java.lang.String str,
                             java.lang.Throwable t)

Sends the given string to the log file. (And possibly the console--see the 'consoleLevel' parameter on the constructor.)

Overrides:

logMessage in class com.isti.util.logging.IstiConsoleLogger

Parameters:

level - the message level to be used, or NO_LEVEL for none.

str - the string to be outputted.

t - Throwable associated with a log message or null if none.

Returns:

true if successful, false if an I/O error was detected.

See Also:

AbstractIstiLogger.getMessage(String, Throwable)

getMessage

protected java.lang.String getMessage(int level)

Gets the message for the level.

Overrides:

getMessage in class com.isti.util.logging.AbstractIstiLogger

Parameters:

level - the message level.

Returns:

the message.

println

public boolean println(java.lang.String str)

Sends the given string to the log file. (And possibly the console--see the 'consoleLevel' parameter on the constructor.) A log-level indicator is not included in the output.

Specified by:

println in interface com.isti.util.logging.IstiLogger

Overrides:

println in class com.isti.util.logging.AbstractIstiLogger

Parameters:

str - the string to be outputted.

Returns:

true if successful, false if an I/O error was detected.

close

public void close()

Closes the log file.

getLogOutputStream

public LogOutputStream getLogOutputStream()

Returns an 'OutputStream' object whose output is directed to this log file.

Returns:

A new 'LogOutputStream' object associated with this log file.

getFileName

public java.lang.String getFileName()

Returns the current log file name in use.

Returns:

The log file name, or null if an error occurred.

isOpen

public boolean isOpen()

Determines if the log file is open.

Returns:

true if the log file is open.

getLogFileLevel

public int getLogFileLevel()

Gets the current level for log file output messages. (See the 'logFileLevel' parameter on the constructor.)

Returns:

the current level for log file output messages

getMinLevel

public int getMinLevel()

Get the minimum level for all output messages.

Overrides:

getMinLevel in class com.isti.util.logging.IstiConsoleLogger

Returns:

the minimum level for all output messages.

See Also:

AbstractIstiLogger.isLoggable(int)

setLogFileLevel

public void setLogFileLevel(int level)

Sets the current level for console output messages. (See the 'logFileLevel' parameter on the constructor.)

Parameters:

level - the log file level to be used.

getLevelNamesVector

public static java.util.Vector getLevelNamesVector()

Returns a Vector containing all the valid log-level name strings.

Returns:

A Vector of String objects.

getLevelNamesArray

public static java.lang.String[] getLevelNamesArray()

Returns an array containing all the valid log-level name strings.

Returns:

An array of String objects.

getLevelNamesDisplayStr

public static java.lang.String getLevelNamesDisplayStr()

Returns an array containing all the valid log-level name strings.

Returns:

An array of String objects.

initGlobalLogObj

public static LogFile initGlobalLogObj(LogFile logObj)

Initializes the "global" log file object. This function would be used by a program's "main" module to establish a "global" log file. Other modules can then get a handle to the "global" log file via the 'getGlobalLogObj()' function.

Parameters:

logObj - the log file object.

Returns:

A handle to the "global" log file object.

initGlobalLogObj

public static LogFile initGlobalLogObj(java.lang.String fName,
                                       int logFileLevel,
                                       int consoleLevel,
                                       boolean gmtFlag,
                                       boolean useDateInFnameFlag)

Initializes the "global" log file object. This function would be used by a program's "main" module to establish a "global" log file. Other modules can then get a handle to the "global" log file via the 'getGlobalLogObj()' function.

Parameters:

fName - log file name to use (if a path name then any needed parent directories will be created).

consoleLevel - minimum level of messages to send to the console, such as NO_MSGS, INFO, etc.

logFileLevel - minimum level of messages to send to the log file, such as NO_MSGS, INFO, etc.

gmtFlag - true to use GMT for timestamps, false to use the local timezone.

useDateInFnameFlag - true to use the date in the file name (and create a new log file everytime the date changes).

Returns:

A handle to the "global" log file object.

initGlobalLogObj

public static LogFile initGlobalLogObj(java.lang.String fName,
                                       int logFileLevel,
                                       int consoleLevel,
                                       boolean gmtFlag)

Initializes the "global" log file object. This function would be used by a program's "main" module to establish a "global" log file. Other modules can then get a handle to the "global" log file via the 'getGlobalLogObj()' function.

Parameters:

fName - log file name to use (if a path name then any needed parent directories will be created).

consoleLevel - minimum level of messages to send to the console, such as NO_MSGS, INFO, etc.

logFileLevel - minimum level of messages to send to the log file, such as NO_MSGS, INFO, etc.

gmtFlag - true to use GMT for timestamps, false to use the local timezone.

Returns:

A handle to the "global" log file object.

initGlobalLogObj

public static LogFile initGlobalLogObj(java.lang.String fName,
                                       int logFileLevel,
                                       int consoleLevel)

Initializes the "global" log file object, using the local timezone for timestamps. This function would be used by a program's "main" module to establish a "global" log file. Other modules can then get a handle to the "global" log file via the 'getGlobalLogObj()' function.

Parameters:

fName - log file name to use (if a path name then any needed parent directories will be created).

consoleLevel - minimum level of messages to send to the console, such as NO_MSGS, INFO, etc.

logFileLevel - minimum level of messages to send to the log file, such as NO_MSGS, INFO, etc.

Returns:

A handle to the "global" log file object.

getGlobalLogObj

public static LogFile getGlobalLogObj()

Gets a handle to the "global" log file object. A program's "main" module would establish a "global" log file via the 'initGlobalLogObj()' function. Other modules can then get a handle to the "global" log file via this function. If 'initGlobalLogObj()' was not called previously then a "global" log file named "default.log" will be created and used.

Returns:

A handle to the "global" log file object.

getGlobalLogObj

public static LogFile getGlobalLogObj(boolean consoleFlag)

Gets a handle to the "global" log file object. A program's "main" module would establish a "global" log file via the 'initGlobalLogObj()' function. Other modules can then get a handle to the "global" log file via this function. If 'initGlobalLogObj()' was not called previously then either a null log file that does nothing or a console log file is returned.

Parameters:

consoleFlag - true to return a console log file if 'initGlobalLogObj()' was not called previously, otherwise a null log file is returned. NOTE: Console output should be limited to messages that will be displayed infrequently.

Returns:

A handle to the "global" log file object.

getConsoleLogObj

public static LogFile getConsoleLogObj()

Gets a handle to the console log file object.

Returns:

A handle to the console log file object.

getNullLogObj

public static LogFile getNullLogObj()

Gets a handle to the null log file object.

Returns:

A handle to the null log file object.

getDateFormat

public java.text.DateFormat getDateFormat()

Gets the date formatter for log file entries.

Returns:

the date formatter for log file entries.