Tutorial:
JavaScout ProjectAssist, Task-Frame Grundlagen (Java_Fatclient_01) –
DataBase-Access Klasse für eine Liste von Datensätzen aus der DB-Tabelle 'ProjLang' (DBA-Set)

In diesem Dokument wird die Klasse mit den Methoden für das Lesen von der Datenbank mit Auswahlkriterien, die mehrere Datensätze selektieren könnten, implementiert.
Diese Klasse wird allgemein als DataBase-Access (DBA) bezeichnet und ist die unterste Ebene in der Hierarchie der Datenverwaltung.

Einen Überblick über die verschiedenen Klassen zur Verwaltung von persistenten Daten finden Sie im Dokument Business-Object – Überblick über die Funktion zum Abfragen und Speichern von Daten.
Eine detailliertere Beschreibung der Aufgabe einer DBA-Klasse finden Sie im Dokument DBA (DataBase-Access) Klasse.

Die Codierung von DBA-Set-Klassen ist in weiten Teilen gleich mit der Codierung für das Selektieren von Daten wie im Dokument Tutorial: JavaScout ProjectAssist, Task-Frame Grundlagen (Java_Fatclient_01) – DataBase-Access (DBA) Klasse für DB-Tabelle 'ProjLang' beschrieben.
Für die Übertragung der Werte, die von der Datenbank-Tabelle gelesen wurden, auf die Variablen dieser Klasse werden die Methoden, die für das Selektieren eines einzelnen Datensatzes entwickelt wurden, verwendet.

Inhaltsverzeichnis:

Voriger Schritt: Daten erfassen und Speichern 

Vorbemerkung 
Vorbedingungen 
DBA-Set-Klasse eröffnen 
Code für die DBA-Set-Klasse 
* Von Basisklasse erben 
* Importieren der Bibliotheken 
* Methode zum Selektieren der Daten 
* SQL-Kommando 
* Übertragen der Daten auf den Vector (definiert in der Basisklasse) 
Gesamter Code am Ende des Schrittes 
* Klasse JS_ProjAssist_ProjLang_DBA_Set 
Weitere Schritte und verwandte Dokumentation 

Nächster Schritt: General BO-Set Klasse für eine Liste von 'ProjectLanguage' Business Objects 

Vorbemerkung

Für die 'Massenproduktion' von DBA-Set-Klassen wurde ein Muster-Code entwickelt, aus dem durch Ersetzen von 'Platzhaltern' einfach und vor allem schnell bedarfsgerechte DBA-Klassen implementiert werden können.
Der Muster-Code und die Anleitungen zur Adaption sind im Dokument Muster-Code für ein DBA-Set (Liste mit DataBase-Access Objekten) beschrieben.
Der in diesem Tutorial vorgestellte Code folgt der Struktur des Muster-Codes – dadurch wird das Verstehen und Adaptieren leichter.

▲ zum Inhaltsverzeichnis

Vorbedingungen:

• Voriger Schritt Daten erfassen und Speichern dieses Tutorials abgeschlossen.

• Überblick über die theoretischen Grundlagen aus den Dokumenten Business-Object – Überblick über die Funktion zum Abfragen und Speichern von Daten und DBA (DataBase-Access) Klasse.

▲ zum Inhaltsverzeichnis

DBA-Set-Klasse eröffnen

Diese Klasse wird im gleichen Java-Package erstellt wie die DBA-Klasse.

Das Erstellen einer neuen Klasse wurde bereits mehrmals im Detail und mit Abbildungen beschrieben.
Aus diesem Grund wird er Vorgang nur mehr in Stichworten beschrieben.
Wenn sie unsicher sind, nehmen Sie bitte die ausführliche Anleitung unter JavaScout ProjectAssist, Task-Frame Grundlagen (Java_Fatclient_01) – DataBase-Access (DBA) Klasse für DB-Tabelle 'ProjLang' > DBA-Klasse eröffnen als Richtlinie.

• Um eine neue Java-Klasse zu eröffnen wird mit der rechten Maustaste das Project (Java_Fatclient_01) angeklickt und aus dem Kontext-Menu >New>Class ausgewählt.

• Im darauf hin erscheinenden Fenster (New Java Class) wird

• Das 'Package' (js_projassist.dba) festgelegt.

