X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=ovsdb%2FSPECS;h=260786edb9bbd37d935344b26864531b90cf9cd9;hb=71ce92352cbcb96f179f8ec19dd1e843d91d8828;hp=adc6dd2278b4ad341695341996bfcf0813825900;hpb=89521e3f79d53523fda9f284e74f0f7aa21332b4;p=openvswitch diff --git a/ovsdb/SPECS b/ovsdb/SPECS index adc6dd22..260786ed 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. @@ -89,25 +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. It must be provided to most JSON-RPC requests to identify the database being - operated on. 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. + 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: @@ -126,19 +136,27 @@ 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 + "mutable": 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. If "mutable" is specified as false, then this column's + values may not be modified after they are initially set with the + "insert" operation. @@ -173,6 +191,7 @@ 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 @@ -180,10 +199,18 @@ is represented by , as described below. "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 @@ -201,8 +228,17 @@ is represented by , as described below. 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. + 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 "refType" is "strong" or if "refType" is omitted, 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" @@ -231,6 +267,8 @@ 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 @@ -335,11 +373,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 @@ -389,8 +441,10 @@ Request object members: "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: @@ -411,15 +465,16 @@ Response object members: "id": same "id" as request This JSON-RPC request enables a client to replicate tables or subsets -of tables within database . 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 : @@ -437,8 +492,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