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:

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

1. Eine neue Adapter-Klasse erstellen, die das Interface de.softproject.integration.adapter.core.Adapter implementiert. 

2. 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.

3. Statusvariable anlegen und Instanz-Status zuweisen.

4. 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

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;
    }
}