Genealogie: Code-Struktur/Datenbankschicht
Die Objektstruktur: HirachyDB
Verzeichnis: Der Code der Datenbankschicht befindet sich im Verzeichnis: Genealogie\DB\. Die Objekte:
  • CDBException
  • CDB
  • CDBLog
  • CDBLogin
  • CDBConnect
  • CDBData
befinden sich im File DB.inc.php. Für alle anderen Objekte der Datenbankschicht wurden in der Regel eigene Files (nach dem Muster DB*.inc.php) angelegt.
CDBException: Beschreibung:

CDBException ist von Exception abgeleitet. Fehler in der Datenbankschicht lösen die Fehlerklasse CDBException aus.


Auruf der Fehler-Exception:

  throw new CDBException("Es ist ein Fehler aufgetreten!");  


Die Methoden:

  function __construct($ErrorMessage)  

An den Constructor wird eine "Klartext"-Fehlermeldung übergeben, die ebenso wie die im Constructor ermittelte Fehlermeldung der Datenbank über die beiden nachfolgenden Methoden abgefragt werden können:


  public function getErrorMessage()  

Die an den Constructor übergebene Fehlermeldung wird zurückgegeben.


  public function getDBMessage()  

Die im Constructor von der Datenbank gelesene Fehlermeldung wird zurückgegeben.
CDB: Beschreibung:

Von CDB sind alle Objekte der Datenbankschicht abgeleitet (bis auf CDBException). Sie enthält die elementaren Methoden zum Zugriff auf die Datenbank.


Die Methoden:

  public function getDBConnection()  

Gibt die Datenbank-Connection zurück. Der Rückgabewert ist 0, wenn keine Connection aktiv ist.


  public function getDBServer()  
  public function getDBDatabase()  
  public function getDBLogin()  
  public function getDBPassword()  

Schnittstellen-Methoden, zur Rückgabe der einzelnen Login-Parameter. Das für die Connection zuständige Objekt ist das von CDB abgeleitete Objekt CDBConnect. In CDB fungieren sie daher nur als Platzhalter.


  public function connect()  
  public function disconnect()  

Methoden zum Verbinden und Trennen der Datenbank. connect() benutzt dazu die mittels getDBServer(), getDBDatabase(), getDBLogin() und getPassword() übergebenen Parameter. Sollte der Verbindungsaufbau oder Abbau fehlschlagen, dann wird CDBException ausgelöst.


  public function executeQuery($SQL, $ErrorMessage = "")  

Führt eine SQL-Datenbankabfrage (SELECT) aus. Das Result-Set wird als zweidimensionales Array zurückgegeben. Der ersten Dimension ist als Array-Key die jeweilig Zeilennummer (mit 0 beginnend) zugeordnet. In der zweiten Dimension werden die Tabellenspalten zurück gegeben. Als Array-Key werden hier die Spaltennamen genutzt.

Beispiel:    ... = $Result[0]["SpaltenName"]

Als zweiter Parameter kann eine "Klartext"-Fehlermeldung übergeben werden. Im Fehlerall wird diese CDBException im Constructor übergeben.


  public function executeUpdate($SQL, $ErrorMessage = "")  

Führt eine SQL-Datenbankanweisung (INSERT, UPDATE, DELETE) aus, bei der kein Result-Set erwartet wird.

Als zweiter Parameter kann eine "Klartext"-Fehlermeldung übergeben werden. Im Fehlerfall wird diese CDBException im Constructor übergeben.


  public function getRows()  

Gibt die Anzahl der durch executeQuery und executeUpdate beeinflußten Zeilen zurück.
CDBLog: Beschreibung:

In CDBLog ist die Funktionalität zur Nutzung des Datenbank-Logs und dem Auslesen der in der Datenbank hinterlegten Parameter realisiert. Nähere Informationen zum Datenbank-Log und der Parameterablage finden Sie im Kapitel Datenmodel.


Die Methoden (Parameter):

  public function getParameter($Group, $Label, $Default)  

