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

Fetch transactions in batches ordered chronologically using a startId to get the next batch of transactions. 

Request

The fetch transactions GET/POST request receives the storage unit name and optionally the scope 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, an includeFirst parameter to indicate whether or not to include the transaction of startId or start from the next one and a zone parameter to indicate from which zone to get transactions from (all if omitted).

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

Response

Responds with a 200 response code. The response body contains an array of transactions and a next transaction number for the next batch call. If there are no more transactions, the next transaction number is not part of the response. 

{"transactions": 
	[
		{
			"transaction": {
				"_id": "578fbc689eabceb422d3b4b7",
				"__v": 0,"fileUpdate": false,
				"scope": "connector",
				"recordId": "APP_ZONE:995BB4838C40E9900FD098F6205824D1",
				"timestamp": "2016-07-20T18:01:12.234Z",
				"type": "ADD"
			},
			"record": {
				"content": {
					"connector": {...}
				},
				"key": "APP_ZONE:995BB4838C40E9900FD098F6205824D1"
			}
		},
		{
			"transaction": {
				"_id": "578fbc689eabceb422d3b4b8",
				"__v": 0,"fileUpdate": false,
				"scope": "connector",
				"recordId": "APP_ZONE:995BB4838C40E9900FD098F6205824D2",
				"timestamp": "2016-07-20T18:01:15.234Z",
				"type": "ADD"
			},
			"record": {
				"content": {
					"connector": {...}
				},

				"key": "APP_ZONE:995BB4838C40E9900FD098F6205824D2"

			}

		}
	],
	"nextTransactionNum": "578fbc689eabceb422d3b4cb"
}