JDBC-Empfänger-Adapter konfigurieren 

Verwendung

Sie konfigurieren den JDBC-Empfänger-Adapter, um damit XML-Messages von der Integration Engine in Inhalte von Datenbanktabellen zu verwandeln.

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

·        der Adresse (HTTP-Port und URL), unter der der Adapter von der Integration Engine aus erreicht werden kann

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 Adapter-Moduls aufgerufen

Vorgehensweise

Für den JDBC-Empfänger-Adapter besteht die Konfiguration aus fünf funktionalen Teilbereichen:

...

       1.      Der Name der Java-Klasse für den JDBC-Empfänger-Adapter

Geben Sie den Namen der Klasse folgendermaßen an:

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

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-Empfänger-Adapters an. Erlaubte Werte sind:

○       mode=XMB2DB

○       mode=XMB2DB_XML

○       mode=XMB2DB_RAWSQL

Abhängig vom gewählten Modus bietet der Adapter verschiedene Funktionalitäten und erwartet dafür jeweils spezielle Dokumentenformate in der empfangenen Nachricht vom Integration Server. Grundsätzlich gilt:

○       Im Modus XMB2DB werden Tabellenwerte in eine in der Konfiguration des Adapters spezifizierten Tabelle eingefügt. Dieser Modus ist aus Kompatibilitätsgründen mit den älteren Versionen des JDBC-Adapters beibehalten worden, sollte aber im Prinzip nicht mehr verwendet werden.

○       Im Modus XMB2DB_XML können Tabellenwerte in einer oder mehreren Tabellen eingefügt, geändert oder gelöscht werden. Darüber hinaus können in der Datenbank vorhandene Stored Procedures mit Übergabeparametern aufgerufen werden. In synchronen Abfragen können auch Ergebnisse von Datenbankabfragen bzw. Rückgabewerte von Stored Procedures übertragen werden.

Diese Funktionalität wird jeweils durch die Übermittlung vordefinierter XML-Schemata beschrieben, die weiter unten erläutert werden. Hierbei können beliebige und beliebig viele Aktionen in einer Nachricht gebündelt werden. Alle Aktionen werden dann jeweils innerhalb einer Datenbanktransaktion ausgeführt, also komplett oder gar nicht.

○       Im Modus XMB2DB_RAWSQL wird als Inhalt der Nachricht ein beliebiges SQL-Statement erwartet, das unverändert an die Datenbank zur Verarbeitung übergeben wird. Dieser Modus ist hauptsächlich zu Testzwecken gedacht.

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

       4.      Die Angaben für die Adressierung von der Integration Engine

○       XI. httpPort=<port_no>

<port_no> gibt den Port des HTTP-Servers an, der die Nachrichten der Integration Engine entgegennimmt.

○       XI. httpService=<service>

<service> beschreibt den Service-Teil der Adresse, zu dem die Integration Engine ihre Nachrichten schicken muss.

Diese Angaben sind zwingend.

Haben Sie zum Beispiel XI.httpPort=1234 und XI.httpService=/db/Receiver spezifiziert, muss die Endpunkt-Adresse des JDBC-Adapters in der Integration Engine wie folgt spezifiziert sein:

http://<Datenbankadapterhost>:1234/db/Receiver

Für die Integration Engine in der Version 1.0 muss die Endpunkt-Adresse wie folgt erweitert werden:

http://<Datenbankadapterhost>:1234/db/Receiver?action=execute&pipelineid=Receiver

Wird die Nachricht von der Integration Engine an einen nicht spezifizierten Service des Adapters geschickt, erfolgt die Fehlermeldung

No registered listener for <service> found

Die gleiche Fehlermeldung erhält man, wenn der Adapter initialisiert, aber nicht gestartet ist (sich also im Status ANGEHALTEN oder INITIALISIERT befindet).

○       XI.ReceiverAdapterForService=<Service>

Diese Angabe ist optional.

