Merge pull request #56 from oxygenxml/CF-1333

CF-1333: Document the new SaveStrategy API.

DITA/topics/webauthor-concurrent-editing-api.dita

@@ -125,7 +125,7 @@ RewriteRule ^/oxygen-xml-web-author/?(.*)
             check-out.</li>
           <li id="li_bdt_dgk_54b">Creating the concurrent editing room.</li>
           <li id="li_cdt_dgk_54b">Enabling users to join the room.</li>
-          <li id="li_ddt_dgk_54b">Saving the content of the room.</li>
+          <li id="li_ddt_dgk_54b">Specifying the Save Strategy </li>
           <li id="li_edt_dgk_54b">Closing the room.</li>
         </ul></p>
       <section id="section_evc_zgt_rnb">
@@ -152,22 +152,28 @@ window.open(window.location.href + '&amp;roomId=' + roomId))</codeblock></p>
         </ul>
       </section>
       <section id="section_jkr_4ht_rnb">
-        <title>Saving the Content of the Room</title>
-        <p id="p_ndt_dgk_54b">To Save a document edited in a concurrent editing room, the CMS can use the room
-            <i>Observer</i>, which provides the "source-of-truth" for the document content. The
-            <i>Observer</i> integrates changes made by each user in batches. This helps to keep an
-          informative version history.</p>
-        <p id="p_odt_dgk_54b">For example, to implement auto-save, a CMS should:</p>
-        <ul id="ul_fww_pht_rnb">
-          <li id="li_pdt_dgk_54b">Add an <codeph>EditListener</codeph> on the observer
-              (<codeph>room.getObserver()</codeph>) to be notified when the document state is
-            changed.</li>
-          <li id="li_qdt_dgk_54b">Periodically call <codeph>room.getObserver().sync(peerId -> { }};</codeph>. The
-            callback is called after integrating a batch of changes from a single user.</li>
-          <li id="li_rdt_dgk_54b">After integrating each batch of changes, the CMS can call
-              <codeph>room.getObserver().createInputStream()</codeph> to obtain a reader over the
-            document content at that point. The reader should be consumed immediately.</li>
-        </ul>
+        <title>Saving a Concurrently Edited Session</title>
+        <p>When having to save a concurrently edited document, the application uses a so-called
+            <i>save strategy</i> that  can be specified when creating the room by calling
+            <codeph>ro.sync.ecss.extensions.api.webapp.ce.RoomFactory.createRoom(AuthorDocumentModel,
+            SaveStrategy)</codeph>.</p>
+        <p>The save strategy decides if the application writes to the CMS the document containing
+          edits for each peer individually or if should group all changes and write only once to
+          save all changes made from the last save. Additionally it provides the
+            <codeph>URLConnection</codeph> on whose <codeph>OutputStream</codeph> the changes from
+          an author or from a list of author are written.</p>
+        <p>There are two base classes that shall be extended:<ol id="ol_jt4_v2z_ypb">
+            <li><codeph>ro.sync.ecss.extensions.api.webapp.ce.GroupChangesForSinglePeerStrategy</codeph><p>It
+                facilitates tracking precise authorship of changes, each written revision containing
+                changes by only one author.</p><p>Note that the <codeph>URLConnection
+                  openConnection(URL documentUrl, PeerContext author)</codeph> method has only one
+                peer involved, being both the author and the committer.</p></li>
+            <li><codeph>ro.sync.ecss.extensions.api.webapp.ce.GroupChangesForMultiplePeersStrategy</codeph><p>It
+                facilitates a minimum number of writes to the file server per save.</p><p>Note that
+                the <codeph>URLConnection openConnection(URL documentUrl, PeerContext committer,
+                  List&lt;PeerContext> authors)</codeph> method has a committer and a list of
+                authors, whose changes are grouped together.</p></li>
+          </ol></p>
       </section>
       <section id="section_wfk_qht_rnb">
         <title>Enabling Users to Join a Room</title>