YapDatabaseReadWriteTransaction

@interface YapDatabaseReadWriteTransaction : YapDatabaseReadTransaction

/////////////////////////////////////////////////////////////////////////////////////////////////////////////////////

  • Under normal circumstances, when a read-write transaction block completes, the changes are automatically committed. If, however, something goes wrong and you’d like to abort and discard all changes made within the transaction, then invoke this method.

    You should generally return (exit the transaction block) after invoking this method. Any changes made within the the transaction before and after invoking this method will be discarded.

    Declaration

    Objective-C

    - (void)rollback;

    Swift

    func rollback()

  • The YapDatabaseModifiedNotification is posted following a readwrite transaction which made changes.

    These notifications are used in a variety of ways:

    • They may be used as a general notification mechanism to detect changes to the database.
    • They may be used by extensions to post change information. For example, YapDatabaseView will post the index changes, which can easily be used to animate a tableView.
    • They are integrated into the architecture of long-lived transactions in order to maintain a steady state.

    Thus it is recommended you integrate your own notification information into this existing notification, as opposed to broadcasting your own separate notification.

    For more information, and code samples, please see the wiki article: https://github.com/yapstudios/YapDatabase/wiki/YapDatabaseModifiedNotification

    Declaration

    Objective-C

    @property (readwrite, strong, nonatomic, nullable)
    id yapDatabaseModifiedNotificationCustomObject;

    Swift

    var yapDatabaseModifiedNotificationCustomObject: Any? { get set }

