Wstęp

Strona zawiera dokumentację PluginFramework API 

Plugin API

Plugin API wykorzystywane jest do zarządzania pojedynczą wtyczką.

Obiekt (com.suncode.plugin.framework.Plugin) reprezentuje wtyczkę i umożliwia sterowanie jej stanem oraz komunikację z mechanizmem wtyczek. Obiekt ten możemy otrzymać poprzez:

• pobranie obiektu wtyczki z serwisu com.suncode.plugin.framework.PluginFramework wywołując metodę getPlugin(String key)  podając jej identyfikator:

  // dowolny komponent (wewnątrz wtyczki lub w systemie)
  @Component
  public class SomeComponent {
   
  	@Autowired
  	private PluginFramework framework;
   
  	public void method(){
  		Plugin plugin = framework.getPlugin("plugin-key");
  	}
  }

• wstrzyknięcie (@Autowired) obiektu wtyczki do komponentu tej wtyczki. W taki sposób możemy pobrać obiekt aktualnej wtyczki:

  // komponent wewnątrz wtyczki
  @Component
  public class SomePluginComponent {
   
  	@Autowired
  	private Plugin plugin;
   
  	public void method(){
  		plugin.getKey(); // klucz tej wtyczki
  	}
  }

Cykl życia wtyczki

Wtyczka może być dynamicznie uruchamiana, zatrzymywana i aktualizowana poprzez wywołanie odpowiednich metod na obiekcie tej wtyczki:

• Uruchomienie wtyczki

  Plugin plugin = ...
   
  plugin.start();
  System.out.println(plugin.getState()); // wypisuje ACTIVE

• Zatrzymanie wtyczki

  Plugin plugin = ...
  
  
  plugin.stop();
  System.out.println(plugin.getState()); // wypisuje STOPPED

• Aktualizacja wtyczki z podanego pliku

  Plugin plugin = ...
  
  
  plugin.update(new File("ścieżka do pliku jar wtyczki"));

• Odinstalowanie wtyczki

  Odinstalowana wtyczka nie może być już wykorzystywana. Wywołanie jakiejkolwiek metody (z wyjątkiem kilku np. getState) zakończy się błędem.

  Plugin plugin = ...
  
  
  plugin.uninstall();
  System.out.println(plugin.getState()); // wypisuje UNINSTALLED

Zasoby wtyczki

Każda wtyczka zbudowana jest z klas Java oraz statycznych zasobów. Ze względu na izolację wtyczek, odczyt zasobów może odbywać się tylko z wykorzystaniem przedstawionych metod.

• Pobieranie pojedynczych zasobów 

  Plugin plugin = ...
   
  Resource resource = plugin.getResource("suncode-plugin.xml"); // deskryptor wtyczki
  if(resource.exists()){
  	// zasób istnieje i można go odczytać
  }

• Wyszukiwanie zasobów 

  Plugin plugin = ...
  PluginContext context = plugin.getPluginContext();
   
  // mappings/a.xml
  // mappings/b.xml
  // mappings/c.json
  // mappings/sub/a.json
  // mappings/sub/b.xml
   
  // wszystkie pliki z katalogu mappings i podkatalogów
  Resource[] resources = context.getResources( "mappings/**/*" );
  // resources ma:
  // mappings/a.xml
  // mappings/b.xml
  // mappings/c.json
  // mappings/sub/a.json
  // mappings/sub/b.xml
   
  // wszystkie pliki xml z katalogu mappings
  Resource[] resources = context.getResources( "mappings/*.xml" );
  // resources ma:
  // mappings/a.xml
  // mappings/b.xml

  
  Wzorzec zasobów jest wyrażeniem Ant. Więcej info w dokumentacji Spring'a PathMatchingPatternResolver (http://docs.spring.io/autorepo/docs/spring-framework/3.2.6.RELEASE/javadoc-api/org/springframework/core/io/support/PathMatchingResourcePatternResolver.html).

Lokalne repozytorium

PluginStore pozwala na zapisywanie zasobów (np. plików) w lokalnym repozytorium wtyczki. Pliki zapisane w takim repozytorium są stałe tzn. nie są usuwane podczas zatrzymywania wtyczki. Stanowi to alternatywę dla baz danych.

• Pobieranie instancji store'a 

  // z instancji wtyczki
  PluginStore store = plugin.getPluginStore();
   
  // poprzez @Autowired
  @Autowired
  private PluginStore store;

  
  Komponent PluginStore może być pobrany zarówno z instancji wtyczki jak i z kontekstu tej wtyczki.

• Zapis zasobów 

  PluginStore store = ...
   
  // zapis InputStream
  PluginStoreResource resource = store.store("some/path/file.xml", inputStream);
  resource.getPath(); // some/path/file.xml
  resource.getInputStream();

  Domyślne metody nie pozwalają na nadpisywanie plików. Aby nadpisywać pliki musimy wykorzystać inny wariant metody.

• Odczyt zasobów 

  PluginStore store = ...
   
  // pobranie zasobu
  PluginStoreResource resource = store.read("some/path/file.xml")
  if(resource == null){
  	// zasób nie istnieje
  	return;
  }
   
  // odczyt i poprawne zamknięcie
  InputStream input = resource.getInputStream();
  try{
  	// odczyt/kopiowanie etc.
  }
  finally{
  	input.close();
  }

• Usuwanie zasobów 

  PluginStore store = ...
   
  // usunięcie pojedynczego zasobu
  store.delete("some/path/file.xml");
   
  // wyczyszczenie całego store'a
  store.clear();