• Der Name der Klasse (JS_ProjAssist_ProjLang_DBA_Set) festgelegt.
  ProjLang ist der Name der DB-Tabelle der diese DBA-Klasse zugeordnet ist.

• Folgende Auswahl-Möglichkeiten werden de-markiert:
  [  ] public static void main(String[] args)
  [  ] Constructors from superclass
  [  ] Inherited abstract methods

• Die anderen bereits vorgegebenen Werte werden nicht verändert.

• Durch Anklicken der Schaltfläche [ Finish ] wird die Datei für den Quell-Code der Klasse angelegt.

▲ zum Inhaltsverzeichnis

Code für die DBA-Set-Klasse

Der Code für die DBA-Set-Klasse beschränkt sich auf das Selektieren von Daten und benutzt dazu weitestgehend die Funktionalität der Klasse JS_ProjAssist_ProjLang_DBA so wie im Dokument JavaScout ProjectAssist, Task-Frame Grundlagen (Java_Fatclient_01) – DataBase-Access (DBA) Klasse für DB-Tabelle 'ProjLang' > Code für die DBA-Klasse beschrieben.

Der gesamte Code ist unter Klasse JS_ProjAssist_ProjLang_DBA_Set gelistet und mit Kommentaren versehen.
Aus diesem Grund wird anschließend der Code nicht mehr im Gesamten wiederholt sondern nur mehr Erläuterungen zu bisher nicht erklärten Algorithmen gegeben.

▲ zum Inhaltsverzeichnis

Von Basisklasse erben

package js_projassist.dba;
. . . . . . . .
. . . . . . . .
/*
 * Package mit den Basisklassen für DBA und DBA-Set. */