Object & Metadata

  • Sets the object for the given key/collection. The object is automatically serialized using the database’s configured objectSerializer.

    If you pass nil for the object, then this method will remove the row from the database (if it exists). This method implicitly sets the associated metadata to nil.

    Declaration

    Objective-C

    - (void)setObject:(nullable id)object
           forKey:(nonnull NSString *)key
     inCollection:(nullable NSString *)collection;

    Swift

    func setObject(_ object: Any?, forKey key: String, inCollection collection: String?)

    Parameters

    object

    The object to store in the database. This object is automatically serialized using the database’s configured objectSerializer.
    key

    The lookup key. The tuple is used to uniquely identify the row in the database. This value should not be nil. If a nil key is passed, then this method does nothing.
    collection

    The lookup collection. The tuple is used to uniquely identify the row in the database. If a nil collection is passed, then the collection is implicitly the empty string (@“”).

  • Sets the object & metadata for the given key/collection.

    If you pass nil for the object, then this method will remove the row from the database (if it exists).

    Declaration

    Objective-C

    - (void)setObject:(nullable id)object
           forKey:(nonnull NSString *)key
     inCollection:(nullable NSString *)collection
     withMetadata:(nullable id)metadata;

    Swift

    func setObject(_ object: Any?, forKey key: String, inCollection collection: String?, withMetadata metadata: Any?)

    Parameters

    object

    The object to store in the database. This object is automatically serialized using the database’s configured objectSerializer.
    key

    The lookup key. The tuple is used to uniquely identify the row in the database. This value should not be nil. If a nil key is passed, then this method does nothing.
    collection

    The lookup collection. The tuple is used to uniquely identify the row in the database. If a nil collection is passed, then the collection is implicitly the empty string (@“”).
    metadata

    The metadata to store in the database. This metadata is automatically serialized using the database’s configured metadataSerializer. The metadata is optional. You can pass nil for the metadata is unneeded. If non-nil then the metadata is also written to the database (metadata is also persistent).

  • Sets the object & metadata for the given key/collection.

    If you pass nil for the object, then this method will remove the row from the database (if it exists).

    This method allows for a bit of optimization if you happen to already have a serialized version of the object and/or metadata. For example, if you downloaded an object in serialized form, and you still have the raw serialized NSData, then you can use this method to skip the serialization step when storing the object to the database.

    The preSerializedObject is only used if object is non-nil. The preSerializedMetadata is only used if metadata is non-nil.

    Declaration

    Objective-C

    - (void)setObject:(nullable id)object
                forKey:(nonnull NSString *)key
          inCollection:(nullable NSString *)collection
          withMetadata:(nullable id)metadata
      serializedObject:(nullable NSData *)preSerializedObject
    serializedMetadata:(nullable NSData *)preSerializedMetadata;

    Swift

    func setObject(_ object: Any?, forKey key: String, inCollection collection: String?, withMetadata metadata: Any?, serializedObject preSerializedObject: Data?, serializedMetadata preSerializedMetadata: Data?)

    Parameters

    object

    The object to store in the database. This object is automatically serialized using the database’s configured objectSerializer.
    key

    The lookup key. The tuple is used to uniquely identify the row in the database. This value should not be nil. If a nil key is passed, then this method does nothing.
    collection

    The lookup collection. The tuple is used to uniquely identify the row in the database. If a nil collection is passed, then the collection is implicitly the empty string (@“”).
    metadata

    The metadata to store in the database. This metadata is automatically serialized using the database’s configured metadataSerializer. The metadata is optional. You can pass nil for the metadata is unneeded. If non-nil then the metadata is also written to the database (metadata is also persistent).
    preSerializedObject

    This value is optional. If non-nil then the object serialization step is skipped, and this value is used instead. It is assumed that preSerializedObject is equal to what we would get if we ran the object through the database’s configured objectSerializer.
    preSerializedMetadata

    This value is optional. If non-nil then the metadata serialization step is skipped, and this value is used instead. It is assumed that preSerializedMetadata is equal to what we would get if we ran the metadata through the database’s configured metadataSerializer.

  • If a row with the given key/collection exists, then replaces the object for that row with the new value.

    It only replaces the object. The metadata for the row doesn’t change. If there is no row in the database for the given key/collection then this method does nothing.

    If you pass nil for the object, then this method will remove the row from the database (if it exists).

    Declaration

    Objective-C

    - (void)replaceObject:(nullable id)object
               forKey:(nonnull NSString *)key
         inCollection:(nullable NSString *)collection;

    Swift

    func replace(_ object: Any?, forKey key: String, inCollection collection: String?)

    Parameters

    object

    The object to store in the database. This object is automatically serialized using the database’s configured objectSerializer.
    key

    The lookup key. The tuple is used to uniquely identify the row in the database. This value should not be nil. If a nil key is passed, then this method does nothing.
    collection

    The lookup collection. The tuple is used to uniquely identify the row in the database. If a nil collection is passed, then the collection is implicitly the empty string (@“”).

  • If a row with the given key/collection exists, then replaces the object for that row with the new value.

    It only replaces the object. The metadata for the row doesn’t change. If there is no row in the database for the given key/collection then this method does nothing.

    If you pass nil for the object, then this method will remove the row from the database (if it exists).

    This method allows for a bit of optimization if you happen to already have a serialized version of the object and/or metadata. For example, if you downloaded an object in serialized form, and you still have the raw serialized NSData, then you can use this method to skip the serialization step when storing the object to the database.

    Declaration

    Objective-C

    - (void)replaceObject:(nullable id)object
                  forKey:(nonnull NSString *)key
            inCollection:(nullable NSString *)collection
    withSerializedObject:(nullable NSData *)preSerializedObject;

    Swift

    func replace(_ object: Any?, forKey key: String, inCollection collection: String?, withSerializedObject preSerializedObject: Data?)

    Parameters

    object

    The object to store in the database. This object is automatically serialized using the database’s configured objectSerializer.
    key

    The lookup key. The tuple is used to uniquely identify the row in the database. This value should not be nil. If a nil key is passed, then this method does nothing.
    collection

    The lookup collection. The tuple is used to uniquely identify the row in the database. If a nil collection is passed, then the collection is implicitly the empty string (@“”).
    preSerializedObject

    This value is optional. If non-nil then the object serialization step is skipped, and this value is used instead. It is assumed that preSerializedObject is equal to what we would get if we ran the object through the database’s configured objectSerializer.

  • If a row with the given key/collection exists, then replaces the metadata for that row with the new value.

    It only replaces the metadata. The object for the row doesn’t change. If there is no row in the database for the given key/collection then this method does nothing.

    If you pass nil for the metadata, any metadata previously associated with the key/collection is removed.

    Declaration

    Objective-C

    - (void)replaceMetadata:(nullable id)metadata
                 forKey:(nonnull NSString *)key
           inCollection:(nullable NSString *)collection;

    Swift

    func replaceMetadata(_ metadata: Any?, forKey key: String, inCollection collection: String?)

    Parameters

    metadata

    The metadata to store in the database. This metadata is automatically serialized using the database’s configured metadataSerializer.
    key

    The lookup key. The tuple is used to uniquely identify the row in the database. This value should not be nil. If a nil key is passed, then this method does nothing.
    collection

    The lookup collection. The tuple is used to uniquely identify the row in the database. If a nil collection is passed, then the collection is implicitly the empty string (@“”).

  • If a row with the given key/collection exists, then replaces the metadata for that row with the new value.

    It only replaces the metadata. The object for the row doesn’t change. If there is no row in the database for the given key/collection then this method does nothing.

    If you pass nil for the metadata, any metadata previously associated with the key/collection is removed.

    This method allows for a bit of optimization if you happen to already have a serialized version of the object and/or metadata. For example, if you downloaded an object in serialized form, and you still have the raw serialized NSData, then you can use this method to skip the serialization step when storing the object to the database.

    Declaration

    Objective-C

    - (void)replaceMetadata:(nullable id)metadata
                    forKey:(nonnull NSString *)key
              inCollection:(nullable NSString *)collection
    withSerializedMetadata:(nullable NSData *)preSerializedMetadata;

    Swift

    func replaceMetadata(_ metadata: Any?, forKey key: String, inCollection collection: String?, withSerializedMetadata preSerializedMetadata: Data?)

    Parameters

    metadata

    The metadata to store in the database. This metadata is automatically serialized using the database’s configured metadataSerializer.
    key

    The lookup key. The tuple is used to uniquely identify the row in the database. This value should not be nil. If a nil key is passed, then this method does nothing.
    collection

    The lookup collection. The tuple is used to uniquely identify the row in the database. If a nil collection is passed, then the collection is implicitly the empty string (@“”).
    preSerializedMetadata

    This value is optional. If non-nil then the metadata serialization step is skipped, and this value is used instead. It is assumed that preSerializedMetadata is equal to what we would get if we ran the metadata through the database’s configured metadataSerializer.

