付録 F   動的に結果をキャッシュする関数


この付録で説明する関数を使って、iPlanet Web Server 用の結果をキャッシュするプラグインを作成できます。 Service SAF である結果をキャッシュするプラグインは、Web サーバのアドレス空間にあるデータ、ページ、またはページの一部をキャッシュします。これらのものは、要求に応じて定期的に Web サーバによってリフレッシュすることができます。 Init SAF は、リフレッシュを行なうコールバック関数を初期化します。

結果をキャッシュするプラグインは、次の 3 つの部分からなる要求に対するページを生成することができます。

• ページバナーなどのヘッダー。要求ごとに変わります。

• 本体。あまり頻繁には変わりません。

• フッター。これも、要求ごとに変わります。

この機能がなければ、プラグインは要求ごとにページ全体を生成しなければならなくなります (IFRAME を使用しない限り。IFRAME を使用する場合は、ヘッダーまたはフッターがその本体をポイントする IFRAME とともに最初の応答で送信されます。この場合ブラウザは、IFRAME に対する別の要求を送信しなければなりません)。

ページの本体が変更されていなければ、プラグインはヘッダーとフッターのみを生成して、次のような引数を持つ dr_net_write 関数 (net_write ではなく) を呼び出す必要があります。

• ヘッダー

• フッター

• キャッシュへのハンドル

• キャッシュされたオブジェクトを識別する鍵

Web サーバは、キャッシュから本体を取り出すことで、ページ全体を構築します。 キャッシュの有効期限が切れている場合は、リフレッシュ関数を呼び出して、リフレッシュされたページをクライアントに送信します。

プラグインから見える Init SAF は、キャッシュへのハンドルを作成します。 Init SAF は、dr_cache_init 関数に次のようなパラメータを渡す必要があります。

• RefreshFunctionPointer

• FreeFunctionPointer

• KeyComparatorFunctionPtr

• RefershInterval

RefershInterval 値は PrIntervalTime タイプでなければなりません。 詳細は、次の場所にある NSPR リファレンスを参照してください。

http://www.mozilla.org/projects/nspr/reference/html/index.html

別のケースとして、本体が Web サーバシステムのマシン内のディレクトリにあるファイルの場合、プラグインは、ヘッダーとフッターを生成して、ファイル名とともに fc_net_write 関数を呼び出すことができます。

この付録では、結果をキャッシュするプラグインが使用できるもっとも重要な関数をリストしています。 詳細については次のファイルを参照してください。

server_root/plugins/include/drnsapi.h

dr_cache_destroy

dr_cache_destroy 関数は、以前に作成され使用されたキャッシュハンドルに関連するリソースを削除して、解放します。 別の dr_cache_init を実行しない限り、このハンドルは、前述の関数へのこの後の呼び出しには使用できなくなります。

構文
void dr_cache_destroy(DrHdl *hdl);

パラメータ
DrHdl *hdlは、キャッシュへの以前に初期化したハンドルへのポインタです (dr_cache_init を参照)。

戻り値
void

例
dr_cache_destroy(&myHdl);

dr_cache_init

dr_cache_init 関数は、キャッシュへの持続性ハンドル、つまり障害時の NULL を作成します。 これは Init SAF によって呼び出されます。

構文
PRInt32 dr_cache_init(DrHdl *hdl, RefreshFunc_t ref, FreeFunc_t fre, CompareFunc_t cmp, PRUint32 maxEntries, PRIntervalTime maxAge);

戻り値
1 成功した場合。

0 エラーが発生した場合。

パラメータ
DrHdl hdl は、割り当てられていないハンドルへのポインタです。

RefreshFunc_t ref は、キャッシュリフレッシュ関数へのポインタです。 これは NULL にすることができます。dr_net_write の DR_CHECK フラグと DR_EXPIR 戻り値を参照してください。

FreeFunc_t fre は、エントリを解放する関数へのポインタです。

CompareFunc_t cmp は、鍵比較関数へのポインタです。

PRUint32 maxEntriesp は、指定した hdl のキャッシュに入れることができるエントリの最大数です。

PRIntervalTime maxAgep は、エントリが有効な最大時間です。 0 の場合、キャッシュが期限切れになることはありません。

例
if(!dr_cache_init(&hdl, (RefreshFunc_t)FnRefresh, (FreeFunc_t)FnFree, (CompareFunc_t)FnCompare, 150000, PR_SecondsToInterval(7200)))
{
   ereport(LOG_FAILURE, "dr_cache_init() failed");
   return(REQ_ABORTED);
}

