Zwischenspeicherung von DBX-Parametern

Nach oben zu DataSnap-REST

Das Zwischenspeichern von DBX-Parametern in REST-Sitzungen ermöglicht die Ausführung einer Servermethode mit mehreren Ausgabe- und Rückgabeparametern, ohne dass die komplexen Typergebnisse, wie Tabellen, Objekte usw., in JSON formatiert zurückgegeben werden müssen. Dazu wurde die Zwischenspeicherung von komplexen Typen auf dem Server eingeführt. Des Weiteren wurde der Client mit einem URL (Uniform Resource Locator) für den einzelnen Zugriff auf die Rückgabetypen ausgestattet.

Details

Als Beispiel soll die folgende Methode auf dem Server dienen:

function GetImage(Name: String; out Stream: TStream): TStream;

Beachten Sie bitte, dass die Funktion GetImage zwei Streams zurückgibt. Vor der Einführung der Parameter-Zwischenspeicherung konnte diese Servermethode nur über einen URL des folgenden Typs ausgeführt werden: http://host:port/datasnap/rest/Classame/GetImage/Name.

Dieser URL führt die Funktion korrekt aus, aber beide Streams werden als JSON-Byte-Arrays zurückgegeben. Wenn nur ein einzelner Stream zurückgegeben wird, könnten Sie das Ausgabeformat mit dem URL-Parameter json (true/false) steuern. Dieser Parameter wird jedoch ignoriert, wenn mehrere Ergebnisse zurückgegeben werden, um Datenverluste zu vermeiden.

Jetzt können Sie dieselbe Funktion (z.B. GetImage) mit dem obigen URL ausführen, und dabei application/rest als den Accept-Header-Wert der Anforderung übergeben. Auf diese Weise erkennt der Server, dass Sie anhand des Zwischenspeichers der aktuellen Sitzung die komplexen Parameter behandeln möchten. Datenverlustprobleme werden so gelöst, aber der Anwender muss auf dem Server die Methode und zusätzlich jeden komplexen Parameter aufrufen, den er lesen möchte.

Ein Beispiel

Der folgende Quelltext ist ein Beispiel, das die Funktion GetImage ausführt. Es wird vorausgesetzt, dass beide Streams Bilder sind. Das Beispiel fügt die zwischengespeicherten Bilder in eine Webseite, die Bilder enthält, ein.

  function PopulateImages()
  {
    var exec=new ServerFunctionExecutor("ClassName");
    var resultObj=exec.executeMethod("GetImage", null, "GET", ["Key"], null, true, null, "application/rest");
    // returns: {"result":["0/0/0", "0/0/1"],"cacheId":0,"cmdIndex":0}
    document.getElementById("image1").src=exec.getCacheURL(resultObj.result[0],true);
    document.getElementById("image2").src=exec.getCacheURL(resultObj.result[1],true);
  }

Der obige Quelltext geht von einigen Voraussetzungen bezüglich der Webseite aus, mit der er geladen wird, sollte aber die Grundidee veranschaulichen. Es gibt zwei Hauptänderungen bei ServerFunctionExecutor, die deutlich werden. Erstens: Die Funktion executeMethod übernimmt am Ende einen optionalen Parameter, der der im Accept -Header der Anforderung verwendete Wert wird. Zweitens: Die neue Funktion getCacheURL wurde hinzugefügt. Sie gibt den vollständigen URL auf das zwischengespeicherte Objekt auf der Basis des Teil-URLs zurück, der im Ausführungsergebnis angegeben ist. Das als zweiter Parameter übergebene true bewirkt, dass die Sitzungs-ID dem zurückgegebenen URL hinzugefügt wird, so dass der URL eigenständig ohne ServerFunctionExecutor arbeiten kann.

Ergebnisformat

Wie oben bereits erwähnt, ist das zurückgegebene Ergebnis bei der Angabe von application/rest als Accept-Typ geringfügig unterschiedlich. Der Hauptunterschied besteht darin, dass das zurückgegebene Ergebnis für jeden komplexen Datentyp, wie Tabelle, Objekt, Stream usw., ein URL-Fragment anstatt des tatsächlichen Wertes ist. Das Fragment ist wie folgt zu verstehen:

