org.safs.logging

Class LogUtilities

java.lang.Object

org.safs.STAFRequester

org.safs.logging.LogUtilities

Direct Known Subclasses:

ApacheLogUtilities, RLogUtilities

public class LogUtilities
extends STAFRequester

Provides access to tool-independent logging through the STAF SAFSLOGS service. This class also acts as a superclass for tool-dependent subclasses so that they can also log the same messages to the native tool log and any tool console. If the SAFSLOGS service is not running; or some other error prevents logging to the SAFSLOGS service; then messages will be sent to the static org.safs.Log class.

The subclass would minimally overload the primary logMessage function--the one that actually implements the logging code--and intercept logMessage calls. The subclass function would call its super.logMessage to perform the normal SAFSLOGS logging and then evaluate the returned String to see if it is expected to write to the native tool log and/or console.

Version:

1.0, 09/12/2003

Author:

Carl Nagle, SAS Institute, Carl Nagle, SEP 16, 2003 Enabled copying org.safs.Log with messages., Carl Nagle, NOV 18, 2003 Added default System.out console logging. General Public License: http://www.opensource.org/licenses/gpl-license.php

Field Summary

Fields

Modifier and Type	Field and Description
protected boolean	copyLogClass flag for sending/copying messages to static org.safs.Log class.
protected boolean	initialized flag for instance initialization state
protected java.lang.String	lastNamedLogFacility Stores the name of the last used LogFacility when logging.
static java.lang.String	LOG_ERROR Generic error return value from logMessage routines.
protected int	logLevel curent log level as retrieved from SAFSLOGS.

Fields inherited from class org.safs.STAFRequester

staf

Constructor Summary

Constructors

Constructor and Description
LogUtilities() Noop Constructor User must provide an initialized STAFHelper via superclass STAFRequester before the instance can be effective.
LogUtilities(STAFHelper helper) Constructor with pre-registered STAF handle
LogUtilities(STAFHelper helper, boolean copyLogClass) Constructor with pre-registered STAF handle and flag for using the static Log class.

Method Summary

Modifier and Type	Method and Description
protected boolean	checkInitialized() convenience routine to throw a LogException when uninitialized.
void	closeLogFacility(java.lang.String facname) Closes a specified LogFacility or ALL LogFacilities via the SAFSLOGS service.
void	consoleLog(java.lang.String formattedMessage, java.lang.String description) Subclasses override to log to a proprietary tool-dependent console.
boolean	getCopyLogClass() Check the present state of our copyLogClass flag.
java.lang.String	getLastNamedLogFacility() returns the name of the last used LogFacility for logging.
void	initLogFacility(java.lang.String facname, long facmode) Initialize a new LogFacility via the SAFSLOGS service.
void	initLogFacility(java.lang.String facname, long facmode, java.lang.String linkedfac) Initialize a new LogFacility via the SAFSLOGS service.
void	initLogFacility(java.lang.String facname, long facmode, java.lang.String alttextlog, java.lang.String altxmllog, java.lang.String linkedfac) Initialize a new LogFacility via the SAFSLOGS service.
java.lang.String	logMessage(java.lang.String facname, java.lang.String msg) Log a message to the specified LogFacility via the SAFSLOGS service.
java.lang.String	logMessage(java.lang.String facname, java.lang.String msg, int msgType) Log a message to the specified LogFacility via the SAFSLOGS service.
java.lang.String	logMessage(java.lang.String facname, java.lang.String msg, int msgType, java.lang.String description) Log a message to the specified LogFacility via the SAFSLOGS service.
java.lang.String	logMessage(java.lang.String facname, java.lang.String msg, java.lang.String description) Log a message to the specified LogFacility via the SAFSLOGS service.
java.lang.String	logMessage(java.lang.String facname, java.lang.String msg, java.lang.String description, int msgType) Log a message to the specified LogFacility via the SAFSLOGS service.
static void	main(java.lang.String[] args) Some self-test diagnostics...does it really work :?
protected void	sendLogClassMessage(java.lang.String msg, java.lang.String description, int msgType) Copy the message to the static org.safs.Log class if enabled.
void	setCopyLogClass(boolean copyLogClass) Set or Reset the flag to enable logging to org.safs.Log This Log class is primarily used during development and debugging and is not normally used during production testing.
void	setLastNamedLogFacility(java.lang.String lastNamedLogFacility)
void	toolLog(int messageType, java.lang.String formattedMessage, java.lang.String description) Subclasses override to log to their proprietary tool-dependent log.

Methods inherited from class org.safs.STAFRequester

getSTAFHelper, setSTAFHelper

