Skip to content

Commit

Permalink
[project @ Include generated documentation in repository.]
Browse files Browse the repository at this point in the history
  • Loading branch information
@tonyg
tonyg committed May 25, 2008
1 parent 16409d8 commit be901b6
Show file tree
Hide file tree
Showing 12 changed files with 1,266 additions and 0 deletions.
4 changes: 4 additions & 0 deletions doc/edoc-info
View file
@@ -0,0 +1,4 @@
{application,rfc4627}.
{packages,[]}.
{modules,[rfc4627,rfc4627_jsonrpc,rfc4627_jsonrpc_http,
rfc4627_jsonrpc_inets]}.
Binary file added doc/erlang.png
View file
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
17 changes: 17 additions & 0 deletions doc/index.html
View file
@@ -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>
15 changes: 15 additions & 0 deletions doc/modules-frame.html
View file
@@ -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>
124 changes: 124 additions & 0 deletions doc/overview-summary.html
View file
@@ -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>
117 changes: 117 additions & 0 deletions doc/overview.edoc
View file
@@ -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.)
11 changes: 11 additions & 0 deletions doc/packages-frame.html
View file
@@ -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>

0 comments on commit be901b6

Please sign in to comment.