X-Git-Url: http://git.onelab.eu/?a=blobdiff_plain;f=ovsdb%2FSPECS;h=d9c92dead942ae7aded4f09f7bd160689471c168;hb=1d273d6d802e5daeebe551e8ca0c3e99f4dda15e;hp=ff4015c2749e8c8ddef5230d3d083630afece96d;hpb=ae8f13e29057e233712356b3c03f02a7ef4e1e93;p=sliver-openvswitch.git diff --git a/ovsdb/SPECS b/ovsdb/SPECS index ff4015c27..d9c92dead 100644 --- a/ovsdb/SPECS +++ b/ovsdb/SPECS @@ -5,6 +5,19 @@ Basic Notation -------------- +OVSDB uses JSON, as defined by RFC 4627, for its schema format and its +wire protocol format. The JSON implementation in Open vSwitch has the +following limitations: + + - Null bytes (\u0000) are not allowed in strings. + + - Only UTF-8 encoding is supported. (RFC 4627 also mentions + UTF-16BE, UTF-16LE, and UTF-32.) + + - RFC 4627 says that names within a JSON object should be unique. + The Open vSwitch JSON parser discards all but the last value + for a name that is specified more than once. + The descriptions below use the following shorthand notations for JSON values. Additional notation is presented later. @@ -33,10 +46,14 @@ 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. + + + Any JSON value except null. + A JSON object with the following members: @@ -85,24 +102,22 @@ is represented by , as described below. A JSON object with the following members: "name": required - "comment": optional "tables": {: , ...} required - The "name" identifies the database as a whole. The "comment" - optionally provides more information about the database. The - value of "tables" is a JSON object whose names are table names and - whose values are s. + The "name" identifies the database as a whole. It must be + provided to most JSON-RPC requests to identify the database being + operated on. The value of "tables" is a JSON object whose names + are table names and whose values are s. A JSON object with the following members: - "comment": optional "columns": {: , ...} required + "maxRows": optional - The "comment" optionally provides information about this table for - a human reader. The value of "columns" is a JSON object whose - names are column names and whose values are s. + 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: @@ -121,19 +136,24 @@ is represented by , as described below. the database process is stopped and then started again, each "_version" also changes to a new random value. + If "maxRows" is specified, as a positive integer, it limits the + maximum number of rows that may be present in the table. This is + a "deferred" constraint, enforced only at transaction commit time + (see the "transact" request below). If "maxRows" is not + specified, the size of the table is limited only by the resources + available to the database server. + A JSON object with the following members: - "comment": optional "type": required "ephemeral": optional - The "comment" optionally provides information about this column - for a human reader. The "type" specifies the type of data stored - in this column. If "ephemeral" is specified as true, then this - column's values are not guaranteed to be durable; they may be lost - when the database restarts. + The "type" specifies the type of data stored in this column. If + "ephemeral" is specified as true, then this column's values are + not guaranteed to be durable; they may be lost when the database + restarts. @@ -168,19 +188,26 @@ is represented by , as described below. or a JSON object with the following members: "type": required + "enum": optional "minInteger": optional, integers only "maxInteger": optional, integers only "minReal": optional, reals only "maxReal": optional, reals only - "reMatch": optional, strings only - "reComment": optional, strings only "minLength": optional, strings only "maxLength": optional, strings only "refTable": optional, uuids only + "refType": "strong" or "weak" optional, only with "refTable" An by itself is equivalent to a JSON object with a single member "type" whose value is the . + "enum" may be specified as a whose type is a set of one + or more values specified for the member "type". If "enum" is + specified, then the valid values of the are limited to + those in the . + + "enum" is mutually exclusive with the following constraints. + If "type" is "integer", then "minInteger" or "maxInteger" or both may also be specified, restricting the valid integer range. If both are specified, then the maxInteger must be greater than or @@ -191,27 +218,24 @@ is represented by , as described below. specified, then the maxReal must be greater than or equal to minReal. - If "type" is "string", then: + If "type" is "string", then "minLength" and "maxLength" or both + may be specified, restricting the valid length of value strings. + If both are specified, then maxLength must be greater than or + equal to minLength. String length is measured in characters (not + bytes or UTF-16 code units). - "reMatch" may be a JavaScript (Perl 5-like) regular expression - that restricts the allowed values. The regular expression - must match the entire string value, that is, it is treated as - if it begins with ^ and ends with $, regardless of whether it - really does. + If "type" is "uuid", then "refTable", if present, must be the name + of a table within this database. If "refTable" is specified, then + "refType" may also be specified. If "refTable" is set, the effect + depends on "refType": - If "reMatch" is specified, then "reComment" may be a string - that describes the allowed values, phrased so that it fits - into a sentence such as "This value must be...". + - If "refType" is "strong" or if "refType" is omitted, the + allowed UUIDs are limited to UUIDs for rows in the named + table. - "minLength" and "maxLength" or both may be specified, - restricting the valid length of value strings. If both are - specified, then maxLength must be greater than or equal to - minLength. String length is measured in characters (not bytes - or UTF-16 code units). - - If "type" is "uuid", then "refTable", if present, must be the name - of a table within this database. If "refTable" is set, the - allowed UUIDs are limited to UUIDs for rows in the named table. + - If "refType" is "weak", then any UUIDs are allowed, but + UUIDs that do not correspond to rows in the named table will + be automatically deleted. "refTable" constraints are "deferred" constraints: they are enforced only at transaction commit time (see the "transact" @@ -240,16 +264,37 @@ over HTTP, for these reasons: * The JSON-RPC specification for HTTP transport is incomplete. +We are using TCP port 6632 for the database JSON-RPC connection. + The database wire protocol consists of the following JSON-RPC methods: +list_dbs +........ + +Request object members: + + "method": "list_dbs" required + "params": [] required + "id": required + +Response object members: + + "result": [, ...] + "error": null + "id": same "id" as request + +This operation retrieves an array whose elements are s +that name the databases that can be accessed over this JSON-RPC +connection. + get_schema .......... Request object members: "method": "get_schema" required - "params": [] required - "id": any JSON value except null required + "params": [] required + "id": required Response object members: @@ -257,17 +302,17 @@ Response object members: "error": null "id": same "id" as request -This operation retrieves a that describes the -hosted database. +This operation retrieves a that describes hosted +database . transact ........ Request object members: - "method": "transact" required - "params": [*] required - "id": any JSON value except null required + "method": "transact" required + "params": [, *] required + "id": required Response object members: @@ -275,9 +320,11 @@ Response object members: "error": null "id": same "id" as request -The "params" array for this method consists of zero or more JSON -objects, each of which represents a single database operation. The -"Operations" section below describes the valid operations. +The "params" array for this method consists of a that +identifies the database to which the transaction applies, followed by +zero or more JSON objects, each of which represents a single database +operation. The "Operations" section below describes the valid +operations. The value of "id" must be unique among all in-flight transactions within the current JSON-RPC session. Otherwise, the server may return @@ -323,11 +370,25 @@ include at least the following: When the commit was attempted, a column's value referenced the UUID for a row that did not exist in the table named by the - column's key or value "refTable". (This can be - caused by inserting a row that references a nonexistent row, - by deleting a row that is still referenced by another row, by - specifying the UUID for a row in the wrong table, and other - ways.) + column's key or value "refTable" that has a + "refType" of "strong". (This can be caused by inserting a row + that references a nonexistent row, by deleting a row that is + still referenced by another row, by specifying the UUID for a + row in the wrong table, and other ways.) + + "error": "constraint violation" + + A column with a key or value "refTable" whose + "refType" is "weak" became empty due to deletion(s) caused + because the rows that it referenced were deleted (or never + existed, if the column's row was inserted within the + transaction), and this column is not allowed to be empty + because its has a "min" of 1. + + "error": "constraint violation" + + The number of rows in a table exceeds the maximum number + permitted by the table's "maxRows" value (see ). If "params" contains one or more "wait" operations, then the transaction may take an arbitrary amount of time to complete. The @@ -373,12 +434,14 @@ monitor Request object members: - "method": "monitor" required - "params": [, ] required - "id": any JSON value except null required + "method": "monitor" required + "params": [, , ] required + "id": required - is an object that maps from a table name to a -. + is an object that maps from a table name to an +array of objects. For backward compatibility, a +single may be used instead of an array; it is +treated as a single-element array. Each is an object with the following members: @@ -399,15 +462,16 @@ Response object members: "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. +of tables within database . Each element of + specifies a table to be replicated. The JSON-RPC +response to the "monitor" includes the initial contents of each table, +unless disabled (see below). 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: +Each describes how to monitor columns in a table: The circumstances in which an "update" notification is sent for a row within the table are determined by : @@ -425,8 +489,13 @@ Each describes how to monitor a table: 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. + monitored. It must not contain duplicates. If "columns" is + omitted, all columns in the table, except for "_uuid", are + monitored. + +If there is more than one in an array of them, then +each in the array should specify both "columns" and +"select", and the "columns" must be non-overlapping sets. The "result" in the JSON-RPC response to the "monitor" request is a object (see below) that contains the contents of the @@ -439,11 +508,11 @@ update Notification object members: "method": "update" - "params": [, ] + "params": [, ] "id": null -The in "params" is the same as the value passed as the -in "params" for the "monitor" request. +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 . @@ -482,8 +551,8 @@ monitor_cancel Request object members: "method": "monitor_cancel" required - "params": [] required - "id": any JSON value except null required + "params": [] required + "id": required Response object members: @@ -491,10 +560,10 @@ Response object members: "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. +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 .... @@ -503,7 +572,7 @@ Request object members: "method": "echo" required "params": JSON array with any contents required - "id": required + "id": required Response object members: @@ -521,6 +590,12 @@ there or vice versa. Notation for the Wire Protocol ------------------------------ + + + An that names a database. The valid s can be + obtained using a "list-db" request. The is taken from + the "name" member of . + An that names a table.