import js_base.dba.*;
. . . . . . . .
. . . . . . . .
public class JS_ProjAssist_ProjLang_DBA_Set extends JSBS_DBA_Set {
/* ---------------------
 * METHODE zum Lesen aller Datensätze die zum Arbeitsdatum
/*

In der Basisklasse JSBS_DBA_Set ist jene Variable des Typs 'Vector' definiert, in dem die selektierten Datensätze (für diese Klasse vom Typ 'JS_ProjAssist_ProjLang_DBA') nach dem Abschluß einer Methode enthalten sind.
Mit den obigen Anweisungen wird die Bibliothek, in der diese Klasse enthalten ist, importiert und von dieser Klasse 'geerbt'.

▲ zum Inhaltsverzeichnis

Importieren der Bibliotheken

package js_projassist.dba;
. . . . . . . .
. . . . . . . .
/*
 * Package mit dem DBA-Objekt, das in der Liste dieses DBA-Set enthalten ist. */
import js_projassist.dba.JS_ProjAssist_ProjLang_DBA;
/* */
public class JS_ProjAssist_ProjLang_DBA_Set extends JSBS_DBA_Set {
/* ---------------------
 * METHODE zum Lesen aller Datensätze die zum Arbeitsdatum

Neben anderen Bibliotheken (die schon bei der zugehörigen DBA-Klasse erläutert wurden) ist für diese Klasse mit dem DBA-Set auch der Import der zugehörigen DBA-Klasse erforderlich.

▲ zum Inhaltsverzeichnis

Methode zum Selektieren der Daten

In diesem Beispiel ist nur eine Methode implementiert, die alle zum aktuellen Datum (in der als Parameter übergebenen Struktur JSBS_MinimalParameter enthalten) gültigen Datensätze selektiert.

▲ zum Inhaltsverzeichnis

SQL-Kommando

. . . . . . . .
. . . . . . . .
 * JS_ProjAssist_ProjLang_DBA verwendet.
 * Anmerkung zum Mandanten-ID (ClientID):
 * ----------
 * Da das Tutorial keine Möglichkeit bietet einen Mandanten zu wählen wird der Default-ClientID (Wert 0)
 * verwendet; dadurch liefert das SQL-Kommando nur einen Datensatz zurück auch wenn kein 'ClientID' im
 * 'where' enthalten ist. */
      final String locstrSQLCommand =
                     JS_ProjAssist_ProjLang_DBA.CONST_SELECT_ALL_ATTRIBUTES +
/* Selectionskriterien in die Zeichenkette einfügen. */
                     " where " + JS_ProjAssist_ProjLang_DBA.CONST_ValidTill + " >=?" +
/* Sortierkriterium, damit die Datensätze aufsteigend nach ProjectCode und
 * LanguageCode in die Liste eingefügt werden. */
                     " order by " + JS_ProjAssist_ProjLang_DBA.CONST_ProjectCode + ", " +
                     JS_ProjAssist_ProjLang_DBA.CONST_LanguageCode + ", " +
                     JS_ProjAssist_ProjLang_DBA.CONST_ValidFrom + ", " +
                     JS_ProjAssist_ProjLang_DBA.CONST_ValidTill + " desc";
/* Das im Parameter 'JSBS_MinimalParameters' enthaltene Arbeitsdatum muß in das
. . . . . . . .
. . . . . . . .

Für den Aufbau der Zeichenkette mit dem SQL-Kommando werden die in der DBA-Klasse definierten Konstanten verwendet.
Beim Selektieren mehrerer Datensätze kann im SQL-Kommando auch gleich die Anweisung zum Sortieren gegeben werden.
Besonders wenn die als Sortier-Kriterium gewählten Attribute in einem Sekundär-Index der Datenbank-Tabelle enthalten sind, ist das Sortieren während der Datenbank-Abfrage wesentlich performanter als die Datensätze anschließend im Anwendungsprogramm zu sortieren.

▲ zum Inhaltsverzeichnis

Übertragen der Daten auf den Vector (definiert in der Basisklasse)

. . . . . . . .
. . . . . . . .
/* 
 * Datenbank-Abfrage ohne Fehler; Vector mit der Liste der DBA-Objekte leeren und
 * Fehler-Meldung mit leerem 'String' füllen – als Zeichen der ordnungsgemäßen Ausführung. */
        ErrorMsg = "";
        vecRecordSet.removeAllElements();
/* 
 * In einer Schleife jeden Datensatz aus dem SQLResultSet auslesen und auf ein
 * JS_ProjAssist_ProjLang_DBA Objekt übertragen. */
        for (;;) {
/* 
 * Prüfen ob ein weiterer Datensatz vorhanden ist. */
          if (!SQLResultSet.next()) return;
/* 
 * Prüfen ob die Gültigkeit des bearbeiteten Datensatzes mit dem Arbeitsdatum übereinstimmt.
 * Damit werden Datensätze ausgeschlossen, deren Gültigkeit eventuell erst in der Zukunft beginnt. */
          locdteReadValidFrom = SQLResultSet.getDate(JSBS_DBA.CONST_ValidFrom);
          locdteReadValidTill = SQLResultSet.getDate(JSBS_DBA.CONST_ValidTill);
/* Methode aus der Basisklasse verwenden um die Gültigkeit zu prüfen. */
          if (isWithinDateRange(locdteWorkDate, locdteReadValidFrom, locdteReadValidTill)) {
/* 
 * Ein DBA-Objekt 'konstruieren' und die Werte aus dem SQLResultSet übertragen. */
            JS_ProjAssist_ProjLang_DBA locstructJS_ProjAssist_ProjLang_DBA =
              new JS_ProjAssist_ProjLang_DBA();
            locstructJS_ProjAssist_ProjLang_DBA.getValuesFromSQLResultSet(SQLResultSet);
/* 
 * Das DBA-Objekt in den Vector mit der Liste der DBA-Objekte einfügen.
 * Der Vector ist in der geerbten Basisklasse definiert. */
            vecRecordSet.addElement(locstructJS_ProjAssist_ProjLang_DBA);
          }
        }
. . . . . . . .
. . . . . . . .

Das vom Datenbank-System zurückgelieferte ResultSet wird mit einer for-Schleife verarbeitet.
Die Schleife wird beendet wenn kein weiterer Datensatz mehr im ResultSet enthalten ist.

Jeder gelesene Datensatz wird untersucht, ob die Gültigkeit nicht eventuell erst in Zukunft beginnt.
Dazu wird die in der Basisklasse enthaltene Methode isWithinDateRange(...) verwendet.
/* 
 * Prüfen ob die Gültigkeit des bearbeiteten Datensatzes mit dem Arbeitsdatum übereinstimmt.
 * Damit werden Datensätze ausgeschlossen, deren Gültigkeit eventuell erst in der Zukunft beginnt. */
          locdteReadValidFrom = SQLResultSet.getDate(JSBS_DBA.CONST_ValidFrom);
          locdteReadValidTill = SQLResultSet.getDate(JSBS_DBA.CONST_ValidTill);
/* Methode aus der Basisklasse verwenden um die Gültigkeit zu prüfen. */
          if (isWithinDateRange(locdteWorkDate, locdteReadValidFrom, locdteReadValidTill)) {

Es wäre auch möglich, dieses 'Ausschließen' auch im SQL-Kommando zu definieren. Damit wäre das SQL-Kommando aber wesentlich schwerer verständlich.
Ziel dieses Tutorials soll es sein, Wissen aufzubauen – darum wurde diese einfacher verständliche Anleitung gewählt.

Für das Übertragen der von der Datenbank gelesenen Werte wird die in der zugehörigen DBA-Klasse definierte Methode zum 'Holen' der Werte von der DB-Tabelle verwendet.
/* 
 * Ein DBA-Objekt 'konstruieren' und die Werte aus dem SQLResultSet übertragen. */
            JS_ProjAssist_ProjLang_DBA locstructJS_ProjAssist_ProjLang_DBA =
              new JS_ProjAssist_ProjLang_DBA();
            locstructJS_ProjAssist_ProjLang_DBA.getValuesFromSQLResultSet(SQLResultSet);
/* 
 * Das DBA-Objekt in den Vector mit der Liste der DBA-Objekte einfügen.
 * Der Vector ist in der geerbten Basisklasse definiert. */
            vecRecordSet.addElement(locstructJS_ProjAssist_ProjLang_DBA);

▲ zum Inhaltsverzeichnis

Gesamter Code am Ende des Schrittes

Klasse JS_ProjAssist_ProjLang_DBA_Set

package js_projassist.dba;
/*
 * Package für die Verbindung zur Datenbank. */
import java.sql.*;
/*
 * Package mit den Basisklassen für DBA und DBA-Set. */
import js_base.dba.*;
/*
 * Package mit dem Minimalen Set an Parametern. Diese enthalten das Arbeitsdatum.
 * Das Arbeitsdatum wird für verschiedene Abfragen gebrauucht. */
import js_base.structures.JSBS_MinimalParameters;
/*
 * Package mit dem DBA-Objekt, das in der Liste dieses DBA-Set enthalten ist. */
import js_projassist.dba.JS_ProjAssist_ProjLang_DBA;
/* */
public class JS_ProjAssist_ProjLang_DBA_Set extends JSBS_DBA_Set {
/* ---------------------
 * METHODE zum Lesen aller Datensätze die zum Arbeitsdatum
 * (im Parameter JSBS_MinimalParameters enthalten) gültig sind.
 * Damit werden alle Kombinationen aus ProjectCode und LanguageCode selektiert.
 * 'Connection' ist eine Klasse aus dem package 'java.sql' und enthält die
 * Verbindung zum Datenbanksystem. */
    public void selectAllProjectLanguageCombinations(
                   Connection parmDBCon, JSBS_MinimalParameters parmMinParm) {
/* Aufbauen des SQL-Kommandos in einer eigenen Zeichenkette (String).
 * Gegenüber einem direkten Schreiben des des SQL-Kommandos als Parameter
 * beim 'Construct' des 'SQLStatement' hilft der eigene String beim Debuggen.
 * Dabei werden die als Konstante definierten Werte der Klasse
 * JS_ProjAssist_ProjLang_DBA verwendet.
 * Anmerkung zum Mandanten-ID (ClientID):
 * ----------
 * Da das Tutorial keine Möglichkeit bietet einen Mandanten zu wählen wird der Default-ClientID (Wert 0)
 * verwendet; dadurch liefert das SQL-Kommando nur einen Datensatz zurück auch wenn kein 'ClientID' im
 * 'where' enthalten ist. */
      final String locstrSQLCommand =
                     JS_ProjAssist_ProjLang_DBA.CONST_SELECT_ALL_ATTRIBUTES +
/* Selectionskriterien in die Zeichenkette einfügen. */
                     " where " + JS_ProjAssist_ProjLang_DBA.CONST_ValidTill + " >=?" +
/* Sortierkriterium, damit die Datensätze aufsteigend nach ProjectCode und
 * LanguageCode in die Liste eingefügt werden. */
                     " order by " + JS_ProjAssist_ProjLang_DBA.CONST_ProjectCode + ", " +
                     JS_ProjAssist_ProjLang_DBA.CONST_LanguageCode + ", " +
                     JS_ProjAssist_ProjLang_DBA.CONST_ValidFrom + ", " +
                     JS_ProjAssist_ProjLang_DBA.CONST_ValidTill + " desc";
/* Das im Parameter 'JSBS_MinimalParameters' enthaltene Arbeitsdatum muß in das
 * Datumsformat der 'java.sql' Klassen konvertiert werden. */
      Date locdteWorkDate = new Date(parmMinParm.calWorkDate.getTime().getTime());
/* 'PreparedStatement' ist eine Klasse aus dem 'java.sql'-package die das
 * SQL-Kommando an das Datenbanksystem überträgt. */
      PreparedStatement SQLStatement;
/* Es folgt die Ausführung des SQL-Kommandos; die dafür zuständigen Klassen
 * und Methoden arbeiten mit 'try/catch' zur Fehlerbehandlung. */
      try {
/* Gerade vorher definiertes 'PreparedStatement' konstruieren
 * und dabei als Parameter das SQL-Kommando übergeben. */
        SQLStatement = parmDBCon.prepareStatement(locstrSQLCommand);
/* Datum für die Selektion in die Zeichenkette mit dem SQL-Kommando einfügen. */
        SQLStatement.setDate(1, locdteWorkDate);
/* SQL-Kommando an die Datenbank 'absenden'; die Werte des gefundenen Datensatzes
 * sind dann im Objekt der Klasse 'ResultSet'. */
        ResultSet SQLResultSet = SQLStatement.executeQuery();
/* 
 * Datenbank-Abfrage ohne Fehler; Vector mit der Liste der DBA-Objekte leeren und
 * Fehler-Meldung mit leerem 'String' füllen – als Zeichen der ordnungsgemäßen Ausführung. */
        ErrorMsg = "";
        vecRecordSet.removeAllElements();
/* 
 * In einer Schleife jeden Datensatz aus dem SQLResultSet auslesen und auf ein
 * JS_ProjAssist_ProjLang_DBA Objekt übertragen. */
        for (;;) {
/* 
 * Prüfen ob ein weiterer Datensatz vorhanden ist. */
          if (!SQLResultSet.next()) return;
/* 
 * Prüfen ob die Gültigkeit des bearbeiteten Datensatzes mit dem Arbeitsdatum übereinstimmt.
 * Damit werden Datensätze ausgeschlossen, deren Gültigkeit eventuell erst in der Zukunft beginnt. */
          locdteReadValidFrom = SQLResultSet.getDate(JSBS_DBA.CONST_ValidFrom);
          locdteReadValidTill = SQLResultSet.getDate(JSBS_DBA.CONST_ValidTill);
/* Methode aus der Basisklasse verwenden um die Gültigkeit zu prüfen. */
          if (isWithinDateRange(locdteWorkDate, locdteReadValidFrom, locdteReadValidTill)) {
/* 
 * Ein DBA-Objekt 'konstruieren' und die Werte aus dem SQLResultSet übertragen. */
            JS_ProjAssist_ProjLang_DBA locstructJS_ProjAssist_ProjLang_DBA =
              new JS_ProjAssist_ProjLang_DBA();
            locstructJS_ProjAssist_ProjLang_DBA.getValuesFromSQLResultSet(SQLResultSet);
/* 
 * Das DBA-Objekt in den Vector mit der Liste der DBA-Objekte einfügen.
 * Der Vector ist in der geerbten Basisklasse definiert. */
            vecRecordSet.addElement(locstructJS_ProjAssist_ProjLang_DBA);
          }
        }
      }
      catch (SQLException SQLExc) {
/* Wenn ein Fehler aufgetreten ist dann den Fehler-Text extrahieren und an die
 * aufrufende Methode zurückliefern. */
        ErrorMsg = SQLExc.getMessage();
      }
    }
}

▲ zum Inhaltsverzeichnis

Weitere Schritte und verwandte Dokumentation

▲ zum Inhaltsverzeichnis