Requests als Schablonen und die Darstellung der Ergebnis-Daten

Für jede Anfrage in einem Payload wird genau eine Antwort im Ergebnis-Payload erzeugt. Bei Requests, die nicht Instanz-Eigenschaften abfragen, sondern setzen oder Instanzen erzeugen, werden die Daten zurückgegeben, die auch das entsprechende Tcl-Kommando zurückgeben würde.

<cm-request ...>
  <obj-where>
    <id>2001</id>
  </obj-where>
  <obj-create>
    <name>simplepub</name>
    <objClass>publication</objClass>
  </obj-create>
</cm-request>

Der obige Request, der eine Datei unmittelbar unterhalb des Basisordners erzeugt, führt zu folgender Response:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <obj>
      <id>32191</id>
    </obj>
  </cm-code>
</cm-response>

Bei Anfragen, mit denen Instanzen-Eigenschaften mit where und folgendem get ermittelt werden sollen, gibt die Struktur der Anfrage die Struktur der Antwort vor. Eine Anfrage ist gewissermaßen eine Schablone, die der Content Management Server ausfüllt, um die Antwort zu erzeugen. Im folgenden Beispiel gibt der Request vor, dass die Response den Namen und die ID der selektierten Dateien enthalten soll.

<cm-request ...>
  <obj-where>
    <objClass>document</objClass>
  </obj-where>
  <obj-get>
    <name/>
    <id/>
  </obj-get>
</cm-request>

Das Antwort-Dokument zu diesem Request wird eine Response enthalten, in der für jede auf die Kriterien im obj-where-Element passende Datei der Name und die ID geliefert werden:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <obj>
      <name>mary</name>
      <id>92674</id>
    </obj>
  </cm-code>
  <cm-code numeric="0" phrase="ok">
    <obj>
      <name>john</name>
      <id>72941</id>
    </obj>
  </cm-code>
</cm-response>

In den beiden vorausgehenden Beispiel-Responses ist zu erkennen, dass für jede mit where selektierte Instanz ein cm-code-Element erzeugt wird. Innerhalb eines solchen Elements sind die abgefragten Instanzen-Werte als Inhalt des Klassen-Elements kodiert. In den obigen Beispielen ist dies das obj-Element.

Manche Instanzen-Eigenschaften sind Referenzen auf Instanzen der gleichen oder einer anderen Klasse. So ist beispielsweise der Ordner, in dem sich eine Datei befindet (parent) außer beim Basisordner eine Referenz auf eine Datei-Instanz. Die Mitglieder (users) einer Benutzergruppe (group) sind Benutzer-Referenzen, und die obligatorischen Felder (mandatoryAttributes) eine Dateivorlage (objClass) sind Referenzen auf Felder (attribute). Wie später gezeigt wird, können die Instanzen, auf die sich die Referenzen beziehen, durch eine Erweiterung der Abfrage-Schablone im get-Element ebenfalls nach ihren Eigenschaften befragt werden.

Hier folgt erst einmal ein Beispiel, das zeigt, wie die Dateien im Basisordner abgefragt und in der Antwort kodiert werden:

<cm-request ...>
  <obj-where>
    <path>/</path>
  </obj-where>
  <obj-get>
    <children/>
  </obj-get>
</cm-request>

Die Antwort hat das folgende Schema:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <obj>
      <children type="list">
        <listitem>92674</listitem>
        <listitem>72941</listitem>
      </children>
    </obj>
  </cm-code>
</cm-response>

Zurückgegeben werden in diesen Fällen die eindeutigen Identifikatoren der Instanzen, bei Dateien, Versionen und Links die IDs, bei den Instanzen aller anderen Klassen die Namen. Ein Identifikator wird nicht als Inhalt des entsprechenden Eigenschaften-Elements kodiert, d. h. die ID einer Datei-Referenz ist nicht der Inhalt eines id-Elements und der Name eines Feldes ist nicht der Inhalt eines name-Elements. Stattdessen werden die Identifikatoren mit listitem als Listenelemente kodiert. Hier ein Beispiel, in dem die Gruppen ermittelt werden, in denen ein Benutzer Mitglied ist. Auf den Request

