Implementierung des Connectors mit dem Jitterbit Connector SDK

Einführung

Obwohl jeder mit dem Jitterbit Connector SDK erstellte Connector in Design und Implementierung unterschiedlich sein wird, gibt es einige grundlegende Konzepte, die alle Connectoren enthalten, die im Abschnitt Connector SDK-Konzepte in Jitterbit Connector SDK behandelt werden.

Diese Seite erweitert diese grundlegenden Konzepte und behandelt die Implementierungsdetails für Connectoren, die mit dem Connector SDK entwickelt wurden.

Wenn Sie einen Connector implementieren, um ihn zur Zertifizierung bei Jitterbit einzureichen, muss der Quellcode, der zur Zertifizierung eingereicht wird, den Java-Code-Stil von Jitterbit befolgen. Siehe die Kommentare zum Code-Stil im Abschnitt Vollständiges Beispiel weiter unten für die Checkstyle-Konfigurationsdatei, die verwendet werden sollte.

Connector

Benennung

Bei der Benennung eines Connectors sollten keine Sonderzeichen oder Schrägstriche (/) im Namen enthalten sein. Diese können Probleme verursachen, wenn der Connector im Agenten geladen wird.

Siehe Adapter JSON für Details zur Angabe der verschiedenen Namen, die in einem Connector verwendet werden.

Implementierung

Ein Connector sollte das BaseJitterbitConnector-Interface erweitern und eine Fabrik bereitstellen, die Harmony aufrufen kann, um Instanzen davon zu erstellen. Die Basisimplementierung umfasst die gemeinsamen Methoden, die ein Connector implementieren muss. (Eine Alternative besteht darin, das JitterbitConnector-Interface direkt zu implementieren.)

Um anzuzeigen, dass die Klasse, die dieses erforderliche Interface implementiert, als JitterbitConnector betrachtet werden soll, annotieren Sie sie mit einer @Connector-Annotation und geben Sie die Klasse an, die ihre Fabrik implementiert.

(Eine Alternative zur Verwendung einer Annotation besteht darin, die Fabrikklasse im Manifest der JAR-Datei als Wert des Attributs Jitterbit-Connector-Factory-Class anzugeben. Siehe Connector-Registrierung für Details.)

Diese Schnittstellen und ihre Methoden müssen implementiert werden:

• Connection-Schnittstelle und ihre Methoden open() und close()
• ConnectionFactory-Schnittstelle und ihre Methode createConnection(Map<String,String> properties)

public class MyConnectorUtils {
  public static String accessToken;
  public static String host;
  ...
}

public class MyConnectorUtils {
  private String accessToken;

  public String getAccessToken() {
    return accessToken;
  }

  public String setAccessToken(String accessToken) {
    this.accessToken = accessToken;
  }
  ...
}

Beispiel-Connector

Ein einfaches Beispiel für einen Connector:

/**
 * Example Connector.
 */
@Connector(factory = ExampleConnector.ExampleConnectorFactory.class)
public class ExampleConnector extends BaseJitterbitConnector {

  public static final ExampleConnector INSTANCE = new ExampleConnector();

  static {
    connectionFactory = ExampleConnectionFactory.INSTANCE;
  }

  @Override
  public ConnectionFactory getConnectionFactory() {
    return connectionFactory;
  }

  @Override
  public String getName() {
    return "ExampleConnector";
  }

  private static ConnectionFactory connectionFactory;

  /**
   * ExampleConnectorFactory.
   */
  public static class ExampleConnectorFactory implements
    JitterbitConnector.Factory {
      @Override
      public JitterbitConnector create() {
        return ExampleConnector.INSTANCE;
      }
  }
}

Verbindungsfabrik

Connectoren werden typischerweise verwendet, um eine Verbindung zu einem Endpunkt herzustellen. Um diese Verbindung zu erstellen, ihre Konfiguration zu erleichtern und die Verbindung zu testen, stellen Sie eine Implementierung einer ConnectionFactory bereit. Die Verbindung wird den Aktivitäten des Connectors durch den Kontext, der an jede Aktivität übergeben wird, zur Verfügung stehen.

Beispiel-Verbindungsfabrik

Ein einfaches Beispiel für eine Verbindungsfabrik:

