hql / fullhql

Allgemein

Abfragen gegen JDBC Content Stores werden in HQL (Hibernate Query Language) formuliert, der integrierten Abfragesprache von „Hibernate“, einer Software die zwischen den Objekten in WGA (Content-Dokumente, Struktureinträge etc.) und den relational gespeicherten Daten vermittelt. Eine umfangreiche Dokumentation zu HQL finden sie im Netz:

http://www.hibernate.org/hib_docs/reference/en/html/queryhql.html

Es gibt einen einzigen Unterschied zwischen den hier gezeigten Abfragen und jenen, die sie in WGA verwenden. HQL-Queries beginnen normalerweise mit einer Beschreibung des Objekttypen, der ermittelt werden soll, z.B.

from WGContent as content where ....

Da in WGA-Queries immer derselbe Objekttyp gesucht wird, nämlich Content-Dokumente, übernimmt WGA diesen Teil. Das was in WGA-Queries formuliert wird ist nur der Teil hinter dem „where“:

<tml:query type="hql">content.uniquename = 'home'</tml:query>

Muss die gesamte HQL-Query formuliert werden (was in einigen Spezialfällen notwendig sein kann) so kann man den Querytypen als "fullhql" anstelle "hql" angeben. Hierbei wird dann eine komplette valide Hibernate-HQL-Abfrage als Eingabe erwartet.


<tml:query type="fullhql">from WGContent as content where content.uniquename = 'home'</tml:query>

Generelle Syntax

Die Syntax von HQL ist objektorientiert. Man operiert an Objekten und deren Eigenschaftswerten, die Text-, Nummer- oder Datumswerte sein können oder wiederum selbst Objekte mit eigenen Eigenschaftswerten.

Basis einer Query in WGA ist immer das Objekt „content“. Fragt man eine Eigenschaft des Objektes „content“ ab, so stellt man sie mit einem Punkt dem Objektnamen hinten an:

content.title = 'Home'

Bestimmte Eigenschaften von Objekten sind wiederum selbst Objekte mit eigenen Eigenschaften. Will man die Eigenschaften dieser Objekte abfragen, stellt man sie wiederum mit einem Punkt hinten an:

content.language.name = 'de'

Hier wird die Eigenschaft „language“ des Objektes „content“ abgefragt. Da diese Eigenschaft selbst wieder ein Objekt (vom Typ „Language“) ist, können dessen Eigenschaften, wie „name“ in diesem Beispiel, durch Anfügen eines weiteren Punktes abgefragt werden.

Die verfügbaren Objekte und Eigenschaften der Objekte in WGA sind im Anhang dieses Dokumentes dokumentiert.


ACHTUNG: Wenn auf Schlüsselnamen von Objekten (z.B. der Name von Sprachdefinitionen, wie in diesem Beispiel) geprüft wird, so müssen diese immer im „Lower-Case“ angegeben werden. Die Schlüsselnamen sind in der Referenz "Objekte in HQL-Abfragen und ihre Eigenschaften" am Ende dieses Kapitels als solche ausgewiesen.

Bestimmte Eigenschaften bestehen aus Listen von Werten, die entweder mit einer Nummer oder einem Textbezeichner indiziert sind. Will man eines der Listenelemente einzeln adressieren, so setzt man den Index in eckige Klammern dem Bezeichner hinten an:

content.items['Body'].text != ''


In diesem speziellen Fall beinhaltet die Content-Eigenschaft „items“ eine Liste, die mit Textbezeichnern (den Itemnamen) indiziert ist. Elemente dieser Liste sind wiederum Objekte vom Typ „ContentItem“ (der Typname ist hierbei unwichtig). Content-Items haben selbst eine Eigenschaft „text“, welche den Textinhalt des Items enthält, gesetzt den Fall es handelt sich um ein Text-Item.

VORSICHT: Die Indizes sind Gross/Klein-Sensitiv!

Alle Listeneigenschaften haben selbst wiederum die Eigenschaft „size“, mit welcher Anzahl der Listenelemente geprüft werden kann:


content.items.size > 10


Weitere implizite Eigenschaften von Listen sind:

- „minIndex“ und „maxIndex“: Minimaler und maximaler Index.