Touch

  • You can touch an object if you want to mark it as updated without actually writing any changes to disk.

    For example:

    You have a BNBook object in your database. One of the properties of the book object is a URL pointing to an image for the front cover of the book. This image gets changed on the server. Thus the UI representation of the book needs to be updated to reflect the updated image on the server. You realize that all your views are already listening for YapDatabaseModified notifications, so if you update the object in the database then all your views are already wired to update the UI appropriately. However, the actual object itself didn’t change. So while there technically isn’t any reason to update the object on disk, doing so would be the easiest way to keep the UI up-to-date. So what you really want is a way to mark the object as updated, without actually incurring the overhead of rewriting it to disk.

    And this is exactly what the touch methods were designed for. It won’t actually cause the object to get rewritten to disk. However, it will mark the object as updated within the YapDatabaseModified notification, so any UI components listening for changes will see this object as updated, and can update as appropriate.

    • touchObjectForKey:inCollection: Similar to calling replaceObject:forKey:inCollection: and passing the object that already exists. But without the overhead of fetching the object, or re-writing it to disk.

    • touchMetadataForKey:inCollection: Similar to calling replaceMetadata:forKey:inCollection: and passing the metadata that already exists. But without the overhead of fetching the metadata, or re-writing it to disk.

    • touchRowForKey:inCollection: Similar to calling setObject:forKey:inCollection:withMetadata: and passing the object & metadata the already exist. But without the overhead of fetching the items, or re-writing them to disk.

    Note: It is safe to touch items during enumeration. Normally, altering the database while enumerating it will result in an exception (just like altering an array while enumerating it). However, it’s safe to touch items during enumeration.

    Declaration

    Objective-C

    - (void)touchObjectForKey:(nonnull NSString *)key
             inCollection:(nullable NSString *)collection;

    Swift

    func touchObject(forKey key: String, inCollection collection: String?)

  • Undocumented

    Declaration

    Objective-C

    - (void)touchMetadataForKey:(NSString *)key inCollection:(nullable NSString *)collection;

    Swift

    func touchMetadata(forKey key: String, inCollection collection: String?)

  • Undocumented

    Declaration

    Objective-C

    - (void)touchRowForKey:(NSString *)key inCollection:(nullable NSString *)collection;

    Swift

    func touchRow(forKey key: String, inCollection collection: String?)

Remove

  • Deletes the database row with the given key/collection.

    This method is automatically called if you invoke setObject:forKey:collection: and pass a nil object.

    Declaration

    Objective-C

    - (void)removeObjectForKey:(nonnull NSString *)key
              inCollection:(nullable NSString *)collection;

    Swift

    func removeObject(forKey key: String, inCollection collection: String?)

  • Deletes the database rows with the given keys in the given collection.

    Declaration

    Objective-C

    - (void)removeObjectsForKeys:(nonnull NSArray<NSString *> *)keys
                inCollection:(nullable NSString *)collection;

    Swift

    func removeObjects(forKeys keys: [String], inCollection collection: String?)

  • Deletes every key/object pair from the given collection. No trace of the collection will remain afterwards.

    Declaration

    Objective-C

    - (void)removeAllObjectsInCollection:(nullable NSString *)collection;

    Swift

    func removeAllObjects(inCollection collection: String?)

  • Removes every key/object pair in the entire database (from all collections).

    Declaration

    Objective-C

    - (void)removeAllObjectsInAllCollections;

    Swift

    func removeAllObjectsInAllCollections()

Completion

  • It’s often useful to compose code into various reusable functions which take a YapDatabaseReadWriteTransaction as a parameter. However, the ability to compose code in this manner is often prevented by the need to perform a task after the commit has finished.

    The end result is that programmers either end up copy-pasting code, or hack together a solution that involves functions returning completion blocks.

    This method solves the dilemma by allowing encapsulated code to register its own commit completionBlock.

    Declaration

    Objective-C

    - (void)addCompletionQueue:(nullable dispatch_queue_t)completionQueue
           completionBlock:(nonnull dispatch_block_t)completionBlock;

    Swift

    func addCompletionQueue(_ completionQueue: DispatchQueue?, completionBlock: @escaping () -> Void)