Methods inherited from class java.lang.Object

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

Field Detail

LOG_ERROR

public static final java.lang.String LOG_ERROR

Generic error return value from logMessage routines.

See Also:

Constant Field Values

initialized

protected boolean initialized

flag for instance initialization state

copyLogClass

protected boolean copyLogClass

flag for sending/copying messages to static org.safs.Log class.

logLevel

protected int logLevel

curent log level as retrieved from SAFSLOGS.

lastNamedLogFacility

protected java.lang.String lastNamedLogFacility

Stores the name of the last used LogFacility when logging.

This is useful for subclasses like ApacheLogUtilities that bridge to our logging mechanism but do not provide a facname parameter in their APIs.

Constructor Detail

LogUtilities

public LogUtilities()

Noop Constructor User must provide an initialized STAFHelper via superclass STAFRequester before the instance can be effective.

LogUtilities

public LogUtilities(STAFHelper helper)

Constructor with pre-registered STAF handle

Parameters:

helper - -- an initialized STAFHelper for talking with STAF.

LogUtilities

public LogUtilities(STAFHelper helper,
                    boolean copyLogClass)

Constructor with pre-registered STAF handle and flag for using the static Log class.

Parameters:

helper - -- an initialized STAFHelper for talking with STAF.

copyLogClass - -- flag as to whether or not messages should be forwarded to the static org.safs.Log class That Log class is primarily used during development and debugging and is not normally used during production testing.

Method Detail

getLastNamedLogFacility

public java.lang.String getLastNamedLogFacility()

returns the name of the last used LogFacility for logging.

This is useful for subclasses like ApacheLogUtilities that bridge to our logging mechanism but do not provide a facname parameter in their APIs.

setLastNamedLogFacility

public void setLastNamedLogFacility(java.lang.String lastNamedLogFacility)

Parameters:

lastNamedLogFacility - String, the name of the last used LogFacility for logging

setCopyLogClass

public void setCopyLogClass(boolean copyLogClass)

Set or Reset the flag to enable logging to org.safs.Log This Log class is primarily used during development and debugging and is not normally used during production testing.

Parameters:

copyLogClass - -- true to forward messages to org.safs.Log

getCopyLogClass

public boolean getCopyLogClass()

Check the present state of our copyLogClass flag.

checkInitialized

protected boolean checkInitialized()
                            throws LogException

convenience routine to throw a LogException when uninitialized. Checks for: STAFHelper provided, STAFHelper initialized, and SAFSLOGS service is running.

Throws:

LogException

initLogFacility

public void initLogFacility(java.lang.String facname,
                            long facmode,
                            java.lang.String alttextlog,
                            java.lang.String altxmllog,
                            java.lang.String linkedfac)
                     throws LogException

Initialize a new LogFacility via the SAFSLOGS service.

Parameters:

facname - -- String name for this log facility.

facmode - -- long OR'd values of enabled logs. Valid values are the various LOGMODE_ constants defined in AbstractLogFacility.

alttextlog - -- alternative String name for an enabled SAFS TEXT log. If null the default name for the text log as defined in AbstractLogFacility will be used.

altxmllog - -- alternative String name for an enabled SAFS XML log. If null the default name for the XML log as defined in AbstractLogFacility will be used.

linkedfac - -- NOT YET IMPLEMENTED
optional String name for another existing LogFacility that is to be linked to this one. Messages sent to this LogFacility will also be sent to the linked LogFacility.

Throws:

LogException

initLogFacility

public void initLogFacility(java.lang.String facname,
                            long facmode)
                     throws LogException

Initialize a new LogFacility via the SAFSLOGS service. Provides for minimal parameters. Default values are used for all parameters missing from this overloaded method.

Parameters:

facname - -- String name for this log facility.

facmode - -- long OR'd values of enabled logs. Valid values are the various LOGMODE_ constants defined in AbstractLogFacility.

Throws:

LogException

initLogFacility

public void initLogFacility(java.lang.String facname,
                            long facmode,
                            java.lang.String linkedfac)
                     throws LogException

Initialize a new LogFacility via the SAFSLOGS service. Provides for a small subset of parameters. Default values are used for all parameters missing from this overloaded method.

Parameters:

facname - -- String name for this log facility.

facmode - -- long OR'd values of enabled logs. Valid values are the various LOGMODE_ constants defined in AbstractLogFacility.

linkedfac - -- NOT YET IMPLEMENTED
optional String name for another existing LogFacility that is to be linked to this one. Messages sent to this LogFacility will also be sent to the linked LogFacility.

Throws:

LogException

closeLogFacility