- „minElement“ und „maxElement“: Kleinstes und grösstes Element aller Listenelemente (NICHT die Elemente am kleinsten und grössten Index!), wenn die Listenelemente selbst keine Objekte sind.

Diese Eigenschaften funktionieren jedoch nicht auf Datenbanksystemen, die keine Subqueries unterstützen (wie z.B. MySQL 4.0).

Allgemeine Operatoren sind solche Operatoren, die nicht in Abhängigkeit zu einer speziellen Funktion stehen, sondern generell überall verwendet werden können.

Mehrere Ausdrücke können mit Operatoren verbunden werden, wie sie in SQL üblich sind:


content.title = 'Home' AND content.language.name = 'de'
content.title = 'Home' OR content.language.name = 'de'
content.title = 'Home' AND NOT content.language.name = 'en'


Mit Klammerungen kann die Präzedenz der Operatoren festgelegt werden:

content.title = 'Home' AND
(content.language.name = 'en' OR  content.language.name = 'de')


Auf leere Eigenschaften kann mit folgendem Operator getestet werden:

content.virtuallink is not null


Neben dem Gleichheits-Operator gibt es auch den Ungleichheits-Operator und Grösser/Kleiner-Operatoren:

content.structentry.position != 0
content.structentry.position > 0
content.structentry.position >= 0


Desweiteren gibt es den „like“-Operator, der eine String-Matching-Funktionalität ausführt. Als Wildcards wird „?“ für eine einzelnes beliebiges Zeichen und „%“ für eine beliebige Anzahl beliebiger Zeichen verwendet:

content.title like '%wga%'


Der „in“-Operator prüft, ob sich ein Wert in einer Menge von Werten befindet:

content.structentry.doctype.name in ('Standard', 'Homepage', 'News')


Der „between“-Operator prüft, ob ein Wert sich in einem Wertbereich befindet:

content.structentry.position between 0 and 10


Der Operator „exists“ prüft auf das Vorhandensein von Listenelementen:

exists content.items['body']

Es ist möglich, HQL eine Sortierung der Ergebnisse vorzugeben. Das ist in aller Regel performanter, als die (nachträgliche) Sortierung per WebTML. Dazu muss dem Selektionsausdruck (wenn vorhanden) eine „order by“-Klausel angefügt werden:

order by content.title, content.created

ACHTUNG: Sortierungen sind in HQL leider nur nach Metadaten-Feldern, jedoch nicht nach Items möglich.

Items sind in HQL eigene Objekte, die in der Listeneigenschaft „items“ des Content-Objektes gespeichert sind. Diese Listeneigenschaft ist mit den Namen der Items indiziert:

content.items['body']


Die Items wiederum besitzen selbst Eigenschaften, welche ihre Inhaltswerte enthalten. Je nach Datentyp des Items muss eine andere Eigenschaft abgefragt werden:

content.items['body'].text
content.items['body'].number
content.items['body'].date


ACHTUNG: In HQL können nur Items abgefragt werden, die keine Mehrfachwerte enthalten!




Items können wie oben beschrieben auf bestimmte Werte überprüft werden.


content.items['type'].text = 'article'
 content.items['count'].number = 5
content.items['startdate'].date > '2005-05-01 10:00:01.0' 


Aufgrund der Limitationen von SQL ist das Abfragen mehrerer Itemwerte über AND verknüpft komplizierter. Das sich aus der normalen Syntax ergebende Konstrukt funktioniert nicht:

content.items['type'].text = 'article' AND content.items['count'].number = 5 FUNKTIONIERT NICHT!


Grund hierfür ist die Tatsache, dass Items und die sonstigen Daten von Contentdokumenten sich in separaten Tabellen befinden. Einen (komplizierteren) Ausweg aus dieser Situation biete das Artefakt der Subqueries. Ist der Datenbankserver in der Lage SQL-Subqueries zu interpretieren so können AND-verknüpfte Item-Abfragen folgendermaßen formuliert werden:


content in (select item.parentcontent from ContentItem as item where item.name='type' and item.text='article') AND
content in (select item.parentcontent from ContentItem as item where item.name='count' and number=5)


