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

Development



This guide is outdated. JMP3Renamer now uses OSGi for its' plug-in system.

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. If it's 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:

public void init() {
    loadConfig();
    loadLanguage();
    gui = new LamePanel();
    configGui = new LameConfigPanel();
    FileManager.getInstance().addObserver(this);
}

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 shall 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:

package net.sf.jmp3renamer.plugins.ExamplePlugin;
 
import net.sf.jmp3renamer.Plugin;
import net.sf.jmp3renamer.GeneralPlugin;
import net.sf.jmp3renamer.gui.PluginConfigGUI;
 
public class ExamplePlugin implements GeneralPlugin {
    ...   
}

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 ExamplePlugin.jar. Copy it to the plugin directory of JMP3renamer and start JMP3Renamer.

Internationalization (I18N)

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

package net.sf.jmp3renamer.plugins.ExamplePlugin;
 
import net.sf.jmp3renamer.AbstractTranslatablePlugin;
import net.sf.jmp3renamer.Plugin;
import net.sf.jmp3renamer.GeneralPlugin;
import net.sf.jmp3renamer.gui.PluginConfigGUI;
 
public class ExamplePlugin extends AbstractTranslatablePlugin implements GeneralPlugin {
    ...   
}

Logging

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

public class ExamplePlugin extends AbstractTranslatablePlugin implements GeneralPlugin {
 
    private static transient Logger logger = LoggerFactory.getLogger(ExamplePlugin.class);
    ...
}
 

Then you can use the five logging methods trace(), debug(), info(), warn() and error()
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() will also appear in a popup window.

For more details on slf4j visit the slf4j homepage.

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.