/**
* Factory that creates an ExampleConnection instance.
*/
public class ExampleConnectionFactory implements ConnectionFactory {

  public static final ExampleConnectionFactory INSTANCE =
    new ExampleConnectionFactory();

  private ExampleConnectionFactory () {}

  /**
   * Returns a connection to an Example endpoint,
   * created from the specified properties.
   *
   * @param props properties for configuring and
   *              creating an Example connection
   * @return the configured connection
   * @throws RuntimeException if the name or password
   *                          of the specified properties
   *                          are empty or null
   */
  @Override
  public Connection createConnection(Map<String, String> props) {
    String name = props.get("name");
    String password = props.get("password");
    String locale = !props.containsKey("locale") ?
      Locale.getDefault().toString() : "EN_US";
    if (name == null || name.length() == 0) {
      throw new RuntimeException("Name property cannot be empty. " +
        "Specify the name associated with the Example connection.");
    }
    if (password == null || password.length() == 0) {
      throw new RuntimeException("Password cannot be empty. " +
        "Specify the password associated with the Example connection.");
    }
    return new ExampleConnection(name, password, locale);
  }

  /**
   * Returns the pool size configuration.
   *
   * @return the pool size configuration
   */
  @Override
  public PoolSizeConfiguration getPoolSizeConfiguration() {
    return new PoolSizeConfiguration();
  }
}

Verbindung

Im vorherigen Beispiel würde die Klasse ExampleConnection (nicht gezeigt) tatsächlich die Verbindung herstellen. Ihre Anforderungen werden durch den jeweiligen Endpunkt oder Dienst, mit dem verbunden wird, sowie durch alle Bibliotheken, die für diese Verbindung verwendet werden (wie zu einer Datenbank oder einem Webdienst), und die Einzelheiten der Verbindung bestimmt.

Im Integration Studio UI wird die Methode open() der Klasse, die die Connection-Schnittstelle implementiert, aufgerufen, wenn ein Benutzer auf die Schaltfläche Test der Verbindungs-Konfiguration klickt. Dies gibt dem Connector die Möglichkeit, nicht nur die Verbindung herzustellen, sondern auch zu überprüfen, ob die Verbindung funktioniert. Typischerweise kann dies durch den Aufruf des Endpunkts oder Dienstes erfolgen, wobei entweder ein kleines Payload zurückgegeben oder der zurückgegebene Wert zur Validierung der Verbindung verwendet wird.

Da diese Methode jedes Mal aufgerufen wird, um eine Verbindung zu einem Endpunkt herzustellen, wenn sie derzeit nicht geöffnet ist, ist es eine gute Idee, dass jeder Test schnell und klein ist, um keine weiteren Verarbeitungen zu verzögern.

Ein Beispiel dafür ist in der DropboxConnection.java des Dropbox-Connectors zu sehen:

  /**
   * Opens a Dropbox version 2 connection.
   */
  public void open() throws ConnectionException {
    if (client != null) {
      return;
    }
    try {
      DbxRequestConfig dbxConfig = new DbxRequestConfig(appKey, locale);
      client = new DbxClientV2(dbxConfig, accessToken);
      ListFolderResult results = client.files().listFolder("");
      System.out.println("Dropbox Connection successful -> app-key: "
        + appKey + ", access-token: " + accessToken);
    } catch (Exception x) {
      x.printStackTrace();
      throw new ConnectionException(Messages.DROPBOX_CODE07,
          Messages.getMessage(Messages.DROPBOX_CODE07_MSG,
            new Object[]{x.getLocalizedMessage()}), x);
    }
  }

Wenn bereits eine Verbindung besteht, gibt die Methode sofort zurück. Andernfalls wird eine neue Client-Verbindung innerhalb eines Try-Catch-Blocks erstellt. Sobald der Client erstellt ist, wird er getestet, indem die Liste der Objekte im Wurzel-("") Ordner angefordert wird. Die zurückgegebenen Ergebnisse werden tatsächlich nicht überprüft, da ein erfolgreicher Aufruf ausreichend ist. Wenn es ein Problem mit dem Zugriffsschlüssel gibt, den ein Benutzer zur Erstellung der Verbindung bereitstellt, wird eine Ausnahme von der Dropbox-API ausgelöst. Diese wird abgefangen und dann mit einer entsprechenden Fehlermeldung für den Benutzer erneut ausgelöst.

