MLObject Class Reference

Inherits from NSObject
Conforms to NSSecureCoding
Declared in MLObject.h

Overview

The MLObject class represent the data persisted to the MaxLeap cloud. This is the main class to interact with to fetch data from and save data to the cloud.

Subclassing Notes

Developers can subclass MLObject for a more native object-oriented class structure. Strongly-typed subclasses of MLObject must conform to the MLSubclassing protocol and must call registerSubclass to be returned by MLQuery and other MLObject factories. All methods in MLSubclassing except for [MLSubclassing leapClassName] are already implemented in the MLObject(Subclass) category. Inculding MLObject+Subclass.h in your implementation file provides these implementations automatically.

Subclasses support simpler initializers, query syntax, and dynamic synthesizers. The following shows an example subclass:

@code
@interface MYGame : MLObject MLSubclassing

// Accessing this property is the same as objectForKey:@"title"
@property (retain) NSString *title;

+ (NSString *)leapClassName;

@end

@implementation MYGame

@dynamic title;

+ (NSString *)leapClassName {
    return @"Game";
}

@end

MYGame *game = [[MYGame alloc] init];
game.title = @"Bughouse";
[game saveInBackgroundWithBlock:^(BOOL succeeded, NSError *error) {
    if (succeeded) {

    } else {

    }
}];
@endcode

Creating a MLObject

+ objectWithClassName:

Creates a new MLObject with a class name.

+ (instancetype)objectWithClassName:(NSString *)className

Parameters

className

A class name can be any alphanumeric string that begins with a letter. It represents an object in your app, like a User of a Document.

Return Value

Returns the object that is instantiated with the given class name.

Declared In

MLObject.h

+ objectWithoutDataWithClassName:objectId:

Creates a reference to an existing MLObject for use in creating associations between MLObjects. Calling isDataAvailable on this object will return NO until fetchIfNeeded or refresh has been called. No network request will be made.

+ (instancetype)objectWithoutDataWithClassName:(NSString *)className objectId:(nullable NSString *)objectId

Parameters

className

The object’s class.

objectId

The object id for the referenced object.

Return Value

A MLObject without data.

Declared In

MLObject.h

+ objectWithClassName:dictionary:

Creates a new MLObject with a class name, initialized with data constructed from the specified set of objects and keys.

+ (instancetype)objectWithClassName:(NSString *)className dictionary:(nullable NSDictionary ML_GENERIC ( NSString *, id ) *)dictionary

Parameters

className

The object’s class.

dictionary

An NSDictionary of keys and objects to set on the new MLObject.

Return Value

A MLObject with the given class name and set with the given data.

Declared In

MLObject.h

– initWithClassName:

Initializes a new MLObject with a class name.

- (instancetype)initWithClassName:(NSString *)className

Parameters

className

A class name can be any alphanumeric string that begins with a letter. It represents an object in your app, like a User or a Document.

Return Value

Returns the object that is instantiated with the given class name.

Declared In

MLObject.h

Managing Object Properties

  leapClassName

The class name of the object.

@property (nonatomic, readonly) NSString *leapClassName

Declared In

MLObject.h

  objectId

The id of the object.

@property (nonatomic, strong, readonly, nullable) NSString *objectId

Declared In

MLObject.h

  updatedAt

When the object was last updated.

@property (nonatomic, strong, readonly, nullable) NSDate *updatedAt

Declared In

MLObject.h

  createdAt

When the object was created.

@property (nonatomic, strong, readonly, nullable) NSDate *createdAt

Declared In

MLObject.h

– allKeys

Returns an array of the keys contained in this object. This does not include createdAt, updatedAt, authData, or objectId. It does include things like username and ACL.

- (NSArray ML_GENERIC ( NSString *) *)allKeys

Declared In

MLObject.h

– objectForKey:

Returns the object associated with a given key.

- (nullable id)objectForKey:(NSString *)key

Parameters

key

The key that the object is associated with.

Return Value

The value associated with the given key, or nil if no value is associated with key.

Declared In

MLObject.h

– setObject:forKey:

Sets the object associated with a given key.

- (instancetype)setObject:(id)object forKey:(NSString *)key

Parameters

object

The object for key. A strong reference to the object is maintained by MLObject.

key

The key. Raises an NSInvalidArgumentException if key is nil.

Discussion

Setting nil for key results in unsetting the key on the object. This is the same behavior as removeObjectForKey:. If you need to represent a nil value, use NSNull.

Declared In

MLObject.h

– removeObjectForKey:

Unsets a key on the object.

- (instancetype)removeObjectForKey:(NSString *)key

Parameters

key

The key.

Declared In

MLObject.h

