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)
SUSPEND : Suspend debug log recording
RESUME : Resume devug log recording
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

Author:

Doug Bauman

Field Summary

Fields

Modifier and Type	Field and Description
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.
(package private) static int	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_RESUME "RESUME" -- Command to RESUME debug logging.
static java.lang.String	SAFS_TESTLOG_SHUTDOWN "SHUTDOWN" -- Command to close the debug console and unregister with STAF.
static java.lang.String	SAFS_TESTLOG_SUSPEND "SUSPEND" -- Command to SUSPEND debug logging temporarily.
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

Constructors

Constructor and Description
Log()

Method Summary

Modifier and Type	Method and Description
static void	close() Doesn't do anything unless we are running Embedded.
static void	debug(java.lang.Object msg)
static void	debug(java.lang.Object msg, java.lang.Throwable ex)
static void	error(java.lang.Object msg)
static void	error(java.lang.Object msg, java.lang.Throwable 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.Throwable ex)
static boolean	isEmbedded()
static void	main(java.lang.String[] args) Run standalone to activate the debug console.
static void	message(int logLevel, java.lang.Object msg) Purpose: logs using 'logmsg' if that fails, then does console.
(package private) static void	message(int logLevel, java.lang.String levelMsg, java.lang.Object msg) Purpose: logs using 'logmsg' if that fails, then does console.
static void	pass(java.lang.Object msg)
static boolean	resume()
static void	runEmbedded(java.lang.String[] args) Call to make the SAFS Debug Log--normally a separate Java Process--run embedded inside the test process in a separate Thread.
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 boolean	suspend()
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_SUSPEND

public static final java.lang.String SAFS_TESTLOG_SUSPEND

"SUSPEND" -- Command to SUSPEND debug logging temporarily.

See Also:

Constant Field Values

SAFS_TESTLOG_RESUME

public static final java.lang.String SAFS_TESTLOG_RESUME

"RESUME" -- Command to RESUME debug logging.

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

level

static int level

strlevel

protected static final java.lang.String[] strlevel

log_processname

protected static java.lang.String log_processname

Constructor Detail

Log

public Log()

Method Detail

runEmbedded

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

Call to make the SAFS Debug Log--normally a separate Java Process--run embedded inside the test process in a separate Thread. This call will start the new Daemon Thread and the caller will return immediately.

Parameters:

args - -- Same as for main(String[] args)--which will be invoked with a new Thread.

isEmbedded

public static boolean isEmbedded()

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

static void message(int logLevel,
                    java.lang.String levelMsg,
                    java.lang.Object msg)

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

Parameters:

logLevel - int

levelMsg - String

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

message

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

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

Parameters:

logLevel - int, the log level

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

suspend

public static boolean suspend()

resume

public static boolean resume()

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.Throwable ex)

info

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

debug

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

close

public static void close()

Doesn't do anything unless we are running Embedded. Otherwise, will shutdown the embedded debug log.

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 -