DataNode

public final class DataNode : Hashable, CustomStringConvertible
extension DataNode: WebcomCombinable

An object that represents a reference to a database node.

By abuse of language, the node reference is sometimes assimilate with the referred node itself. This does not usually preclude understanding. Just keep in mind that there may be several references for the same database node.

Instances are created using the DataService.node(for:) method of a DataService instance.

Stored Properties

  • The absolute path of the node referred by this instance.

    The path consists of the keys of the ancestors of this node, starting from the root of the tree, separated by / (slash) characters. The last segment of the path is the key of this node. The before last segment of the path, if any, is the key of the parent of this node. The path always begins with a /. The path of the root node is "/".

    Declaration

    Swift

    public let path: String

API

  • key

    The key of the node represented by this instance.

    It corresponds to the last segment of the path. It does not contain any / (slash) character. The key of the root node is the empty string ("").

    Since

    2.2.0

    Declaration

    Swift

    public var key: WebcomKey { get }

  • A reference to the parent of the node referred by this instance.

    The root node does not have a parent, so this property returns nil for the root node. For all other nodes, this property never returns nil.

    Note: With a reference to the root node, relativeNode(for: "..") returns a reference to the root node.

    Since

    2.2.0

    Declaration

    Swift

    public var parent: DataNode? { get }

  • Returns a reference to another node, relatively to the node referred by this instance.

    This method always succeeds. If the path is ill-formed, it is the methods of the resulting instance that will fail.

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

    • The starting point is the node corresponding to this instance.
    • 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.

    If the path referred by this node is /foo/bar:

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

    Note: With a reference to the root node, parent returns nil.

    Since

    2.2.0

    Declaration

    Swift

    public func relativeNode(for path: String) -> DataNode

    Parameters

    path

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

    Return Value

    A reference to the node corresponding to the relative path.

  • Returns a reference to a database node, relatively to a base node.

    This operator returns:

    node.relativeNode(for: path)

    Since

    2.2.0

    Declaration

    Swift

    public static func / (node: DataNode, path: String) -> DataNode

    Parameters

    node

    A reference to the base node.
    path

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

    Return Value

    A node reference.

  • Gets the value of the node referred by this instance.

    The value is not returned synchronously, but a callback is called asynchronously with the value as its parameter.

    The decodedValue(session:queue:then:) method can be used to get decoded values. The keys(session:) method can be used to get only the keys of the children of the node.

    Declaration

    Swift

    public func value(session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: @escaping WebcomResult<DataValue>.Callback)

    Parameters

    queue

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

    The closure to call upon completion. In case of success, it is called with the current value of the referred node. In case of failure, it is called with a WebcomError value indicating the reason of the failure.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

  • Gets the value of the node referred by this instance.

    The value is not returned synchronously, but a callback is called asynchronously with the value as its parameter.

    This method behaves like the value(session:queue:then:) method with a callback that receives a decoded value in case of success. When the value cannot be decoded, the completionCallback is called with an error having the WebcomError.SDKCode.decodingFailed code. If this behavior does not fit your needs, use the value(session:queue:then:) method and process the callback parameter as expected.

    The decoding is done using the WebcomApplication.jsonDecoder of the WebcomApplication from which this node derives.

    Declaration

    Swift

    public func decodedValue<T>(session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: @escaping WebcomResult<T>.Callback) where T : Decodable

    Parameters

    queue

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

    The closure to call upon completion. In case of success, it is called with the decoded current value of the referred node. In case of failure, it is called with a WebcomError value indicating the reason of the failure.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

  • Gets the keys of the children of the node referred by this instance.

    When the node has no child, an empty array is got.

    The keys are not returned synchronously, but a callback is called asynchronously with the value as its parameter.

    The value(session:queue:then:) method may be used to get the full value of the node.

    Since

    2.2.0

    Declaration

    Swift

    public func childrenKeys(session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: @escaping WebcomResult<[WebcomKey]>.Callback)

    Parameters

    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.
    queue

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

    The closure to call upon completion. In case of success, it is called with the keys of the children of the referred node. In case of failure, it is called with a WebcomError value indicating the reason of the failure.

  • Gets the keys of the children of the node referred by this instance.

    Warning

    This method was deprecated in version 2.2.0. Use childrenKeys(session:queue:then:) instead.

    Declaration

    Swift

    @available(*, deprecated, renamed: "childrenKeys(session:queue:then:﹚")