[Zwischenspeicher-Eintrags-ID]/[Befehlsindex]/[Parameterindex]

wobei Zwischenspeicher-Eintrags-ID der eindeutige Bezeichner für den Methodenaufruf ist, den Sie ausführen. Beachten Sie aber, dass nur Ausführungen, die Ergebnisse im Zwischenspeicher speichern, eindeutige Bezeichner erhalten. Befehlsindex bezeichnet den Befehl der Ausführung, zu dem das Ergebnis gehört. Es ist nur ein Wert ungleich Null , wenn es sich um eine Stapelausführung handelt, die gleichzeitig mehrere Servermethoden betrifft. Parameterindex ist der Index des komplexen Parameters, der zurückgegeben werden soll. Dieser Index beginnt mit Null und basiert nur auf den komplexen Parametern des Befehls, nicht auf den anderen.

Außer diesem Unterschied hat das Ergebnisobjekt auch zwei neue Eigenschaften, CacheId und CmdIndex. Diese Eigenschaften sind dieselben Werte wie die beiden ersten Teile des weiter oben erwähnten URL-Fragments und sind nur vorhanden, damit diese Werte ohne Zerlegen des URL-Fragments ermittelt werden können.

Interaktion mit dem Zwischenspeicher

Zwischenspeicherungs-URLs unterstützen die Anforderungstypen GET und DELETE.

Wird ein GET-Befehl aufgerufen, sind die folgenden URLs verfügbar:

URL	Bedeutung
http://host:port/datasnap/cache	Gibt ein JSON-Objekt zurück, das den Inhalt des Zwischenspeichers beschreibt.
http://host:port/datasnap/cache/[Zwischenspeicherungs-ID]	Gibt ein JSON-Objekt zurück, das das Zwischenspeicherungsobjekt mit der angegebenen ID beschreibt.
http://host:port/datasnap/cache/[CacheID]/[Befehlsindex]/	Gibt eine JSON-Repräsentation des angegebenen Befehls zurück.
http://host:port/datasnap/cache/[CacheId]/[CmdIndex]/[Parameterindex]	Gibt den tatsächlichen Parameter als JSON oder Stream zurück.

Wird ein GET-Befehl aufgerufen, sind die folgenden URLs verfügbar:

URL	Bedeutung
http://host:port/datasnap/cache	Löscht alle zwischengespeicherten Einträge.
http://host:port/datasnap/cache/[Zwischenspeicherungs-ID]	Löscht die zwischengespeicherten Einträge und alle zugehörigen Befehle und/oder Parameter.

Anforderungsfilter

Wenn Sie keinen Zwischenspeicher verwenden, arbeiten Anforderungsfilter wie üblich. Bei der Verwendung des Zwischenspeichers unterstützt eine GET-Anforderung, die einen bestimmten Parameter (z.B. CacheId/CmdIndex/ParameterIndex) angibt, dieselben Anforderungsfilter. Bei der Verwendung dieser Parameter muss aber Folgendes beachtet werden:

• Beim ersten Aufruf der Servermethode werden Anforderungsfilter für komplexe Typen ignoriert. Die Filter für diese Parameter werden nicht für komplexe Typen angewendet und werden nicht für die spätere Verwendung beim Ermitteln von Parametern aus dem Zwischenspeicher gespeichert.

• Bei der Verwendung von Anforderungsfiltern für zwischengespeicherte Streams müssen Sie den Parameter json=false hinzufügen. Ansonsten werden die Filter ignoriert, und der Stream wird direkt als Inhalts-Stream der Antwort zurückgegeben.

• Der Parameterindex für die Filter ist der ursprüngliche Parameterindex, nicht der Index des komplexen Parameters im Zwischenspeicher. Mit anderen Worten: Der Index entspricht dem, was Sie angegeben hätten, wenn Sie den Filter in dem ursprünglichen Methodenaufruf verwendet hätten.

JS Proxy-Änderungen

Die erzeugte JS Proxy-Funktionen unterstützen jetzt einen weiteren optionalen Parameter nach Callback und Filter, der nicht in der Funktionssignatur erscheint. Dieser Parameter wird als String behandelt und direkt als Wert von Accept in dem Anforderungs-Header verwendet.

Siehe auch

• DataSnap-REST