dr_cache_refresh

dr_cache_refresh 関数は、プラグインが要求したときにキャッシュエントリをリフレッシュする方法を提供します。 これは、dr_cache_init 内の ref パラメータには NULL を渡し、dr_net_write 呼び出し内に DR_CHECK を渡すことで、実行することができます。 DR_CHECK が dr_net_write に渡され、DR_EXPIR が返される場合、プラグインは、応答を送信するために、再度 dr_net_write を呼び出す前に、エントリに新しい内容を生成し、そのエントリで dr_cache_refresh を呼び出す必要があります。

プラグインは、まだ期限切れになっていなくても、キャッシュされたエントリを単に置き換えることを決定することもあります (他のビジネスロジックに従って)。 この場合、dr_cache_refresh 関数が便利です。 このようにプラグインは、自身でキャッシュリフレッシュ管理をアクティブに行ないます。

構文
PRInt32 dr_cache_refresh(DrHdl hdl, const char *key, PRUint32 klen, PRIntervalTime timeout, Entry *entry, Request *rq, Session *sn);

戻り値
1 成功した場合。

0 エラーが発生した場合。

パラメータ
DrHdl hdl は、dr_cache_init 関数によって作成される持続性ハンドルです。

const char *key は、キャッシュ、検索、またはリフレッシュへの鍵です。

PRUint32 klen は、鍵の長さ (バイト) です。

PRIntervalTime timeout は、このエントリの期限切れの時間です。 値 0 が渡されると、dr_cache_init に渡された maxAge 値が使用されます。

Entry *entry は、キャッシュされる非 NULL エントリです。

Request *rq は、要求へのポインタです。

Session *sn は、セッションへのポインタです。

例
Entry entry;
char *key = "MOVIES"
GenNewMovieList(&entry.data, &entry.dataLen); // Implemented by
                                              // plugin developer
if(!dr_cache_refresh(hdl, key, strlen(key), 0, &entry, rq, sn))
{
   ereport(LOG_FAILURE, "dr_cache_refresh() failed");
   return REQ_ABORTED;
}

dr_net_write

dr_net_write 関数は、hdr、本体としてキャッシュされたエントリの内容 (key を使って配置されたもの)、および ftr から成るページ全体を構築したあと、要求者に応答を返信します。 hdr、ftr、または hdl は NULL にすることができますが、これらのすべてを NULL にすることはできません。 hdl が NULL の場合、キャッシュ検索は行なわれません。呼び出し元はフラグとして DR_NONE を渡さなければなりません。

デフォルトでは、キャッシュエントリが dr_cache_init に渡された ref 関数への呼び出しによって期限切れになった場合に、この関数がキャッシュエントリをリフレッシュします。 指定した key でキャッシュエントリが見つからない場合は、応答を送信する前にこの関数が ref 関数を呼び出して、新しいキャッシュエントリを追加します。 ただし、DR_CHECK フラグが flags パラメータで渡され、キャッシュエントリが期限切れになったか、key に相当するキャッシュエントリが存在しない場合は、dr_net_write はデータを送信しません。 代わりに、DR_EXPIR とともに返されます。

ref (dr_cache_init に渡される) が NULL の場合、DR_CHECK フラグは flags パラメータには渡されず、key に相当するキャッシュエントリは期限切れになっているか存在せず、dr_net_write は DR_ERROR で失敗します。 しかし、ref が NULL ではなく、DR_CHECK が渡されない場合は、dr_net_write はキャッシュをリフレッシュします。

ref (dr_cache_init に渡される) が NULL で、DR_CHECK フラグが渡されなくても DR_IGNORE が渡され、キャッシュにエントリがある場合、エントリが期限切れになっていても dr_net_write は応答を送信します。 ただし、エントリが見つからない場合は、dr_net_write は DR_ERROR を返します。

ref (dr_cache_init に渡される) が NULL ではなく、DR_CHECK フラグが渡されなくても DR_IGNORE が渡され、キャッシュにエントリがある場合、エントリが期限切れになっていても dr_net_write は応答を送信します。 ただし、エントリが見つからない場合、dr_net_write は、応答を送信する前に ref 関数を呼び出して、ref から返された新しいエントリを格納します。

