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

Side by Side Diff: README.md

Issue 1652413002: Use StreamChannel. (Closed) Base URL: git@github.com:dart-lang/json_rpc_2.git@master
Patch Set: Code review changes Created 4 years, 10 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
« no previous file with comments | « CHANGELOG.md ('k') | lib/src/channel_manager.dart » ('j') | no next file with comments »
Toggle Intra-line Diffs ('i') | Expand Comments ('e') | Collapse Comments ('c') | Show Comments Hide Comments ('s')
OLDNEW
1 A library that implements the [JSON-RPC 2.0 spec][spec]. 1 A library that implements the [JSON-RPC 2.0 spec][spec].
2 2
3 [spec]: http://www.jsonrpc.org/specification 3 [spec]: http://www.jsonrpc.org/specification
4 4
5 ## Server 5 ## Server
6 6
7 A JSON-RPC 2.0 server exposes a set of methods that can be called by clients. 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`: 8 These methods can be registered using `Server.registerMethod`:
9 9
10 ```dart 10 ```dart
11 import "package:json_rpc_2/json_rpc_2.dart" as json_rpc; 11 import "package:json_rpc_2/json_rpc_2.dart" as json_rpc;
12 import "package:stream_channel/stream_channel.dart";
12 13
13 void main() { 14 main() async {
14 WebSocket.connect('ws://localhost:4321').then((socket) { 15 var socket = await WebSocket.connect('ws://localhost:4321');
15 // You can start the server with a Stream for requests and a StreamSink for 16 var server = new json_rpc.Server(new StreamChannel(socket, socket));
16 // responses, or with an object that's both, like a WebSocket.
17 var server = new json_rpc.Server(socket);
18 17
19 // Any string may be used as a method name. JSON-RPC 2.0 methods are 18 // Any string may be used as a method name. JSON-RPC 2.0 methods are
20 // case-sensitive. 19 // case-sensitive.
21 var i = 0; 20 var i = 0;
22 server.registerMethod("count", () { 21 server.registerMethod("count", () {
23 // Just return the value to be sent as a response to the client. This can 22 // Just return the value to be sent as a response to the client. This can
24 // be anything JSON-serializable, or a Future that completes to something 23 // be anything JSON-serializable, or a Future that completes to something
25 // JSON-serializable. 24 // JSON-serializable.
26 return i++; 25 return i++;
27 }); 26 });
28 27
29 // Methods can take parameters. They're presented as a [Parameters] object 28 // Methods can take parameters. They're presented as a [Parameters] object
30 // which makes it easy to validate that the expected parameters exist. 29 // which makes it easy to validate that the expected parameters exist.
31 server.registerMethod("echo", (params) { 30 server.registerMethod("echo", (params) {
32 // If the request doesn't have a "message" parameter, this will 31 // If the request doesn't have a "message" parameter, this will
33 // automatically send a response notifying the client that the request 32 // automatically send a response notifying the client that the request
34 // was invalid. 33 // was invalid.
35 return params.getNamed("message"); 34 return params.getNamed("message");
36 }); 35 });
37 36
38 // [Parameters] has methods for verifying argument types. 37 // [Parameters] has methods for verifying argument types.
39 server.registerMethod("subtract", (params) { 38 server.registerMethod("subtract", (params) {
40 // If "minuend" or "subtrahend" aren't numbers, this will reject the 39 // If "minuend" or "subtrahend" aren't numbers, this will reject the
41 // request. 40 // request.
42 return params.getNum("minuend") - params.getNum("subtrahend"); 41 return params.getNum("minuend") - params.getNum("subtrahend");
43 }); 42 });
44 43
45 // [Parameters] also supports optional arguments. 44 // [Parameters] also supports optional arguments.
46 server.registerMethod("sort", (params) { 45 server.registerMethod("sort", (params) {
47 var list = params.getList("list"); 46 var list = params.getList("list");
48 list.sort(); 47 list.sort();
49 if (params.getBool("descending", orElse: () => false)) { 48 if (params.getBool("descending", orElse: () => false)) {
50 return params.list.reversed; 49 return params.list.reversed;
51 } else { 50 } else {
52 return params.list; 51 return params.list;
53 } 52 }
54 }); 53 });
55 54
56 // A method can send an error response by throwing a 55 // A method can send an error response by throwing a
57 // `json_rpc.RpcException`. Any positive number may be used as an 56 // `json_rpc.RpcException`. Any positive number may be used as an
58 // application- defined error code. 57 // application- defined error code.
59 const DIVIDE_BY_ZERO = 1; 58 const DIVIDE_BY_ZERO = 1;
60 server.registerMethod("divide", (params) { 59 server.registerMethod("divide", (params) {
61 var divisor = params.getNum("divisor"); 60 var divisor = params.getNum("divisor");
62 if (divisor == 0) { 61 if (divisor == 0) {
63 throw new json_rpc.RpcException( 62 throw new json_rpc.RpcException(
64 DIVIDE_BY_ZERO, "Cannot divide by zero."); 63 DIVIDE_BY_ZERO, "Cannot divide by zero.");
65 } 64 }
66 65
67 return params.getNum("dividend") / divisor; 66 return params.getNum("dividend") / divisor;
68 }); 67 });
69 68
70 // To give you time to register all your methods, the server won't actually 69 // To give you time to register all your methods, the server won't actually
71 // start listening for requests until you call `listen`. 70 // start listening for requests until you call `listen`.
72 server.listen(); 71 server.listen();
73 });
74 } 72 }
75 ``` 73 ```
76 74
77 ## Client 75 ## Client
78 76
79 A JSON-RPC 2.0 client calls methods on a server and handles the server's 77 A JSON-RPC 2.0 client calls methods on a server and handles the server's
80 responses to those method calls. These methods can be called using 78 responses to those method calls. These methods can be called using
81 `Client.sendRequest`: 79 `Client.sendRequest`:
82 80
83 ```dart 81 ```dart
84 import "package:json_rpc_2/json_rpc_2.dart" as json_rpc; 82 import "package:json_rpc_2/json_rpc_2.dart" as json_rpc;
83 import "package:stream_channel/stream_channel.dart";
85 84
86 void main() { 85 main() async {
87 WebSocket.connect('ws://localhost:4321').then((socket) { 86 var socket = await WebSocket.connect('ws://localhost:4321');
88 // Just like the server, a client takes a Stream and a StreamSink or a 87 var client = new json_rpc.Client(new StreamChannel(socket, socket));
89 // single object that's both.
90 var client = new json_rpc.Client(socket);
91 88
92 // This calls the "count" method on the server. A Future is returned that 89 // This calls the "count" method on the server. A Future is returned that
93 // will complete to the value contained in the server's response. 90 // will complete to the value contained in the server's response.
94 client.sendRequest("count").then((result) => print("Count is $result.")); 91 client.sendRequest("count").then((result) => print("Count is $result."));
95 92
96 // Parameters are passed as a simple Map or, for positional parameters, an 93 // Parameters are passed as a simple Map or, for positional parameters, an
97 // Iterable. Make sure they're JSON-serializable! 94 // Iterable. Make sure they're JSON-serializable!
98 client.sendRequest("echo", {"message": "hello"}) 95 client.sendRequest("echo", {"message": "hello"})
99 .then((echo) => print('Echo says "$echo"!')); 96 .then((echo) => print('Echo says "$echo"!'));
100 97
101 // A notification is a way to call a method that tells the server that no 98 // A notification is a way to call a method that tells the server that no
102 // result is expected. Its return type is `void`; even if it causes an 99 // result is expected. Its return type is `void`; even if it causes an
103 // error, you won't hear back. 100 // error, you won't hear back.
104 client.sendNotification("count"); 101 client.sendNotification("count");
105 102
106 // If the server sends an error response, the returned Future will complete 103 // If the server sends an error response, the returned Future will complete
107 // with an RpcException. You can catch this error and inspect its error 104 // with an RpcException. You can catch this error and inspect its error
108 // code, message, and any data that the server sent along with it. 105 // code, message, and any data that the server sent along with it.
109 client.sendRequest("divide", {"dividend": 2, "divisor": 0}) 106 client.sendRequest("divide", {"dividend": 2, "divisor": 0})
110 .catchError((error) { 107 .catchError((error) {
111 print("RPC error ${error.code}: ${error.message}"); 108 print("RPC error ${error.code}: ${error.message}");
112 }); 109 });
113 110
114 // The client won't subscribe to the input stream until you call `listen`. 111 // The client won't subscribe to the input stream until you call `listen`.
115 client.listen(); 112 client.listen();
116 });
117 } 113 }
118 ``` 114 ```
119 115
120 ## Peer 116 ## Peer
121 117
122 Although JSON-RPC 2.0 only explicitly describes clients and servers, it also 118 Although JSON-RPC 2.0 only explicitly describes clients and servers, it also
123 mentions that two-way communication can be supported by making each endpoint 119 mentions that two-way communication can be supported by making each endpoint
124 both a client and a server. This package supports this directly using the `Peer` 120 both a client and a server. This package supports this directly using the `Peer`
125 class, which implements both `Client` and `Server`. It supports the same methods 121 class, which implements both `Client` and `Server`. It supports the same methods
126 as those classes, and automatically makes sure that every message from the other 122 as those classes, and automatically makes sure that every message from the other
127 endpoint is routed and handled correctly. 123 endpoint is routed and handled correctly.
OLDNEW
« no previous file with comments | « CHANGELOG.md ('k') | lib/src/channel_manager.dart » ('j') | no next file with comments »

Powered by Google App Engine
This is Rietveld 408576698