Was hier passiert ist:
• Es werden zwei Subqueries formuliert, jeweils eine in jeder Klammer die separat von der Hauptabfrage ausgeführt werden
• In jeder Subquery werden direkt ContentItem-Objekte abgefragt, welche den gewünschten Namen und den gewünschten Inhalt haben sollen
• Jede Subquery gibt als Ergebnis die Content-Objekte zurück, zu welchen die selektierten Items gehören
• Das Konstrukt "content in" sorgt dafür, dass in der Hauptabfrage nur Contents selektiert werden die durch die jeweilige Subquery zurückgegeben wurden
• Durch AND-Verknüpfung wird dafür gesorgt, dass das Endergebnis der Hauptabfrage nur Contents enthält, die durch alle Subqueries zurückgegeben wurden

Funktionen haben einen Funktionsnamen und übernehmen in runden Klammern Parameter.

Eine Funktion, die Tests gegen alle Elemente einer Liste erlaubt, ist „elements“.


'Hamburg' in elements(content.keywords)


Dieses Beispiel selektiert Contents, in deren Keywords sich das Wort „Hamburg“ befindet.

In Kombination mit dem „in“-Operator kann man so gegen alle Werte eines Items testen.

Ein weiterer Operator, der in Zusammenhang mit „elements“ benutzt werden kann, ist „all“. Er testet, ob alle von Elemente einer Liste demselben Wert entsprechen:


„nav“ = all elements(content.ishiddenfrom)


Dieses Beispiel prüft, ob ein Dokument nur für Navigatoren versteckt ist.

Die Funktionen „upper“ und „lower“ erlauben die Manipulation von Strings, so dass diese nur aus Gross- bzw. Kleinbuchstaben bestehen:


upper(content.title) like „%HAMBURG%“


Hibernate erlaubt es, spezielle Funktionen, die vom verwendet

en Datenbank-Server unterstützt werden, in HQL zu integrieren. So kann z.B. die MySQL-Funktion „date_sub“ auch in HQL verwendet werden, wenn als Datenbank-Backend ein MySQL-Server fungiert:


content.lastmodified < date_sub(NOW(), INTERVAL 10 DAY)


Diese Query ermittelt die Content-Dokumente, die in den letzten 10 Tagen verändert worden sind.

„content“

Das Content-Objekt repräsentiert ein Inhaltsdokument und ist in jeder HQL-Query automatisch vorhanden, muss daher nicht über eine andere Eigenschaft ermittelt werden.

