RLMRealm

Obtains an instance of the default Realm.

The default Realm is used by the RLMObject class methods which do not take a RLMRealm parameter, but is otherwise not special. The default Realm is persisted as default.realm under the Documents directory of your Application on iOS, and in your application’s Application Support directory on OS X.

The default Realm is created using the default RLMRealmConfiguration, which can be changed via +[RLMRealmConfiguration setDefaultConfiguration:].

Obtains an RLMRealm instance with the given configuration.

Obtains an RLMRealm instance persisted at a specified file URL.

The RLMSchema used by the Realm.

Indicates if the Realm is currently engaged in a write transaction.

The RLMRealmConfiguration object that was used to create this RLMRealm instance.

Indicates if this Realm contains any objects.

Adds a notification handler for changes in this Realm, and returns a notification token.

Notification handlers are called after each write transaction is committed, either on the current thread or other threads.

Handler blocks are called on the same thread that they were added on, and may only be added on threads which are currently within a run loop. Unless you are specifically creating and running a run loop on a background thread, this will normally only be the main thread.

The block has the following definition:

typedef void(^RLMNotificationBlock)(NSString *notification, RLMRealm *realm);

It receives the following parameters:

• NSString *notification: The name of the incoming notification. See RLMRealmNotification for information on what notifications are sent.

• RLMRealm *realm: The Realm for which this notification occurred.

Begins a write transaction on the Realm.

Only one write transaction can be open at a time. Write transactions cannot be nested, and trying to begin a write transaction on a Realm which is already in a write transaction will throw an exception. Calls to beginWriteTransaction from RLMRealm instances in other threads will block until the current write transaction completes.

Before beginning the write transaction, beginWriteTransaction updates the RLMRealm instance to the latest Realm version, as if refresh had been called, and generates notifications if applicable. This has no effect if the Realm was already up to date.

It is rarely a good idea to have write transactions span multiple cycles of the run loop, but if you do wish to do so you will need to ensure that the Realm participating in the write transaction is kept alive until the write transaction is committed.

Commits all write operations in the current write transaction, and ends the transaction.

Commits all write operations in the current write transaction, and ends the transaction.

Reverts all writes made during the current write transaction and ends the transaction.

This rolls back all objects in the Realm to the state they were in at the beginning of the write transaction, and then ends the transaction.

This restores the data for deleted objects, but does not revive invalidated object instances. Any RLMObjects which were added to the Realm will be invalidated rather than becoming unmanaged. Given the following code:

ObjectType *oldObject = [[ObjectType objectsWhere:@"..."] firstObject];
ObjectType *newObject = [[ObjectType alloc] init];

[realm beginWriteTransaction];
[realm addObject:newObject];
[realm deleteObject:oldObject];
[realm cancelWriteTransaction];

Both oldObject and newObject will return YES for isInvalidated, but re-running the query which provided oldObject will once again return the valid object.

Performs actions contained within the given block inside a write transaction.

Performs actions contained within the given block inside a write transaction.

Write transactions cannot be nested, and trying to execute a write transaction on a Realm which is already participating in a write transaction will throw an exception. Calls to transactionWithBlock: from RLMRealm instances in other threads will block until the current write transaction completes.

Before beginning the write transaction, transactionWithBlock: updates the RLMRealm instance to the latest Realm version, as if refresh had been called, and generates notifications if applicable. This has no effect if the Realm was already up to date.

Updates the Realm and outstanding objects managed by the Realm to point to the most recent data.

Set this property to YES to automatically update this Realm when changes happen in other threads.

If set to YES (the default), changes made on other threads will be reflected in this Realm on the next cycle of the run loop after the changes are committed. If set to NO, you must manually call -refresh on the Realm to update it to get the latest data.

Note that by default, background threads do not have an active run loop and you will need to manually call -refresh in order to update to the latest version, even if autorefresh is set to YES.

Even with this enabled, you can still call -refresh at any time to update the Realm before the automatic refresh would occur.

Notifications are sent when a write transaction is committed whether or not automatic refreshing is enabled.

Disabling autorefresh on a Realm without any strong references to it will not have any effect, and autorefresh will revert back to YES the next time the Realm is created. This is normally irrelevant as it means that there is nothing to refresh (as persisted RLMObjects, RLMArrays, and RLMResults have strong references to the Realm that manages them), but it means that setting RLMRealm.defaultRealm.autorefresh = NO in application:didFinishLaunchingWithOptions: and only later storing Realm objects will not work.

Defaults to YES.

Writes a compacted and optionally encrypted copy of the Realm to the given local URL.

The destination file cannot already exist.

Note that if this method is called from within a write transaction, the current data is written, not the data from the point when the previous write transaction was committed.

Invalidates all RLMObjects and RLMResults managed by the Realm.

A Realm holds a read lock on the version of the data accessed by it, so that changes made to the Realm on different threads do not modify or delete the data seen by this Realm. Calling this method releases the read lock, allowing the space used on disk to be reused by later write transactions rather than growing the file. This method should be called before performing long blocking operations on a background thread on which you previously read data from the Realm which you no longer need.

All RLMObject, RLMResults and RLMArray instances obtained from this RLMRealm instance on the current thread are invalidated. RLMObjects and RLMArrays cannot be used. RLMResults will become empty. The Realm itself remains valid, and a new read transaction is implicitly begun the next time data is read from the Realm.

Calling this method multiple times in a row without reading any data from the Realm, or before ever reading any data from the Realm, is a no-op. This method may not be called on a read-only Realm.

Adds an object to the Realm.

Once added, this object is considered to be managed by the Realm. It can be retrieved using the objectsWhere: selectors on RLMRealm and on subclasses of RLMObject.

When added, all child relationships referenced by this object will also be added to the Realm if they are not already in it.

If the object or any related objects are already being managed by a different Realm an exception will be thrown. Use -[RLMObject createInRealm:withObject:] to insert a copy of a managed object into a different Realm.

The object to be added must be valid and cannot have been previously deleted from a Realm (i.e. isInvalidated must be NO).

Adds all the objects in a collection to the Realm.

This is the equivalent of calling addObject: for every object in a collection.

Adds or updates an existing object into the Realm.

The object provided must have a designated primary key. If no objects exist in the Realm with the same primary key value, the object is inserted. Otherwise, the existing object is updated with any changed values.

As with addObject:, the object cannot already be managed by a different Realm. Use -[RLMObject createOrUpdateInRealm:withValue:] to copy values to a different Realm.

Adds or updates all the objects in a collection into the Realm.

This is the equivalent of calling addOrUpdateObject: for every object in a collection.

Deletes an object from the Realm. Once the object is deleted it is considered invalidated.

Deletes one or more objects from the Realm.

This is the equivalent of calling deleteObject: for every object in a collection.

Deletes all objects from the Realm.

Returns the schema version for a Realm at a given local URL.

Performs the given Realm configuration’s migration block on a Realm at the given path.

This method is called automatically when opening a Realm for the first time and does not need to be called explicitly. You can choose to call this method to control exactly when and how migrations are performed.