Plugin-Bundle-Properties

Inhalt [ Verbergen ]

Die Bundle-Properties bieten dem Plugin-Entwickler die Möglichkeit Plugins von außen zu konfigurieren und damit das Laufzeitverhalten der entwickelten Plugins zu steuern.

Die Bundle-Properties können beispielsweise verwendet werden, um Adressen und Zugangsinformationen von Webservice-Endpoints konfigurierbar zu gestalten.

Sie eignen sich dafür, bestimmte Plugin-Typen, wie das IPluginFormPreRender-Plugin oder das IPluginServletAction-Plugin, die selbst über keine eigene Konfigurationsoberfläche in Xima® Formcycle verfügen, von außen zu beeinflussen.

Definition von Bundle-Properties durch den Plugin-Entwickler

Durch Einbinden des Interfaces IBundleProperties können konfigurierbare Optionen in der Oberfläche von Xima® Formcycle angezeigt werden.

Die Oberfläche von Xima® Formcycle bietet die Möglichkeit neue Properties mit Namen und Wert am jeweiligen Plugin-Bundle zu hinterlegen.
In den meisten Fällen ist es jedoch sinnvoll, wenn der Name (Zugriffsschlüssel, muss eindeutig innerhalb der Bundle-Properties sein)
und gegebenenfalls ein Standard-Wert für ein Property, bereits durch den Plugin-Entwickler festgelegt werden.

Damit werden zum einen Schreibfehler beim Anlegen der Zugriffsschlüssels durch den Plugin-Benutzer ausgeschlossen und
zum Anderen erhält der Plugin-Benutzer eine Sicht auf alle durch den Plugin-Entwickler unterstützten Konfigurationswerte.

Schnittstelle IBundleProperties

Die Schnittstelle bietet folgende Methodesignaturen:

Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale)

Die Methode getConfigProperties dient zur Konfiguration von Eigenschaftswerten, die allen Java-Klassen innerhalb des Plugin-Bundles zur Verfügung stehen sollen.
Übergabewerte:
  • IPluginResourceHelper
    • Objekte zum Zugriff auf die im Plugin-Bundle enthaltenen Datei-Ressourcen.
  • Locale
    • Das für den aktuell angemeldeten Nutzer festgelegte Locale-Objekt (enthält Informationen zur Sprache und Region). Dieses kann zum Ermitteln von sprachabhängigen Texten verwendet werden.
Rückgabewerte:
Die Methode muss ein Objekt vom Typ java.util.Map mit Value-Objekten vom Typ IBundleConfigParam zurückliefern. Es existieren zwei mögliche Implementierung von IBundleConfigParam:
  • BundleConfigGroupItem
    • Dieses Element kann zur Strukturierung der Listendarstellung in der Oberfläche von Xima® Formcycle verwendet werden.
  • BundleConfigParam
    • Dient zur Definition eines Bundle-Properties. Ein Objekt definiert die folgenden Eigenschaften:
      name
      Der Name oder Zugriffsschlüssel einer Property.
      description
      Beschreibung zu einer Property. Wird per Mouseover über den Property-Namen in der Oberfläche eingeblendet. Kann verwendet werden, um dem Nutzer des Plugins nähere Information zur Verwendung oder möglicher Wertebereiche des Parameters anzuzeigen.
      mandatory
      Legt fest, ob der Parameter in der Oberfläche als Pflichtparameter dargestellt wird und ein Validierung auf Vorhandensein eines Wertes beim Abspeichern durchgeführt wird.
      crypticValue
      Legt fest, ob der Wert der Property wie bei einem Passwordfeld maskiert werden soll. Standardwert ist false.
      defaultValue
      Ermöglicht die Festlegung eines Defaultwertes durch den Entwickler. Standardwert ist null.

Implementierungsbeispiel

Das nachfolgende Codebeispiel zeigt eine mögliche Implementierung:

@SuppressWarnings("serial")
public class MyBundleProperties implements IBundleProperties {

