Class Record - deepstreamHub Java SDK Record

This class represents a single record - an observable dataset returned by client.record.getRecord(recordName)

Methods

boolean isReady()

Indicates whether the record data has been loaded from the platform.

boolean isDestroyed()

Return whether the record data has been destroyed. To continue using the record it will need to be re-requested via client.record.getRecord(name).

int version()

Return the record version.

String name()

Return the record name.

Record addRecordEventsListener(RecordEventsListener listener)

Adds a Listener that will be invoked if a discard, delete or error event occurs.

Show example...

Record record = client.record.getRecord("users/A");
record.addRecordEventsListener(new RecordEventsListener() {
  public void onError(String recordName, Event errorType, String errorMessage) {
    // handle error
  }



  public void onRecordHasProviderChanged(String recordName, boolean hasProvider) {
    // handle provider changed
  }



  public void onRecordDeleted(String recordName) {
    // handle record deleted
  }



  public void onRecordDiscarded(String recordName) {
    // handle record discarded
  }
});

Record removeRecordEventsListener(RecordEventsListener listener)

Remove listener added via addRecordEventsListener(listener).

Record setMergeStrategy(MergeStrategy strategy)

Set a merge strategy that comes with deepstream. These are currently LOCAL_WINS and REMOTE_WINS.

Show example...

record.setMergeStrategy(MergeStrategy.LOCAL_WINS); // always use local version during conflicts



record.setMergeStrategy(MergeStrategy.REMOTE_WINS); // always use remote version during conflicts

Record setMergeStrategy(RecordMergeStrategy strategy)

Set a custom merge strategy for the record.

Show example...

class CustomMergeStrategy implements RecordMergeStrategy {
  public JsonElement merge(Record record, JsonElement remoteValue, int remoteVersion) throws RecordMergeStrategyException {
    // custom merge strategy logic here
    return null;
  }
}



record.setMergeStrategy(new CustomMergeStrategy());

JsonElement get()

Gets the entire record data and should always return a JsonObject that might be empty. Show example...

JsonObject data = record.get();
// {
//   "name": "Homer",
//   "lastname": "Simpson"
// }

JsonElement get(String path)

Gets the value at the path indicated. Because of the JSON library used, any values retrieved from the JsonObject will need to be cast accordingly, ie. object.getAsString() or object.getAsInt().

Show example...

// with record data
// {
//  "name": "Yasser",
//  "pets": [ {
//    "type": "Dog",
//    "name": "Whiskey",
//    "age": 3
//  } ]
// }
// we can do
record.get("name") // JsonElement.getAsString()
record.get("pets[0]") // JsonElement.getAsJsonObject()
record.get("pets[0].age") // JsonElement.getAsInt()

Record set(Object value) throws DeepstreamRecordDestroyedException

Set the value for the entire record.

Make sure that the Object passed in can be serialised to a JsonElement, otherwise it will throw a IllegalStateException. Best way to guarantee this is by setting Json friendly objects, such as Map. Since this is a root the object should also not be a primitive.

Show example...

JsonObject data = new JsonObject();
data.addProperty.addProperty("name", "Homer");
record.set(data);

Record set(String path, Object value) throws DeepstreamRecordDestroyedException

Set the value for a specific path in the Record data.

Make sure that the Object passed in can be serialised to a JsonElement, otherwise it will throw a IllegalStateException.

The best way to guarantee this is by setting Json friendly objects, such as Map.

Show example...

record.set("lastname", "Simpson");

RecordSetResult setWithAck(Object data)

Set the value for the entire record.

Make sure that the Object passed in can be serialised to a JsonElement, otherwise it will throw a IllegalStateException. Best way to guarantee this is by setting Json friendly objects, such as Map. Since this is a root the object should also not be a primitive.

The RecordSetResult returned by this function will contain an error string or null, indicating the write success.

Show example...

JsonObject data = new JsonObject();
data.addProperty("firstname", "Homer");
RecordSetResult result = record.setWithAck(data);
if (result.getResult() != null) {
  // handle error writing to record
}

RecordSetResult setWithAck(String path, Object data)

Set the value for a specific path in the Record data.

Make sure that the Object passed in can be serialised to a JsonElement, otherwise it will throw a IllegalStateException.

The best way to guarantee this is by setting Json friendly objects, such as Map.

The RecordSetResult returned by this function will contain an error string or null, indicating the write success.

Show example...

RecordSetResult result = record.setWithAck("lastname", "Simpson");
if (result.getResult() != null) {
  // handle error writing to record
}

Record subscribe(RecordPathChangedCallback callback) throws DeepstreamRecordDestroyedException

Registers a callback that will be invoked whenever the record's value changes. Optionally passing the argument true will cause the callback to be invoked immediately with the records value.

Show example...

record.subscribe(new RecordChangedCallback() {
    @Override
    public void onRecordChanged(String recordName, JsonElement data) {
        // handle record changed
    }
});

Record subscribe(String path, RecordPathChangedCallback callback) throws DeepstreamRecordDestroyedException

Registers a callback that will be invoked whenever anything in the records path changes. Optionally passing the argument true will cause the callback to be invoked immediately with the records value.

Show example...

record.subscribe("lastname", new RecordPathChangedCallback() {
  public void onRecordPathChanged(String recordName, String path, JsonElement data) {
    // handle path changed
  }
});

Record subscribe(RecordChangeCallback callback) throws DeepstreamRecordDestroyedException

Removes a subscription previously made using subscribe(callback).

Record unsubscribe(String path, RecordPathChangedCallback callback) throws DeepstreamRecordDestroyedException

Remove the listener added via subscribe(path,callback).

Record discard() throws DeepstreamRecordDestroyedException

Discards the record. This should be called whenever a part of an application no longer requires a record previously requested via client.record.getRecord(recordName).

Calling discard does not guarantee that all subscriptions will be unsubscribed.

If all usages of the same record have been discarded, the record will no longer be updated by deepstreamHub and any further usages will require the record to be retrieved again via client.record.getRecord(recordName)

Once the record is successfully discard, the client will be notified via onRecordDiscarded(name)

Record delete() throws DeepstreamRecordDestroyedException

Deletes the record and notifies other users of its deletion. This in turn will force all clients to discard the record.

Once the record is successfully deleted, clients will be notified via onRecordDeleted(name)