couchdb-commits mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From d..@apache.org
Subject [2/4] git commit: updated refs/heads/1781-reorganize-and-improve-docs to 083bb15
Date Fri, 27 Sep 2013 23:58:54 GMT
docs: update changes


Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/e6f1e841
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/e6f1e841
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/e6f1e841

Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: e6f1e8411eeb0737d2126f4367dff07238c48de1
Parents: 1f10129
Author: Dave Cottlehuber <dch@apache.org>
Authored: Fri Sep 27 23:47:42 2013 +0200
Committer: Dave Cottlehuber <dch@apache.org>
Committed: Fri Sep 27 23:47:42 2013 +0200

----------------------------------------------------------------------
 share/doc/src/api/database/changes.rst | 53 ++++++++++++++++-------------
 1 file changed, 30 insertions(+), 23 deletions(-)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/couchdb/blob/e6f1e841/share/doc/src/api/database/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database/changes.rst b/share/doc/src/api/database/changes.rst
index 344a3bb..739f7d8 100644
--- a/share/doc/src/api/database/changes.rst
+++ b/share/doc/src/api/database/changes.rst
@@ -21,9 +21,10 @@
 .. http:head:: /{db}/_changes
 .. http:post:: /{db}/_changes
 
-  A list of changes made to documents in the database, in the order they were
-  made, can be obtained from the database's ``_changes`` resource.
-  This can be used to monitor for update and modifications to the database for
+  A sorted list of changes made to documents in the database, in the order
+  they were made, can be obtained from the database's ``_changes`` resource.
+
+  This can be used to listen for update and modifications to the database for
   post processing or synchronization.
 
   :param db: Database name
@@ -162,7 +163,7 @@ Changes Feeds
 Polling
 -------
 
-By default all changes are immediately returned as a JSON object::
+By default all changes are immediately returned within the JSON body::
 
     GET /somedatabase/_changes HTTP/1.1
 
@@ -194,7 +195,7 @@ including the given sequence number::
 The return structure for ``normal`` and ``longpoll`` modes is a JSON
 array of changes objects, and the last update sequence number.
 
-The return format for ``continuous`` mode the server sends a ``CRLF``
+In the return format for ``continuous`` mode, the server sends a ``CRLF``
 (carriage-return, linefeed) delimited line for each change. Each line
 contains the `JSON object` described above.
 
@@ -203,35 +204,43 @@ of just the change notification) by using the ``include_docs`` parameter.
 
 .. code-block:: javascript
 
-    {"results":[
-    {"seq":5,"id":"deleted","changes":[{"rev":"2-eec205a9d413992850a6e32678485900"}],"deleted":true}
-    ],
-    "last_seq":5} 
-
+    {
+        "last_seq": 5
+        "results": [
+            {
+                "changes": [
+                    {
+                        "rev": "2-eec205a9d413992850a6e32678485900"
+                    }
+                ],
+                "deleted": true,
+                "id": "deleted",
+                "seq": 5,
+            }
+        ]
+    }
 
 .. _changes/longpoll:
 
 Long Polling
 ------------
 
-With long polling the request to the server will remain open until a
-change is made on the database, when the changes will be reported,
-and then the connection will close. The long poll is useful when you
-want to monitor for changes for a specific purpose without wanting to
-monitoring continuously for changes.
-
-The `longpoll` feed (probably most useful used from a browser) is a more
+The `longpoll` feed, probably most applicable for a browser, is a more
 efficient form of polling that waits for a change to occur before the response
 is sent. `longpoll` avoids the need to frequently poll CouchDB to discover
 nothing has changed!
 
+The request to the server will remain open until a change is made on the
+database and is subsequently transferred, and then the connection will close.
+This is low load for both server and client.
+
 The response is basically the same JSON as is sent for the `normal` feed.
 
 Because the wait for a change can be significant you can set a
 timeout before the connection is automatically closed (the
 ``timeout`` argument). You can also set a heartbeat interval (using
 the ``heartbeat`` query argument), which sends a newline to keep the
-connection open.
+connection active.
 
 
 .. _changes/continuous:
@@ -239,7 +248,7 @@ connection open.
 Continuous
 ----------
 
-Polling the CouchDB server is not a good thing to do. Setting up new HTTP
+Continually polling the CouchDB server is not ideal - setting up new HTTP
 connections just to tell the client that nothing happened puts unnecessary
 strain on CouchDB.
 
@@ -271,8 +280,7 @@ results.
 Obviously, `... tum tee tum ...` does not appear in the actual response, but
 represents a long pause before the change with seq 6 occurred.  
 
-.. _section in the book: http://books.couchdb.org/relax/reference/change-notifications
-
+.. _section in the book: http://guide.couchdb.org/draft/notifications.html
 
 .. _changes/eventsource:
 
@@ -282,7 +290,6 @@ Event Source
 The `eventsource` feed provides push notifications that can be consumed in
 the form of DOM events in the browser. Refer to the `W3C eventsource
 specification`_ for further details. CouchDB also honors the ``Last-Event-ID``
-header, and if it's present it will take precedence over the ``since`` query
 parameter.
 
 .. code-block:: text
@@ -316,7 +323,7 @@ parameter.
 .. note::
 
    EventSource connections are subject to cross-origin resource sharing
-   restrictions. You might need to use the experimental :ref:`CORS support
+   restrictions. You might need to configure :ref:`CORS support
    <cors>` to get the EventSource to work in your application.
 
 .. _W3C eventsource specification: http://www.w3.org/TR/eventsource/


Mime
View raw message