debian: Move openvswitch-dbg to "debug" section.

[openvswitch] / ovsdb / SPECS

diff --git a/ovsdb/SPECS b/ovsdb/SPECS
index 3acf32d27b8c113ae3f1ff358a841a73bc66f3d9..93db15d4cc41191c75af22688ff69cef252db0a4 100644 (file)
--- a/ovsdb/SPECS
+++ b/ovsdb/SPECS
@@ -10,7 +10,8 @@ values.  Additional notation is presented later.
 
 <string>
 
-    A JSON string.
+    A JSON string.  Any Unicode string is allowed, as specified by RFC
+    4627.  Implementations may disallowed null bytes.
 
 <id>
 
@@ -133,8 +134,21 @@ is represented by <database-schema>, 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
 ..........
@@ -585,7 +599,7 @@ Request object members:
     "op": "insert"          required
     "table": <table>        required
     "row": <row>            required
-    "uuid-name": <string>   optional
+    "uuid-name": <id>       optional
 
 Result object members:
 
@@ -597,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 this
-    operation and 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 <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".
+
+    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.
+
+    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
 ......
@@ -783,3 +818,37 @@ Errors:
     "error": "aborted"
 
         This operation always fails with this error.
+
+declare
+.......
+
+Request object members:
+
+    "op": "declare"                    required
+    "uuid-name": <id>                  required
+
+Result object members:
+
+    none
+
+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.
+
+Result object members:
+
+    "uuid": <uuid>
+
+Errors:
+
+    "error": "duplicate uuid-name"
+
+        The same "uuid-name" appeared on an earlier "insert" or
+        "declare" operation within this transaction.