Variationen dieses Entwurfsmusters können je nach Endpunkt oder Dienst, mit dem der Connector arbeitet, verwendet werden.

Aktivitäten

Die Aktivitäten, die ein Connector bereitstellt und implementiert, werden von Klassen erstellt, die JitterbitActivity implementieren. Eine Jitterbit-Aktivität ist eine Arbeitseinheit mit zwei Rollen:

• Entdeckung/Konfiguration: Die Entdeckung von Metadaten, die mit einer Aktivität verbunden sind, und die Konfiguration ihrer Parameter.
• Ausführung: Eine Ausführungseinheit, die Teil einer Kette von Operationen ist.

Obwohl der Entdeckungsprozess in der Praxis zuerst erfolgt, werden wir hier zuerst den Ausführungsprozess besprechen, da dieser die Anforderungen des Entdeckungsprozesses bestimmt.

Aktivitäten werden in der Manifestdatei als Jitterbit-Activity-* Attribute deklariert, mit IDs, die basierend auf der Registrierung des Connectors bei Harmony zugewiesen werden. (Siehe Connector-Registrierung für Details.)

Jede Aktivitätsklasse erhält eine @Activity-Annotation, um sie als Teil des Connectors zu registrieren, und muss eine execute()-Methode implementieren, die einen JitterbitActivity.ExecutionContext erhält.

Während der Laufzeit wird der Betriebsprozess die Aktivität aufrufen, indem er die Methode execute(ExecutionContext) der Aktivität aufruft.

Der Ausführungskontext enthält Informationen über die Anfrage (falls vorhanden) und die Nutzlast. Die Aktivität ist dafür verantwortlich, die Antwortnutzlast festzulegen (indem die Methode JitterbitActivity.ExecutionContext.getResponsePayload() implementiert wird), die dann vom Prozessbetriebsengine an die nächste Aktivität in der Kette von Operationen übergeben wird.

Aus dem übergebenen Kontext hat die Aktivität ihre Verbindung zu Harmony. Sie kann Folgendes abrufen:

• Die Parameter, falls vorhanden, mit denen die Aktivität vom Endbenutzer konfiguriert wurde. Zum Beispiel durch den Aufruf der Methode context.getFunctionParameters().get("folder").
• Alle Verbindungen, die in der ursprünglichen Konfiguration der Verbindung hergestellt wurden, sofern der Entwickler sie verfügbar macht. Zum Beispiel durch den Aufruf der Methode context.getConnection().
• Parameter des Connectors selbst, sofern der Entwickler sie verfügbar macht.
• Die Anfrage- oder Antwortnutzlast, die in die Verbindung geschrieben oder von dieser abgerufen wird.

Konfigurierbare Parameter werden vom Endbenutzer in der Benutzeroberfläche des Integration Studio festgelegt und sind Teil der Konfiguration des Connectors und seiner Aktivitäten. Sie sind in der Datei adapter.json deklariert, die im JAR-Archiv des Connectors enthalten ist.

Die Anfrage- oder Antwortnutzlasten einer Aktivität sind die Daten, die entweder in die Verbindung geschrieben oder von dieser abgerufen werden; sie werden durch die XML-Schemadateien bestimmt, die diese Nutzlasten definieren, wie im nächsten Abschnitt beschrieben.

Aktivitätsanfrage und -antwort

Die Anfrage und Antwort der Aktivitäten eines Connectors werden mithilfe der Java-API für XML-Bindung (JAXB, Version 2+) behandelt, um Java-Klassen aus XML-Schemata zu generieren. Für jede Anfrage oder Antwort wird eine separate XML-Schemadatei (.xsd) verwendet. Die Zuordnung zwischen den generierten Dateien und diesen Quellen ist in der Ausgabedatei sun-jaxb.episode angegeben.

Die generierten Java-Klassen können dann von den Klassen importiert werden, die die execute()-Methode der Aktivität implementieren.

Zum Beispiel bewegt sich in der FetchFileActivity des Dropbox-Connectors Daten von Dropbox nach Harmony. Diese execute()-Methode verwendet eine DropboxConnection und die Dropbox-API, um Daten und Metadaten abzurufen; sie setzt dann diese Werte in ein Antwortobjekt (eine Instanz von FetchFileResponse) und marshaliert die Antwort in den Antwort-Payload-Ausgabestrom.

