JDBC-Sender-Adapter konfigurieren 

Verwendung

Sie konfigurieren den JDBC-Sender-Adapter, um damit Inhalte von Datenbanken an die Integration Engine zu verschicken.

Die Konfiguration besteht im Wesentlichen aus der Angabe

●      eines JDBC-Datenbanktreibers, über den auf die Datenbank zugegriffen werden kann

Dieser Treiber gehört nicht zum Lieferumfang des Adapters sondern muss vom Datenbankhersteller oder Drittanbietern geliefert werden.

·        von Anmeldedaten für die zu lesende Datenbank

·        eines SQL-Statements zur Ermittlung der gewünschten Tabelleninhalte

·        eines SQL-Statements zur Bearbeitung erfolgreich verschickter Tabelleninhalte

·        der Dispatcherklasse (optional) mit den entsprechenden Einstellungen sowie der vom Dispatcher aufzurufenden User-Exits und deren Einstellungen

·        der von der Integration Engine benötigten Absender- und Empfängerdaten für das Routing und Mapping

Voraussetzungen

Sie haben

...

       1.      einen JDBC-Treiber (Version 2.0) für die Datenbank installiert

       2.      den entsprechenden Adapter installiert

       3.      den Adapter in der Konfigurationsoberfläche ausgewählt

       4.      über Konfigurieren die Konfiguration des Adapters aufgerufen

Vorgehensweise

Für den JDBC-Sender-Adapter besteht die Konfiguration aus vier funktionalen Teilbereichen:

...

       1.      Der Name der Java-Klasse für den JDBC-Sender-Adapter

Geben Sie den Namen der Klasse folgendermaßen an:

classname=com.sap.aii.messaging.adapter.ModuleDB2XMB

Diese Angabe ist zwingend.

       2.      Die Versionsangabe für die Konfiguration.

version=30

Diese Angabe ist zwingend. Fehlt die Angabe, wird die Konfiguration als XI 2.0 Adapter-Konfiguration interpretiert. Andere Werte sind nicht zulässig und werden als Fehler ausgegeben.

       3.      Der Modus des JDBC-Adapters

Geben Sie den Modus des JDBC-Sender-Adapters an. Der einzige erlaubt Wert ist

mode=DB2XMB

In zukünftigen Versionen können weitere mögliche Werte dazukommen.

       4.      Die Dispatcherklasse und die vom Dispatcher aufzurufenden User-Exits (optional)

Der JDBC-Sender-Adapter bietet einen Dispatcher an, mit dem Sie Messages vor dem Verschicken konvertieren können. Die für den Dispatcher notwendigen Einstellungen werden anhand eines konkreten Beispiels erklärt.

       5.      Die Angaben für die Integration Engine

Geben Sie die vollständige Adresse (URL) der Integration Engine ein, an die die Message geschickt werden soll:

XI.TargetURL=http://IntegrationEngineHost:port/pipeline-arguments

Diese Angabe ist zwingend.

Die Adresse der Integration Engine kann auch dynamisch aus dem System Landscape Directory (SLD) ermittelt werden. Hierzu wird in der Konfiguration folgender Eintrag hinzugefügt:

XI.SLDConfiguration=SLDaccessor

In diesem Fall wird für das mit XI.SenderService angegebene System die URL des zugehörigen Integration Server im SLD ausgelesen und anstelle des unter XI.TargetURL angegebenen Wertes verwendet. Daher sollte hier folgendes angegeben werden:

XI.TargetURL=<fromSLD>

Damit der Zugriff funktioniert, muss der Dienst SLDaccessor für den Zugriff ins SLD konfiguriert sein, und die entsprechenden Einträge müssen im SLD gepflegt sein.

Ist der Integration Server nicht direkt, sondern über einen HTTP-Proxy-Server zu erreichen, müssen folgende Parameter gesetzt werden:

XI.proxyHost=<proxyHostname>

XI.proxyPort=<proxyPortnumber>

Hierbei ist <proxyHostname> der Host-Name des Proxy und <proxyPortnumber> der Port, auf dem der Proxy HTTP-Requests annimmt (z.B. 8080).

Wurde für die angegebene URL (HTTP-Service) in der Integration Engine eine Authentifizierung spezifiziert, sind die folgenden Angaben zwingend:

○       XI.User=<user-name>

¡        XI.Password=<password>

Die Angaben müssen mit denen übereinstimmen, die Sie in der Transaktion SICF in der Integration Engine gemacht haben. Falls Sie keine oder eine ungültige Kombination von Benutzer und Passwort angeben, wird jeder Übertragungsversuch in die Integration Engine mit Transport Exception: http-Error 401 – Unauthorized scheitern.

