PluginDevToolkit: the dynamic plugin loader for developersHello SH3D developers! While writing my plugins the code become a bit complex, and sometime it required a trial and error approach. The major drawback using this method is that every small change to the code requires exporting the project as jar into the plugins folder and restart SH3D, which could be a big waste of time because of the splash screen and eventually loading a large test home from the disk... not taking into account for temporary changes to the home that would be lost, camera positioning, and so on. Before starting to write my last plugin I decided to create a system to overcome these limitations. The system worked like a charm, and I've extensively tested it almost for a month while working to the Wirings plugin, so I decided to share it to help the plugins ecosystem growing faster
.Integrating the system into existing plugins is a matter of minutes.
First you have to setup your plugin project as described in the plug-in developer's guide, completing the Debugging the plug-in step in order to have a working run configuration. If you experience trouble with this step see the troubleshooting section at the end of this post.
Once you have a working run configuration follow these simple steps:
- Download PluginDevToolkit.zip
- Right click on the src folder of your project, select Import..., General > Archive file, select the file you downloaded at the previous step and click Finish.
- Create a new class named YourPluginLoader which extends DynamicPluginLoader and override its constructor aswhere YourPlugin is the real plugin class, and your.package is the package name.
public YourPluginLoader() {
super("your.package.YourPlugin", new String[] {"your.package"});
} - Edit the ApplicationPlugin.properties and change the value of the class parameter to the fully qualified name of the class you created in the previous step (eg. your.package.YourPluginLoader).
- Build your .sh3p package just once and place it in the SH3D plugins folder.
- Add to your run configuration a Java property named plugin.classpath pointing to the absolute path of the output folder of your class files. To do this, go to Arguments tab and put the following line in the VM arguments field:
-Dplugin.classpath="${workspace_loc}\your_project\bin"
When you're ready to release your plugin to the public there is no need to remove the customizations, you can safely leave them in place,
but don't forget to rebuild the sh3p package before distributing it!
Lifecycle management
To avoid unexpected results when reloading the plugin at runtime, you should correctly implement the plugin lifecycle management by overriding the init() and destroy() methods in your real plugin class. Everytime a change is detected in class files, the DynamicPluginLoader calls the destroy() method to let you release any allocated resource; your plugin is then replaced by a fresh new instance of the new class and the init() method is called to let you initialize your plugin.
Limitations
- If you add or remove a PluginAction from the values returned by getActions() method, you have to rerun your configuration before the change takes effect. Existing actions will be updated in a seamless way.
Examples
You can download this example which is the VolumePlugin proposed in the developer guide already configured to work with the PluginDevToolkit, you just have to add the SweetHome3D-x.y.jar from your local filesystem. Try to change the output unit from m3 to liters while the SH3D is running!
Troubleshooting
If you didn't succeed to run SH3D from Eclipse getting the following exception:
Exception in thread "AWT-EventQueue-0" java.lang.NullPointerException: Cannot invoke "com.jogamp.nativewindow.awt.AWTGraphicsConfiguration.getAWTGraphicsConfiguration()" because "<local3>" is nullHope you have nice times developing SH3D plugins!
Cheers!
