DatasyncManager

public final class DatasyncManager : CustomDebugStringConvertible
extension DatasyncManager: WebcomCombinable

An object that creates references to database nodes and stores event subscriptions.

The DatasyncManager.node(for:) method or the equivalent (_:_:) operator create a DatasyncNode instance, which is a reference to a database node.

When such a node reference, created from a given manager instance, subscribes to an event with the DatasyncNode.subscribe(to:childrenConstraint:stores:file:line:queue:onEvent:onCompletion:) method, setting the stores parameter to true (which is its default value), the returned subscription is stored by that manager. When the manager instance is deinitialized, it implicitly cancels all those stored event subscriptions automatically, including subscriptions that have other references. It is also possible to explicitly cancel an event subscription by calling the DatasyncSubscription.cancel() method manually.

An implicit cancellation and an explicit cancellation do not have the same effect when DatasyncManager.defaultCompletedSubscriptionPolicy is DatasyncCompletedSubscriptionPolicy.keepUpdatingDataWhenImplicit.

Managers are designed to be used as properties in view controllers, in order to bind their respective lifecycles. The view controller uses this manager to create node references and subscribe to events. Thanks to ARC (automatic reference counting), the subscriptions are automatically cancelled when the view controller is unloaded.

Stored Properties

API

  • Returns a reference to a database node.

    This method behaves like the node(for:) method, with the difference it throws instead of returning nil.

    Throws

    A WebcomError value when the path is syntactically not valid.

    Declaration

    Swift

    public func nodeThrows(for path: String) throws -> DatasyncNode

    Parameters

    path

    The absolute path of the node to refer.

    Return Value

    A reference to the node corresponding to the path when the path is valid.

  • Returns a reference to a database node.

    This method only returns nil when the path is ill-formed, that is when it contains forbidden characters. All nodes always exists: this method always returns a plain node reference when the path is syntactically valid. From a theoretical point of view, the concept on existence is a nonsense. From a practical point of view, we can consider that a node exists when its value is not null (the JSON null value, not to be confused with the Swift nil keyword).

    Creating a node reference is an extremely light-weight operation, so as many as desired can be created without worrying about wasting bandwidth or memory. It is possible to create several references for the same path. Each piece of code should declare the references it needs, without trying to factorize or cache anything.

    The path consists of segments separated by / (slash) characters. Each segment corresponds to a move in the database tree:

    • The starting point is the root node of the database tree
    • The . segment is a no-operation.
    • The .. segment indicates to go one level up in the tree. When already at the root node, this is a no-operation.
    • The empty segment, when using a / at the beginning or at the end of the path, or when using several consecutive /, is a no-operation.
    • Any other valid segment indicates to go one level down towards the so-named child.

    Examples:

    • If path is equal to foo, /foo, foo/ or /foo/, the path of the resulting node is /foo.
    • If path is equal to foo/bar, /foo/./bar or foo/geek/../bar/, the path of the resulting node is /foo/bar.
    • If path is equal to foo/bar/../geek/noob or /foo/bar/../geek/noob/. or foo//bar/../geek/./noob/., the path of the resulting node is /foo/geek/noob.

    • If path is equal to foo/..//.., the resulting node is the root node.

    Declaration

    Swift

    public func node(for path: String) -> DatasyncNode?

    Parameters

    path

    The absolute path of the node to refer. It can start or not with a / (slash) character. It is always absolute.

    Return Value

    A reference to the node corresponding to the path when the path is valid, nil otherwise.

  • Returns a reference to the database root node.

    Declaration

    Swift

    public var rootNode: DatasyncNode { get }

  • Returns a reference to a database node.

    This operator returns:

    manager.node(for: path)

    Declaration

    Swift

    public static func / (manager: DatasyncManager, path: String) -> DatasyncNode?

    Parameters

    manager

    The manager to use to get the node reference.
    path

    The path of the node to refer.

    Return Value

    A reference to the node corresponding to the path when the path is valid, nil otherwise.

  • Subscribes to changes of the state of the web socket opened by the DatasyncService instance which creates this manager.

    The returned subscription is stored by this manager instance, like the DatasyncNode.subscribe(to:childrenConstraint:stores:file:line:queue:onEvent:onCompletion:) method does when the stores parameter is set to true (which is its default value).

    Declaration

    Swift

    @discardableResult