<Service> ist der logische Name eines Business-Systems im System Landscape Directory (SLD). Ist die Verbindung der Adapter-Engine zum SLD konfiguriert, wird für den JDBC-Empfänger-Adapter eine Assoziation zu diesem Business-System angelegt. Im Integration Directory wird beim Anlegen eines Endpunkts für dieses Business-System, aus dieser Assoziation die Adresse des Adapters als Vorschlagswert ermittelt.

Kann keine Verbindung zum SLD hergestellt werden, oder existiert das Business-System im SLD nicht, ist die Angabe bedeutungslos.

       5.      Die Angaben für die Datenbankzugriffe

Diese Angaben sind alle zwingend und haben keine Vorschlagswerte.

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

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

Bei Datenbankverbindungsfehlern baut der JDBC-Adapter die Datenbankverbindung automatisch wieder neu auf.

¡        db.execute=<operating system command>

Ein hier spezifiziertes Betriebssystemkommando wird nach fehlerfreien Datenbankoperationen ausgeführt. Der Vorschlagswert ist eine leere Zeichenkette (kein Kommando).

○       db.noOfRetries=<n>

Bei einer SQL-Exception wird die Datenbankverbindung so oft wie angegeben neu aufgebaut und der Zugriff wird wiederholt. Ist die Anzahl der Wiederholungsversuche abgelaufen, wird der letzte Zustand an den sendenden Integration Server zurückgemeldet. Im Fehlerfall wird die Nachricht also erst dann erneut verarbeitet, wenn sie vom Integration Server erneut versendet wird.

Der Vorschlagswert ist 0.

○       db.disconnect=NO|YES

Nach jeder Datenbanktransaktion wird die Datenbank geschlossen und die Datenbankverbindung wird aufgelöst (YES) bzw. aufrechterhalten (NO).

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.

       6.      Zusätzliche Angaben zur Behandlung von Nachrichten mit Quality-of-Service = Exactly Once (In Order)

¡        db.exactlyOnceErrorInPendingState=IGNORE|ERROR

Die Behandlung von Nachrichten des Typs Exactly Once erfolgt, wie bei den übrigen Adaptern auch, standardmäßig über die Verwaltung von Statusinformationen für diese Nachrichten im Dateisystem. Auch in diesem Modus werden sämtliche Fehlerzustände des Adapters sowie extern eingeleitete Programmabbrüche (Shutdown des Adapter-Betriebssystemprozesses) korrekt behandelt.

Eine Ausnahme hierzu bilden externe Programmabbrüche während eines Datenbank-Commit. Dann ist der Zustand der Nachrichtenverarbeitung unklar, da er erst nach Abschluss des Datenbank-Commit in der Verwaltungsdatei geändert werden kann.

Eine solche Situation wird aber bei einem Neustart der Anwendung erkannt, und die Bearbeitung der abgebrochenen Nachrichtenverarbeitung kann über db.exactlyOnceErrorInPendingState gesteuert werden.

Diese Angabe wirkt sich aber nur auf die Behandlung von Fehlern aus, die während einer wiederholten Bearbeitung von Nachrichten auftreten, deren erste Bearbeitung in dem oben beschriebenen unklaren Zustand verblieben war.

Tritt nun bei der erneuten Bearbeitung ein Fehler auf, wird dieser standardmäßig (oder wenn explizit der Wert ERRORgesetzt ist), als Fehler an das rufende System zurückgemeldet.

Tritt der Fehler aber auf, weil die Nachricht beim erstenmal doch schon in der Datenbank gespeichert wurde und sich dort noch befindet (typischerweise wird die Datenbankschnittstelle dann den Fehler duplicate insert ausgeben, falls mindestens eines der Tabellenfelder als Primary Key definiert wurde), kann mit dem Wert IGNORE die Bearbeitung für das sendende System erfolgreich abgeschlossen werden. Ansonsten wird das sendende System die Nachricht immer wieder erneut verschicken, und der Fehler tritt immer wieder auf.