Im Gegensatz dazu bewegt sich in der PutFileActivity des Dropbox-Connectors Daten von Harmony nach Dropbox. Die execute()-Methode in dieser Klasse arbeitet in die entgegengesetzte Richtung. Sie unmarshaliert einen Eingabestrom, verwendet die Dropbox-API, um in Dropbox hochzuladen, und erstellt dann ein Antwortobjekt (in diesem Fall eine Instanz von PutFileResponse), das mit Werten aus der Antwort von Dropbox vervollständigt wird.

Jede Aktivität ist dafür verantwortlich, die Methode getActivityRequestResponseMetadata() zu implementieren und ein ActivityRequestResponseMetaData zurückzugeben. Die XML-Schema-Dateien werden verwendet, um das ActivityRequestResponseMetaData zu erstellen.

Um bei der Erstellung dieses Objekts zu helfen, steht ein Hilfsprogramm (wie im DropboxUtils.setRequestResponseSchemas von DropboxUtils.java gezeigt) zur Verfügung, um die XML-Schema-Dateien zu laden und sie als Anfrage oder Antwort festzulegen.

Diese werden dann in der Benutzeroberfläche des Integration Studio im Datenschema angezeigt, das während des letzten Schrittes der Konfiguration einer Aktivität angezeigt wird. Wenn eine Antwort oder Anfrage nicht gewünscht oder erforderlich ist, kann sie ignoriert werden, und es wird kein Datenstrukturbaum in der Benutzeroberfläche des Integration Studio für diese Komponente erstellt. Die Fetch File-Aktivität des Dropbox-Connectors ist ein Beispiel dafür; sie hat nur eine Antwort und keine Anfragedatenstruktur.

Wenn eine Anfrage erforderlich ist, kann dies in der JSON-Datei angegeben werden, die die Benutzeroberfläche des Integration Studio für den Connector definiert. Durch die Deklaration von inputRequired für eine Aktivität in der adapter.json für den Connector wird die Benutzeroberfläche des Integration Studio gezwungen, einen Validierungsfehler für die übergeordnete Operation auszulösen, wenn es keine Quelltransformation vor der Verwendung der Aktivität gibt. Zum Beispiel zeigt dieser Ausschnitt einer JSON-Datei die Definition der SAP-Aktivität BAPI als eingabepflichtig:

"activities": {
    "bapi": {
        "displayName": "BAPI",
        "inputRequired": true,
        "properties": [
            " . . . "
        ]
    }
}

Siehe Connector SDK UI-Komponenten für Details zur Definition der JSON-Datei, die die Cloud Studio UI spezifiziert.

Discovery und Metadaten

Im Rahmen des Lebenszyklus der Konfiguration einer Connector-Aktivität kann ein Discovery-Prozess verwendet werden, um Informationen zu erhalten, die zur Vervollständigung der Konfiguration erforderlich sind.

Ein Beispiel dafür ist, einen Tabellennamen zu erhalten und aus dieser Auswahl die Feldnamen zu erhalten. Um dies zu erleichtern, steht eine Schnittstelle im Connector SDK (org.jitterbit.connector.sdk.Discoverable) zur Implementierung zur Verfügung.

Wenn die Konfiguration für eine Aktivität in der Integration Studio UI aufgerufen wird, wird die Methode getObjectList() der Schnittstelle aufgerufen, wodurch der Connector eine Liste entdeckter Objekte erstellen und zurückgeben kann, die in der UI angezeigt werden können. Nachdem eine Auswahl durch den Benutzer getroffen wurde, ist diese Auswahl in der Methode getActivityRequestResponseMetadata() der Schnittstelle über den Parameter activityFunctionParams verfügbar, der übergeben wird.

Siehe die ProcessFileActivity des Dropbox-Connectors für ein Beispiel, wie Discovery bei der Erstellung von Metadaten verwendet werden kann.

Weitere Beispiele sind in den Beschreibungen der Integration Studio UI-Komponenten enthalten, die Metadaten nutzen, wie im nächsten Abschnitt beschrieben.

Integration Studio UI

