You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@couchdb.apache.org by kx...@apache.org on 2013/09/28 14:42:59 UTC
[33/50] [abbrv] git commit: updated refs/heads/master to 17e0b7c
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/master
Commit: e6f1e8411eeb0737d2126f4367dff07238c48de1
Parents: 1f10129
Author: Dave Cottlehuber <dc...@apache.org>
Authored: Fri Sep 27 23:47:42 2013 +0200
Committer: Dave Cottlehuber <dc...@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/