public func subscribeToStateChange(stores: Bool = true, file: StaticString = #fileID, line: UInt = #line, queue: DispatchQueue? = nil, onChange changeCallback: @escaping (_ state: DatasyncState) -> Void, onCompletion completionCallback: (() -> Void)? = nil) -> DatasyncSubscription?

    Parameters

    stores

    Indicates whether the returned subscription should be stored by the manager.
    file

    The file from which the method is called. This is used for debugging purposes.
    line

    The line from which the method is called. This is used for debugging purposes.
    queue

    The queue to which the provided callback dispatches. When nil, the default callback queue of this instance is used.
    changeCallback

    The closure to call when the state of the web socket changes.
    state

    The new state of the web socket.
    completionCallback

    The closure to call when the subscription is cancelled.

    Return Value

    An instance describing the subscription, or nil if the subscription failed.

  • Subscribes to changes of the user currently authenticated on the web socket opened by the DatasyncService instance which creates this manager.

    The returned subscription is stored by this manager instance, like the DatasyncNode.subscribe(to:childrenConstraint:stores:file:line:queue:onEvent:onCompletion:) method does when the stores parameter is set to true (which is its default value).

    Declaration

    Swift

    @discardableResult
public func subscribeToCurrentUIDChange(stores: Bool = true, file: StaticString = #fileID, line: UInt = #line, queue: DispatchQueue? = nil, onChange changeCallback: @escaping (_ currentUID: String?) -> Void, onCompletion completionCallback: (() -> Void)? = nil) -> DatasyncSubscription?

    Parameters

    stores

    Indicates whether the returned subscription should be stored by the manager.
    file

    The file from which the method is called. This is used for debugging purposes.
    line

    The line from which the method is called. This is used for debugging purposes.
    queue

    The queue to which the provided callback dispatches. When nil, the default callback queue of this instance is used.
    changeCallback

    The closure to call when the state of the web socket changes.
    currentUID

    The unique identifier of the user currently authenticated on the web socket if any, nil otherwise.
    completionCallback

    The closure to call when the subscription is cancelled.

    Return Value

    An instance describing the subscription, or nil if the subscription failed.

  • Cancels all stored subscriptions.

    Subscriptions are stored by the DatasyncNode.subscribe(to:childrenConstraint:stores:file:line:queue:onEvent:onCompletion:) method with nodes belonging to this manager instance, when the stores parameter is set to true (which is its default value).

    Usually, there is no need to call this method since it is done automatically when this instance is deinitialized.

    Declaration

    Swift

    public func unsubscribeFromAll()

  • Returns the creation date of a timestamp-based node key.

    Warning

    This method was deprecated in version 2.2.0. Use pushIdentifier.date instead.

    Declaration

    Swift

    @available(*, deprecated, renamed: "WebcomKey.date")
public func date(fromPushIdentifier pushIdentifier: WebcomKey) -> Date?

  • Encodes the input string to get a value that may be used as a valid node key. Returns a string that may be used as a valid node key to represent a given value.

    The returned value may be decoded as follow to retrieve the input value:

    • in Swift, use the removingPercentEncoding property,

    • in JavaScript (e.g. for security rules), use the decodeURIComponent() global function.

    Declaration

    Swift

    public func encodedKey(from rawKey: String) -> String?

    Parameters

    rawKey

    The input string to encode.

    Return Value

    An encoded form of the input string, or nil when the input string cannot be encoded.

  • Runs a block the first time this method is used for a given instance.

    The first time this method is called for a given instance, the block is run. On subsequent calls on the same instance, this method is a no-operation, whether the block is the same of different from the first call.

    This method is designed to be used in the viewDidAppear(_:) or the viewWillAppear(_:) method of a view controller to do some subscriptions, that need the user interface to be already loaded.

    Declaration

    Swift

    public func runOnlyFirstTime(_ block: () -> Void)

    Parameters

    block

    The block to run.

CustomDebugStringConvertible Protocol

  • Declaration

    Swift

    public var debugDescription: String { get }

Combine Module

  • The type that wraps DatasyncManager in order to enrich it with a Combine-based API.

    See also the documentation section of WebcomWrapper for the corresponding wrapped type.

    To use this type, import the following dependency in your code:

    import WebcomCombine
    See more

    Declaration

    Swift

    public final class CombineWrapper : WebcomWrapper, CustomDebugStringConvertible

  • The wrapping instance, which has a Combine-based API.

    Declaration

    Swift

    public var forCombine: CombineWrapper { get }