Anleitung BaseLink

Ist eine Klasse wie im vorigen Abschnitt beschrieben mittels Annotationen an eine Datenbanktabelle gebunden, können Objekte dieser Klasse als DTO auf die Datenbank abgebildet werden. BaseLink kann für solche DTO mit Hilfe der Klasse GenericRecord das SQL für die Datenbankoperationen dynamisch erzeugen.

Stattdessen kann für die Klasse eines DTO auch zuvor ein Wandler-Objekt gebildet werden:

Record userWandler = new GenericRecord(User.class);

Mit dieser Vorgehensweise muss BaseLink nicht immer erst implizit einen Wandler für ein DTO bilden und später wieder freigeben. Ein so erzeugtes Wandler-Objekt ist für alle DTOs einer Klasse wiederverwendbar. Im Falle häufiger Datenbankoperationen kann damit effizienter gearbeitet werden.

Der PersistenceManager ist die zentrale Klasse von BaseLink. Sie stellt Verbindungen zu einer Datenbank her und hält Methoden zur Arbeit mit der Datenbank bereit. Eine Instanz des PersistenceManagers repräsentiert eine Datenbank.

Instanzen des PersistenceManagers verbrauchen ansonsten keine Ressourcen, sie können bedenkenlos nach Bedarf instanziiert werden, die Garbage Collection der Java Virtual Machine gibt sie automatisch wieder restlos frei. Lediglich im Falle der Nutzung von Transaktionen sollten die Verbindungen zur Datenbank stets geschlossen werden bevor ein PersistenceManager der Garbage Collection überlassen wird.

Für das Speichern, Ändern und Löschen von Daten liefert BaseLink die Standardmethoden insert, update und delete. Sie sind jeweils gleich aufgebaut und erfordern im einfachsten Fall als Parameter das Objekt, das gespeichert, geändert oder gelöscht werden soll.

Wenn viele Datenbankoperationen ausgeführt werden sollen kann es effizienter sein, einen Wandler für eine Klasse bereitzuhalten, dann muss er nicht bei jeder Operation gebildet und wieder freigegeben werden (vgl. Abschnitt Wandler-Objekte). BaseLink hält für diesen Zweck eine Variante bereit, die als zusätzlichen Parameter einen Wandler akzeptiert.

Diese Vorgehensweise funktioniert so auch für die Methoden update und delete. Der Rückgabewert ist stets entweder das übergebene Objekt oder null, falls die Operation nicht durchgeführt werden konnte (vgl. Fehlerbehandlung). Für eine Rückgabe erzeugter Schlüssel siehe Abschnitt Schlüsselrückgabe.

Die Methode select des PersistenceManagers dient in verschiedenen Varianten zum Lesen aus der Datenbank. Das geschieht stets mit Hilfe von Ausdrücken der Structured Query Language (SQL). Hierbei unterstützt BaseLink hauptsächlich an zwei Stellen:

Für das Gelingen von Punkt 1 oben muss die SQL-Abfrage die Felder ausgeben, die vom Zielobjekt erwartet werden. Die Parameter an den Aufruf von select müssen in der Reihenfolge übergeben werden, in der sie im SQL-Ausdruck enthalten sind, damit Punkt 2 funktioniert.

Die obigen Funktionen werden in folgendem Beispiel veranschaulicht:

Wird die Methode getUser in obigem Beispielcode mit zwei Vornamen gerufen wie z.B. in

List nutzerliste = getUser("Maria", "Peter");

gibt sie ein Objekt der Klasse List zurück. Diese Liste enthält alle Benutzer, deren Vorname Maria oder Peter lautet, als Objekte der Klasse User.

Ein Beispiel, das freilich so in der Praxis vermutlich nicht vorkommt. Es zeigt aber, dass die Methode select mit einer unterschiedlichen Anzahl von Parametern gerufen werden kann. Die Parameter richten sich nach den veränderlichen Elementen des SQL-Ausdrucks. Im Beispielcode werden die mit Fragezeichen markierten Platzhalter der SQL-Abfrage where user_first = ? or user_first = ? mit den Inhalten der Parameter name1 und name2 befüllt.

Damit SQL-Ausdrücke in der Praxis nicht wie im Beispiel hart codiert im Quellcode enthalten sein müssen, empfiehlt sich eine Vorgehensweise, wie sie der Abschnitt SQL-Konfiguration beschreibt.

Der Parameter Record.WITHOUT_BLOBS regelt, ob eine Abfrage den Inhalt von Binary Large Objects (BLOBs) ausgibt oder nicht. Er kann verwendet werden, um die Ausgabe zu beschleunigen, wenn es absehbar ist, dass die Abfrage keine BLOBs betrifft oder deren Inhalt nicht benötigt wird.

Mit Transaktionen lassen sich mehrere Datenbankoperationen zu Funktionsblöcken zusammenfassen die entweder ganz durchgeführt oder ganz rückgängig gemacht werden. Auf diese Weise wird sichergestellt, dass voneinander abhängende Operationen im Falle von Fehlern keine inkonsistenten Zustände in der Datenbank hinterlassen.

