Plugin Development Guide

From VuzeWiki
Jump to: navigation, search

This is a new work-in-progress guide on how to write a plugin for Azureus.

Introduction[edit]

What things can a plugin do?[edit]

A lot of things. :) For something to technically be a plugin, it just needs to do a couple of things so that Azureus recognises it as one.

Plugins are essentially individual programs which are provided with a mechanism to interact with Azureus. They are Java programs which define an "entry" point to allow Azureus to use it as a plugin. So when we say plugins can do anything - generally speaking, they can. They have the whole of the Java API to interact with.

However, what plugins can do with Azureus is limited to the API's provided. Plugins can add table columns, menu items, present new views of information, generate config sections, manage downloads (including adding new ones), change settings, write extension messages to communicate with other peers, interact with other plugins - doing a lot of things which Azureus does).

Azureus doesn't just provide a large number of methods to interact with it, it also provides a large number of convenient utilities - like the ability to prompt the user for information (regardless of what interface the user might be using), a generic downloader facility (being able to download from HTTP, handling authentication, downloading from BitTorrent, specifying retry mechanisms)...

How do I know what's available to me?[edit]

The best guide at the moment is the Javadoc documentation that is available. The best approach to have is to decide what you want your plugin to do, and then see if Azureus provides you a way to do it. You can also post in the forum if you have any questions.

What if Azureus doesn't provide me with a way to do what I want?[edit]

Again, on the forum. Since I started writing plugins in Azureus, I have extended the plugin API so that plugins have a lot more control over many things. If you think the plugin API is lacking anything (either minor or major changes), you can make requests in the forum to be added.

How do I get started?[edit]

Prerequisites[edit]

To get started, you will need to be able to program in Java and have a decent Java editor - if you're not familiar with writing Java programs, you will probably struggle. If you've programmed in an object-orientated language before, you might find that it's not too difficult to program in Java.

As for choice of Java IDE to use - I'll leave that you. A lot of the Azureus developers use Eclipse (you can see a guide of how to start modifying the Azureus source with Eclipse here).

Dependencies[edit]

When you write your plugin, you will need to compile against the Azureus code itself, which is provided in a single JAR file. You need to use either the main Azureus2.jar file or a JAR file containing just the interfaces which make up the plugin API (both of which are available here).

If you write any plugins which need to interact with SWT objects, then you will need to use the swt.jar file that is in the Azureus directory too.

Step-by-step guide[edit]

This section describes gradual development of an example plugin, which includes more and more functionality. It's not necessary for you to follow all steps to know how to write a plugin, but later sections may refer to previous sections.

Rather than naming the plugin something like "ExamplePlugin", I've called it Aizen, because Aizen wears glasses, and you can trust a man with glasses...

Getting prepared[edit]

  1. Preparing an environment in Eclipse.
  2. Writing a blank plugin.
  3. Running the plugin.
  4. Building the plugin.

The basics[edit]

  1. How plugins work with Azureus.
  2. Storing data and changing config settings.
  3. Defining plugin text.
  4. Creating a configuration page.
  5. Alerts and logging.

User Interface (basic)[edit]

  1. Adding menus.
  2. Adding table columns.

Downloads[edit]

  1. Adding download listeners.
  2. Manipulating download objects.
  3. Manipulating torrents.
  4. Storing values on objects.
  5. Adding torrents and downloads.

General[edit]

  1. More uses of listener objects.
  2. The utilities library.

User Interface (advanced)[edit]

  1. More interesting things to do with menus and tables.
  2. Getting text input and sending messages to users.
  3. Providing interface-specific behaviour.
  4. Creating a status entry.
  5. Creating log views and using views.

Advanced[edit]

  1. Threading.
  2. Generic resource downloading / uploading.
  3. Extension messaging - sending messages between peers.
  4. Plugin-to-plugin communication.