XQDB-Referenzhandbuch für Version 0.1

Allgemeines

Admintool

Mit dem Admintool können Anfragen an die Datenbank gestellt werden. Wenn dem Admintool der Parameter USETESTFILE übergeben wird, werden anstatt der angegebenen Anfrage die Testqueries ausgeführt.
ACHTUNG: Die Benuzterverwaltung und die Dokumente 'test' und 'test1' werden verändert!

Struktur der Dokumente

Die Dokumente der XQDB entsprechen nicht genau dem XML-Standart des W3C. Die XQDB hat neben den Element-, Text-, Kommentart- und Attributknoten noch eine 5 Knotenart, die Accessknoten. Sie stehen wie die Attribute innerhalb der Elementknoten, doch sie beginnen mit einer Raute '#'. Die Accessknoten haben immer die folgende Form: #GruppenOderUserName='rwxi'. Die vier Buchstaben haben folgende bedeutung:

r: read, die Gruppe / der Benuzter darf den Inhalt des Elements lesen (for ... reutrn ...)
w: write, die Gruppe / der Benuzter darf in des Element schreiben (for ... rename / replace ...)
x: execute, die Gruppe / der Benuzter darf den Knoten mit Kinderknoten löschen (for ... delte ...)
i: insert, die Gruppe / der Benuzter darf Kinderknoten in das Element einfügen (for ... insert ...)

Wenn der Buchstabe angegeben wird, hat die Gruppe / der Benuzter zugriff auf den Elementknoten, wenn ein Bindestrich '-' angegeben wird, wird der Gruppe / dem Benuzter der Zugriff verweigert. Die EBNF eines XML-Dokuments:
(Die Grammatik verwendet die gleiche EBNF-Notation wie in REC-xml-19980210 (mit der Ausnahme, dass Grammatiksymbole immer mit einem Grossbuchstaben beginnen).)

`[1]`	`Document`	`::=`	`CharData Element CharData`
`[2]`	`Element`	`::=`	`'<' QName ( S Attribute \| Attribute ) * S '/>'`
			`\| '<' QName ( S Attribute \| Attribute ) * S '>' Content ''`
`[3]`	`Access`	`::=`	`'#' QName '=' Literal`
`[4]`	`Attribute`	`::=`	`QName '=' Literal`
`[5]`	`Comment`	`::=`	`'<!--' CharData '-->'`
`[6]`	`Content`	`::=`	`CharData ? ( Element \| Comment )`

Benuzterverwaltung

Jedes Dokument hat automatisch eine Benuzterverwaltung. Wenn diese umgangen werden soll, dann kann man sich entweder als Benuzter root anmelden oder man kann in den Wurzelknoten folgenden Accessknoten einfügen:

#groups="rwxi"

Das Dokument users bildet die Benuztervarwaltung. Es ist folgendermassen aufgebaut:

<?xml version="1.0"?>
<auth>
  <users>
    <root passwd="" />
    <guest passwd="" />
  </users>
  <groups>
    <guest />
    <admin>
      <root />
    </admin>
  </groups>
</auth>

In <users> sind alle Benuzter mit den Passwörtern gespeichert, in <groups> sind die Gruppen mit den Benutzern gespeichert.
Es gibt zwei ausgezeichnete Benuzter in der Datenbank. XQDB_GUEST und XQDB_ROOT. Wenn ein Benuzter nicht eingeloggd ist, ist er immer als XQDB_GUEST angemeldet. XQDB_ROOT ist der Root auf der Datenbank. Ihm kann man keine Rechte wegnehmen, er hat auf alles Zugriff.

XQDB-Funktionsreferenz

XQDB::execute()

folgt noch ...

XQDB::getTimerMsg()

return string[] Array mit den Zeiten, die die Funktionen der XQDB für die Ausführung brauchten.

XQDB::getErrorMsg()

return string Beschreibung, des Zuletzt aufgetretenen Fehlers.

Gibt die Beschreibung des zuletzt aufgetretenen Fehler zurück. Wenn kein Fehler aufgetreten ist, wird null zurückgegeben.

XQDB::getErrorNo()

return int Nummer des zuletzt aufgetretenen Fehlers.

