com.izforge.izpack.util
Class Log

java.lang.Object
  extended by com.izforge.izpack.util.Log
All Implemented Interfaces:
LogError, LogMessage, LogWarning

public class Log
extends java.lang.Object
implements LogError, LogWarning, LogMessage

This class handles informing the user about unusual events during the installation process and therefore about the possibility that the installation may not have succeeded at all or may have succeeded only partially. Because the logger represents a single resource it is implemented as singleton.

Usage

To add a message to the install log call one of the addMessage() methods, using the appropriate message index. If the message contains placeholders for variables, provide a String array that supplies the necessary variable text. Calling addMessage() will add an informative message to the log. These may be used to indicate actions taken by the installer throughout the progression of the install. Calling addWarning() will not only add the requested warning message to the log but also cause the user to be alerted about the fact that the install might not have succeeded completely. addError() goes one step further, by alerting the user that the installation has failed.

Adding Messages

Messages are divided into three categories:
  1. informative/general messages
  2. warning messages
  3. error messages
To add a message, define the text resource in the language packs. Then add a new constant for the message, along with a brief description of the purpose of the message. If the message contains place holders for variable text add an ordered list to the description, that lists all variables in proper order, so that other programmers have no difficulty to form a correct call for the message. The constants are defined in the individual interfaces LogMessage, LogWarning and LogError.

To derive a correct integer value for the message index add a new value to either MESSAGE_BASE, WARNING_BASE or ERROR_BASE, depending on the message category. Next, increment the MAX_ constant for the message category, to ensure that the add... methods actually allow the message to be added. The key for the text resource must be named either log.message_, log.warning_ or log.error_ in accordance with the chosen index base. In addition, the key must be appended by the message index (without the base, since this implementation will automatically subtract the base). Variable place holders must conform to the specification for java.text.MessageFormat.

Debug Messages

The output of debug messages is controlled through system properties. These properties may be set using the -D command line option. Please note, that the -D option is a command line switch for the VM, not for IzPack. In order for this to work, these options must be listed on the command line before IzPack!

Turning Debug On

In order to receive debug output, it is necessary to turn this feature on explicitely. This is done with the command line otprion:

 -DIzPack.debug=on
 

Selecting Debug Channels

Setting the list of specific debug channels to trace is accomplished with the following command line option:

 -DIzPack.debug.channel=<channelA,channelB,...>
 

The parameter is a comma separated list of one or more channel identifiers.

Dumping a List of Debug Channels

 -DIzPack.debug.dumpList=on
 

To turn debug messages on

Version:
0.0.1 / 11/20/06
Author:
Elmar Grom

Nested Class Summary
private  class Log.Record
           
 
Field Summary
private static java.lang.String CHANNEL_LIST
          System property to enable dumping of the list of debug channels that did record messages
private static java.lang.String CHANNEL_SPEC
          System property to set the debug channels to trace
private  java.util.Vector<java.lang.String> channels
          The list of channels requested for debug output.
private static java.lang.String DATE_FORMAT
          The formatting used for the report time stamp
private  java.util.ArrayList<Log.Record> debug
          The collection of debug messages
private static java.lang.String DEBUG_SWITCH
          System property to turn debug output on
private  boolean debugActive
          This flag signals if debug messages should be recorded
private  boolean dumpChannels
          This flag signals that the identifiers of the recorded debug channels should be dumped
private static java.lang.String ERROR_PREFIX
          The prefix for building error message keys
private  java.util.ArrayList<Log.Record> errors
          The collection of error messages
private  AutomatedInstallData installData
          Access to the installation information and the localized text resources
private static Log me
          The only instance of Messenger
private static java.lang.String MESSAGE_PREFIX
          The prefix for building message keys
private  java.util.ArrayList<Log.Record> messages
          The collection of installation messages
private  java.lang.String newline
          The system dependent newline character sequence
private  java.util.Hashtable<java.lang.String,java.lang.String> recordedChannels
          This map keeps track of all channels that are recorded.
private static java.lang.String RESOURCE_PREFIX
          The prefix for all text resources related to this class
private static java.lang.String WARNING_PREFIX
          The prefix for building warning message keys
private  java.util.ArrayList<Log.Record> warnings
          The collection of warning messages
 
Fields inherited from interface com.izforge.izpack.util.LogError
COULD_NOT_WRITE_FILE, ERROR_BASE, MAX_ERROR
 
Fields inherited from interface com.izforge.izpack.util.LogWarning
MAX_WARNING, WARNING_BASE
 
Fields inherited from interface com.izforge.izpack.util.LogMessage
MAX_MESSAGE, MESSAGE_BASE
 
Constructor Summary
private Log()
          This class is installed as singleton.
 