Gibt ein in der Datenbank hinterlegten Parameter zurück. Dabei representiert $Group die Parametergruppe und $Label den entsprechenden Parameter in der Gruppe. Sollte der Parameter nicht gefunden werden, dann gibt die Methode den in $Default definierten Wert zurück.


Die Methoden (Logging):

Jede im Log zu hinterlegende Message soll der aktiven Log-Session zugeordnet werden. Dazu muß beim Starten der WEB-Application (physisch im Objekt CSession) eine Log-Session-ID auf der Datenbank erzeugt werden, die dann der Zuordnung der Log-Messages zur aktiven Session dient. Diese darf nicht mit der Session-ID des WEB-Servers verwechselt werden! Sie dient lediglich der Zuordnung der Log-Messages zu einer aktiven Session, sodaß die Log-Messages nicht nur in ihrem zeitlichen Verlauf sondern auch in ihrem funktionalen Zusammenhang ausgewertet werden können.


  public function createLogSessionID()  

Erzeugt eine neue Log-Session-ID und gibt diese zurück. Die Bezeichnung der Session wird dazu als Parameter übergeben und zusammen mit der neu erzeugten Log-Session-ID auf der Datenbank abgelegt.


  public function getLogSessionID()  

Gibt die aktive Log-Session-ID zurück, nachdem diese zu Beginn der Session mit createLogSessionID() erzeugt wurde. Wurde keine Log-Session-ID erzeugt, dann wird 0 zurück gegeben.


  public function setLogSessionID($LogSessionID)  

Setzt die Log-Session-ID (wenn diese z.B. andersweitig erzeugt wurde).


  public function setLogMessage($Source, $Type, $Message)  

Speichert eine Log-Message auf der Datenbank. Dazu sind die folgenden Übergabeparameter erforderlich:


$Source  :  Modul, das die Meldung erzeugt hat
$Type  :  Beschreibt die Art der Log-Message. Die folgenden Werte sind gültig:
INF:  Allgemeine Meldung
ERR:  Fehler-Meldung
TRC:  Trace-Meldung
STA:  Start-Meldung
STP:  Stop-Mmeldung
$Message  :  Zu speichernde Log-Meldung
CDBLogin: Beschreibung:

Um individuell und ohne Administrationsrechte auf der Datenbank User anzulegen und diesen individuell Rechte innerhalb der Applikation zuordnen zu können, wurde eine eigene User- und Login-Verwaltung implementiert. Nähere Informationen finden Sie im Kapitel Datenmodel. CDBLogin enthält dazu die für die allgemeine Nutzung notwendigen Methoden.


Die Methoden:

  public function getLogin()  
  public function getPassword()  

Die beiden Methoden geben die Login-Parameter des aktiven Applications-User zurück. Die Rückgabewerte sind leer, wenn kein Applications-User angemeldet ist.


  public function logon($Login, $Password)  

Überprüft das in $Password übergebene Password für den in $Login übergebenen Application-User. Das Ergebnis der Überprüfung wird als Rückgabewert zurück gegeben:


user_not_defined  :  Der angegebene Application-User ist ungültig.
wrong_pw  :  Das Password ist nicht korrekt.
locked  :  Der Application-User wurde gelockt (Vom Administrator, nach zu vielen fehlerhaften Logins).
pw_must_changed  :  Der Application-User muß sein Password ändern (durch Einstellung des Administrator, nach Ablauf des Gültigkeitszeitraums für das Password).
active  :  Der Application-User hat sich erfolgreich mit dem richtigem Password angemeldet.

Fehlerhafte und erfolgreiche Logins werden in einer eigenen Tabelle protokolliert (siehe dazu des Kapitel Datenmodel dieser Dokumentation).


  public function changePassword($OldPassword, $NewPassword)  

Ändert das Password des aktiven Users nach Überprüfung des alten Password ($OldPassword). Vorher wird das neue Password ($NewPassword) au Einhaltung der definierten Password-Regeln überprüft. Weiterhin wird überprüft, daß das neue Password nicht mit einem der zuletzt verwendeten Passwörtern übereinstimmt. Wieviele alte Passwörter überprüft werden ist auf der Datenbank als Parameter hinterlegt und somit vom Administrator frei wählbar.