Gibt die Nummer des zuletzt aufgetretenen Fehler zurück. Mögliche Rückgabewerte sind aus den Konstanten zusammengesetzte Fehlernummern. Wenn kein Fehler aufgetreten ist, wird XQDB_OK zurückgegeben.

Einführung in XQDB: Ein Tutorial

Diese Kapitel enthält eine Einführung in XQDB in Form eines Tutorials. Dabei werden die wichtigsten Syntaxelemente erläutert. Die Beispeile beziehen sich auf die ein und Ausgabe der shell. Als Beispieldokumente werden immer die beiden Dokumente './manual/xqdb.example.xml' und './manual/xqdb.users.xml' verwendet.

Benuzter anmelden

Mit LOGIN benuztername 'passwort' kann man sich bei der Datenbank anmelden.

xqldb> LOGIN root ''

Benuzter abmelden

Mit LOGOUT kann man sich bei der Datenbank abmelden. Wenn man sich nicht angemeldet oder abgemeldet hat, ist man als Gast eingeloggd.

xqldb> LOGOUT

Erstellen eines Dokuments

Ein Dokument wird mit der folgenden Syntax erstellt: CREATE DOCUMENT 'documentName'
Das Dokument ist leer und kann nun gefüllt werden. Der Name des Dokuments muss eindeutig sein, d.h er darf nur einmal in der Datenbank vokommen.

xqldb> CREATE DOCUMENT 'test'

Alle vorhandenen Dokumente anzeigen

Die Syntax SHOW DOCUMENTS zeigt die Namen alle in der Datenbank gespeicherten Dokumente an.

xqldb> SHOW DOCUMENTS 
 'test'

Inhalt eines Dokuments löschen

