org.safs.staf.service.logging

Class STAFFileLogItem

java.lang.Object

org.safs.logging.LogItem

org.safs.logging.FileLogItem

org.safs.staf.service.logging.STAFFileLogItem

Direct Known Subclasses:

AbstractSTAFTextLogItem, AbstractSTAFXmlLogItem

public abstract class STAFFileLogItem
extends FileLogItem

This class represents a file log implemented using STAF LOG service. It contains a STAF handle to interact with STAF.

The initialization of this log item clears existing STAF log with the same name.

Since:

MAY 19 2009 (LW) Modify the method getSTAFLogDirectory() to abstract. getSTAFLogDirectory() contains the STAF-version related code, realize them in subclass can make the code more independent of STAF-version.

Author:

Carl Nagle 02/24/05 changed use of machine to effectiveMachine to avoid "localhost" when finding STAF logs to export to SAFS logs., Carl Nagle 11/03/2006 modified to process mixed-mode UTF-8 strings.

Field Summary

Fields

Modifier and Type	Field and Description
protected ServiceDebugLog	debugLog
protected HandleInterface	handle
protected static java.lang.String	LINEFEED
protected static int	SAFSLOG_MAJOR_VER
protected static int	SAFSLOG_MINOR_VER
protected java.lang.String	STAFVersion

Fields inherited from class org.safs.logging.LogItem

closed, enabled, level, mode, name

Constructor Summary

Constructors

Constructor and Description
STAFFileLogItem(long mode, java.lang.String parent, java.lang.String file) Creates a disabled STAFFileLogItem with default name (file name) and log level (LOGLEVEL_INFO).
STAFFileLogItem(java.lang.String name, long mode, boolean enabled, java.lang.String parent, java.lang.String file) Creates a STAFFileLogItem with the default log level (LOGLEVEL_INFO).

Method Summary

Modifier and Type	Method and Description
protected void	appendFinalLog(java.io.Writer out) Allow subclasses to append information to the final destination log.
abstract void	close() Close this log.
protected void	exportSTAFLog(java.io.File src) Exports the message fields of all log records of a STAF log to this log item's destination file.
protected void	finalizeLogFile() Finalizes the detination log file.
protected abstract java.util.List<java.lang.String>	getCloseMessages() Return the messages to write before the log is closed.
protected abstract java.util.List<java.lang.String>	getInitMessages() Return the messages to write after the log is initialized.
protected java.lang.String	getMachineName() STAF version 2 will use {STAF/Config/EffectiveMachine} to make log.
protected abstract java.lang.String	getSTAFLogDirectory() Returns the DIRECTORY setting of the STAF LOG service.
protected java.lang.String	getTestName() Strip the suffix of the test file to get the test name.
void	init() Initializes this log by clearing the STAF log with the same name, if any.
protected void	prependFinalLog(java.io.Writer out) Allow subclasses to prepend information to the final destination log.
protected java.lang.String	readStringFromSTAFLog(java.io.DataInputStream in) Read the next string from the STAF log.
protected long	readUIntFromSTAFLog(java.io.DataInputStream in) Reads the next "unsigned integer" from the input stream.
protected void	setDebugLog(ServiceDebugLog debugLog)
void	setHandle(HandleInterface h) Set the STAF handle of this log item.
protected com.ibm.staf.STAFResult	stafLogLog(java.lang.String message) Logs a message of Info level to the associated STAF log.
protected com.ibm.staf.STAFResult	stafLogLog(java.lang.String message, java.lang.String level) Logs a message to the STAF log associated with this log item.
protected com.ibm.staf.STAFResult	stafLogRequest(java.lang.String request) Submits a request to the instance of STAF LOG service loaded by the SAFS logging service.
protected void	write(java.lang.String msg) Write a message to the log.
protected void	writeCloseMessages() Write message to log before it is closed.
protected void	writeInitMessages() Write messages to log after it is initialized.

Methods inherited from class org.safs.logging.FileLogItem

fileExists, getAbsolutePath, getFileSpec, getParentDir, isFileSpecAbsolute, setParentDir

Methods inherited from class org.safs.logging.LogItem

dateTime, isClosed, logMessage

Methods inherited from class java.lang.Object

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

Field Detail

SAFSLOG_MAJOR_VER

protected static final int SAFSLOG_MAJOR_VER

See Also:

Constant Field Values

SAFSLOG_MINOR_VER

protected static final int SAFSLOG_MINOR_VER

See Also:

Constant Field Values

LINEFEED

protected static final java.lang.String LINEFEED

STAFVersion

protected java.lang.String STAFVersion

handle

protected HandleInterface handle

debugLog

protected ServiceDebugLog debugLog

Constructor Detail

STAFFileLogItem

public STAFFileLogItem(java.lang.String name,
                       long mode,
                       boolean enabled,
                       java.lang.String parent,
                       java.lang.String file)

Creates a STAFFileLogItem with the default log level (LOGLEVEL_INFO).

Parameters:

name - the name of this log. If null, file name is used as the name.

mode - the type of this log (LOGMODE constant defined by AbstractLogFacility).

enabled - true to enable this log; false to disable.

