Der DLE JDBC Konnektor

Die Klasse DLEJDBCConnector implementiert einen allgemeingültigen DLE Konnektor, der JDBC für den Datenzugriff und das Transaktionsmanagement verwendet.
Der JDBC Konnektor ist der Referenzkonnektor der DLE. Er schränkt keinerlei Funktionalität der DLE ein.
Der Konnektor verwendet folgende Dienstparameter:

Parameter	Beschreibung
ConnectionFactory	Klassenname der Klasse, die die Verbindung aufbauen soll. Diese muß das Interface DLEJDBCConnectionFactoryIfc implementieren. Üblicherweise wird die Klasse DefaultJDBCConnectionFactory verwendet. Optional, seit der Version 1.6.6. wird per Default auf dem Client eine DefaultJDBCConnectionFactory, auf dem Server eine DLEPooledJDBCConnectionfactory verwendet.
JDBCDriver	Der Name der JDBC Treiberklasse, zum Beispiel com.ibm.db2.jdbc.app.DB2Driver. Die Klasse muss im Klassenpfad sein, damit sie geladen werden kann. Seit der Version 1.6.6. Optional, der richtige Treiber wird bei neueren JDBC Treibern automatisch gefunden.
JDBCURL	Die URL für die Datenbankverbindung. Wie diese aufgebaut ist, hängt vom gewählten JDBCDriver ab, die Treiberspezifische Dokumentation ist hier zu konsultieren. Beispiel für eine DB2 URL: jdbc:db2:DB_NAME
JDBCUser	Der Benutzername für die Datenbankverbindung.
JDBCPassword	Das unverschlüsselte Kennwort für die Verbindung.
EncodedPassword	Alternativ zu dem Parameter JDBCPassword kann hier ein verschlüsseltes Kennwort angegeben werden. Näheres dazu weiter unten.
TransactionLevel	Die verwendete Transaktionsstufe: none, local oder xa. (Siehe Transaktionen).
IsDLEManaged	True oder False, steuert ob der DLE Transaktionsmanager diesen Konnektor verwalten soll. (Siehe Transaktionen). Seit der Version 1.6.6. Optional, ist per Default True.
Dialect	Der verwendete Datenbankdialekt. Derzeit werden die Dialekte db2, oracle, informix und hsqldb, mysql, postgres, firebird, sqlserver, access unterstützt.
TraceSqlDetail	Steuert den Detailgrad der Protokollierung. Mögliche werte sind true (Vorgabe) oder false. Bei dem Wert false werden keine Detailinformationen ausgegeben.
UseJNDI	Wird derzeit nur von der ConnectionFactory DB2XAConnectionFactory verwendet. Mögliche Werte sind true oder false. Bei true wird durch den mit den Parametern JNDIService und JNDIName eine Datenbankverbindung über JNDI aufgebaut. Bei dem Wert false wird eine normale Verbindung aufgebaut.
JNDIService	Wird derzeit nur von der ConnectionFactory DB2XAConnectionFactory verwendet. Gibt den in der Konfiguration definierten JNDI Dienst an.
JNDIName	Wird derzeit nur von der ConnectionFactory DB2XAConnectionFactory verwendet. Gibt den JNDI Namen an.
Database	Wird derzeit nur von der ConnectionFactory DB2XAConnectionFactory verwendet. Gibt den Datenbanknamen an, wenn die Verbindung nicht über JNDI erfolgt.
Server	Wird derzeit nur von der ConnectionFactory DB2XAConnectionFactory verwendet. Gibt den Servernamen an, wenn die Verbindung nicht über JNDI erfolgt.
IsolationLevel	Bei der Verwendung von Transaktionen kann hier der Isolation Level der Verbindung gesetzt werden. Mögliche Werte sind: READ_UNCOMMITTED, READ_COMMITTED, REPEATABLE_READ, SERIALIZABLE
SqlInitCommands	Hier können ein oder mehrere SQL Kommandos angegeben werden, die initial beim Öffnen der Verbindung ausgeführt werden. Mehrere Kommandos können durch ein Semikolon getrennt werden. Soll ein Semikolon als Teil des Kommandos verstanden werden, ist es mit \; zu maskieren. Ab DLE Version 2.1.2 kann bei Verwendung vom Datenbankpool an dieser Stelle aktuell nur mehr ein einziges Statement verwendet werden.

ColumnNameQuote	Diese Option dient zur Maskierung von Spaltennamen, die als reservierte Worte in der jeweiligen Datenbank gelten. Hier kann optional ein Zeichen angegeben werden, mit dem dann die SQL Spaltennamen bei Kommandos wie Insert/Update und Delete maskiert werden. Bei den meisten Datenbanken ist dies normalerweise das doppelte Anführungszeichen. Im XML als " zu schreiben. MySQL Datenbanken verwenden üblicherweise den Backtick (`). Es werden nur die internen DLE Kommandos zur Datenmanipulation über Metadaten und die Script-Kommandos (Erstellen, ändern von Tabellen etc.) unterstützt. Bei freiem SQL ist das setzten der richtigen Zeichen vom Entwickler zu beachten. Der Connector ersetzt beim Ausführen des SQLs die Zeichenfolge $BASE:ColumnQuote! durch eine evtl. konfigurierte ColumnNameQuote

