Startpage - All pages - Edit - Show Properties - Create new page - Help - Login / Sign in

Development


Version as of 16.06.2007 21:03:51

Writing Plugins

Plugin types

There are 3 types of plugins. DataPlugins, FilePlugins and GeneralPlugins. DataPlugins are all the plugins, which fetch the metadata from different sources like the filename, the filetag or sources in the web like musicbrainz.
Through FilePlugins JMP3Renamer gets the capability to open files with the according suffix and to read and write meta information. Let's have a look at the Mp3-Plugin. Is it installed, JMP3Renamer can open Mp3s and read and write ID3-Tags (Version 1.1 and 2.3).
The last type are GeneralPlugins. They extend the functionality of JMP3Renamer in a general way. All plugins, which are no Data- or FilePlugin are GeneralPlugins.
The three types of plugins are represented by the three interfaces DataPlugin, FilePlugin and GeneralPlugin. Your own plugin has to implement one of these interfaces.

Constructor

Since the plugins are loaded dynamically, there is no constructor we can use to set things up. Instead each plugin has to implement the method init(), which acts like a constructor. For example the init() of the Lame Encoder plugin:
 

Properties

If your plugin shall support properties, which can be adjusted by the user, you should implement the methods getConfig() and saveConfig(). It's on you, how to save the properties, but it is a good idea to save the properties in the user home directory. Have a look at the existing plugins to get a clue how to do that. If the user should be able to change these properties through the settings dialog you also have to implement getConfigGUI() and return a GUI object. If you don't want that, you can return null. Make sure, that you always read the roperties via getConfig(), so that changes of the properties are applied immediately. Don't store one of the properties in local variable.

Naming conventions

To write your own plugin you have to follow some naming conventions. Otherwise JMP3Renamer is not able to load your plugin. The main class of your plugin has to belong to a package net.sf.jmp3renamer.plugins.<Main Class>
So, let's assume to write a plugin named ExamplePlugin. The first few lines of code have to look like this:
 
If you think, you are ready to test your plugin, create a jar file of it named like the main class. In our example that would be. Copy it to the plugin directory of JMP3renamer and start JMP3Renamer. ExamplePlugin.jar

Internationalization (I18N)

To make your plugin multilingual, you have to extend AbstractTranslatablePlugin. Our example plugin would look like this:
 

Logging

You should use the Logging system of JMP3Renamer to log debug and error messages. All you have to do is, to create a logging object for each class:

 
Then you can use the five logging methods debug(), info(), warn(), error() and fatal()
For example: logger.debug("This is a debug message");
All messages should appear on stdout / the logging file and the DebugConsole window, which can be accessed via the Help-Menu. All messages, which are logged through error() or fatal() will also appear in a popup window.

Accessing the files

You can access the selected files via the FileManager. The FileManager is implemented as a singleton, so you may access it from everywhere with the following statement: FileManager.getInstance();. If you want to get informed about changes of the files you can register an observer: FileManager.getInstance().addObserver(observer);. Your plugin or a class of your plugin has to implement the Observer interface.

Accessing the metadata

Analog to the FileManager, there is the DataManager, which holds all collected metadata. You may register an observer, too.

Troubleshooting

If your plugin doesn't load and java is saying something about invalid class version numbers or something like that, make sure, that you have compiled JMP3Renamer and your plugin with the same JDK version.