OLD | NEW |
---|---|
(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 | |
OLD | NEW |