Chromium Code Reviews
chromiumcodereview-hr@appspot.gserviceaccount.com (chromiumcodereview-hr) | Please choose your nickname with Settings | Help | Chromium Project | Gerrit Changes | Sign out
(142)

Side by Side Diff: pkg/json_rpc_2/README.md

Issue 205533005: Create a package that implements a JSON-RPC 2.0 server. (Closed) Base URL: https://dart.googlecode.com/svn/branches/bleeding_edge/dart
Patch Set: Created 6 years, 9 months ago
Use n/p to move between diff chunks; N/P to move between comments. Draft comments are only viewable by you.
Jump to:
View unified diff | Download patch | Annotate | Revision Log
OLDNEW
(Empty)
1 A library that implements the [JSON-RPC 2.0 spec][spec].
2
3 [spec]: http://www.jsonrpc.org/specification
4
5 ## Server
6
7 A JSON-RPC 2.0 server exposes a set of methods that can be called by clients.
8 These methods can be registered using `Server.registerMethod`:
9
10 ```dart
11 import "package:json_rpc_2/json_rpc_2.dart" as json_rpc;
12
13 var server = new json_rpc.Server();
14
15 // Any string may be used as a method name. JSON-RPC 2.0 methods are
16 // case-sensitive.
17 var i = 0;
18 server.registerMethod("count", () {
19 // Just return the value to be sent as a response to the client. This can be
20 // anything JSON-serializable, or a Future that completes to something
21 // JSON-serializable.
22 return i++;
23 });
24
25 // Methods can take parameters. They're presented as a [Parameters] object which
26 // makes it easy to validate that the expected parameters exist.
27 server.registerMethod("echo", (params) {
28 // If the request doesn't have a "message" parameter, this will automatically
29 // send a response notifying the client that the request was invalid.
30 return params.getNamed("message");
31 });
32
33 // [Parameters] has methods for verifying argument types.
34 server.registerMethod("subtract", (params) {
35 // If "minuend" or "subtrahend" aren't numbers, this will reject the request.
36 return params.getNum("minuend") - params.getNum("subtrahend");
37 });
38
39 // [Parameters] also supports optional arguments.
40 server.registerMethod("sort", (params) {
41 var list = params.getList("list");
42 list.sort();
43 if (params.getBool("descending", orElse: () => false)) {
44 return params.list.reversed;
45 } else {
46 return params.list;
47 }
48 });
49
50 // A method can send an error response by throwing a `json_rpc.RpcException`.
51 // Any positive number may be used as an application-defined error code.
52 const DIVIDE_BY_ZERO = 1;
53 server.registerMethod("divide", (params) {
54 var divisor = params.getNum("divisor");
55 if (divisor == 0) {
56 throw new json_rpc.RpcException(DIVIDE_BY_ZERO, "Cannot divide by zero.");
57 }
58
59 return params.getNum("dividend") / divisor;
60 });
61 ```
62
63 Once you've registered your methods, you can handle requests with
64 `Server.parseRequest`:
Bob Nystrom 2014/03/20 18:25:58 How about "handleRequest" since this is the common
nweiz 2014/03/20 22:55:41 I like [parseRequest] -- it's shorter and conveys
65
66 ```dart
67 import 'dart:io';
68
69 WebSocket.connect('ws://localhost:4321').then((socket) {
70 socket.listen((message) {
71 server.parseRequest(message).then((response) {
72 if (response != null) socket.add(response);
73 });
74 });
75 });
76 ```
77
78 If you're communicating with objects that haven't been serialized to a string,
79 you can also call `Server.handleRequest` directly:
Bob Nystrom 2014/03/20 18:25:58 And then maybe make this "handleMessage" or "handl
nweiz 2014/03/20 22:55:41 See above.
80
81 ```dart
82 import 'dart:isolate';
83
84 var receive = new ReceivePort();
85 Isolate.spawnUri('path/to/client.dart', [], receive.sendPort).then((_) {
86 receive.listen((message) {
87 server.handleRequest(message['request']).then((response) {
88 if (response != null) message['respond'].send(response);
89 });
90 });
91 })
92 ```
93
94 ## Client
95
96 Currently this package does not contain an implementation of a JSON-RPC 2.0
97 client.
98
OLDNEW

Powered by Google App Engine
This is Rietveld 408576698