– objectForKeyedSubscript:

  • In LLVM 4.0 (XCode 4.5) or higher allows myMLObject[key].
- (nullable id)objectForKeyedSubscript:(NSString *)key

Parameters

key

The key.

Declared In

MLObject.h

– setObject:forKeyedSubscript:

  • In LLVM 4.0 (XCode 4.5) or higher allows myObject[key] = value
- (void)setObject:(id)object forKeyedSubscript:(NSString *)key

Parameters

object

The object. A strong reference to the object is maintained by MLObject.

key

The key. Raises an NSInvalidArgumentException if key is nil.

Discussion

Setting nil for key results in unsetting the key on the object. This is the same behavior as removeObjectForKey:. If you need to represent a nil value, use NSNull.

Declared In

MLObject.h

– relationForKey:

Returns the relation object associated with the given key

- (MLRelation *)relationForKey:(NSString *)key

Parameters

key

The key that the relation is associated with.

Declared In

MLObject.h

– addObject:forKey:

Adds an object to the end of the array associated with a given key.

- (instancetype)addObject:(id)object forKey:(NSString *)key

Parameters

object

The object to add.

key

The key.

Declared In

MLObject.h

– addObjectsFromArray:forKey:

Adds the objects contained in another array to the end of the array associated with a given key.

- (instancetype)addObjectsFromArray:(NSArray *)objects forKey:(NSString *)key

Parameters

objects

The array of objects to add.

key

The key.

Declared In

MLObject.h

– addUniqueObject:forKey:

Adds an object to the array associated with a given key, only if it is not already present in the array. The position of the insert is not guaranteed.

- (instancetype)addUniqueObject:(id)object forKey:(NSString *)key

Parameters

object

The object to add.

key

The key.

Declared In

MLObject.h

– addUniqueObjectsFromArray:forKey:

Adds the objects contained in another array to the array associated with a given key, only adding elements which are not already present in the array. The position of the insert is not guaranteed.

- (instancetype)addUniqueObjectsFromArray:(NSArray *)objects forKey:(NSString *)key

Parameters

objects

The array of objects to add.

key

The key.

Declared In

MLObject.h

– removeObject:forKey:

Removes all occurrences of an object from the array associated with a given key.

- (instancetype)removeObject:(id)object forKey:(NSString *)key

Parameters

object

The object to remove.

key

The key.

Declared In

MLObject.h

– removeObjectsInArray:forKey:

Removes all occurrences of the objects contained in another array from the array associated with a given key.

- (instancetype)removeObjectsInArray:(NSArray *)objects forKey:(NSString *)key

Parameters

objects

The array of objects to remove.

key

The key.

Declared In

MLObject.h

– incrementKey:

Increments the given key by 1.

- (instancetype)incrementKey:(NSString *)key

Parameters

key

The key.

Declared In

MLObject.h

– incrementKey:byAmount:

Increments the given key by a number.

- (instancetype)incrementKey:(NSString *)key byAmount:(NSNumber *)amount

Parameters

key

The key.

amount

The amount to increment.

Declared In

MLObject.h

– clear

Clear all keys on this object by creating delete operations for each key.

- (void)clear

Declared In

MLObject.h

– isDataAvailable

Gets whether the MLObject has been fetched.

- (BOOL)isDataAvailable

Return Value

YES if the MLObject is new or has been fetched or refreshed. NO otherwise.

Declared In

MLObject.h

– isDirty

Gets whether any key-value pair in this object (or its children) has been added/updated/removed and not saved yet.

- (BOOL)isDirty

Return Value

Returns whether this object has been altered and not saved yet.

Declared In

MLObject.h

– isDirtyForKey:

Get whether a value associated with a key has been added/updated/removed and not saved yet.

- (BOOL)isDirtyForKey:(NSString *)key

Parameters

key

The key to check for

Return Value

Returns whether this key has been altered and not saved yet.

Declared In

MLObject.h

Saving an Object to MaxLeap

– saveInBackgroundWithBlock:

Save asynchronously and executes the given callback block.

- (void)saveInBackgroundWithBlock:(nullable MLBooleanResultBlock)block

Parameters

block

The block to execute. The block should have the following argument signature: (BOOL succeeded, NSError *error)

Declared In

MLObject.h

Saving Many Objects to MaxLeap

+ saveAllInBackground:block:

Saves a collection of objects all at once asynchronously and the block when done.

+ (void)saveAllInBackground:(nullable NSArray ML_GENERIC ( MLObject *) *)objects block:(nullable MLBooleanResultBlock)block

Parameters

objects

The array of objects to save.

block

The block to execute. The block should have the following argument signature: (BOOL succeeded, NSError *error)

