1 ////////////////////////////////////////////////////////////////////////////
3 // Copyright 2014 Realm Inc.
5 // Licensed under the Apache License, Version 2.0 (the "License");
6 // you may not use this file except in compliance with the License.
7 // You may obtain a copy of the License at
9 // http://www.apache.org/licenses/LICENSE-2.0
11 // Unless required by applicable law or agreed to in writing, software
12 // distributed under the License is distributed on an "AS IS" BASIS,
13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 // See the License for the specific language governing permissions and
15 // limitations under the License.
17 ////////////////////////////////////////////////////////////////////////////
19 #import <Foundation/Foundation.h>
21 NS_ASSUME_NONNULL_BEGIN
28 A block type which provides both the old and new versions of an object in the Realm. Object
29 properties can only be accessed using keyed subscripting.
31 @see `-[RLMMigration enumerateObjects:block:]`
33 @param oldObject The object from the original Realm (read-only).
34 @param newObject The object from the migrated Realm (read-write).
36 typedef void (^RLMObjectMigrationBlock)(RLMObject * __nullable oldObject, RLMObject * __nullable newObject);
39 `RLMMigration` instances encapsulate information intended to facilitate a schema migration.
41 A `RLMMigration` instance is passed into a user-defined `RLMMigrationBlock` block when updating
42 the version of a Realm. This instance provides access to the old and new database schemas, the
43 objects in the Realm, and provides functionality for modifying the Realm during the migration.
45 @interface RLMMigration : NSObject
47 #pragma mark - Properties
50 Returns the old `RLMSchema`. This is the schema which describes the Realm before the
53 @property (nonatomic, readonly) RLMSchema *oldSchema;
56 Returns the new `RLMSchema`. This is the schema which describes the Realm after the
59 @property (nonatomic, readonly) RLMSchema *newSchema;
62 #pragma mark - Altering Objects during a Migration
65 Enumerates all the objects of a given type in the Realm, providing both the old and new versions
66 of each object. Within the block, object properties can only be accessed using keyed subscripting.
68 @param className The name of the `RLMObject` class to enumerate.
70 @warning All objects returned are of a type specific to the current migration and should not be cast
71 to `className`. Instead, treat them as `RLMObject`s and use keyed subscripting to access
74 - (void)enumerateObjects:(NSString *)className block:(__attribute__((noescape)) RLMObjectMigrationBlock)block;
77 Creates and returns an `RLMObject` instance of type `className` in the Realm being migrated.
79 The `value` argument is used to populate the object. It can be a key-value coding compliant object, an array or
80 dictionary returned from the methods in `NSJSONSerialization`, or an array containing one element for each managed
81 property. An exception will be thrown if any required properties are not present and those properties were not defined
84 When passing in an `NSArray` as the `value` argument, all properties must be present, valid and in the same order as
85 the properties defined in the model.
87 @param className The name of the `RLMObject` class to create.
88 @param value The value used to populate the object.
90 - (RLMObject *)createObject:(NSString *)className withValue:(id)value;
93 Deletes an object from a Realm during a migration.
95 It is permitted to call this method from within the block passed to `-[enumerateObjects:block:]`.
97 @param object Object to be deleted from the Realm being migrated.
99 - (void)deleteObject:(RLMObject *)object;
102 Deletes the data for the class with the given name.
104 All objects of the given class will be deleted. If the `RLMObject` subclass no longer exists in your program,
105 any remaining metadata for the class will be removed from the Realm file.
107 @param name The name of the `RLMObject` class to delete.
109 @return A Boolean value indicating whether there was any data to delete.
111 - (BOOL)deleteDataForClassName:(NSString *)name;
114 Renames a property of the given class from `oldName` to `newName`.
116 @param className The name of the class whose property should be renamed. This class must be present
117 in both the old and new Realm schemas.
118 @param oldName The old name for the property to be renamed. There must not be a property with this name in the
119 class as defined by the new Realm schema.
120 @param newName The new name for the property to be renamed. There must not be a property with this name in the
121 class as defined by the old Realm schema.
123 - (void)renamePropertyForClass:(NSString *)className oldName:(NSString *)oldName newName:(NSString *)newName;
127 NS_ASSUME_NONNULL_END