parent - the parent directory for this log.

file - the file spec of this log.

STAFFileLogItem

public STAFFileLogItem(long mode,
                       java.lang.String parent,
                       java.lang.String file)

Creates a disabled STAFFileLogItem with default name (file name) and log level (LOGLEVEL_INFO).

Parameters:

mode - the type of this log (LOGMODE constant defined by AbstractLogFacility).

parent - the parent directory for this log.

file - the file spec of this log.

Method Detail

setHandle

public void setHandle(HandleInterface h)

Set the STAF handle of this log item.

Parameters:

h - the new STAF handle.

init

public void init()

Initializes this log by clearing the STAF log with the same name, if any.

close

public abstract void close()
                    throws STAFLogException

Close this log.

Specified by:

close in class LogItem

Throws:

STAFLogException - if this method failed for any reason.

getInitMessages

protected abstract java.util.List<java.lang.String> getInitMessages()

Return the messages to write after the log is initialized.

getCloseMessages

protected abstract java.util.List<java.lang.String> getCloseMessages()

Return the messages to write before the log is closed.

write

protected void write(java.lang.String msg)

Write a message to the log.

writeInitMessages

protected void writeInitMessages()

Write messages to log after it is initialized. It should be called in method init().

writeCloseMessages

protected void writeCloseMessages()

Write message to log before it is closed. It should be called in method close().

getTestName

protected java.lang.String getTestName()

Strip the suffix of the test file to get the test name.

Returns:

String, the test's name.

stafLogRequest

protected com.ibm.staf.STAFResult stafLogRequest(java.lang.String request)

Submits a request to the instance of STAF LOG service loaded by the SAFS logging service.

Parameters:

request - the service request to submit.

Returns:

the result of the request.

stafLogLog

protected com.ibm.staf.STAFResult stafLogLog(java.lang.String message,
                                             java.lang.String level)

Logs a message to the STAF log associated with this log item.

Parameters:

message - the MESSAGE option value of the LOG request.

level - the LEVEL option value of the LOG request.

stafLogLog

protected com.ibm.staf.STAFResult stafLogLog(java.lang.String message)

Logs a message of Info level to the associated STAF log.

Parameters:

message - the MESSAGE option value of the LOG request.

finalizeLogFile

protected void finalizeLogFile()
                        throws STAFLogException

Finalizes the detination log file.

Throws:

SAFSLogException - if failed to finalize the log file.

STAFLogException

getSTAFLogDirectory

protected abstract java.lang.String getSTAFLogDirectory()

Returns the DIRECTORY setting of the STAF LOG service. This method is defined as abstract. Because STAF 2 and STAF 3 return non-marshaled and marshaled result. While to un-marshal the result, we must import the STAF 3 library; To separate STAF 2 and STAF 3, this method is defined as abstract, and it will be implemented in STAFTextLogItem, STAFTextLogItem3, STAFXmlLogItem and STAFXmlLogItem3.

Returns:

the Directory setting as returned by LIST SETTINGS request to STAF LOG service.

prependFinalLog

protected void prependFinalLog(java.io.Writer out)

Allow subclasses to prepend information to the final destination log. This implementation does nothing.

Parameters:

out -

appendFinalLog

protected void appendFinalLog(java.io.Writer out)

Allow subclasses to append information to the final destination log. This implementation does nothing.

Parameters:

out -

exportSTAFLog

protected void exportSTAFLog(java.io.File src)
                      throws java.io.IOException

Exports the message fields of all log records of a STAF log to this log item's destination file.

This method parsed the STAF log file directly for the log messages and writes them to the destination file. In terms of performance and memory consumption, it is better than indirectly querying the log content via STAF LOG service.

Parameters:

src - contains full path to the source STAF log file.

Throws:

java.io.IOException - if file related error occured.

readStringFromSTAFLog

protected java.lang.String readStringFromSTAFLog(java.io.DataInputStream in)
                                          throws java.io.IOException

Read the next string from the STAF log.

Strings are saved in the STAF log as byte data, with the number of bytes (saved as 4-byte long unsigned integer) preceeding the actual data.

Parameters:

in - the STAF log input stream.

Returns:

the string value read from the input stream.

Throws:

java.io.IOException

readUIntFromSTAFLog

protected long readUIntFromSTAFLog(java.io.DataInputStream in)
                            throws java.io.IOException

Reads the next "unsigned integer" from the input stream.

This method reads the next 4 bytes from the input stream, and convert them to a long (because java does not support unsigned data types), using the first byte as the highest byte and treating each byte as unsigned. For example:

 00 00 01 01 -> 257
 00 00 00 FF -> 255
 

Parameters:

in - the STAF log input stream.

Returns:

a long equal to the unsigned integer converted from the bytes.

Throws:

java.io.IOException

setDebugLog

protected void setDebugLog(ServiceDebugLog debugLog)

getMachineName

protected java.lang.String getMachineName()

STAF version 2 will use {STAF/Config/EffectiveMachine} to make log. While STAF version 3 use (STAF/Config/MachineNickName)

Returns:

EffectiveMachine (for version 2) of MachineNickName (for version 3)