com.tivoli.twg.log
Class TWGLog

java.lang.Object
  extended bycom.tivoli.twg.log.TWGLog
All Implemented Interfaces:
TWGRasLogger

public class TWGLog
extends java.lang.Object
implements TWGRasLogger

This class provides logging function that allows multiple processes to write log messages into shared log files. This function is used primarily for RAS logging by most of Director's components, but it is also used to log operational status messages by the scheduler and scheduled tasks. Most of the work done by this class is implemented in native methods. In the current Windows NT environment of Director's server, there are three binaries that are used:


Field Summary
static int defaultBufferSize
           
static int defaultFileSize
           
static int TARGET_JAVA
           
static int TARGET_JNI
           
static int TARGET_SYSOUT
           
 
Constructor Summary
TWGLog(java.lang.String logName)
          Constructor specifying only the name of the log.
TWGLog(java.lang.String logName, boolean useLogDir)
          Constructor specifying the name of the log and if the file should be created in the \log directory.
TWGLog(java.lang.String logName, long categories, int level)
          Constructor specifying categories and level.
TWGLog(java.lang.String logName, long categories, int level, int maxFileSize, int bufferSize)
          Constructor specifying all log parameters
 
Method Summary
static long attachListener(TWGLogListener listener, java.lang.String logName)
          Attach a listener to a specified log.
static long attachListener(TWGLogListener listener, java.lang.String logName, boolean isRas)
          Attach a listener to a specified log.
static java.lang.String byteArrayToHexString(java.lang.String label, byte[] array, int offset)
           
 void clearAllMessages()
           
 void close()
           
 void closeDefine()
           
 void define(java.lang.String key, java.lang.String value)
           
 void define(java.lang.String key, java.lang.String bundleName, java.lang.String bundleKey)
           
static void delete(java.lang.String logName)
           
static void detachListener(int listenerHandle)
          Remove a listener from a log.
 void formatDebug(long component, java.lang.String message)
          Formats a RAS debug message.
 void formatDebug(long component, java.lang.String message, java.lang.Throwable e)
           
 void formatDebugH(long component, java.lang.String message)
           
 void formatDebugH(long component, java.lang.String message, java.lang.Throwable e)
           
 void formatDump(long component, java.lang.String message, byte[] data, int dataLength)
          Formats a RAS dump message.
 void formatDumpH(long component, java.lang.String message, byte[] data, int dataLength)
           
 void formatEntry(long component, java.lang.String message)
          Formats a RAS method entry trace message.
 void formatEntryExit(long component, java.lang.String message)
          Formats a RAS method entry/exit trace message.
 void formatEntryExitH(long component, java.lang.String message)
           
 void formatEntryH(long component, java.lang.String message)
           
 void formatError(long component, java.lang.String message)
          Formats a RAS error message.
 void formatError(long component, java.lang.String message, java.lang.Throwable e)
           
 void formatExit(long component, java.lang.String message)
          Formats a RAS method exit trace message.
 void formatExitH(long component, java.lang.String message)
           
 long getCategories()
          Get this log's category mask.
 long getComponents()
          Get the RAS log's component mask
 int getLevel()
          Get this log's level.
 TWGLogImpl getLogImpl()
           
 int getMaxFileSize()
          Get the maximum size the log engine will allow the log file for this log to grow before rolling it over to a back-up file and starting a new log file.
 java.lang.String getName()
          Get the name of this log.
static TWGRasLogger getRasLoggerInstance(java.lang.String logName)
           
static int getTarget()
           
 int getTypes()
          Get the RAS log's type mask
static void initialize()
           
static void initialize(int initializer)
          Initializes the log engine by starting it in a new process
static java.lang.String intArrayToHexString(java.lang.String label, int[] array, int offset)
           