<cm-request ...>
  <user-where>
    <login>mustermann</login>
  </user-where>
  <user-get>
    <groups/>
  </user-get>
</cm-request>

folgt eine Antwort nach diesem Schema:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <user>
      <groups type="list">
        <listitem>cmadmins</listitem>
        <listitem>sysadmins</listitem>
      </groups>
    </user>
  </cm-code>
</cm-response>

Erweiterte Abfrage

Wenn die in einer Anfrage ermittelten Daten Instanzen einer Klasse sind, so kann man die Anfrage erweitern, um Daten auch dieser Instanzen zu ermitteln. So sind die im obigen Beispiel abgefragten Gruppen Instanzen der Klasse group, und jede dieser Instanzen kann im gleichen Request nach Parameterwerten befragt werden:

<cm-request ...>
  <user-where>
    <login>mustermann</login>
  </user-where>
  <user-get>
    <groups>
      <group>
        <realName/>
        <users>
      </group>
    </groups>
  </user-get>
</cm-request>

Der obige Request erzeugt eine Antwort nach dem folgenden Muster:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <user>
      <groups>
        <group>
          <realName>CM-Administratoren</realName>
          <users type="list">
            <listitem>musterfrau</listitem>
            <listitem>mustermann</listitem>
          </users>
        </group>
        <group>
          <realName>System-Administratoren</realName>
          <users type="list">
            <listitem>mustermann</listitem>
          </users>
        </group>
      </groups>
    </user>
  </cm-code>
</cm-response>

Mit einer einzigen Anfrage können also Daten über die ursprünglichen und die von ihnen referenzierten Instanzen in beliebiger Tiefe ermittelt werden. Zu diesem Zweck kodiert man wie im obigen Beispiel die abzufragende Eigenschaft nicht als leeres Element. Stattdessen gibt man als Inhalt dieses Elements die Schablone für die weitere Abfrage vor.

Das folgende Beispiel zeigt, wie man bei Ordnern den jeweiligen Namen und die Dateivorlage ermittelt. Von den Dateivorlagen werden die erlaubten Vorlagen für darunter liegende Dateien abgefragt und von diesen wiederum der Name und der Titel in deutscher Sprache:

<cm-request ...>
  <obj-where>
    <objType>publication</objType>
  </obj-where>
  <obj-get>
    <name/>
    <objClass>
      <name/>
      <validSubObjClasses>
        <name/>
        <title lang="de"/>
      </validSubObjClasses>
    </objClass>
  </obj-get>
</cm-request>

Diese Anfrage erzeugt eine Antwort nach dem folgenden Schema:

<cm-response ...>
  <cm-code numeric="0" phrase="ok">
    <obj>
      <name>ROOTPUB</name>
      <objClass>
        <name>publication<name/>
        <validSubObjClasses>
          <objClass>
            <name>publication</name>
            <title lang="de">Standard-Ordner</title>
          </objClass>
          <objClass>
            <name>document</name>
            <title lang="de">Standard-Dokument</title>
          </objClass>
          ...
        </validSubObjClasses>
      </objClass>
    <obj>
  </cm-code>
  <cm-code numeric="0" phrase="ok"> ... </cm-code>
  <cm-code numeric="0" phrase="ok"> ... </cm-code>
  ...
</cm-response>

Bitte beachten Sie, dass eine Eigenschaft nur dadurch zu einer weiterzuverfolgenden Referenz wird, dass das entsprechende Element nicht leer ist, sondern die zu ermittelnden Eigenschaften in seinem Inhalt kodiert sind. Die folgende Anfrage liefert zu jeder Datei des Typs publication die ID des darüber liegenden Ordners und die IDs der Dateien in diesem Ordner (also die ursprüngliche Datei und deren Geschwisterdateien):

<cm-request ...>
  <obj-where>
    <objType>publication</objType>
  </obj-where>
  <obj-get>
    <parent/>
    <parent>
      <children/>
    </parent>
  </obj-get>
</cm-request>

Während das erste parent-Element nur die ID liefert, weil es leer ist, liefert das zweite die in seinem Inhalt spezifizierten Eigenschaften des darüber liegenden Ordners, also die children.