From AzureusWiki

Plugin Development Guide: Alerts and Logging

We're going to introduce two concepts here - "logging" and "alerts". We group them together because they are part of the same mechanism. And that's done through the mechanism of LoggerChannel objects...

LoggerChannel

A plugin can create a logging channel. This becomes the device the plugin uses to log information to (for both debugging and informative purposes). You can create as many channels are you like, but we'll manage with just one. We use the Logger object to create a LoggerChannel object.

 LoggerChannel channel = plugin_interface.getLogger().getLoggerChannel("aizen");

That's all there is to it. Now how to create alerts with it.

Alerts

Before we begin, let's introduce you to Mr Slidey:

Mr Slidey is the informal name that the Azureus developers use for the popup alert mechanism to notify the user about something, though the user may have configured different behaviour.

To log an alert, you can use some of the logAlert methods on the LoggerChannel object. Alerts generally consist of three or four pieces of information:

• The message text (any text localisation needs to be done beforehand).
• The alert type - information, warning or error.
• Whether the message is repeatable or not. By default, alerts are only shown once. If you log the same alert (with the same text repeatedly), it will only show it once. Azureus will automatically filter duplicate messages out. If you do need to alert the user repeatedly with the same message, you need to use to the logAlertRepeatable method.
• A Throwable object - this is only if you want to popup an alert with some context information to the user. This will then create a Details button on Mr Slidey to then display it to the user.

So, the code we need to generate the alert we saw earlier is this:

 channel.logAlert(LoggerChannel.LT_INFORMATION, "Hello, I'm Mr Slidey!\nPleased to meet you. :)");

(If we were doing things properly, this text wouldn't be hardcoded, it would be defined in a MessageBundle.)

Displaying Alerts

Although it might be possible (using some GUI libraries) to pop up a message in a different way, it's recommended you use the alert system, because it adheres to using what the user has configured.

For example, although the default behaviour would generate this:

But they may have turned off the auto-closing behaviour for popup alerts...

And might have decided to include a timestamp for their alerts...

Or maybe they don't use Mr Slidey, and just use a normal message box instead...

Or maybe they don't want alerts to pop-up at all...

Or maybe they're not using the normal Azureus GUI, and using the console instead...

Or perhaps they're using an external plugin to provide alerts...

So logging an alert to inform the user about something is the best way to make sure that you adhere to the user's wishes about how they want to be notified.

Using Alerts - an example

Let's make some use of alerts in our plugin. We'll add some code which prevents the download speed being to a value smaller than 5 kbps (we'll define a new method to contain this logic).

 public void setDownloadSpeed(int value) {
   try {
     if (value < 5) {
       throw new Exception("Cannot set speed below 5 kbps.");
     }
     plugin_config.setCoreIntParameter(
       PluginConfig.CORE_PARAM_INT_MAX_DOWNLOAD_SPEED_KBYTES_PER_SEC, value);
   }
   catch (Exception e) {
     logger_channel.logAlertRepeatable("Error while trying to set download speed.", e);
   }
 }

Now, what happens if we try to set the speed to 2 kbps?

As you can see, the user is notified of the error, and as we logged an exception - the full stacktrace is available in the "Details" section.

Logging

This bit is yet to be done.