X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=ovsdb%2FSPECS;h=93db15d4cc41191c75af22688ff69cef252db0a4;hb=a0a9f31ddc4fc213f9550c93478b4f03b948f606;hp=97c9a78068676db1c9edb3202659503c3b7e758d;hpb=a8425c53c5785856cabe80295f0cea0135febdb6;p=openvswitch diff --git a/ovsdb/SPECS b/ovsdb/SPECS index 97c9a780..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. @@ -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 @@ -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 [, , @@ -582,7 +599,7 @@ Request object members: "op": "insert" required "table": required "row": required - "uuid-name": optional + "uuid-name": optional Result object members: @@ -594,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 ...... @@ -654,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. @@ -780,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.