Wurde das Password erfolgreich geändert, gibt die Methode den String "Password changed" zurück. Im Fehlerfall wird eine Fehlermeldung im Klartext zurück gegeben.

Jede Password-Änderung wird in einer eigenen Tabelle protokolliert (Siehe dazu des Kapitel Datenmodel dieser Dokumentation)


  public function checkPasswordRoles($Password)  
  public function getPasswordRoles()  

In checkPasswordRoles können die Password-Regeln hinterlegt werden. Die Passwörter werden dann beim Auruf von changePassword mit dieser Methode auf Einhaltung der Regeln überprüft (z.Z. wird lediglich überprüft, daß das neue Password mindestens 6 Zeichen lang ist).

getPasswordRoles gibt eine Klartext-Beschreibung der Password-Regeln zurück (zur Anzeige für die User).


  public function getPermission($Permission)  

Gibt true zurück, wenn der aktive Application-User das in $Permission angegebene Recht hat.
CDBConnect: Beschreibung:

Bei der Instanzierung von CDBConnect wird automatisch eine Datenbank-Verbindung augebaut. Dazu werden die notwendigen Verbindungs-Parameter im Constructor aus der Datei Connect.inc.php gelesen. Connect.inc.php ist wie folgt aufgebaut:


 
<?php
  DBServer = localhost
  DBDatabase = Datenbank
  DBLogin = User
  DBPassword = Password
?>
 

Durch die Datei-Endung .php und die Klammerung der Parameter in den Blöcken <?php und ?> werden die Parameter vom WEB-Server als PHP-Script interpretiert. Wird diese Datei über den WEB-Server aufgerufen, so wird lediglch eine Fehlermeldung angezeigt, nicht jedoch die Parameterwerte!


Die Methoden:

  function __construct()  
  function __destruct()  

Wie oben ausgeführt werden die Verbindungs-Parameter im Constructor aus der Datei Connect.inc.php gelesen und die Verbindung zur Datebank automatisch aufgebaut. Dazu wird die Methode connect() des Vorgängerobjekts CDB verwendet.

Im Destuctor wird mit der Methode disconnect() des Vorgängerobjekts CDB die Datenbankverbindung automatisch gelöscht.


  public function getDBServer()  
  public function getDBDatabase()  
  public function getDBLogin()  
  public function getDBPassword()  

Diese Methoden, die von CDB vererbt wurden, werden hier überschrieben, sodaß sie die im Constructor aus der Datei Connect.inc.php gelesenen Verbindungs-Parameter zurückliefern.
CSesssion: CDBSession leitet sich zwar von CDBConnect ab, aber aufgrund seiner über alle 4 Schichten wirkenden Funktionalität läßt es sich keiner der 4 Schicht eindeutig zuordnen. Da sich der Code physikalisch im Verzeichnis der Datenstruktur befindet, soll hier nur auf das entsprechende Kapitel verwiesen werden.
CDBData: Beschreibung:

CDBData leitet sich von CDBLog und CDB ab. Damit verfügt es über alle notwendigen Funktionalitäten, die für Objekte der Datenbankschicht representativ sind. Lediglich die notwendigen Verbindungs-Parameter müssen CDBData noch bei der Instanzierung übergeben werden. Da diese zentral im Objekt CDBConnect bzw. in desen Ableitung CSession gehalten werden, wird CSession im Constructor übergeben.


Die Methoden:

  function __construct(CDBConnect $DBConnect)  

Im Constructor werden die Verbindungsparameter aus CDBConnect übernommen.


  public function getDBConnection()  
  public function getLogSessionID()  
  public function getDBServer()  
  public function getDBDatabase()  
  public function getDBLogin()  
  public function getDBPassword()  

Die von CDBund CDBLog übernommenen Methoden werden hier überschrieben und geben die Werte aus CDBConnect (bzw. CDBSession) zurück.
CDB ...: Alle Objekte der Datenbankschicht, die nun direkt in der Application zur Anwendung kommen, sind direkt von CDBData abgeleitet.
.:  :.