Adapter-Interface implementieren

Alle Adapter implementieren das Interface de.softproject.integration.adapter.core.Adapter und den Standard-Konstruktor (ohne Parameter) zum Erstellen der Hauptklasse. Die abstrakte Klasse de.softproject.integration.adapter.core.BaseAdapter enthält eine Basisimplementierung, um den Adapter-Status und den Zugriff im Projektverzeichnis zu erhalten.

Adapter-Metadaten definieren

Um Adapter-Metadaten zu definieren wird die Annotation @AdapterDescription verwendet. Folgende Felder müssen gesetzt sein:

Feld	Beschreibung	Pflicht
`category`	Fachliche Kategorie des Adapters	ja
`description`	Beschreibung über den Zweck des Adapters	ja
`displayName`	Sprechender Name des Adapters	ja
`version`	Version des Adapters im Format `major.minor.patch` (z.B. `1.0.0`)	ja
`configurationBeanClass`	Typ der `ConfigurationBean`, falls der Adapter Parameter benötigt. Ist die Konfiguration in der Adapterklasse selbst, muss hier nichts angegeben werden.	nein

BaseAdapter verwenden

Diese Basisklasse enthält geschützte Methoden für den Zugriff auf den Adapter-Status und den ProjectExplorer. Die Basisimplementierung geht davon aus, dass die Konfiguration in der Adapterklasse vorgenommen wird. Das heißt die Adapter-Parameter sind in der Klasse selbst definiert. Wenn eine eigene Klasse zur Adapter-Konfiguration verwendet werden soll, muss die Methode getConfigurationBean wie unter Adapter-Metadaten definieren beschrieben überschrieben werden.

Adapter-Interface verwenden

Eine neue Adapter-Klasse erstellen, die das Interface de.softproject.integration.adapter.core.Adapter implementiert.
Standard-Konstruktor verwenden. Die Klasse wird vom X4 ESB zur Laufzeit über den Standard-Konstruktor instantiiert.
Die Methoden init() und cleanup() sowie getConfigurationBean() werden angelegt sowie die notwendigen Pakete importiert. Mit dem Konstruktor werden folgende Elemente angelegt:
- public void cleanup(): Räumt immer nach dem Ausführen der operation-Methode auf und schließt Ressourcen, die von der Adapterinstanz belegt wurden.
- public void init(Status arg0, long arg1): Nach dem Anlegen der Adapter-Instanz wird eine Status-Instanz angelegt und an den Adapter mit dem Aufruf der init()-Methode übergeben. Parameter arg0 gibt das Objekt an, für dessen Adapter-Instanz ein Status gesetzt werden soll, Parameter arg1 bezeichnet die Adapter-Instanz (im Code).
  Der Adapter kann bei dessen Ausführung in seinen do…-Methoden die Status-Instanz manipulieren, anschließend wird dieser Status vom X4 ESB ausgewertet.
- public Object getConfigurationBean(): Liefert eine Instanz der Configuration Bean zurück, die Setter-Methoden zum Setzen von Konfigurationsparameter enthält. Adapter-Instanzen können durch das Configuration-Bean-Objekt auf die Konfigurationsparameter zugreifen.
Statusvariable anlegen und Instanz-Status zuweisen.
Configuration-Bean-Objekt (optional) anlegen (siehe Configuration Bean erstellen), und in getConfigurationBean() als Rückgabewert verwenden bzw. bei Verzicht auf ein Configuration-Bean-Objekt null zurückgeben.
Das Grundgerüst für die Hauptklasse des Adapters ist nun fertig.

Beispiel

JAVA

import java.nio.charset.StandardCharsets;
import de.softproject.integration.adapter.annotations.AdapterDescription;
import de.softproject.integration.adapter.annotations.AdapterOperation;
import de.softproject.integration.adapter.annotations.AdapterParameter;
import de.softproject.integration.adapter.core.AdapterException;
import de.softproject.integration.adapter.core.AdapterParameterDataType;
import de.softproject.integration.adapter.core.BaseAdapter;
import de.softproject.integration.util.x4documents.MimeTypeUtils;
import de.softproject.integration.util.x4documents.X4Document;
import de.softproject.integration.util.x4documents.X4DocumentFactory;

/**
 * This is a simple Adapter showing how Adapters are declared in the
 * X4-BPMS.<br>
 * An adapter needs some Annotation to be recognized by the X4-System:<br>
 * <ul>
 * <li>{@link AdapterDescription}: Mandatory for making an Adapter visible. It
 * describes the metadata of the adapter</li>
 * <li>{@link AdapterParameter}: Mandatory for Parameters. They will be mapped
 * to the corresponding setter Method. It must match the parameter name.
 * <li>{@link AdapterOperation}: Mandatory for Operations. It describes the
 * metadata for an adapter operation
 * </ul>
 */
@AdapterDescription(category = "Demo", description = "Say Hello...", displayName = "HelloWorld", version = "1.0.0")
public class HelloWorldAdapter extends BaseAdapter {

    @AdapterParameter(dataType = AdapterParameterDataType.STRING, description = "say hello to", optional = true)
    private String name = "default";

    @AdapterOperation(name = "HelloWorld")
    public X4Document sayHelloWorld(X4Document input) {
        return X4DocumentFactory.createX4Document("Hello World", StandardCharsets.UTF_8.name(),
                MimeTypeUtils.TEXTPLAIN);
    }

    @AdapterOperation(name = "HelloTo")
    public X4Document sayHelloTo(X4Document input) throws AdapterException {
        if (name == null || "".equals(name)) {
            throw new AdapterException(123, "Parameter \"name\" ist nicht gesetzt...");
        }
        getStatus().setOk();
        return X4DocumentFactory.createX4Document("Hello " + name, StandardCharsets.UTF_8.name(),
                MimeTypeUtils.TEXTPLAIN);
    }

    public void setName(String name) {
        this.name = name;
    }
}