com.ibm.etools.logging.util
Class AbstractMessageLogger

java.lang.Object
  |
  +--com.ibm.etools.logging.util.AbstractMessageLogger
Direct Known Subclasses:
MsgLogger

public abstract class AbstractMessageLogger
extends java.lang.Object


Field Summary
protected static AbstractMessageLoggerFactory _factory
           
static java.lang.String abstractMessageLoggerCopyright
          Copyright statement.
 
Constructor Summary
AbstractMessageLogger()
          AbstractMessageLogger constructor.
 
Method Summary
 void archiveFile()
          Archives the file being used
protected  void checkEnvironment()
          Deprecated. This method is not the correct way to check the environment variable(s) to turn logging on and off. Logging is now based on a logging level (see Level.java) rather than a boolean environment variable. Setting the level (and any other preferences) from the environment variable(s) will be handled under the covers in future releases. The preferred way to do this is via the setLevel(Level) method.
 void closeFile()
          If the current logger has an associated file handle to an output file for logging, the existing file handle is closed.
 void delArchivedFiles()
          Deletes archived files based on '_archiveExpiryDays'
 void finalize()
          Deregisters this Logging Agent instance from the Agent Controller.
 int getArchiveExpiryDays()
          The number of days since an archived file was archived and its deletion.
 boolean getArchiveOnOff()
          Returns archiveOnOff
