X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=ovsdb%2FSPECS;h=7963a2adfb38f98c4bc1a5d3cd8896c707e8bbf6;hb=847c7448532ddf90f28ace17233f4993e403f6f2;hp=97c9a78068676db1c9edb3202659503c3b7e758d;hpb=a8425c53c5785856cabe80295f0cea0135febdb6;p=openvswitch diff --git a/ovsdb/SPECS b/ovsdb/SPECS index 97c9a780..7963a2ad 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: @@ -112,9 +113,9 @@ is represented by , as described below. If "min" or "max" is not specified, each defaults to 1. If "max" is specified as "unlimited", then there is no specified maximum number of elements, although the implementation will enforce some - limit. After considering defaults, "min" must be at least 0, - "max" must be at least 1, and "max" must be greater than or equal - to "min". + limit. After considering defaults, "min" must be exactly 0 or + exactly 1, "max" must be at least 1, and "max" must be greater + than or equal to "min". If "min" and "max" are both 1 and "value" is not specified, the type is the scalar type specified by "key". @@ -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 @@ -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 only 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 ...... @@ -654,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 ...... @@ -780,3 +942,52 @@ Errors: "error": "aborted" This operation always fails with this error. + +declare +....... + +Request object members: + + "op": "declare" required + "uuid-name": required + +Result object members: + + "uuid": + +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. + +Errors: + + "error": "duplicate uuid-name" + + The same "uuid-name" appeared on an earlier "insert" or + "declare" operation within this transaction. + +comment +....... + + +Request object members: + + "op": "comment" required + "comment": required + +Result object members: + + none + +Semantics: + + Provides information to a database administrator on the purpose of + a transaction. The OVSDB server, for example, adds comments in + transactions that modify the database to the database journal.