Next: Process-based JSONRPC connections, Up: JSONRPC [Contents][Index]
specから引用するとJSONRPCは、"同一プロセス、ソケットやhttp、多くのさまざまなメッセージパッシング環境において使用可能という概念においてトランスポート非依存"です。
この非依存性をモデル化するために、jsonrpcライブラリーはリモートのJSONのエンドポイントへの接続の表現にjsonrpc-connectionクラスのオブジェクトを使用します(Emacsのオブジェクトシステムの詳細はEIEIO in EIEIOを参照)。これはオブジェクト指向の現代的な用語では“抽象的(abstract)”なクラス、すなわち有用な接続オブジェクトの実クラスは常にjsonrpc-connectionのサブクラスになります。それにも関わらず、jsonrpc-connectionクラスを中心に2つのAPIを個別に定義できます。
このシナリオではJSONRPCアプリケーションはjsonrpc-connectionの具象サブクラスを選択して、make-instanceを使用することによりサブクラスのオブジェクト作成を行う。JSONRPCアプリケーションはリモートのエンドポイントとの対話を開始するために、関数jsonrpc-notify、jsonrpc-request、および/またはjsonrpc-async-requestにこのオブジェクトを渡す。一般的には非同期に到達するリモートで開始された対話を処理するために、インスタンス化には:request-dispatcherと:notification-dispatcherの初期化引数(initarg)を含める必要があり、これらはいずれも接続オブジェクト、リモートで呼び出されたJSONRPCメソッドを命名するシンボル、JSONRPCのparamsオブジェクトという3つの引数を受け取る関数である。
:request-dispatcherとして渡された関数は、ローカルのエンドポイントからのリプライ(この場合では構築するプログラム)を除いた、リモートのエンドポイントのリクエストを処理する役目を担う。その関数の内部では局所的なリターン(通常のリターン)と非局所的なリターン(エラーによるリターン)が起こり得る。局所的なリターン値はJSONとしてシリアライズ可能なLispオブジェクトでなければならない(Parsing JSONを参照)。これは成功レスポンスを決定するとともに、オブジェクトはJSONRPCのresultオブジェクトとしてサーバーにフォワードされる。関数jsonrpc-errorの呼び出しにより達成される非局所的なリターンは、エラーレスポンスをサーバーに送信する。JSONRPCのerrorに付随する詳細には、jsonrpc-errorに渡されるものすべてが含まれる。他のタイプの予期せぬエラーからトリガーされた非局所的なリターンでも、(
debug-on-errorをセットしていなければ)エラーレスポンスを送信して、この場合にはLispデバッガが呼び出される。Error Debuggingを参照のこと。
このシナリオでは基盤として異なるトランスポートストラテジーを実装するためにjsonrpc-connectionをサブクラス化する(サブクラス化する方法についての詳細は(eieio)Inheritanceを参照)。その後にアプリケーション構築インターフェースのユーザーは、(
make-instance関数を使用して)その具象クラスのオブジェクトをインスタンス化して、そのストラテジーを使用してJSONRPCエンドポイントに接続できる。
このAPIには必須部分とオプション部分がある。
ユーザーがJSONRPCコンタクト(通知やリクエスト)を開始したり、エンドポイントにリプライできるようにするためには、そのサブクラスはjsonrpc-connection-sendメソッドを実装しなければならない。
同様に3種類のリモートコンタクト(リクエスト、通知、ローカルリクエストへの応答)を処理するために、トランスポート実装はワイヤー(wire:
通信ライン)上への新たなJSONRPCメッセージの通知後に、(その"ワイヤー"が何であれ)関数jsonrpc-connection-receiveが呼び出されるように計らわなければならない。
最後にオプジョンとしてjsonrpc-shutdownメソッドとjsonrpc-running-pメソッドの概念をトランスポートに適用する場合には、jsonrpc-connectionサブクラスはそれらのメソッドを実装する必要がある。それらを行う場合には、ワイヤー上でメッセージをリッスン(listen)するために使用するシステムリソース(プロセス、タイマー等)はjsonrpc-shutdownで解放する必要がある(それらのリソースはjsonrpc-running-pが非nilの間だけ必要なはずなので)。