why deepstreamHub? compare us getting started faq
use cases
products
developers
company
blog contact

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

Records are the documents in deepstreamHub’s realtime datastore. A record is identified by a unique id and can contain any kind of JSON data. Clients and backend processes can create, read, write, update and observe the entire record as well as paths within it. Any change is immediately synchronized amongst all connected subscribers.

Records can be arranged in lists and collections and can contain references to other records to allow for the modelling of relational data structures.

You can learn more about records in the records tutorial.

Methods

isReady()

boolean isReady()
Indicates whether the record data has been loaded from the platform.

isDestroyed()

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).

version()

int version()
Return the record version.

name()

String name()
Return the record name.

addRecordEventsListener(listener)

Record addRecordEventsListener(RecordEventsListener listener)
argument type description
listener RecordEventsListener The listener to add

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

Show example...

removeRecordEventsListener(listener)

Record removeRecordEventsListener(RecordEventsListener listener)
argument type description
listener RecordEventsListener The listener to remove

Remove listener added via addRecordEventsListener(listener).

setMergeStrategy(mergeStrategy)

Record setMergeStrategy(MergeStrategy strategy)
argument type description
strategy MergeStrategy The name of the built in merge strategy to use

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

Show example...

setMergeStrategy(recordMergeStrategy)

Record setMergeStrategy(RecordMergeStrategy strategy)
argument type description
strategy RecordMergeStrategy The custom merge strategy to use

Set a custom merge strategy for the record.

Show example...

get()

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

get(path)

JsonElement get(String path)
argument type description
path String The location of the data to retrieve

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...

set(value)

Record set(Object value) throws DeepstreamRecordDestroyedException
argument type description
value Object The value to set

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...

set(path,value)

Record set(String path, Object value) throws DeepstreamRecordDestroyedException
argument type description
path String The path with the JsonElement at which to set the value
value Object The value to set

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...

setWithAck(data)

RecordSetResult setWithAck(Object data)
argument type description
data Object The value to set

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...

setWithAck(path,data)

RecordSetResult setWithAck(String path, Object data)
argument type description
path String The path with the JsonElement at which to set the value
data Object The value to set

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...

subscribe(callback)

Record subscribe(RecordPathChangedCallback callback) throws DeepstreamRecordDestroyedException
argument type description
callback RecordPathChangedCallback The listener to add

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...

subscribe(path,callback)

Record subscribe(String path, RecordPathChangedCallback callback) throws DeepstreamRecordDestroyedException
argument type description
path String The path with the JsonElement at which to set the value
callback RecordPathChangedCallback The listener to add

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...

unsubscribe(callback)

Record subscribe(RecordChangeCallback callback) throws DeepstreamRecordDestroyedException
argument type description
recordChangeCallback RecordChangeCallback The listener to add

Removes a subscription previously made using subscribe(callback).

unsubscribe(path,callback)

Record unsubscribe(String path, RecordPathChangedCallback callback) throws DeepstreamRecordDestroyedException
argument type description
path String The path to unsubscribe from
callback RecordPathChangedCallback The listener to remove

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

discard()

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)

delete()

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)