ZDCCloudOperation

@interface ZDCCloudOperation <NSCoding, NSCopying>

ZDCCloudOperation is a lightweight representation of a push task that needs to be performed.

That is, it represents a change that needs to be pushed to the server such as:

  • uploading a new node
  • modifying an existing node
  • moving or renaming a node
  • deleting a node

It encodes the minimum information necessary to to execute the task at a later date, possibly after an app re-launch.

The operation objects get stored in the database as part of ZDCCloud (a database extension), which manages the operation objects in a semi-queue-like fashion.

Note

ZDCCloudOperation extends YapDatabaseCloudCoreOperation. (YapDatabaseCloudCore was also developed by us, which we contributed to the open source community.) The YapDatabaseCloudCoreOperation class is where you’ll find the basic operation stuff, such as the uuid, dependencies, and priority.
  • Creates a new instance with the basics. You’ll need to fill out the remaining information based on the requirements for the particular type.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithLocalUserID:(nonnull NSString *)localUserID
                                         treeID:(nonnull NSString *)treeID
                                           type:(ZDCCloudOperationType)type;

    Swift

    init(localUserID: String, treeID: String, type: ZDCCloudOperationType)
  • Creates a new instance with the basics. You’ll need to fill out the remaining information based on the requirements for the particular putType.

    Declaration

    Objective-C

    - (nonnull instancetype)initWithLocalUserID:(nonnull NSString *)localUserID
                                         treeID:(nonnull NSString *)treeID
                                        putType:(ZDCCloudOperationPutType)putType;

    Swift

    init(localUserID: String, treeID: String, putType: ZDCCloudOperationPutType)
  • The value specified during init.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic) NSString *_Nonnull localUserID;

    Swift

    var localUserID: String { get }
  • The value specified during init.

    Declaration

    Objective-C

    @property (readonly, copy, nonatomic) NSString *_Nonnull treeID;

    Swift

    var treeID: String { get }
  • Corresponds to the operation to be performed on the server.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) ZDCCloudOperationType type;

    Swift

    var type: ZDCCloudOperationType { get set }
  • For put operations, corresponds to the type of put operation being performed.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) ZDCCloudOperationPutType putType;

    Swift

    var putType: ZDCCloudOperationPutType { get set }
  • Points to the corresponding node (nodeID == ZDCNode.uuid)

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *nodeID;

    Swift

    var nodeID: String? { get set }
  • For copy-leaf operations, points to the corresponding destination node (nodeID == ZDCNode.uuid)

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *dstNodeID;

    Swift

    var dstNodeID: String? { get set }
  • Points to the corresponding cloudNode (cloudNodeID == ZDCCloudNode.uuid)

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *cloudNodeID;

    Swift

    var cloudNodeID: String? { get set }
  • The cloud location of the operation.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) ZDCCloudLocator *cloudLocator;

    Swift

    @NSCopying var cloudLocator: ZDCCloudLocator? { get set }
  • For move & copy operations, represents the target destination. That is, the cloudLocator property represents the ‘source’ location, and this property represents the ‘destination’ location.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable)
        ZDCCloudLocator *dstCloudLocator;

    Swift

    @NSCopying var dstCloudLocator: ZDCCloudLocator? { get set }
  • The eTag is used for put-node-data operations. It designates the currently known version of the data in the cloud.

    For example, imagine the current version of a node is ‘A’. If we queue an operation to update that node, then our operation will specify that we expect the current version of the node to be ‘A’. When the operation hits the cloud, that operation will succeed as long as the node is still at ‘A’. However, if the node has been updated by another device, we may discover it’s actually at ‘B’ now.

    When this is the case, we will need to perform one of the following actions:

    • download the latest version of the node, and merge changes
    • skip our queued put-node-data operations

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *eTag;

    Swift

    var eTag: String? { get set }
  • An ‘orphaned’ node is where a RCRD file exists on the server, however there’s no corresponding DATA file. This may occur if a client is taken offline between uploading the RCRD and DATA files.

    If a node remains orphaned for an extended period of time, other clients may automatically ask the server to delete the node. When they perform this request, they send a special ‘if-orphan’ flag to the server to clarify the intent of the delete operation.

    Declaration

    Objective-C

    @property (assign, readwrite, nonatomic) BOOL ifOrphan;

    Swift

    var ifOrphan: Bool { get set }
  • A serialized version of the JSON request that’s sent during a delete-node operation.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSData *deleteNodeJSON;

    Swift

    var deleteNodeJSON: Data? { get set }
  • A list of cloudID’s that are being deleted (for both delete-leaf & delete-node operations).

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable)
        NSSet<NSString *> *deletedCloudIDs;

    Swift

    var deletedCloudIDs: Set<String>? { get set }
  • For ZDCCloudOperationType_Avatar. Specifies the particular identity for which we’re uploading the avatar.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *avatar_auth0ID;

    Swift

    var avatar_auth0ID: String? { get set }
  • For ZDCCloudOperationType_Avatar. Specifies the old eTag, representing the avatar we’re replacing. This can be nil if the particular identity doesn’t have a current eTag.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *avatar_oldETag;

    Swift

    var avatar_oldETag: String? { get set }
  • For ZDCCloudOperationType_Avatar. Specifies the new eTag, representing the avatar we’re expecting to upload. This can be nil if we’re deleting the current avatar.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSString *avatar_newETag;

    Swift

    var avatar_newETag: String? { get set }
  • Used for RCRD operations when the permissions have changed. Stores the changeset obtained via ZDCShareList. Since ZDCShareList implements the ZDCSyncable protocol, this allows us to easily merge changes.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable)
        NSDictionary *changeset_permissions;

    Swift

    var changeset_permissions: [AnyHashable : Any]? { get set }
  • Used for DATA operations. This value is supplied by the framework user, either via [ZDCCloudTransaction queueDataUploadForNodeID:withChangeset:], or the user can set it manually via the operation.

    It’s recommended (but not required) that the ZDCSyncable protocol is used to simplify the process of merging changes.

    Declaration

    Objective-C

    @property (readwrite, copy, nonatomic, nullable) NSDictionary *changeset_obj;

    Swift

    var changeset_obj: [AnyHashable : Any]? { get set }
  • Returns true if both the receiver and ‘another’ have the same target. Two operations with the same target will result in the same operation being generated.

    Declaration

    Objective-C

    - (BOOL)hasSameTarget:(nonnull ZDCCloudOperation *)another;

    Swift

    func hasSameTarget(_ another: ZDCCloudOperation) -> Bool
  • Convenience method: returns YES if:

    • type == ZDCCloudOperationType_Put AND
    • putType == ZDCCloudOperationPutType_Node_Rcrd

    Declaration

    Objective-C

    - (BOOL)isPutNodeRcrdOperation;

    Swift

    func isPutNodeRcrdOperation() -> Bool
  • Convenience method: returns YES if:

    • type == ZDCCloudOperationType_Put AND
    • putType == ZDCCloudOperationPutType_Node_Data

    Declaration

    Objective-C

    - (BOOL)isPutNodeDataOperation;

    Swift

    func isPutNodeDataOperation() -> Bool
  • Utility method: converts from enum to string. Used during encoding/decoding to protect against the possibility of enum values changing over time.

    Declaration

    Objective-C

    + (nonnull NSString *)stringForType:(ZDCCloudOperationType)type;

    Swift

    class func string(for type: ZDCCloudOperationType) -> String
  • Utility method: converts from string to enum. Used during encoding/decoding to protect against the possibility of enum values changing over time.

    Declaration

    Objective-C

    + (ZDCCloudOperationType)typeForString:(nonnull NSString *)string;

    Swift

    class func type(for string: String) -> ZDCCloudOperationType
  • Utility method: converts from enum to string. Used during encoding/decoding to protect against the possibility of enum values changing over time.

    Declaration

    Objective-C

    + (nonnull NSString *)stringForPutType:(ZDCCloudOperationPutType)putType;

    Swift

    class func string(for putType: ZDCCloudOperationPutType) -> String
  • Utility method: converts from string to enum. Used during encoding/decoding to protect against the possibility of enum values changing over time.

    Declaration

    Objective-C

    + (ZDCCloudOperationPutType)putTypeForString:(nonnull NSString *)string;

    Swift

    class func putType(for string: String) -> ZDCCloudOperationPutType