Development
Version as of 05.08.2009 22:19:50
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:
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:
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:
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:
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.