BaseLink stellt Transaktionen über die Methoden getConnection, startTransaction, commit, rollback sowie closeConnectionFinally des PersistenceManagers bereit. Deren Nutzung ist im folgenden Code-Beispiel dargestellt:

Nach dem Aufruf von startTransaction können beliebige Datenbankoperationen stattfinden, die einstweilen in der Datenbank noch nicht wirksam werden. Passiert bei einer Operation ein Fehler, werden mit dem Aufruf von rollback im catch-Zweig alle Operationen seit startTransaction rückgängig gemacht. Nur, wenn alle Operationen ohne Fehler durchgeführt werden, sorgt der Aufruf von commit zum Schluß dafür, dass alle Operationen in der Datenbank dauerhaft wirksam werden.

Die relevanten Methoden von BaseLink wie z.B. insert, update, select usw. sehen zur Arbeit mit Transaktionen nach obigem Muster jeweils Varianten vor, die ein Connection-Objekt als Parameter akzeptieren.

Wichtig: Bei der Arbeit mit Transaktionen muss wie im obigen Beispiel sichergestellt werden, dass eine Datenbankverbindung stets geschlossen wird weil andernfalls Speicherlecks entstehen können (siehe Ressourcenverwaltung).

Viele Datenbanksysteme bieten die Möglichkeit, eindeutige Schlüssel für Tabellen zu verwalten. Wenn in solchen Tabellen ein neuer Datensatz angelegt wird, sorgt das Datenbanksystem dafür, dass ihm ein eindeutiger Schlüssel zugewiesen wird. Das folgende SQL-Beispiel aus der Derby-Dokumentation zeigt diesen Fall

Mit BaseLink lässt sich ein so erzeugter eindeutiger Schlüssel mit der Methode executeWithKeys ermitteln. Ein Aufruf wie beispielsweise

liefert den erzeugten Schlüssel in keys zurück. Hier noch beschreiben, wie keys aufgebaut ist und gelesen wird.

Eine Alternative zur Nutzung datenbankspezifischer Mechanismen zur Schlüsselerzeugung zeigt der Abschnitt Eigene Schlüssel.

Mit PersistenceManager.executeScript liefert BaseLink eine Methode zur Ausführung von SQL-Skripten. Die Methode lautet wie folgt

Die Methode executeScript erwartet als Parameter einen String mit dem Skriptinhalt. Im Beispiel oben wird angenommen, dass eine separate Methode getSqlSkript das Skript liefert. Einzelne SQL-Kommandos müssen darin zeilenweise enthalten sein und jeweils mit Semikolon enden.

Der Rückgabewert ist ein Array mit ganzzahligen Werten, die für jede Zeile des Skripts entweder Statement.SUCCESS_NO_INFO oder die Anzahl der von ihr betroffenen Datensätze angeben. Sind alle Rückgabewerte ungleich Statement.EXECUTE_FAILED, war die Ausführung des gesamten Skriptes erfolgreich.

Im Abschnitt Datenbankstruktur erzeugen wird gezeigt, wie mit executeScript beispielsweise Skripte zur Anlage einer ganzen Datenbankstruktur ausgeführt werden können.

Alle Methoden von BaseLink fangen Fehler ab und vermerken die Fälle im Protokoll. Die Klasse de.uhilger.baselink.PersistenceManager legt dafür einen entsprechenden Logger an. Über die Logging-Konfiguration eigener Apps kann gesteuert werden, ob Fehler protokolliert werden und in welchem Umfang.

Es werden also beim Aufruf von BaseLink keine Exceptions geworfen. Ein Fehler lässt sich nur am Rückgabewert einzelner Methoden ablesen.

Zur Nutzung von BaseLink werden Datenbankstrukturen mit Annotationen an Java-Klassen gebunden (vgl. objektrelationale Abbildung). BaseLink unterstützt diese Aufgabe mit der Methode Util.generateDTO. Mit Übergabe eines Tabellennamens wie in folgendem Beispiel erzeugt die Methode den Quellcode einer kompletten Klasse mit Annotationen passend zur Struktur der Datenbanktabelle.

Die Ausgabe des Quellcodes auf der Konsole kann direkt als neue Klasse gespeichert und kompiliert oder zuvor nach Wunsch von Hand ergänzt und geändert werden. Die Methode generateDAO erspart dabei die Tipparbeit bei der Entwicklung erheblich.

Bei der Arbeit mit relationalen Datenbanken ist die Structure Query Language (SQL) ein zentrales Hilfsmittel. SQL wird wie eine Programmiersprache verwendet, beinhaltet aber veränderliche Teile der Datenbankstruktur wie z.B. Tabellen- oder Feldnamen. Bei Änderungen der Datenbankstruktur müssen SQL-Ausdrücke angepasst werden. Um Eingriffe in den Quellcode von Anwendungen zu vermeiden sollte SQL stets außerhalb des Quellcodes angelegt sein.

Die Java-Plattform liefert mit der Klasse java.util.Properties eine Möglichkeit, veränderliche Programmbestandteile wie z.B. Konfigurationseinstellungen außerhalb des Quellcodes zu halten und eignet sich damit für die Verwendung von SQL.

