org.safs
Class Log

java.lang.Object
  org.safs.Log

public class Log
extends java.lang.Object

SAFS Debug Log

This class provides an independent logging capability available to both Java and non-Java SAFS clients. Non-Java clients will write to this log through STAF using the STAF QUEUE of a registered "SAFS/TESTLOG" client of this class. Java clients will simply write to the static methods of this Log class.

The class is intended to act as a development, debugging, and troubleshooting log allowing SAFS clients to write detailed information to this separate log that will not clutter the normal log output during production testing.

Typical usage of this class requires the following steps:

1. STAF must be running. Start STAF if necessary.
   !!! DO NOT SHUTDOWN STAF UNTIL AFTER YOU HAVE SHUTDOWN THIS DEBUG LOG !!!

2. Launch the debug Log as a standalone application:
   Example debug Log invocations:

   a) java org.safs.Log

   b) java org.safs.Log 1

   c) java org.safs.Log INFO

   d) java org.safs.Log -file:c:/safs/data/debuglog.txt

   e) java org.safs.Log DEBUG -file:c:/safs/data/debuglog.txt

   Example (a) shows launching the debug Log with the default DEBUG log level.
   Examples (b) and (c) are examples launching the debug Log with the INFO log level.

   The static main method will launch the debug console and receive 'logmsg' messages on it's STAF QUEUE.

3. Java classes call the appropriate static methods to write to the open debug log. The public methods (debug/info/generic/pass/warn/error) are provided to do logging during Java development/maintenance/debugging of the code when the SAFSLOGS service is not being used.

   Some log levels, like INFO and INDEX, will always log to this class since they are ONLY used during development/maintenance and will never be written to SAFSLOGS. The org.safs.logging.LogUtilities class can also be enabled to forward messages to this class, if that is desirable.

   The internal 'message' method will first try to send using STAF using the 'logmsg' method, if that fails, then it will simply do a System.out.println.

4. Non-Java STAF clients:
   Any STAF client wishing to send a message to this debug log will send a specially formatted STAF QUEUE service message like this:
   QUEUE NAME SAFS/TESTLOG MESSAGE "<formatted_message>"

   The formatted_message is expected to be in the following format:

   "n|message"
   where 'n' is the loglevel intended for this message.
   • 0 = DEBUG
   • 1 = INFO
   • 2 = INDEX
   • 3 = GENERIC
   • 4 = PASS
   • 5 = WARN
   • 6 = ERROR

The debug Log has some special reserved messages:

SHUTDOWN: used to shutdown this static main log
CLS: used to clear lines to separate log sessions. Also clears and restarts any file log.
LEVELn: change the log level (n=0 to 6)
LEVELdebug : change the log level (0:DEBUG)
LEVELinfo : change the log level (1:INFO)
LEVELindex : change the log level (2:INDEX)
LEVELgeneric : change the log level (3:GENERIC)
LEVELpass : change the log level (4:PASS)
LEVELwarn : change the log level (5:WARN)
LEVELerror : change the log level (6:ERROR)
HELP : list HELP text
LIST : list HELP text

So, in order to change the level to WARN, do this:

staf local queue queue name SAFS/TESTLOG message LEVEL5

OR

staf local queue queue name SAFS/TESTLOG message LEVELwarn

And to shutdown the debug Log, do this:

staf local queue queue name SAFS/TESTLOG message SHUTDOWN

Since:

JUN 03, 2003
AUG 01, 2003 (DBauman) Original Release
Aug 01, 2003 (Carl Nagle) Added GENERIC log level between INFO and PASS.
Sep 02, 2003 (DBauman) Added INDEX log level between INFO and GENERIC to give and indication of the index= levels used for recognition strings
Sep 16, 2003 (Carl Nagle) Removed references to defunct org.safs.LogUtilities
JUL 01, 2004 (Carl Nagle) Lotsa cleanup and user-friendly additions.
AUG 12, 2004 (Carl Nagle) Added file output option.
NOV 05, 2004 (Carl Nagle) Log.class disabled by default for performance.
APR 15, 2005 (Carl Nagle) Removed static initialization System.err.println
APR 15, 2005 (Carl Nagle) Added some clarifying documentation for non-Java clients writing to this log. Improved the displayed HELP accordingly.
JAN 08, 2007 (Carl Nagle) Added more clarifying documentation.
JUL 30, 2009 (Carl Nagle) Added Output Filename to debug console at startup.

