Migrate Plugin Data

Now your plugin is used by a lot of users and they've configured your plugin and used steps contributed by your plugin. This leads to a problem: you might need to change fields of plugin setting and step classes in new version of your plugin and the change could be incompatible with existing steps and plugin settings. We certainly do not want to have users re-define their steps and plugin settings.

To solve this problem, QuickBuild utilizes XMT to handle plugin data migration. Taking the plugin setting class in Working with Plugin Settings chapter for example, let's assume that we want to introduce a non-empty suffix field in new version of our plugin. The new plugin setting class can be written as:

package com.example.myplugin;

import org.hibernate.validator.NotEmpty;
import com.pmease.quickbuild.annotation.Editable;

// Plugin setting class must contains a default constructor
public class MyPluginSetting {
	
	private String prefix;

        private String suffix;

	@Editable(description="Specify a message prefix here.")
	@NotEmpty
	public String getPrefix() {
		return prefix;
	}

	public void setPrefix(String prefix) {
		this.prefix = prefix;
	}
	
	@Editable(description="Specify a message suffix here.")
	@NotEmpty
	public String getSuffix() {
		return suffix;
	}

	public void setSuffix(String suffix) {
		this.suffix = suffix;
	}

	@SuppressWarnings("unused")
	private void migrate1(VersionedDocument dom, Stack<Integer> versions) {
		dom.getRootElement().addElement("suffix").setText("thanks");
	}
}

The method migrate1 handles migration of the class from version "0" to version "1", and plugin setting created previously will automatically have the suffix set to "thanks". This migration approach also applies for step and repository classes contributed by the plugin. For details of migration, please refer to XMT documentation.

At last, do not forget to increase version of your plugin so that QuickBuild can detect the change and propagate new version of your plugin to all agents. Plugin version can be changed by editing plugin MANIFEST in Eclipse like below:

danger

During upgrade of your plugin, the old version also needs to be removed from directory <QuickBuild server install dir>/plugins .