com.isti.util
Class LogFile

java.lang.Object
  extended by com.isti.util.logging.AbstractIstiLogger
      extended by com.isti.util.logging.IstiConsoleLogger
          extended by com.isti.util.LogFile
All Implemented Interfaces:
IstiLogger

public class LogFile
extends 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 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 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 IstiLogger
Overrides:
println in class 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 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.