What Is the Changes API
- The Changes API is a Push Notifications service, that allows a RavenDB Client to receive messages from a RavenDB Server regarding events that occurred on the server.
- A client can subscribe to events related to documents, indexes, operations, counters, and time series.
-
Using the Changes API allows you to notify users of various changes without requiring any expensive polling.
-
In this page:
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);
}
Subscribing
To receive notifications regarding server-side events, subscribe using one of the following methods.
- forAllDocuments
- forAllIndexes
- forAllOperations
- forDocument
- forDocumentsInCollection
- forDocumentsStartingWith
- forIndex
- forOperationId
Unsubscribing
To end a subscription (stop listening for particular notifications) you must
close
the subscription.
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();
}
}
Note
One or more open Changes API connections will prevent a database from becoming
idle and unloaded, regardless of the configuration value for database idle timeout.
Changes API -vs- Data Subscriptions
Changes API and Data Subscription
are services that a RavenDB Server provides subscribing clients.
Both services respond to events that take place on the server, by sending updates
to their subscribers.
-
Changes API is a Push Notifications Service.
-
Changes API subscribers receive notifications regarding events that took place on the server, without receiving the actual data entities affected by these events.
For the modification of a document, for example, the client will receive a DocumentChange object with details like the document's ID and collection name. -
The server does not keep track of sent notifications or checks clients' usage of them. It is a client's responsibility to manage its reactions to such notifications.
-
-
Data Subscription is a Data Consumption Service.
- A Data Subscription task keeps track of document modifications in the database and delivers the documents in an orderly fashion when subscribers indicate they are ready to receive them.
- The process is fully managed by the server, leaving very little for the subscribers to do besides consuming the delivered documents.
Data Subscriptions | Changes API | |
---|---|---|
What can the server Track | Documents Revisions |
Documents Indexes Operations Counters Time Series |
What can the server Deliver | Documents Revisions |
Notifications |
Management | Managed by the Server | Managed by the Client |