Der Benutzer muss im Integration Server über die Berechtigungen der Gruppe SAP_XI_APPL_SERV_USER verfügen.

Informationen zur Konfiguration der SSL-Authentifizierung mit Zertifikat finden Sie unter: Zertifikatverwaltung, dort unter Adapter Engine als SSL-Client einrichten

Soll bei der Anmeldung ein anderer Mandant bzw. eine andere Sprache als die Default-Werte der Integration Engine verwendet werden, können Sie zusätzlich die folgenden Parameter setzen:

¡        XI.Client=<client-no>

¡        XI.Language=<language-id>

Die folgenden Adress-Argumente für das Sendersystem (also den JDBC-Adapter) sind zwingend. Sie dienen der Identifikation der Adapter-Konfiguration beim Routing und Mapping in der Pipeline der Integration Engine. Dort ist auch die Bedeutung der einzelnen Argumente beschrieben.

¡        XI.SenderParty=<sender party name>

¡        XI.SenderService=<sender service name>

¡        XI.InterfaceNamespace=<namespace URI>

¡        XI.Interface=<name>

¡        XI.ReceiverParty=<receiver party name>

¡        XI.ReceiverService=<receiver service name>

Zwingend sind zumindest XI.SenderService sowie XI.Interface und XI.InterfaceNamespace. Der Empfänger ist nur dann zwingend, wenn beim Routing kein Empfänger ermittelt wird.

¡        XI.QualityOfService=<QualityOfService>

Gibt an wie eine Message durch die Integration Engine verarbeitet werden soll. Erlaubte Werte sind:

■       XI.qualityOfService=BE (Best Effort, bedeutet synchrone Verarbeitung)

§         XI.qualityOfService=EO (Exactly Once, bedeutet asynchrone Verarbeitung mit garantierter einmaliger Ausführung)

§         XI.qualityOfService=EOIO (Exactly Once in Order, bedeutet asynchrone Verarbeitung über Queues, also eine garantierte einmalige Ausführung unter Beibehaltung der Reihenfolge aufeinanderfolgender Nachrichten)

Bei EOIO muss zusätzlich ein Queue-Name definiert werden:

¡        XI.QueueId=<QueueName>

Dieser Queue-Name wird in der Integration Engine verwendet, um Nachrichten in der Reihenfolge ihres Eingangs zu bearbeiten.

       6.      Die Angaben für die Datenbankzugriffe

¡        db.jdbcDriver=<java_class_of_jdbcdriver>

Geben Sie die Java-Klasse des JDBC-Treibers an, die der JDBC-Adapter laden muss, um auf den Treiber zugreifen zu können. Die genaue Angabe variiert je nach JDBC-Treiber und muss aus den Unterlagen des jeweiligen Anbieters hervorgehen. Die Angabe ist zwingend.

¡        db.connectionURL=<jdbc_driver_connection_url>

Geben Sie die Adresse an, unter der über den JDBC-Treiber eine Datenbankverbindung geöffnet werden kann. Das genaue Format der Adresse kann variieren und muss aus den Unterlagen des jeweiligen Anbieters hervorgehen. Die Angabe ist zwingend.

○       db.user=<username>

○       db.password=<password>

Anstelle der Datenbankanmeldung innerhalb der mit dem Parameter db.connectionURL spezifizierten Zeichenkette kann auch die Datenbankanmeldung mit Benutzer und Kennwort explizit angegeben werden. Dadurch wird im JDBC-Adapter anstelle des JDBC-Aufrufs getConnection(url) der Aufruf (url,user,password) ausgeführt, der von manchen Datenbanksystemen erwartet bzw. anders behandelt wird.

○       db.reconnect=YES|NO

Hier können Sie angeben, ob im Falle eines Verbindungsfehlers zur Datenbank die Verbindung über den JDBC-Treiber bei jedem Datenbankzugriff neu aufgebaut werden soll. Voreingestellt ist YES. Wenn Sie NO angeben, bricht der JDBC-Adapter beim ersten Fehler der Datenbankverbindung ab und muss über die Administrationsoberfläche neu gestartet werden.

○       db.processDBSQLStatement=<SQL-Select-Statement>