static AbstractMessageLoggerFactory getFactory()
          Get the factory for this logger.
 java.lang.String getFileName()
          Returns the logging file name.
 boolean getFormatXMLOutput()
          Determines whether XML log message strings are formatted (i.e.
 boolean getIncludeTimeStamp()
          Deprecated. As of May 25, 2004, time stamps are included in all generated Common Base Events.
 int getLevel()
          Retrieves the level of this logger.
 AgentConfiguration getLoggingAgentDefaultConfiguration()
          Return the default configuration for this logger's LoggingAgent.
 java.util.Hashtable getMsgLoggerConfig()
          Retrieves a hashtable of the logger's preferences using the static instance variables in LoggerStateHashKeys as keys.
 java.lang.String getName()
          Retrieves the name of this logger.
 Plugin getPlugin()
          Retrieves the Plugin that this logger belongs, if running within a plugin environment.
 boolean getRotationalLogging()
          Returns 'true' if rotational logging is turned ON, otherwise false is returned
 java.lang.String getVersion()
          Retrieves the version of this logger.
 int getXMLDepth()
          Gets the maximum number of referenced complex objects traversed when generating the Common Base Event XML fragment.
 int getXMLDetailLevel()
          Deprecated. As of May 25, 2004, the level of detail is the same for all generated Common Base Events.
 boolean getXMLFormat()
          Determines whether this logger is using XML as it's output format.
protected  void initialize(java.lang.String name)
          Bring up the agent mechanism and sets any preferences that are stored in environment variable(s) (lowest priority) and/or the plugin's plugin.xml file that this logger belongs, if running within a plugin environment.
protected  void initialize(java.lang.String name, java.lang.String version)
          Bring up the agent mechanism and sets any preferences that are stored in environment variable(s) (lowest priority) and/or the plugin's plugin.xml file that this logger belongs, if running within a plugin environment.
 boolean isActive()
          Checks if the logger is actively logging or turned 'on'.
 boolean isLogging()
          Checks if the current logging level is set to log information.
 boolean isLoggingLevel(int checkLevel)
          Checks if the current logging level is at the parameter check level or higher (i.e.
 boolean isMonitored()
          Checks if the logger is being monitored.
static java.lang.String printStackToString(java.lang.Throwable throwable)
          Deprecated. This method is not the correct way to return an exception's stack trace as a String. Logging messages are now logged using the write([object/exception/primitive/thread]) method.
 void setActive(boolean active)
          This method sets the flag that turns the logger 'on' for active logging or 'off' for no logging.
 void setArchiveExpiryDays(int _archiveExpiryDays)
          Sets the number of days since an archived file was archived and its deletion.
 void setArchiveOnOff(boolean archiveOnOff)
          Sets the archiveOnOff instance variable
 void setFileName(java.lang.String logFile)
          This method sets the file name where messages are to be logged.
 void setFormatXMLOutput(boolean formatXMLOutput)
          Sets whether XML log message strings are formatted (i.e.
 void setIncludeTimeStamp(boolean includeTimeStamp)
          Deprecated. As of May 25, 2004, time stamps are included in all generated Common Base Events.
 void setLevel(int newLevel)
          Set the level of logging to one of the eight levels (i.e.
 void setMaxSize(long size)
          Sets the maximum size of the log file used for rotational logging.
 void setMsgLoggerConfig(java.util.Hashtable msgLoggerConfig)
          Sets the logger's preferences based on values in the parameter hashtable.
protected  void setPlugin(Plugin plugin)
          Set the Plugin that this logger belongs, if running within a plugin environment.
 void setXMLDepth(int newDepth)
          Sets the maximum number of referenced complex objects traversed when generating the Common Base Event XML fragment.
 void setXMLDetailLevel(int xmlDetailLevel)
          Deprecated. As of May 25, 2004, the level of detail is the same for all generated Common Base Events.
 void setXMLFormat(boolean format)
          Sets whether this logger is using XML as it's output format.
 void turnRLOff()
          Turns OFF rotational logging.
 boolean waitUntilMonitored(long maxTime)
          Suspends the current thread until the logging agent is monitored or the the parameter maximum time (milliseconds) has expired.
 void write(boolean msg)
          Log a boolean message.
 void write(byte msg)
          Log a byte message.
 void write(char msg)
          Log a char message.
 void write(DefaultRecord defaultRecord)
          Log a DefaultRecord object and respect its current logging level.
 void write(double msg)
          Log a double message.
 void write(float msg)
          Log a float message.
 void write(int msg)
          Log an int message.
 void write(int logLevel, boolean msg)
          Log a boolean message if the current logging level is at the parameter check level or higher (i.e.
 void write(int logLevel, byte msg)
          Log a byte message if the current logging level is at the parameter check level or higher (i.e.
 void write(int logLevel, char msg)
          Log a char message if the current logging level is at the parameter check level or higher (i.e.
 void write(int logLevel, double msg)
          Log a double message if the current logging level is at the parameter check level or higher (i.e.
 void write(int logLevel, float msg)
          Log a float message if the current logging level is at the parameter check level or higher (i.e.
 void write(int logLevel, int msg)
          Log an int message if the current logging level is at the parameter check level or higher (i.e.
 void write(int logLevel, long msg)
          Log a long message if the current logging level is at the parameter check level or higher (i.e.
 void write(int logLevel, java.lang.Object obj)
          Log an object message if the current logging level is at the parameter check level or higher (i.e.
 void write(int logLevel, short msg)
          Log a short message if the current logging level is at the parameter check level or higher (i.e.
 void write(long msg)
          Log a long message.
 void write(java.lang.Object obj)
          Log an Object message.
 void write(short msg)
          Log a short message.
 void writeCurrentThread()
          Log the current thread.
 void writeStackTrace()
          Log a stack trace of the current thread.
 
Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

abstractMessageLoggerCopyright

public static final java.lang.String abstractMessageLoggerCopyright
Copyright statement.

See Also:
Constant Field Values

_factory

protected static AbstractMessageLoggerFactory _factory
Constructor Detail

AbstractMessageLogger

public AbstractMessageLogger()
AbstractMessageLogger constructor.

Method Detail

getFactory

public static AbstractMessageLoggerFactory getFactory()
                                               throws NoDefinedFactoryException
Get the factory for this logger. When subclassing this class the implementor must ensure that the _factory variable holds the proper factory type.

Returns:
AbstractMessageLoggerFactory
NoDefinedFactoryException

initialize

protected final void initialize(java.lang.String name)
                         throws java.lang.IllegalArgumentException
Bring up the agent mechanism and sets any preferences that are stored in environment variable(s) (lowest priority) and/or the plugin's plugin.xml file that this logger belongs, if running within a plugin environment.

Throws:
java.lang.IllegalArgumentException - Attempting to set a logger's name with an illegal name

initialize

protected final void initialize(java.lang.String name,
                                java.lang.String version)
                         throws java.lang.IllegalArgumentException
Bring up the agent mechanism and sets any preferences that are stored in environment variable(s) (lowest priority) and/or the plugin's plugin.xml file that this logger belongs, if running within a plugin environment.

Throws:
java.lang.IllegalArgumentException - Attempting to set a logger's name with an illegal name

setXMLDetailLevel

public void setXMLDetailLevel(int xmlDetailLevel)
Deprecated. As of May 25, 2004, the level of detail is the same for all generated Common Base Events.

Since May 25, 2004, logged primitives and complex objects are converted to Common Base Events and serialized to XML based on the Common Base Event v1.0.1 schema. As such, the Common Base Event v1.0.1 specification specifies the required level of detail for all generated Common Base Events.

As such, this method does nothing.

Parameters:
xmlDetailLevel - Unused parameter.

getXMLDetailLevel

public int getXMLDetailLevel()
Deprecated. As of May 25, 2004, the level of detail is the same for all generated Common Base Events.

Since May 25, 2004, logged primitives and complex objects are converted to Common Base Events and serialized to XML based on the Common Base Event v1.0.1 schema. As such, the Common Base Event v1.0.1 specification specifies the required level of detail for all generated Common Base Events.

As such, this method always returns Detail.ALL.

Returns:
Detail.ALL since the level of detail is the same for all generated Common Base Events.

getIncludeTimeStamp

public boolean getIncludeTimeStamp()
Deprecated. As of May 25, 2004, time stamps are included in all generated Common Base Events.

Since May 25, 2004, logged primitives and complex objects are converted to Common Base Events and serialized to XML based on the Common Base Event v1.0.1 schema. Since the Common Base Event v1.0.1 specification requires the creationTime property, time stamps are included in all generated Common Base Events.

As such, this method always returns true.

Returns:
True since time stamps are included in all generated Common Base Events.

setIncludeTimeStamp

public void setIncludeTimeStamp(boolean includeTimeStamp)
Deprecated. As of May 25, 2004, time stamps are included in all generated Common Base Events.

Since May 25, 2004, logged primitives and complex objects are converted to Common Base Events and serialized to XML based on the Common Base Event v1.0.1 schema. Since the Common Base Event v1.0.1 specification requires the creationTime property, time stamps are included in all generated Common Base Events.

As such, this method does nothing.

Parameters:
includeTimeStamp - Unused parameter.

printStackToString

public static java.lang.String printStackToString(java.lang.Throwable throwable)
Deprecated. This method is not the correct way to return an exception's stack trace as a String. Logging messages are now logged using the write([object/exception/primitive/thread]) method.


checkEnvironment

protected void checkEnvironment()
Deprecated. This method is not the correct way to check the environment variable(s) to turn logging on and off. Logging is now based on a logging level (see Level.java) rather than a boolean environment variable. Setting the level (and any other preferences) from the environment variable(s) will be handled under the covers in future releases. The preferred way to do this is via the setLevel(Level) method.


getLoggingAgentDefaultConfiguration

public final AgentConfiguration getLoggingAgentDefaultConfiguration()
Return the default configuration for this logger's LoggingAgent.

Returns:
com.ibm.etools.logging.tracing.control.AgentConfiguration reference to this logger's LoggingAgent default configuration.

finalize

public final void finalize()
Deregisters this Logging Agent instance from the Agent Controller.

Overrides:
finalize in class java.lang.Object

isMonitored

public boolean isMonitored()
Checks if the logger is being monitored.

Returns:
true if the logger is being monitored

waitUntilMonitored

public boolean waitUntilMonitored(long maxTime)
Suspends the current thread until the logging agent is monitored or the the parameter maximum time (milliseconds) has expired.

Parameters:
maxTime - the maximum amount of time (milliseconds) to suspend the current thread
Returns:
true if the logger is being monitored

isLogging

public final boolean isLogging()
Checks if the current logging level is set to log information.

Returns:
true if logging is turned on (i.e. LEVEL.FINEST - Level.CONFIG), otherwise false (i.e. Level.NONE).

isLoggingLevel

public final boolean isLoggingLevel(int checkLevel)
Checks if the current logging level is at the parameter check level or higher (i.e. logging more information).

Parameters:
checkLevel - level to be checked against the current level.
Returns:
true if the current logging level is at the parameter check level or higher.

write

public void write(int logLevel,
                  boolean msg)
Log a boolean message if the current logging level is at the parameter check level or higher (i.e. logging more information).

Parameters:
logLevel - the level to be checked against the current level
msg - the message to be logged

write

public void write(boolean msg)
Log a boolean message.

Parameters:
msg - the message to be logged

write

public void write(int logLevel,
                  char msg)
Log a char message if the current logging level is at the parameter check level or higher (i.e. logging more information).

Parameters:
logLevel - the level to be checked against the current level
msg - the message to be logged

write

public void write(char msg)
Log a char message.

Parameters:
msg - the message to be logged

write

public void write(int logLevel,
                  byte msg)
Log a byte message if the current logging level is at the parameter check level or higher (i.e. logging more information).

Parameters:
logLevel - the level to be checked against the current level
msg - the message to be logged

write

public void write(byte msg)
Log a byte message.

Parameters:
msg - the message to be logged

write

public void write(int logLevel,
                  short msg)
Log a short message if the current logging level is at the parameter check level or higher (i.e. logging more information).

Parameters:
logLevel - the level to be checked against the current level
msg - the message to be logged

write

public void write(short msg)
Log a short message.

Parameters:
msg - the message to be logged

write

public void write(int logLevel,
                  int msg)
Log an int message if the current logging level is at the parameter check level or higher (i.e. logging more information).

Parameters:
logLevel - the level to be checked against the current level
msg - the message to be logged

write

public void write(int msg)
Log an int message.

Parameters:
msg - the message to be logged

write

public void write(int logLevel,
                  long msg)
Log a long message if the current logging level is at the parameter check level or higher (i.e. logging more information).

Parameters:
logLevel - the level to be checked against the current level
msg - the message to be logged

write

public void write(long msg)
Log a long message.

Parameters:
msg - the message to be logged

write

public void write(int logLevel,
                  float msg)
Log a float message if the current logging level is at the parameter check level or higher (i.e. logging more information).

Parameters:
logLevel - the level to be checked against the current level
msg - the message to be logged

write

public void write(float msg)
Log a float message.

Parameters:
msg - the message to be logged

write

public void write(int logLevel,
                  double msg)
Log a double message if the current logging level is at the parameter check level or higher (i.e. logging more information).

Parameters:
logLevel - the level to be checked against the current level
msg - the message to be logged

write

public void write(double msg)
Log a double message.

Parameters:
msg - the message to be logged

write

public void write(DefaultRecord defaultRecord)
Log a DefaultRecord object and respect its current logging level.

Parameters:
defaultRecord - the DefaultRecord object to be logged

write

public void write(int logLevel,
                  java.lang.Object obj)
Log an object message if the current logging level is at the parameter check level or higher (i.e. logging more information).

Parameters:
logLevel - the level to be checked against the current level

write

public void write(java.lang.Object obj)
Log an Object message.


writeCurrentThread

public final void writeCurrentThread()
Log the current thread.


writeStackTrace

public final void writeStackTrace()
Log a stack trace of the current thread.


getMsgLoggerConfig

public java.util.Hashtable getMsgLoggerConfig()
Retrieves a hashtable of the logger's preferences using the static instance variables in LoggerStateHashKeys as keys.

Returns:
hashtable of the logger's preferences

setMsgLoggerConfig

public void setMsgLoggerConfig(java.util.Hashtable msgLoggerConfig)
Sets the logger's preferences based on values in the parameter hashtable. The logger's preferences are stored in the parameter hashtable using the static instance variables in LoggerStateHashKeys as keys.

Parameters:
msgLoggerConfig - hashtable of the logger's preferences

getArchiveExpiryDays

public final int getArchiveExpiryDays()
The number of days since an archived file was archived and its deletion. Setting the number of days to '0' is equivalent to keeping archived files forever.

Returns:
the number of days before archived files are deleted

setArchiveExpiryDays

public final void setArchiveExpiryDays(int _archiveExpiryDays)
Sets the number of days since an archived file was archived and its deletion. Setting the number of days to '0' is equivalent to keeping archived files forever.

Parameters:
_archiveExpiryDays - the number of days before archived files are deleted

getFormatXMLOutput

public final boolean getFormatXMLOutput()
Determines whether XML log message strings are formatted (i.e. indentation and separate lines for all open/close tags).

Returns:
true if XML log message strings are formatted

setFormatXMLOutput

public final void setFormatXMLOutput(boolean formatXMLOutput)
Sets whether XML log message strings are formatted (i.e. indentation and separate lines for all open/close tags).

Parameters:
formatXMLOutput - if XML log message strings are formatted

setMaxSize

public final void setMaxSize(long size)
Sets the maximum size of the log file used for rotational logging. It also turns rotational logging ON.

Parameters:
size - - The maximum size of the log file in bytes

turnRLOff

public final void turnRLOff()
Turns OFF rotational logging. To turn ON rotational logging, 'setMaxSize' needs to be invoked.


getRotationalLogging

public final boolean getRotationalLogging()
Returns 'true' if rotational logging is turned ON, otherwise false is returned

Returns:
true if rotational logging is ON; otherwise false

getPlugin

public final Plugin getPlugin()
Retrieves the Plugin that this logger belongs, if running within a plugin environment.

Returns:
Plugin that this logger belongs, if running within a plugin environment, otherwise null

setPlugin

protected final void setPlugin(Plugin plugin)
Set the Plugin that this logger belongs, if running within a plugin environment.

Parameters:
plugin - the Plugin that this logger belongs

getName

public final java.lang.String getName()
Retrieves the name of this logger.

Returns:
copy of the agent name

getVersion

public final java.lang.String getVersion()
Retrieves the version of this logger.

Returns:
copy of the agent version

setLevel

public final void setLevel(int newLevel)
                    throws java.lang.IllegalArgumentException
Set the level of logging to one of the eight levels (i.e. LEVEL.FINEST - Level.NONE).

Parameters:
newLevel - new level of logging (i.e. LEVEL.FINEST - Level.NONE)
Throws:
java.lang.IllegalArgumentException - Attempting to set an illegal level

getLevel

public final int getLevel()
Retrieves the level of this logger.

Returns:
level of logging (i.e. LEVEL.FINEST - Level.NONE)

setXMLDepth

public void setXMLDepth(int newDepth)
Sets the maximum number of referenced complex objects traversed when generating the Common Base Event XML fragment.

The following ranges exist:

Parameters:
newDepth - The new maximum number of referenced complex objects traversed

getXMLDepth

public int getXMLDepth()
Gets the maximum number of referenced complex objects traversed when generating the Common Base Event XML fragment.

The following ranges exist:

Returns:
The new maximum number of referenced complex objects traversed

setXMLFormat

public void setXMLFormat(boolean format)
Sets whether this logger is using XML as it's output format.

Parameters:
format - if this logger is using XML as it's output format

getXMLFormat

public boolean getXMLFormat()
Determines whether this logger is using XML as it's output format.

Returns:
true if this logger is using XML as it's output format

getFileName

public java.lang.String getFileName()
Returns the logging file name.

Returns:
String logging file name

setFileName

public void setFileName(java.lang.String logFile)
This method sets the file name where messages are to be logged. If stand-alone mode is active, this overrides logging to standard out, by pumping all logs to the specified file. If standalone behavior is not active, then the file name is simply set for later use when standalone mode is enabled. If null is passed as a parameter, this stops logging to a file (and closes it), and redirects logging to Standard out.

Parameters:
logFile - new file name

closeFile

public void closeFile()
If the current logger has an associated file handle to an output file for logging, the existing file handle is closed.


isActive

public final boolean isActive()
Checks if the logger is actively logging or turned 'on'.

Returns:
true if the logger is actively logging or turned 'on'

setActive

public void setActive(boolean active)
This method sets the flag that turns the logger 'on' for active logging or 'off' for no logging. If the logger has an associated file name as the output file for logging, a file handle is created when the logger is turned 'on' and the existing file handle is closed when the logger is turned 'off'. All other logger preferences are maintained while the logger is turned 'off'.

Parameters:
active - boolean flag that turns the logger 'on' or 'off'

setArchiveOnOff

public void setArchiveOnOff(boolean archiveOnOff)
Sets the archiveOnOff instance variable

Parameters:
archiveOnOff - boolean flag that turns archiving 'on' or 'off'

getArchiveOnOff

public boolean getArchiveOnOff()
Returns archiveOnOff

Returns:
A flag indicating whether archiving is 'on' or 'off'

archiveFile

public void archiveFile()
Archives the file being used


delArchivedFiles

public void delArchivedFiles()
Deletes archived files based on '_archiveExpiryDays'