Class: DataSet

Source Location: /DataSet.php

Class Overview [line 57]


Speicher für Daten nach dem relationalen Datenmodell; im Hauptspeicher gehalten.

Author(s):

  • Matthias Ansorg <matthias at ansorgs dot de>

Version:

Copyright:

Variables

Constants

Methods


Inherited Variables

Inherited Constants

Inherited Methods



Class Details

Speicher für Daten nach dem relationalen Datenmodell; im Hauptspeicher gehalten.

Tags:

[ Top ]


Class Variables

$DataSetName =

[line 122]

eindeutiger Name dieses DataSets

get/set-Methode dieses Attributs: dataSetName.

Tags:

  • access - private

Type: string

Overrides:

[ Top ]

$EnforceConstraints = true

[line 150]

Wahrheitswert, der bestimmt, ob die Constraints dieses DataSets durchgesetzt werden sollen

get/set-Methode dieses Attributs: enforceConstraints. Standardwert: true.

Tags:

  • access - private

Type: bool

Overrides:

[ Top ]

$Tables =

[line 185]

die Kollektion der Tabellen dieses DataSets

get/set-Methode zu diesem Attribut: tables

Tags:

  • access - private

Type: DataTable[]

Overrides:

[ Top ]


Class Methods

DataSet

DataSet DataSet( [string $DataSetName = null])

[line 69]

Konstruktor zur Initialisierung jedes neuen DataSets

Für jeden Aufruf dieses Konstruktor wird eine neu erzeugte Kopie eines DataSets initialisiert. Dazu gehört, sie mit einem eindeutigen Namen zu versehen. Wird kein Name als Parameter übergeben, so wird automatisch ein eindeutiger Name generiert.

Tags:

  • access - public

Parameters:

  • string $DataSetName - ptionaler benutzerdefinierter Name für dieses DataSet

[ Top ]

Clear

void Clear( )

[line 211]

Löscht alle Daten dieses DataSets

Alle Zeilen aller Tabellen werden entfernt. Die Schemata der Tabellen, d.h. ihre DataColumn-Objekte, bleiben jedoch erhalten. Ebenso bleiben die Beziehungen der Tabellen erhalten, d.h. ihre DataRelation-Objekte.

Tags:

  • access - public

Parameters:

[ Top ]

containsBasicSchemaOf

bool containsBasicSchemaOf( object $DataProvider)

[line 419]

Ermittle, ob das Schema der Tabellen dieses DataSets die Basis für das Schema aller übergebenen Tabellen enthält.

Ein Schema ist die Kollektion der DataColumns einer Tabelle (d.h. auch, die Reihenfolge wird berücksichtigt). Ein Schema ist eine zulässige Erweiterung eines anderen Schemas, wenn es von diesem anderen Schema nur durch zusätzliche, am Ende angefügte Spalten differiert.

containsBasicSchemaOf prüft nun nach, ob die Schemata aller übergebenen Tabellen solche zulässigen Erweiterungen der Schemata der Tabellen in diesem DataSet sind. Die erste Voraussetzung ist dabei, dass zu jeder übergebenen Tabelle überhaupt eine gleichnamige Tabelle in diesem DataSet existiert.

Tags:

  • return - Angabe, ob die Schemata aller übergebenen Tabellen zulässige Erweiterungen der Schemata der entsprechenden Tabellen in diesem DataSet sind (true) oder nicht (false).
  • access - private

Parameters:

  • object $DataProvider - Enthält ein oder mehrere Tabellen, für die nachgeprüft wird, ob sie zulässige Erweiterungen des Schemas dieses DataSets sind. Es können übergeben werden: DataSet, DataTable oder DataRow.

[ Top ]

dataSetName

string dataSetName( [mixed $DataSetName = null], string $dataSetName)

[line 135]

eindeutiger Name dieses DataSets (lesen, schreiben)

get/set-Methode des Attributs DataSetName.

Tags:

  • return - aktueller Name dieses DataSets. Entspricht dem Parameter dieser Methode, wenn ein solcher angegeben wurde, d.h. wenn die Methode als set-Methode verwendet wurde.
  • access - public

Parameters:

  • string $dataSetName - Name, den das DataSet annehmen soll. Optional.

[ Top ]

enforceConstraints

bool enforceConstraints( [bool $EnforceConstraints = null])

[line 166]

Wahrheitswert, der bestimmt, ob die Constraints dieses DataSets angewandt werden sollen(lesen, schreiben).

get/set-Methode des Attributs EnforceConstraints. Für die gelesenen und zu schreibenden Wahrheitswerte gilt: true, um Constraints durchzusetzen, false, um Constraints nicht durchzusetzen.

Tags:

  • return - Wahrheitswert, den das Attribut EnforceConstraints angenommen hat. Wurde ein Parameter übergeben, so ist der Rückgabewert diesem gleich.
  • access - public

