Working with Plugin Settings

Global plugin setting

Plugin might have settings global to the system. For example, the Ant plugin defines path to Ant executable in the global plugin setting. In this tutorial, we will continue to evolve myplugin to define a message prefix in the plugin setting so that all user specified messages are automatically prefixed with certain string.
First let's define the plugin setting class MyPluginSetting.java:

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;

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

	public void setPrefix(String prefix) {
		this.prefix = prefix;
	}
	
}

And then tell QuickBuild about this class by modifying MyPlugin.java as below:

... // omitted for brevity

public class MyPlugin extends AbstractPlugin {

	@Override
	public Object[] getExtensions() {
                ... // omitted for brevity
	}

	@Override
	public Class<?> getSettingClass() {
		return MyPluginSetting.class;
	}

}

Finally we modify MyAnotherStep.java to make use of the prefix:

... // omitted for brevity
public class MyAnotherStep extends Step {

        ... // omitted for brevity

	@Override
	public void run() {
		// You may also get the plugin setting object through PluginSettingHelper 
		MyPluginSetting pluginSetting = (MyPluginSetting) getPlugin().getSetting();
		Context.getLogger().info(pluginSetting.getPrefix() + ": " + getMessage());
	}

}

Now start QuickBuild and it prints a warning message complaining that plugin com.example.myplugin needs to be configured. The plugin will temporarily be disabled if stored plugin setting object vilolates constraints of the plugin class. For newly installed plugins, the plugin setting object is initially created by calling default constructor of the plugin setting class.
Run the root configuration, and you will see that all messages will start with the specified prefix.

Refer to Bean Editor for more information of how to annotate plugin setting class to generate appropriate UI.

Configuration level plugin setting

Configuration level plugin setting is defined at configuration level. The setting will be inherited from parent configuration if it is not defined. Continue with myplugin, now assume that we need to specify message prefix per configuration, we can then modify MyPlugin.java as below:

... // omitted for brevity
public class MyPlugin extends AbstractPlugin {

	@Override
	public Object[] getExtensions() {
                ... // omitted for brevity
	}

        /*
	@Override
	public Class<?> getSettingClass() {
		return MyPluginSetting.class;
	}
        */

	@Override
	public Class<?> getConfigurationSettingClass() {
		return MyPluginSetting.class;
	}

}

Also please modify MyPluginSetting.java to provide a description:

... // omitted for brevity	
@Editable(description="Specify plugin setting for myplugin.")
public class MyPluginSetting {
        ... // omitted for brevity	
}

Finally modify MyAnotherStep.java to make use of the configuration level prefix:

... // omitted for brevity
public class MyAnotherStep extends Step {

        ... // omitted for brevity

	@Override
	public void run() {
		// You may also get the plugin setting object through PluginSettingHelper 
		MyPluginSetting pluginSetting = (MyPluginSetting) getPlugin().getSetting(Context.getConfiguration());
		Context.getLogger().info(pluginSetting.getPrefix() + ": " + getMessage());
	}

}

Save above classes, start QuickBuild, and edit advanced setting of the root configuration. You will see that the advanced setting of the configuration includes a section contributed by myplugin as below:

All child configurations will by default inherit myplugin setting and can choose to override it by enabling myplugin setting.

Run the root configuration, and you will see that all messages will start with the prefix specified at root configuration level.

Refer to Bean Editor for more information of how to annotate plugin configuration setting class to generate appropriate UI.

User level plugin setting

Now we change the plugin setting from configuration level to user level: users define their own prefixes in the profile and printed message will start with the user specific prefix. To do so, first modify MyPlugin.java as below:

... // omitted for brevity
public class MyPlugin extends AbstractPlugin {

	@Override
	public Object[] getExtensions() {
                ... // omitted for brevity
	}

        /*
	@Override
	public Class<?> getSettingClass() {
		return MyPluginSetting.class;
	}     

	@Override
	public Class<?> getConfigurationSettingClass() {
		return MyPluginSetting.class;
	}
        */

	@Override
	public Class<?> getUserSettingClass() {
		return MyPluginSetting.class;
	}

}

To make use of the user level prefix, please modify MyAnotherStep.java as below:

... // omitted for brevity
public class MyAnotherStep extends Step {

        ... // omitted for brevity

	@Override
	public void run() {
		if (Context.getUser() != null) {
			// You may also get the plugin setting object through PluginSettingHelper 
			MyPluginSetting pluginSetting = (MyPluginSetting) getPlugin().getSetting(Context.getUser());
			Context.getLogger().info(pluginSetting.getPrefix() + ": " + getMessage());
		}
	}

}

Save above modifications, start QuickBuild, and switch to my setting page. It will include a section contributed by myplugin as below:

Run the root configuration, and you will see that all messages will start with the prefix specified by current user.

Refer to Bean Editor for more information of how to annotate plugin user setting class to generate appropriate UI.

Group level plugin setting

Group level plugin setting is very similar to user level plugin setting, except that:

1. It is attached to each group and will be displayed and edited if you view or edit particular group.
2. The setting class is specified by overriding method getGroupSettingClass
3. The setting object can be retrieved by calling PluginSettingHelper.getPluginSetting(<Plugin Main Class>, <group instance>)

Refer to Bean Editor for more information of how to annotate plugin group setting class to generate appropriate UI.

Combine different levels of plugin settings

Different levels of plugin settings can be combined together. The plugin com.pmease.quickbuild.plugin.notifier.msn in Plugin Examples demonstrates this:

• It includes a global plugin setting class MsnSetting.java to define MSN account used to login and send out build notifications through MSN messenger.
• It includes an user level plugin setting class MsnUserSetting.java to define MSN account for each user, which will be used to receive build notifications sent out by QuickBuild server through MSN messenger.