X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=ovsdb%2FSPECS;h=17b0840cacc7706790be4c8f94a9fb07e1cadf9d;hb=c3e3d2a1e72f2fec8580e7974f809846788bc8ff;hp=ae4d649b664ee40c9a4b70d3b59184835578cd32;hpb=6e79e2104c95e005e81a070053a3dc99a2bfde09;p=openvswitch diff --git a/ovsdb/SPECS b/ovsdb/SPECS index ae4d649b..17b0840c 100644 --- a/ovsdb/SPECS +++ b/ovsdb/SPECS @@ -10,7 +10,8 @@ values. Additional notation is presented later. - A JSON string. + A JSON string. Any Unicode string is allowed, as specified by RFC + 4627. Implementations may disallowed null bytes. @@ -64,8 +65,8 @@ is represented by , as described below. "columns": {: , ...} required The "comment" optionally provides information about this table for - a human reader. The value of "tables" is a JSON object whose - names are table names and whose values are s. + a human reader. The value of "columns" is a JSON object whose + names are column names and whose values are s. Every table has the following columns whose definitions are not included in the schema: @@ -133,8 +134,21 @@ is represented by , as described below. Wire Protocol ------------- -The database wire protocol is implemented in JSON-RPC 1.0. It -consists of the following JSON-RPC methods: +The database wire protocol is implemented in JSON-RPC 1.0. We +encourage use of JSON-RPC over stream connections instead of JSON-RPC +over HTTP, for these reasons: + + * JSON-RPC is a peer-to-peer protocol, but HTTP is a client-server + protocol, which is a poor match. Thus, JSON-RPC over HTTP + requires the client to periodically poll the server to receive + server requests. + + * HTTP is more complicated than stream connections and doesn't + provide any corresponding advantage. + + * The JSON-RPC specification for HTTP transport is incomplete. + +The database wire protocol consists of the following JSON-RPC methods: get_schema .......... @@ -199,7 +213,7 @@ array corresponds to the same element of the "params" array. The individual operations. Some operations do not produce any results, in which case the object will have no members. - - A JSON object that contains a "error" member indicates that the + - A JSON object that contains an "error" member indicates that the operation completed with an error. The value of the "error" member is a short string, specified in this document, that broadly indicates the class of the error. Besides the ones @@ -281,6 +295,134 @@ form: The "cancel" notification itself has no reply. +monitor +....... + +Request object members: + + "method": "monitor" required + "params": [, ] required + "id": any JSON value except null required + + is an object that maps from a table name to a +. + +Each is an object with the following members: + + "columns": [*] optional + "select": optional + + is an object with the following members: + + "initial": optional + "insert": optional + "delete": optional + "modify": optional + +Response object members: + + "result": + "error": null + "id": same "id" as request + +This JSON-RPC request enables a client to replicate tables or subsets +of tables. Each specifies a table to be replicated. +The JSON-RPC response to the "monitor" includes the initial contents +of each table. Afterward, when changes to those tables are committed, +the changes are automatically sent to the client using the "update" +monitor notification. This monitoring persists until the JSON-RPC +session terminates or until the client sends a "monitor_cancel" +JSON-RPC request. + +Each describes how to monitor a table: + + The circumstances in which an "update" notification is sent for a + row within the table are determined by : + + If "initial" is omitted or true, every row in the table is + sent as part of the reply to the "monitor" request. + + If "insert" is omitted or true, "update" notifications are + sent for rows newly inserted into the table. + + If "delete" is omitted or true, "update" notifications are + sent for rows deleted from the table. + + If "modify" is omitted or true, "update" notifications are + sent whenever when a row in the table is modified. + + The "columns" member specifies the columns whose values are + monitored. If "columns" is omitted, all columns in the table, + except for "_uuid", are monitored. + +The "result" in the JSON-RPC response to the "monitor" request is a + object (see below) that contains the contents of the +tables for which "initial" rows are selected. If no tables' initial +contents are requested, then "result" is an empty object. + +update +...... + +Notification object members: + + "method": "update" + "params": [, ] + "id": null + +The in "params" is the same as the value passed as the +in "params" for the "monitor" request. + + is an object that maps from a table name to a +. + +A is an object that maps from the row's UUID (as a +36-byte string) to a object. + +A is an object with the following members: + + "old": present for "delete" and "modify" updates + "new": present for "initial", "insert", and "modify" updates + +This JSON-RPC notification is sent from the server to the client to +tell it about changes to a monitored table (or the initial state of a +modified table). Each table in which one or more rows has changed (or +whose initial view is being presented) is represented in "updates". +Each row that has changed (or whose initial view is being presented) +is represented in its as a member with its name taken +from the row's _uuid member. The corresponding value is a +: + + The "old" member is present for "delete" and "modify" updates. + For "delete" updates, each monitored column is included. For + "modify" updates, the prior value of each monitored column whose + value has changed is included (monitored columns that have not + changed are represented in "new"). + + The "new" member is present for "initial", "insert", and "modify" + updates. For "initial" and "insert" updates, each monitored + column is included. For "modify" updates, the new value of each + monitored column is included. + +monitor_cancel +.............. + +Request object members: + + "method": "monitor_cancel" required + "params": [] required + "id": any JSON value except null required + +Response object members: + + "result": {} + "error": null + "id": the request "id" member + +Cancels the ongoing table monitor request, identified by the +in "params" matching the in "params" for an ongoing "monitor" +request. No more "update" messages will be sent for this table +monitor. + echo .... @@ -369,13 +511,16 @@ Notation for the Wire Protocol A 2-element JSON array that represents the UUID of a row inserted in a previous "insert" operation within the same transaction. The first element of the array must be the string "named-uuid" and the - second element must be the string specified on a previous "insert" - operation's "uuid-name". For example, if a previous "insert" + second element must be the string specified on this "insert" + operation's "uuid-name" or on a preceding "insert" within the same + transaction. For example, if this or a previous "insert" operation specified a "uuid-name" of "myrow", the following represents the UUID created by that operation: ["named-uuid", "myrow"] + A may be used anywhere a is valid. + A 3-element JSON array of the form [, , @@ -467,9 +612,9 @@ Semantics: values. The new row receives a new, randomly generated UUID, which is - returned as the "_uuid" member of the result. If "uuid-name" - is supplied, then the UUID is made available under that name - to later operations within the same transaction. + returned as the "uuid" member of the result. If "uuid-name" is + supplied, then the UUID is made available under that name to this + operation and later operations within the same transaction. select ...... @@ -526,9 +671,9 @@ Semantics: value of each column specified in "row" to the value for that column specified in "row". - The "_uuid" and "_version" columns of a table may not be updated. - Columns designated read-only in the schema also may not be - updated. + The "_uuid" and "_version" columns of a table may not be directly + updated with this operation. Columns designated read-only in the + schema also may not be updated. The "count" member of the result specifies the number of rows that matched.