Name	Datentyp	Inhalt
created	Datum	Erstellungsdatum
lastmodified	Datum	Letztes Änderungsdatum
title	Text	Titel
status	Text	Workflow-Status „w“ - In Arbeit „g“ - Zur Genehmigung „p“ - Freigegeben „a“ - Archiviert
uniquename	Text	Eindeutiger Name Schlüsselname, nur lower case abfragen!
version	Nummer	Versionsnummer
ishiddenfrom	Liste von Textelementen, indiziert mit Zahl	Navigationselemente, in welchen das Inhaltsdokument nicht angezeigt werden soll: „nav“ - Navigatoren „search“ - Abfragen „sitemap“ - Sitemap
readers	Liste von Textelementen indiziert mit Zahl	Benutzer, welche dieses Dokument lesen dürfen.
visible	Boolesch (true/false)	Generelles Sichtbarkeits-Flag
validfrom	Datum	Datum, ab welchem das Dokument sichtbar sein darf
validto	Datum	Datum, bis zu welchem das Dokument sichtbar sein darf.
baseimage	Text	Name eines Attachments, welches in Navigatoren angezeigt werden soll.
mouseoverimage	Text	Name eines Attachments, welches in Navigatoren angezeigt werden soll, wenn der Browserbenutzer mit der Maus über den Eintrag dieses Dokumentes fährt.
selectedimage	Text	Name eines Attachments, welches in Navigatoren angezeigt werden soll, wenn das Dokument aktuell angezeigt wird.
usenavimages	Boolesch (true/false)	Steuert, ob bei diesem Dokument Navigationsgrafiken verwendet werden sollen.
virtuallink	Text	Link auf ein Dokument, welches anstelle dieses Dokumentes angezeigt werden soll.
virtuallinktype	Text	Typ des Virtuellen Links. „int“ - Interner Link. Eigenschaft „virtuallink“ enthält den Contentkey eines Dokumentes dieser Content Store. „intfile“ - Interner Link auf ein Attachment an diesem Content-Dokument. Eigenschaft „virtuallink“ enthält den Namen des Attachments. „file“ - Link auf ein Datei an einem Filecontainer. „virtuallink“ enthält relative URL zu dieser Datei. „exturl“ - Externer Link. Eigenschaft „virtuallink“ enthält eine beliebige URL.
linktarget	Text	HTML-Frame, in welchem Links auf dieses Dokument verarbeitet werden sollen.
lastclient	Text	Letzter Client, welcher dieses Dokument bearbeitet hat.
htmlhead	Text	HTML-Text, der zur Ausgabe im HEAD-Bereich des HTML-Dokumentes bestimmt ist, wenn dieses Dokument angezeigt wird.
keywords	Liste von Textelementen, indiziert mit Zahl	Schlüsselwörter zu diesem Inhaltsdokument, welche in Suchmaschinen als Suchbegriffe zu diesem Dokument registriert werden sollen.
refresh	Boolesch (true/false)	Steuert, ob ein HTML-Meta-Tag „refresh“ ausgegeben werden soll, wenn dieses Dokument angezeigt wird.
refreshtime	Zahl	Zeitangabe in Sekunden für Meta-Tag „refresh“.
refreshurl	Text	URL, welche nach Ablauf der Zeit des HTML-Meta-Tags „refresh“ (anstelle der aktuellen) aufgerufen werden soll.
trackingkeys	Liste von Textelementen, indiziert mit Zahl	Schlüsselbegriffe zu diesem Dokument, welche in Zugriffslogs vermerkt werden sollen, wenn ein Zugriff auf dieses Dokument verzeichnet wird.
author	Text	(Ursprünglicher) Autor dieses Dokumentes.
email	Text	E-Mail-Adresse des ursprünglichen Autors.
wfhistory	Liste von Textelementen, indiziert mit Zahl	Liste von Beschreibungen zu Workflow-Stationen dieses Dokumentes.
items	Liste von Elementen des Objektyps „ContentItem“, indiziert mit dem Namen des Items (Text)	Liste aller Items an diesem Inhaltsdokument.
files	Liste von Elementen des Objekttyps „ContentFile“, indiziert mit dem Namen der Dateien (Text)	Liste aller Datei-Attachments an diesem Inhaltsdokument.
structentry	Objekt vom Typ „StructEntry“	Der zugehörige Struktureintrag zu diesem Inhaltsdokument.
language	Objekt vom Typ „Language“	Die zugehörige Sprachdefinition zur Sprache dieses Inhaltsdokumentes.



„contentItem“

Repräsentiert ein Item an einem Inhaltsdokument. Ist über die Listeneigenschaft „content.items“ ermittelbar.

Name	Datentyp	Inhalt
name	Text	Name des Items
type	Nummer	Datentyp des Items 1 – Text 2 – Nummer 3 – Datum
text	Text	Der Textwert dieses Items (wenn es vom Datentyp „Text“ ist).
number	Nummer	Der Nummerwert dieses Items (wenn es vom Datentyp „Nummer“ ist).
date	Datum	Der Datumswert dieses Items (wenn es vom Datentyp „Datum“ ist).




„contentFile“

Repräsentiert ein Datei-Attachment an einen Inhaltsdokument. Ist über die Listeneigenschaft „content.files“ ermittelbar.

Name	Datentyp	Inhalt
name	Text	Name der Datei

„structEntry“

Repräsentiert einen Struktureintrag. Ist über die Eigenschaft „content.structentry“ ermittelbar.