Field Summary

static int	DEBUG "0" DEBUG log level.
static boolean	ENABLED Enables/Disables the use of this class for performance reasons.
static int	ERROR "6" ERROR log level.
static int	GENERIC "3" GENERIC log level.
static int	INDEX "2" INDEX log level.
static int	INFO "1" INFO log level.
protected static java.lang.String	log_processname
static int	PASS "4" PASS log level.
static java.lang.String	SAFS_TESTLOG_CLIENT "SAFSTESTLOGClient" -- registered STAF Process name for other JVM/processes.
static java.lang.String	SAFS_TESTLOG_CLS "CLS" -- Command to clear lines in the debug console to separate logging sessions.
static java.lang.String	SAFS_TESTLOG_FILE "-file:" -- Command-line prefix to enable output to file.
static java.lang.String	SAFS_TESTLOG_HELP "HELP" -- Command to show the Help info in the debug console.
static java.lang.String	SAFS_TESTLOG_LEVEL "LEVEL" -- root command for setting the log level.
static java.lang.String	SAFS_TESTLOG_LIST "LIST" -- Command to show the Help info in the debug console.
static java.lang.String	SAFS_TESTLOG_PROCESS "SAFS/TESTLOG" - registered STAF Process name for the primary debug console.
static java.lang.String	SAFS_TESTLOG_SHUTDOWN "SHUTDOWN" -- Command to close the debug console and unregister with STAF.
static java.lang.String	SAFS_TESTLOG_VARIABLE "SAFS/TESTLOG/MSG" -- SAFSVARS variable to monitor sent messages.
protected static java.lang.String[]	strlevel
static int	WARN "5" WARN log level.

Constructor Summary

Log()

Method Summary

static void	close() Doesn't do anything.
static void	debug(java.lang.Object msg)
static void	debug(java.lang.Object msg, java.lang.Exception ex)
static void	error(java.lang.Object msg)
static void	error(java.lang.Object msg, java.lang.Exception ex)
static void	generic(java.lang.Object msg)
static java.lang.String	getHelp() Returns the Help text seen in the SAFS/TESTLOG console.
static int	getLogLevel()
protected static int	getStrLevel(java.lang.String slevel) Parse a string log level into its equivalent int log level value.
static void	index(java.lang.Object msg)
static void	info(java.lang.Object msg)
static void	info(java.lang.Object msg, java.lang.Exception ex)
static void	main(java.lang.String[] args) Run standalone to activate the debug console.
static void	message(int local, java.lang.Object msg) Purpose: logs using 'logmsg' if that fails, then does System.out.println.
static void	pass(java.lang.Object msg)
static void	setDoLogMsg(boolean _doLogMsg)
static void	setHelper(STAFHelper aHelper)
static void	setLogLevel(int loglevel)
static void	setLogProcessName(java.lang.String _processName) Used to preset a Log processName prior to any STAFHelper initialization.
static void	warn(java.lang.Object msg)

Methods inherited from class java.lang.Object

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

Field Detail

ENABLED

public static boolean ENABLED

Enables/Disables the use of this class for performance reasons.

SAFS_TESTLOG_PROCESS

public static final java.lang.String SAFS_TESTLOG_PROCESS

"SAFS/TESTLOG" - registered STAF Process name for the primary debug console.

See Also:

Constant Field Values

SAFS_TESTLOG_CLIENT

public static final java.lang.String SAFS_TESTLOG_CLIENT

"SAFSTESTLOGClient" -- registered STAF Process name for other JVM/processes. Must not have exact root name (SAFS/TESTLOG) as the primary process or the STAFHelper.isToolAvailable function will return erroneous 'true'.

See Also:

Constant Field Values

SAFS_TESTLOG_VARIABLE

public static final java.lang.String SAFS_TESTLOG_VARIABLE

"SAFS/TESTLOG/MSG" -- SAFSVARS variable to monitor sent messages.

See Also:

Constant Field Values

SAFS_TESTLOG_SHUTDOWN

