X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=ovsdb%2FSPECS;h=9fd654be6d1c51857ed0d5932adf47bfd6a4440b;hb=e9f8f9367e9e654b9582279608af86ea3744a2a0;hp=a4e9ab48385c3511eeda148b3b80a819b84bd58c;hpb=e68c3e486a31997a82a831eef4cd272a428bf0a8;p=openvswitch diff --git a/ovsdb/SPECS b/ovsdb/SPECS index a4e9ab48..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. @@ -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 .......... @@ -497,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 [, , @@ -569,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 ---------- @@ -582,7 +672,7 @@ Request object members: "op": "insert" required "table": required "row": required - "uuid-name": optional + "uuid-name": optional Result object members: @@ -594,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 ...... @@ -661,6 +772,57 @@ Semantics: 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 ...... @@ -780,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.