構文
PRInt32 dr_net_write(DrHdl hdl, const char *key, PRUint32 klen, const char *hdr, const char *ftr, PRUint32 hlen, PRUint32 flen, PRIntervalTime timeout, PRUint32 flags, Request *rq, Session *sn);

戻り値
IO_OKAY 成功した場合。

IO_ERROR エラーが発生した場合。

DR_ERROR キャッシュ処理でエラーが発生した場合。

DR_EXPIR キャッシュの期限が切れている場合。

パラメータ
DrHdl hdl は、dr_cache_init 関数によって作成される持続性ハンドルです。

const char *key は、キャッシュ、検索、またはリフレッシュへの鍵です。

PRUint32 klen は、鍵の長さ (バイト) です。

const char *hdr は任意のヘッダーデータです (NULL にすることもできます)。

const char *ftr は任意のフッターデータです (NULL にすることもできます)。

PRUint32 hlen は、ヘッダーデータの長さ (バイト) です (0 にすることもできます)。

PRUint32 flen は、フッターデータの長さ (バイト) です (0 にすることもできます)。

PRIntervalTime timeout は、この関数を強制終了するまでのタイムアウトです。

PRUint32 flags は、この関数の ORed 指令です (「フラグ」を参照)。

Request *rq は、要求へのポインタです。

Session *sn は、セッションへのポインタです。

フラグ
DR_NONE は、キャッシュを使用しないことを指定します。このため、関数は net_write と同じように機能します。DrHdl は NULL にすることができます。

DR_FORCE は、キャッシュが期限切れになっていない場合でも、強制的にキャッシュをリフレッシュさせます。

DR_CHECK は、キャッシュの期限が切れている場合に DR_EXPIR を返します。 呼び出し元の関数がリフレッシュ関数を提供しておらず、このフラグが使われない場合は、DR_ERROR が返されます。

DR_IGNORE は、キャッシュの期限が切れている場合でもキャッシュの期限切れを無視して、キャッシュエントリを送信します。

DR_CNTLEN は、「Content-length」ヘッダーを提供し、PROTOCOL_START_RESPONSE を実行します。

DR_PROTO は PROTOCOL_START_RESPONSE を実行します。

例
if(dr_net_write(Dr, szFileName, iLenK, NULL, NULL, 0, 0, 0, DR_CNTLEN | DR_PROTO, rq, sn) == IO_ERROR)
{
   return(REQ_ABORTED);
}

fc_net_write

fc_net_write 関数は、ヘッダー、フッターのどちらかまたはその両方と、システム内のどこかに存在するファイルを送信するために使われます。 fileName は、ファイルへの絶対パスでなければなりません。

構文
PRInt32 fc_net_write(const char *fileName, const char *hdr, const char *ftr, PRUint32 hlen, PRUint32 flen, PRUint32 flags, PRIntervalTime timeout, Session *sn, Request *rq);

戻り値
IO_OKAY 成功した場合。

IO_ERROR エラーが発生した場合。

FC_ERROR ファイル処理でエラーが発生した場合。

パラメータ
const char *fileName は挿入されるファイルです。

const char *hdr は任意のヘッダーデータです (NULL にすることもできます)。

const char *ftr は任意のフッターデータです (NULL にすることもできます)。

PRUint32 hlen は、ヘッダーデータの長さ (バイト) です (0 にすることもできます)。

PRUint32 flen は、フッターデータの長さ (バイト) です (0 にすることもできます)。

PRUint32 flags は、この関数の ORed 指令です (「フラグ」を参照)。

PRIntervalTime timeout は、この関数を強制終了するまでのタイムアウトです。

Request *rq は、要求へのポインタです。

Session *sn は、セッションへのポインタです。

フラグ
FC_CNTLEN は、「Content-length」ヘッダーを提供し、PROTOCOL_START_RESPONSE を実行します。

FC_PROTO は PROTOCOL_START_RESPONSE を実行します。

例
const char *fileName = "/docs/myads/file1.ad";
char *hdr = GenHdr(); // Implemented by plugin
char *ftr = GenFtr(); // Implemented by plugin

if(fc_net_write(fileName, hdr, ftr, strlen(hdr), strlen(ftr),
   FC_CNTLEN, PR_INTERVAL_NO_TIMEOUT, sn, rq) != IO_OKEY)
{
   ereport(LOG_FAILURE, "fc_net_write() failed");
   return REQ_ABORTED;
}