Mit TRUNCATE DOCUMENT ( 'documentName' | users ) kann der Inhalt eines Dokuments gelöscht werden. Der Inhalt wird unwiederruflich gelöscht und kann nicht wieder hergestellt werden. Es kann entweder der Name eines Dokuments als Literal (in Hockkomma " oder ') oder die Zeichenfolge 'users' angegeben werden. Wenn users angegeben wird, wird das Dokument mit der Benuzterverwaltung gelöscht.

xqldb> TRUNCATE DOCUMENT 'test' 
xqldb> TRUNCATE DOCUMENT users

Löschen eines Dokuments

Mit DROP DOCUMENT 'documentName' kann der Inhalt eines Dokuments gelöscht werden. Der Inhalt wird unwiederruflich gelöscht und kann nicht wieder hergestellt werden.

xqldb> DROP DOCUMENT 'test'

Dokument in die Datenbank importieren

Mit LOAD 'pfad' INTO ( 'documentName' | users ) kann eine externe Datei in die Datenbank eingelesen werden. Das Dokument muss leer sein, damit eine Datei importiert werden kann.

xqldb> load './manual/xqdb.example.xml' into 'test' 
xqldb> load './manual/xqdb.users.xml' into users

Dokument aus der Datenbank exportieren

Mit SAVE ( 'documentName' | users ) INTO 'pfad' wird ein Dokument in eine Datei gespeichert. Die Ausgegebene Datei entspricht nicht dem genauen XML-Standart, da auch die Zugriffsknoten exportiert werden.

xqldb> save 'test' into '/tmp/test.xml' 
xqldb> save users into '/tmp/users.xml'

Abfrage an ein Dokument

Mit FOR variable IN DOCUMENT( 'documentName' | users )/pfad RETURN variable wird ein besimmter Pfad in einem Dokument abgefragt.

xqldb> for $x in document('test')/zutat return $x/text()
xqldb> for $x in document('test')/zutat return $x/attribute::id
xqldb> for $x in document(users)/users return $x/root

Knoten löschen

Mit FOR variable IN DOCUMENT( 'documentName' | users )/pfad DELETE variable wird ein Knoten mit all seinen Kinderknoten unwiederruflich gelöscht und kann nicht wiederhergestellt werden.

xqldb> for $x in document('test')/anleitung/zutat delete $x
xqldb> for $x in document('test')/anleitung delete $x/access::test
xqldb> for $x in document(users)/descendant-or-self::*/root delete $x

Knoten umbenennen

Mit FOR variable IN DOCUMENT( 'documentName' | users )/pfad RENAME variable TO 'name' wird ein Knoten umbenannt.

xqldb> for $x in document('test')/anleitung/zutat rename $x to 'andereZutat'

Knoten ersetzen

Mit FOR variable IN DOCUMENT( 'documentName' | users )/pfad REPLACE variable TO 'neuerWert' wird der Inhalt eines Knotens geändert. Replace kann nur auf Text, Kommentart, Attribute und Accessknoten angewant werden

xqldb> for $x in document('test') replace $x/comment() to 'noch mehr Zutaten :)'
xqldb> for $x in document('test')/zutat replace $x/attribute::id to 'Vollkornmehl'
xqldb> for $x in document('test') replace $x/access::groups to 'rw--'
xqldb> for $x in document(users)/users/root replace $x/attribute::passwd to 'root'

Knoten einfügen

Mit FOR variable IN DOCUMENT( 'documentName' | users )/pfad INSERT 'xmlNodes' ( INTO | BEFORE | AFTER ) variable werden die Elemente, die in xmlNodes gespeichert sind in / vor / nach den ausgewählten Knoten gespeichert.

xqldb> for $x in document('test')/anleitung insert '1Kg Zucker' before $x
xqldb> for $x in document('test')/anleitung insert access(test, 16) into $x

XQDB-Sprachreferenz

[7] Query ::= S SingleQuery S ( ';' S Query S ) ?

[8] SingleQuery ::= Flower

| Login

| Logout

| CreateDocument

| DropDocument

| ShowDocuments

| TruncateDocument

| LoadFile

| SaveFile

[9] Literal ::= '"' [^"]* '"'

| "'" [^']* "'"

[10] Login ::= 'login' QName Literal

[11] Logout ::= 'logout'

[12] CreateDocument ::= 'create' 'document' Literal

[13] DropDocument ::= 'drop' 'document' Literal

[14] ShowDocuments ::= 'show' 'documents'

[15] TruncateDocument ::= 'truncate' 'document' DocumentName

[16] LoadFile ::= 'load' Literal 'into' DocumentName

[17] SaveFile ::= 'save' DocumentName 'into' Literal

[18] Flower ::= 'for' Variable 'in' LocationPath ActionExpr

[19] ActionExpr ::= 'return' ReturnExpr

'delete' DeleteExpr

'rename' RenameExpr

'replace' ReplaceExpr

'insert' InsertExpr

[20] ReturnExpr ::= LocationPath

[21] DeleteExpr ::= LocationPath

[22] RenameExpr ::= LocationPath 'to' Literal

`[7]`	`Query`	`::=`	`S SingleQuery S ( ';' S Query S ) ?`
`[8]`	`SingleQuery`	`::=`	`Flower`
			`\| Login`
			`\| Logout`
			`\| CreateDocument`
			`\| DropDocument`
			`\| ShowDocuments`
			`\| TruncateDocument`
			`\| LoadFile`
			`\| SaveFile`
`[9]`	`Literal`	`::=`	`'"' [^"]* '"'`
			`\| "'" [^']* "'"`
`[10]`	`Login`	`::=`	`'login' QName Literal`
`[11]`	`Logout`	`::=`	`'logout'`
`[12]`	`CreateDocument`	`::=`	`'create' 'document' Literal`
`[13]`	`DropDocument`	`::=`	`'drop' 'document' Literal`
`[14]`	`ShowDocuments`	`::=`	`'show' 'documents'`
`[15]`	`TruncateDocument`	`::=`	`'truncate' 'document' DocumentName`
`[16]`	`LoadFile`	`::=`	`'load' Literal 'into' DocumentName`
`[17]`	`SaveFile`	`::=`	`'save' DocumentName 'into' Literal`
`[18]`	`Flower`	`::=`	`'for' Variable 'in' LocationPath ActionExpr`
`[19]`	`ActionExpr`	`::=`	`'return' ReturnExpr`
			`'delete' DeleteExpr`
			`'rename' RenameExpr`
			`'replace' ReplaceExpr`
			`'insert' InsertExpr`
`[20]`	`ReturnExpr`	`::=`	`LocationPath`
`[21]`	`DeleteExpr`	`::=`	`LocationPath`
`[22]`	`RenameExpr`	`::=`	`LocationPath 'to' Literal`