NSPersistentStore Class Reference
| Inherits from | |
| Conforms to | |
| Framework | /System/Library/Frameworks/CoreData.framework |
| Availability | Available in Mac OS X v10.5 and later. |
| Declared in | NSPersistentStore.h |
| Companion guides | |
| Related sample code |
Overview
This class is the abstract base class for all Core Data persistent stores.
Core Data provides four store types—SQLite, Binary, XML, and In-Memory (the XML store is not available on iPhone OS); these are described in Persistent Stores. Core Data also provides a subclass of NSPersistentStore, NSAtomicStore. The Binary and XML stores are examples of atomic stores that inherit functionality from NSAtomicStore.
Subclassing Notes
You should not subclass NSPersistentStore directly. Core Data currently only supports subclassing of NSAtomicStore.
The designated initializer is initWithPersistentStoreCoordinator:configurationName:URL:options:. When you implement the initializer, you must ensure you load metadata during initialization and set it using setMetadata:.
You must override these methods:
Tasks
Initializing a Persistent Store
Working with State Information
-
– type
-
– persistentStoreCoordinator
-
– configurationName
-
– options
-
– URL
-
– setURL:
-
– identifier
-
– setIdentifier:
-
– isReadOnly
-
– setReadOnly:
Managing Metadata
-
+ metadataForPersistentStoreWithURL:error:
-
+ setMetadata:forPersistentStoreWithURL:error:
-
– metadata
-
– loadMetadata:
-
– setMetadata:
Setup and Teardown
Supporting Migration
Class Methods
metadataForPersistentStoreWithURL:error:
Returns the metadata from the persistent store at the given URL.
+ (NSDictionary *)metadataForPersistentStoreWithURL:(NSURL *)url error:(NSError **)error
Parameters
- url
The location of the store.
- error
If an error occurs, upon return contains an
NSErrorobject that describes the problem.
Return Value
The metadata from the persistent store at url. Returns nil if there is an error.
Special Considerations
Subclasses must override this method.
Availability
- Available in Mac OS X v10.5 and later.
Declared In
NSPersistentStore.hmigrationManagerClass
Returns the NSMigrationManager class for this store class.
+ (Class)migrationManagerClass
Return Value
The NSMigrationManager class for this store class
Discussion
In a subclass of NSPersistentStore, you can override this to provide a custom migration manager subclass (for example, to take advantage of store-specific functionality to improve migration performance).
Availability
- Available in Mac OS X v10.6 and later.
Declared In
NSPersistentStore.hsetMetadata:forPersistentStoreWithURL:error:
Sets the metadata for the store at a given URL.
+ (BOOL)setMetadata:(NSDictionary *)metadata forPersistentStoreWithURL:(NSURL *)url error:(NSError **)error
Parameters
- metadata
The metadata for the store at url.
- url
The location of the store.
- error
If an error occurs, upon return contains an
NSErrorobject that describes the problem.
Return Value
YES if the metadata was written correctly, otherwise NO.
Special Considerations
Subclasses must override this method to set metadata appropriately.
Availability
- Available in Mac OS X v10.5 and later.
Declared In
NSPersistentStore.hInstance Methods
configurationName
Returns the name of the managed object model configuration used to create the receiver.
- (NSString *)configurationName
Return Value
The name of the managed object model configuration used to create the receiver.
Availability
- Available in Mac OS X v10.5 and later.
Declared In
NSPersistentStore.hdidAddToPersistentStoreCoordinator:
Invoked after the receiver has been added to the persistent store coordinator.
- (void)didAddToPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator
Parameters
- coordinator
The persistent store coordinator to which the receiver was added.
Discussion
The default implementation does nothing. You can override this method in a subclass in order to perform any kind of setup necessary before the load method is invoked.
Availability
- Available in Mac OS X v10.5 and later.
Declared In
NSPersistentStore.hidentifier
Returns the unique identifier for the receiver.
- (NSString *)identifier
Return Value
The unique identifier for the receiver.
Discussion
The identifier is used as part of the managed object IDs for each object in the store.
Special Considerations
NSPersistentStore provides a default implementation to provide a globally unique identifier for the store instance.
Availability
- Available in Mac OS X v10.5 and later.
See Also
Declared In
NSPersistentStore.hinitWithPersistentStoreCoordinator:configurationName:URL:options:
Returns a store initialized with the given arguments.
- (id)initWithPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)root configurationName:(NSString *)name URL:(NSURL *)url options:(NSDictionary *)options
Parameters
- coordinator
A persistent store coordinator.
- configurationName
The name of the managed object model configuration to use. Pass
nilif you do not want to specify a configuration.- url
The URL of the store to load.
- options
A dictionary containing configuration options.
Return Value
A new store object, associated with coordinator, that represents a persistent store at url using the options in options and—if it is not nil—the managed object model configuration configurationName.
Discussion
You must ensure that you load metadata during initialization and set it using setMetadata:.
Special Considerations
This is the designated initializer for persistent stores.
Availability
- Available in Mac OS X v10.5 and later.
See Also
Declared In
NSPersistentStore.hisReadOnly
Returns a Boolean value that indicates whether the receiver is read-only.
- (BOOL)isReadOnly
Return Value
YES if the receiver is read-only, otherwise NO.
Availability
- Available in Mac OS X v10.5 and later.
Related Sample Code
Declared In
NSPersistentStore.hloadMetadata:
Instructs the receiver to load its metadata.
- (BOOL)loadMetadata:(NSError **)error
Parameters
- error
If an error occurs, upon return contains an
NSErrorobject that describes the problem.
Return Value
YES if the metadata was loaded correctly, otherwise NO.
Special Considerations
There is no way to return an error if the store is invalid.
Availability
- Available in Mac OS X v10.6 and later.
Declared In
NSPersistentStore.hmetadata
Returns the metadata for the receiver.
- (NSDictionary *)metadata
Return Value
The metadata for the receiver. The dictionary must include the store type (NSStoreTypeKey) and UUID (NSStoreUUIDKey).
Special Considerations
Subclasses must override this method to provide storage and persistence for the store metadata.
Availability
- Available in Mac OS X v10.5 and later.
Related Sample Code
Declared In
NSPersistentStore.hoptions
Returns the options with which the receiver was created.
- (NSDictionary *)options
Return Value
The options with which the receiver was created.
Discussion
See NSPersistentStoreCoordinator for a list of key names for options in this dictionary.
Availability
- Available in Mac OS X v10.5 and later.
Declared In
NSPersistentStore.hpersistentStoreCoordinator
Returns the persistent store coordinator which loaded the receiver.
- (NSPersistentStoreCoordinator *)persistentStoreCoordinator
Return Value
The persistent store coordinator which loaded the receiver.
Availability
- Available in Mac OS X v10.5 and later.
Related Sample Code
Declared In
NSPersistentStore.hsetIdentifier:
Sets the unique identifier for the receiver.
- (void)setIdentifier:(NSString *)identifier
Parameters
- identifier
The unique identifier for the receiver.
Availability
- Available in Mac OS X v10.5 and later.
See Also
Declared In
NSPersistentStore.hsetMetadata:
Sets the metadata for the receiver.
- (void)setMetadata:(NSDictionary *)storeMetadata
Parameters
- storeMetadata
The metadata for the receiver.
Availability
- Available in Mac OS X v10.5 and later.
Related Sample Code
Declared In
NSPersistentStore.hsetReadOnly:
Sets whether the receiver is read-only.
- (void)setReadOnly:(BOOL)flag
Parameters
- flag
YESif the receiver is read-only, otherwiseNO.
Availability
- Available in Mac OS X v10.5 and later.
Declared In
NSPersistentStore.hsetURL:
Sets the URL for the receiver.
- (void)setURL:(NSURL *)url
Parameters
- url
The URL for the receiver.
Discussion
To alter the location of a store, send the persistent store coordinator a setURL:forPersistentStore: message.
Availability
- Available in Mac OS X v10.5 and later.
See Also
Declared In
NSPersistentStore.htype
Returns the type string of the receiver.
- (NSString *)type
Return Value
The type string of the receiver.
Discussion
This string is used when specifying the type of store to add to a persistent store coordinator.
Special Considerations
Subclasses must override this method to provide a unique type.
Availability
- Available in Mac OS X v10.5 and later.
Related Sample Code
Declared In
NSPersistentStore.hURL
Returns the URL for the receiver.
- (NSURL *)URL
Return Value
The URL for the receiver.
Availability
- Available in Mac OS X v10.5 and later.
See Also
Related Sample Code
Declared In
NSPersistentStore.hwillRemoveFromPersistentStoreCoordinator:
Invoked before the receiver is removed from the persistent store coordinator.
- (void)willRemoveFromPersistentStoreCoordinator:(NSPersistentStoreCoordinator *)coordinator
Parameters
- coordinator
The persistent store coordinator from which the receiver was removed.
Discussion
The default implementation does nothing. You can override this method in a subclass in order to perform any clean-up before the store is removed from the coordinator (and deallocated).
Availability
- Available in Mac OS X v10.5 and later.
Related Sample Code
Declared In
NSPersistentStore.h© 2009 Apple Inc. All Rights Reserved. (Last updated: 2009-05-01)
