X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=ovsdb%2FSPECS;h=9fd654be6d1c51857ed0d5932adf47bfd6a4440b;hb=e9f8f9367e9e654b9582279608af86ea3744a2a0;hp=12d97682a836ebf61d0a8b320b31de7c929109c8;hpb=f85f8ebbfac946c19b3c6eb0f4170f579d0a4d25;p=openvswitch diff --git a/ovsdb/SPECS b/ovsdb/SPECS index 12d97682..9fd654be 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 [, , @@ -415,6 +586,79 @@ Notation for the Wire Protocol One of "<", "<=", "==", "!=", ">=", ">", "includes", "excludes". + + + A 3-element JSON array of the form [, , ] + that represents a change to a column value. + + Except as otherwise specified below, must have the same + type as . + + The meaning depends on the type of : + + integer + real + + must be "+=", "-=", "*=", "/=" or (integer only) + "%=". The value of is changed to the sum, + difference, product, quotient, or remainder, respectively, + of and . + + boolean + string + uuid + + No valid s are currently defined for these types. + + set + + Any valid for the set's element type may be + applied to the set, in which case the mutation is applied + to each member of the set individually. must be a + scalar value of the same type as the set's element type. + + If is "insert", then each of the values in the + set in is added to if it is not already + present. The required type of is slightly + relaxed, in that it may have fewer than the minimum number + of elements specified by the column's type. + + If is "delete", then each of the values in the + set in is removed from if it is present + there. The required type is slightly relaxed in that + may have more or less than the maximum number of + elements specified by the column's type. + + map + + must be "insert" or "delete". + + If is "insert", then each of the key-value pairs + in the map in is added to if its key is + not already present. The required type of is + slightly relaxed, in that it may have fewer than the + minimum number of elements specified by the column's type. + + If is "delete", then may have the same + type as (a map type) or it may be a set whose + element type is the same as 's key type: + + - If is a map, the mutation deletes each + key-value pair in whose key and value equal + one of the key-value pairs in . + + - If is a set, the mutation deletes each + key-value pair in whose key equals one of + the values in . + + For "delete", may have any number of elements, + regardless of restrictions on the number of elements in + . + + + + One of "+=", "-=", "*=", "/=", "%=", "insert", "delete". + Operations ---------- @@ -428,7 +672,7 @@ Request object members: "op": "insert" required "table": required "row": required - "uuid-name": optional + "uuid-name": optional Result object members: @@ -440,10 +684,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,13 +765,64 @@ 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. +mutate +...... + +Request object members: + + "op": "mutate" required + "table":
required + "where": [*] required + "mutations": [*] required + +Result object members: + + "count": + +Semantics: + + Mutates rows in a table. + + Searches "table" for rows that match all the conditions specified + in "where". For each matching row, mutates its columns as + specified by each in "mutations", in the order + specified. + + The "_uuid" and "_version" columns of a table may not be directly + modified 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. + +Errors: + + "error": "domain error" + + The result of the mutation is not mathematically defined, + e.g. division by zero. + + "error": "range error" + + The result of the mutation is not representable within the + database's format, e.g. an integer result outside the range + INT64_MIN...INT64_MAX or a real result outside the range + -DBL_MAX...DBL_MAX. + + "error": "constraint violation" + + The mutation caused the column's value to violate a + constraint, e.g. it caused a column to have more or fewer + values than are allowed or an arithmetic operation caused a + set or map to have duplicate elements. + delete ...... @@ -626,3 +942,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.