Pflichtenheft zum Softwaretechnologie-Projekt JDBC-Treiber - Gruppe 11 Version: 2.1 Stand
←
→
Transkription von Seiteninhalten
Wenn Ihr Browser die Seite nicht korrekt rendert, bitte, lesen Sie den Inhalt der Seite unten
Pflichtenheft zum
Softwaretechnologie-Projekt
JDBC-Treiber
Gruppe 11
Version: 2.1
Stand: 2013-11-15Historie
Version Status Datum Autor(en) Erläuterung
0.1 in Arbeit 2013-10-23 * Erster Entwurf basierend auf der
Vorlage
0.2 in Arbeit 2013-10-27 Vincent Erster Entwurf entsprechend der ge-
gebenen Hilfestellung
0.3 in Arbeit 2013-10-28 Sebastian, Erweiterung um erste Inhalte
Simon
0.4 in Arbeit 2013-10-28 Vincent Weitere Inhalte
0.5 in Arbeit 2013-10-28 * Mehr Inhalte, ansehnlicher Zustand
0.6 in Arbeit 2013-10-29 Sebastian Einbau der ersten Kritik
1.0 in Arbeit 2013-10-31 * Konkretisierungen
1.1 in Arbeit 2013-11-02 Sebastian Einarbeitung des Meeting-
Feedbacks
1.2 in Arbeit 2013-11-05 Sebastian, Weitere Konkretisierungen (Einar-
Simon beitung von Feedback) und aktuali-
sierte Diagramme
1.3 in Arbeit 2013-11-05 Simon, JDBC-Connection-String
Vincent
1.4 in Arbeit 2013-11-06 Sebastian Kleine Formulierungsrevisionen
1.5 in Arbeit 2013-11-07 Vincent Konkretisierung JDBC-Connection-
String, kleinere sonstige Änderungen
1.6 in Arbeit 2013-11-07 Sebastian, Meeting-Feedback, Diagrammedits,
Simon Loggingedits
1.7 in Arbeit 2013-11-10 Vincent Seite für Unterschriften, Bsp. für
Connection-String etc.
1.8 in Arbeit 2013-11-10 Simon, Fehlerkorrektur und Erweiterung
Vincent der Beispiel-Connection-Strings
2.0 abgabebereit 2013-11-12 Vincent, Fehlerkorrektur und kleine
Sebastian, Änderungen
Simon
2.1 abgabebereit 2013-11-15 * Kosmetische Änderungen
iiInhaltsverzeichnis
1. Zielbestimmung 1
1.1. Musskriterien . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.2. Kannkriterien . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 1
1.3. Abgrenzungskriterien . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2
2. Produkteinsatz 2
3. Produktanwendungsfälle und -funktionen 3
4. Produktdaten 5
5. Technische Produktumgebung 6
6. Globale Testfälle 6
A. Glossar 8
B. Aufbau des JDBC-Connection-Strings 9
C. Sequenzdiagramme 11
D. Analyseklassendiagramm 14
iii1. Zielbestimmung
Ziel ist die Entwicklung eines Type-3-JDBC-Treibers, der mit Eclipse-Plugins, wie z.B.
dem Eclipse SQL Explorer“ verwendet werden kann.
”
Der Treiber muss in Java 1.7 entwickelt werden und über eine vorgegebene WSDL-
Schnittstelle mit einem Webservice kommunizieren, um Schemadaten auslesen und OQL-
Anweisungen ausführen zu können. Dieser Webservice-Endpunkt muss nutzerkonfigurier-
bar sein.
Der Quellcode soll dokumentiert werden (Javadoc + Anwenderdokumentation), um
die Einarbeitung eventueller späterer Entwickler möglichst einfach zu halten.
1.1. Musskriterien
Das Produkt muss
• in Java 1.7 geschrieben sein und die JDBC-Interfaces implementieren,
• kompatibel mit dem Eclipse SQL Explorer“ sein,
”
• eine Übersicht der verfügbaren Datenbanken eines CEE-Datenbank-Servers zurückliefern,
• eine Verbindung zu einer frei einstellbaren CEE-Datenbank aufbauen,
• sich gegenüber dem Webservice mit einem auswählbaren X.509-Zertifikat authen-
tifizieren,
• eine Übersicht über das Datenbank-Schema zurückliefern können (BusinessObjects
inkl. aller Felder, etc., OQL-Views inkl. aller Felder),
• OQL-Statements (via SOAP) über diesen Webservice an die Datenbank senden
können und dadurch
– Daten aus der Datenbank auslesen können,
– Daten in der Datenbank ebenso ändern können,
• die Verbindung sauber schließen können,
• bei Fehlern aller Art eine adäquate Fehlermeldung erzeugen und
• alle Aktionen und Ereignisse (mit dem java.util.logging-Paket) loggen.
1.2. Kannkriterien
Weitere gewünschte Kriterien sind, dass das Programm
• SELECT FROM x“ automatisch durch SELECT a, b, c FROM x“ ersetzt (wobei
” ”
a, b, c alle Felder des Business Objects x sind),
1• Kommentare (--, bzw. /* */) vor dem Senden aus dem Statement entfernt,
• mit anderen Eclipse-SQL-Plugins kompatibel ist,
• ebenfalls eine Authentifizierung via Benutzername und Passwort ermöglicht,
• Statements nicht nur mit folgendem (automatischen) Commit sondern auch mit
folgendem Rollback ausführen kann, praktisch also bloß die potenziellen Ergebnis-
se anzeigt, die Datenbank aber nicht ändert (ggf. werden dann auch Savepoints
implementiert und es wird nicht nur der auto-commit-Modus möglich sein) und
• Verbundstatements mit Hilfe der execute()-Methode des JDBC-Statement-Interfaces
ausführen kann.
1.3. Abgrenzungskriterien
• Über die in den JDBC-Interfaces vorgesehenen Funktionen hinaus werden keine
weiteren Features implementiert.
2. Produkteinsatz
Der JDBC-Treiber soll zusammen mit Plugins wie dem SQL-Explorer“ in Eclipse ver-
”
wendet werden, dabei gibt der User eine OQL-Anfrage in den SQL-Explorer ein und
erhält in diesem auch seine Antwort von der Datenbank.
Ein Type-3-JDBC-Treiber, wie der, der entwickelt wird, kommuniziert mit der eigent-
lichen Datenbank immer über eine Zwischensoftware (hier ein Webserver).
Ein entsprechendes Kontextdiagramm ist in Abb. 1 zu sehen.
Abbildung 1: Kontextdiagramm
23. Produktanwendungsfälle und -funktionen
Im Use-Case-Diagramm (Abb. 2) sind folgende Anwendungsfälle zu sehen:
1. OQL-Query. Der Nutzer (Entwickler) kann eine OQL-Abfrage (SELECT) ausführen
und darüber eine Ergebnisliste erhalten.
2. OQL-Update. Der Nutzer (Entwickler) kann ein OQL-Update (also eine verändernde
Abfrage wie UPDATE, INSERT, DELETE) ausführen und darüber eine Meldung über
die Änderung erhalten.
3. fehlerhaftes OQL-Statement. Der Nutzer (Entwickler) kann eine fehlerhafte
Abfrage senden und die entsprechende Fehlermeldung erhalten.
In jedem Fall wird für diese Anwendungsfälle vorausgesetzt, dass der Nutzer (Ent-
wickler) eine Verbindung zum Server aufbauen kann.
Abbildung 2: Use-Case-Diagramm
Hinweise:
• Bis auf /F10/ und /FW80/ setzen alle folgenden Funktionen voraus, dass das
Programm erfolgreich mit einer Datenbank verbunden ist und die Verbindung noch
nicht geschlossen wurde (andernfalls werden Exceptions erzeugt, s. /F40/).
3• Der Aufbau des JDBC-Connection-Strings wird in Anhang B aufgezeigt.
/F10/ Verbindungsaufbau Der Treiber versucht, eine Verbindung mit einer
CEE-Datenbank aufzubauen, indem er sich gegenüber dem dafür zu nut-
zenden Webservice mit einem einstellbaren (s. Anhang B) X.509-Zertifikat
authentifiziert.
• /F10.1/: Verbindung mit einem im JDBC-Connection-String fest-
gelegten CEE-Server aufbauen (ohne direkt eine Datenbank aus-
zuwählen).
• /F10.2/: Auswahl einer Datenbank (Nennung beim Namen) auf dem
Server, mit dem der Treiber verbunden ist.
• /F10.3/: Verbindung mit einem im JDBC-Connection-String festge-
legten CEE-Server aufbauen und direkte Auswahl der Datenbank, de-
ren Name ebenfalls im JDBC-Connection-String enthalten ist.
• /F10.4/: Time out. Wurde die Verbindung nicht innerhalb einer im
JDBC-Connection-String konfigurierbaren Zeit aufgebaut, wird der
Verbindungsaufbau unterbrochen.
/F20/ Datenbankliste Eine Liste aller Datenbanken des CEE-Servers kann ab-
gerufen werden.
/F30/ Ausführen von einzelnen Statements Übermittlung einer OQL-
Anfrage an den Webservice. Die OQL-Anfrage des Entwicklers wird an die
Datenbank übermittelt, danach wartet der Treiber auf eine Antwort des
Servers:
• /F30.1/: Daten abfragen. Der Treiber gibt die erhaltenen Objekte
zurück oder erzeugt aus der Fehlermeldung, die er vom Webserver
erhalten hat eine Exception, die dann entsprechend behandelt wird
(s. /F40/).
• /F30.2/: Daten ändern. Der Treiber gibt die Anzahl der geänderten
Zeilen (insbesondere 0, wenn keine Zeile geändert wurde) zurück und
behandelt Fehler analog zu /F30.1/.
• /F30.3/: Time out. Antwortet der Server bei einer einzelnen Abfrage
innerhalb einer gewissen Zeit (s. Anhang B) nicht, gibt der Treiber
eine Fehlermeldung zurück.
4/F40/ Fehlerbehandlung Fehler werden als Exceptions behandelt, sofern
möglich bzw. sinnvoll abgefangen und verarbeitet (bspw. Retry), oder sonst
an den Benutzer weitergegeben. Die Exceptions sind hier die in den JDBC-
Interfaces spezifizierten Exceptions (java.sql.SQLException und Kind-
klassen).
/F50/ Log Erfolgsmeldungen und Fehler werden gleichermaßen (mit den Logging-
Möglichkeiten des java.util.logging-Pakets) geloggt und dem Entwickler
zurückgegeben, dabei ist zu beachten, dass die Ereignisse ihrer Wichtigkeit
und Wirkung nach den verschiedenen Log-Leveln eindeutig zugeordnet wer-
den (ähnlich der in den Programming Guidelines festgelegten Herangehens-
weise)
/F60/ Verbindungstrennung Die Verbindung kann vom Benutzer geschlossen
werden.
/FW70/ Statementoptimierung OQL-Statements werden vor dem Senden an den
Webservice optimiert, dies kann im JDBC-Connection-String deaktiviert
werden (s. Anhang B).
• /FW70.1/: Statements der Form SELECT FROM x“ werden automa-
”
tisch durch SELECT a, b, c FROM x“ ersetzt, wobei a, b, c alle
”
Felder des Business Objects x sind.
• /FW70.2/: Kommentare (--, bzw. /* */) werden vor dem Senden
aus dem Statement entfernt.
/FW80/ Alternative Authentifizierung Eine Authentifizierung via Benutzerna-
me und Passwort (wird im Plugin eingestellt und über die properties an
den Treiber weitergegeben) ist ebenso möglich wie die Authentifizierung via
Zertifikat (s. /F10/).
/FW90/ Rollback-Modus Neben dem auto-commit-Modus soll es auch möglich
sein, die Wirkung eines Statements auf die Datenbank zu erfahren, ohne
diese tatsächlich zu ändern (d.h. das Statement wird ausgeführt und das
Resultat angezeigt, die Änderung wird jedoch nicht in die Datenbank ge-
schrieben). Gegebenenfalls wird dies über Savepoints ermöglicht.
/FW100/ Verbundstatements Es sind Verbundstatements (also Kombinationen aus
/F30.1/ und /F30.2/, s. Glossar) mit der execute()-Methode möglich, der
Treiber stellt bei einer solchen Abfrage alle Rückgabewerte (wie in /F30.1/
und /F30.2/ beschrieben) bereit.
4. Produktdaten
Der Treiber selbst behält keine persistenten Daten: Die Daten, die er handhabt, stammen
aus der hinter dem Webinterface liegenden Datenbank und werden immer direkt an den
Nutzer weitergegeben.
55. Technische Produktumgebung
Software
• Java: Version 1.7 muss verwendet werden.
• Eclipse: Der JDBC-Treiber wird im Kontext mit Eclipse verwendet, um das Erstel-
len von OQL-Anfragen an CEE zu erleichtern. Die konkrete Einbindung in Eclipse
findet dann bspw. über das Plugin SQL-Explorer“ statt, das die erforderliche GUI
”
liefert.
• Für die direkte Low-Level-SOAP-Kommunikation mit dem Server kann auf Basis
der WSDL des Webservers bereits eine geeignete Library generiert werden, die
Funktionen für das Senden von OQL-Statements und das Empfangen von Resul-
taten via SOAP bereitstellt.
Hardware Ein Java-fähiger Rechner mit funktionierender Netzwerkverbindung (um die
Verbindung zu einem CEE-Datenbank-Webserver aufbauen zu können) ist nötig.
6. Globale Testfälle
Hinweis: Die Testfälle /T30/ bis /T80/ setzen voraus, dass die Aktionen aus /T10/ und
/T20/ bereits ausgeführt wurden.
/T10/ Der Treiber wird von dem Plugin ordnungsgemäß akzeptiert und kann sich
beim DriverManager registrieren.
/T20/ Der Treiber bekommt die URL https://localhost:4434 übergeben und
baut erfolgreich eine Verbindung mit dem laufenden Webservice-Dummy
auf.
/T30/ Die Software liefert eine Übersicht der verfügbaren Datenbanken an das
Eclipse-Plugin.
/T40/ Es können OQL-Statements, sofern durch den Webservice unterstützt, an
diesen gesendet werden. Die folgenden Querys werden an die Datenbank
DUMMYDV01“ des Webservice-Dummys gesendet:
”
• /T40.1a/:
SELECT i:number FROM com.cisag.app.general.obj.Item i
WHERE i:number = ’10010’ORDER BY i:number DESC
Der Treiber gibt das korrekte ResultSet zurück.
6• /T40.1b/
SELECT i:number FROM com.cisag.app.general.obj.Item i
WHERE i:number = ’3141592653’ORDER BY i:number DESC
Die WHERE-clause soll äquivalent zu WHERE 0=1 sein, wähle also
eine sicher nicht auftretende number. Der Treiber gibt das korrekte
(leere) ResultSet zurück.
• /T40.2/:
SELECT i:number AS Item, i:description
FROM com.cisag.app.general.obj.Item i
WHERE i:_timeZoneGuid = toGuid(’0DE013F0446F1D10A1908464960F0000’)
ORDER BY i:number
Der Treiber gibt das korrekte ResultSet zurück.
• /T40.3/:
SELECT FROM com.cisag.app.general.obj.Item i
ORDER BY i:number
Der Treiber gibt das korrekte ResultSet zurück.
/T50/ Nicht erfolgreiche OQL-Statements resultieren in einem Fehler. Die folgende
Query wird an die Datenbank DUMMYDV02“ des Dummy-Webservers gesen-
”
det:
SELECT FROM com.cisag.app.general.obj.Item i
ORDER BY i:number
Der Treiber wirft eine Exception.
/T60/ Ergebnisse einer Datenbankabfrage (Abfrage nach der Liste der verfügbaren
Datenbanken) an den Webservice werden korrekt an das Plugin übergeben.
/T70/ Es können verschiedene Einstellungen des Treibers über den JDBC-
Connection-String vorgenommen werden (z.B. Servername, Datenbankna-
me, Timeout-Dauer; s. Anhang B).
/T80/ Alle Ereignisse (Fehler wie Erfolgsmeldungen) werden (mit den Logging-
Möglichkeiten des java.util.logging-Pakets) geloggt.
7A. Glossar
CEE (Comarch ERP Enterprise) Auf der Serverseite befindet sich CEE, ein ERP-Server-
system, welches die OQL-Datenbank verwaltet, der Server kann über eine SOAP-
Schnittstelle angesteuert werden. Der Webserver lässt alle OQL-Befehle auswer-
ten und gibt die Resultate oder bei Fehlern die entsprechenden Fehlermeldungen
zurück.
JDBC (Java Database Connectivity) eine von Oracle in Java verankerte API, die In-
terfaces für den Zugriff auf Datenbanken enthält, die von JDBC-Treibern zu im-
plementieren sind.
OQL (Object Query Language) eine objektorientierte Abfragesprache, die an SQL an-
gelehnt ist.
OQLRemoteToolkit Zusammenfassende Bezeichnung für die aus der WSDL generierten
Klassen, welche vom JDBC-Treiber genutzt werden, um die Low-Level-Kommunikation
mit dem Webserver zu kapseln.
SOAP (Simple Object Access Protocol) ein Netzwerkprotokoll, welches zum Daten-
austausch zwischen zwei Systemen benutzt wird. Das Protokoll ist ein Standard
des W3C.
Verbundstatement Eine OQL-Query, die aus mehr als einem Befehl (SELECT, UPDATE,
INSERT, DELETE) besteht, die Befehle werden dabei mit einem ;“ verkettet und
”
fortan als eine Anfrage betrachtet.
8B. Aufbau des JDBC-Connection-Strings
Der JDBC-Connection-String ist von der folgenden Form:
jdbc:cee : key1=value1;...;keyn=valuen
Festgelegter Identifier Liste von Key=Value Paaren
Hinweise:
• Die gültigen Keys sind der nachfolgenden Liste zu entnehmen.
• Die Key-Value Paare sind mittels Semikolon (;) zu trennen. Zwischen Key und
zugehörigem Value ist ein Gleichheitszeichen (=) zu setzen.
• Kein Value darf ein Semikolon enthalten.
• Der Connection-String darf keine Leerzeichen, die nicht Teil eines Values sind,
enthalten.
• Sollte ein obligatorischer Key nicht im String enthalten sein, wird keine Verbindung
aufgebaut und eine Exception geworfen.
• Sollte ein Key im Connection-String mehrmals vorkommen, so wird der letzte
zugehörige Wert benutzt.
• Sollte ein Key verwendet werden, welcher nicht in der unten stehenden Liste auf-
geführt wird, wird der Key samt Value ignoriert.
• Sollte ein Value nicht zum zugehörigen Key passen (d.h. keine ganzen Zahlen bei
port und timeout-Werten, kein valider Fingerprint etc.), wird keine Connection
hergestellt und eine Exception geworfen.
• Sollte der JDBC-Connection-String nicht den beschriebenen Aufbau haben, wird
keine Verbindung hergestellt und eine Exception geworfen.
Keyname Standardwert Beschreibung siehe
host — Adresse des Servers (obligatorisch) /F10/
port 80 Port für die Kommunikation mit dem
Server
database — Name der Datenbank /F10/
certificate — Fingerprint des Zertifikats, kann als /F10/
4b:3a:...“, 4B:3A:...“, 4b 3a
” ” ”
...“, 4B 3A ...“, 4b3a...“ oder
” ”
4B3A...“ angegeben werden
”
9trustStore Zu verwendende KeyStore-Datei /FW80/
(=
ˆ Windows-
Zertifikatstore)
loginTimeout 15 Zeit (in Sekunden) bis der Verbingsauf- /F10.4/
bau abgebrochen wird
oqlTimeout ˆ ∞)
0 (= Zeit (in Sekunden) bis das Senden eines /F30.3/
OQL-Statements abgebrochen wird
addSelectFields true Optimierung verwenden? Ersetzen von /FW70.1/
SELECT a, b, c FROM x“
”
stripComments true Optimierung verwenden? Kommentare /FW70.2/
aus dem OQL-Statement löschen
Beispiele:
• jdbc:cee:host=https://localhost;port=4434;database=comarch1;
”
certificate=43:51:53:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:66:73:a8;
trustStore=C:\store1.keystore;loginTimeout=100;oqlTimeout=200;
addSelectFields=false;stripComments=false“ ist ein Beispiel für einen (ma-
ximalen) sinnvollen und gültigen Connection-String.
Ebenso ist dies jdbc:cee:database=comarch1;trustStore=;
”
certificate=43:51:53:a1:b5:fc:8b:b7:0a:3a:a9:b1:0f:
66:73:a8;oqlTimeout=0;port=80;loginTimeout=15;addSelectFields=true;
host=https://localhost;stripComments=true“ ein gültiger Connection-String,
allerdings ändert dieser weniger, da die Standardwerte genommen wurden.
• jdbc:cee:host=https://localhost“ ist ein Minimalbeispiel für einen sinnvol-
”
len und gültigen Connection-String.
• Bei Übergabe von jdbc:cee:“ oder jdbc:cee:port=80;oqlTimeout=60“ wird
” ”
keine Verbindung aufgebaut, sondern eine Exception geworfen, da der obligatori-
sche key host nicht gesetzt wird.
• jdbc:cee:port=80;host=https://localhost;port=42“ ist gültig, port wird
”
auf 42 gesetzt. Im Gegensatz dazu ist jdbc:cee:port=41;port=43“ ungültig,
”
jedoch aus einem anderen Grund.
• jdbc:cee:port=80;unknownKey=42;host=https://localhost“ und jdbc:
” ”
cee:port=80;unknownKey=;host=https://localhost“ sind gültig, unknownKey
und der entsprechende Wert 42“ bzw. “ werden einfach ignoriert.
” ”
• jdbc:cee:host=https://localhost;port=true“ ist ein fehlerhafter Connection-
”
String mit einem falschen Value für den Key port.
• jdbc:abc:host=https://localhost“, jdbc:cee:host=;;80=port“, jdbc:
” ” ”
cee:host=https://localhost;port=oqlTimeout=80“ und host=https://
”
localhost;port=80;oqlTimeout=80“ sowie jdbc:cee:host=https://localhost;“
”
entsprechen nicht dem geforderten Aufbau.
10C. Sequenzdiagramme
Abbildung 3: Sequenzdiagramm: Verbindung aufbauen
Abbildung 4: Sequenzdiagramm: Anfrage, Query
11Abbildung 5: Sequenzdiagramm: Anfrage, Update
Abbildung 6: Sequenzdiagramm: fehlerhafte Anfrage
12Abbildung 7: Sequenzdiagramm: Verbindung beenden
13D. Analyseklassendiagramm
Abbildung 8: Analyseklassendiagramm
14Externer Betreuer von
Tutor
der Comarch AG
Klaus Bergmann Balint Gyapjas
Entwicklerteam
Michael Günther Simon Hanisch Vincent Knyrim
Sebastian Manecke Sebastian Mielke
15Sie können auch lesen
