RKManagedObjectStore Class Reference
| Inherits from | NSObject |
| Declared in | RKManagedObjectStore.h |
Overview
The RKManagedObjectStore class encapsulates a Core Data stack including a managed object model, a persistent store coordinator, and a set of managed object contexts. The managed object store simplifies the task of properly setting up a Core Data stack and provides some additional functionality, such as the use of a seed database to initialize a SQLite backed persistent store and a simple code path for resetting the store by destroying and recreating the persistent stores.
Initialization
The managed object store is designed to easily initialize a Core Data stack in a recommended configuration. A store object must always be initialized with a managed object model, but this managed object model can be directly provided, inferred from an already configured persistent store coordinator, or read from the currently available bundles within the application. Note that several features provided by the framework rely on the store being initialized with a mutable managed object model. Please refer to the documentation in the initWithManagedObjectModel: for details.
Managed Object Contexts
The managed object store provides the application developer with a pair of managed objects with which to work with Core Data. The store configures a primary managed object context with the NSPrivateQueueConcurrencyType that is associated with the persistent store coordinator for handling Core Data persistence. A second context is also created with the NSMainQueueConcurrencyType that is a child of the primary managed object context for doing work on the main queue. Additional child contexts can be created directly or via a convenience method interface provided by the store (see newChildManagedObjectContextWithConcurrencyType:).
The managed object context hierarchy is designed to isolate the main thread from disk I/O and avoid deadlocks. Because the primary context manages its own private queue, saving the main queue context will not result in the objects being saved to the persistent store. The primary context must be saved as well for objects to be persisted to disk.
It is also worth noting that because of the parent/child context hierarchy, objects created on the main thread will not obtain permanent managed object ID’s even after the primary context has been saved. If you need to refer to the permanent representations of objects created on the main thread after a save, you may ask the main queue context to obtain permanent managed objects for your objects via obtainPermanentIDsForObjects:error:. Be warned that when obtaining permanent managed object ID’s, you must include all newly created objects that are reachable from the object you are concerned with in the set of objects provided to obtainPermanentIDsForObjects:error:. This means any newly created object in a one-to-one or one-to-many relationship must be provided or you will face a crash from the managed object context. This is due to a bug in Core Data still present in iOS5, but fixed in iOS6 (see Open Radar http://openradar.appspot.com/11478919)..)
Tasks
Accessing the Default Object Store
-
+ defaultStoreReturns the default managed object store for the application.
-
+ setDefaultStore:Sets the default managed object store for the application.
Initializing an Object Store
-
– initWithManagedObjectModel:Initializes the receiver with a given managed object model. This is the designated initializer for
RKManagedObjectStore. -
– initWithPersistentStoreCoordinator:Initializes the receiver with an existing persistent store coordinator.
-
– initInitializes the receiver with a managed object model obtained by merging the models from all of the application’s non-framework bundles.
Configuring Persistent Stores
-
– createPersistentStoreCoordinatorCreates a persistent store coordinator with the receiver’s managed object model. After invocation, the persistentStoreCoordinator property will no longer be nil.
-
– addInMemoryPersistentStore:Adds a new in memory persistent store to the persistent store coordinator of the receiver.
-
– addSQLitePersistentStoreAtPath:fromSeedDatabaseAtPath:withConfiguration:options:error:Adds a new SQLite persistent store, optionally initialized with a seed database, to the persistent store coordinator of the receiver.
-
– resetPersistentStores:Resets the persistent stores in the receiver’s persistent store coordinator and recreates them. If a store being reset is backed by a file on disk (such as a SQLite file), the file will be removed prior to recreating the store. If the store was originally created using a seed database, the seed will be recopied to reset the store to its seeded state.
Retrieving Details about the Store
-
managedObjectModelReturns the managed object model of the receiver.
property -
persistentStoreCoordinatorReturns the persistent store coordinator of the receiver.
property -
managedObjectCacheThe managed object cache associated with the receiver.
property
Working with Managed Object Contexts
-
– createManagedObjectContextsCreates the persistent store and main queue managed object contexts for the receiver.
-
persistentStoreManagedObjectContextReturns the managed object context of the receiver that is associated with the persistent store coordinator and is responsible for managing persistence.
property -
mainQueueManagedObjectContextThe main queue managed object context of the receiver.
property -
– newChildManagedObjectContextWithConcurrencyType:Creates a new child managed object context of the persistent store managed object context with a given concurrency type.
RKSearchAdditions Methods
-
– addSearchIndexingToEntityForName:onAttributes:Adds search indexing to the entity for the given name in the receiver’s managed object model.
-
searchIndexerThe search indexer for the receiver’s primary managed object context.
property -
– startIndexingPersistentStoreManagedObjectContextTells the search indexer to begin observing the persistent store managed object context for changes to searchable entities and updating the search words.
-
– stopIndexingPersistentStoreManagedObjectContextTells the search indexer to stop observing the persistent store managed object context for changes to searchable entities.
Properties
mainQueueManagedObjectContext
The main queue managed object context of the receiver.
@property (nonatomic, strong, readonly) NSManagedObjectContext *mainQueueManagedObjectContextDiscussion
The main queue context is available for usage on the main queue to drive user interface needs. The context is created with the NSMainQueueConcurrencyType and as such may be messaged directly from the main thread. The context is a child context of the persistentStoreManagedObjectContext and can persist changes up to the parent via a save.
Declared In
RKManagedObjectStore.hmanagedObjectCache
The managed object cache associated with the receiver.
@property (nonatomic, strong) id<RKManagedObjectCaching> managedObjectCacheDiscussion
The managed object cache is used to accelerate intensive Core Data operations by caching managed objects by their primary key value.
Default: An instance of RKFetchRequestManagedObjectCache.
Warning: A nil managed object cache will result in a store that is unable to uniquely identify existing objects by primary key attribute value and may result in the creation of duplicate objects within the store.
Declared In
RKManagedObjectStore.hmanagedObjectModel
Returns the managed object model of the receiver.
@property (nonatomic, strong, readonly) NSManagedObjectModel *managedObjectModelReturn Value
The managed object model of the receiver.
Declared In
RKManagedObjectStore.hpersistentStoreCoordinator
Returns the persistent store coordinator of the receiver.
@property (nonatomic, strong, readonly) NSPersistentStoreCoordinator *persistentStoreCoordinatorReturn Value
The persistent store coordinator of the receiver.
Declared In
RKManagedObjectStore.hpersistentStoreManagedObjectContext
Returns the managed object context of the receiver that is associated with the persistent store coordinator and is responsible for managing persistence.
@property (nonatomic, strong, readonly) NSManagedObjectContext *persistentStoreManagedObjectContextDiscussion
The persistent store context is created with the NSPrivateQueueConcurrencyType and as such must be interacted with using [NSManagedObjectContext performBlock:] or [NSManagedObjectContext performBlockAndWait:]. This context typically serves as the parent context for scratch contexts or main queue contexts for interacting with the user interface. Created by the invocation of createManagedObjectContexts.
Declared In
RKManagedObjectStore.hsearchIndexer
The search indexer for the receiver’s primary managed object context.
@property (nonatomic, readonly) RKSearchIndexer *searchIndexerDiscussion
A search indexer is instantiated when search indexing is added to an entity in the receiver’s managed object model.
Declared In
RKManagedObjectStore+RKSearchAdditions.hClass Methods
Instance Methods
addInMemoryPersistentStore:
Adds a new in memory persistent store to the persistent store coordinator of the receiver.
- (NSPersistentStore *)addInMemoryPersistentStore:(NSError **)errorParameters
- error
On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.
Return Value
The new persistent store, or nil in the event of an error.
Discussion
This method will invoke createPersistentStore if a persistent store coordinator has not yet been created.
Declared In
RKManagedObjectStore.haddSQLitePersistentStoreAtPath:fromSeedDatabaseAtPath:withConfiguration:options:error:
Adds a new SQLite persistent store, optionally initialized with a seed database, to the persistent store coordinator of the receiver.
- (NSPersistentStore *)addSQLitePersistentStoreAtPath:(NSString *)storePath fromSeedDatabaseAtPath:(NSString *)seedPath withConfiguration:(NSString *)nilOrConfigurationName options:(NSDictionary *)nilOrOptions error:(NSError **)errorParameters
- storePath
The path at which to save the persistent store on disk.
- seedPath
An optional path to a seed database to copy to the given storePath in the event that a store does not yet exist.
- nilOrConfigurationName
An optional name of a Core Data configuration in the managed object model.
- nilOrOptions
An optional dictionary of options with which to configure the persistent store. If
nil, a dictionary of options enablingNSMigratePersistentStoresAutomaticallyOptionandNSInferMappingModelAutomaticallyOptionwill be used.
- error
On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.
Discussion
Bug: Note that when built for iOS, this method will set a resource value on the SQLite file backing the persistent store for the NSURLIsExcludedFromBackupKey key set to YES to exclude the SQLite file from being backed up by iCloud to conform with the “iOS Data Storage Guidelines”
Warning: If the seed database at the given path was created with an incompatible managed object model an application error may be raised.
Declared In
RKManagedObjectStore.haddSearchIndexingToEntityForName:onAttributes:
Adds search indexing to the entity for the given name in the receiver’s managed object model.
- (void)addSearchIndexingToEntityForName:(NSString *)entityName onAttributes:(NSArray *)attributesParameters
- entityName
The name of the entity in the receiver’s managed object model that should be made searchable.
- attributes
An array of
NSAttributeDescriptionobjects orNSStringattribute names specifying theNSStringAttributeTypeattributes that are to be indexed for searching.
Discussion
Invocation of this method will result in the entity for the given name being updated to include a new to-many relationship with the name searchWords. The receiver’s search indexer will also be instructed to begin monitoring changes to the specified entity’s searchable attributes to maintain the collection of search words. If no search indexer exists, a new
Warning: Must be invoked before adding persistent stores as the managed object model will become immutable once the persistent store coordinator is created.
Declared In
RKManagedObjectStore+RKSearchAdditions.hcreateManagedObjectContexts
Creates the persistent store and main queue managed object contexts for the receiver.
- (void)createManagedObjectContextsDeclared In
RKManagedObjectStore.hcreatePersistentStoreCoordinator
Creates a persistent store coordinator with the receiver’s managed object model. After invocation, the persistentStoreCoordinator property will no longer be nil.
- (void)createPersistentStoreCoordinatorDiscussion
Warning: Creating the persistent store coordinator will render the managed object model immutable. Attempts to use functionality that requires a mutable managed object model after the persistent store coordinator has been created will raise an application error.
Declared In
RKManagedObjectStore.hinit
Initializes the receiver with a managed object model obtained by merging the models from all of the application’s non-framework bundles.
- (id)initDiscussion
Warning: Obtaining a managed object model by merging all bundles may result in an application error if versioned object models are in use.
Declared In
RKManagedObjectStore.hinitWithManagedObjectModel:
Initializes the receiver with a given managed object model. This is the designated initializer for RKManagedObjectStore.
- (id)initWithManagedObjectModel:(NSManagedObjectModel *)managedObjectModelParameters
- managedObjectModel
The managed object model with which to initialize the receiver.
Return Value
The receiver, initialized with the given managed object model.
Discussion
Bug: Several features require that the managed object model used to initialize the store be mutable so that entities may be changed before the persistent store coordinator is created. Since iOS 5, managed object models initialized via initWithContentsOfURL: return an immutable model. The application developer must send the returned managed object model a mutable copy message to ensure that it is mutable before initializing the managed object store. The recommended approach for initializing a managed object store is as follows:
NSURL *modelURL = [NSURL fileURLWithPath:[[NSBundle mainBundle] pathForResource:@"MyApplication" ofType:@"momd"]];
// NOTE: Due to an iOS 5 bug, the managed object model returned is immutable.
NSManagedObjectModel *managedObjectModel = [[[NSManagedObjectModel alloc] initWithContentsOfURL:modelURL] mutableCopy];
RKManagedObjectStore *managedObjectStore = [[RKManagedObjectStore alloc] initWithManagedObjectModel:managedObjectModel];
Declared In
RKManagedObjectStore.hinitWithPersistentStoreCoordinator:
Initializes the receiver with an existing persistent store coordinator.
- (id)initWithPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)persistentStoreCoordinatorParameters
- persistentStoreCoordinator
The persistent store coordinator with which to initialize the receiver.
Return Value
The receiver, initialized with the managed object model of the given persistent store coordinator and the persistent store coordinator.
Discussion
The managed object model from the persistent store coordinator will be used to initialize the receiver and the given persistent store coordinator will be configured as the persistent store coordinator for the managed object store.
This initialization method provides for easy integration with an existing Core Data stack.
Declared In
RKManagedObjectStore.hnewChildManagedObjectContextWithConcurrencyType:
Creates a new child managed object context of the persistent store managed object context with a given concurrency type.
- (NSManagedObjectContext *)newChildManagedObjectContextWithConcurrencyType:(NSManagedObjectContextConcurrencyType)concurrencyTypeParameters
- concurrencyType
The desired concurrency type for the new context.
Return Value
A newly created managed object context with the given concurrency type whose parent is the persistentStoreManagedObjectContext.
Declared In
RKManagedObjectStore.hresetPersistentStores:
Resets the persistent stores in the receiver’s persistent store coordinator and recreates them. If a store being reset is backed by a file on disk (such as a SQLite file), the file will be removed prior to recreating the store. If the store was originally created using a seed database, the seed will be recopied to reset the store to its seeded state.
- (BOOL)resetPersistentStores:(NSError **)errorParameters
- error
On input, a pointer to an error object. If an error occurs, this pointer is set to an actual error object containing the error information. You may specify nil for this parameter if you do not want the error information.
Return Value
A Boolean value indicating if the reset was successful.
Discussion
Bug: This method will implictly result in the managed object contexts associated with the receiver to be discarded and recreated. Any managed objects or additional child contexts associated with the store will need to be discarded or else exceptions may be raised (i.e. NSObjectInaccessibleException).
Also note that care must be taken to cancel/suspend all mapping operations, reset all managed object contexts, and disconnect all NSFetchedResultController objects that are associated with managed object contexts using the persistent stores of the receiver before attempting a reset. Failure to completely disconnect usage before calling this method is likely to result in a deadlock.
Declared In
RKManagedObjectStore.hstartIndexingPersistentStoreManagedObjectContext
Tells the search indexer to begin observing the persistent store managed object context for changes to searchable entities and updating the search words.
- (void)startIndexingPersistentStoreManagedObjectContextDiscussion
This is a convenience method that is equivalent to the following example code:
RKSearchIndexer *searchIndexer = managedObjectStore.searchIndexer;
[searchIndexer startObservingManagedObjectContext:managedObjectStore.persistentStoreManagedObjectContext];
Declared In
RKManagedObjectStore+RKSearchAdditions.hstopIndexingPersistentStoreManagedObjectContext
Tells the search indexer to stop observing the persistent store managed object context for changes to searchable entities.
- (void)stopIndexingPersistentStoreManagedObjectContextDiscussion
This is a convenience method that is equivalent to the following example code:
RKSearchIndexer *searchIndexer = managedObjectStore.searchIndexer;
[searchIndexer stopObservingManagedObjectContext:managedObjectStore.persistentStoreManagedObjectContext];
Declared In
RKManagedObjectStore+RKSearchAdditions.h