| java.lang.Object
 com.izforge.izpack.util.Log
| Log | | public class Log implements LogError,LogWarning,LogMessage(Code) | | 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:
- informative/general messages
- warning messages
- 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 |
| Method Summary | |
| public void | addCustomError(String template, String[] detail, Throwable exception)
This method records an error message, using a custom text template. | | public void | addCustomMessage(String template, String[] detail)
This method records a general installation message, using a custom text template. | | public void | addCustomWarning(String template, String[] detail, Throwable exception)
This method records a warning message, using a custom text template. | | public void | addDebugMessage(String template, String[] detail, String channel, Throwable exception)
This method provides a channel for debugging messages in IzPack development. | | public void | addError(int message, String[] detail, 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 incom.izforge.izpack.util.LogError LogError
Parameters:
detail - a string array of variable fields that should be inserted into the messagetext. | | public void | addMessage(int message, String[] detail)
| | public void | addWarning(int message, String[] detail, 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 incom.izforge.izpack.util.LogWarning LogWarning
Parameters:
detail - a string array of variable fields that should be inserted into the messagetext. | | public void | dumpRecordedChannels()
| | public boolean | errorsRecorded()
Reports if any errors have been recorded. | | public static Log | getInstance()
| | public void | informUser()
Displays a dialog that informs the user about the fact that one or more unusual events have
occurred during installation. | | public boolean | messagesRecorded()
Reports if any messages have been recorded. | | public boolean | warningsRecorded()
Reports if any warnings have been recorded. | | 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. | | public void | writeReport(String file)
Writes a report contianing all messages to the indicated file. |
| addCustomError | | public void addCustomError(String template, String[] detail, Throwable exception)(Code) | | 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
Parameters:
detail - a string array of variable fields that should be inserted into the messagetext. Each array element will be inserted into the text template, replacing a marker.
Parameters:
exception - the exception associated with the event or null if there wasnone.
See Also: java.text.MessageFormat.format(java.lang.Stringjava.lang.Object[]) |
| addCustomMessage | | public void addCustomMessage(String template, String[] detail)(Code) | | 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
Parameters:
detail - a string array of variable fields that should be inserted into the messagetext. Each array element will be inserted into the text template, replacing a marker.
See Also: java.text.MessageFormat.format(java.lang.Stringjava.lang.Object[]) |
| addCustomWarning | | public void addCustomWarning(String template, String[] detail, Throwable exception)(Code) | | 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
Parameters:
detail - a string array of variable fields that should be inserted into the messagetext. Each array element will be inserted into the text template, replacing a marker.
Parameters:
exception - the exception associated with the event or null if there wasnone.
See Also: java.text.MessageFormat.format(java.lang.Stringjava.lang.Object[]) |
| addDebugMessage | | public void addDebugMessage(String template, String[] detail, String channel, Throwable exception)(Code) | | 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
Parameters:
detail - a string array of variable fields that should be inserted into the messagetext. Each array element will be inserted into the text template, replacing a marker.
Parameters:
channel - the debug channel the message is associated with.
Parameters:
exception - the exception associated with the event or null if there wasnone. |
| addError | | public void addError(int message, String[] detail, Throwable exception)(Code) | | This method records an error message to the list of messages
Parameters:
message - the numeric identifier of the message to add, as defined incom.izforge.izpack.util.LogError LogError
Parameters:
detail - a string array of variable fields that should be inserted into the messagetext. Each array element will be inserted into the text template, replacing a marker.
Parameters:
exception - the exception associated with the event or null if there wasnone.
See Also: java.text.MessageFormat.format(java.lang.Stringjava.lang.Object[]) |
| addMessage | | public void addMessage(int message, String[] detail)(Code) | | This method records general installation message
Parameters:
message - the numeric identifier of the message to add, as defined incom.izforge.izpack.util.LogMessage LogMessage
Parameters:
detail - a string array of variable fields that should be inserted into the message text |
| addWarning | | public void addWarning(int message, String[] detail, Throwable exception)(Code) | | This method records a warning message to the list of messages
Parameters:
message - the numeric identifier of the message to add, as defined incom.izforge.izpack.util.LogWarning LogWarning
Parameters:
detail - a string array of variable fields that should be inserted into the messagetext. Each array element will be inserted into the text template, replacing a marker.
Parameters:
exception - the exception associated with the event or null if there wasnone.
See Also: java.text.MessageFormat.format(java.lang.Stringjava.lang.Object[]) |
| dumpRecordedChannels | | public void dumpRecordedChannels()(Code) | | Dumps the list of debug channels to stdout that have recorded messages
|
| errorsRecorded | | public boolean errorsRecorded()(Code) | | Reports if any errors have been recorded.
true if any errors have been recorded |
| getInstance | | public static Log getInstance()(Code) | | Returns the only instance of Log
the only instance of Log |
| informUser | | public void informUser()(Code) | | 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.
|
| messagesRecorded | | public boolean messagesRecorded()(Code) | | Reports if any messages have been recorded.
true if any messages have been recorded |
| warningsRecorded | | public boolean warningsRecorded()(Code) | | Reports if any warnings have been recorded.
true if any warnings have been recorded |
| writeReport | | public void writeReport()(Code) | | 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(String file)(Code) | | Writes a report contianing all messages to the indicated file.
Parameters:
file - the fully qualifies name of the file to write to. |
|
|