Changes between Version 1 and Version 2 of Infinote/Protocol

Timestamp:

09/11/07 13:39:04 (6 years ago)

Author:

armin (IP: 87.178.211.239)

Comment:

Added InfText? messages

Infinote/Protocol

@@ -427 +427 @@
 == Additional InfText messages ==
 
-=== Additional user attributes ===
-
-TODO
+=== State vectors ===
+
+The state of a document is completely defined by a so-called state vector specifying how many operations each user did. For example, if user A made 2 requests and user B made 3 requests, the document has a certain state. All users that processed these 5 requests are in the same state. Note that it does not matter in which order the requests are processed (as long as the causal order is kept), which is the key concept behind the adOPTed algorithm.
+
+Each user maintains a state vector for each user that describes in which state that user is. This vector is updated every time a request is received from a particular user. This requires every user to send no-op requests if it has been inactive for some time, so that others know the state of this user.
+
+Also, each user maintains a request log in which all requests the user made are stored. This is required for transforming incoming requests from other users that were made in a different state of the document. Details to the adOPTed algorithm and how these transformations are performed can be found in the papers at http://portal.acm.org/citation.cfm?id=240305 and http://portal.acm.org/citation.cfm?doid=320297.320312.
+
+Some attributes of the following messages describe such a state vector. The state vector has the form "user_id:processed_requests;user_id:processed_requests;[...]" where user_id is the ID of a user and processed_requests describe the number of requests that this user is guaranteed to have already processed.
+
+=== User attributes ===
+
+The following attributes are used in the <sync-user> and <join-user> requests for text sessions:
+
+ * time, StateVector: The current state vector of the user
+ * caret: The position of the user's cursor, in characters, from the document beginning
+ * selection: The number of characters selected, starting at the character caret. Negative means selection towards the beginning of the document.
+
+TODO: Viewport
 
 === Synchronization ===
 
-TODO
+These are additional messages sent during synchronization:
+
+{{{
+<sync-state time="time" />
+}}}
+
+ * time, StateVector: The current state vector.
+
+Tells the state vector of the state the document currently is in.
+
+{{{
+<sync-request user="user_id" time="time">
+ <operation />
+</sync-request>
+}}}
+
+ * user, Integer: The ID of the user that made the request.
+ * time, State Vector: The state at which the request was made.
+ * operation: The operation performed by the request, see below.
+
+Tells that at the given time a user made a request. This should be added to the request log and might be necessary to transform incoming operations or to compute Undo operations.
+
+{{{
+<sync-segment author="user_id">Text</sync-segment>
+}}}
+
+ * author, optional: The user ID of the user that wrote the text.
+ * Text: The text that user wrote.
+
+Synchronizes a part of the initial document that was written by a single user. The <sync-segment> messages should be sent in-order so the document can be reconstructed.
 
 === Independant ===
@@ -439 +484 @@
 These messages are sent no matter whether being client or server.
 
-TODO
+{{{
+<request user="user_id" time="time">
+ <operation />
+</request>
+}}}
+
+ * user, Integer: The ID of the user that made the request.
+ * time, State Vector: The document state at which the request was made.
+ * operation: The operation performed by the request, see below.
+
+Whenever a user issues a request the <request> message is sent. The user must have joined via the connection the request message comes from. <request> is sent to the whole subscription group.
+
+=== Operations ===
+
+There are two types of operations. Such operations that modify the document and such that do not. For example, inserting a character into the document does modify it, but moving the cursor of a user does not. If the operation of a request does not modify the document, the request is not recorded in the request log.
+
+The following operations are defined
+
+{{{
+<insert pos="pos">text</insert>
+<insert-caret pos="pos">text</insert-caret>
+}}}
+
+ * pos, Integer: The character offset at which to insert text.
+ * text, String: The text to insert.
+
+An operation that inserts new text into the document. The <insert-caret> version additionally places the cursor of the user that made the request behind the inserted text.
+
+{{{
+<delete pos="pos" len="len" />
+<delete-caret pos="pos" len="len" />
+}}}
+
+ * pos, Integer: The character offset at which to start deleting characters
+ * len, Integer: The number of characters to delete.
+
+Deletes text from the buffer. This operation is only used in <request> messages. Again, <delete-caret> additionally places the cursor of the user that made the request to the place where characters have been deleted.
+
+{{{
+<delete pos="pos"><segment author="user_id">text</segment>[...]</delete>
+}}}
+
+ * pos, Integer: The character offset at which to start deleting characters.
+ * segments: The text that was deleted, including author information, i.e. which user wrote what text.
+
+Deletes text from the buffer and specifies what text is deleted. This operation is only used in <sync-request> messages. The synchronization client cannot deduce what text was actually deleted, but must be able to compute the reverse operation in case someone undoes the request. In a normal <request> message, other users can deduce what text was deleted by having a look at the document and which transformations were required to transform the request to the current state before the operation is actually executed.
+
+{{{
+<no-op />
+}}}
+
+Does nothing, and does especially not modify the document (see above). This is used when a user was inactive for some time to report its current state vector to the other users.
+
+{{{
+<move caret="pos" selection="len" />
+}}}
+
+ * pos, Integer: The character offset to place the cursor to.
+ * len, Integer: The length of the selection area, in characters. Negative values mean selection towards the beginning of the document.
+
+Changes the position of the user's cursor position and selection area. This operation does not modify the document.
+
+{{{
+<undo />
+<undo-caret />
+}}}
+
+Undoes the last request of the user. The <undo-caret> version also places the user's cursor to the position where the operation was performed.
+
+{{{
+<redo />
+<redo-caret />
+}}}
+
+Redoes the last request of the user. The <redo-caret> version also places the user's cursor to the position where the operation was performed.
 
 == Discussion ==
@@ -445 +564 @@
 Please ask if things remain unclear.
 
-'''Armin:''' Things I did not yet think about (too much): Access restriction, xmlns, user colors.
+'''Armin:''' Things I did not yet think about (too much): Access restriction, xmlns, user colors, viewport.