How to create a data subscription?

In order to create a data subscription you have to specify the criteria that documents must match to be incorporated into subscription results.

long create(Class<?> expectedType, SubscriptionCriteria criteria);

long create(Class<?> expectedType, SubscriptionCriteria criteria, String database);

long create(SubscriptionCriteria criteria);

long create(SubscriptionCriteria criteria, String database);

In SubscriptionCriteria, where you can specify the following filters:

• KeyStartsWith - a document id must starts with a specified prefix,
• BelongsToAnyCollection - list of collections that the subscription deals with,
• PropertiesMatch - map of field names and related values that a document must have,
• PropertiesNotMatch - map of field names and related values that a document must not have,
• StartEtag - an etag of a document which a subscription is going to consider as already acknowledged and start processing docs with higher etags.

BelongsToAnyCollection will be automatically filled in by a single value based on the entity type (see findTypeTagName convention), when using override with clazz parameter.

Additionally the criteria object has StartEtag property which sets the etag of the first document that the subscription starts from (in large databases can be used to skip documents that you already know they won't match the given criteria).

The execution of create method will create a data subscription in a database and return its identifier (you can see Raven/Subscriptions/[id] documents in the database). This identifier is needed to open the subscription so you need to keep that information to be able to make use of it later.

Example I

SubscriptionCriteria criteria = new SubscriptionCriteria();
criteria.setKeyStartsWith("employees/");
criteria.propertyNotMatch("Address.City", RavenJToken.fromObject("Seattle"));
long id = store.subscriptions().create(criteria);

In this case we want to get all documents that id starts with employees/ but does not contain Address.City field with value Seattle. Note that although we specified employees/ prefix id it doesn't mean we will get documents belonging to the same collection. It can return a developer (employees/developers/1) as well as a manager (employees/managers/1), anyhow we can be sure that none of them is living in Seattle.

Example II

QOrder o = QOrder.order;
SubscriptionCriteria criteria = new SubscriptionCriteria();
criteria.propertyMatch(o.company, "company/1");
long id = store.subscriptions().create(criteria);

In this case, it will give us all the orders, but only those which are handled by employees/1 employee. Here we used generic type criteria, so we can specify properties filtering in strongly typed way. Also we can be sure that all returned documents belong to Orders collection (so we will be able to open the strongly typed subscription).