5.265 Controlling Lifecycle

Plugin control is currently in Beta. Interfaces may change significantly in future releases.

At times a plugin developer may wish to modify the current state of a plugin or even create plugins programatically. This may be done with the Plugin Control Service. Operations exist on the service to:

create plugin instances dynamically with specific configuration.
retrieve plugin instances by ID or based on configuration properties.
start or stop plugin instances.
verify plugin instance configuration.

Creating plugins

Several methods are provided to allow on-the-fly creation of new plugins. Generally, they allow a plugin with a specific ID and plugin type (as a string or as a Groovy Class) to be created with optional configuration properties. These properties should match the fields in Plugins.

If any configuration properties are omitted, the defaults will be used as described in Setting Default Plugin Configuration. A boolean value is also returned indicating whether the creation succeeded or not.

Note that the createPlugin methods will initialize the plugin for retrieval or usage and attempt to start the plugin if the autoStart property is true.

Retrieving plugins

Plugins may be retrieved by using an ID, querying by plugin type, or even querying based on configuration parameters. Several methods are provided to perform these functions as shown on Plugin Control Service.

Starting and stopping plugins

Plugins may also be started or stopped on demand. These two methods are exposed directly as start and stop on the plugin control service. Although each method does not return any data, exceptions are thrown if errors are encountered.

Verifying plugin configuration

Finally, the plugin control service may be used to verify plugin configuration at any point instead of just when the plugin is started or modified. This may be useful to attempt to modify plugin configuration directly through the setConfig dynamic method (see Dynamic Methods) and then verify that the new configuration is valid for the plugin. Exceptions are thrown if the plugin or the configuration is invalid.

Examples

If an error state is detected it may be necessary to stop the current plugin instance until corrective action can be taken. This may be done using the following code:

package example
            
import com.adaptc.mws.plugins.*

class ErrorPlugin {
	IPluginControlService pluginControlService

	public void poll() {
		// Error is detected, stop plugin instance!
		try {
			log.warn("An error was detected, trying to stop the plugin ${id}")
			pluginControlService.stop(id)
			log.warn("The plugin was successfully stopped")
		} catch(PluginStopException e) {
			log.error("Plugin instance ${id} could not be stopped", e)
		}
	}
}