What Is the Changes API



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.

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