Parameters:

  • bool $EnforceConstraints - Wahrheitswert, den das Attribut EnforceConstraints annehmen soll. Optional.

[ Top ]

extend

void extend( string $subclassName, string $code)

[line 488]

Wandelt das aktuelle DataSet-Objekt in eine Instanz einer dynamisch erzeugten Unterklasse von DataSet um.

Der Name der dynamisch zu erzeugenden Unterklasse kann als Parameter übergeben werden. Auch können Methoden und Eigenschaften, die zur Implementierung der Unterklasse gehören sollen, per Parameter als PHP-Quelltext übergeben werden.

Dies ist eine Hilfsfunktion für makeTyped.

Tags:

  • todo - Diese Methode wird auch in den Klassen DataTable und DataRow gebraucht, um ihre Instanzen in typisierte Pendants umwandeln zu können. Dazu sollte diese Methode in eine gemeinsame Oberklasse »Typable« ausgegliedert werden.
  • access - private

Parameters:

  • string $subclassName - Name der dynamisch zu erzeugenden Unterklasse. $this ist nach Aufruf dieser Methode eine Instanz einer Klasse mit diesem Namen! Der Name darf keine schon existierende Klasse bezeichnen, um Konflikte zu vermeiden.
  • string $code - PHP-Code, der die Implementierung der dynamisch erzeugten Unterklasse darstellen soll. Auch Überschreiben von Methoden und Attributen ist zulässig.

[ Top ]

makeTyped

void makeTyped( )

[line 540]

Wandelt das DataSet-Objekt inkl.

seinem gesamten Schema in ein typisiertes DataSet um.

Das Schema eines DataSets ist die Menge seiner DataTables, und DataRelations. Ein typisiertes DataSet ist selbst typisiert (d.h. Instanz einer Unterklasse von DataSet) und besitzt auch typisierte DataTables. Das sind Unterklassen von DataTable. Typisierte DataTables besitzen wiederum typisierte DataRows, das sind Unterklassen von DataRow.

Der Klassenname eines typisierten DataSets ergibt sich aus dem Namen des -Objektes (siehe dataSetName), dem »DataSet_« vorangestellt wird.

Typisierte DataSets werden erstellt, indem man dem Konstruktor als Parameter eine XSD-Datei (XML Schema Definition) übergibt, die das Schema des DataSets angibt (wobei diese Funktionalität erst nach Version 1.0 zur Verfügung stehen wird). Entsprechend ist diese Methode makeTyped auch nur zur Verwendung im Konstruktor gedacht, daher private.

Die Methoden DataSet::makeTyped() und DataSet::extend() sind vollständig implementiert, jedoch müssen noch Änderungen an DataTable und DataRow vorgenommen werden, um eine vollständige Typisierung zu ermöglichen. Die notwendigen Änderungen sind in den @todo-Tags dokumentiert.

Tags:

  • todo - Wie hier für den Zugriff auf die Tables-Collection eines DataSet gezeigt, muss in typisierten DataTables der Zugriff auf die Collections DataTable::$Rows(), DataTable::$Columns, DataTable::$ParentRelations und DataTable::$ChildRelations durch eine get/set-Methode pro Element ermöglicht werden.
  • todo - Auch die Klassen DataTable und DataRow benötigen eine Methode makeTyped(). Ihre Grundfunktionalität sollte also in eine Basisklasse »Typable« ausgegliedert werden. makeTyped() der Basisklasse wird dann durch DataSet, DataTable und DataRow genutzt und durch eine eigene spezialisierte Version überschrieben (Polymorphie).
  • access - private

Parameters:

[ Top ]

Merge

void Merge( mixed $secondDataProvider, &object[] $signalQueue, [string $onMissingSchema = null])

[line 282]

führt dieses DataSet mit anderen Daten (DataRows, DataTable oder DataSet) und ihren Schemata zusammen.

Die Zusammenführung läuft wie folgt ab:

  1. Zusammenführung der Schemata. Üblicherweise wird die Merge-Methode für Daten mit identischen Schemata verwendet, das ist jedoch nicht zwingend. Zulässinge Schemadifferenzen sind zusätzliche Spalten geänderte Primärschlüsseleinstellungen in Tabellen. Diese eventuellen Zusätze werden ermittelt und dann die Schemata entsprechend dem Argument $onMissingSchema behandelt.
  2. Zusammenführung der Daten. Dabei werden Daten aus Schemaelementen, die in den Quelldaten zusätzlich vorhanden sind, nur übernommen, wenn $onMissingSchema den Wert MissingSchemaAction::Add()oder MissingSchemaAction::AddWithKey() hat. Alle anderen Daten werden aus den jeweils gleichnamigen Tabellen der Quelldaten übernommen, vorausgesetzt sie haben nicht denselben Primärschlüsselwert wie eine in der betreffenden Tabelle der Zieldaten existierende DataRow. Das nämlich wird als Fehler gewertet.