ColumnNameQuote

Diese Option dient zur Maskierung von Spaltennamen, die als reservierte Worte in der jeweiligen Datenbank gelten. Hier kann optional ein Zeichen angegeben werden, mit dem dann die SQL Spaltennamen bei Kommandos wie Insert/Update und Delete maskiert werden. Bei den meisten Datenbanken ist dies normalerweise das doppelte Anführungszeichen. Im XML als " zu schreiben. MySQL Datenbanken verwenden üblicherweise den Backtick (`).
Es werden nur die internen DLE Kommandos zur Datenmanipulation über Metadaten und die Script-Kommandos (Erstellen, ändern von Tabellen etc.) unterstützt. Bei freiem SQL ist das setzten der richtigen Zeichen vom Entwickler zu beachten. Der Connector ersetzt beim Ausführen des SQLs die Zeichenfolge $BASE:ColumnQuote! durch eine evtl. konfigurierte ColumnNameQuote

Verbindungsaufbau

Die Verbindung zu einer Datenbank wird nicht direkt durch die angegebene Treiberklasse aufgebaut, sondern an eine Factory Klasse delegiert, die mit dem Parameter ConnectionFactory spezifiziert wird.
Diese Klasse muss das Interface DLEJDBCConnectionFactoryIfc implementieren, es definiert zwei Methoden:

Object getConnection(DLEConnectorIfc connector)
Object getConnection(DLEConnectorIfc connector, String usr, String pw)

Diese Methoden müssen eine gültige Instanz einer java.sql.Connection oder javax.sql.XAConnection zurückliefern. Eine XAConnection wird für die Unterstützung von verteilten Transaktionen benötigt. Wird nur eine normale i zurückgegeben, unterstützt der Konnektor keine verteilten Transaktionen. Im Fehlerfall sollten beide Methoden eine java.sql.SQLException werfen.
Verbindungen werden bei dem ersten Datenzugriff aufgebaut und bleiben für die Dauer der DLE Nutzung bestehen.

Transaktionen

Wurde durch die ConnectionFactory eine XAConnection zurückgegeben, unterstützt der Konnektor alle Transaktionsstufen. Bei Rückgabe einer Connection werden maximal lokale Transaktionen unterstützt.
Wird die Transaktionsstufe durch den Parameter TransactionLevel auf none gesetzt, schaltet der Konnektor automatisch die Verbindung auf auto commit, das heißt alle Anweisungen werden durch JDBC sofort durch commit bestätigt. (Siehe dazu die JDBC Dokumentation von Java).

DefaultJDBCConnectionFactory

Diese Klasse erstellt eine Verbindung zu einer Datenbank mithilfe einer java.sql.Connection. Diese Verbindung unterstützt keine verteilten Transaktionen.

DB2XAConnectionFactory

Diese Klasse erstellt eine Verbindung zu einer Datenbank mithilfe einer javax.sql.XAConnection. Wurde das Parameter UseJNDI auf true gesetzt, wird mittels des in der Konfiguration definierten JNDI Dienstes eine DB2XADataSource geladen, über die eine DB2XAConnection ermittelt wird. Der zu verwendende JNDI Dienst wird mit dem Parameter JNDIService spezifiziert. Der Name der DB2XADataSource wird über den Parameter JNDIName angegeben.
Wurde das Parameter UseJNDI auf false gesetzt, wird eine neue Verbindung über einen Server- und Datenbanknamen erstellt. Der Server wird mit dem Parameter Server und der Datenbankname mit dem Parameter Database angegeben.

Datenbankdialekte

Datenbanken unterscheiden sich vielfach in der SQL Syntax. Um kleine Unterschiede, wie Datumsbehandlung und Sequenzen zu unterstützen ohne einen zusätzlichen Konnektor zu implementieren, kann mit dem Parameter Dialect der Datenbankdialekt spezifiziert werden. Derzeit Unterstützte Dialekte sind oracle, db2 (Auch für IBM iSeries/AS400), informix und hsqldb.
Wird eine Verbindung zu einer Oracle Datenbank gewünscht, ist jedoch neben dem Dialekt auch der spezielle Oracle JDBC Konnektor zu verwenden.

Kennworte

Für eine Datenbankverbindung werden normalerweise ein Benutzername und ein Kennwort benötigt. Diese werden durch die Parameter JDBCUser und JDBCPassword angegeben. Soll das Kennwort nicht in Klarschrift lesbar sein, so gibt es die Möglichkeit, dieses zu verschlüsseln.
Das Skript DLE/scripts/crypt.bat kann dazu verwendet werden, ein Kennwort zu verschlüsseln. Als Parameter erhält es das zu verschlüsselnde Kennwort. Das verschlüsselte Kennwort kann dann für den Konnektor in dem Parameter EncodedPassword hinterlegt werden. Das Parameter JDBCPassword darf in diesem Fall nicht angegeben werden, da es sonst anstelle von EncodedPassword verwendet wird.