subscribe #

Subscribes by providing a set of filters: messages, document changes and, optionally, user events matching the provided filters will generate real-time notifications, sent to you in real-time by Kuzzle.

Arguments #

public String subscribe(
  String index,
  String collection,
  String filters,
  io.kuzzle.sdk.NotificationListener listener,
  io.kuzzle.sdk.RoomOptions options
)
public String subscribe(
  String index,
  String collection,
  String filters,
  io.kuzzle.sdk.NotificationListener listener
)

Arguments	Type	Description
`index`	String	Index name
`collection`	String	Collection name
`filters`	String	JSON string representing a set of filters following Koncorde syntax
`listener`	io.kuzzle.sdk.NotificationListener	Listener function to handle notifications
`options`	io.kuzzle.sdk.RoomOptions	Subscription options

options #

Additional subscription options.

Property	Type (default)	Description
`scope`	String (`all`)	Subscribe to document entering or leaving the scopePossible values: `all`, `in`, `out`, `none`
`users`	String (`none`)	Subscribe to users entering or leaving the roomPossible values: `all`, `in`, `out`, `none`
`subscribeToSelf`	boolean (`true`)	Subscribe to notifications fired by our own queries
`volatile`	String (`null`)	JSON string representing subscription information, used in user join/leave notifications

Return #

Return the room ID.

Exceptions #

Throws a io.kuzzle.sdk.KuzzleException if there is an error. See how to handle error.

Usage #

Simple subscription to document notifications

String filters = "{ \"exists\": \"name\" }";
NotificationListener listener = new NotificationListener() {
  public void onMessage(NotificationResult notification) {
    String id = notification.getResult().getId();
    if (notification.getScope().equals("in")) {
      System.out.println("Document " + id + " enter the scope");
    } else {
      System.out.println("Document " + id + " leave the scope");
    }
  }
};
String document = "{ \"name\": \"nina vkote\", \"age\": 19 }";
try {
  kuzzle.getRealtime().subscribe(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    listener
  );
  kuzzle.getDocument().create(
    "nyc-open-data",
    "yellow-taxi",
    "nina-vkote",
    document
  );
} catch (KuzzleException e) {
  System.err.println(e.getMessage());
}

Subscription to document notifications with scope option

NotificationListener listener = new NotificationListener() {
  public void onMessage(NotificationResult notification) {
    System.out.println("Document moved " + notification.getScope() + " from the scope");
  }
};
try {
  String filters = "{ \"range\": { \"age\": { \"lte\": 20 } } }";
  RoomOptions options = new RoomOptions();
  options.setScope("out");
  // Subscribe to notifications when document leaves the scope
  kuzzle.getRealtime().subscribe(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    listener,
    options
  );
  String document = "{ \"name\": \"nina vkote\", \"age\": 19 }";
  // The document is in the scope
  kuzzle.getDocument().create(
    "nyc-open-data",
    "yellow-taxi",
    "nina-vkote",
    document
  );
  // The document isn't in the scope anymore
  kuzzle.getDocument().update(
    "nyc-open-data",
    "yellow-taxi",
    "nina-vkote",
    "{ \"age\": 42 }"
  );
} catch (KuzzleException e) {
  System.err.println(e.getMessage());
}

Subscription to message notifications

String filters = "{ \"exists\": \"name\" }";
NotificationListener listener = new NotificationListener() {
  public void onMessage(NotificationResult notification) {
    System.out.println("Message notification received");
  }
};
try {
  kuzzle.getRealtime().subscribe(
    "i-dont-exist",
    "in-database",
    "{}",
    listener
  );
  String message = "{ \"metAt\": \"Insane\", \"hello\": \"world\" }";
  kuzzle.getRealtime().publish("i-dont-exist", "in-database", message);
} catch (KuzzleException e) {
  System.err.println(e.getMessage());
}

Subscription to user notifications

String filters = "{ \"exists\": \"name\" }";
RoomOptions options = new RoomOptions();
options.setUsers("all");
NotificationListener listener = new NotificationListener() {
  public void onMessage(NotificationResult notification) {
    System.out.println(notification.getVolatiles());
    // "{ "username\": "nina vkote" }"
    System.out.println("Currently " + notification.getResult().getCount() + " users in the room");
  }
};
try {
  kuzzle.getRealtime().subscribe(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    listener,
    options
  );
  // Instantiates a second kuzzle client: multiple subscriptions
  // made by the same user will not trigger "new user" notifications
  WebSocket ws2 = new WebSocket("kuzzle");
  Kuzzle kuzzle2 = new Kuzzle(ws2);
  kuzzle2.connect();
  // Set some volatile data
  RoomOptions options2 = new RoomOptions();
  options2.setVolatiles("{ \"username\": \"nina vkote\" }");
  // Subscribe to the same room with the second client
  kuzzle2.getRealtime().subscribe(
    "nyc-open-data",
    "yellow-taxi",
    filters,
    listener,
    options2
  );
} catch (KuzzleException e) {
  System.err.println(e.getMessage());
}

Edit this page on Github