iOS/Pods/Realm/include/RLMMigration.h

   1 ////////////////////////////////////////////////////////////////////////////
   2 //
   3 // Copyright 2014 Realm Inc.
   4 //
   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
   8 //
   9 // http://www.apache.org/licenses/LICENSE-2.0
  10 //
  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.
  16 //
  17 ////////////////////////////////////////////////////////////////////////////
  18
  19 #import <Foundation/Foundation.h>
  20
  21 NS_ASSUME_NONNULL_BEGIN
  22
  23 @class RLMSchema;
  24 @class RLMArray;
  25 @class RLMObject;
  26
  27 /**
  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.
  30
  31  @see `-[RLMMigration enumerateObjects:block:]`
  32
  33  @param oldObject The object from the original Realm (read-only).
  34  @param newObject The object from the migrated Realm (read-write).
  35 */
  36 typedef void (^RLMObjectMigrationBlock)(RLMObject * __nullable oldObject, RLMObject * __nullable newObject);
  37
  38 /**
  39  `RLMMigration` instances encapsulate information intended to facilitate a schema migration.
  40
  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.
  44  */
  45 @interface RLMMigration : NSObject
  46
  47 #pragma mark - Properties
  48
  49 /**
  50  Returns the old `RLMSchema`. This is the schema which describes the Realm before the
  51  migration is applied.
  52  */
  53 @property (nonatomic, readonly) RLMSchema *oldSchema;
  54
  55 /**
  56  Returns the new `RLMSchema`. This is the schema which describes the Realm after the
  57  migration is applied.
  58  */
  59 @property (nonatomic, readonly) RLMSchema *newSchema;
  60
  61
  62 #pragma mark - Altering Objects during a Migration
  63
  64 /**
  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.
  67
  68  @param className   The name of the `RLMObject` class to enumerate.
  69
  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
  72             properties.
  73  */
  74 - (void)enumerateObjects:(NSString *)className block:(__attribute__((noescape)) RLMObjectMigrationBlock)block;
  75
  76 /**
  77  Creates and returns an `RLMObject` instance of type `className` in the Realm being migrated.
  78
  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
  82  with default values.
  83
  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.
  86
  87  @param className   The name of the `RLMObject` class to create.
  88  @param value       The value used to populate the object.
  89  */
  90 - (RLMObject *)createObject:(NSString *)className withValue:(id)value;
  91
  92 /**
  93  Deletes an object from a Realm during a migration.
  94
  95  It is permitted to call this method from within the block passed to `-[enumerateObjects:block:]`.
  96
  97  @param object  Object to be deleted from the Realm being migrated.
  98  */
  99 - (void)deleteObject:(RLMObject *)object;
 100
 101 /**
 102  Deletes the data for the class with the given name.
 103
 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.
 106
 107  @param  name The name of the `RLMObject` class to delete.
 108
 109  @return A Boolean value indicating whether there was any data to delete.
 110  */
 111 - (BOOL)deleteDataForClassName:(NSString *)name;
 112
 113 /**
 114  Renames a property of the given class from `oldName` to `newName`.
 115
 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.
 122  */
 123 - (void)renamePropertyForClass:(NSString *)className oldName:(NSString *)oldName newName:(NSString *)newName;
 124
 125 @end
 126
 127 NS_ASSUME_NONNULL_END