public void closeLogFacility(java.lang.String facname)
                      throws LogException

Closes a specified LogFacility or ALL LogFacilities via the SAFSLOGS service.

Parameters:

facname - -- String name of an open LogFacility in SAFSLOGS. If this parameter is null, then we will close ALL open LogFacilities in the service.

Throws:

LogException

sendLogClassMessage

protected void sendLogClassMessage(java.lang.String msg,
                                   java.lang.String description,
                                   int msgType)

Copy the message to the static org.safs.Log class if enabled.

Parameters:

msg - -- the message to send

msgType - the local msgType. This will be converted to the appropriate message type for the Log class.

logMessage

public java.lang.String logMessage(java.lang.String facname,
                                   java.lang.String msg,
                                   java.lang.String description,
                                   int msgType)

Log a message to the specified LogFacility via the SAFSLOGS service.

Tool-dependent subclass implementations would minimally overload this function to intercept the call. Subclasses would then call this function via super.logMessage and evaluate the returned String to see if the tool- dependent subclass is expected to log to the native tool log and/or console.

Parameters:

facname - -- String name of an open LogFacility in SAFSLOGS.

msg - -- String text of the message to log.

description - -- optional String text of additional details for the message.

msgType - -- int message type identifier constant as defined in AbstractLogFacility.

Returns:

String STAFResult.result from SAFSLOGS service call; or, LOG_ERROR if we were unable to make the call due to improper initialization of SAFSLOGS, this LogUtilities instance, or bad function parameters.

If no error occurred, the returned String informs the caller if native tool logging or console logging is enabled and at what log level. The caller, presumably a commercial automation tool, can then determine if it should log the message to the native tool log and/or console.

logMessage

public java.lang.String logMessage(java.lang.String facname,
                                   java.lang.String msg,
                                   int msgType,
                                   java.lang.String description)

Log a message to the specified LogFacility via the SAFSLOGS service.

Parameters:

facname - -- String name of an open LogFacility in SAFSLOGS.

msg - -- String text of the message to log.

msgType - -- int message type identifier constant as defined in AbstractLogFacility.

description - -- optional String text of additional details for the message.

Returns:

String STAFResult.result from SAFSLOGS service call; or, LOG_ERROR if we were unable to make the call due to improper initialization of SAFSLOGS, this LogUtilities instance, or bad function parameters.

logMessage

public java.lang.String logMessage(java.lang.String facname,
                                   java.lang.String msg,
                                   int msgType)

Log a message to the specified LogFacility via the SAFSLOGS service.

Parameters:

facname - -- String name of an open LogFacility in SAFSLOGS.

msg - -- String text of the message to log.

msgType - -- int message type identifier constant as defined in AbstractLogFacility.

Returns:

String STAFResult.result from SAFSLOGS service call; or, LOG_ERROR if we were unable to make the call due to improper initialization of SAFSLOGS, this LogUtilities instance, or bad function parameters.

logMessage

public java.lang.String logMessage(java.lang.String facname,
                                   java.lang.String msg,
                                   java.lang.String description)

Log a message to the specified LogFacility via the SAFSLOGS service. A default message type of GENERIC_MESSAGE is used.

Parameters:

facname - -- String name of an open LogFacility in SAFSLOGS.

msg - -- String text of the message to log.

description - -- optional String text of additional details for the message.

Returns:

String STAFResult.result from SAFSLOGS service call; or, LOG_ERROR if we were unable to make the call due to improper initialization of SAFSLOGS, this LogUtilities instance, or bad function parameters.

logMessage

public java.lang.String logMessage(java.lang.String facname,
                                   java.lang.String msg)

Log a message to the specified LogFacility via the SAFSLOGS service. A default message type of GENERIC_MESSAGE is used.

Parameters:

facname - -- String name of an open LogFacility in SAFSLOGS.

msg - -- String text of the message to log.

Returns:

String STAFResult.result from SAFSLOGS service call; or, LOG_ERROR if we were unable to make the call due to improper initialization of SAFSLOGS, this LogUtilities instance, or bad function parameters.

toolLog

public void toolLog(int messageType,
                    java.lang.String formattedMessage,
                    java.lang.String description)

Subclasses override to log to their proprietary tool-dependent log.

Parameters:

messageType - int type of to be logged

formattedMessage - String the message to be logged

description - String optional description about the message being logged

consoleLog

public void consoleLog(java.lang.String formattedMessage,
                       java.lang.String description)

Subclasses override to log to a proprietary tool-dependent console.

Parameters:

formattedMessage - String the message to be logged

description - String optional description about the message being logged

main

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

Some self-test diagnostics...does it really work :?