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

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.

Show example...

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.

Show example...

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.

Show example...

get()

class func get() -> JsonElement

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

Show example...

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

Show example...

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.

Show example...

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.

Show example...

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.

Show example...

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.

Show example...

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.

Show example...

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.

Show example...

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(_:)