Plugin class implementation

From VuzeWiki
Jump to: navigation, search

Plugin Interface Documentation[edit]

The plugin interface documentation can be found online at Plugin Interface JavaDoc for the last release and the CVS Plugin Interface JavaDoc.

With Java editors that integrate javadoc, a faster alternative is to grab the source and attach it to your reference to the azureus2 (plugin) jar.

The Basics[edit]

The plugin interface lives in the packages under org.gudy.azureus2.plugins, as well as org.gudy.azureus2.ui.swt.plugins for Azureus versions 2.3.0.5 and higher.

Your very first class should implement the Plugin class or one of its subinterfaces (UnloadablePlugin and LaunchablePlugin). UnloadablePlugin is preferred to Plugin.

In order for Azureus to find your plugin, you need a file named plugin.properties located in either your JAR or the same directory as your JAR. You must set the key "plugin.class" to be equal to the fully qualified path to your class that implements the Plugin class (or one of it's subinterfaces). See Plugin requirements for more properties that can be set.

Plugin.initialize(..): Your key to the Plugin Interface[edit]

The required initialize method passes you your key to the plugin interface as a parameter. Almost all plugin functionality is returned from the PluginInterface.

The JavaDoc's PluginInterface exposes very nicely what you can do. Most of the functions return another interface object that manages a part of Azureus.

The Plugin API jar[edit]

To compile your plugin, you must attach the Plugin API jar (About 405k) to your project -- the link is the CVS version of the Plugin API; be very mindful of the @since tag in the JavaDocs. Alternatively, if you are compiling or have the Azureus source, you may use that instead, but you will be flooded with Azureus core classes in the auto-complete windows.

If you use any SWT functionality, you will also need to attach swt.jar to your plugin project. Try to use the same SWT jar that Azureus uses. If you download SWT from eclipse, you can attach src.zip to swt.jar in most IDEs for autocompletion. (For the Eclipse IDE, right-click on swt.jar after adding it and choose properties. Go to "Java Source Attachment" and enter the path to src.zip.)

UnloadablePlugin[edit]

A plugin can implement the UnloadablePlugin interface instead of Plugin to signal Azureus that it can be unloaded during runtime. To ensure that the garbage collector can unload the plugin classes it is important that all external references to instances of plugin classes are removed and plugin threads (including hidden ones, e.g. those in timers) are closed. All listeners, UI objects and other plugin objects (e.g. external peers) registered in the core through the plugin interface must be unregistered or otherwise be disposed of to eleminate all references to plugin objects.

Embedding Azureus[edit]

If you want to embed Azureus in another Java application this can be done as per the following example code (note that the app+user+doc properties were added in 4901-B33, prior to this you would need to set the "azureus.config.path" and "azureus.install.path" (and "user.dir") system properties by hand). This gives you access to a default plugin interface that can then be used to interact with the plugin API as usual.


	public static void
	main(
		String[]	args )
	{
		Properties props = new Properties();
		
		File	az_dir = new File( "C:\\temp\\aztest" );
		
		props.put( PluginManager.PR_APP_DIRECTORY, az_dir.getAbsolutePath());
		props.put( PluginManager.PR_USER_DIRECTORY, az_dir.getAbsolutePath());
		
		File	doc_dir = new File( "C:\\temp\\aztest\\data" );

		props.put( PluginManager.PR_DOC_DIRECTORY, doc_dir.getAbsolutePath());

		PluginManager pm = PluginManager.startAzureus( 
			PluginManager.UI_NONE,
			props );
		
		final PluginInterface pi = pm.getDefaultPluginInterface();
		
		pi.addListener(
			new PluginListener()
			{
					public void
					initializationComplete()
					{
						Download[] downloads = pi.getDownloadManager().getDownloads();
						
						for ( Download d: downloads ){
							
							System.out.println( "Download: " + d.getName());
						}
					}
					
					public void
					closedownInitiated()
					{
						
					}
					
					public void
					closedownComplete()
					{
						
					}
		});
			
	}

Note that by default Azureus will try to instantiate platform-specific native support and will log an error if this isn't available. For windows, for example, this requires "aereg.dll" to be available on the library path. To disable this add the property:

		props.put( PluginManager.PR_DISABLE_NATIVE_SUPPORT, "true" );