PluginDevGuide Creating

From VuzeWiki
Jump to: navigation, search

Plugin Development Guide: Writing a blank plugin[edit]

For this step, we'll show you how to create the bare minimum required to actually create a plugin.

Required files[edit]

To create a plugin, you strictly need two files. Ideally, at least three. :)

  • The plugin class - the main entry point for the plugin itself.
  • plugin.properties - this sits in the root of the JAR file, which describes the plugin.
  • A language properties file. Not essential if your plugin doesn't display any text anywhere (or you want to use hardcoded text everywhere), but we generally would encourage the use of a properties file to allow your plugin to be internationalised.

The two properties files are just text files which define key-value mappings (more information here).

OK, let's get started.

Step-by-step[edit]

  • First of all, the plugin class. You need to create a package for your plugin class to live in.

PluginDevGuide Creating 1.png

  • We'll use azplugins.aizen in this example. I'm not suggesting that you use this naming scheme for your plugins - it doesn't event follow Sun's own recommendation about naming schemes - but the choice is up to you. Something relatively unique is recommended.

PluginDevGuide Creating 2.png

  • Now to create the plugin class.

PluginDevGuide Creating 3.png

  • You can call your plugin anything you like (here, we've gone for AizenPlugin). Your plugin class needs to implement the org.gudy.azureus2.plugins.Plugin interface. I've checked the "inherit abstract methods" option here, so that the required method definition is already prepared for us when its created.

PluginDevGuide Creating 4.png

  • There's our plugin class! And, as it happens, it's actually usable as a plugin already. It won't actually do anything, but it just defines the required initialisation method.

PluginDevGuide Creating 5.png

  • Create a text file in the root of the project, and call it plugin.properties. You won't be able to save the file if it's empty (in Eclipse), so you can just put a hash (#) character in the file (which serves as a comment character).
  • Now for the optional messages properties file. Although it's optional (and not needed this early), I'll recommend creating it now. There's no strict rules about where it should live, but I would suggest in a subpackage of the main class package - I've chosen azplugins.aizen.messages.
  • You can call the file whatever you want, as long as it ends with .properties. My own convention is just to call it Messages.properties.
  • Once we've created these files, your project will look something like this:

PluginDevGuide Creating 6.png

Defining plugin properties[edit]

The plugin class is defined, but none of the properties describing the plugin have been done yet - that's handled through the plugin.properties file - an more extensive explanation of what can be defined in the properties file can be found here.

We'll put the following data into the plugin.properties file:

plugin.class=azplugins.aizen.AizenPlugin
plugin.id=aizen
plugin.name=Aizen - Example Plugin
plugin.version=0.1
plugin.langfile=azplugins.aizen.messages.Messages

plugin.class[edit]

The class file which implements the Plugin interface.

plugin.id[edit]

A short string which will be the internal name for the plugin. This internal name gets used for various things by Azureus (it's used as a prefix for config settings used by the plugin, for example). Don't include the .java or .class file extension.

plugin.name[edit]

A user-readable name for the plugin - this gets displayed in a few different places (like the Plugins page).

plugin.version[edit]

The plugin version. The numbering scheme should be of the form <number>.<number>.<number> (as many components as you want) - as long as it increases from version to version. A version of 0.9 is smaller than 0.10.

plugin.langfile[edit]

The location of the language resource file (don't include the .properties file).

And when that's done....[edit]

You've got a plugin! But you haven't built or run it yet, that's covered in the next step...