| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/CoreData.framework |
| Availability | Available in Mac OS X v10.4 and later. |
| Declared in | NSPersistentStoreCoordinator.h |
| Companion guides | |
Instances of NSPersistentStoreCoordinator associate persistent stores (by type) with a model (or more accurately, a configuration of a model) and serve to mediate between the persistent store or stores and the managed object context or contexts. Instances of NSManagedObjectContext use a coordinator to save object graphs to persistent storage and to retrieve model information. A context without a coordinator is not fully functional as it cannot access a model except through a coordinator. The coordinator is designed to present a façade to the managed object contexts such that a group of persistent stores appears as an aggregate store. A managed object context can then create an object graph based on the union of all the data stores the coordinator covers.
Coordinators do the opposite of providing for concurrency—€”they serialize operations. If you want to use multiple threads for different write operations you use multiple coordinators. Note that if multiple threads work directly with a coordinator, they need to lock and unlock it explicitly.
Each coordinator (and thus container) may use different copies, and hence different versions, of a managed object model. This allows you to cleanly deal with file versioning.
The coordinator gives access to its underlying object stores. You can retrieve an object store when you first add one (using addPersistentStoreWithType:configuration:URL:options:error:), or by using persistentStoreForURL: or persistentStores. This allows you to to determine, for example, whether a store has already been added, or whether two objects come from the same store.
You move a store from one location to another, or change the type of a store, using migratePersistentStore:toURL:options:withType:error:.
You can set metadata for a given store using the persistent store coordinator (setMetadata:forPersistentStore:).
For more details about these tasks, see Persistent Store Features in Core Data Programming Guide.
– addPersistentStoreWithType:configuration:URL:options:error:
– setURL:forPersistentStore:
– removePersistentStore:error:
– migratePersistentStore:toURL:options:withType:error:
– persistentStores
– persistentStoreForURL:
– URLForPersistentStore:
– metadataForPersistentStore:
– setMetadata:forPersistentStore:
+ setMetadata:forPersistentStoreOfType:URL:error:
+ metadataForPersistentStoreOfType:URL:error:
+ metadataForPersistentStoreWithURL:error: Deprecated in Mac OS X v10.5
+ elementsDerivedFromExternalRecordURL:
– importStoreWithIdentifier:fromExternalRecordsDirectory:toURL:options:withType:error:
Returns a dictionary containing the parsed elements derived from the Spotlight external record file specified by the given URL.
+ (NSDictionary *)elementsDerivedFromExternalRecordURL:(NSURL *)fileURL
A file URL specifying the location of a Spotlight external record file.
A dictionary containing the parsed elements derived from the Spotlight support file specified by fileURL.
Dictionary keys and the corresponding values are described in “Spotlight External Record Elements.”
NSPersistentStoreCoordinator.hReturns a dictionary containing the metadata stored in the persistent store at a given URL.
+ (NSDictionary *)metadataForPersistentStoreOfType:(NSString *)storeType URL:(NSURL *)url error:(NSError **)error
The type of the store at url. If this value is nil, Core Data determines which store class should be used to get or set the store file's metadata by inspecting the file contents.
The location of a persistent store.
If no store is found at url or if there is a problem accessing its contents, upon return contains an NSError object that describes the problem.
A dictionary containing the metadata stored in the persistent store at url, or nil if the store cannot be opened or if there is a problem accessing its contents.
The keys guaranteed to be in this dictionary are NSStoreTypeKey and NSStoreUUIDKey.
You can use this method to retrieve the metadata from a store without the overhead of creating a Core Data stack.
NSPersistentStoreCoordinator.hReturns a dictionary of the registered store types.
+ (NSDictionary *)registeredStoreTypes
A dictionary of the registered store types—the keys are the store type strings, and the values are the NSPersistentStore subclasses.
NSPersistentStoreCoordinator.hRegisters a given NSPersistentStore subclass for a given store type string.
+ (void)registerStoreClass:(Class)storeClass forStoreType:(NSString *)storeType
The NSPersistentStore subclass to use for the store of type storeType.
A unique string that identifies a store type.
You must invoke this method before a custom subclass of NSPersistentStore can be loaded into a persistent store coordinator.
You can pass nil for storeClass to unregister the store type.
NSPersistentStoreCoordinator.hSets the metadata for a given store.
+ (BOOL)setMetadata:(NSDictionary *)metadata forPersistentStoreOfType:(NSString *)storeType URL:(NSURL *)url error:(NSError **)error
A dictionary containing metadata for the store.
The type of the store at url. If this value is nil, Core Data will determine which store class should be used to get or set the store file's metadata by inspecting the file contents.
The location of a persistent store.
If no store is found at url or if there is a problem setting its metadata, upon return contains an NSError object that describes the problem.
YES if the metadata was set correctly, otherwise NO.
You can use this method to set the metadata for a store without the overhead of creating a Core Data stack.
NSPersistentStoreCoordinator.hAdds a new persistent store of a specified type at a given location, and returns the new store.
- (NSPersistentStore *)addPersistentStoreWithType:(NSString *)storeType configuration:(NSString *)configuration URL:(NSURL *)storeURL options:(NSDictionary *)options error:(NSError **)error
A string constant (such as NSSQLiteStoreType) that specifies the store type—see “Store Types” for possible values.
The name of a configuration in the receiver's managed object model that will be used by the new store. The configuration can be nil, in which case no other configurations are allowed.
The file location of the persistent store.
A dictionary containing key-value pairs that specify whether the store should be read-only, and whether (for an XML store) the XML file should be validated against the DTD before it is read. For key definitions, see “Store Options” and “Migration Options”. This value may be nil.
If a new store cannot be created, upon return contains an instance of NSError that describes the problem
The newly-created store or, if an error occurs, nil.
NSPersistentStoreCoordinator.hCreates and populates a store with the external records found at a given URL.
- (NSPersistentStore *)importStoreWithIdentifier:(NSString *)storeIdentifier fromExternalRecordsDirectory:(NSURL *)externalRecordsURL toURL:(NSURL *)destinationURL options:(NSDictionary *)options withType:(NSString *)storeType error:(NSError **)error
The identifier for a store.
If this value is nil then the method imports the records for the first store found.
The location of the directory containing external records.
An URL object that specifies the location for the new store.
There should be no existing store at this location, as the store will be created from scratch (appending to an existing store is not allowed).
A dictionary containing key-value pairs that specify whether the store should be read-only, and whether (for an XML store) the XML file should be validated against the DTD before it is read. For key definitions, see “Store Options.”
A string constant (such as NSSQLiteStoreType) that specifies the type of the new store—see “Store Types.”
If an error occurs, upon return contains an instance of NSError that describes the problem.
An object representing the newly-created store.
NSPersistentStoreCoordinator.hInitializes the receiver with a managed object model.
- (id)initWithManagedObjectModel:(NSManagedObjectModel *)model
A managed object model.
The receiver, initialized with model.
NSPersistentStoreCoordinator.hAttempts to acquire a lock.
- (void)lock
This method blocks a thread’€™s execution until the lock can be acquired. An application protects a critical section of code by requiring a thread to acquire a lock before executing the code. Once the critical section is past, the thread relinquishes the lock by invoking unlock.
NSPersistentStoreCoordinator.hReturns an object ID for the specified URI representation of an object ID if a matching store is available, or nil if a matching store cannot be found.
- (NSManagedObjectID *)managedObjectIDForURIRepresentation:(NSURL *)URL
An URL object containing a URI that specify a managed object.
An object ID for the object specified by URL.
The URI representation contains a UUID of the store the ID is coming from, and the coordinator can match it against the stores added to it.
URIRepresentation (NSManagedObjectID)objectWithID: (NSManagedObjectContext)NSPersistentStoreCoordinator.hReturns the receiver’s managed object model.
- (NSManagedObjectModel *)managedObjectModel
The receiver’s managed object model.
NSPersistentStoreCoordinator.hReturns a dictionary that contains the metadata currently stored or to-be-stored in a given persistent store.
- (NSDictionary *)metadataForPersistentStore:(NSPersistentStore *)store
A persistent store.
A dictionary that contains the metadata currently stored or to-be-stored in store.
NSPersistentStoreCoordinator.hMoves a persistent store to a new location, changing the storage type if necessary.
- (NSPersistentStore *)migratePersistentStore:(NSPersistentStore *)store toURL:(NSURL *)URL options:(NSDictionary *)options withType:(NSString *)storeType error:(NSError **)error
A persistent store.
An URL object that specifies the location for the new store.
A dictionary containing key-value pairs that specify whether the store should be read-only, and whether (for an XML store) the XML file should be validated against the DTD before it is read. For key definitions, see “Store Options.”
A string constant (such as NSSQLiteStoreType) that specifies the type of the new store—see “Store Types.”
If an error occurs, upon return contains an instance of NSError that describes the problem.
If the migration is successful, the new store, otherwise nil.
This method is typically used for “Save As”€ operations. Performance may vary depending on the type of old and new store. For more details of the action of this method, see Persistent Store Features in Core Data Programming Guide.
NSPersistentStoreCoordinator.hReturns the persistent store for the specified URL.
- (NSPersistentStore *)persistentStoreForURL:(NSURL *)URL
An URL object that specifies the location of a persistent store.
The persistent store at the location specified by URL.
NSPersistentStoreCoordinator.hReturns an array of persistent stores associated with the receiver.
- (NSArray *)persistentStores
An array persistent stores associated with the receiver.
NSPersistentStoreCoordinator.hRemoves a given persistent store.
- (BOOL)removePersistentStore:(NSPersistentStore *)store error:(NSError **)error
A persistent store.
If an error occurs, upon return contains an instance of NSError that describes the problem.
YES if the store is removed, otherwise NO.
NSPersistentStoreCoordinator.hSets the metadata stored in the persistent store during the next save operation executed on it to metadata.
- (void)setMetadata:(NSDictionary *)metadata forPersistentStore:(NSPersistentStore *)store
A dictionary containing metadata for the store.
A persistent store.
The store type and UUID (NSStoreTypeKey and NSStoreUUIDKey) are always added automatically, however NSStoreUUIDKey is only added if it is not set manually as part of the dictionary argument.
NSPersistentStoreCoordinator.hSets the URL for a given persistent store.
- (BOOL)setURL:(NSURL *)url forPersistentStore:(NSPersistentStore *)store
The new location for store.
A persistent store associated with the receiver.
YES if the store was relocated, otherwise NO.
For atomic stores, this method alters the location to which the next save operation will write the file; for non-atomic stores, invoking this method will release the existing connection and create a new one at the specified URL. (For non-atomic stores, a store must already exist at the destination URL; a new store will not be created.)
NSPersistentStoreCoordinator.hAttempts to acquire a lock.
- (BOOL)tryLock
YES if successful, otherwise NO.
Returns immediately—contrast lock which blocks.
NSPersistentStoreCoordinator.hRelinquishes a previously acquired lock.
- (void)unlock
NSPersistentStoreCoordinator.hReturns the URL for a given persistent store.
- (NSURL *)URLForPersistentStore:(NSPersistentStore *)store
A persistent store.
The URL for store.
NSPersistentStoreCoordinator.hTypes of persistent store.
NSString * const NSSQLiteStoreType; NSString * const NSXMLStoreType; NSString * const NSBinaryStoreType; NSString * const NSInMemoryStoreType;
NSSQLiteStoreTypeThe SQLite database store type.
Available in Mac OS X v10.4 and later.
Declared in NSPersistentStoreCoordinator.h.
NSXMLStoreTypeThe XML store type.
Available in Mac OS X v10.4 and later.
Declared in NSPersistentStoreCoordinator.h.
NSBinaryStoreTypeThe binary store type.
Available in Mac OS X v10.4 and later.
Declared in NSPersistentStoreCoordinator.h.
NSInMemoryStoreTypeThe in-memory store type.
Available in Mac OS X v10.4 and later.
Declared in NSPersistentStoreCoordinator.h.
Keys used in a store’€™s metadata dictionary.
NSString * const NSStoreTypeKey; NSString * const NSStoreUUIDKey;
NSStoreTypeKeyThe key in the metadata dictionary to identify the store type.
Available in Mac OS X v10.4 and later.
Declared in NSPersistentStoreCoordinator.h.
NSStoreUUIDKeyThe key in the metadata dictionary to identify the store UUID.
The store UUID is useful to identify stores through URI representations, but it is not guaranteed to be unique. The UUID generated for new stores is unique—users can freely copy files and thus the UUID stored inside—so if you track or reference stores explicitly you need to be aware of duplicate UUIDs and potentially override the UUID when a new store is added to the list of known stores in your application.
Available in Mac OS X v10.4 and later.
Declared in NSPersistentStoreCoordinator.h.
NSPersistentStoreCoordinator.hAn NSPersistentStoreCoordinatorStoresDidChangeNotification notification is posted whenever persistent stores are added to or removed from a persistent store coordinator, or when store UUIDs change. The userInfo dictionary contains information about the stores that were added or removed using these keys.
NSString * const NSAddedPersistentStoresKey; NSString * const NSRemovedPersistentStoresKey; NSString * const NSUUIDChangedPersistentStoresKey;
NSAddedPersistentStoresKeyKey for the array of stores that were added.
Available in Mac OS X v10.4 and later.
Declared in NSPersistentStoreCoordinator.h.
NSRemovedPersistentStoresKeyKey for the array of stores that were removed.
Available in Mac OS X v10.4 and later.
Declared in NSPersistentStoreCoordinator.h.
NSUUIDChangedPersistentStoresKeyKey for the array of stores whose UUIDs changed.
Available in Mac OS X v10.4 and later.
Declared in NSPersistentStoreCoordinator.h.
NSPersistentStoreCoordinator.hKeys for the options dictionary used in addPersistentStoreWithType:configuration:URL:options:error:, migratePersistentStore:toURL:options:withType:error:, and importStoreWithIdentifier:fromExternalRecordsDirectory:toURL:options:withType:error:.
NSString * const NSReadOnlyPersistentStoreOption; NSString * const NSValidateXMLStoreOption; NSString * const NSPersistentStoreTimeoutOption; NSString * const NSSQLitePragmasOption; NSString * const NSSQLiteAnalyzeOption; NSString * const NSSQLiteManualVacuumOption; NSString * const NSExternalRecordsDirectoryOption; NSString * const NSExternalRecordExtensionOption; NSString * const NSExternalRecordsFileFormatOption;
NSReadOnlyPersistentStoreOptionA flag that indicates whether a store is treated as read-only or not.
The default value is NO.
Available in Mac OS X v10.4 and later.
Declared in NSPersistentStoreCoordinator.h.
NSValidateXMLStoreOptionA flag that indicates whether an XML file should be validated with the DTD while opening.
The default value is NO.
Available in Mac OS X v10.4 and later.
Declared in NSPersistentStoreCoordinator.h.
NSPersistentStoreTimeoutOptionOptions key that specifies the connection timeout for Core Data stores.
The corresponding value is an NSNumber object that represents the duration in seconds that Core Data will wait while attempting to create a connection to a persistent store. If a connection is cannot be made within that timeframe, the operation is aborted and an error is returned.
Available in Mac OS X v10.5 and later.
Declared in NSPersistentStoreCoordinator.h.
NSSQLitePragmasOptionOptions key for a dictionary of SQLite pragma settings with pragma values indexed by pragma names as keys.
All pragma values must be specified as NSString objects. The fullfsync and synchronous pragmas control the tradeoff between write performance (write to disk speed & cache utilization) and durability (data loss/corruption sensitivity to power interruption). For more information on pragma settings, see http://sqlite.org/pragma.html.
Available in Mac OS X v10.5 and later.
Declared in NSPersistentStoreCoordinator.h.
NSSQLiteAnalyzeOptionOption key to run an analysis of the store data to optimize indices based on statistical information when the store is added to the coordinator.
This invokes SQLite's ANALYZE command. It is ignored by stores other than the SQLite store.
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
NSSQLiteManualVacuumOptionOption key to rebuild the store file, forcing a database wide defragmentation when the store is added to the coordinator.
This invokes SQLite's VACUUM command. It is ignored by stores other than the SQLite store.
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
NSExternalRecordsDirectoryOptionOption indicating the directory where Spotlight external record files should be written to.
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
NSExternalRecordExtensionOptionOption indicating the file extension to use for Spotlight external record files.
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
NSExternalRecordsFileFormatOptionOption to specify the file format of a Spotlight external records.
For possible values, see “Spotlight External Record File Format Options.”
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
Migration options, specified in the dictionary of options when adding a persistent store using addPersistentStoreWithType:configuration:URL:options:error:.
NSString * const NSIgnorePersistentStoreVersioningOption; NSString * const NSMigratePersistentStoresAutomaticallyOption; NSString * const NSInferMappingModelAutomaticallyOption;
NSIgnorePersistentStoreVersioningOptionKey to ignore the built-in versioning provided by Core Data.
The corresponding value is an NSNumber object. If the boolValue of the number is YES, Core Data will not compare the version hashes between the managed object model in the coordinator and the metadata for the loaded store. (It will, however, continue to update the version hash information in the metadata.) This key and corresponding value of YES is specified by default for all applications linked on or before Mac OS X 10.4.
Available in Mac OS X v10.5 and later.
Declared in NSPersistentStoreCoordinator.h.
NSMigratePersistentStoresAutomaticallyOptionKey to automatically attempt to migrate versioned stores.
The corresponding value is an NSNumber object. If the boolValue of the number is YES and if the version hash information for the added store is determined to be incompatible with the model for the coordinator, Core Data will attempt to locate the source and mapping models in the application bundles, and perform a migration.
Available in Mac OS X v10.5 and later.
Declared in NSPersistentStoreCoordinator.h.
NSInferMappingModelAutomaticallyOptionKey to attempt to create the mapping model automatically.
The corresponding value is an NSNumber object. If the boolValue of the number is YES and the value of the NSMigratePersistentStoresAutomaticallyOption is YES, the coordinator will attempt to infer a mapping model if none can be found.
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
Constants that specify the format for Spotlight external records. These constants are the possible values for the key NSExternalRecordsFileFormatOption.
NSString * const NSXMLExternalRecordType; NSString * const NSBinaryExternalRecordType;
NSXMLExternalRecordTypeSpecifies an XML file format.
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
NSBinaryExternalRecordTypeSpecifies a binary file format
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
Keys in store metadata to support versioning.
NSString * const NSStoreModelVersionHashesKey; NSString * const NSStoreModelVersionIdentifiersKey; NSString * const NSPersistentStoreOSCompatibility;
NSStoreModelVersionHashesKeyKey to represent the version hash information for the model used to create the store.
This key is used in the metadata for a persistent store.
Available in Mac OS X v10.5 and later.
Declared in NSPersistentStoreCoordinator.h.
NSStoreModelVersionIdentifiersKeyKey to represent the version identifiers for the model used to create the store.
If you add your own annotations to a model’s version identifier (see versionIdentifiers), they are stored in the persistent store’s metadata. You can use this key to retrieve the identifiers from the metadata dictionaries available from NSPersistentStore (metadata) and NSPersistentStoreCoordinator (metadataForPersistentStore: and related methods). The corresponding value is a Foundation collection (an NSArray or NSSet object).
Available in Mac OS X v10.5 and later.
Declared in NSPersistentStoreCoordinator.h.
NSPersistentStoreOSCompatibilityKey to represent the earliest version of Mac OS X the persistent store supports.
The corresponding value is an NSNumber object that takes the form of the constants defined by the Mac OS X availability macros (defined in /usr/include/AvailabilityMacros.h), for example 1040 represents Mac OS X version 10.4.0.
Backward compatibility may preclude some features.
Available in Mac OS X v10.5 and later.
Declared in NSPersistentStoreCoordinator.h.
Keys for the dictionary with the parsed elements derived from Spotlight external record file.
NSString * const NSEntityNameInPathKey; NSString * const NSStoreUUIDInPathKey; NSString * const NSStorePathKey; NSString * const NSModelPathKey; NSString * const NSObjectURIKey;
NSEntityNameInPathKeyDictionary key for the entity name extracted from an external record file.
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
NSStoreUUIDInPathKeyDictionary key for the store UUID extracted from an external record file.
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
NSStorePathKeyDictionary key for the store path (an instance of NSURL) extracted from an external record file.
This is resolved to the store-file path contained in the an external record file directory.
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
NSModelPathKeyDictionary key for the managed object model path (an instance of NSURL) extracted from an external record file.
This is resolved to the model.mom path contained in the external record file directory.
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
NSObjectURIKeyDictionary key for the object URI extracted from an external record file.
Available in Mac OS X v10.6 and later.
Declared in NSPersistentStoreCoordinator.h.
Posted whenever persistent stores are added to or removed from a persistent store coordinator, or when store UUIDs change.
The notification's object is the persistent store coordinator that was affected. The notification's userInfo dictionary contains information about the stores that were added or removed, specified using the following keys:
NSAddedPersistentStoresKey | Key for the array of stores that were added. |
NSRemovedPersistentStoresKey | Key for the array of stores that were removed. |
NSUUIDChangedPersistentStoresKey | Key for the array of stores whose UUIDs changed. |
NSPersistentStoreCoordinator.hPosted whenever a persistent store is removed from a persistent store coordinator.
The notification is sent during the invocation of NSPersistentStore's willRemoveFromPersistentStoreCoordinator method during store deallocation or removal. The notification's object is the persistent store coordinator will be removed.
NSPersistentStoreCoordinator.hLast updated: 2009-05-01