Der Connector und seine Aktivitäten werden über die Integration Studio UI konfiguriert. Die Benutzeroberfläche dieser Konfigurationen ist in der Datei adapter.json spezifiziert. Der tatsächliche Dateiname der JSON-Datei kann von diesem Standard geändert werden; er ist im Manifest der JAR-Datei angegeben.

Die Datei spezifiziert die UI für den Connector und all seine Aktivitäten. Die Einzelheiten der JSON-Datei sind in Connector SDK UI-Komponenten behandelt.

Komponenten werden als grundlegende oder komplexe Komponenten kategorisiert.

• Basis-Komponenten interagieren nicht mit dem Connector. Sie dienen lediglich dazu, einen Wert vom Benutzer zu empfangen und diesen an den Connector zurückzugeben.
• Komplexe Komponenten sind ausgefeilter und erfordern mehrere Methoden sowie zusätzlichen Code im Connector, um ihren Entdeckungsprozess zu implementieren und in der Ausführung zu verwenden. Sie sind dafür gedacht, schwierigere Herausforderungen der Connector-UI zu lösen.

Beachten Sie, dass der im JSON-Dokument verwendete name der gleiche Name sein muss, unter dem der Connector registriert ist und der im Java-Code definiert ist. Siehe Connector-Registrierung für Details.

Manifest

Diese verschiedenen Komponenten (Registrierungsinformationen für den Connector und jede Aktivität, Klassen, Drittanbieter-Classpath, Connector-UI-Dateiname) sind im MANIFEST.MF zusammengefasst, das in der JAR-Datei enthalten ist, die den Connector archiviert. Die Einzelheiten zur Registrierung und zum Manifest sind in der Connector-Registrierung behandelt.

Connector erstellen

Wie üblich für ein Java-Projekt dieser Komplexität ist eine Maven pom.xml-Datei unerlässlich, um alle importierten Abhängigkeiten und Komponenten korrekt zu verknüpfen. Beim Ausführen des Builds müssen Sie zunächst die XML-Schema-Dateien kompilieren, bevor die Java-Kompilierung und -Verpackung erfolgt. Der entsprechende Maven-Befehl lautet:

$ mvn jaxb2:xjc compile install

Installieren

Im Gegensatz zu Jitterbit-Plugins (die installiert werden, indem sie in Harmony hochgeladen werden und die Plattform sie installiert, indem sie die Plugins mit einer Agentengruppe verknüpft), werden Harmony-Connectoren, die mit dem SDK erstellt wurden, installiert, indem ihre JAR-Dateien manuell im entsprechenden Verzeichnis eines privaten Agents platziert werden. Wenn der Connector in einer Agentengruppe mit mehr als einem Agenten verwendet werden soll, müssen die JAR-Dateien in jeden privaten Agenten kopiert werden. Wenn der Connector von bestimmten Bibliotheken abhängt, die nicht in seinen JAR-Dateien enthalten sind, müssen diese im Classpath jedes privaten Agents installiert werden, damit sie zum Zeitpunkt des Ladens des Connectors durch den Agenten zugänglich sind.

Wenn Sie einen Connector entwickeln und auf Linux oder macOS arbeiten, empfehlen wir die Verwendung eines Docker-Privatagents, da dieser so konfiguriert werden kann, dass das Build-Verzeichnis des Connectors als Volume lokal zum Agenten gemountet wird. Für Windows kann ein Windows-Privatagent verwendet werden.

Das Connector-Verzeichnis wird automatisch vom Agenten auf Änderungen gescannt, und alle modifizierten Connectoren werden automatisch neu geladen, ohne dass der Agent neu gestartet oder aufgefordert werden muss. Dies beschleunigt und vereinfacht den Entwicklungsprozess. Beachten Sie, dass Sie nicht direkt in dieses Verzeichnis bauen sollten, da die Zwischenprodukte des Builds den Agenten verwirren können.

Connector-Standorte

Synchronisierung

Öffentliche Connectoren (von Jitterbit veröffentlichte Connectoren) synchronisieren sich automatisch mit einem Jitterbit-Agenten, wenn dies erforderlich ist. Um die Synchronisierung öffentlicher Connectoren zu verhindern, steht eine Umgebungsvariable (SKIP_SYNC_CONNECTORS) zur Verfügung, die die Synchronisierung steuert. Setzen Sie diese Umgebungsvariable in der Shell, die den Agenten ausführt, und starten Sie den Agenten neu.