public func keys(session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: @escaping WebcomResult<[WebcomKey]>.Callback)

  • Clears the value of the node referred by this instance.

    Clearing the value is equivalent to setting a JSON null value. Therefore, calling this method is equivalent to call:

    set(nil, session: session, queue: queue, then: completionCallback)

    Declaration

    Swift

    public func clear(session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: WebcomResult<Void>.Callback? = nil)

    Parameters

    queue

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

    The closure to call upon completion. In case of success, it is called with a void value. In case of failure, it is called with a WebcomError value indicating the reason of the failure.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

  • Sets the value of the node referred by this instance.

    Note: In most cases, you should rather use the set(_:session:queue:then:) overload that takes an Encodable parameter.

    All children of the referred node cleared before setting the new value. The merge(_:with:session:queue:then:) method may be used to merge existing children with the ones of the value when it is a JSON object or array.

    Declaration

    Swift

    public func set(_ raw: WebcomMarkers.Raw, _ json: Any?, session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: WebcomResult<Void>.Callback? = nil)

    Parameters

    raw

    Use the .raw value to disambiguate with the set(_:session:queue:then:) overload that takes an Encodable parameter.
    json

    The value to set. It must be valid JSON (object, array, string, number, boolean or null). The null value can be specified with nil or NSNull().
    queue

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

    The closure to call upon completion. In case of success, it is called with a void value. In case of failure, it is called with a WebcomError value indicating the reason of the failure.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

  • Sets the value of the node referred by this instance.

    All children of the referred node are cleared before setting the new value. The merge(with:session:queue:then:) method may be used to merge existing children with the ones of the value when it is a JSON object or array.

    Declaration

    Swift

    public func set(_ value: (some Encodable)?, session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: WebcomResult<Void>.Callback? = nil)

    Parameters

    value

    The value to set. It will be encoded to JSON before being sent to the back-end, using the WebcomApplication.jsonEncoder of the WebcomApplication from which this node derives. The null value can be specified with nil or NSNull().
    queue

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

    The closure to call upon completion. In case of success, it is called with a void value. In case of failure, it is called with a WebcomError value indicating the reason of the failure.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

  • Sets the value of a node.

    This operator is equivalent to:

    node.set(value)

    Declaration

    Swift

    public static func <- (node: DataNode, value: (some Encodable)?)

    Parameters

    node

    A reference to the node whose value must be set.
    value

    The value to set.

  • Merges a value with the current value of the node referred by this instance.

    Note: In most cases, you should rather use the merge(with:session:queue:then:) overload that takes an Encodable parameter.

    Unlike what happens with the set(_:_:session:queue:then:):

    • json must be a valid JSON object,

    • existing direct children (i.e. the descendants at the first level of depth) that exist in the current value are preserved when json does not specify them.

    Declaration

    Swift

    public func merge(_ raw: WebcomMarkers.Raw, with json: [String : Any], session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: WebcomResult<Void>.Callback? = nil)

    Parameters

    raw

    Use the .raw value to disambiguate with the merge(with:session:queue:then:) overload that takes an Encodable parameter.
    json

    The value to merge with. It must be a valid JSON object.
    queue

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

    The closure to call upon completion. In case of success, it is called with a void value. In case of failure, it is called with a WebcomError value indicating the reason of the failure.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

  • Merges a value with the current value of the node referred by this instance.

    Unlike what happens with the set(_:session:queue:then:):

    • value may not be nil,
    • the encoding of value to JSON must give a JSON object (or a JSON array but this is discouraged), or the method will fail,

    • existing direct children (i.e. the descendants at the first level of depth) that exist in the current value are preserved when value does not specify them.

    Declaration

    Swift

    public func merge(with value: (some Encodable)?, session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: WebcomResult<Void>.Callback? = nil)

    Parameters

    value

    The value to merge with. It will be encoded to JSON before being sent to the back-end, using the WebcomApplication.jsonEncoder of the WebcomApplication from which this node derives.
    queue

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

    The closure to call upon completion. In case of success, it is called with a void value. In case of failure, it is called with a WebcomError value indicating the reason of the failure.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.

  • Subscribes to events related to the value of the referred node through remote notifications (push notifications).

    This method requires that:

    There can be at most one subscription of this type per node, per user and per device. Therefore, a new subscription of this type for the same node, the same user and the same device overwrites the first one.

    The subscription is stored by the DataService instance, whether it succeeded or failed. The DataService.unsubscribeFromAllThroughNotifications(session:queue:then:) method may be used to cancel all subscriptions that used notifications at the same time. The DataService.updateDeviceTokenInAllSubscriptions(file:line:session:queue:then:) method may be used to update the device token of all subscriptions.

    Declaration

    Swift

    public func subscribeThroughNotifications(descriptor: DataSubscriptionDescriptor, file: StaticString = #fileID, line: UInt = #line, session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: WebcomResult<DataSubscription>.Callback? = nil)

    Parameters

    descriptor

    The descriptor for the subscription.
    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.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.
    queue

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

    The closure to call upon completion. In case of success, it is called with a value representing the subscription. In case of failure, it is called with a WebcomError value indicating the reason of the failure.

  • Cancels the possible subscription through remote notifications (push notifications) for the referred node.

    This method requires that the current user is authenticated.

    When there is currently no subscription of this type for the referred node, the current user and the current device, this method is a no-operation.

    Declaration

    Swift

    public func unsubscribeThroughNotifications(session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: WebcomResult<Void>.Callback? = nil)

    Parameters

    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.
    queue

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

    The closure to call upon completion. In case of success, it is called with a void value. In case of failure, it is called with a WebcomError value indicating the reason of the failure.

  • Subscribes to events related to the value of the referred node through a webhook.

    This method requires that the current user is authenticated.

    There can be at most one subscription of this type per node, per user and per device for a given identifier and a given context. Therefore, a new subscription of this type for the same node, the same user, the same device, the same identifier and the same context overwrites the first one.

    The subscription is stored by the DataService instance, whether it succeeded or failed. The DataService.unsubscribeFromAllThroughWebhook(session:queue:then:) method may be used to cancel all subscriptions that used notifications at the same time.

    Declaration

    Swift

    public func subscribeThroughWebhook(_ identifier: String, context: String, descriptor: DataSubscriptionDescriptor, file: StaticString = #fileID, line: UInt = #line, session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: WebcomResult<DataSubscription>.Callback? = nil)

    Parameters

    identifier

    The identifier of the webhook to subscribe to.
    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.
    context

    The value to pass to the webhook when the value of the referred node is modified.
    descriptor

    The descriptor for the subscription.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.
    queue

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

    The closure to call upon completion. In case of success, it is called with a value representing the subscription. In case of failure, it is called with a WebcomError value indicating the reason of the failure.

  • Cancels the possible subscription through a webhook for the referred node.

    This method requires that the current user is authenticated.

    When there is currently no subscription of this type for the referred node, the current user, the current device, the same identifier and the same context, this method is a no-operation.

    Declaration

    Swift

    public func unsubscribeThroughWebhook(_ identifier: String, context: String, session: URLSession? = nil, queue: DispatchQueue? = nil, then completionCallback: WebcomResult<Void>.Callback? = nil)

    Parameters

    identifier

    The identifier of the webhook to unsubscribe from.
    context

    The value passed to the webhook as it was set in the subscription.
    session

    The session used to send the request to the back-end. When nil, the default session of the application of this instance is used.
    queue

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

    The closure to call upon completion. In case of success, it is called with a void value. In case of failure, it is called with a WebcomError value indicating the reason of the failure.

Equatable Protocol

  • Declaration

    Swift

    public static func == (left: DataNode, right: DataNode) -> Bool

Hashable Protocol

  • Declaration

    Swift

    public func hash(into hasher: inout Hasher)

CustomStringConvertible Protocol

  • Declaration

    Swift

    public var description: String { get }

Combine Module

  • The type that wraps DataNode 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, Hashable, CustomStringConvertible

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

    Declaration

    Swift

    public var forCombine: CombineWrapper { get }