FreenetWiki: How to create a Thaw plugin

How to create a Thaw plugin

Required

You need a working jdk (>= 1.4) and Ant. It's recommended to know well how Thaw works see from the user side.

Get Thaw source and javadoc

Firstly, you must get the source code. I think the best way is to use the subversion repository:

 $ svn co https://emu.freenetproject.org/svn/trunk/apps/Thaw Thaw

To generate the javadoc:

 $ ant javadoc

Compile and test Thaw

To make the jar (the jar name is in bin/Thaw.jar):

 $ ant

To wipe out the previous build:

 $ ant clean

And now, how to implements a plugin

Thaw plugin mechanism is quite simple, but one of the restrictions is that plugins must be in the classpath when Thaw is started. So the easiest way to distribute your plugin is to try to ask to add it in the official distribution (see below).
All the plugins must implements thaw.core.Plugin, and all the plugins should be in the package thaw.plugins (or a sub-package).

Here is thaw.core.Plugin:

package thaw.core;

/**
 * Define what methods a plugin must implements.
 * Only default constructor will be called, but the recommandation is to not use it.
 */
public interface Plugin {


	/**
	 * Called when the plugin is runned.
	 * @param core A ref to the core of the program.
	 * @return false means that plugin has troubles and should not be considered as running.
	 */
	public boolean run(Core core);


	/**
	 * Called when the plugin is stopped (often at the end of the program).
	 * @return false means that plugin has troubles and should not be unload.
	 */
	public boolean stop();


	/**
	 * Gives plugin name. The same name as used for the tabs is recommanded.
	 * Result of this function is used only to inform user.
	 */
	public String getNameForUser();

}

Quite simple, isn't it ? :)
When the plugins are loaded/runned, the function run() is called, with the Thaw core as parameter. stop() is called when the plugin must be stopped.
getNameForUser() is purely informal: In the configuration panel, it's the text displayed just after the plugin classname (don't use non-english characters please).
When the configuration is changed by the user (=> using by the config panel), plugins are stop()-ed and then run()-ned.

run() function must return quickly. If you need to have code running all the time, use threads (cf thaw.core.ThawThread). It's the same for stop() (except you must stop the threads :p).

The reference to the core should give you access to 90% of the application. For example you should be able to access to the whole ThawFCPImplementation. One of the only thing that plugins can never touch is i18n (you can use it, but not modify on-the-fly the i18n settings). It can't be changed on-the-fly without troubles. You can look at the Javadoc (starting from the Core) to see what you can reach.

If you need some accessors which don't exist currently, just ask for it on the thaw mailing list, or on Frost.

Update:
Since 0.6.2 (fixed version), the Thaw plugin manager has a predefined plugin list. If you want to start your plugin from it, you must add in src/thaw/core/PluginManager.java the class name of your plugin. Another solution is to edit your thaw.conf.xml and add it.

How to add your plugin in the official distribution

If your plugin and you meet the following conditions, it could be accepted in the official distribution :

Easy to use: Once it's loaded, the user interface must be clear.
User interface must support window resizing.
Must not be a plugin for leechers or spammers.
You must be ready to maintain it : So you will have to follow what is said on the mailing-list and Frost, and must look at the bugtracker regularly.
Try to make the code clean.

In any case, the Freenet Project team will always have the last word.