static java.lang.String intArrayToString(java.lang.String label, int[] array)
           
 boolean isLoggable(long category, int level)
          See if a message is loggable based on this log's component and level setting.
 long lastServiced()
          Get the time of when the log engine last serviced this log
 long lastWrapped()
          Get the time of when the log engine last wrapped this log
 boolean openDefine()
           
 void setCategory(long category)
          Add one or more categories to this log's category mask.
 void setComponent(long newComponents)
          Add one or more components to the RAS log's component mask.
 void setLevel(int level)
          Set this log's level.
 void setMaxFileSize(int maxFileSize)
          Set the maximum size the log engine will allow the log file for this log to grow before rolling it over to a back-up file and starting a new log file.
static void setTarget(int t)
           
 void setType(int newTypes)
          Add one or more types to the RAS log's type mask.
 void term()
           
static void terminate()
          Terminate the log engine by killing the process
 boolean traceOn(long component, int types)
          Determine if a RAS message should be logged based on the component and type masks.
 void unsetCategory(long category)
          Remove one or more categories from this log's category mask.
 void unsetComponent(long delComponents)
          Remove one or more components from the RAS log's component mask.
 void unsetType(int delTypes)
          Remove one or more types from the RAS log's type mask.
 void updateParms()
           
 void write(java.lang.String message, long category, int level)
          Conditionally write a message to a log.
 void write(java.lang.String message, long category, int level, int correlator)
          Conditionally write a correlated message to a log.
 void writeAll(java.lang.String message, long category, int level)
          Unconditionally write a message to a log.
 void writeAll(java.lang.String message, long category, int level, int correlator)
          Unconditionally write a correlated message to a log.
static void writeDefault(java.lang.String message, long category, int level)
          Conditionally write a message to the default log.
static void writeDefault(java.lang.String message, long category, int level, int correlator)
          Conditionally write a correlated message to the default log.
static void writeDefaultAll(java.lang.String message, long category, int level)
          Unconditionally write a message to the default log.
static void writeDefaultAll(java.lang.String message, long category, int level, int correlator)
          Unconditionally write a correlated message to the default log.
 void writeNLS(java.lang.String bundleName, java.lang.String messageKey, int level)
          Conditionally write a NLS message to a log.
 void writeNLS(java.lang.String bundleName, java.lang.String messageKey, int level, int correlator)
          Conditionally write a NLS message to a log.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

defaultFileSize

public static final int defaultFileSize
See Also:
Constant Field Values

defaultBufferSize

public static final int defaultBufferSize
See Also:
Constant Field Values

TARGET_JAVA

public static final int TARGET_JAVA
See Also:
Constant Field Values

TARGET_SYSOUT

public static final int TARGET_SYSOUT
See Also:
Constant Field Values

TARGET_JNI

public static final int TARGET_JNI
See Also:
Constant Field Values
Constructor Detail

TWGLog

public TWGLog(java.lang.String logName,
              long categories,
              int level,
              int maxFileSize,
              int bufferSize)
Constructor specifying all log parameters

Parameters:
logName - The name of the log. Don't include any extensions, for example ("TWGRas").
categories - The initial value for the categories mask (for RAS logs, this is the component mask)
level - The initial value for the level mask. (for RAS logs, this is the type mask)
maxFileSize - The maximum size to allow the log file to grow before it is renamed to logName.bak and reopened. So, the maximum amount of log data ranges from maxFileSize to 2*maxFileSize.
bufferSize - The size of the memory buffer used to store log messages prior to writing them out to disk.

TWGLog

public TWGLog(java.lang.String logName,
              long categories,
              int level)
Constructor specifying categories and level. The other fields are defaulted as:

Parameters:
logName - The name of the log. Don't include any extensions, for example ("TWGRas").
categories - The initial value for the categories mask (for RAS logs, this is the component mask)
level - The initial value for the level mask. (for RAS logs, this is the type mask)

TWGLog

public TWGLog(java.lang.String logName,
              boolean useLogDir)
Constructor specifying the name of the log and if the file should be created in the \log directory. The other fields are defaulted as:

Parameters:
logName - The name of the log. Don't include any extensions, for example ("TWGRas").
useLogDir - Should the created logfile be placed in the \log directory.

TWGLog

public TWGLog(java.lang.String logName)
Constructor specifying only the name of the log. The other fields are defaulted as:

