X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=ovsdb%2FSPECS;h=93db15d4cc41191c75af22688ff69cef252db0a4;hb=77ce847d0be64ac3781ac112044dde5ddcbc30bf;hp=12d97682a836ebf61d0a8b320b31de7c929109c8;hpb=f85f8ebbfac946c19b3c6eb0f4170f579d0a4d25;p=openvswitch diff --git a/ovsdb/SPECS b/ovsdb/SPECS index 12d97682..93db15d4 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. @@ -32,6 +33,10 @@ values. Additional notation is presented later. A JSON number with an integer value, within a certain range (currently -2**63...+2**63-1). + + + Any JSON value. + Schema Format ------------- @@ -60,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: @@ -129,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 .......... @@ -195,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 @@ -255,7 +273,7 @@ cancel Request object members: "method": "cancel" required - "params": the "id" for an outstanding request required + "params": [the "id" for an outstanding request] required "id": null required Response object members: @@ -277,6 +295,156 @@ 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 +.... + +Request object members: + + "method": "echo" required + "params": JSON array with any contents required + "id": required + +Response object members: + + "result": same as "params" + "error": null + "id": the request "id" member + +Both the JSON-RPC client and the server must implement this request. + +This JSON-RPC request and response can be used to implement connection +keepalives, by allowing the server to check that the client is still +there or vice versa. + + Notation for the Wire Protocol ------------------------------ @@ -343,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 [, , @@ -428,7 +599,7 @@ Request object members: "op": "insert" required "table": required "row": required - "uuid-name": optional + "uuid-name": optional Result object members: @@ -440,10 +611,31 @@ Semantics: for all the columns in "table", those columns receive default 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. + If "uuid-name" is not supplied, the new row receives a new, + randomly generated UUID. + + If "uuid-name" is supplied, then it is an error if has + previously appeared as the "uuid-name" in an "insert" operation. + + If "uuid-name" is supplied and its previously appeared as the + "uuid-name" in a "declare" operation, then the new row receives + the UUID associated with that "uuid-name". + + If "uuid-name" is supplied and its has not previously + appeared as the "uuid-name" in a "declare" operation, then the new + row also receives a new, randomly generated UUID. This UUID is + also made available under that name to this operation and later + operations within the same transaction. + + The UUID for the new row is returned as the "uuid" member of the + result. + +Errors: + + "error": "duplicate uuid-name" + + The same "uuid-name" appeared on an earlier "insert" operation + within this transaction. select ...... @@ -500,9 +692,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. @@ -626,3 +818,37 @@ Errors: "error": "aborted" This operation always fails with this error. + +declare +....... + +Request object members: + + "op": "declare" required + "uuid-name": required + +Result object members: + + none + +Semantics: + + Predeclares a UUID named that may be referenced in later + operations as ["named-uuid", ] or (at most once) in an + "insert" operation as "uuid-name". + + It is an error if has appeared as the "uuid-name" in a prior + "insert" or "declare" operation within this transaction. + + The generated UUID is returned as the "uuid" member of the result. + +Result object members: + + "uuid": + +Errors: + + "error": "duplicate uuid-name" + + The same "uuid-name" appeared on an earlier "insert" or + "declare" operation within this transaction.