kylefang/RestKit
1
0
Fork 0
mirror of https://github.com/zhigang1992/RestKit.git synced 2026-04-22 20:18:53 +08:00
Code Issues Packages Projects Releases Wiki Activity

Updated header documentation for RKManagedObjectStore

Browse Source
This commit is contained in:
Blake Watters
2012-08-02 10:32:58 -04:00
parent 232b3eb861
commit 544be269da
1 changed files with 200 additions and 10 deletions
Download Patch File Download Diff File Expand all files Collapse all files

210
Code/CoreData/RKManagedObjectStore.h
View File

@@ -27,13 +27,70 @@
// Option containing the path to the seed database a SQLite store was initialized with
extern NSString * const RKSQLitePersistentStoreSeedDatabasePathOption;
/**
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 present as of iOS 6
(see Open Radar http://openradar.appspot.com/11478919).
@see NSManagedObjectContext (RKAdditions)
@see NSEntityDescription (RKAdditions)
*/
@interface RKManagedObjectStore : NSObject
///-----------------------------------------------------------------------------
/// @name Accessing the Default Object Store
///-----------------------------------------------------------------------------
/**
Returns the default managed object store for the application.
@return The default managed object store.
*/
+ (RKManagedObjectStore *)defaultStore;
/**
Sets the default managed object store for the application.
@param managedObjectStore The new default managed object store.
*/
+ (void)setDefaultStore:(RKManagedObjectStore *)managedObjectStore;
///-----------------------------------------------------------------------------
@@ -41,42 +98,175 @@ extern NSString * const RKSQLitePersistentStoreSeedDatabasePathOption;
///-----------------------------------------------------------------------------
/**
ADD NOTE ABOUT THE MANAGED OBJECT MODEL COMING BACK IMMUTABLE IN IOS 5+
Initializes the receiver with a given managed object model. This is the designated initializer for RKManagedObjectStore.
NSURL *modelURL = [NSURL fileURLWithPath:[[NSBundle mainBundle] pathForResource:@"GateGuru" ofType:@"momd"]];
// NOTE: Due to an iOS 5 bug, the managed object model returned is immutable.
NSManagedObjectModel *managedObjectModel = [[[NSManagedObjectModel alloc] initWithContentsOfURL:modelURL] mutableCopy];
@param managedObjectModel The managed object model with which to initialize the receiver.
@return The receiver, initialized with the given managed object model.
@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];
*/
- (id)initWithManagedObjectModel:(NSManagedObjectModel *)managedObjectModel;
/**
Initializes the receiver with an existing persistent store coordinator.
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.
@param persistentStoreCoordinator The persistent store coordinator with which to initialize the receiver.
@return The receiver, initialized with the managed object model of the given persistent store coordinator and
the persistent store coordinator.
*/
- (id)initWithManagedObjectModel:(NSManagedObjectModel *)managedObjectModel; // Designated initializer
- (id)initWithPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)persistentStoreCoordinator;
- (id)init; // calls initWithManagedObjectModel: by obtaining the merged model...
/**
Initializes the receiver with a managed object model obtained by merging the models from all of
the application's non-framework bundles.
@see [NSBundle allBundles]
@see [NSManagedObjectModel mergedModelFromBundles:]
@warning Obtaining a managed object model by merging all bundles may result in an application error
if versioned object models are in use.
*/
- (id)init;
///-----------------------------------------------------------------------------
/// @name Configuring Persistent Stores
///-----------------------------------------------------------------------------
- (NSPersistentStore *)addInMemoryPersistentStore:(NSError **)error;
- (NSPersistentStore *)addSQLitePersistentStoreAtPath:(NSString *)storePath fromSeedDatabaseAtPath:(NSString *)seedPath error:(NSError **)error;
/**
Creates a persistent store coordinator with the receiver's managed object model. After invocation,
the persistentStoreCoordinator property will no longer be nil.
@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.
*/
- (void)createPersistentStoreCoordinator;
/**
Adds a new in memory persistent store to the persistent store coordinator of the receiver.
This method will invoke createPersistentStore if a persistent store coordinator has not yet been created.
@param 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.
@returns The new persistent store, or nil in the event of an error.
*/
- (NSPersistentStore *)addInMemoryPersistentStore:(NSError **)error;
/**
Adds a new SQLite persistent store, optionally initialized with a seed database, to the persistent store coordinator of the receiver.
@param storePath The path at which to save the persistent store on disk.
@param seedPath An optional path to a seed database to copy to the given storePath in the event that a store does not yet exist.
@param 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.
@warning If the seed database at the given path was created with an incompatible managed object model an application error
may be raised.
*/
- (NSPersistentStore *)addSQLitePersistentStoreAtPath:(NSString *)storePath fromSeedDatabaseAtPath:(NSString *)seedPath error:(NSError **)error; // Will implictly create PSC
/**
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.
@param 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 A Boolean value indicating if the reset was successful.
@warning 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).
*/
- (BOOL)resetPersistentStores:(NSError **)error; // has the side-effect of recreating the managed object contexts. Respects seed database
///-----------------------------------------------------------------------------
/// @name Retrieving Details about the Store
///-----------------------------------------------------------------------------
// Core Data
/**
Returns the managed object model of the receiver.
@return The managed object model of the receiver.
*/
@property (nonatomic, retain, readonly) NSManagedObjectModel *managedObjectModel;
/**
Returns the persistent store coordinator of the receiver.
@return The persistent store coordinator of the receiver.
*/
@property (nonatomic, retain, readonly) NSPersistentStoreCoordinator *persistentStoreCoordinator;
/**
The managed object cache associated with the receiver.
The managed object cache is used to accelerate intensive Core Data operations by
caching managed objects by their primary key value.
@see RKManagedObjectCaching
@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.
*/
@property (nonatomic, retain) id<RKManagedObjectCaching> managedObjectCache;
///-----------------------------------------------------------------------------
/// @name Working with Managed Object Contexts
///-----------------------------------------------------------------------------
- (void)createManagedObjectContexts; // will raise exception if they are already created...
/**
Creates the primary and main queue managed object contexts for the receiver.
@see primaryManagedObjectContext
@see mainQueueManagedObjectContext
@raises NSInternalInconsistencyException Raised if the managed object contexts have already been created.
*/
- (void)createManagedObjectContexts;
/**
The primary managed object context of the receiver.
The primary context is responsible for managing persistence to the persistent store coordinator for the
managed object store. The context is created with the NSPrivateQueueConcurrencyType and as such must
be interacted with using [NSManagedObjectContext performBlock:] or [NSManagedObjectContext performBlockAndWait:].
The primary context is useful as the parent context for scratch contexts or main queue contexts for interacting
with the user interface. Created by the invocation of createManagedObjectContexts.
@see createManagedObjectContexts
*/
@property (nonatomic, retain, readonly) NSManagedObjectContext *primaryManagedObjectContext;
/**
The main queue managed object context of the receiver.
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 primaryManagedObjectContext and can persist changes up to the parent via a save.
*/
@property (nonatomic, retain, readonly) NSManagedObjectContext *mainQueueManagedObjectContext;
/**
Creates a new child managed object context of the primary managed object context with a given concurrency type.
@param concurrencyType The desired concurrency type for the new context.
@return A newly created managed object context with the given concurrency type whose parent is the primaryManagedObjectContext.
*/
- (NSManagedObjectContext *)newChildManagedObjectContextWithConcurrencyType:(NSManagedObjectContextConcurrencyType)concurrencyType;
@end