Wtyczka

Plugin

The plugin is an OSGi bundle installed in the OSGi environment. It can be used dynamically:

• installed
• updated
• launched
• stopped
• uninstalled

The plugin has its own context, which acts as a container for plugin components, services, controllers. It is possible to inject inject dependencies and use all the benefits of SpringFramework.

Plugin descriptor (suncode-plugin.xml)

The plugin descriptor is an XML file that provides basic information about the plugin and is a place for declarations of the modules used. This file is required because it provides information about the plugin (its unique identifier and display name).

The descriptor has the following structure:

<?xml version="1.0" encoding="UTF-8"?>
<plugin key="com.suncode.plugin-tutorial" name="Tutorial Plugin">
	<plugin-details>
		<description>
			<localized language="en">Description</localized>
			<localized language="pl">Opis</localized>
		</description>
		<author>Suncode</author>
        <requirements>
            <plusworkflow>3.2.200</plusworkflow>
            <com.suncode.plugin-dbexplorer>2.0.24</com.suncode.plugin-dbexplorer>
            <com.suncode.plugin-pwe>2.3.63</com.suncode.plugin-pwe>
        </requirements>
        <free-license>XXXXXXXXXXXXXXXXXXXXX</free-license>
        <changelog>https://docs.plusworkflow.pl/confluence/display/UNICMP/Change+Log+cuf-components</changelog>
        <documentation>https://docs.plusworkflow.pl/confluence/display/UNICMP/Cuf-components</documentation>
	</plugin-details>
	
	<!-- All subsequent elements are declarations of modules -->	
</plugin>

The <requirements> section allows you to specify the required plugin dependencies. The <plusworfklow> system dependency should match as to version with the parent version specified in pom.xml.
The <free-license> section allows you to assign a free license to the plugin - plugins having this entry will install as "Free" Plugins without this section are paid. Licenses are associated with the plugin ID - license generation is available in the ISO system.
The <changelog> section allows you to indicate the URL to the changelog of a given plugin. The link will be available to click on from the update center. Note: the link should point to a public resource, accessible without login.
The <documentation> section allows you to point to the URL with the plugin's documentation. The link will be available to click from the update center.

The plugin can also define PluginHook, if an action is needed to be triggered when the plugin starts and stops:

<?xml version="1.0" encoding="UTF-8"?>
<plugin key="com.suncode.plugin-tutorial" name="Tutorial Plugin" hook="com.suncode.plugin.tutorial.Hook">
	<!-- ... -->
</plugin>

Plugin requirements

A plugin can define its requirements, which are checked during:

1. launch - the plug-in cannot be launched if there are no mandatory dependencies
2. update - a message is displayed in which:
   
   1. new dependencies that are not met are visible
   2. visible are plugins that may have required a different version of this plugin (only for downgrade)
3. stopping a plugin - a message is displayed containing all plug-ins that may stop working properly after stopping this plugin
4. deleting a plugin - a message is displayed containing all plug-ins that may stop working properly after deleting this plugin

Requirements are divided into:

• optional - launching the plugin is not blocked
• mandatory - the plugin will never be launched

<?xml version="1.0" encoding="UTF-8"?>
<plugin key="com.suncode.plugin-tutorial" name="Tutorial Plugin">
	<plugin-details>
		<requirements>
			<!-- Requirement 'mandatory' for PlusWorkflow system -->
			<plusworkflow>3.2.50</plusworkflow>
			<!-- Requirement 'optional' on plugin with key "com.suncode.plugin.pluginX" -->
			<com.suncode.plugin.pluginX optional="true">1.1</com.suncode.plugin.pluginX>
		</requirements>
	</plugin-details>
</plugin>

Plugin operations

This chapter shows how to use the plugin mechanism API. The Plugins management shows how to manage plugins from within the system.

The main component of the plugin mechanism is the PluginFramework. In PlusWorkflow, we need to retrieve this object from the application context:

• use dependency injection

  @Component
  public class SomeComponent {
  	@Autowired
  	private PluginFramework framework;	
   
  	/**
  ...
  	*/
  }

• retrieve the object statically from the application context

  import com.suncode.plugin.framework.PluginFramework;
  import com.suncode.pwfl.util.SpringContext;
   
  public class SomeClass {
  	public static void doSomething(){
  		PluginFramework framework = SpringContext.getBean( PluginFramework.class );
  	/**
  	...
  */
  }
  }

The following shows the performance of some basic operations:

// taken any method
// PluginFramework framework = ...
 
// 1. Installation of the plugin from the given file
File pluginFile = new File("/fakepath");
Plugin plugin = framework.installPlugin( pluginFile );
 
// 2. Plugin update
File updatedPluginFile = new File("/fakepath");
plugin.update( updatedPluginFile );
 
// 3. Launching the plugin
plugin.start();
plugin.getState(); // PluginState.ACTIVE
 
// 4. Translation download 
// zwraca "message1" jeżeli moduł I18N nie jest obecny, w przeciwnym wypadku zwraca znalezione tłumaczenie
plugin.getMessage("message1"); 
 
// 5. Stopping the plugin
plugin.stop();
plugin.getState(); // PluginState.STOPPED