651 lines
28 KiB
Objective-C
651 lines
28 KiB
Objective-C
////////////////////////////////////////////////////////////////////////////
|
|
//
|
|
// Copyright 2014 Realm Inc.
|
|
//
|
|
// Licensed under the Apache License, Version 2.0 (the "License");
|
|
// you may not use this file except in compliance with the License.
|
|
// You may obtain a copy of the License at
|
|
//
|
|
// http://www.apache.org/licenses/LICENSE-2.0
|
|
//
|
|
// Unless required by applicable law or agreed to in writing, software
|
|
// distributed under the License is distributed on an "AS IS" BASIS,
|
|
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
|
|
// See the License for the specific language governing permissions and
|
|
// limitations under the License.
|
|
//
|
|
////////////////////////////////////////////////////////////////////////////
|
|
|
|
#import <Foundation/Foundation.h>
|
|
|
|
#import <Realm/RLMObjectBase.h>
|
|
#import <Realm/RLMThreadSafeReference.h>
|
|
|
|
NS_ASSUME_NONNULL_BEGIN
|
|
|
|
@class RLMNotificationToken;
|
|
@class RLMObjectSchema;
|
|
@class RLMPropertyChange;
|
|
@class RLMPropertyDescriptor;
|
|
@class RLMRealm;
|
|
@class RLMResults<RLMObjectType>;
|
|
|
|
/**
|
|
`RLMObject` is a base class for model objects representing data stored in Realms.
|
|
|
|
Define your model classes by subclassing `RLMObject` and adding properties to be managed.
|
|
Then instantiate and use your custom subclasses instead of using the `RLMObject` class directly.
|
|
|
|
// Dog.h
|
|
@interface Dog : RLMObject
|
|
@property NSString *name;
|
|
@property BOOL adopted;
|
|
@end
|
|
|
|
// Dog.m
|
|
@implementation Dog
|
|
@end //none needed
|
|
|
|
### Supported property types
|
|
|
|
- `NSString`
|
|
- `NSInteger`, `int`, `long`, `float`, and `double`
|
|
- `BOOL` or `bool`
|
|
- `NSDate`
|
|
- `NSData`
|
|
- `NSNumber<X>`, where `X` is one of `RLMInt`, `RLMFloat`, `RLMDouble` or `RLMBool`, for optional number properties
|
|
- `RLMObject` subclasses, to model many-to-one relationships.
|
|
- `RLMArray<X>`, where `X` is an `RLMObject` subclass, to model many-to-many relationships.
|
|
|
|
### Querying
|
|
|
|
You can initiate queries directly via the class methods: `allObjects`, `objectsWhere:`, and `objectsWithPredicate:`.
|
|
These methods allow you to easily query a custom subclass for instances of that class in the default Realm.
|
|
|
|
To search in a Realm other than the default Realm, use the `allObjectsInRealm:`, `objectsInRealm:where:`,
|
|
and `objectsInRealm:withPredicate:` class methods.
|
|
|
|
@see `RLMRealm`
|
|
|
|
### Relationships
|
|
|
|
See our [Cocoa guide](https://realm.io/docs/objc/latest#relationships) for more details.
|
|
|
|
### Key-Value Observing
|
|
|
|
All `RLMObject` properties (including properties you create in subclasses) are
|
|
[Key-Value Observing compliant](https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/KeyValueObserving/KeyValueObserving.html),
|
|
except for `realm` and `objectSchema`.
|
|
|
|
Keep the following tips in mind when observing Realm objects:
|
|
|
|
1. Unlike `NSMutableArray` properties, `RLMArray` properties do not require
|
|
using the proxy object returned from `-mutableArrayValueForKey:`, or defining
|
|
KVC mutation methods on the containing class. You can simply call methods on
|
|
the `RLMArray` directly; any changes will be automatically observed by the containing
|
|
object.
|
|
2. Unmanaged `RLMObject` instances cannot be added to a Realm while they have any
|
|
observed properties.
|
|
3. Modifying managed `RLMObject`s within `-observeValueForKeyPath:ofObject:change:context:`
|
|
is not recommended. Properties may change even when the Realm is not in a write
|
|
transaction (for example, when `-[RLMRealm refresh]` is called after changes
|
|
are made on a different thread), and notifications sent prior to the change
|
|
being applied (when `NSKeyValueObservingOptionPrior` is used) may be sent at
|
|
times when you *cannot* begin a write transaction.
|
|
*/
|
|
|
|
@interface RLMObject : RLMObjectBase <RLMThreadConfined>
|
|
|
|
#pragma mark - Creating & Initializing Objects
|
|
|
|
/**
|
|
Creates an unmanaged instance of a Realm object.
|
|
|
|
Call `addObject:` on an `RLMRealm` instance to add an unmanaged object into that Realm.
|
|
|
|
@see `[RLMRealm addObject:]`
|
|
*/
|
|
- (instancetype)init NS_DESIGNATED_INITIALIZER;
|
|
|
|
|
|
/**
|
|
Creates an unmanaged instance of a Realm object.
|
|
|
|
Pass in an `NSArray` or `NSDictionary` instance to set the values of the object's properties.
|
|
|
|
Call `addObject:` on an `RLMRealm` instance to add an unmanaged object into that Realm.
|
|
|
|
@see `[RLMRealm addObject:]`
|
|
*/
|
|
- (instancetype)initWithValue:(id)value NS_DESIGNATED_INITIALIZER;
|
|
|
|
|
|
/**
|
|
Returns the class name for a Realm object subclass.
|
|
|
|
@warning Do not override. Realm relies on this method returning the exact class
|
|
name.
|
|
|
|
@return The class name for the model class.
|
|
*/
|
|
+ (NSString *)className;
|
|
|
|
/**
|
|
Creates an instance of a Realm object with a given value, and adds it to the default Realm.
|
|
|
|
If nested objects are included in the argument, `createInDefaultRealmWithValue:` will be recursively called
|
|
on them.
|
|
|
|
The `value` argument can be a key-value coding compliant object, an array or dictionary returned from the methods in
|
|
`NSJSONSerialization`, or an array containing one element for each managed property.
|
|
|
|
An exception will be thrown if any required properties are not present and those properties
|
|
were not defined with default values.
|
|
|
|
If the `value` argument is an array, all properties must be present, valid and in the same
|
|
order as the properties defined in the model.
|
|
|
|
@param value The value used to populate the object.
|
|
|
|
@see `defaultPropertyValues`
|
|
*/
|
|
+ (instancetype)createInDefaultRealmWithValue:(id)value;
|
|
|
|
/**
|
|
Creates an instance of a Realm object with a given value, and adds it to the specified Realm.
|
|
|
|
If nested objects are included in the argument, `createInRealm:withValue:` will be recursively called
|
|
on them.
|
|
|
|
The `value` argument can be a key-value coding compliant object, an array or dictionary returned from the methods in
|
|
`NSJSONSerialization`, or an array containing one element for each managed property.
|
|
|
|
An exception will be thrown if any required properties are not present and those properties
|
|
were not defined with default values.
|
|
|
|
If the `value` argument is an array, all properties must be present, valid and in the same
|
|
order as the properties defined in the model.
|
|
|
|
@param realm The Realm which should manage the newly-created object.
|
|
@param value The value used to populate the object.
|
|
|
|
@see `defaultPropertyValues`
|
|
*/
|
|
+ (instancetype)createInRealm:(RLMRealm *)realm withValue:(id)value;
|
|
|
|
/**
|
|
Creates or updates a Realm object within the default Realm.
|
|
|
|
This method may only be called on Realm object types with a primary key defined. If there is already
|
|
an object with the same primary key value in the default Realm, its values are updated and the object
|
|
is returned. Otherwise, this method creates and populates a new instance of the object in the default Realm.
|
|
|
|
If nested objects are included in the argument, `createOrUpdateInDefaultRealmWithValue:` will be
|
|
recursively called on them if they have primary keys, `createInDefaultRealmWithValue:` if they do not.
|
|
|
|
The `value` argument is used to populate the object. It can be a Realm object, a key-value coding
|
|
compliant object, an array or dictionary returned from the methods in `NSJSONSerialization`, or an
|
|
array containing one element for each managed property.
|
|
|
|
If the object is being created, an exception will be thrown if any required properties
|
|
are not present and those properties were not defined with default values.
|
|
|
|
If the `value` argument is a Realm object already managed by the default Realm, the
|
|
argument's type is the same as the receiver, and the objects have identical values for
|
|
their managed properties, this method does nothing.
|
|
|
|
If the object is being updated, each property defined in its schema will be set by copying from
|
|
`value` using key-value coding. If the `value` argument does not respond to `valueForKey:` for a
|
|
given property name (or getter name, if defined), that value will remain untouched.
|
|
Nullable properties on the object can be set to nil by using `NSNull` as the updated value.
|
|
Each property is set even if the existing value is the same as the new value being set, and
|
|
notifications will report them all being changed. See `createOrUpdateModifiedInDefaultRealmWithValue:`
|
|
for a version of this function which only sets the values which have changed.
|
|
|
|
If the `value` argument is an array, all properties must be present, valid and in the same
|
|
order as the properties defined in the model.
|
|
|
|
@param value The value used to populate the object.
|
|
|
|
@see `defaultPropertyValues`, `primaryKey`
|
|
*/
|
|
+ (instancetype)createOrUpdateInDefaultRealmWithValue:(id)value;
|
|
|
|
/**
|
|
Creates or updates a Realm object within the default Realm.
|
|
|
|
This method may only be called on Realm object types with a primary key defined. If there is already
|
|
an object with the same primary key value in the default Realm, its values are updated and the object
|
|
is returned. Otherwise, this method creates and populates a new instance of the object in the default Realm.
|
|
|
|
If nested objects are included in the argument, `createOrUpdateModifiedInDefaultRealmWithValue:` will be
|
|
recursively called on them if they have primary keys, `createInDefaultRealmWithValue:` if they do not.
|
|
|
|
The `value` argument is used to populate the object. It can be a Realm object, a key-value coding
|
|
compliant object, an array or dictionary returned from the methods in `NSJSONSerialization`, or an
|
|
array containing one element for each managed property.
|
|
|
|
If the object is being created, an exception will be thrown if any required properties
|
|
are not present and those properties were not defined with default values.
|
|
|
|
If the `value` argument is a Realm object already managed by the default Realm, the
|
|
argument's type is the same as the receiver, and the objects have identical values for
|
|
their managed properties, this method does nothing.
|
|
|
|
If the object is being updated, each property defined in its schema will be set by copying from
|
|
`value` using key-value coding. If the `value` argument does not respond to `valueForKey:` for a
|
|
given property name (or getter name, if defined), that value will remain untouched.
|
|
Nullable properties on the object can be set to nil by using `NSNull` as the updated value.
|
|
Unlike `createOrUpdateInDefaultRealmWithValue:`, only properties which have changed in value are
|
|
set, and any change notifications produced by this call will report only which properies have
|
|
actually changed.
|
|
|
|
Checking which properties have changed imposes a small amount of overhead, and so this method
|
|
may be slower when all or nearly all of the properties being set have changed. If most or all
|
|
of the properties being set have not changed, this method will be much faster than unconditionally
|
|
setting all of them, and will also reduce how much data has to be written to the Realm, saving
|
|
both i/o time and disk space.
|
|
|
|
If the `value` argument is an array, all properties must be present, valid and in the same
|
|
order as the properties defined in the model.
|
|
|
|
@param value The value used to populate the object.
|
|
|
|
@see `defaultPropertyValues`, `primaryKey`
|
|
*/
|
|
+ (instancetype)createOrUpdateModifiedInDefaultRealmWithValue:(id)value;
|
|
|
|
/**
|
|
Creates or updates an Realm object within a specified Realm.
|
|
|
|
This method may only be called on Realm object types with a primary key defined. If there is already
|
|
an object with the same primary key value in the given Realm, its values are updated and the object
|
|
is returned. Otherwise this method creates and populates a new instance of this object in the given Realm.
|
|
|
|
If nested objects are included in the argument, `createOrUpdateInRealm:withValue:` will be
|
|
recursively called on them if they have primary keys, `createInRealm:withValue:` if they do not.
|
|
|
|
The `value` argument is used to populate the object. It can be a Realm object, a key-value coding
|
|
compliant object, an array or dictionary returned from the methods in `NSJSONSerialization`, or an
|
|
array containing one element for each managed property.
|
|
|
|
If the object is being created, an exception will be thrown if any required properties
|
|
are not present and those properties were not defined with default values.
|
|
|
|
If the `value` argument is a Realm object already managed by the given Realm, the
|
|
argument's type is the same as the receiver, and the objects have identical values for
|
|
their managed properties, this method does nothing.
|
|
|
|
If the object is being updated, each property defined in its schema will be set by copying from
|
|
`value` using key-value coding. If the `value` argument does not respond to `valueForKey:` for a
|
|
given property name (or getter name, if defined), that value will remain untouched.
|
|
Nullable properties on the object can be set to nil by using `NSNull` as the updated value.
|
|
Each property is set even if the existing value is the same as the new value being set, and
|
|
notifications will report them all being changed. See `createOrUpdateModifiedInRealm:withValue:`
|
|
for a version of this function which only sets the values which have changed.
|
|
|
|
If the `value` argument is an array, all properties must be present, valid and in the same
|
|
order as the properties defined in the model.
|
|
|
|
@param realm The Realm which should own the object.
|
|
@param value The value used to populate the object.
|
|
|
|
@see `defaultPropertyValues`, `primaryKey`
|
|
*/
|
|
+ (instancetype)createOrUpdateInRealm:(RLMRealm *)realm withValue:(id)value;
|
|
|
|
/**
|
|
Creates or updates an Realm object within a specified Realm.
|
|
|
|
This method may only be called on Realm object types with a primary key defined. If there is already
|
|
an object with the same primary key value in the given Realm, its values are updated and the object
|
|
is returned. Otherwise this method creates and populates a new instance of this object in the given Realm.
|
|
|
|
If nested objects are included in the argument, `createOrUpdateInRealm:withValue:` will be
|
|
recursively called on them if they have primary keys, `createInRealm:withValue:` if they do not.
|
|
|
|
The `value` argument is used to populate the object. It can be a Realm object, a key-value coding
|
|
compliant object, an array or dictionary returned from the methods in `NSJSONSerialization`, or an
|
|
array containing one element for each managed property.
|
|
|
|
If the object is being created, an exception will be thrown if any required properties
|
|
are not present and those properties were not defined with default values.
|
|
|
|
If the `value` argument is a Realm object already managed by the given Realm, the
|
|
argument's type is the same as the receiver, and the objects have identical values for
|
|
their managed properties, this method does nothing.
|
|
|
|
If the object is being updated, each property defined in its schema will be set by copying from
|
|
`value` using key-value coding. If the `value` argument does not respond to `valueForKey:` for a
|
|
given property name (or getter name, if defined), that value will remain untouched.
|
|
Nullable properties on the object can be set to nil by using `NSNull` as the updated value.
|
|
Unlike `createOrUpdateInRealm:withValue:`, only properties which have changed in value are
|
|
set, and any change notifications produced by this call will report only which properies have
|
|
actually changed.
|
|
|
|
Checking which properties have changed imposes a small amount of overhead, and so this method
|
|
may be slower when all or nearly all of the properties being set have changed. If most or all
|
|
of the properties being set have not changed, this method will be much faster than unconditionally
|
|
setting all of them, and will also reduce how much data has to be written to the Realm, saving
|
|
both i/o time and disk space.
|
|
|
|
If the `value` argument is an array, all properties must be present, valid and in the same
|
|
order as the properties defined in the model.
|
|
|
|
@param realm The Realm which should own the object.
|
|
@param value The value used to populate the object.
|
|
|
|
@see `defaultPropertyValues`, `primaryKey`
|
|
*/
|
|
+ (instancetype)createOrUpdateModifiedInRealm:(RLMRealm *)realm withValue:(id)value;
|
|
|
|
#pragma mark - Properties
|
|
|
|
/**
|
|
The Realm which manages the object, or `nil` if the object is unmanaged.
|
|
*/
|
|
@property (nonatomic, readonly, nullable) RLMRealm *realm;
|
|
|
|
/**
|
|
The object schema which lists the managed properties for the object.
|
|
*/
|
|
@property (nonatomic, readonly) RLMObjectSchema *objectSchema;
|
|
|
|
/**
|
|
Indicates if the object can no longer be accessed because it is now invalid.
|
|
|
|
An object can no longer be accessed if the object has been deleted from the Realm that manages it, or
|
|
if `invalidate` is called on that Realm.
|
|
*/
|
|
@property (nonatomic, readonly, getter = isInvalidated) BOOL invalidated;
|
|
|
|
|
|
#pragma mark - Customizing your Objects
|
|
|
|
/**
|
|
Returns an array of property names for properties which should be indexed.
|
|
|
|
Only string, integer, boolean, and `NSDate` properties are supported.
|
|
|
|
@return An array of property names.
|
|
*/
|
|
+ (NSArray<NSString *> *)indexedProperties;
|
|
|
|
/**
|
|
Override this method to specify the default values to be used for each property.
|
|
|
|
@return A dictionary mapping property names to their default values.
|
|
*/
|
|
+ (nullable NSDictionary *)defaultPropertyValues;
|
|
|
|
/**
|
|
Override this method to specify the name of a property to be used as the primary key.
|
|
|
|
Only properties of types `RLMPropertyTypeString` and `RLMPropertyTypeInt` can be designated as the primary key.
|
|
Primary key properties enforce uniqueness for each value whenever the property is set, which incurs minor overhead.
|
|
Indexes are created automatically for primary key properties.
|
|
|
|
@return The name of the property designated as the primary key.
|
|
*/
|
|
+ (nullable NSString *)primaryKey;
|
|
|
|
/**
|
|
Override this method to specify the names of properties to ignore. These properties will not be managed by the Realm
|
|
that manages the object.
|
|
|
|
@return An array of property names to ignore.
|
|
*/
|
|
+ (nullable NSArray<NSString *> *)ignoredProperties;
|
|
|
|
/**
|
|
Override this method to specify the names of properties that are non-optional (i.e. cannot be assigned a `nil` value).
|
|
|
|
By default, all properties of a type whose values can be set to `nil` are considered optional properties.
|
|
To require that an object in a Realm always store a non-`nil` value for a property,
|
|
add the name of the property to the array returned from this method.
|
|
|
|
Properties of `RLMObject` type cannot be non-optional. Array and `NSNumber` properties
|
|
can be non-optional, but there is no reason to do so: arrays do not support storing nil, and
|
|
if you want a non-optional number you should instead use the primitive type.
|
|
|
|
@return An array of property names that are required.
|
|
*/
|
|
+ (NSArray<NSString *> *)requiredProperties;
|
|
|
|
/**
|
|
Override this method to provide information related to properties containing linking objects.
|
|
|
|
Each property of type `RLMLinkingObjects` must have a key in the dictionary returned by this method consisting
|
|
of the property name. The corresponding value must be an instance of `RLMPropertyDescriptor` that describes the class
|
|
and property that the property is linked to.
|
|
|
|
return @{ @"owners": [RLMPropertyDescriptor descriptorWithClass:Owner.class propertyName:@"dogs"] };
|
|
|
|
@return A dictionary mapping property names to `RLMPropertyDescriptor` instances.
|
|
*/
|
|
+ (NSDictionary<NSString *, RLMPropertyDescriptor *> *)linkingObjectsProperties;
|
|
|
|
|
|
#pragma mark - Getting & Querying Objects from the Default Realm
|
|
|
|
/**
|
|
Returns all objects of this object type from the default Realm.
|
|
|
|
@return An `RLMResults` containing all objects of this type in the default Realm.
|
|
*/
|
|
+ (RLMResults *)allObjects;
|
|
|
|
/**
|
|
Returns all objects of this object type matching the given predicate from the default Realm.
|
|
|
|
@param predicateFormat A predicate format string, optionally followed by a variable number of arguments.
|
|
|
|
@return An `RLMResults` containing all objects of this type in the default Realm that match the given predicate.
|
|
*/
|
|
+ (RLMResults *)objectsWhere:(NSString *)predicateFormat, ...;
|
|
|
|
/// :nodoc:
|
|
+ (RLMResults<__kindof RLMObject *> *)objectsWhere:(NSString *)predicateFormat args:(va_list)args;
|
|
|
|
|
|
/**
|
|
Returns all objects of this object type matching the given predicate from the default Realm.
|
|
|
|
@param predicate The predicate with which to filter the objects.
|
|
|
|
@return An `RLMResults` containing all objects of this type in the default Realm that match the given predicate.
|
|
*/
|
|
+ (RLMResults *)objectsWithPredicate:(nullable NSPredicate *)predicate;
|
|
|
|
/**
|
|
Retrieves the single instance of this object type with the given primary key from the default Realm.
|
|
|
|
Returns the object from the default Realm which has the given primary key, or
|
|
`nil` if the object does not exist. This is slightly faster than the otherwise
|
|
equivalent `[[SubclassName objectsWhere:@"primaryKeyPropertyName = %@", key] firstObject]`.
|
|
|
|
This method requires that `primaryKey` be overridden on the receiving subclass.
|
|
|
|
@return An object of this object type, or `nil` if an object with the given primary key does not exist.
|
|
@see `-primaryKey`
|
|
*/
|
|
+ (nullable instancetype)objectForPrimaryKey:(nullable id)primaryKey NS_SWIFT_NAME(object(forPrimaryKey:));
|
|
|
|
|
|
#pragma mark - Querying Specific Realms
|
|
|
|
/**
|
|
Returns all objects of this object type from the specified Realm.
|
|
|
|
@param realm The Realm to query.
|
|
|
|
@return An `RLMResults` containing all objects of this type in the specified Realm.
|
|
*/
|
|
+ (RLMResults *)allObjectsInRealm:(RLMRealm *)realm;
|
|
|
|
/**
|
|
Returns all objects of this object type matching the given predicate from the specified Realm.
|
|
|
|
@param predicateFormat A predicate format string, optionally followed by a variable number of arguments.
|
|
@param realm The Realm to query.
|
|
|
|
@return An `RLMResults` containing all objects of this type in the specified Realm that match the given predicate.
|
|
*/
|
|
+ (RLMResults *)objectsInRealm:(RLMRealm *)realm where:(NSString *)predicateFormat, ...;
|
|
|
|
/// :nodoc:
|
|
+ (RLMResults<__kindof RLMObject *> *)objectsInRealm:(RLMRealm *)realm where:(NSString *)predicateFormat args:(va_list)args;
|
|
|
|
/**
|
|
Returns all objects of this object type matching the given predicate from the specified Realm.
|
|
|
|
@param predicate A predicate to use to filter the elements.
|
|
@param realm The Realm to query.
|
|
|
|
@return An `RLMResults` containing all objects of this type in the specified Realm that match the given predicate.
|
|
*/
|
|
+ (RLMResults *)objectsInRealm:(RLMRealm *)realm withPredicate:(nullable NSPredicate *)predicate;
|
|
|
|
/**
|
|
Retrieves the single instance of this object type with the given primary key from the specified Realm.
|
|
|
|
Returns the object from the specified Realm which has the given primary key, or
|
|
`nil` if the object does not exist. This is slightly faster than the otherwise
|
|
equivalent `[[SubclassName objectsInRealm:realm where:@"primaryKeyPropertyName = %@", key] firstObject]`.
|
|
|
|
This method requires that `primaryKey` be overridden on the receiving subclass.
|
|
|
|
@return An object of this object type, or `nil` if an object with the given primary key does not exist.
|
|
@see `-primaryKey`
|
|
*/
|
|
+ (nullable instancetype)objectInRealm:(RLMRealm *)realm forPrimaryKey:(nullable id)primaryKey NS_SWIFT_NAME(object(in:forPrimaryKey:));
|
|
|
|
#pragma mark - Notifications
|
|
|
|
/**
|
|
A callback block for `RLMObject` notifications.
|
|
|
|
If the object is deleted from the managing Realm, the block is called with
|
|
`deleted` set to `YES` and the other two arguments are `nil`. The block will
|
|
never be called again after this.
|
|
|
|
If the object is modified, the block will be called with `deleted` set to
|
|
`NO`, a `nil` error, and an array of `RLMPropertyChange` objects which
|
|
indicate which properties of the objects were modified.
|
|
|
|
If an error occurs, `deleted` will be `NO`, `changes` will be `nil`, and
|
|
`error` will include information about the error. The block will never be
|
|
called again after an error occurs.
|
|
*/
|
|
typedef void (^RLMObjectChangeBlock)(BOOL deleted,
|
|
NSArray<RLMPropertyChange *> *_Nullable changes,
|
|
NSError *_Nullable error);
|
|
|
|
/**
|
|
Registers a block to be called each time the object changes.
|
|
|
|
The block will be asynchronously called after each write transaction which
|
|
deletes the object or modifies any of the managed properties of the object,
|
|
including self-assignments that set a property to its existing value.
|
|
|
|
For write transactions performed on different threads or in differen
|
|
processes, the block will be called when the managing Realm is
|
|
(auto)refreshed to a version including the changes, while for local write
|
|
transactions it will be called at some point in the future after the write
|
|
transaction is committed.
|
|
|
|
Notifications are delivered via the standard run loop, and so can't be
|
|
delivered while the run loop is blocked by other activity. When notifications
|
|
can't be delivered instantly, multiple notifications may be coalesced into a
|
|
single notification.
|
|
|
|
Unlike with `RLMArray` and `RLMResults`, there is no "initial" callback made
|
|
after you add a new notification block.
|
|
|
|
Only objects which are managed by a Realm can be observed in this way. You
|
|
must retain the returned token for as long as you want updates to be sent to
|
|
the block. To stop receiving updates, call `-invalidate` on the token.
|
|
|
|
It is safe to capture a strong reference to the observed object within the
|
|
callback block. There is no retain cycle due to that the callback is retained
|
|
by the returned token and not by the object itself.
|
|
|
|
@warning This method cannot be called during a write transaction, when the
|
|
containing Realm is read-only, or on an unmanaged object.
|
|
|
|
@param block The block to be called whenever a change occurs.
|
|
@return A token which must be held for as long as you want updates to be delivered.
|
|
*/
|
|
- (RLMNotificationToken *)addNotificationBlock:(RLMObjectChangeBlock)block;
|
|
|
|
#pragma mark - Other Instance Methods
|
|
|
|
/**
|
|
Returns YES if another Realm object instance points to the same object as the receiver in the Realm managing
|
|
the receiver.
|
|
|
|
For object types with a primary, key, `isEqual:` is overridden to use the same logic as this
|
|
method (along with a corresponding implementation for `hash`).
|
|
|
|
@param object The object to compare the receiver to.
|
|
|
|
@return Whether the object represents the same object as the receiver.
|
|
*/
|
|
- (BOOL)isEqualToObject:(RLMObject *)object;
|
|
|
|
#pragma mark - Dynamic Accessors
|
|
|
|
/// :nodoc:
|
|
- (nullable id)objectForKeyedSubscript:(NSString *)key;
|
|
|
|
/// :nodoc:
|
|
- (void)setObject:(nullable id)obj forKeyedSubscript:(NSString *)key;
|
|
|
|
@end
|
|
|
|
/**
|
|
Information about a specific property which changed in an `RLMObject` change notification.
|
|
*/
|
|
@interface RLMPropertyChange : NSObject
|
|
|
|
/**
|
|
The name of the property which changed.
|
|
*/
|
|
@property (nonatomic, readonly, strong) NSString *name;
|
|
|
|
/**
|
|
The value of the property before the change occurred. This will always be `nil`
|
|
if the change happened on the same thread as the notification and for `RLMArray`
|
|
properties.
|
|
|
|
For object properties this will give the object which was previously linked to,
|
|
but that object will have its new values and not the values it had before the
|
|
changes. This means that `previousValue` may be a deleted object, and you will
|
|
need to check `invalidated` before accessing any of its properties.
|
|
*/
|
|
@property (nonatomic, readonly, strong, nullable) id previousValue;
|
|
|
|
/**
|
|
The value of the property after the change occurred. This will always be `nil`
|
|
for `RLMArray` properties.
|
|
*/
|
|
@property (nonatomic, readonly, strong, nullable) id value;
|
|
@end
|
|
|
|
#pragma mark - RLMArray Property Declaration
|
|
|
|
/**
|
|
Properties on `RLMObject`s of type `RLMArray` must have an associated type. A type is associated
|
|
with an `RLMArray` property by defining a protocol for the object type that the array should contain.
|
|
To define the protocol for an object, you can use the macro RLM_ARRAY_TYPE:
|
|
|
|
RLM_ARRAY_TYPE(ObjectType)
|
|
...
|
|
@property RLMArray<ObjectType *><ObjectType> *arrayOfObjectTypes;
|
|
*/
|
|
#define RLM_ARRAY_TYPE(RLM_OBJECT_SUBCLASS)\
|
|
@protocol RLM_OBJECT_SUBCLASS <NSObject> \
|
|
@end
|
|
|
|
NS_ASSUME_NONNULL_END
|