Permalink
Browse files

Updates to examples in README.md.

  • Loading branch information...
1 parent 8e36ee0 commit 2a20d290875f70139fd9914c44dc3a5bb5940691 @tedeh committed Jun 30, 2012
Showing with 48 additions and 37 deletions.
  1. +48 −37 README.md
View
85 README.md
@@ -1,6 +1,6 @@
# Jayson
-Jayson is a [JSON-RPC 2.0 compliant][jsonrpc-spec] server and client written in [nodejs/javascript][node.js] that wants to be as simple as possible to use.
+Jayson is a [JSON-RPC 2.0][jsonrpc-spec] compliant server and client written in JavaScript for [node.js][node.js] that wants to be as simple as possible to use.
[jsonrpc-spec]: http://jsonrpc.org/spec.html
[node.js]: http://nodejs.org/
@@ -13,15 +13,16 @@ Jayson is a [JSON-RPC 2.0 compliant][jsonrpc-spec] server and client written in
* Automatic request relaying to other servers
* Simple process forking for expensive computations
* JSON Reviving and Replacing for advanced (de)serialization of objects
-* Fully tested to comply with the [official specification][jsonrpc-spec]
+* Extensively tested to comply with the [official specification][jsonrpc-spec]
## Example
-A very basic JSON-RPC 2.0 server via HTTP:
+A basic JSON-RPC 2.0 server via HTTP:
+
+Server in `examples/simple_example/server.js`:
```javascript
-// server.js
-var jayson = require('jayson');
+var jayson = require(__dirname + '/../..');
// create a server
var server = jayson.server({
@@ -34,11 +35,10 @@ var server = jayson.server({
server.http().listen(3000);
```
-A client invoking `add` on the above server:
+Client in `examples/simple_example/client.js` invoking `add` on the above server:
```javascript
-// client.js
-var jayson = require('jayson');
+var jayson = require(__dirname + '/../..');
// create a client
var client = jayson.client.http({
@@ -64,7 +64,11 @@ Jayson does not have any special dependencies that cannot be resolved with a sim
- node.js v0.6.x
- node.js v0.8.x
-### Running tests
+## Class documentation
+
+In addition to this document, a comprehensive class documentation is available at [jayson.tedeh.net](http://jayson.tedeh.net).
+
+## Running tests
- Change directory to the repository root
- Install the testing framework
@@ -82,21 +86,19 @@ The client is available as the `Client` or `client` property of `require('jayson
#### Interfaces
* `Client` Base class for interfacing with a server.
-* `Client.http` HTTP interface. See [http.request][nodejs_doc_http_request] for supported options.
+* `Client.http` HTTP interface.
* `Client.fork` Node.js child_process/fork interface.
* `Client.jquery` Wrapper around `jQuery.ajax`.
-[nodejs_doc_http_request]: http://nodejs.org/docs/v0.6.19/api/http.html#http_http_request_options_callback
-
#### Notifications
Notification requests are for cases where the reply from the server is not important and should be ignored. This is accomplished by setting the `id` property of a request object to `null`.
-A client doing a notification request:
+Client in `examples/notifications/client.js` doing a notification request:
```javascript
-// client.js
-var jayson = require('jayson');
+var jayson = require(__dirname + '/../..');
+
var client = jayson.client.http({
host: 'localhost',
port: 3000
@@ -108,11 +110,10 @@ client.request('ping', [], null, function(err) {
// request was received successfully
});
```
-A server:
+A server in `examples/notifications/server.js`:
```javascript
-// server.js
-var jayson = require('jayson');
+var jayson = require(__dirname + '/../..');
var server = jayson.server({
ping: function(callback) {
@@ -127,7 +128,7 @@ server.http().listen(3000);
##### Notes
* Any value that the server returns will be discarded when doing a notification request.
-* Omitting the third argument `null` to `client.prototype.request` does not generate a notification request. This argument has to be set explicitly to `null` for this to happen.
+* Omitting the third argument `null` to `Client.prototype.request` does not generate a notification request. This argument has to be set explicitly to `null` for this to happen.
* Network errors and the like will still reach the callback. When the callback is invoked (with or without error) one can be certain that the server has received the request.
* See the [Official JSON-RPC 2.0 Specification][jsonrpc-spec] for additional information on how Jayson handles notifications that are erroneous.
@@ -232,38 +233,43 @@ The server also sports several interfaces that can be accessed as properties of
A Jayson server can use many interfaces at the same time.
-Example of a server that listens to both `http` and a `https` requests:
+Server in `examples/many_interfaces/server.js` that listens to both `http` and a `https` requests:
```javascript
-var jayson = require('jayson');
+var jayson = require(__dirname + '/../..');
var server = jayson.server({
- add: function(a, b, callback) { return callback(null, a + b); }
+ add: function(a, b, callback) {
+ return callback(null, a + b);
+ }
});
-// http is now an instance of require('http').Server
+// "http" will be an instance of require('http').Server
var http = server.http();
-// https is now an instance of require('https').Server
+// "https" will be an instance of require('https').Server
var https = server.https({
- cert: require('fs').readFileSync('cert.pem'),
- key require('fs').readFileSync('key.pem')
+ //cert: require('fs').readFileSync('cert.pem'),
+ //key require('fs').readFileSync('key.pem')
});
-http.listen(80); // let http listen to localhost:3000
+http.listen(80, function() {
+ console.log('Listening on *:80')
+});
-https.listen(443); // let https listen to localhost:443
+https.listen(443, function() {
+ console.log('Listening on *:443')
+});
```
#### Using the server as a relay
Passing an instance of a client as a method to the server makes the server relay incoming requests to wherever the client is pointing to. This might be used to delegate computationally expensive functions into a separate fork/server or to abstract a cluster of servers behind a common interface.
-Public server listening on *:3000 in `examples/relay/server_public.js`
+Public server in `examples/relay/server_public.js` listening on *:3000:
```javascript
-// server_public.js
-var jayson = require('jayson');
+var jayson = require(__dirname + '/../..');
// create a server where "add" will relay a localhost-only server
var server = jayson.server({
@@ -274,14 +280,15 @@ var server = jayson.server({
});
// let the server listen to *:3000
-server.http().listen(3000, '0.0.0.0');
+server.http().listen(3000, function() {
+ console.log('Listening on *:3000');
+});
```
-Private server listening on localhost:3001 in `examples/relay/server_private.js`
+Private server in `examples/relay/server_private.js` listening on localhost:3001:
```javascript
-// server_private.js
-var jayson = require('jayson');
+var jayson = require(__dirname + '/../..');
var server = jayson.server({
add: function(a, b, callback) {
@@ -290,7 +297,9 @@ var server = jayson.server({
});
// let the private server listen to localhost:3001
-server.http().listen(3001);
+server.http().listen(3001, '127.0.0.1', function() {
+ console.log('Listening on 127.0.0.1:3001');
+});
```
Every request to `add` on the public server will now relay the request to the private server. See the client example in `examples/relay/client.js`.
@@ -457,5 +466,7 @@ requests on [Github](https://github.com/tedeh/jayson) is most welcome.
### TODO
-* `jayson.Server.fork.deferred` - Deferred forking for those _really_ expensive/memory intensive calculations
+* `jayson.Server.fork.deferred` - Deferred forking that only spawns on demand
* Streaming
+* Middleware-like support for defining server methods
+* Integration with the Cluster API

0 comments on commit 2a20d29

Please sign in to comment.