Das Setzen von SKIP_SYNC_CONNECTORS auf ein Sternchen stoppt die Synchronisierung aller öffentlichen Connectoren:

SKIP_SYNC_CONNECTORS=*

Das Setzen von SKIP_SYNC_CONNECTORS auf eine durch Kommas getrennte Liste von Connectoren stoppt die Synchronisierung aller öffentlichen Connectoren, mit Ausnahme der aufgelisteten:

SKIP_SYNC_CONNECTORS=Box,Magento

Dieses letzte Beispiel stoppt die Synchronisierung aller öffentlichen Connectoren, mit Ausnahme der Box- und Magento-Connectoren, die synchronisiert werden.

Vollständiges Beispiel

Der Dropbox-Connector ist ein vollständiges funktionierendes Beispiel für diese Konzepte. Konsultieren Sie ihn für weitere Details.

Wenn Sie den Dropbox-Connector in Ihren eigenen Connector mit Ihrem eigenen Paket und Ihrer eigenen Domain anpassen möchten, müssen Sie zusätzlich zu den Paketnamen, Pfaden, dem Inhalt des Java-Codes und der Registrierung Ihres Connectors diese Elemente aktualisieren:

• pom.xml: Ersetzen Sie die Verwendung von Jitterbit durch Ihre eigene Domain, wo es angebracht ist; aktualisieren Sie den Artefaktnamen und die Version.
• MANIFEST.MF: Ersetzen Sie die Verwendung von Jitterbit durch Ihren eigenen Namen, wo es angebracht ist; aktualisieren Sie die Schlüssel und IDs.
• DropboxConstants.java: Aktualisieren Sie den Namensraum in Verbindung mit den XML-Schema-XSD-Dateien; aktualisieren Sie den Connector-Namen.
• XML-Schema-XSD-Dateien: Aktualisieren Sie den Zielnamensraum in Verbindung mit der DropboxConstants.java.
• adapter.json und BaseJitterbitConnector: Das Namensfeld der adapter.json und der Name, der die Klasse annotiert, die BaseJitterbitConnector erweitert, werden verwendet, um den Connector zu benennen. Wenn im adapter.json angegeben, verwendet das Framework diesen Namen; andernfalls wird der in der Annotation angegebene Name verwendet. Siehe DropboxConstants.java und DropboxConnector.java für Beispiele, wie dies geschieht.

Code-Stil

Der Dropbox-Connector wurde gemäß dem Java-Code-Stil von Jitterbit formatiert. Dieser Stil sollte für jeden Code befolgt werden, der als Teil der Zertifizierung eines Connectors an Jitterbit eingereicht wird.

Um diesen Stil in Ihrem Quellcode umzusetzen:

• Fügen Sie in Ihrem Quellcode die Jitterbit checkstyle.xml Datei ein; und
• Fügen Sie in Ihrer pom.xml-Datei einen Verweis auf das maven-checkstyle-plugin und diese checkstyle.xml-Datei ein. Fügen Sie zu den <plugins> des <build>-Abschnitts der pom.xml hinzu:

  <plugin>
    <groupId>org.apache.maven.plugins</groupId>
    <artifactId>maven-checkstyle-plugin</artifactId>
    <version>2.17</version>
    <executions>
      <execution>
        <id>validate</id>
        <phase>process-test-classes</phase>
        <configuration>
          <configLocation>checkstyle.xml</configLocation>
          <suppressionsLocation>suppressions.xml</suppressionsLocation>
          <encoding>UTF-8</encoding>
          <consoleOutput>true</consoleOutput>
          <failsOnError>true</failsOnError>
          <includeTestSourceDirectory>true</includeTestSourceDirectory>
        </configuration>
        <goals>
          <goal>check</goal>
        </goals>
      </execution>
    </executions>
    <dependencies>
      <dependency>
        <groupId>com.puppycrawl.tools</groupId>
        <artifactId>checkstyle</artifactId>
        <version>6.19</version>
      </dependency>
    </dependencies>
  </plugin>
  

Beziehen Sie sich auf den Dropbox-Connector pom.xml für ein Beispiel zur Verwendung dieses Checkstyles in einem Projekt.