Wtyczka

Wtyczka

Wtyczka jest bundlem OSGi instalowanym w środowisku OSGi. Może być ona dynamicznie:

• instalowana
• aktualizowana
• uruchamiana
• zatrzymywana
• odinstalowana

Wtyczka posiada własny kontekst, który pełni rolę kontenera komponentów wtyczki, serwisów, kontrolerów. Możliwe jest wstrzykiwanie zależności i korzystanie ze wszystkich dobrodziejstw SpringFramework.

Deskryptor wtyczki (suncode-plugin.xml)

Deskryptor wtyczki to plik XML który dostarcza podstawowe informacje o wtyczce oraz jest miejscem na deklaracje wykorzystywanych modułów. Plik ten jest wymagany, ponieważ dostarcza informacje o wtyczce (jej unikalny identyfikator i wyświetlaną nazwę).

Deskryptor ma następującą strukturę:

<?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>
	
	<!-- Wszystkie kolejne elementy stanowią deklaracje modułów -->	
</plugin>

Sekcja <requirements> pozwala na określenie wymaganych zależności wtyczka. Zależność systemowa <plusworfklow> powinna być zgodna co do wersji z wersją parenta określoną w pom.xml.
Sekcja <free-license> pozwala na przypisanie wtyczce darmowej licencji - wtyczki posiadające ten wpis będą instalowały się jako "Darmowe" Wtyczki bez tej sekcji są płatne. Licencje są powiązane z identyfikatorem wtyczki - generowanie licencji jest dostępne w systemie ISO.
Sekcja <changelog> pozwala na wskazanie URLa do changeloga danej wtyczki. Link będzie dostępny do kliknięcia z poziomu centrum aktualizacji. Uwaga: link powininen wskazywać na zasoby publiczne, dostępne bez konieczności logowania.
Sekcja <documentation> pozwala na wskazanie URL z dokumentacją wtyczki. Link będzie dostępny z poziomu centrum aktualizacji.

Wtyczka może także zdefiniować PluginHook, jeżeli potrzebne jest wywołanie akcji przy starcie i zatrzymaniu wtyczki:

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

Wymagania wtyczek

Wtyczka może zdefiniować swoje wymagania, które są sprawdzane podczas:

1. uruchomienia – wtyczka nie może być uruchomiona w przypadku braku zależności mandatory
2. aktualizacji - wyświetlany jest komunikat w którym:
   
   1. widoczne są nowe zależności które nie są spełnione
   2. widoczne są wtyczki które mogą wymagały innej wersji tej wtyczki (tylko przy downgrade)
3. zatrzymania wtyczki - wyświetlany jest komunikat zawierający wszystkie wtyczki które mogą przestać działać poprawnie po zatrzymaniu tej wtyczki
4. usunięcia wtyczki - wyświetlany jest komunikat zawierający wszystkie wtyczki które mogą przestać działać poprawnie po usunięciu tej wtyczki

Wymagania dzielimy na:

• optional - uruchomienie wtyczki nie jest blokowane
• mandatory - wtyczka nigdy nie zostanie uruchomiona

<?xml version="1.0" encoding="UTF-8"?>
<plugin key="com.suncode.plugin-tutorial" name="Tutorial Plugin">
	<plugin-details>
		<requirements>
			<!-- Wymaganie 'mandatory' na system PlusWorkflow -->
			<plusworkflow>3.2.50</plusworkflow>
			<!-- Wymaganie 'optional' na wtyczke o kluczu "com.suncode.plugin.pluginX" -->
			<com.suncode.plugin.pluginX optional="true">1.1</com.suncode.plugin.pluginX>
		</requirements>
	</plugin-details>
</plugin>

Operacje na wtyczkach

Ten rozdział pokazuje, jak korzystać z API mechanizmu wtyczek. Rozdział Zarządzanie wtyczkami pokazuje, jak zarządzać nimi z poziomu systemu.

Głównym komponentem mechanizmu wtyczek jest PluginFramework. W systemie PlusWorkflow musimy pobrać ten obiekt z kontekstu aplikacji:

• wykorzystać wstrzykiwanie zależności

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

• pobrać obiekt statycznie z kontekstu aplikacji

  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 );
  	/**
  	...
  */
  }
  }

Poniżej przedstawiono wykonywanie kilku podstawowych operacji:

// pobrany w dowolny sposób
// PluginFramework framework = ...
 
// 1. Instalacja wtyczki z podanego pliku
File pluginFile = new File("/fakepath");
Plugin plugin = framework.installPlugin( pluginFile );
 
// 2. Aktualizacja wtyczki
File updatedPluginFile = new File("/fakepath");
plugin.update( updatedPluginFile );
 
// 3. Uruchomienie wtyczki
plugin.start();
plugin.getState(); // PluginState.ACTIVE
 
// 4. Pobranie tłumaczenia 
// zwraca "message1" jeżeli moduł I18N nie jest obecny, w przeciwnym wypadku zwraca znalezione tłumaczenie
plugin.getMessage("message1"); 
 
// 5. Zatrzymanie wtyczki
plugin.stop();
plugin.getState(); // PluginState.STOPPED