Parameters:
logName - The name of the log. Don't include any extensions, for example ("TWGRas").
Method Detail

getTarget

public static int getTarget()

setTarget

public static void setTarget(int t)

getLogImpl

public TWGLogImpl getLogImpl()

initialize

public static void initialize()

delete

public static void delete(java.lang.String logName)

close

public void close()

updateParms

public void updateParms()
Specified by:
updateParms in interface TWGRasLogger

term

public void term()
Specified by:
term in interface TWGRasLogger

initialize

public static void initialize(int initializer)
Initializes the log engine by starting it in a new process

Parameters:
initializer - this integer should be set to TWGRas.INIT_ENGINE, TWGRas.INIT_CONSOLE, TWGRas.INIT_NONE depending on if it this initialization is being called by code running in the engine's JVM, the console's JVM or some other JVM. If the INIT_ENGINE is specified, it causes the server engine's config properties to be used for the log engine launch command and its parameters. Temporarily, INIT_CONSOLE simply causes the useNative flag to be set to false.

terminate

public static void terminate()
Terminate the log engine by killing the process


getRasLoggerInstance

public static TWGRasLogger getRasLoggerInstance(java.lang.String logName)

getName

public final java.lang.String getName()
Get the name of this log.


getMaxFileSize

public final int getMaxFileSize()
Get the maximum size the log engine will allow the log file for this log to grow before rolling it over to a back-up file and starting a new log file.


setMaxFileSize

public final void setMaxFileSize(int maxFileSize)
Set the maximum size the log engine will allow the log file for this log to grow before rolling it over to a back-up file and starting a new log file.

Specified by:
setMaxFileSize in interface TWGRasLogger
Parameters:
maxFileSize - The maximum size to allow the log file to grow before it is renamed to logName.bak and reopened. So, the maximum amount of log data ranges from maxFileSize to 2*maxFileSize.

isLoggable

public final boolean isLoggable(long category,
                                int level)
See if a message is loggable based on this log's component and level setting. A message is loggable if the category ANDed with the log's category mask is equal to the specified category (i.e. all bits are set in the mask), and the level is less than or equal the log's level.

Parameters:
category - The category to be tested
level - The level to be tested

write

public final void write(java.lang.String message,
                        long category,
                        int level)
Conditionally write a message to a log. The message will not be logged if the category or level don't match the log's settings.

Parameters:
message - message text
category - category of the message
level - level of the message

write

public final void write(java.lang.String message,
                        long category,
                        int level,
                        int correlator)
Conditionally write a correlated message to a log. The message will not be logged if the category or level don't match the log's settings.

Parameters:
message - message text
category - category of the message
level - level of the message
correlator - correlator for this message

writeNLS

public void writeNLS(java.lang.String bundleName,
                     java.lang.String messageKey,
                     int level,
                     int correlator)
Conditionally write a NLS message to a log. The message will not be logged if the level doesn't match the log's settings. param bundleName NLS resource bundle name

Parameters:
messageKey - key of message in resource bundle
level - level of the message
correlator - correlator for the message

writeNLS

public void writeNLS(java.lang.String bundleName,
                     java.lang.String messageKey,
                     int level)
Conditionally write a NLS message to a log. The message will not be logged if the level doesn't match the log's settings. param bundleName NLS resource bundle name

Parameters:
messageKey - key of message in resource bundle
level - level of the message

writeAll

public final void writeAll(java.lang.String message,
                           long category,
                           int level)
Unconditionally write a message to a log.

Parameters:
message - message text
category - category of the message
level - level of the message

writeAll

public final void writeAll(java.lang.String message,
                           long category,
                           int level,
                           int correlator)
Unconditionally write a correlated message to a log.

Parameters:
message - message text
category - category of the message
level - level of the message
correlator - correlator for this message

openDefine

public final boolean openDefine()

define

public final void define(java.lang.String key,
                         java.lang.String value)

define

public final void define(java.lang.String key,
                         java.lang.String bundleName,
                         java.lang.String bundleKey)

