Connector-Implementierung

Einführung

Obwohl sich jeder mit dem Jitterbit Connector SDK erstellte Connector sowohl im Design als auch in der Implementierung unterscheidet, gibt es einige Kernkonzepte, die alle Connectors beinhalten und unter Connector SDK Concepts behandelt werden im Jitterbit Connector SDK.

Diese Seite erweitert diese Kernkonzepte und behandelt Implementierungsdetails für Konnektoren, die mit dem Connector SDK entwickelt wurden.

Wenn Sie einen Konnektor mit der Absicht implementieren, ihn zur Zertifizierung durch Jitterbit einzureichen, muss der zur Zertifizierung eingereichte Quellcode dem Java-Codestil von Jitterbit entsprechen. Siehe die Kommentare zu Codestil im Abschnitt Vollständiges Beispiel unten für die zu verwendende Checkstyle-Konfigurationsdatei.

Konnektor

Benennung

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

Siehe Adapter JSON für Einzelheiten zum Angeben der verschiedenen Namen, die in einem Connector verwendet werden.

Umsetzung

Ein Konnektor sollte die BaseJitterbitConnector Schnittstelle und bieten eine Fabrik, die Harmony kann aufrufen, um Instanzen davon zu erstellen. Die Basisimplementierung enthält die allgemeinen Methoden, die ein Connector benötigt implementieren. (Eine Alternative besteht darin, die JitterbitConnector Schnittstelle direkt.)

Um anzuzeigen, dass die Klasse, die diese erforderliche Schnittstelle implementiert, diejenige ist, die als JitterbitConnector, vermerken Sie es mit einem @Connector Annotation und geben Sie die Klasse an, die ihre Factory implementiert.

(Alternativ zur Verwendung einer Annotation können Sie die Factory-Klasse im Manifest der JAR-Datei als Wert des Jitterbit-Connector-Factory-Class Attribut. Siehe Connector-Registrierung für Details.)

Diese Schnittstellen und ihre Methoden müssen implementiert werden:

• ConnectionSchnittstelle und ihre open() Und close() Methoden
• ConnectionFactorySchnittstelle und ihre createConnection(Map<String,String> properties)Methode

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 Konnektor:

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

Verbindungsfactory

Konnektoren werden normalerweise verwendet, um eine Verbindung mit einem Endpoint herzustellen. Um diese Verbindung herzustellen, seine Konfiguration und zum Testen der Verbindung bieten wir eine Implementierung eines ConnectionFactory. Die Verbindung wird für Aktivitäten des Connectors über den Kontext verfügbar, der an jede Aktivität übergeben wird.

Beispiel einer Verbindungsfactory

Ein einfaches Beispiel einer 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 hat die Klasse ExampleConnection (nicht dargestellt) würde die Verbindung tatsächlich herstellen. Die Anforderungen werden durch den jeweiligen Endpoint oder Dienst bestimmt, mit dem eine Verbindung hergestellt wird, sowie durch alle Bibliotheken, für die diese Verbindung (z. B. zu einer Datenbank oder einem Webdienst) und die Details der Verbindung.

In der Benutzeroberfläche von Integration Studio wird open() Methode der Klasse, die die Connection Schnittstelle wird aufgerufen, wenn ein Der Benutzer klickt auf die Schaltfläche Test der Verbindungskonfiguration. Dies gibt dem Connector die Möglichkeit, nicht nur die Verbindung herzustellen, sondern auch zu prüfen, ob die Verbindung funktioniert. Normalerweise kann dies durch den Aufruf des Endpoint oder Dienst und gibt entweder eine kleine Payload zurück oder verwendet den zurückgegebenen Wert zum Validieren der Verbindung.

Da diese Methode jedes Mal aufgerufen wird, wenn eine Verbindung zu einem Endpoint geöffnet wird, wenn diese derzeit nicht geöffnet ist, ist es eine gute Idee dass alle Tests schnell und klein sind, um die weitere Verarbeitung nicht zu verzögern.