Tags:

  • todo - Beschreibe und implementiere die Fehlerbehandlung, wenn in Quell- und Zieldaten eine Zeile mit gleichen Primärschlüsselwerten vorkommt und EnforceConstraints==true ist. Wie im Microsoft .NET-DataSet soll das zu einem MergeFailed-Event führen. Wird nach Version 1.0 implementiert, weil erst dann das Constraint-Handling implementiert wird und die von LoadDataRow erzeugten Exceptions, an denen Merge diesen Fehler nur erkennen kann.
  • see - MissingSchemaAction
  • access - public

Parameters:

  • mixed $secondDataProvider - Daten, die mit diesem ersten DataSet zusammengeführt werden sollen. Zulässig sind: DataRow[] (sofern alle DataRow-Objekte denselben Wert des Attributs DataRow::$Table haben), DataTable, DataSet.
  • &object[] $signalQueue - Warteschlange für Events und Exceptions. Ihre Verwendung ist in DataExceptions.php dokumentiert. Alle Events und Exceptions, die diese Methode erzeugt, werden hier angehängt. Das sind hier MergeFailed-Event und InvalidOperationException.
  • string $onMissingSchema - Angabe, welche Aktion auszuführen ist wenn das Ziel-DataSet Schemaelemente vermisst, die die Quelldaten besitzen. Zulässige Werte sind die der statischen Variablen der Klasse MissingSchemaAction. Optionales Argument. Fehlt es, entspricht das der Angabe MissingSchemaAction::Ignore.

[ Top ]

presetObjCounter

mixed presetObjCounter( mixed $newPresetValue)

[line 107]

Klassenweiter Startwert für einen Zähler, der zur Generierung eindeutiger Namen für -Objekte im Konstruktor verwendet wird.

Der Startwert wird beim nächsten Aufruf von DataSet::DataSet() ausgewertet und dabei gleichzeitig gelöscht, so dass folgende Aufrufe von DataSet::DataSet() beim aktuellen Zählerstand und nicht wieder bei diesem Startwert beginnen. Löschen bedeutet, dass dieser Startwert auf null gesetzt wird.

Zugriff eigentlich friend, erlaubt auch für DataSetTest. Gedacht ist diese Methode dazu, in Tests auch statische Variablen direkt setzen zu können, um so ihre aktuellen Werte zu kennen und sinnvolle Annahmen über zukünftige Werte in den Tests machen zu können.

Tags:

  • return - bisheriger Wert des Startwertes. Es kann ein Integer sein oder null. Der letzte Fall bedeutet, dass der Startwert nicht gesetzt ist.
  • access - private

Parameters:

  • mixed $newPresetValue - neuer Wert, den der Startwert annehmen soll. Es kann ein Integer oder null übergeben werden. Letzteres bedeutet ein Löschen des Startwertes.

[ Top ]

Reset

void Reset( )

[line 232]

bringt das DataSet in den Zustand zurück, den es hatte nachdem der Konstruktor ausgeführt wurde

Wie bei Clear werden alle Daten gelöscht. Darüber hinaus werden alle Änderungen an der Struktur gelöscht; für DataSet als Basisklasse bedeutet das: alle Tabellen und alle Relationen. Seinen Namen behält das DataSet jedoch, er wurde ja im Konstruktor festgelegt.

Diese Methode ist hauptsächlich bei der Verwendung von typisierten DataSets wertvoll. Dabei repräsetiert jede von DataSet abgeleitete Klasse einen Typ eines DataSets, mit spezifischem Schema, spezifischen Beziehungen der Tabellen und Constraints. Diese werden durch den Konstruktor erzeugt und müssen durch eine überschriebene Version dieser Methode * wiederhergestellt werden.

Tags:

  • access - public

Parameters:

[ Top ]

tables

DataTable[] &tables( )

[line 198]

die Tabellen dieses DataSets als Kollektion (lesen, schreiben)

get/set-Methode des Attributs Tables. Schreiben geschieht durch Ändern des Rückgabewertes, er ist eine Referenz. Das Attribut ein assoziatives Array mit den Namen der Tabellen als Schlüsseln. Wie jedes PHP-Array kann der Zugriff auch mit numerischem Index erfolgen: array_values($dataSet->tables())[0].

Tags:

  • return - Kollektion aller Tabellen, die in diesem DataSet enthalten sind.
  • access - public

Parameters:

[ Top ]


Class Methods


Documentation generated on Tue, 27 Jul 2004 21:15:36 +0200 by phpDocumentor 1.3.0RC3