The subscription API provides access to the transaction log, in chronological order, for bulk and real-time storage unit updates.

Subscribe

Provides a subscription service to the transaction log of a storage unit. The service will automatically push new transactions and the records linked with each transaction to the subscriber clients. The subscription service uses Server-Sent Events protocol for communication.

Reconnection: If the connection is lost by the client, when reconnecting it will send a last-event-id header with the last transaction id that was received by the client. The subscription service will resume from the last-event-id.

Request

The subscribe GET request receives the storage unit name and optionally the scope to subscribe to in the URL. It can also received a startId parameter to start getting transactions starting on that particular one, a doContentProcessing (default true) boolean parameter to trigger or not the Fetch events from content processing modules, a transactionsOnly (default false) boolean parameter to indicate whether or not the record data should be sent along a add/update transaction and a zone parameter to indicate from which zone to get transactions from (all if omitted).

GET subscription/subscribe/<storage-unit>/<optional-scope>?startId=5644f2d497cc11144081d111&doContentProcessing=true&transactionsOnly=false&zone=LOCAL_ZONE

Java example

Client client = ClientBuilder.newBuilder().register(SseFeature.class).build();
WebTarget target = client.target(new URI("http://localhost:3000/subscription/subscribe/<storage-unit-name>/<scope>"));
EventSource eventSource = EventSource.target(target).reconnectingEvery(2, TimeUnit.SECONDS).build();
EventListener listener = new EventListener(){
  public void onEvent(InboundEvent inboundEvent) {
    System.out.println(inboundEvent.getId() + "; "
    + inboundEvent.readData(String.class));
  }
};    
eventSource.register(listener);
eventSource.open();
...
eventSource.close();

Javascript example

var EventSource = require('eventsource') // https://www.npmjs.com/package/eventsource
var source = new EventSource('http://localhost:3000/subscription/subscriptionEvent/<storage-unit-name>/<scope>')
source.onmessage = function (e) {
    console.log(e.lastEventId + ':' + e.data)
}

Response

The response is of type text/event-stream and remains open until the client decides to unsubscribe. Each transaction log entry is returned as a single event with the transaction id as the event id and the transaction JSON as the data. If the transaction has a content record associated, a second JSON object is sent with the record data as a second data entry on the response, separated from the previous with a single new line. Each new event message is separated by two new lines (\n\n).

id:5644f2d497cc11144081d111\n
data:{"_id" : 5644f2d497cc11144081d111, "scope" : "connector", "recordId" : "LOCAL_ZONE:E0F57D337D5021236E353C7AB305F147", "timestamp" : 2015-11-12T20:13:08.243Z, "type" : "ADD", "__v" : 0}\n
data:{"key": "LOCAL_ZONE:E0F57D337D5021236E353C7AB305F147", "content": {"connector": {"doc": {"test": "data"}}}}\n\n

Fetch Transactions