Changes API: What is Changes API?

The RavenDB client offers a push notification feature that allows you to receive messages from a server about events that occurred there. You are able to subscribe to events for all documents or indexes as well as to indicate a particular one that you are interested in. This mechanism lets you notify users if something has changed without the need to do any expensive polling.

Accessing Changes API

The changes subscription is accessible by a document store.

public IDatabaseChanges changes();

public IDatabaseChanges changes(String database);

Connection properties

IDatabaseChanges has three properties that are related to the server connection:

// returns state of the connection
boolean isConnected();

// the event raised if a connection state is changed
public void addConnectionStatusChanged(EventHandler<VoidArgs> handler);

public void removeConnectionStatusChanges(EventHandler<VoidArgs> handler);

Subscriptions

In order to retrieve notifications you have to subscribe to server-side events by using one of the following methods:

• ForAllDocuments
• ForAllIndexes
• ForAllReplicationConflicts
• ForAllTransformers
• ForBulkInsert
• ForDocument
• ForDocumentsInCollection
• ForDocumentsOfType
• ForDocumentsStartingWith
• ForIndex
• ForAllDataSubscriptions

Unsubscribing

In order to end subscription (stop listening for particular notifications) you must close() it.

Closeable subscription = store
  .changes()
  .forAllDocuments()
  .subscribe(Observers.create(new Action1<DocumentChangeNotification>() {
    @Override
    public void apply(DocumentChangeNotification change) {
      System.out.println(change.getType() + " on document " + change.getId());
    }
  }));

try {
  // application code here
} finally {
  if (subscription != null) {
    subscription.close();
  }
}