xenserver: Fix comment in interface-reconfigure.

[openvswitch] / ovsdb / SPECS

diff --git a/ovsdb/SPECS b/ovsdb/SPECS
index c1e3eca679743c7a729506b62346fce6447e6e03..4020241e54e44a17a7b5eb9922724bce784304f8 100644 (file)
--- a/ovsdb/SPECS
+++ b/ovsdb/SPECS
@@ -33,10 +33,14 @@ values.  Additional notation is presented later.
     A JSON number with an integer value, within a certain range
     (currently -2**63...+2**63-1).
 
     A JSON number with an integer value, within a certain range
     (currently -2**63...+2**63-1).
 

-<value>
+<json-value>

 
     Any JSON value.
 
 
     Any JSON value.
 

+<nonnull-json-value>
+
+    Any JSON value except null.
+

 <error>
 
     A JSON object with the following members:
 <error>
 
     A JSON object with the following members:


@@ -88,10 +92,11 @@ is represented by <database-schema>, as described below.
         "comment": <string>                     optional
         "tables": {<id>: <table-schema>, ...}   required
 
         "comment": <string>                     optional
         "tables": {<id>: <table-schema>, ...}   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 <table-schema>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 "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 <table-schema>s.

 
 <table-schema>
 
 
 <table-schema>
 


@@ -242,14 +247,33 @@ over HTTP, for these reasons:
 
 The database wire protocol consists of the following JSON-RPC methods:
 
 
 The database wire protocol consists of the following JSON-RPC methods:
 

+list_dbs
+........
+
+Request object members:
+
+    "method": "list_dbs"              required
+    "params": []                      required
+    "id": <nonnull-json-value>        required
+
+Response object members:
+
+    "result": [<db-name>, ...]
+    "error": null
+    "id": same "id" as request
+
+This operation retrieves an array whose elements are <db-name>s
+that name the databases that can be accessed over this JSON-RPC
+connection.
+

 get_schema
 ..........
 
 Request object members:
 
     "method": "get_schema"            required
 get_schema
 ..........
 
 Request object members:
 
     "method": "get_schema"            required

-    "params": []                      required
-    "id": any JSON value except null  required
+    "params": [<db-name>]             required
+    "id": <nonnull-json-value>        required

 
 Response object members:
 
 
 Response object members:
 


@@ -257,17 +281,17 @@ Response object members:
     "error": null
     "id": same "id" as request
 
     "error": null
     "id": same "id" as request
 

-This operation retrieves a <database-schema> that describes the
-hosted database.
+This operation retrieves a <database-schema> that describes hosted
+database <db-name>.

 
 transact
 ........
 
 Request object members:
 
 
 transact
 ........
 
 Request object members:
 

-    "method": "transact"              required
-    "params": [<operation>*]          required
-    "id": any JSON value except null  required
+    "method": "transact"                  required
+    "params": [<db-name>, <operation>*]   required
+    "id": <nonnull-json-value>            required

 
 Response object members:
 
 
 Response object members:
 


@@ -275,9 +299,11 @@ Response object members:
     "error": null
     "id": same "id" as request
 
     "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 <db-name> 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
 
 The value of "id" must be unique among all in-flight transactions
 within the current JSON-RPC session.  Otherwise, the server may return


@@ -373,9 +399,9 @@ monitor
 
 Request object members:
 
 
 Request object members:
 

-    "method": "monitor"                        required
-    "params": [<value>, <monitor-requests>]    required
-    "id": any JSON value except null           required
+    "method": "monitor"                                       required
+    "params": [<db-name>, <json-value>, <monitor-requests>]   required
+    "id": <nonnull-json-value>                                required

 
 <monitor-requests> is an object that maps from a table name to a
 <monitor-request>.
 
 <monitor-requests> is an object that maps from a table name to a
 <monitor-request>.


@@ -399,13 +425,13 @@ Response object members:
     "id": same "id" as request
 
 This JSON-RPC request enables a client to replicate tables or subsets
     "id": same "id" as request
 
 This JSON-RPC request enables a client to replicate tables or subsets

-of tables.  Each <monitor-request> 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 <db-name>.  Each <monitor-request> 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.

 
 Each <monitor-request> describes how to monitor a table:
 
 
 Each <monitor-request> describes how to monitor a table:
 


@@ -439,11 +465,11 @@ update
 Notification object members:
 
     "method": "update"
 Notification object members:
 
     "method": "update"

-    "params": [<value>, <table-updates>]
+    "params": [<json-value>, <table-updates>]

     "id": null
 
     "id": null
 

-The <value> in "params" is the same as the value passed as the <value>
-in "params" for the "monitor" request.
+The <json-value> in "params" is the same as the value passed as the
+<json-value> in "params" for the "monitor" request.

 
 <table-updates> is an object that maps from a table name to a
 <table-update>.
 
 <table-updates> is an object that maps from a table name to a
 <table-update>.