Name	Datentyp	Inhalt
structkey	Text	Schlüssel des Struktureintrags
created	Datum	Erstellungsdatum
lastmodified	Datum	Datum der letzten Modifikation
position	Nummer	Positionsnummer
title	Text	Titel
contentcreators	Liste von Textelementen, indiziert mit Zahl	Personen, die diesen Struktureintrag und seine Inhaltsdokumente indizieren dürfen.
childentrycreators	Liste von Textelementen, indiziert mit Zahl	Personen, die Kind-Struktureinträge und deren Inhaltsdokumente indizieren dürfen (wenn diese Kind-Struktureinträge die Rechte erben).
childentries	Liste von Elementen des Objekttyps „structEntry“, indiziert mit dem Strukturschlüssel dieser Einträge (Text)	Kindeinträge zu diesem Struktureintrag.
parententry	Objekt vom Typ „structEntry“	Der Vatereintrag dieses Struktureintrags.
contenttype	Objekt vom Typ „contentType“	Der Content-Typ zu diesem Struktureintrag.
area	Objekt vom Typ „area“	Website-Bereich dieses Struktureintrags.




„language“

Dies repräsentiert eine Sprachdefinition. Das Objekt ist über die Eigenschaft „content.language“ erreichbar.

Name	Datentyp	Inhalt
name	Text	Name (Code) der Sprache Schlüsselname, nur lower case abfragen!
created	Datum	Erstellungsdatum
lastmodified	Datum	Datum der letzten Modifikation
title	Text	Bezeichnung der Sprache
description	Text	Beschreibung
contentcreators	Liste von Textelementen, indiziert mit Zahl	Liste von Personen, welche Inhaltsdokumente unter dieser Sprache bearbeiten dürfen.




„contentType“

Repräsentiert einen Content-Typen. Das Objekt ist allokierbar über die Eigenschaft „content.structentry.contenttype“.

Name	Datentyp	Inhalt
name	Text	Name des Contenttypen Schlüsselname, nur lower case abfragen!
created	Datum	Erstellungsdatum
lastmodified	Datum	Datum der letzten Modifikation
description	Text	Beschreibung
workflow	Text	Name des zu verwendenen Workflows
outerlayout	Text	Name des TML-Moduls, welches als äußeres Layout verwendet wird.
innerlayout	Text	Name des TML-Moduls, welches als inneres Layout verwendet wird.
positioning	Text	Positionen, an welchen Inhaltsdokumente dieses Contenttypen erstellt werden dürfen: „all“ - Überall. „root“ - Nur als Quelleinträge. „child“ - Nur als Kindeinträge. „fixParentDocs“ - Nur unter bestimmten Vaterdokumenten. „fixParentTypes“ - Nur, wenn das Vaterdokument bestimmten Contenttypen angehört.
preferredparent	Text	Strukturschlüssel des bevorzugten Vaterdokumentes für Struktureinträge dieses Contenttyps.
contentcreators	Liste von Textelementen, indiziert mit Zahl	Liste von Personen, welche Inhaltsdokumente unter diesem Contenttypen bearbeiten dürfen.
allowedpositions	Liste von Textelementen, indiziert mit Zahl	Erlaubte Positionen für Inhaltsdokumente dieses Contenttyps. Bei positioning=“fixParentDocs“ - Strukturschlüssel der erlaubten Vaterdokumente. Bei positioning=“fixParentTypes“ - Namen von erlaubten Contenttypen für das Vaterdokument.
entries	Liste von Elementen des Typs „structEntry“, indiziert mit den Strukturschlüsseln dieser Struktureinträge (Text)	Struktureinträge mit diesem Contenttyp.




„area“

Repräsentiert einen Website-Bereich. Das Objekt ist ermittelbar über die Eigenschaft „content.structentry.area“.

Name	Datentyp	Inhalt
name	Text	Name des Bereichs. Schlüsselname, nur lower case abfragen!
created	Datum	Erstellungsdatum
lastmodified	Datum	Datum der letzten Modifikation
description	Text	Beschreibung
editors	Liste von Textelementen, indiziert mit Zahl	Liste von Personen, die Struktureinträge und Inhaltsdokumente in diesem Bereich bearbeiten dürfen (solange die Struktureinträge des Bereiches ihre Berechtigungen erben).
rootentries	Liste von Elementen des Objekttyps „structEntry“, indiziert mit den Strukturschlüsseln dieser Struktureinträge (Text)	Quelleinträge dieses Bereichs