X-Git-Url: https://pintos-os.org/cgi-bin/gitweb.cgi?a=blobdiff_plain;f=ovsdb%2FSPECS;h=93db15d4cc41191c75af22688ff69cef252db0a4;hb=a0a9f31ddc4fc213f9550c93478b4f03b948f606;hp=a4e9ab48385c3511eeda148b3b80a819b84bd58c;hpb=e68c3e486a31997a82a831eef4cd272a428bf0a8;p=openvswitch

diff --git a/ovsdb/SPECS b/ovsdb/SPECS
index a4e9ab48..93db15d4 100644
--- 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
 ..........
@@ -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
     <named-uuid> represents the UUID created by that operation:
 
         ["named-uuid", "myrow"]
 
+    A <named-uuid> may be used anywhere a <uuid> is valid.
+
 <condition>
 
     A 3-element JSON array of the form [<column>, <function>,
@@ -582,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:
 
@@ -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 <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
 ......
@@ -780,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.