ZDCDatabaseManager

@interface ZDCDatabaseManager : NSObject

ZeroDarkCloud requires a database for atomic operations. YapDatabase is used as it’s the most performant and highly-concurrent.

If you’re curious about YapDatabase, you can find the project page here. The extensive documentation is on the wiki.

This class provides access to the YapDatabase instance & various connections/extensions being used by the framework. You’re encouraged (but not required) to store your objects in the same YapDatabase instance, as doing so allows you to participate in the same atomic transactions being used by the framework.

  • The root YapDatabase instance. Most of the time you’ll want a database connection instead.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) YapDatabase *database

    Swift

    var database: UnsafeMutablePointer<Int32> { get }
  • The UI connection is read-only, and is reserved for use EXCLUSIVELY on the MAIN THREAD.

    This follows the recommended best-practices for YapDatabase: https://github.com/yapstudios/YapDatabase/wiki/Performance-Pro

    Only use this connection for performing synchronous reads on the main thread. All other uses violate the recommended best-practices outlined in the wiki, and will throw an exception in DEBUG builds (to help you learn the rules).

    Warning

    Attempting to access this property outside the main thread will throw an exception.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) YapDatabaseConnection *uiDatabaseConnection

    Swift

    var uiDatabaseConnection: UnsafeMutablePointer<Int32> { get }
  • A read-only connection pool. Most of the time you’ll want the roDatabaseConnection property (which uses this connection pool).

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) YapDatabaseConnectionPool *roConnectionPool

    Swift

    var roConnectionPool: UnsafeMutablePointer<Int32> { get }
  • Read-only connection(s) are automatically vended from the roConnectionPool. With this connection you can perform a read-only sync/async transaction.

    Note

    When performing a synchronous read-only connection on the main-thread, you’re encouraged to use the uiDatabaseConnection.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) YapDatabaseConnection *roDatabaseConnection

    Swift

    var roDatabaseConnection: UnsafeMutablePointer<Int32> { get }
  • Read-write connection is reserved for write transactions. This may be used from ANY THREAD.

    Note: For performance reasons, you’ll want to avoid performing a synchronous write from the main thread, as that would risk stalling your user interface.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) YapDatabaseConnection *rwDatabaseConnection

    Swift

    var rwDatabaseConnection: UnsafeMutablePointer<Int32> { get }
  • Uses the roDatabaseConnection & rwDatabaseConnection.

    Declaration

    Objective-C

    @property (nonatomic, strong, readonly) YapDatabaseConnectionProxy *databaseConnectionProxy

    Swift

    var databaseConnectionProxy: UnsafeMutablePointer<Int32> { get }
  • For use within:

    • Ext_View_Flat

    Declaration

    Objective-C

    + (nonnull NSString *)groupForLocalUserID:(nonnull NSString *)localUserID
                                       treeID:(nonnull NSString *)treeID;

    Swift

    class func group(forLocalUserID localUserID: String, treeID: String) -> String
  • For use within:

    • Ext_View_CloudNode_DirPrefix

    Declaration

    Objective-C

    + (nonnull NSString *)groupForLocalUserID:(nonnull NSString *)localUserID
                                       region:(AWSRegion)region
                                       bucket:(nonnull NSString *)bucket
                                       treeID:(nonnull NSString *)treeID
                                    dirPrefix:(nonnull NSString *)dirPrefix;

    Swift

    class func group(forLocalUserID localUserID: String, region: AWSRegion, bucket: String, treeID: String, dirPrefix: String) -> String
  • Returns the registered name of the ZDCCloud extension for the given localUserID. This is typically used to access the ZDCCloudTransaction. For example:

    [zdc.rwDatabaseConnection readWithBlock:^(YapDatabaseReadTransaction *transaction){

    NSString *extName = [zdc.databaseManager cloudExtNameForUser:localUserID app:MyAppID];
    ZDCCloudTransaction *ext = [transaction ext:extName];
    
    // ... do something with ext ...
    

    }];

    Declaration

    Objective-C

    - (nonnull NSString *)cloudExtNameForUserID:(nonnull NSString *)localUserID;

    Swift

    func cloudExtName(forUserID localUserID: String) -> String
  • Returns the registered name of the ZDCCloud extension for the given tuple. This is typically used to access the ZDCCloudTransaction. For example:

    [zdc.rwDatabaseConnection readWithBlock:^(YapDatabaseReadTransaction *transaction){

    NSString *extName = [zdc.databaseManager cloudExtNameForUserID:localUserID treeID:myTreeID];
    ZDCCloudTransaction *ext = [transaction ext:extName];
    
    // ... do something with ext ...
    

    }];

    Declaration

    Objective-C

    - (nonnull NSString *)cloudExtNameForUserID:(nonnull NSString *)localUserID
                                         treeID:(nonnull NSString *)treeID;

    Swift

    func cloudExtName(forUserID localUserID: String, treeID: String) -> String
  • Returns all registered ZDCCloud instances for the given account.

    Declaration

    Objective-C

    - (nonnull NSArray<ZDCCloud *> *)cloudExtsForUserID:
        (nonnull NSString *)localUserID;

    Swift

    func cloudExts(forUserID localUserID: String) -> [ZDCCloud]
  • Returns the registered ZDCCloud instance for the given account.

    This method invokes -cloudExtForUserID:treeID: and passes the primary treeID (ZeroDarkCloud.primaryTreeID).

    Declaration

    Objective-C

    - (nullable ZDCCloud *)cloudExtForUserID:(nonnull NSString *)localUserID;

    Swift

    func cloudExt(forUserID localUserID: String) -> ZDCCloud?
  • Returns the registered ZDCCloud instance for the given account.

    Declaration

    Objective-C

    - (nullable ZDCCloud *)cloudExtForUserID:(nonnull NSString *)localUserID
                                      treeID:(nonnull NSString *)treeID;

    Swift

    func cloudExt(forUserID localUserID: String, treeID: String) -> ZDCCloud?
  • A separate ZDCCloud instance is registered for every account.

    When the database is unlocked, ZDCCloudCore instances are automatically registered for all pre-existing accounts in the database. During runtime, ZDCCloud instances are created for you when you activate a treeID for a localUser.

    Declaration

    Objective-C

    - (nonnull ZDCCloud *)
        registerCloudExtensionForUserID:(nonnull NSString *)localUserID
                                 treeID:(nonnull NSString *)treeID;

    Swift

    func registerCloudExtension(forUserID localUserID: String, treeID: String) -> ZDCCloud
  • A separate ZDCCloud instance MUST be registered for every account. If an account is deleted (not suspended) during runtime, then this method MUST be invoked to delete the instance.

    Declaration

    Objective-C

    - (void)unregisterCloudExtensionForUserID:(nonnull NSString *)localUserID
                                       treeID:(nonnull NSString *)treeID;

    Swift

    func unregisterCloudExtension(forUserID localUserID: String, treeID: String)