This class represents a single record - an observable dataset returned by client.record.getRecord(_:)
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()
class func isReady() -> Bool
Indicates whether the record data has been loaded from the platform.
isDestroyed()
class func isDestroyed() -> Bool
Return whether the record data has been destroyed. To continue using the record it will need to be re-requested via client.record.getRecord(_:)
.
version()
class func version() -> Int
Return the record version.
name()
class func name() -> String
Return the record name.
addRecordEventsListener(_:)
class func addRecordEventsListener(_ listener: RecordEventsListener) -> Self
argument | type | description |
---|---|---|
listener | RecordEventsListener | The listener to add |
Adds a Listener that will be invoked if a discard, delete or error event occurs.
func onRecordHasProviderChanged(recordName: String, hasProvider: Bool) -> Void {
// handle provider changed
}
func onRecordDeleted(recordName: String) -> Void {
// handle record deleted
}
func onRecordDiscarded(recordName: String) -> Void {
// handle record discarded
}
} let record = client.record.getRecord("users/A") record.addRecordEventsListener(MyRecordEventsListener())
removeRecordEventsListener(_:)
class func removeRecordEventsListener(_ listener: RecordEventsListener) -> Self
argument | type | description |
---|---|---|
listener | RecordEventsListener | The listener to remove |
Remove listener added via addRecordEventsListener(_:)
.
setMergeStrategy(_:)
class func setMergeStrategy(_ strategy: MergeStrategy) -> Self
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.
setMergeStrategy(_:)
class func setMergeStrategy(_ strategy: RecordMergeStrategy) -> Self
argument | type | description |
---|---|---|
strategy | RecordMergeStrategy | The custom merge strategy to use |
Set a custom merge strategy for the record.
get()
class func get() -> JsonElement
Gets the entire record data and should always return a JsonObject that might be empty.
get(_:)
class func get(_ path: String) -> JsonElement
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()
.
set(_:)
class func set(_ value: Any) throws -> Self
argument | type | description |
---|---|---|
value | Any | 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.
set(_:value:)
class func set(_ path: String, value: Any) throws -> Self
argument | type | description |
---|---|---|
path | String | The path with the JsonElement at which to set the value |
value | Any | 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.
setWithAck(_:)
class func setWithAck(_ data: Any) -> RecordSetResult
argument | type | description |
---|---|---|
data | Any | 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.
setWithAck(_:data:)
class func setWithAck(_ path: String, data: Any) -> RecordSetResult
argument | type | description |
---|---|---|
path | String | The path with the JsonElement at which to set the value |
data | Any | 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.
subscribe(_:)
class func subscribe(_ callback: RecordPathChangedCallback) throws -> Self
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.
subscribe(_:callback:)
class func subscribe(_ path: String, callback: RecordPathChangedCallback) throws -> Self
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.
unsubscribe(_:)
class func subscribe(_ callback: RecordChangeCallback) throws -> Self
argument | type | description |
---|---|---|
recordChangeCallback | RecordChangeCallback | The listener to add |
Removes a subscription previously made using subscribe(_:)
.
unsubscribe(_:callback:)
class func unsubscribe(_ path: String, callback: RecordPathChangedCallback) throws -> Self
argument | type | description |
---|---|---|
path | String | The path to unsubscribe from |
callback | RecordPathChangedCallback | The listener to remove |
Remove the listener added via subscribe(_:callback:)
.
discard()
class func discard() throws -> Self
Discards the record. This should be called whenever a part of an application no longer requires a record previously requested via client.record.getRecord(_:)
.
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(_:)
Once the record is successfully discard, the client will be notified via onRecordDiscarded(_:)
delete()
class func delete() throws -> Self
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(_:)