WTAData provides a light-weight interface for setting up an asynchronous CoreData stack. WTAData utilizes two NSManagedObjectContexts: main and background, for achieving fast and performant core data access. The main context is generally used for read access to the core data stack. The main context updates automatically when changes are saved by the background managed object context. The background context is primarily used for performing saves in background threads, such as when a network call completes.

Setting up a default stack supporting CoreData automigration by providing WTAData with your Core Data model.

WTAData *data = [[WTAData alloc] initWithModelNamed:@"WTADataExample"];

Once the stack is created, the stack is ready to go. In additon to the default initialization, WTAData provides some additional initializers for speciifc use-cases as shown below.

// Initialize a new configuration
WTADataConfiguration *configuration = [WTADataConfiguration defaultConfigurationWithModelNamed:@"WTADataExample"];

// Set flag for deleting the store on a model mis-match
[configuration setShouldDeleteStoreFileOnModelMismatch:YES];

// Set flag for deleting the store on sql integrity errors
[configuration setShouldDeleteStoreFileOnIntegrityErrors:YES];

// Set flag for using an in-memory store
[configuration setShouldUseInMemoryStore:YES];

[[WTAData alloc] initWithConfiguration:configuration];

Fetching entities from the store is easy using the categories provided by WTAData on NSManagedObjects

NSError *error = nil;
WTAData *data = <initialized stack>
[ManagedObject fetchInContext:data.mainContext error:&error];

See additional helpers in NSManagedObject+WTAData.h for more information.

WTAData provides simple mechanisms for saving and creating data in the background. For example, saving new items in the background is as simple as the following lines of code.

[self.data saveInBackground:^(NSManagedObjectContext *context) {
    Entity *entity = [Entity createEntityInContext:context];
    entity.stringAttribute = [NSString stringWithFormat:@"Entity Created"];
} completion:^(BOOL savedChanges, NSError *error) {
    NSLog(@"Changes saved %d with error %@", savedChanges, error);
}];

WTAData provides a set of import categories that help streamline importing JSON objects directly into Core Data. The import functions are specified in NSManagedObject+WTADataImport.h and define functionality such as importing an array of JSON items or importing a single item. The import functions also support importing relationships and will also use the import functionality on objects in the relationship.

WTAData provides the ability to customize and configure your JSON import by specifying key-value pairs in the UserInfo dictionary in the managed object model. WTAData will by default map your keys in the JSON dictionary to the property names in the NSManagedObject. For example, a key named 'data' in the JSON dictionary would set the 'data' property of your NSManagedObject.

A custom JSON key mapping can be made by adding the 'ImportName' key-value pair on an attribute and specifying the name of the JSON key. For example, the JSON key 'age_level' could be imported to the 'ageLevel' object property by specifying {ImportName: age_level}.

You can specify the primary key in the JSON to map to the primary key in your model. This is done by adding the key 'PrimaryAttribute' to the entity's user info dictionary and setting the value to the name of the attribute that should be used for the primary key.

Alternatively, if your entity specifies an attribute of the format '(entityName)ID', then if the JSON contains the same key, then that value will be used as the primary attribute.

WTAData defaults to using the ISO8601 format string of 'yyyy-MM-dd'T'HH:mm:ssZZZZZ' for date strings in JSON. You can customize this format by specifying the key 'DateFormat' and passing a date format string as the value on the attribute

Relationships pose an interesting challenge when importing, because there may be entities in a relationship that should no longer be part of the relationship or there may be cases where data needs to be merged when importing a JSON dictionary. WTAData provides custom merge policies when importing relationships that covers most common use cases. These are specified on the relationship using the 'MergePolicy' key and setting to one of the following values:

'Replace' - Replace Relationship Policy (DEFAULT)

The default policy for relationship imports. If a custom merge policy is not specified, this is the one that is used. All existing relationship items are removed and replaced with the JSON items.

'Merge' - Merge Relationship Policy

Updates any existing objects found in the relationships based on the primary key. This policy does not delete any objects.

'MergeAndPrune' - Merge and Prune Relationship Policy

Updates any existing objects found in the relationships based on the primary key. Any items not in the import set will be pruned from the relationship set.

There are 2 main imports used with WTAData, one for importing an array of JSON objects and one for importing a single object. Examples of these two are shown below:

// Single entity import
PrimaryKeyEntity *entity = [PrimaryKeyEntity importEntityFromObject:entityWithDataContent
                                                            context:self.wtaData.mainContext];

// Array import
NSArray *importedObjects = [PrimaryKeyEntity importEntitiesFromArray:objectArray];
                                                            context:self.wtaData.mainContext];

Additional import methods are defined in NSManagedObject+WTADataImport.h