DBX パラメータ キャッシング

DataSnap REST への移動

REST セッションでの DBX パラメータ キャッシュ処理により、TTable や TObject などの複合型の結果を JSON 形式で返さなくても、出力パラメータまたは戻り値パラメータを複数持つサーバー メソッドを実行できるようになります。 それを可能にするため、サーバーでの複合型のキャッシングが導入されています。 さらに、クライアントには、それぞれの戻り値型に個別にアクセスするための URL（Uniform Resource Locator）が提供されます。

詳細

例として、サーバー上の以下のメソッドを取り上げましょう。

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

GetImage 関数は 2 つのストリームを返すことに注意してください。 パラメータ キャッシュ処理の導入以前は、このようなサーバー メソッドを実行するには、次のような URL を使用するしか手段はありませんでした： http://host:port/datasnap/rest/Classame/GetImage/Name

この URL で関数は正しく実行されますが、両方のストリームは JSON のバイト配列として返すことになります。 ストリームを 1 つ返すだけなら、URL パラメータ json（true か false）で出力形式を制御することもできます。 ただし、返す結果が複数ある場合は、データ損失を避けるため、これは無視されます。

さて、上記の URL を使ってその同じ関数 （たとえば GetImage）を実行し、要求の Accept ヘッダー値として application/rest を渡すことができます。 このようにして、サーバーには、ユーザーが現在のセッションのキャッシュを使用して複合型パラメータを処理しようとしていることがわかります。 この方法でデータ損失の問題は解決されますが、ユーザーは、メソッド呼び出しのために 1 回、読み取る複合型パラメータごとにもう 1 回ずつサーバーにアクセスする必要があります。

例

以下のコードは、サンプル関数 GetImage を実行する例です。 両方のストリームが画像であると仮定しています。 この例では、2 つの画像が含まれた Web ページに、キャッシュされた画像を設定します。

 
  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);
  }

上記のコードには、Web ページのロードに関していくつかの仮定がありますが、基本的な考え方はこれでわかるはずです。 ServerFunctionExecutor には、一目でわかる大きな変更が 2 つあります。 まず、executeMethod 関数は最後にオプション パラメータを取り、それが要求の Accept ヘッダーで使用される値になります。 第 2 に、getCacheURL という新しい関数が追加されています。これは、実行結果で得られる部分的な URL に基づいて、キャッシュされたオブジェクトの完全な URL を返します。 第 2 パラメータとして true を渡すと、ServerFunctionExecutor がなくても URL が単独で機能できるように、返す URL にセッション ID を追加するように指示することになります。

結果の形式

上記のように、Accept タイプとして application/rest を指定すると、返される結果は少し異なってきます。 主な違いは、TTable、TObject、TStream などの複合データ型ごとに、返される結果は実際の値ではなく URL 断片であることです。 その断片は以下のような形式になります。

[キャッシュ項目 ID]/[コマンド インデックス]/[パラメータ インデックス]

ここで、キャッシュ項目 ID は、実行したメソッド呼び出しの一意な識別子です。 ただし、キャッシュに結果を格納した実行のみ一意な識別子が与えられることに注意してください。 コマンド インデックスは、結果で参照される実行のコマンドを識別するものです。 これは、一度に複数のサーバー メソッドが関与するバッチ実行を行った場合にのみ、ゼロ以外の値になります。 パラメータ インデックスは、返す複合型パラメータのインデックスです。 これは 0 から始まる値で、コマンドの複合型パラメータにのみ基づいたものです。

このような違いの他に、結果オブジェクトに CacheId と CmdIndex の 2 つの新しいプロパティがあることにも気がつきます。 これらのプロパティは、上記 URL 断片の最初の 2 つの部分と同じ値であり、URL 断片を解析せずに値を取得できるように存在しているだけです。

キャッシュとのやり取り

キャッシュ URL では、GET と DELETE の各要求タイプをサポートしています。

GET コマンドを発行する際には、以下の URL を使用できます。

URL	意味
http://host:port/datasnap/cache	キャッシュの内容を記述した JSON オブジェクトを返します。
http://host:port/datasnap/cache/[CacheID]	指定された ID のキャッシュ オブジェクトを記述した JSON オブジェクトを返します。
http://host:port/datasnap/cache/[CacheID]/[CmdIndex]/	指定されたコマンドの JSON 表現を返します。
http://host:port/datasnap/cache/[CacheId]/[CmdIndex]/[ParameterIndex]	実パラメータを JSON またはストリームとして返します。

DELETE コマンドを発行する際には、以下の URL がサポートされています。

URL	意味
http://host:port/datasnap/cache	キャッシュされているすべての項目を削除します。
http://host:port/datasnap/cache/[CacheID]	キャッシュされている項目とそのすべてのコマンドやパラメータを削除します。

要求フィルタ

キャッシュを使用しない場合は、要求フィルタはこれまでどおりに動作します。 キャッシュを使用する場合、特定のパラメータ（たとえば CacheId/CmdIndex/ParameterIndex など）を指定した GET 要求では同じ要求フィルタをサポートしています。 ただし、使用時の注意事項が以下のようにいくつかあります。

• サーバー メソッドへの最初の呼び出しでは、複合型に関する要求フィルタはすべて無視されます。 これらのパラメータのフィルタは複合型には適用されず、パラメータをキャッシュから取得する際に後での使用に備えて記憶されることはありません。

• キャッシュされたストリームに対して要求フィルタを使用する際は、パラメータ json=false を追加する必要があります。 そうしなければ、フィルタは無視され、ストリームが応答のコンテンツ ストリームとして直接返されます。

• フィルタのパラメータ インデックスは、キャッシュにある複合型パラメータのインデックスではなく、元のパラメータ インデックスです。 つまり、インデックスは、フィルタを元のメソッド呼び出しで使用した場合に指定するものと同じです。

JS プロキシの変更点

生成される JS プロキシ関数では、関数シグニチャに現れない追加のオプション パラメータをコールバックとフィルタの後に使用できるようになりました。 このパラメータは文字列として扱われ、要求ヘッダー内の Accept の値として直接使用されます。

関連項目

• DataSnap REST