new repository

1 files changed, 8 insertions, 0 deletions

diff --git a/devdocs/elisp/jsonrpc-overview.html b/devdocs/elisp/jsonrpc-overview.html
new file mode 100644
index 00000000..30700120
--- /dev/null
+++ b/devdocs/elisp/jsonrpc-overview.html
@@ -0,0 +1,8 @@
+ <h4 class="subsection">Overview</h4> <p>Quoting from the <a href="https://www.jsonrpc.org/">spec</a>, JSONRPC "is transport agnostic in that the concepts can be used within the same process, over sockets, over http, or in many various message passing environments." </p>  <p>To model this agnosticism, the <code>jsonrpc</code> library uses objects of a <code>jsonrpc-connection</code> class, which represent a connection to a remote JSON endpoint (for details on Emacs’s object system, see <a href="https://www.gnu.org/software/emacs/manual/html_node/eieio/index.html#Top">EIEIO</a> in <cite>EIEIO</cite>). In modern object-oriented parlance, this class is “abstract”, i.e. the actual class of a useful connection object is always a subclass of <code>jsonrpc-connection</code>. Nevertheless, we can define two distinct APIs around the <code>jsonrpc-connection</code> class: </p>  <ol> <li> A user interface for building JSONRPC applications      <p>In this scenario, the JSONRPC application selects a concrete subclass of <code>jsonrpc-connection</code>, and proceeds to create objects of that subclass using <code>make-instance</code>. To initiate a contact to the remote endpoint, the JSONRPC application passes this object to the functions <code>jsonrpc-notify</code>, <code>jsonrpc-request</code>, and/or <code>jsonrpc-async-request</code>. For handling remotely initiated contacts, which generally come in asynchronously, the instantiation should include <code>:request-dispatcher</code> and <code>:notification-dispatcher</code> initargs, which are both functions of 3 arguments: the connection object; a symbol naming the JSONRPC method invoked remotely; and a JSONRPC <code>params</code> object. </p>  <p>The function passed as <code>:request-dispatcher</code> is responsible for handling the remote endpoint’s requests, which expect a reply from the local endpoint (in this case, the program you’re building). Inside that function, you may either return locally (a normal return) or non-locally (an error return). A local return value must be a Lisp object that can be serialized as JSON (see <a href="parsing-json">Parsing JSON</a>). This determines a success response, and the object is forwarded to the server as the JSONRPC <code>result</code> object. A non-local return, achieved by calling the function <code>jsonrpc-error</code>, causes an error response to be sent to the server. The details of the accompanying JSONRPC <code>error</code> are filled out with whatever was passed to <code>jsonrpc-error</code>. A non-local return triggered by an unexpected error of any other type also causes an error response to be sent (unless you have set <code>debug-on-error</code>, in which case this calls the Lisp debugger, see <a href="error-debugging">Error Debugging</a>). </p> </li>
+<li> A inheritance interface for building JSONRPC transport implementations <p>In this scenario, <code>jsonrpc-connection</code> is subclassed to implement a different underlying transport strategy (for details on how to subclass, see <a href="https://www.gnu.org/software/emacs/manual/html_node/eieio/Inheritance.html#Inheritance">(eieio)Inheritance</a>.). Users of the application-building interface can then instantiate objects of this concrete class (using the <code>make-instance</code> function) and connect to JSONRPC endpoints using that strategy. </p> <p>This API has mandatory and optional parts. </p>  <p>To allow its users to initiate JSONRPC contacts (notifications or requests) or reply to endpoint requests, the subclass must have an implementation of the <code>jsonrpc-connection-send</code> method. </p>  <p>Likewise, for handling the three types of remote contacts (requests, notifications, and responses to local requests), the transport implementation must arrange for the function <code>jsonrpc-connection-receive</code> to be called after noticing a new JSONRPC message on the wire (whatever that "wire" may be). </p>   <p>Finally, and optionally, the <code>jsonrpc-connection</code> subclass should implement the <code>jsonrpc-shutdown</code> and <code>jsonrpc-running-p</code> methods if these concepts apply to the transport. If they do, then any system resources (e.g. processes, timers, etc.) used to listen for messages on the wire should be released in <code>jsonrpc-shutdown</code>, i.e. they should only be needed while <code>jsonrpc-running-p</code> is non-nil. </p> </li>
+</ol><div class="_attribution">
+  <p class="_attribution-p">
+    Copyright &copy; 1990-1996, 1998-2022 Free Software Foundation, Inc. <br>Licensed under the GNU GPL license.<br>
+    <a href="https://www.gnu.org/software/emacs/manual/html_node/elisp/JSONRPC-Overview.html" class="_attribution-link">https://www.gnu.org/software/emacs/manual/html_node/elisp/JSONRPC-Overview.html</a>
+  </p>
+</div>