Changes between Initial Version and Version 1 of DevelopersGuide/PluginInstallationWithoutRestart

Timestamp:

2015-02-12T17:05:36+01:00 (11 years ago)

Author:

bastiK

Comment:

initial doc

DevelopersGuide/PluginInstallationWithoutRestart

@@ +1 @@
+= Plugin installation without restart =
+
+Since version r8024, JOSM can load plugins at runtime. This means that after [wiki:Help/Preferences/Plugins#Installingplugins installation], there is no need to restart, but the plugins can be used immediately. However, this only works for plugins that support this new feature.
+
+== Make plugins ready for installation without restart ==
+
+To indicate to JOSM that the plugin has full support for installation without restart, add the following attribute to the plugin Manifest file:
+{{{
+Plugin-Canloadatruntime=true
+}}}
+If you are using the `build-common.xml` file in your `ant` build script, the corresponding ant-property is:
+{{{
+<property name="plugin.canloadatruntime" value="true"/>
+}}}
+
+When this flag is set, JOSM will not prompt the user for restart and will attempt to load the plugin by:
+1. Calling the Plugin Constructor
+2. Calling the `mapFrameInitialized` method in case a `MapFrame` is currently present.
+
+== Required code changes ==
+
+''So what do you need to change in the plugin source code?'' If you're lucky, nothing at all. The most common ways, a plugin interacts with JOSM work ''without'' adaption:
+* Adding a menu entry to the main menu in the plugin Constructor
+* Adding MapModes or ToggleDialogs to the MapFrame in the `mapFrameInitialized` method
+* Adding a preferences tab to the preferences in the `getPreferenceSetting` method
+
+An example, where an adaption ''would'' be necessary, are layer change listeners. Until now, the order was:
+1. Run plugin constructor
+2. Start JOSM GUI
+3. Add MapFrame, run plugin's `mapFrameInitialized` method
+4. Add Layer, run plugin's layer change listeners (if registered)
+
+Now it can also be
+1. Start JOSM GUI
+2. Add MapFrame
+3. Add Layer
+4. Install plugin
+5. Run plugin constructor
+6. Run plugin's `mapFrameInitialized` method
+
+So basically you may miss a call to the layer change listener because the layers are already there when the plugin is loaded. This can usually be fixed by calling the listener one time explicitly after it has been registered.
+
+== How to test ==
+
+One problem with testing the installation, is that JOSM will keep downloading the plugin binary from the server, instead of using the locally compiled one copied to the plugin directory. Here are two ways to circumvent this:
+1. You can rename the plugin for the purpose of testing. Then JOSM will not find any information on this plugin and will be forced to load the compiled binary.
+2. Alternatively, make sure the version number of the compiled plugin matches the one of the plugin downloaded from the server. Then JOSM will not download and replace the plugin, but use the "cached" binary.
+
+