 /**
   * Returns a map with definitions of bundle configuration parameters. Key is the parameter name, value is a bundle
   * parameter definition of type {@link IBundleConfigParam}.
   * @param resHelper ResourceHelper to determine i18n values from the plugin bundle, if they exists
   * @param currentLocale the current locale
   * @return {@link Map} with objects of type {@link IBundleConfigParam} or <code>null</code>
   */
 @Override
 public Map<String, IBundleConfigParam> getConfigProperties(IPluginResourceHelper resHelper, Locale currentLocale) {
    Map<String, IBundleConfigParam> config = new LinkedHashMap<>();
    config.put("Group", new BundleConfigGroupItem("Unterstützte Parameter:"));
    config.put("Parameter1", new BundleConfigParam("Parameter1", "Pflichtparameter im Scope des Plugins mit Defaultwert", true, "Defaultwert"));
    config.put("Parameter2", new BundleConfigParam("Parameter2", "Pflichtparameter im Scope des Plugins", true));
    config.put("Parameter3", new BundleConfigParam("Parameter3", "Parameter im Scope des Plugins mit Defaultwert", false, "Initialwert"));
    config.put("Parameter4", new BundleConfigParam("Parameter4", "Parameter im Scope des Plugins", false));
   return config;
 }

}

Zugriff auf Bundle-Properties innerhalb der Plugin-Logik

Der Zugriff auf die Bundle-Properties innerhalb von einzelnen Plugin-Implementierungen wird über die Schnittstelle IFCPlugin und deren bereitgestellte Plugin-Lebenszyklus-Methoden ermöglicht.
Alle Plugin-Typen erben von dieser Schnittstelle, sodass damit in allen Plugin-Implementierungen ein Zugriff auf die Bundle-Properties möglich ist.

Beispiele zum Auslesen von Bundle-Properties

Das nachfolgende Beispiel zeigt den Zugriff auf die Bundle-Properties innerhalb einer IPluginFormPreRender-Implementierung.

Ein PreRender-Plugin wird standardmäßig bei allen Formularaufrufen im Scope des Mandanten, in dem er registriert wurde, ausgeführt.
Wenn man zum Beispiel möchte, dass der PreRenderer nur beim Aufruf bestimmter Formulare ausgeführt wird, so kann man dies mittels Bundle-Properties konfigurierbar gestalten.
Das nachfolgende Beispiel liest in der execute Methode den Wert der Bundle-Property activate.form.alias aus, welche die Namen von Formularen (mit Komma getrennt) enthält.
Anschließend werden diese Namen mit dem Namen des aktuellen Formulars, in dessen Anwendungsbereich der PreRenderer gerade ausgeführt wird, verglichen. 
Wenn der Name des aktuellen Formulars nicht mit einen Namen aus der konfigurierten Liste übereinstimmt, wird die weitere Verarbeitung des PreRenderers abgebrochen.

public class MyPreRenderer implements IPluginFormPreRender {

 private Properties bundleProperties = null;

 /**
   * Name, welcher Plugin eindeutig identifizerbar macht.
   */
 @Override
 public String getName() {
   return "Mein PreRenderer";
 }

 /**
   * Plugin-Lebenszyklus-Methode, welche beim Erzeugen der Objekt-Instanz aufgerufen wird.
   */
 @Override
 public void initialize(IPluginInitializeData initializeData) throws FCPluginException {
    bundleProperties = initializeData.getProperties();
 }

 /**
   * Methode zum Ausführen von Plugin-Logik.
   */
 @Override
 public IPluginFormPreRenderRetVal execute(IPluginFormPreRenderParams params) throws FCPluginException {
   // Bundle-Property 'activate.form.alias' auslesen
    Set<String> alias = getConfiguredFormAlias("activate.form.alias");

   // Ist PreRender-Plugin für aktuelle Formularinstanz freigeschalten?
    IExtendedFormRequestContext ctx = (IExtendedFormRequestContext)params.getFormRequestContext();
   if (!alias.contains(ctx.getProjekt().getName())) {
     // keine Formularfreischaltung gefunden -> Verarbeitung abbrechen
      return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
   }

   // weitere PreRender-Implementierung
    // ....

   return new PluginFormPreRenderRetVal(Collections.EMPTY_MAP, true);
 }

 /**
   * Funktion zum Ermitteln eines Bundle-Property-Wertes.
   * Der ermittelte Wert wird mittels Komma getrennt
   * und als HashSet zurückgeliefert.
   * @param propertyName
   * @return ein {@link HashSet}
   */
 protected Set<String> getConfiguredFormAlias(String propertyName) {
    String formAlias = bundleProperties.getProperty(propertyName, null);
   if (XStringUtils.isBlank(formAlias)) { return Collections.emptySet(); }
    String[] arr = XStringUtils.split(formAlias, ",");
   return new HashSet<String>(Arrays.asList(arr));
 }
}