Trotzdem verbleibt in der Behandlung von Exactly Once eine, wenn auch sehr kleine, Lücke: ist in der Datenbanktabelle kein Feld Primary key ausgewiesen, oder wurden die Daten von einer anderen Anwendung bereits weiterverarbeitet und anschließend gelöscht, kann die Nachricht auf diese Weise dupliziert werden, wenn die erste Verarbeitung genau nach dem Datenbank-Commit durch ein externes Beenden des Adapter-Prozesses unterbrochen wurde. Diese Lücke kann nur geschlossen werden, wenn sich die Nachrichtenverarbeitung und die Verwaltung der Statusinformationen in der gleichen Datenbank befinden, so dass ein gemeinsamer Commit-Zyklus der Verarbeitungsschritte möglich wird.

Hierzu muss in der Datenbank, in der die zu schreibende Tabelle liegt, eine zusätzliche Tabelle mit zwei Spalten angelegt werden. Spalte 1 muss vom Typ character mit Länge 36 (oder mehr) sein und den Namen XIMessage_ID tragen. Spalte 2 muss vom Typ integer sein, mit Namen XIMessage_Ts. Diese Tabelle wird dem Adapter dann wie folgt bekannt gemacht:

¡        db.tableForExactlyOnceHandling=<table name>

Ist dieser Wert gesetzt, wird anstelle der datei-basierten Exactly-Once-Verwaltung die angegebene Datenbanktabelle benutzt. Existiert die Tabelle nicht, oder werden die benötigten Spalten nicht gefunden oder sind vom falschen Typ, wird ein entsprechender Fehler ausgegeben und der Adapter startet nicht.

¡        db.tableEOColumnNameId=<column name>

Soll ein anderer Spaltenname als XIMessage_Id vergeben werden (weil zum Beispiel eine bereits existierende Tabelle benutzt werden soll), kann dieser Wert hier für die Spalte vom Typ char(36) angegeben werden. Ist eine größere Feldlänge spezifiziert, kann die Tabelle trotzdem benutzt werden. Kürzere Feldlängen sind jedoch nicht möglich. Dieser Wert wird nur ausgewertet, wenn db.tableForExactlyOnceHandling gesetzt wurde.

¡        db.tableEOColumnNameTs=<column name>

Soll ein anderer Spaltenname als XIMessage_Ts vergeben werden (weil zum Beispiel eine bereits existierende Tabelle benutzt werden soll), kann dieser Wert hier für die Spalte vom Typ integer angegeben werden. Dieser Wert wird nur ausgewertet, wenn db.tableForExactlyOnceHandling gesetzt wurde.

¡        db.exactlyOnceHandlingIDsExpiration=<n Days>

Geben Sie die Anzahl an Tagen an, die die Verwaltungsinformation empfangener Nachrichten mit dem Service-Attribut Exactly Once (In Order) aufbewahrt werden sollen. Diese Informationen werden benötigt, um Nachrichtenduplikate zu verhindern, falls die Integration Engine die gleiche Nachricht im Rahmen einer Fehlerbehandlung mehrmals an den Adapter sendet. Der Vorschlagswert ist 60 Tage. Der Wert gilt sowohl bei datei-basierter wie auch bei datenbank-basierter Statusverwaltung.

Wird der Wert auf 0 oder eine negative Zahl gesetzt, werden bei jeder Adapter-Initialisierung alle Verwaltungsinformationen gelöscht. Dies kann zu Testzwecken sinnvoll sein, sollte aber keinesfalls im Produktivbetrieb gemacht werden.

       7.      Das geforderte XML-Dokumentenformat

Das XML-Dokumentenformat hängt, wie bereits erläutert, vom Modus des JDBC-Adapters ab.

       8.      Der Adapter kann ein synchrones System-Acknowledgment zurücksenden, wenn es vom Sender angefordert wird. Das Acknowledgment bestätigt, dass die Nachricht an den Empfänger ausgeliefert wurde.

○       Wollen Sie ein synchrones System-Acknowledgment zurücksenden, setzten Sie XI.AckFinal=true. Dies ist der Vorgabewert.

○       Wollen Sie vermeiden, dass ein synchrones System-Acknowledgment zurückgesendet wird, auch wenn es vom Sender angefordert wird, setzen Sie XI.AckFinal=false.