Declared In

MLObject.h

Removing an Object from MaxLeap

– deleteInBackgroundWithBlock:

Deletes the MLObject asynchronously and executes the given callback block.

- (void)deleteInBackgroundWithBlock:(nullable MLBooleanResultBlock)block

Parameters

block

The block to execute. The block should have the following argument signature: (BOOL succeeded, NSError *error)

Declared In

MLObject.h

Delete Many Objects from MaxLeap

+ deleteAllInBackground:block:

Deletes a collection of objects all at once asynchronously and excutes the block when done.

+ (void)deleteAllInBackground:(nullable NSArray ML_GENERIC ( MLObject *) *)objects block:(nullable MLBooleanResultBlock)block

Parameters

objects

The array of objects to delete.

block

The block to execute. The block should have the following argument signature: (BOOL succeeded, NSError *error)

Declared In

MLObject.h

Getting an Object from MaxLeap

– fetchInBackgroundWithBlock:

Fetches the MLObject asynchronously and executes the given callback block.

- (void)fetchInBackgroundWithBlock:(nullable MLObjectResultBlock)block

Parameters

block

The block to execute. The block should have the following argument signature: (MLObject object, NSError error)

Declared In

MLObject.h

– fetchIfNeededInBackgroundWithBlock:

Fetches the MLObject’s data asynchronously if isDataAvailable is false, then calls the callback block.

- (void)fetchIfNeededInBackgroundWithBlock:(nullable MLObjectResultBlock)block

Parameters

block

block The block to execute. The block should have the following argument signature: (MLObject object, NSError error)

Declared In

MLObject.h

Getting Many Objects from MaxLeap

+ fetchAllInBackground:block:

Fetches all of the MLObjects with the current data from the server asynchronously and calls the given block.

+ (void)fetchAllInBackground:(nullable NSArray ML_GENERIC ( MLObject *) *)objects block:(nullable MLArrayResultBlock)block

Parameters

objects

An NSArray of MLObjects.

block

The block to execute. The block should have the following argument signature: (NSArray objects, NSError error)

Declared In

MLObject.h

+ fetchAllIfNeededInBackground:block:

Fetches all of the MLObjects with the current data from the server asynchronously and calls the given block.

+ (void)fetchAllIfNeededInBackground:(nullable NSArray ML_GENERIC ( MLObject *) *)objects block:(nullable MLArrayResultBlock)block

Parameters

objects

The list of objects to fetch.

block

The block to execute. The block should have the following argument signature: (NSArray objects, NSError error)

Declared In

MLObject.h

Subclass Methods

– init

Designated initializer for subclasses.
This method can only be called on subclasses which conform to MLSubclassing.
This method should not be overridden.

- (instancetype)init

Declared In

MLObject+Subclass.h

+ object

Creates an instance of the registered subclass with this class’s leapClassName.

+ (instancetype)object

Discussion

This helps a subclass ensure that it can be subclassed itself. For example, [MLUserobject] will return a MyUser object if MyUser is a registered subclass of MLUser. For this reason, [MyClass object] is preferred to [[MyClass alloc] init].

This method can only be called on subclasses which conform to MLSubclassing.

A default implementation is provided by MLObject which should always be sufficient.

Declared In

MLObject+Subclass.h

+ leapClassName

The name of the class as seen in the REST API.

+ (NSString *)leapClassName

Declared In

MLObject+Subclass.h

+ objectWithoutDataWithObjectId:

Creates a reference to an existing MLObject for use in creating associations between MLObjects. Calling isDataAvailable on this object will return NO until fetchIfNeeded has been called. No network request will be made.

+ (instancetype)objectWithoutDataWithObjectId:(nullable NSString *)objectId

Parameters

objectId

The object id for the referenced object.

Return Value

A MLObject without data.

Discussion

This method can only be called on subclasses which conform to MLSubclassing.

A default implementation is provided by MLObject which should always be sufficient.

Declared In

MLObject+Subclass.h

+ registerSubclass

Registers an Objective-C class for MaxLeap to use for representing a given MaxLeap class.

+ (void)registerSubclass

Discussion

Once this is called on a MLObject subclass, any MLObject MaxLeap creates with a class name matching [self leapClassName] will be an instance of subclass.

This method can only be called on subclasses which conform to MLSubclassing.

A default implementation is provided by MLObject which should always be sufficient.

Declared In

MLObject+Subclass.h

+ query

Returns a query for objects of type leapClassName.

+ (nullable MLQuery *)query

Discussion

This method can only be called on subclasses which conform to MLSubclassing.

A default implementation is provided by MLObject which should always be sufficient.

Declared In

MLObject+Subclass.h