Geben Sie entweder eine gültige SQL SELECT-Anweisung an zur Auswahl der zu verschickenden Daten aus der spezifizierten Datenbank, oder eine SQL EXECUTE-Anweisung zur Ausführung einer Stored Procedure, die genau eine SELECT-Anweisung enthält. Der Ausdruck muss nur der vom jeweiligen JDBC-Treiber unterstützten SQL-Variante entsprechen, kann also auch zum Beispiel Tabellen-JOINs enthalten. Die Angabe ist zwingend.

¡        db.confirmDBSQLStatement=<SQL-Update-Statement>

Geben Sie eine gültige SQL-Anweisung an, die nach dem erfolgreichen Verschicken der (mit db.processDBSQLStatement) ermittelten Daten an die Integration Engine auf die Datenbank angewendet werden soll. Dies muss eine INSERT-, UPDATE- oder DELETE-Anweisung sein. Typische Szenarien wären zum Beispiel, die verschickten Daten mit einer DELETE-Anweisung aus der Datenbank zu löschen oder mit einer UPDATE-Anweisung zu markieren. Als Alternative kann anstelle einer SQL-Anweisung auch die Angabe <TEST>gemacht werden (inklusive der spitzen Klammern). In diesem Fall wird nach dem erfolgreichen Versenden keine Datenbankoperation durchgeführt, und die Daten in der Datenbank bleiben unverändert.

Voreingestellter Wert ist <TEST>. Dies kann (außer zu Testzwecken) sinnvoll sein, wenn die Daten zum Beispiel durch eine in der Anweisung db.processDBSQLStatement definierte Stored Procedure nicht nur gelesen, sondern bereits verändert wurden.

Dies hat zur Folge, dass die Daten nach einem Neustart des Adapters oder nach der in db.pollInterval angegebenen Zeitspanne erneut als neue Nachricht versendet werden. Dieser Modus eignet sich daher ausschließlich zum Testen von Konfigurationen des Adapters oder der Integration Engine und nicht für den Produktivbetrieb.

Im Modus Exactly Once erfolgt die Ausführung der unter db.processDBSQLStatement und db.confirmDBSQLStatement angegebenen Anweisungen sowie das Aufbereiten der Nachricht innerhalb einer Datenbanktransaktion. Das Versenden der Nachricht erfolgt anschließend. Die Nachricht wird hierbei temporär im Verzeichnis /Datader Adapter-Engine als Datei persistiert, bis das Versenden der Nachricht zum Integration Server erfolgreich war.

¡        db.execute=<operating system command>

Ein hier spezifiziertes Betriebssystemkommando wird nach erfolgreichen Datenbankoperationen (Statements PROCESS und CONFIRM) ausgeführt. Der Vorschlagswert ist eine leere Zeichenkette (kein Kommando).

○       db.pollInterval=

Geben Sie die Anzahl an Sekunden an, die der Adapter warten soll, bevor er das db.processDBSQLStatement erneut aufruft.

Die Angabe ist zwingend. Optional können Sie zusätzlich den folgenden Parameter angeben, um eine zusätzliche Wartezeit in Millisekunden anzugeben:

db.pollIntervalMsecs=

Ist db.pollInterval auf 0 gesetzt, lassen sich so sehr kurze, echtzeitnahe Verarbeitungszeiten erreichen.

Der Vorschlagswert für diesen Parameter ist 0.

Wenn kein wiederholter Aufruf stattfinden soll, müssen Sie beide Parameter auf 0 setzen (bzw. nur den Parameter db.pollInterval, wenn Sie für den Parameter db.pollIntervalMsecs keinen Wert angeben).

Wenn kein wiederholter Aufruf stattfinden soll, kann der Wert auf 0 gesetzt werden. In diesem Fall verbleibt der Adapter zwar im Status ANGEHALTEN muss aber über Anhalten/Starten bzw. Neu starten erneut gestartet werden, um einen erneuten Aufruf zu initiieren.

○       db.retryInterval=

Geben Sie die Anzahl an Sekunden an, die der Adapter warten soll, bis ein fehlerhaft verarbeitetes SQL-Statement erneut verarbeitet wird.

Als Voreinstellung wird der Wert von db.pollInterval übernommen. Ist dieser Wert 0 (findet also keine Wiederholung der Verarbeitung stattfindet), wird auch keine erneute Verarbeitung von fehlerhaft verarbeiteten SQL-Statements vorgenommen.

Ist db.retryInterval gleich 0, wird im Fehlerfall der Adapter beendet, auch wenn für db.pollInterval ein Wert größer 0 angegeben wurde. In diesem Fall verbleibt der Adapter zwar im Status GESTARTET muss aber über Anhalten/Starten bzw. Neu starten erneut gestartet werden, um eine erneute Verarbeitung zu initiieren.

