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, indexes, and operations 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 through its IDatabaseChanges
interface.
IDatabaseChanges changes();
IDatabaseChanges changes(String database);
Parameters | ||
---|---|---|
database | String | Name of database to open changes API for. If null , the Database configured in DocumentStore will be used. |
Return value | |
---|---|
IDatabaseChanges | Instance implementing IDatabaseChanges interface. |
Connection interface
IDatabaseChanges
inherits from IConnectableChanges<TChanges>
interface that represent the connection.
public interface IConnectableChanges<TChanges extends IDatabaseChanges> extends CleanCloseable {
boolean isConnected();
void ensureConnectedNow();
void addConnectionStatusChanged(EventHandler<VoidArgs> handler);
void removeConnectionStatusChanged(EventHandler<VoidArgs> handler);
void addOnError(Consumer<Exception> handler);
void removeOnError(Consumer<Exception> handler);
}
Subscriptions
In order to retrieve notifications you have to subscribe to server-side events by using one of the following methods:
- forAllDocuments
- forAllIndexes
- forAllOperations
- forDocument
- forDocumentsInCollection
- forDocumentsStartingWith
- forIndex
- forOperationId
Unsubscribing
In order to end subscription (stop listening for particular notifications) you must close
it.
IDatabaseChanges subscription = store.changes();
subscription.ensureConnectedNow();
subscription.forAllDocuments().subscribe(Observers.create(change -> {
System.out.println(change.getType() + " on document " + change.getId());
}));
try {
// application code here
} finally {
if (subscription != null) {
subscription.close();
}
}
Remarks
Note
One or more open Changes API connections will prevent a database from becoming idle and unloaded, regardless of configuration value for database idle timeout