Method Summary
 void addCustomError(java.lang.String template, java.lang.String[] detail, java.lang.Throwable exception)
          This method records an error message, using a custom text template.
 void addCustomMessage(java.lang.String template, java.lang.String[] detail)
          This method records a general installation message, using a custom text template.
 void addCustomWarning(java.lang.String template, java.lang.String[] detail, java.lang.Throwable exception)
          This method records a warning message, using a custom text template.
 void addDebugMessage(java.lang.String template, java.lang.String[] detail, java.lang.String channel, java.lang.Throwable exception)
          This method provides a channel for debugging messages in IzPack development.
 void addError(int message, java.lang.String[] detail, java.lang.Throwable exception)
          This method records an error message to the list of messages
 void addMessage(int message, java.lang.String[] detail)
          This method records general installation message
 void addWarning(int message, java.lang.String[] detail, java.lang.Throwable exception)
          This method records a warning message to the list of messages
private  java.lang.String buildDebug(int index)
          Builds a debug message from the information contained in the indicated debug record
private  java.lang.String buildDebug(Log.Record record)
          Builds a debug message from the information contained in a specific debug record
private  java.lang.String buildError(int index)
          Builds an error message from the information contained in the indicated error record
private  java.lang.String buildMessage(int index)
          Builds a general installation message from the information contained in the indicated record
private  java.lang.String buildWarning(int index)
          Builds a warning message from the information contained in the indicated warning record
private  java.lang.String compileReport()
          Prepares an installation report from the recorded information
 void dumpRecordedChannels()
          Dumps the list of debug channels to stdout that have recorded messages
 boolean errorsRecorded()
          Reports if any errors have been recorded.
static Log getInstance()
          Returns the only instance of Log
 void informUser()
          Displays a dialog that informs the user about the fact that one or more unusual events have occurred during installation.
 boolean messagesRecorded()
          Reports if any messages have been recorded.
 boolean warningsRecorded()
          Reports if any warnings have been recorded.
 void writeReport()
          Presents the user with a dialog to select a file and location for the installation report and writes a report contianing all messages to the user selected file.
 void writeReport(java.lang.String file)
          Writes a report contianing all messages to the indicated file.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

RESOURCE_PREFIX

private static final java.lang.String RESOURCE_PREFIX
The prefix for all text resources related to this class

See Also:
Constant Field Values

DATE_FORMAT

private static final java.lang.String DATE_FORMAT
The formatting used for the report time stamp

See Also:
Constant Field Values

MESSAGE_PREFIX

private static final java.lang.String MESSAGE_PREFIX
The prefix for building message keys

See Also:
Constant Field Values

WARNING_PREFIX

private static final java.lang.String WARNING_PREFIX
The prefix for building warning message keys

See Also:
Constant Field Values

ERROR_PREFIX

private static final java.lang.String ERROR_PREFIX
The prefix for building error message keys

See Also:
Constant Field Values

DEBUG_SWITCH

private static final java.lang.String DEBUG_SWITCH
System property to turn debug output on

See Also:
Constant Field Values

CHANNEL_SPEC

private static final java.lang.String CHANNEL_SPEC
System property to set the debug channels to trace

See Also:
Constant Field Values

CHANNEL_LIST

private static final java.lang.String CHANNEL_LIST
System property to enable dumping of the list of debug channels that did record messages

See Also:
Constant Field Values

me

private static Log me
The only instance of Messenger


newline

private java.lang.String newline
The system dependent newline character sequence


installData

private AutomatedInstallData installData
Access to the installation information and the localized text resources


messages

private java.util.ArrayList<Log.Record> messages
The collection of installation messages


warnings

private java.util.ArrayList<Log.Record> warnings
The collection of warning messages


errors

private java.util.ArrayList<Log.Record> errors
The collection of error messages


debug

private java.util.ArrayList<Log.Record> debug
The collection of debug messages


channels

private java.util.Vector<java.lang.String> channels
The list of channels requested for debug output. A Vector must be used for this purpose, since this is the only class that explicitly specifies that the equals() method is used for determining if a particular object is contained.


recordedChannels

private java.util.Hashtable<java.lang.String,java.lang.String> recordedChannels
This map keeps track of all channels that are recorded. It is used for information purposes.


debugActive

private boolean debugActive
This flag signals if debug messages should be recorded


dumpChannels

private boolean dumpChannels
This flag signals that the identifiers of the recorded debug channels should be dumped

Constructor Detail

Log

private Log()
This class is installed as singleton. Therefore the constructor is declared private. Use getInstance() to get an instance.

Method Detail

getInstance

public static Log getInstance()
Returns the only instance of Log

Returns:
the only instance of Log

addMessage

public void addMessage(int message,
                       java.lang.String[] detail)
This method records general installation message

Parameters:
message - the numeric identifier of the message to add, as defined in LogMessage
detail - a string array of variable fields that should be inserted into the message text

addCustomMessage

public void addCustomMessage(java.lang.String template,
                             java.lang.String[] detail)
This method records a general installation message, using a custom text template. It allows cusom code to insert message text that is not defined in IzPack. IzPack internal code should use the parallel version based on the message index.

Parameters:
template - the basic template of the message
detail - a string array of variable fields that should be inserted into the message text. Each array element will be inserted into the text template, replacing a marker.
See Also:
MessageFormat.format(java.lang.String, java.lang.Object[])

