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/07/24 14:24:57 UTC
[20/50] [abbrv] git commit: updated
refs/heads/1781-reorganize-and-improve-docs to fa11c25
Reduce content duplicity for changes feed.
Project: http://git-wip-us.apache.org/repos/asf/couchdb/repo
Commit: http://git-wip-us.apache.org/repos/asf/couchdb/commit/ca28e125
Tree: http://git-wip-us.apache.org/repos/asf/couchdb/tree/ca28e125
Diff: http://git-wip-us.apache.org/repos/asf/couchdb/diff/ca28e125
Branch: refs/heads/1781-reorganize-and-improve-docs
Commit: ca28e12517b2b6cfb85b5b03491cbb867f64b8a3
Parents: 351e91a
Author: Alexander Shorin <kx...@apache.org>
Authored: Tue Jul 23 03:41:31 2013 +0400
Committer: Alexander Shorin <kx...@apache.org>
Committed: Wed Jul 24 10:48:37 2013 +0400
----------------------------------------------------------------------
share/doc/src/api/database.rst | 54 ++++---------------------------------
share/doc/src/changes.rst | 20 +++++++++++---
2 files changed, 21 insertions(+), 53 deletions(-)
----------------------------------------------------------------------
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ca28e125/share/doc/src/api/database.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/api/database.rst b/share/doc/src/api/database.rst
index 188a9f7..43a1f1c 100644
--- a/share/doc/src/api/database.rst
+++ b/share/doc/src/api/database.rst
@@ -335,55 +335,11 @@ If successful, the returned JSON will indicate success
Obtains a list of the changes made to the database. This can be used to
monitor for update and modifications to the database for post processing
-or synchronization. There are three different types of supported changes
-feeds, poll, longpoll, and continuous. All requests are poll requests by
-default. You can select any feed type explicitly using the ``feed``
-query argument.
-
-- **Poll**
-
- With polling you can request the changes that have occured since a
- specific sequence number. This returns the JSON structure containing
- the changed document information. When you perform a poll change
- request, only the changes since the specific sequence number are
- returned. For example, the query
-
- .. code-block:: http
-
- DELETE http://couchdb:5984/recipes/_changes
- Content-Type: application/json
-
- Will get all of the changes in the database. You can request a
- starting point using the ``since`` query argument and specifying the
- sequence number. You will need to record the latest sequence number
- in your client and then use this when making another request as the
- new value to the ``since`` parameter.
-
-- **Longpoll**
-
- 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.
-
- 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.
-
-- **Continuous**
-
- Continuous sends all new changes back to the client immediately,
- without closing the connection. In continuous mode the format of the
- changes is slightly different to accommodate the continuous nature
- while ensuring that the JSON output is still valid for each change
- notification.
-
- As with the longpoll feed type you can set both the timeout and
- heartbeat intervals to ensure that the connection is kept open for
- new changes and updates.
+or synchronization.
+
+.. seealso::
+
+ :ref:`Detailed description of available changes feed types <changes>`
The return structure for ``normal`` and ``longpoll`` modes is a JSON
array of changes objects, and the last update sequence number. The
http://git-wip-us.apache.org/repos/asf/couchdb/blob/ca28e125/share/doc/src/changes.rst
----------------------------------------------------------------------
diff --git a/share/doc/src/changes.rst b/share/doc/src/changes.rst
index 9ec747e..55f561f 100644
--- a/share/doc/src/changes.rst
+++ b/share/doc/src/changes.rst
@@ -143,16 +143,24 @@ including the given sequence number::
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
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 response is basically the same JSON as is sent for the normal feed.
+The response is basically the same JSON as is sent for the `normal` feed.
-A timeout limits the maximum length of time the connection is open. If there
-are no changes before the timeout expires the response's results will be an
-empty list.
+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.
.. _changes/continuous:
@@ -168,6 +176,10 @@ A continuous feed stays open and connected to the database until explicitly
closed and changes are sent to the client as they happen, i.e. in near
real-time.
+As with the `longpoll` feed type you can set both the timeout and heartbeat
+intervals to ensure that the connection is kept open for new changes
+and updates.
+
The continuous feed's response is a little different than the other feed types
to simplify the job of the client - each line of the response is either empty
or a JSON object representing a single change, as found in the normal feed's