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の間だけ必要なはずなので)。