addWarning

public void addWarning(int message,
                       java.lang.String[] detail,
                       java.lang.Throwable exception)
This method records a warning message to the list of messages

Parameters:
message - the numeric identifier of the message to add, as defined in LogWarning
detail - a string array of variable fields that should be inserted into the message text. Each array element will be inserted into the text template, replacing a marker.
exception - the exception associated with the event or null if there was none.
See Also:
MessageFormat.format(java.lang.String, java.lang.Object[])

addCustomWarning

public void addCustomWarning(java.lang.String template,
                             java.lang.String[] detail,
                             java.lang.Throwable exception)
This method records a warning message, using a custom text template. It allows cusom code to insert message text that is not defined in IzPack. IzPack internal code should use the parallel version based on the message index.

Parameters:
template - the basic template for the message
detail - a string array of variable fields that should be inserted into the message text. Each array element will be inserted into the text template, replacing a marker.
exception - the exception associated with the event or null if there was none.
See Also:
MessageFormat.format(java.lang.String, java.lang.Object[])

addError

public void addError(int message,
                     java.lang.String[] detail,
                     java.lang.Throwable exception)
This method records an error message to the list of messages

Parameters:
message - the numeric identifier of the message to add, as defined in LogError
detail - a string array of variable fields that should be inserted into the message text. Each array element will be inserted into the text template, replacing a marker.
exception - the exception associated with the event or null if there was none.
See Also:
MessageFormat.format(java.lang.String, java.lang.Object[])

addCustomError

public void addCustomError(java.lang.String template,
                           java.lang.String[] detail,
                           java.lang.Throwable exception)
This method records an error message, using a custom text template. It allows cusom code to insert message text that is not defined in IzPack. IzPack internal code should use the parallel version based on the message index.

Parameters:
template - the basic template for the message
detail - a string array of variable fields that should be inserted into the message text. Each array element will be inserted into the text template, replacing a marker.
exception - the exception associated with the event or null if there was none.
See Also:
MessageFormat.format(java.lang.String, java.lang.Object[])

addDebugMessage

public void addDebugMessage(java.lang.String template,
                            java.lang.String[] detail,
                            java.lang.String channel,
                            java.lang.Throwable exception)
This method provides a channel for debugging messages in IzPack development. Note that debug messages are used solely for this purpose. Adding debug messages does not trigger user notification. If the user should be notified about a specific situation, please also call the appropriate (message, warning, error) method. Debug messages are not localized, please use English only.

In order to prevent flooding developers with messages that are generally of no interest, each message may be associated with a specific channel. A message is associated with a channel simply by providing a channel identifier as call parameter. There is no need for registering channels beforehand. If null or an empty string is used as channel identifier the message will be output, regardless of the channel filter applied. Please use this option sparingly, just for really impotant messages of general interest.

To receive output for select channels, start IzPack with the command line option -DIzPack.debug.channel=, followed by a comma separated list of channel identifiers.

Parameters:
template - the basic template for the message
detail - a string array of variable fields that should be inserted into the message text. Each array element will be inserted into the text template, replacing a marker.
channel - the debug channel the message is associated with.
exception - the exception associated with the event or null if there was none.

messagesRecorded

public boolean messagesRecorded()
Reports if any messages have been recorded.

Returns:
true if any messages have been recorded

warningsRecorded

public boolean warningsRecorded()
Reports if any warnings have been recorded.

Returns:
true if any warnings have been recorded

errorsRecorded

public boolean errorsRecorded()
Reports if any errors have been recorded.

Returns:
true if any errors have been recorded

informUser

public void informUser()
Displays a dialog that informs the user about the fact that one or more unusual events have occurred during installation. If nothing has been recorded, this method returns immediately.


writeReport

public void writeReport()
Presents the user with a dialog to select a file and location for the installation report and writes a report contianing all messages to the user selected file.


writeReport

public void writeReport(java.lang.String file)
Writes a report contianing all messages to the indicated file.

Parameters:
file - the fully qualifies name of the file to write to.

compileReport

private java.lang.String compileReport()
Prepares an installation report from the recorded information

Returns:
the installation report

buildMessage

private java.lang.String buildMessage(int index)
Builds a general installation message from the information contained in the indicated record

Parameters:
index - the index of the requested message entry

buildWarning

private java.lang.String buildWarning(int index)
Builds a warning message from the information contained in the indicated warning record

Parameters:
index - the index of the requested warning entry

buildError

private java.lang.String buildError(int index)
Builds an error message from the information contained in the indicated error record

Parameters:
index - the index of the requested error entry

buildDebug

private java.lang.String buildDebug(int index)
Builds a debug message from the information contained in the indicated debug record

Parameters:
index - the index of the requested debug entry

buildDebug

private java.lang.String buildDebug(Log.Record record)
Builds a debug message from the information contained in a specific debug record

Parameters:
record - the debug record

dumpRecordedChannels

public void dumpRecordedChannels()
Dumps the list of debug channels to stdout that have recorded messages