PluginDevGuide Logging

From VuzeWiki
Jump to: navigation, search
You can download the code for this tutorial here. The JAR file can be opened in any program which can open up ZIP files, and contains both the compiled code and the source code.
Version: 0.5
Link: Download
Description: Plugin with popup alerts and logging

Plugin Development Guide: Alerts and Logging[edit]

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[edit]

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[edit]

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

PluginDevGuide Alerts 1.png

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[edit]

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:

PluginDevGuide Alerts 1.png

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

PluginDevGuide Alerts 2.png

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

PluginDevGuide Alerts 3.png

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

PluginDevGuide Alerts 4.png

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

PluginDevGuide Alerts 5.png

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

PluginDevGuide Alerts 6.png

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

PluginDevGuide Alerts 7.png

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[edit]

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?

PluginDevGuide Alerts 8.png

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[edit]

This bit is yet to be done.