¡        db.logPollInterval=NO|YES

Im Protokoll des Adapters wird der Eintritt in die Warteschleife standardmäßig ausgegeben bei Warteschleifen, die länger als 5 Sekunden dauern. Dies kann zu entsprechend vielen Ausgaben im Protokoll führen. In solchen Fällen kann die Ausgabe im Protokoll (nicht die Warteschleife selbst) mit db.logPollInterval=NO abgeschaltet werden.

Bei Warteschleifen, die 5 Sekunden oder weniger dauern, kann die Ausgabe mit db.logPollInterval=YESaktiviert werden.

○       db.disconnect=NO|YES

Vor jedem Poll-Intervall wird die Datenbankverbindung freigegeben und anschließend neu aufgebaut.

Der Vorschlagswert ist NO.

○       db.autoCommit=NO|YES

Die Transaktionsklammer, die der JDBC-Adapter benötigt um konsistente Daten in der Datenbank sicherzustellen, kann mit diesem Parameter abgeschaltet werden. Diese Option wird für JDBC-Treiber benötigt, die keine Transaktionen unterstützen. Es muss dann aber anderweitig sichergestellt werden, dass keine Dateninkonsistenzen in der Datenbank erzeugt werden können, das heißt, in der Regel müssen parallele Zugriffe unterbunden werden.

Der Vorschlagswert ist NO.

Dieser Parameter darf keinesfalls auf YES gesetzt werden, wenn der JDBC-Treiber Transaktionen unterstützt, das heißt, wenn im Normalbetrieb keine entsprechende Fehlermeldung erscheint.

○       db.transactionIsolation=0|1|2|4|8

Datenbanktransaktionen können in verschiedenen Abstufungen (Isolation Levels) betrieben werden. Der JDBC-Adapter verwendet standardmäßig die höchste Isolierungsstufe, um Datenbankinkonsistenzen durch parallele Datenbanktransaktionen zu vermeiden. Bei einigen JDBC-Treibern kann eine Reduzierung dieses Level notwendig sein, wenn der Treiber bzw. das Datenbankprodukt diesen Level nicht unterstützt. Eine Reduzierung des Level kann zu Lasten der Transaktionssicherheit und damit der Datenintegrität gehen und sollte nur wenn nötig angewendet werden. Die oben aufgeführten Werte entsprechen den folgenden JDBC-Konstanten:

■       0 – TRANSACTION_NONE

■       1 – TRANSACTION_READ_UNCOMMITED

■       2 – TRANSACTION_READ_COMMITED

■       4 – TRANSACTION_REPEATABLE_READ

■       8 – TRANSACTION_SERIALIZABLE

Ist der Parameter nicht gesetzt, dann ist der Vorgabewert der angeschlossenen Datenbank wirksam.

Der Level sollte nur wenn nötig und nur so weit wie benötigt reduziert werden. Gegebenenfalls muss dann aber anderweitig sichergestellt werden, dass keine Dateninkonsistenzen in der Datenbank erzeugt werden können, das heißt, in der Regel müssen parallele Zugriffe unterbunden werden.

¡        db.documentName=<name>

Wenn Sie einen Dokumentnamen angeben, wird dieser als Haupt-XML-Tag in die Nachricht eingefügt. Die Voreinstellung ist resultset (siehe unten).

¡        db.documentNamespace=<namespace>

Wenn angegeben, wird der Namensraum an den Namen des Dokuments angehängt.

       7.      Das Verhalten des Adapters, wenn er angehalten wird.

db.stopMode=0|1

○       0 Die Verarbeitung wird sofort abgebrochen, wenn der Adapter angehalten wird.

○       1 Die Message, die gerade verarbeitet wird, wird komplett verarbeitet und der Adapter wird angehalten.

Der Vorschlagswert ist 0.

Ergebnis

Die aus dem db.processDBSQLStatement erhaltene Tabelle wird in ein gültiges XML-Dokument konvertiert und in dieser Form an die Integration Engine geschickt. Das Dokument hat folgendes Aussehen:

<resultset>

<row>

<column-name1>column-value</column-name1>

<column-name2>column-value</column-name2>

<column-name3>column-value</column-name3>

</row>

<row>

<column-name1>column-value</column-name1>

<column-name2>column-value</column-name2>

<column-name3>column-value</column-name3>

</row>

</resultset>

Dieses Dokumentenformat kann dann durch die Integration Engine weiterverarbeitet werden.