@@ -482,8 +508,8 @@ monitor_cancel
 Request object members:
 
     "method": "monitor_cancel"                              required
 Request object members:
 
     "method": "monitor_cancel"                              required

-    "params": [<value>]                                     required
-    "id": any JSON value except null                        required
+    "params": [<json-value>]                                required
+    "id": <nonnull-json-value>                              required

 
 Response object members:
 
 
 Response object members:
 


@@ -491,10 +517,10 @@ Response object members:
     "error": null
     "id": the request "id" member
 
     "error": null
     "id": the request "id" member
 

-Cancels the ongoing table monitor request, identified by the <value>
-in "params" matching the <value> 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
+<json-value> in "params" matching the <json-value> in "params" for an
+ongoing "monitor" request.  No more "update" messages will be sent for
+this table monitor.

 
 echo
 ....
 
 echo
 ....


@@ -503,7 +529,7 @@ Request object members:
 
     "method": "echo"                                required
     "params": JSON array with any contents          required
 
     "method": "echo"                                required
     "params": JSON array with any contents          required

-    "id": <value>                                   required
+    "id": <json-value>                              required

 
 Response object members:
 
 
 Response object members:
 


@@ -521,6 +547,12 @@ there or vice versa.
 Notation for the Wire Protocol
 ------------------------------
 
 Notation for the Wire Protocol
 ------------------------------
 

+<db-name>
+
+    An <id> that names a database.  The valid <db-name>s can be
+    obtained using a "list-db" request.  The <db-name> is taken from
+    the "name" member of <database-schema>.
+

 <table>
 
     An <id> that names a table.
 <table>
 
     An <id> that names a table.


@@ -547,7 +579,8 @@ Notation for the Wire Protocol
 
 <set>
 
 
 <set>
 

-    A 2-element JSON array that represents a database set value.  The
+    Either an <atom>, representing a set with exactly one element, or
+    a 2-element JSON array that represents a database set value.  The

     first element of the array must be the string "set" and the second
     element must be an array of zero or more <atom>s giving the values
     in the set.  All of the <atom>s must have the same type.
     first element of the array must be the string "set" and the second
     element must be an array of zero or more <atom>s giving the values
     in the set.  All of the <atom>s must have the same type.


@@ -582,13 +615,13 @@ Notation for the Wire Protocol
 <named-uuid>
 
     A 2-element JSON array that represents the UUID of a row inserted
 <named-uuid>
 
     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 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
-    <named-uuid> represents the UUID created by that operation:
+    in an "insert" operation within the same transaction.  The first
+    element of the array must be the string "named-uuid" and the
+    second element should be the string specified as the "uuid-name"
+    for an "insert" operation within the same transaction.  For
+    example, if an "insert" operation within this transaction
+    specifies a "uuid-name" of "myrow", the following <named-uuid>
+    represents the UUID created by that operation:

 
         ["named-uuid", "myrow"]
 
 
         ["named-uuid", "myrow"]
 


@@ -773,21 +806,11 @@ Semantics:
 
         - "uuid": 00000000-0000-0000-0000-000000000000
 
 
         - "uuid": 00000000-0000-0000-0000-000000000000
 

-    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 <id> has
-    previously appeared as the "uuid-name" in an "insert" operation.
-
-    If "uuid-name" is supplied and its <id> previously appeared as the
-    "uuid-name" in a "declare" operation, then the new row receives
-    the UUID associated with that "uuid-name".
+    The new row receives a new, randomly generated UUID.

 
 

-    If "uuid-name" is supplied and its <id> 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.
+    If "uuid-name" is supplied, then it is an error if <id> is not
+    unique among the "uuid-name"s supplied on all the "insert"
+    operations within this transaction.

 
     The UUID for the new row is returned as the "uuid" member of the
     result.
 
     The UUID for the new row is returned as the "uuid" member of the
     result.


@@ -796,7 +819,7 @@ Errors:
 
     "error": "duplicate uuid-name"
 
 
     "error": "duplicate uuid-name"
 

-        The same "uuid-name" appeared on an earlier "insert" operation
+        The same "uuid-name" appears on another "insert" operation

         within this transaction.
 
     "error": "constraint violation"
         within this transaction.
 
     "error": "constraint violation"


@@ -1046,36 +1069,6 @@ Errors:
 
         This operation always fails with this error.
 
 
         This operation always fails with this error.
 

-declare
-.......
-
-Request object members:
-
-    "op": "declare"                    required
-    "uuid-name": <id>                  required
-
-Result object members:
-
-    "uuid": <uuid>
-
-Semantics:
-
-    Predeclares a UUID named <id> that may be referenced in later
-    operations as ["named-uuid", <id>] or (at most once) in an
-    "insert" operation as "uuid-name".
-
-    It is an error if <id> 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
 .......
 
 comment
 .......