Plugin Development Guide: Writing a blank plugin
For this step, we'll show you how to create the bare minimum required to actually create a plugin.
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.
- First of all, the plugin class. You need to create a package for your plugin class to live in.
- 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.
- Now to create the plugin class.
- 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.
- 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.
- 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:
Defining plugin properties
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
The class file which implements the Plugin interface.
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.
A user-readable name for the plugin - this gets displayed in a few different places (like the Plugins page).
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.
The location of the language resource file (don't include the .properties file).
And when that's done....
You've got a plugin! But you haven't built or run it yet, that's covered in the next step...