HiRISE

HiRISE.HiPlan.Utilities
Class LoggingUtilities

java.lang.Object
  extended by HiRISE.HiPlan.Utilities.LoggingUtilities

public class LoggingUtilities
extends Object

A set of utilities for managing Java loggers in HiPlan. These are strongly tied to HiPlan. The utilities for enabling and disabling logging, for example, explicitly only handle loggers whose names start with HiRISE.HiPlan.

These utilities make use of a system property, LOGGING_PROPERTY (HiRISE.HiPlan.Logging, to govern their behavior. The property is treated as a boolean, so it should have the value "true" or the value "false" - any other value, including no value, is treated as "false."

Loggers generated by these utilities (the makeLogger() method in particular) have a shared ConsoleHandler attached with a logging level of Level.INFO. If the logging system property is "true," they also have a shared FileHandler attached with a logging level of Level.ALL. The logger's logging level is Level.ALL if the logging property is "true," and it is Level.INFO if it is "false."

The file handler manages a file in the operator's home directory called HiPlanX.log.Y, where X is a unique identifier to handle the case where multiple applications are generating HiPlan logs and where Y is a versioning number. The log manager cycles through log versions automatically, retaining up to five at a time, with 0 being the most recent and 4 being the oldest. It automatically cuts the log and cycles to the next one when the log exceeds 125,000 bytes.

See LoggingUtilities.LogFormatter for the log record format.

The enableLogging() method sets the system property to "true" regardless of its current value. It sets the logging level to Level.ALL for all loggers whose names start with HIPLAN_LOGGERS (HiRISE.HiPlan). If the shared file manager exists, it is attached to these loggers as well; if it does not and cannot exist, the shared console logger's level is raised to Level.ALL (and a warning message is printed to the standard error stream).

The disableLogging() method sets the system property to "false" regardless of its current value. It sets the logging level to Level.INFO for all loggers whose names start with HIPLAN_LOGGERS. If the shared file handler exists, it is removed from these loggers, it is closed, and then it is prepped for being re-created later. (Re-creating it later will force the existing logs to cycle.) If the shared file handler does not exist, the shared console handler's level is set to Level.INFO.

Version:
1.2
Author:
Christian Schaller - UA/PIRL

Nested Class Summary
static class LoggingUtilities.LogFormatter
          A formatter for HiPlan logs.
 
Field Summary
static String DEFAULT_LOG_BASE_NAME
          The default base name for the HiPlan log files.
static String HIPLAN_LOGGERS
          The prefix used for identifying loggers to be managed by these utilities.
static String ID
          Class identification name with source code version and date.
static int LOG_REVISION_COUNT
          The maximum number of log files to cycle through.
static int LOG_SIZE_MAX
          The maximum size of a log file.
static String LOGGING_PROPERTY
          The system property used by these utilities to manage logging.
 
Method Summary
static void connectDatabase(Database database, Logger logger)
           
static void disableLogging()
          Disables logging on all existing loggers managed by these utilities.
static void disconnectDatabase(Database database, Logger logger)
           
static void enableLogging()
          Enables logging on all existing loggers managed by these utilities.
static boolean isLoggingEnabled()
          Checks whether logging is enabled.
static Logger makeLogger()
          Creates a new logger to be managed by these utilities.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

ID

public static final String ID
Class identification name with source code version and date.

See Also:
Constant Field Values

LOGGING_PROPERTY

public static final String LOGGING_PROPERTY
The system property used by these utilities to manage logging. It is treated as a boolean, evaluated by Boolean.getBoolean(String).

See Also:
Constant Field Values

HIPLAN_LOGGERS

public static final String HIPLAN_LOGGERS
The prefix used for identifying loggers to be managed by these utilities.

See Also:
Constant Field Values

LOG_REVISION_COUNT

public static final int LOG_REVISION_COUNT
The maximum number of log files to cycle through.

See Also:
Constant Field Values

LOG_SIZE_MAX

public static final int LOG_SIZE_MAX
The maximum size of a log file.

See Also:
Constant Field Values

DEFAULT_LOG_BASE_NAME

public static final String DEFAULT_LOG_BASE_NAME
The default base name for the HiPlan log files. Normally the log file will be named for the application being logged via the Constants.WRAPPER_NAME_PROPERTY, which is set by the HiPlan application wrappers. If the property isn't set, however, this default value is used.

See Also:
Constant Field Values
Method Detail

makeLogger

public static Logger makeLogger()
Creates a new logger to be managed by these utilities. The logger includes an attached shared ConsoleHandler with a level set to Level.INFO. If logging is enabled (as determined by the LOGGING_PROPERTY), a shared FileHandler is also attached, with a level of Level.ALL.

If logging is enabled, the logger's level is set to Level.ALL; if not, it is set to Level.INFO.

The logger's name is that of the class that created it. Note that if the fully qualified class name does not start with HIPLAN_LOGGERS (HiRISE.HiPlan), the logger created here will not be properly managed. This is potentially a pretty big flaw.

Returns:
a new logger.

enableLogging

public static void enableLogging()
Enables logging on all existing loggers managed by these utilities. This method sets the LOGGING_PROPERTY to "true." It sets the logging level to Level.ALL for all managed loggers. It assigns the shared FileHandler to the loggers; if the handler had previously been closed, it is created anew, triggering a log file rotation if needed. If the handler does not exist and cannot be created, the shared ConsoleHandler's level is set to Level.ALL.


disableLogging

public static void disableLogging()
Disables logging on all existing loggers managed by these utilities. This method sets the LOGGING_PROPERTY to "false." It sets the logging level to Level.INFO for all managed loggers and removes the shared FileHandler. The handler is also closed; later invocations of enableLogging() will start a new handler, possibly trigger logging rotation. If there is no shared file handler, the shared ConsoleHandler's level is set to Level.INFO.


isLoggingEnabled

public static boolean isLoggingEnabled()
Checks whether logging is enabled. The LOGGING_PROPERTY system property is checked. This check only has meaning for these utilities.

Returns:
true if logging is enabled; false otherwise.

connectDatabase

public static void connectDatabase(Database database,
                                   Logger logger)
                            throws Configuration_Exception,
                                   Database_Exception
Throws:
Configuration_Exception
Database_Exception

disconnectDatabase

public static void disconnectDatabase(Database database,
                                      Logger logger)
                               throws Database_Exception
Throws:
Database_Exception

HiRISE

Copyright (C) Arizona Board of Regents on behalf of the Planetary Image Research Laboratory, Lunar and Planetary Laboratory at the University of Arizona