Ein Beispiel hierfür finden Sie in der DropboxConnection.java des Dropbox-Connectors:

  /**
   * 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 eine bestehende Verbindung besteht, kehrt 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 Stammverzeichnis angefordert wird ("") Ordner. Die zurückgegebenen Ergebnisse werden nicht wirklich überprüft, da ein erfolgreicher Aufruf ausreicht. Wenn ein Problem mit dem Zugriffsschlüssel, den ein Benutzer zur Herstellung der Verbindung angibt, wird eine Ausnahme ausgelöst durch den Dropbox-API. Dies wird abgefangen und dann mit einer entsprechenden Fehlermeldung für den Benutzer erneut ausgelöst.

Abhängig vom Endpoint oder Dienst, mit dem der Connector arbeitet, können Variationen dieses Entwurfsmusters verwendet werden. mit.

Aktivitäten

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

• Erkennung/Konfiguration: Die Erkennung von Metadaten, die mit einer Aktivität verknüpft sind, und die Konfiguration ihrer Parameter.
• Ausführung: Eine Ausführungseinheit, die Teil einer Vorgangskette ist.

Obwohl der Erkennungsprozess in der Praxis zuerst stattfindet, werden wir hier zuerst den Ausführungsprozess besprechen, da dieser die Anforderungen des Erkennungsprozesses bestimmt.

Aktivitäten werden in der Manifestdatei wie folgt deklariert: Jitterbit-Activity-* Attribute, deren IDs auf Basis von zur Registrierung des Connectors bei Harmony. (Siehe Connector-Registrierung für Einzelheiten.)

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

Während der Laufzeit ruft der Operation die Aktivität auf, indem er die

execute(ExecutionContext) Verfahren.

Der Ausführungskontext enthält Informationen über die Anforderung (falls vorhanden) und die Payload. Die Aktivität ist verantwortlich für die Festlegung der Antwort-Payload (durch Implementierung der JitterbitActivity.ExecutionContext.getResponsePayload() Verfahren), die dann von der Operation Engine an die nächste Aktivität innerhalb der Operationskette übergeben werden.

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

• Die Parameter, sofern vorhanden, mit denen die Aktivität vom Endbenutzer konfiguriert wurde. Beispielsweise durch den Aufruf des context.getFunctionParameters().get("folder") Verfahren.
• Alle Verbindungen, die in der Erstkonfiguration der Verbindung eingerichtet wurden, sofern der Entwickler diese zur Verfügung stellt. Zum Beispiel durch den Aufruf des context.getConnection() Verfahren.
• Parameter des Connectors selbst, sofern der Entwickler diese zur Verfügung stellt.
• Die Anforderungs- oder Payload, die in die Verbindung geschrieben oder von ihr abgerufen wird.

Konfigurierbare Parameter werden vom Endbenutzer in der Benutzeroberfläche von Integration Studio festgelegt und erfolgen in der Konfiguration des Connector und seine Aktivitäten. Sie werden im adapter.json Datei in der JAR-Datei des Anschluss.

Die Anfrage- oder Antwortnutzdaten einer Aktivität sind die Daten, die entweder in die Verbindung geschrieben oder von ihr abgerufen werden. Sie werden durch die XML Schema bestimmt, die diese Nutzdaten definieren, wie im nächster Abschnitt.

Aktivitätsanforderung und -antwort

Die Anfragen und Antworten der Aktivitäten eines Connectors werden mithilfe der Java API für XML-Binding (JAXB, Version 2+), um Java-Klassen aus XML-Schemas zu generieren. Eine separate XML Schema (.xsd) wird für jede Anfrage oder Antwort verwendet. Die Zuordnung zwischen den generierten Dateien und diesen Quellen finden Sie im sun-jaxb.episode Ausgabedatei.

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

Beispielsweise im Dropbox-Connector FetchFileActivity, Daten werden von Dropbox in Harmony verschoben. Das execute() Methode verwendet eine DropboxConnection und die Dropbox-API, um Daten und Metadaten abzurufen; dann legt es diese Werte in ein Antwortobjekt (eine Instanz von FetchFileResponse) und ordnet dann die Antwort an die Ausgabestrom der Payload.

Im Dropbox-Connector hingegen PutFileActivity werden Daten von Harmony zu Dropbox verschoben.

execute() Methode in dieser Klasse arbeitet in die entgegengesetzte Richtung. Sie deserialisiert einen Eingabestream, verwendet die Dropbox API zum Hochladen auf Dropbox und erstellt dann ein Antwortobjekt (in diesem Fall eine Instanz von PutFileResponse) ergänzt mit Werten, die aus der Antwort von Dropbox stammen.

Jede Aktivität ist für die Umsetzung der getActivityRequestResponseMetadata() Methode und gibt ein ActivityRequestResponseMetaData Die XML- Schema werden verwendet, um die ActivityRequestResponseMetaData.

Um bei der Erstellung dieses Objekts zu helfen, wird ein Hilfsprogramm (wie im Dropbox-Connector gezeigt) benötigt. DropboxUtils.setRequestResponseSchemas von DropboxUtils.java) steht zum Laden der XML Schema und zum Festlegen von sie als Anfrage oder Antwort.

Sie erscheinen dann in der Benutzeroberfläche von Integration Studio im Schema, das im letzten Schritt der Aktivität angezeigt wird. Konfiguration. Wenn eine Antwort oder Anfrage nicht gewünscht oder erforderlich ist, kann sie ignoriert werden und es wird kein Datenstrukturbaum wird in der Integration Studio Benutzeroberfläche für diese Komponente erstellt. Die Dropbox-Connector-Aktivität „Datei abrufen“ ist ein Beispiel davon; es hat nur eine Antwort und keine Anforderungsdatenstruktur.

Wenn eine Anforderung erforderlich ist, kann diese in der JSON-Datei angegeben werden, die die Integration Studio Benutzeroberfläche für den Connector definiert. Durch die Erklärung inputRequired für eine Tätigkeit im adapter.json für den Connector erzwingt die Integration Studio Benutzeroberfläche einen Validierungsfehler für die übergeordnete Operation auszulösen, wenn vor der Verwendung der Aktivität. Dieses Fragment einer JSON-Datei zeigt beispielsweise, wie die SAP Aktivität BAPI als eingabepflichtig definiert wird:

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

Siehe Connector SDK UI-Komponenten für Einzelheiten zum Definieren der JSON-Datei, die die Cloud Studio-Benutzeroberfläche angibt.

Ermittlung und Metadaten

Im Rahmen des Lebenszyklus der Konfiguration einer Connector-Aktivität können Sie einen Erkennungsprozess verwenden, um Informationen abzurufen, die zum Abschließen der Konfiguration erforderlich sind.

Ein Beispiel hierfür ist das Abrufen eines Tabellennamens und aus dieser Auswahl das Abrufen von Feldnamen. Um dies zu erleichtern, gibt es eine Schnittstelle im Connector SDK (org.jitterbit.connector.sdk.Discoverable) steht zur Umsetzung bereit.

Wenn die Konfiguration für eine Aktivität in der Benutzeroberfläche von Integration Studio aufgerufen wird, getObjectList()Methode wird aufgerufen, wodurch der Connector eine Liste der erkannten Objekte erstellen und zurückgeben kann, die in der Benutzeroberfläche angezeigt werden können. Nachdem der Benutzer eine Auswahl getroffen hat, ist diese Auswahl in der Benutzeroberfläche verfügbar. getActivityRequestResponseMetadata()Methode durch die activityFunctionParamsParameter, 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 finden Sie in den Beschreibungen der Integration Studio UI-Komponenten, die Metadaten verwenden, wie im nächsten Abschnitt beschrieben.

Integration Studio Benutzeroberfläche

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

Die Datei gibt die Benutzeroberfläche für den Connector und alle seine Aktivitäten an. Die Details der JSON-Datei werden in Connector SDK UI-Komponenten behandelt.

Komponenten werden als Basiskomponenten oder komplexe Komponenten kategorisiert.

• Basiskomponenten interagieren nicht mit dem Connector. Sie werden verwendet, um einfach einen Wert vom Benutzer zu empfangen und ihn an den Connector zurückzugeben.
• Komplexe Komponenten sind anspruchsvoller und umfassen mehrere Methoden und zusätzlichen Code im Connector, um ihren Erkennungsprozess zu implementieren und bei der Ausführung zu verwenden. Sie sind für die Lösung schwierigerer Connector-UI-Herausforderungen vorgesehen.

Beachten Sie, dass die name Der in der JSON-Datei verwendete Name muss derselbe sein, unter dem der Connector registriert ist und der im Java-Code definiert ist. Siehe Connector-Registrierung für Einzelheiten.

Manifest

Diese verschiedenen Komponenten (Registrierungsinformationen für den Connector und jede Aktivität, Klassen, Drittpartei Klassenpfad, Connector-UI-Dateiname) sind im MANIFEST.MF das in der JAR-Datei enthalten ist, die den Connector archiviert. Die Einzelheiten der Registrierung und des Manifests werden in Connector-Registrierung behandelt.

Erstellen des Connectors

Wie bei einem Java-Projekt dieser Komplexität üblich, ein Maven pom.xml Datei ist wichtig, um alle importierten Abhängigkeiten und alle Komponenten richtig miteinander zu verknüpfen. Wenn Sie den Build ausführen, müssen Sie zuerst die XML-Schemadateien kompilieren, bevor Sie mit der Java-Kompilierung und-Verpackung beginnen. Der entsprechende Maven-Befehl lautet:

$ mvn jaxb2:xjc compile install

Installieren

Im Gegensatz zu Jitterbit-Plugins (die installiert werden, indem sie auf Harmony hochgeladen werden und die Plattform, um sie zu installieren, indem Sie die Plugins einer Agentengruppe zuordnen), Harmony-Konnektoren, die mit Die SDKs werden installiert, indem die JAR-Dateien manuell in das entsprechende Verzeichnis eines privaten Agenten gelegt werden. Wenn die Connector für eine Agentengruppe mit mehr als einem Agenten verwendet werden soll, müssen die JAR-Dateien in jeden privaten Agent. Wenn der Connector von bestimmten Bibliotheken abhängt, die nicht in seinen JAR-Dateien enthalten sind, müssen diese im Klassenpfad jedes privaten Agenten installiert, so dass sie zum Zeitpunkt der Installation des Connectors zugänglich sind. vom Agenten geladen.

Wenn Sie einen Connector entwickeln und dieser unter Linux oder macOS läuft, empfehlen wir die Verwendung eines privaten Docker-Agenten, da dieser so konfiguriert, dass es als lokales Volume für den Agenten das Build-Verzeichnis des Connectors bereitstellt. Für Windows ist ein Windows Es kann ein privater Agent verwendet werden.

Das Connector-Verzeichnis wird vom Agenten automatisch auf Änderungen geprüft und alle geänderten Connectors werden automatisch neu geladen, ohne dass der Agent neu gestartet oder dazu aufgefordert werden muss. Dies beschleunigt und vereinfacht den Entwicklungsprozess. Beachten Sie, dass Sie nicht direkt in dieses Verzeichnis bauen sollten, da die Zwischenprodukte kann den Agenten verwirren.

Anschlussorte

Synchronisieren

Öffentliche Konnektoren (von Jitterbit veröffentlichte Konnektoren) werden bei Bedarf automatisch mit einem Jitterbit-Agenten synchronisiert. Um zu verhindern, die Synchronisierung von öffentlichen Konnektoren, eine Umfeld (SKIP_SYNC_CONNECTORS) ist verfügbar, das steuert Synchronisierung. Legen Sie diese Umfeld in der Shell fest, in der der Agent ausgeführt wird, und starten Sie den Agent neu.

Einstellung SKIP_SYNC_CONNECTORS mit einem Sternchen beendet die Synchronisierung aller öffentlichen Konnektoren:

SKIP_SYNC_CONNECTORS=*

Einstellung SKIP_SYNC_CONNECTORS zu einer durch Kommas getrennten Liste von Konnektoren stoppt die Synchronisierung aller öffentlichen Konnektoren außer den aufgeführten:

SKIP_SYNC_CONNECTORS=Box,Magento

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

Vollständiges Beispiel

Der Dropbox-Connector ist ein vollständiges Arbeitsbeispiel für diese Konzepte. Weitere Einzelheiten finden Sie hier.

Wenn Sie den Dropbox-Connector mit Ihrem eigenen Paket und Ihrer eigenen Domäne in Ihren eigenen Connector umwandeln 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 gegebenenfalls durch Ihre eigene Domäne; aktualisieren Sie den Artefaktnamen und Version
• MANIFEST.MF: Ersetzen Sie die Verwendung von Jitterbit gegebenenfalls durch Ihren eigenen Namen; aktualisieren Sie die Schlüssel und IDs
• DropboxConstants.java: Aktualisieren Sie den Namespace in Verbindung mit den XML-Schema-XSD-Dateien; aktualisieren Sie den Connector-Namen
• XML-Schema-XSD-Dateien: Aktualisieren Sie den Ziel-Namespace in Verbindung mit den DropboxConstants.java
• adapter.json Und BaseJitterbitConnector: Das Namensfeld des adapter.json und der Name, der die Klassenerweiterung annotiert BaseJitterbitConnector werden zur Benennung des Konnektors verwendet. Wenn in der adapter.json, das Framework wird diesen Namen verwenden; andernfalls wird der in der Annotation angegebene Name verwendet. Siehe DropboxConstants.java Und DropboxConnector.java für Beispiele, wie das passiert.

Codestil

Der Dropbox-Connector wurde gemäß dem Java-Codestil von Jitterbit formatiert. Dieser Stil sollte für jeden Code befolgt werden, der im Rahmen der Zertifizierung eines Connectors an Jitterbit übermittelt wird. So implementieren Sie diesen Stil in Ihrem Quellcode: Fügen Sie in Ihren Quellcode das Jitterbit ein. ␠␠ checkstyle.xml Datei; und - fügen Sie sie in Ihre pom.xml einen Verweis auf die maven-checkstyle-plugin und das checkstyle.xml Datei. Fügen Sie zur <plugins> der <build> Abschnitt des pom.xml:

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

Siehe den Dropbox-Connector pom.xml für ein Beispiel zur Verwendung dieses Prüfstils in einem Projekt.