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

Copied to clipboard!
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 scope
Possible values: all, in, out, none
users
String

(none)
Subscribe to users entering or leaving the room
Possible 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

Copied to clipboard!
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

Copied to clipboard!
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

Copied to clipboard!
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

Copied to clipboard!
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());
}