closeDefine

public final void closeDefine()

writeDefault

public static final void writeDefault(java.lang.String message,
                                      long category,
                                      int level)
Conditionally write a message to the default log. The message will not be logged if the category or level don't match the log's settings.

Parameters:
message - message text
category - category of the message
level - level of the message

writeDefault

public static final void writeDefault(java.lang.String message,
                                      long category,
                                      int level,
                                      int correlator)
Conditionally write a correlated message to the default log. The message will not be logged if the category or level don't match the log's settings.

Parameters:
message - message text
category - category of the message
level - level of the message
correlator - correlator for this message

writeDefaultAll

public static final void writeDefaultAll(java.lang.String message,
                                         long category,
                                         int level)
Unconditionally write a message to the default log.

Parameters:
message - message text
category - category of the message
level - level of the message

writeDefaultAll

public static final void writeDefaultAll(java.lang.String message,
                                         long category,
                                         int level,
                                         int correlator)
Unconditionally write a correlated message to the default log.

Parameters:
message - message text
category - category of the message
level - level of the message
correlator - correlator for this message

setCategory

public final void setCategory(long category)
Add one or more categories to this log's category mask.

Parameters:
category - one or more categories to be ORed into this log's category mask

unsetCategory

public final void unsetCategory(long category)
Remove one or more categories from this log's category mask.

Parameters:
category - one or more categories to be ANDed out of this log's category mask

getCategories

public final long getCategories()
Get this log's category mask.

Returns:
This log's category mask

setLevel

public final void setLevel(int level)
Set this log's level.

Parameters:
level - new value for this log's level

getLevel

public final int getLevel()
Get this log's level.

Returns:
This log's level

attachListener

public static final long attachListener(TWGLogListener listener,
                                        java.lang.String logName)
Attach a listener to a specified log.

Parameters:
listener - reference to the object implementing the TWGLogListener interface that will be called when a new message is added to the log.
logName - name of the log to be listened to (for example, "TWGRas")

attachListener

public static final long attachListener(TWGLogListener listener,
                                        java.lang.String logName,
                                        boolean isRas)
Attach a listener to a specified log.

Parameters:
listener - reference to the object implementing the TWGLogListener interface that will be called when a new message is added to the log.
logName - name of the log to be listened to (for example, "TWGRas")

detachListener

public static final void detachListener(int listenerHandle)
Remove a listener from a log.

Parameters:
listenerHandle - handle returned from TWGLog.attachListener()

formatEntry

public final void formatEntry(long component,
                              java.lang.String message)
Formats a RAS method entry trace message.

Specified by:
formatEntry in interface TWGRasLogger
Parameters:
component - component making the flow trace call
message - message to put in RAS log
See Also:
TWGRasLogger

formatEntryH

public final void formatEntryH(long component,
                               java.lang.String message)
Specified by:
formatEntryH in interface TWGRasLogger

formatEntryExit

public final void formatEntryExit(long component,
                                  java.lang.String message)
Formats a RAS method entry/exit trace message.

Specified by:
formatEntryExit in interface TWGRasLogger
Parameters:
component - component making the flow trace call
message - message to put in RAS log
See Also:
TWGRasLogger

formatEntryExitH

public final void formatEntryExitH(long component,
                                   java.lang.String message)
Specified by:
formatEntryExitH in interface TWGRasLogger

formatExit

public final void formatExit(long component,
                             java.lang.String message)
Formats a RAS method exit trace message.

Specified by:
formatExit in interface TWGRasLogger
Parameters:
component - component making the flow trace call
message - message to put in RAS log
See Also:
TWGRasLogger

formatExitH

public final void formatExitH(long component,
                              java.lang.String message)
Specified by:
formatExitH in interface TWGRasLogger

formatDebug

public final void formatDebug(long component,
                              java.lang.String message)
Formats a RAS debug message.

Specified by:
formatDebug in interface TWGRasLogger
Parameters:
component - component making the flow trace call
message - message to put in RAS log
See Also:
TWGRasLogger

formatDebug

