Permalink
Browse files

[project @ Include generated documentation in repository.]

  • Loading branch information...
1 parent 16409d8 commit be901b6b64d74701c99d28f9a62ab27000da8187 @tonyg committed May 25, 2008
View
@@ -0,0 +1,4 @@
+{application,rfc4627}.
+{packages,[]}.
+{modules,[rfc4627,rfc4627_jsonrpc,rfc4627_jsonrpc_http,
+ rfc4627_jsonrpc_inets]}.
View
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
View
@@ -0,0 +1,17 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<title>The rfc4627 application</title>
+</head>
+<frameset cols="20%,80%">
+<frame src="modules-frame.html" name="modulesFrame" title="">
+
+<frame src="overview-summary.html" name="overviewFrame" title="">
+<noframes>
+<h2>This page uses frames</h2>
+<p>Your browser does not accept frames.
+<br>You should go to the <a href="overview-summary.html">non-frame version</a> instead.
+</p>
+</noframes>
+</frameset>
+</html>
View
@@ -0,0 +1,15 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<title>The rfc4627 application</title>
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
+</head>
+<body bgcolor="white">
+<h2 class="indextitle">Modules</h2>
+<table width="100%" border="0" summary="list of modules">
+<tr><td><a href="rfc4627.html" target="overviewFrame" class="module">rfc4627</a></td></tr>
+<tr><td><a href="rfc4627_jsonrpc.html" target="overviewFrame" class="module">rfc4627_jsonrpc</a></td></tr>
+<tr><td><a href="rfc4627_jsonrpc_http.html" target="overviewFrame" class="module">rfc4627_jsonrpc_http</a></td></tr>
+<tr><td><a href="rfc4627_jsonrpc_inets.html" target="overviewFrame" class="module">rfc4627_jsonrpc_inets</a></td></tr></table>
+</body>
+</html>
View
@@ -0,0 +1,124 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<title>RFC4627 (JSON) and JSON-RPC for Erlang</title>
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
+</head>
+<body bgcolor="white">
+<div class="navbar"><a name="#navbar_top"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
+<h1>RFC4627 (JSON) and JSON-RPC for Erlang</h1>
+<p>Copyright © 2007, 2008 Tony Garnock-Jones and LShift Ltd.
+</p>
+<p><b>Version:</b> 1.2.0
+</p>
+<p><b>Authors:</b> Tony Garnock-Jones (<a href="mailto:tonyg@lshift.net"><tt>tonyg@lshift.net</tt></a>), LShift Ltd. (<a href="mailto:query@lshift.net"><tt>query@lshift.net</tt></a>).</p>
+<p><b>References</b><ul><li><a href="http://www.ietf.org/rfc/rfc4627.txt">RFC 4627</a>,
+the JSON RFC
+</li><li>The <a href="http://json-rpc.org/wd/JSON-RPC-1-1-WD-20060807.html">JSON-RPC
+specification</a> 1.1 working draft.
+</li></ul></p>
+<p>An implementation of JSON and JSON-RPC for Erlang.</p>
+
+<p>See <a href="rfc4627.html"><code>rfc4627</code></a>, the JSON/RFC4627 codec itself, to learn how to
+encode and decode JSON objects from Erlang code.</p>
+
+<h3><a name="Providing_and_calling_JSON-RPC_services">Providing and calling JSON-RPC services</a></h3>
+
+<p>See <a href="rfc4627_jsonrpc.html"><code>rfc4627_jsonrpc</code></a>, a JSON-RPC service registry and
+transport-neutral service method invocation mechanism, to learn how to
+expose Erlang processes as remotely-callable JSON-RPC services, and to
+learn how to invoke local JSON-RPC services from Erlang without the
+overhead of HTTP.</p>
+
+<h3><a name="Exposing_JSON-RPC_services_over_HTTP_using_Inets">Exposing JSON-RPC services over HTTP using Inets</a></h3>
+
+<p>See <a href="rfc4627_jsonrpc_inets.html"><code>rfc4627_jsonrpc_inets</code></a>, an Inets HTTP transport binding for
+JSON-RPC, to learn how to configure the Inets HTTP server to respond
+to JSON-RPC requests.</p>
+
+<h3><a name="Running_the_example_test_service_that_comes_with_the_source_code">Running the example test service that comes with the source code</a></h3>
+
+<p>Included with the Erlang RFC4627 source code is a small Inets-based
+example that defines a "hello world"-style JSON-RPC service, and calls
+it from a Javascript program embedded in a web page.</p>
+
+<p>At your Erlang shell,</p>
+
+<ul>
+<li>after compiling the code with "<code>make all test-compile</code>",</li>
+<li>when your current working directory contains the "test" directory
+from the distribution, such that "test/server_root/conf/httpd.conf"
+exists,</li>
+</ul>
+
+<p>type <code>test_jsonrpc_inets:start_httpd()</code>. This will</p>
+
+<ul>
+<li>start the inets httpd on port 5671 (from test/server_root/conf/httpd.conf)</li>
+<li>allow HTTP access to JSON-RPC services via a url prefix of "/rpc" (again from httpd.conf)</li>
+<li>start the <code>rfc4627_jsonrpc</code> service registry</li>
+<li>register the test service</li>
+</ul>
+
+<p>Visiting <a href="http://localhost:5671/" target="_top"><tt>http://localhost:5671/</tt></a> in your browser should load a page
+that uses javascript to invoke the Erlang-implemented JSON-RPC test
+service.</p>
+
+<h3><a name="Invoking_JSON-RPC_procedures_from_Javascript">Invoking JSON-RPC procedures from Javascript</a></h3>
+
+<p>Once <a href="rfc4627_jsonrpc_inets.html"><code>rfc4627_jsonrpc_inets</code></a> is configured as part of a running
+inets httpd, services can be accessed via HTTP POST and
+(conditionally) HTTP GET. This distribution includes Javascript code
+for invoking JSON-RPC services from within a web browser:</p>
+
+<ul>
+ <li><a href="../test/server_root/htdocs/json.js">json.js</a>: a slightly modified version of the original json.org Javascript JSON codec</li>
+ <li><a href="../test/server_root/htdocs/jsonrpc.js">jsonrpc.js</a>: classes for XmlHttpRequest-based JSON-RPC service access</li>
+ <li><a href="../test/server_root/htdocs/prototype-1.4.0.js">prototype-1.4.0.js</a>: provides cross-browser XmlHttpRequest implementation, as well as many very useful utilities and a framework for class-based programming in Javascript</li>
+ <li><a href="../test/server_root/htdocs/test-client.js">test-client.js</a>: running-example javascript client code</li>
+ <li><a href="../test/server_root/htdocs/index.html">index.html</a>: loads and runs the running-example client</li>
+</ul>
+
+<p>The main class for JSON-RPC service access is jsonrpc.js's <code>JsonRpcService</code> class.</p>
+
+<pre>var serviceName = "test"; // or whatever your service is registered as
+var locationBase = document.location; // e.g. "http://localhost:5671/"
+var jsonRpcPrefix = "rpc/"; // or as configured in your httpd.conf
+
+var testService = new JsonRpcService(locationBase + jsonRpcPrefix + serviceName, onReady);
+
+function onReady() {
+ // callback invoked when the service is opened and ready for requests
+ testService.test_proc("Hello, world!").addCallback(process_reply);
+ function process_reply(reply) {
+ // ...
+ }
+}</pre>
+
+<p>When an instance of <code>JsonRpcService</code> is constructed, it immediately
+calls the <code>system.describe</code> method of the service. When the result
+arrives, it uses the service description to add methods for each
+available service procedure to itself (see <code>installGenericProxy</code> in
+jsonrpc.js), and then calls the <code>onReady</code> callback supplied to the
+constructor to indicate that it is ready to process requests.</p>
+
+<p>Javascript's network primitives force you to work in
+continuation-passing-style. Every service procedure available on a
+<code>JsonRpcService</code> instance is asynchronous: calling one returns an
+instance of <code>JsonRpcTransaction</code>. The <code>addCallback</code> method of
+<code>JsonRpcTransaction</code> can be used to add a handler for processing the
+result of a JSON-RPC service request. The <code>addErrorCallback</code> is used
+to catch notifications of error responses to a JSON-RPC service
+request.</p>
+
+<pre>myService.myServiceProcedure(arg).addCallback(myReplyHandler).addErrorCallback(myErrorHandler);</pre>
+
+(note that <code>addCallback</code> and <code>addErrorCallback</code> return the
+<code>JsonRpcTransaction</code> object for convenience, to allow chaining as seen
+above.)
+
+<hr>
+<div class="navbar"><a name="#navbar_bottom"></a><table width="100%" border="0" cellspacing="0" cellpadding="2" summary="navigation bar"><tr><td><a href="overview-summary.html" target="overviewFrame">Overview</a></td><td><a href="http://www.erlang.org/"><img src="erlang.png" align="right" border="0" alt="erlang logo"></a></td></tr></table></div>
+<p><i>Generated by EDoc, May 25 2008, 18:06:25.</i></p>
+</body>
+</html>
View
@@ -0,0 +1,117 @@
+@title RFC4627 (JSON) and JSON-RPC for Erlang
+@author Tony Garnock-Jones <tonyg@lshift.net>
+@author LShift Ltd. <query@lshift.net>
+@copyright 2007, 2008 Tony Garnock-Jones and LShift Ltd.
+
+@version 1.2.0
+
+@reference <a href="http://www.ietf.org/rfc/rfc4627.txt">RFC 4627</a>,
+the JSON RFC
+
+@reference The <a
+href="http://json-rpc.org/wd/JSON-RPC-1-1-WD-20060807.html">JSON-RPC
+specification</a> 1.1 working draft.
+
+@doc <p>An implementation of JSON and JSON-RPC for Erlang.</p>
+
+See {@link rfc4627}, the JSON/RFC4627 codec itself, to learn how to
+encode and decode JSON objects from Erlang code.
+
+== Providing and calling JSON-RPC services ==
+
+See {@link rfc4627_jsonrpc}, a JSON-RPC service registry and
+transport-neutral service method invocation mechanism, to learn how to
+expose Erlang processes as remotely-callable JSON-RPC services, and to
+learn how to invoke local JSON-RPC services from Erlang without the
+overhead of HTTP.
+
+== Exposing JSON-RPC services over HTTP using Inets ==
+
+See {@link rfc4627_jsonrpc_inets}, an Inets HTTP transport binding for
+JSON-RPC, to learn how to configure the Inets HTTP server to respond
+to JSON-RPC requests.
+
+== Running the example test service that comes with the source code ==
+
+Included with the Erlang RFC4627 source code is a small Inets-based
+example that defines a "hello world"-style JSON-RPC service, and calls
+it from a Javascript program embedded in a web page.
+
+At your Erlang shell,
+
+<ul>
+<li>after compiling the code with "`make all test-compile'",</li>
+<li>when your current working directory contains the "test" directory
+from the distribution, such that "test/server_root/conf/httpd.conf"
+exists,</li>
+</ul>
+
+type `test_jsonrpc_inets:start_httpd()'. This will
+
+<ul>
+<li>start the inets httpd on port 5671 (from test/server_root/conf/httpd.conf)</li>
+<li>allow HTTP access to JSON-RPC services via a url prefix of "/rpc" (again from httpd.conf)</li>
+<li>start the `rfc4627_jsonrpc' service registry</li>
+<li>register the test service</li>
+</ul>
+
+Visiting [http://localhost:5671/] in your browser should load a page
+that uses javascript to invoke the Erlang-implemented JSON-RPC test
+service.
+
+== Invoking JSON-RPC procedures from Javascript ==
+
+Once {@link rfc4627_jsonrpc_inets} is configured as part of a running
+inets httpd, services can be accessed via HTTP POST and
+(conditionally) HTTP GET. This distribution includes Javascript code
+for invoking JSON-RPC services from within a web browser:
+
+<ul>
+ <li><a href="../test/server_root/htdocs/json.js">json.js</a>: a slightly modified version of the original json.org Javascript JSON codec</li>
+ <li><a href="../test/server_root/htdocs/jsonrpc.js">jsonrpc.js</a>: classes for XmlHttpRequest-based JSON-RPC service access</li>
+ <li><a href="../test/server_root/htdocs/prototype-1.4.0.js">prototype-1.4.0.js</a>: provides cross-browser XmlHttpRequest implementation, as well as many very useful utilities and a framework for class-based programming in Javascript</li>
+ <li><a href="../test/server_root/htdocs/test-client.js">test-client.js</a>: running-example javascript client code</li>
+ <li><a href="../test/server_root/htdocs/index.html">index.html</a>: loads and runs the running-example client</li>
+</ul>
+
+The main class for JSON-RPC service access is jsonrpc.js's `JsonRpcService' class.
+
+```
+var serviceName = "test"; // or whatever your service is registered as
+var locationBase = document.location; // e.g. "http://localhost:5671/"
+var jsonRpcPrefix = "rpc/"; // or as configured in your httpd.conf
+
+var testService = new JsonRpcService(locationBase + jsonRpcPrefix + serviceName, onReady);
+
+function onReady() {
+ // callback invoked when the service is opened and ready for requests
+ testService.test_proc("Hello, world!").addCallback(process_reply);
+ function process_reply(reply) {
+ // ...
+ }
+}
+'''
+
+When an instance of `JsonRpcService' is constructed, it immediately
+calls the `system.describe' method of the service. When the result
+arrives, it uses the service description to add methods for each
+available service procedure to itself (see `installGenericProxy' in
+jsonrpc.js), and then calls the `onReady' callback supplied to the
+constructor to indicate that it is ready to process requests.
+
+Javascript's network primitives force you to work in
+continuation-passing-style. Every service procedure available on a
+`JsonRpcService' instance is asynchronous: calling one returns an
+instance of `JsonRpcTransaction'. The `addCallback' method of
+`JsonRpcTransaction' can be used to add a handler for processing the
+result of a JSON-RPC service request. The `addErrorCallback' is used
+to catch notifications of error responses to a JSON-RPC service
+request.
+
+```
+myService.myServiceProcedure(arg).addCallback(myReplyHandler).addErrorCallback(myErrorHandler);
+'''
+
+(note that `addCallback' and `addErrorCallback' return the
+`JsonRpcTransaction' object for convenience, to allow chaining as seen
+above.)
View
@@ -0,0 +1,11 @@
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
+<html>
+<head>
+<title>The rfc4627 application</title>
+<link rel="stylesheet" type="text/css" href="stylesheet.css" title="EDoc">
+</head>
+<body bgcolor="white">
+<h2 class="indextitle">Packages</h2>
+<table width="100%" border="0" summary="list of packages"></table>
+</body>
+</html>
Oops, something went wrong.

0 comments on commit be901b6

Please sign in to comment.