Werden SQL-Kommandos in eine XML-Struktur notiert wie im obigen Beispiel, können sie zur Laufzeit gelesen werden. Die Klasse Properties liefert eine bequeme Methode zum Lesen von Eigenschaften aus einer wie im Beispiel strukturierten XML-Datei.

Ein auf diese Weise gelesenes Properties-Objekt lässt sich wie folgt in Methoden von BaseLink einbauen.

In der Methode getUser des obigen Beispiels wird ein SQL-Kommando aus einem zuvor in der Methode initDb gelesenen Properties-Objekt entnommen und der Methode select von BaseLink übergeben. Ändert sich später einmal ein Teil der Datenbankstruktur, kann ohne Eingriff in den Quellcode das SQL in der Konfigurationsdatei angepasst werden.

Datenbanksysteme unterscheiden sich in der Art, ob und wie mit ihnen der Zustand der Struktur einer Datenbank geprüft werden kann. Bei Derby wird beispielsweise mit einem URL wie jdbc:derby://localhost:1527/udb;create=true eine Datenbank angelegt, falls sie noch nicht existiert. Sie besitzt dann aber noch keine Datenbankstruktur im Innern.

In Kombination mit einer SQL-Konfiguration aus dem vorigen Abschnitt kann mit BaseLink in nur wenigen Zeilen Code festgestellt werden, ob eine Datenbank bereits die gewünschte Datenstruktur beinhaltet. In besagter SQL-Konfiguration wird dafür zunächst die folgende SQL-Abfrage hinterlegt.

Damit kann für eine Tabelle der eigenen App geprüft werden, ob sie bereits angelegt wurde wie im folgenden Code gezeigt.

Nötigenfalls können die Angaben APP und USERS noch über eine Environment-Variable parametriert werden, um die Methode veränderlich zu halten.

Setzt eine App auf eine bestimmte Datenbankstruktur auf, ist es im Zuge der Installation dieser App mitunter nötig, neben den sonstigen Bestandteilen der App auch die entsprechende Datenbankstruktur initial anzulegen. Mit den Hilfsmitteln der SQL-Konfiguration und der Prüfung der Datenstruktur aus den vorangegangenen Abschnitten kann dies mit wenigen zusätzlichen Handgriffen erledigt werden.

Die Vorgehensweise dazu sieht die Hinterlegung eines Skripts zur Erzeugung der Datenbankstrukur vor. Viele Datenbanksysteme beinhalten Werkzeuge, mit denen die komplette Struktur einer Datenbank als SQL-Skript erzeugt werden kann. Bei Derby ist dies z.B. dblook. Oft entsteht aber auch das entsprechende Skript nach und nach aus den SQL-Kommandos, die ein Entwickler zur Erstellung einzelner Tabellen nach und nach herstellt.

Davon ausgehend, dass ein Skript zur Erstellung einer Datenbank in der Datei create_database.sql vorliegt, ist mit dem folgenden Beispielcode die Datenbankstruktur im Handumdrehen angelegt.

Im obigen Beispiel wird zunächt geprüft, ob die Datenbankstruktur bereits besteht, indem mit dem Aufruf von dbVorhanden nachgesehen wird, ob die Tabelle app.user vorhanden ist. Wenn die Tabelle fehlt, wird das Skript create_database.sql aus einer Datei gelesen und ausgeführt.

BaseLink implementiert für eigene Zwecke Methoden zum Schließen von Verbindungen, ResultSets und Statements. In Fällen einer individuellen Nutzung der Package javax.sql können diese Methoden verwendet und so Aufwand für die wiederholte eigene Implementierung gespart werden. Die Methoden sind

Eine weitere Methode zur direkten Verwendung von BaseLink-Elementen ist die Methode toList. Sie verwandelt ein beliebiges ResultSet in eine statische Liste wie es für das Lesen von Daten ohne objektrelationale Abbildung von BaseLink implementiert ist.

Wann immer also eine individuelle Nutzung der Package javax.sql mit der Rückgabe eines ResultSets endet, kann die Methode toList von BaseLink angewendet werden. Hierbei bietet sich auch die Kombination der Verwendung von toList und den Methoden zum Schließen an.

Im Abschnitt Schlüsselrückgabe ist beschrieben, wie Datenbankfunktionen zur Erzeugung eindeutiger Schlüssel mit BaseLink eingebunden werden können. Ein Nachteil solcher Funktionen ist deren in der Regel nicht standardkonforme SQL-Syntax. Wenn das Datenbanksystem gewechselt werden soll, muss eine App angepasst werden, wenn sie eine solche Funktion nutzt.

Eine Alternative ist es, einen datenbankunabhängigen Mechanismus zu verwenden wie er beispielsweise im Projekt radiozentrale zur Anwendung kommt. Die nachfolgenden Codebeispiele sind diesem Projekt entlehnt.

Sie könnten so auch Teil von BaseLink sein, Datenbanken müssten dann aber stets mit den angegebenen Tabellen ausgestattet sein. Aus diesem Grund soll es an dieser Stelle genügen, den Mechanismus als Kopiervorlage für andere Projekte vorzustellen.