public static final java.lang.String SAFS_TESTLOG_SHUTDOWN

"SHUTDOWN" -- Command to close the debug console and unregister with STAF.

See Also:

Constant Field Values

SAFS_TESTLOG_CLS

public static final java.lang.String SAFS_TESTLOG_CLS

"CLS" -- Command to clear lines in the debug console to separate logging sessions.

See Also:

Constant Field Values

SAFS_TESTLOG_LEVEL

public static final java.lang.String SAFS_TESTLOG_LEVEL

"LEVEL" -- root command for setting the log level.

See Also:

Constant Field Values

SAFS_TESTLOG_LIST

public static final java.lang.String SAFS_TESTLOG_LIST

"LIST" -- Command to show the Help info in the debug console.

See Also:

Constant Field Values

SAFS_TESTLOG_HELP

public static final java.lang.String SAFS_TESTLOG_HELP

"HELP" -- Command to show the Help info in the debug console.

See Also:

Constant Field Values

SAFS_TESTLOG_FILE

public static final java.lang.String SAFS_TESTLOG_FILE

"-file:" -- Command-line prefix to enable output to file.

See Also:

Constant Field Values

DEBUG

public static final int DEBUG

"0" DEBUG log level.

See Also:

Constant Field Values

INFO

public static final int INFO

"1" INFO log level.

See Also:

Constant Field Values

INDEX

public static final int INDEX

"2" INDEX log level.

See Also:

Constant Field Values

GENERIC

public static final int GENERIC

"3" GENERIC log level.

See Also:

Constant Field Values

PASS

public static final int PASS

"4" PASS log level.

See Also:

Constant Field Values

WARN

public static final int WARN

"5" WARN log level.

See Also:

Constant Field Values

ERROR

public static final int ERROR

"6" ERROR log level.

See Also:

Constant Field Values

strlevel

protected static final java.lang.String[] strlevel

log_processname

protected static java.lang.String log_processname

Constructor Detail

Log

public Log()

Method Detail

getStrLevel

protected static int getStrLevel(java.lang.String slevel)

Parse a string log level into its equivalent int log level value.

Returns:

-1 if not a match, otherwise, 0 thru 6--the available log levels.

setLogLevel

public static void setLogLevel(int loglevel)

getLogLevel

public static int getLogLevel()

setDoLogMsg

public static void setDoLogMsg(boolean _doLogMsg)

message

public static void message(int local,
                           java.lang.Object msg)

Purpose: logs using 'logmsg' if that fails, then does System.out.println. the format is [LEVEL: message], where LEVEL is one of DEBUG, INFO, INDEX, GENERIC, PASS, WARN, or ERROR.

Parameters:

local, - int

msg, - Object, message to send (.toString() is used)

debug

public static void debug(java.lang.Object msg)

info

public static void info(java.lang.Object msg)

index

public static void index(java.lang.Object msg)

generic

public static void generic(java.lang.Object msg)

pass

public static void pass(java.lang.Object msg)

warn

public static void warn(java.lang.Object msg)

error

public static void error(java.lang.Object msg)

error

public static void error(java.lang.Object msg,
                         java.lang.Exception ex)

info

public static void info(java.lang.Object msg,
                        java.lang.Exception ex)

debug

public static void debug(java.lang.Object msg,
                         java.lang.Exception ex)

close

public static void close()

Doesn't do anything.

getHelp

public static java.lang.String getHelp()

Returns the Help text seen in the SAFS/TESTLOG console.

main

public static void main(java.lang.String[] args)

Run standalone to activate the debug console. used for development/debugging log messages.

Accepts a command line argument that allows you to specify the initial log level. The format is strictly the numeric log level ("0" thru "6") or the equivalent text ("debug" thru "error").

Examples:

java org.safs.Log

java org.safs.Log 1

java org.safs.Log INFO

Also accepts a command line argument to write log messages to file.

Examples:

java org.safs.Log -file:afilepath

And, of course, both command-line arguments can be used in the same call.

setHelper

public static void setHelper(STAFHelper aHelper)

setLogProcessName

public static void setLogProcessName(java.lang.String _processName)

Used to preset a Log processName prior to any STAFHelper initialization.

Parameters:

_processName -