public final void formatDebug(long component,
                              java.lang.String message,
                              java.lang.Throwable e)
Specified by:
formatDebug in interface TWGRasLogger

formatDebugH

public final void formatDebugH(long component,
                               java.lang.String message)
Specified by:
formatDebugH in interface TWGRasLogger

formatDebugH

public final void formatDebugH(long component,
                               java.lang.String message,
                               java.lang.Throwable e)
Specified by:
formatDebugH in interface TWGRasLogger

formatError

public final void formatError(long component,
                              java.lang.String message)
Formats a RAS error message.

Specified by:
formatError in interface TWGRasLogger
Parameters:
component - component making the flow trace call
message - message to put in RAS log
See Also:
TWGRasLogger

formatError

public final void formatError(long component,
                              java.lang.String message,
                              java.lang.Throwable e)
Specified by:
formatError in interface TWGRasLogger

intArrayToHexString

public static java.lang.String intArrayToHexString(java.lang.String label,
                                                   int[] array,
                                                   int offset)

byteArrayToHexString

public static java.lang.String byteArrayToHexString(java.lang.String label,
                                                    byte[] array,
                                                    int offset)

intArrayToString

public static java.lang.String intArrayToString(java.lang.String label,
                                                int[] array)

formatDump

public final void formatDump(long component,
                             java.lang.String message,
                             byte[] data,
                             int dataLength)
Formats a RAS dump message.

Specified by:
formatDump in interface TWGRasLogger
Parameters:
component - component making the dump call
message - descriptive message for the data area being dumped
dataLength - length of data area to be dumped
data - data area to be dumped
See Also:
TWGRasLogger

formatDumpH

public final void formatDumpH(long component,
                              java.lang.String message,
                              byte[] data,
                              int dataLength)
Specified by:
formatDumpH in interface TWGRasLogger

traceOn

public final boolean traceOn(long component,
                             int types)
Determine if a RAS message should be logged based on the component and type masks. A message will only be logged if all the bits set in the component parameter are also set in the log's component mask, and all the bits set in the type parameter are also set in the log's type mask.

Specified by:
traceOn in interface TWGRasLogger
Parameters:
component - component(s) to test
Returns:
true if the message will be logged based on the RAS log's settings
See Also:
TWGRasLogger

getComponents

public final long getComponents()
Get the RAS log's component mask

Specified by:
getComponents in interface TWGRasLogger
Returns:
the RAS log's component mask value
See Also:
TWGRasLogger

setComponent

public final void setComponent(long newComponents)
Add one or more components to the RAS log's component mask.

Specified by:
setComponent in interface TWGRasLogger
Parameters:
newComponents - component(s) to be ORed into the RAS log's component mask
See Also:
TWGRasLogger

unsetComponent

public final void unsetComponent(long delComponents)
Remove one or more components from the RAS log's component mask.

Specified by:
unsetComponent in interface TWGRasLogger
Parameters:
delComponents - component(s) to be ANDed out of the RAS log's component mask
See Also:
TWGRasLogger

getTypes

public final int getTypes()
Get the RAS log's type mask

Specified by:
getTypes in interface TWGRasLogger
Returns:
the RAS log's type mask value
See Also:
TWGRasLogger

lastServiced

public final long lastServiced()
Get the time of when the log engine last serviced this log

Returns:
int C-style time stamp

lastWrapped

public final long lastWrapped()
Get the time of when the log engine last wrapped this log

Returns:
int C-style time stamp

setType

public final void setType(int newTypes)
Add one or more types to the RAS log's type mask.

Specified by:
setType in interface TWGRasLogger
Parameters:
newTypes - type(s) to be ORed into the RAS log's type mask
See Also:
TWGRasLogger

unsetType

public final void unsetType(int delTypes)
Remove one or more types from the RAS log's type mask.

Specified by:
unsetType in interface TWGRasLogger
Parameters:
delTypes - type(s) to be ANDed out of the RAS log's type mask
See Also:
TWGRasLogger

clearAllMessages

public final void clearAllMessages()