com.cloudant.client.api

Class Changes

java.lang.Object

com.cloudant.client.api.Changes

public class Changes
extends java.lang.Object

Contains the Change Notifications API, supports normal and continuous feed Changes.

Usage example for normal feed limiting to 10 results, with a filter:

 
 // feed type normal
 String since = db.info().getUpdateSeq(); // latest update seq
 ChangesResult changeResult = db.changes()
 	.since(since)
 	.limit(10)
 	.filter("example/filter")
 	.getChanges();

 //process the ChangesResult
 for (ChangesResult.Row row : changeResult.getResults()) {
   String docId = row.getId()
   JsonObject doc = row.getDoc();
 }
 
 

Usage example for continuous feed, including document content:

 
 // feed type continuous
 Changes changes = db.changes()
 	.includeDocs(true)
 	.heartBeat(30000)
 	.continuousChanges();

 while (changes.hasNext()) {
 	ChangesResult.Row feed = changes.next();
  String docId = feed.getId();
  JsonObject doc = feed.getDoc();
 }

 //while loop blocks; stop from another thread
 changes.stop(); // stop continuous feed
 
 

Since:

0.0.1

See Also:

ChangesResult, Databases - get changes

Method Summary

Modifier and Type	Method and Description
Changes	continuousChanges() Requests Change notifications of feed type continuous.
Changes	descending(boolean descending)
Changes	filter(java.lang.String filter) Specify a filter function to apply to the changes feed.
ChangesResult	getChanges() Requests Change notifications of feed type normal.
boolean	hasNext() Checks whether a feed is available in the continuous stream, blocking until a feed is received.
Changes	heartBeat(long heartBeat) Enable an empty line heartbeat for longpoll or continuous feeds for when there have been no changes.
Changes	includeDocs(boolean includeDocs)
Changes	limit(int limit) Limit the number of rows to return.
ChangesResult.Row	next()
Changes	parameter(java.lang.String name, java.lang.String value) Add a custom query parameter to the _changes request.
Changes	since(java.lang.String since) Return only changes after the specified sequence identifier.
void	stop() Stops a running continuous feed.
Changes	style(java.lang.String style) Configures how many changes are returned "main_only" for the winning revision only or "all_docs" to also include leaf revisions.
Changes	timeout(long timeout) Configure a timeout for the changes feed.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

continuousChanges

public Changes continuousChanges()

Requests Change notifications of feed type continuous.

Feed notifications are accessed in an iterator style.

This method will connect to the changes feed; any configuration options applied after calling it will be ignored.

Note that in some versions of Apache CouchDB and Cloudant the HTTP response headers will be delayed until the first change or heartbeat is sent (see https://github.com/apache/couchdb/issues/985). As such this method may block for up to the heartbeat duration if there are no changes to be received from the database immediately.

Returns:

this Changes instance connected to a continuous feed, use hasNext() and next() to iterate the changes.

hasNext

public boolean hasNext()

Checks whether a feed is available in the continuous stream, blocking until a feed is received.

Returns:

true if there is a change

next

public ChangesResult.Row next()

Returns:

The next feed in the stream.

stop

public void stop()

Stops a running continuous feed.

getChanges

public ChangesResult getChanges()

Requests Change notifications of feed type normal.

Returns:

ChangesResult encapsulating the normal feed changes

since

public Changes since(java.lang.String since)

Return only changes after the specified sequence identifier.

Parameters:

since - sequence identifier or "now"

Returns:

this Changes instance

limit

public Changes limit(int limit)

Limit the number of rows to return.

Parameters:

limit - the number of rows

Returns:

this Changes instance

heartBeat

public Changes heartBeat(long heartBeat)

Enable an empty line heartbeat for longpoll or continuous feeds for when there have been no changes.

Parameters:

heartBeat - time in milliseconds after which an empty line is sent

Returns:

this Changes instance

timeout

public Changes timeout(long timeout)

Configure a timeout for the changes feed.

Parameters:

timeout - time in milliseconds to wait for data

Returns:

this Changes instance

filter

public Changes filter(java.lang.String filter)

Specify a filter function to apply to the changes feed.

Parameters:

filter - name of the design document filter function e.g "designDoc/filterFunction"

Returns:

this Changes instance

includeDocs

public Changes includeDocs(boolean includeDocs)

Parameters:

includeDocs - whether to include document content in the returned rows

Returns:

this Changes instance

style

public Changes style(java.lang.String style)

Configures how many changes are returned "main_only" for the winning revision only or "all_docs" to also include leaf revisions.

Parameters:

style - "main_only" or "all_docs"

Returns:

this Changes instance

descending

public Changes descending(boolean descending)

Parameters:

descending - true to return changes in descending order

Returns:

this Changes instance

Since:

2.5.0

parameter

public Changes parameter(java.lang.String name,
                         java.lang.String value)

Add a custom query parameter to the _changes request. Useful for specifying extra parameters to a filter function for example.

Parameters:

name - the name of the query parameter

value - the value of the query parameter

Returns:

this Changes instance

Since:

2.5.0