---

NSPersistentStore Class Reference

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; 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:

• type

• metadata

• metadataForPersistentStoreWithURL:error:

• setMetadata:forPersistentStoreWithURL:error:

Tasks

Initializing a Persistent Store

• – initWithPersistentStoreCoordinator:configurationName:URL:options:

Working with State Information

• – type
• – persistentStoreCoordinator
• – configurationName
• – options
• – URL
• – setURL:
• – identifier
• – setIdentifier:
• – isReadOnly
• – setReadOnly:

Managing Metadata

• + metadataForPersistentStoreWithURL:error:
• + setMetadata:forPersistentStoreWithURL:error:
• – metadata
• – setMetadata:

Setup and Teardown

• – didAddToPersistentStoreCoordinator:
• – willRemoveFromPersistentStoreCoordinator:

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 NSError object 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.h

setMetadata: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 NSError object 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.h

Instance 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.h

didAddToPersistentStoreCoordinator:

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.h

identifier

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

• – setIdentifier:
• – setMetadata:

Declared In

NSPersistentStore.h

initWithPersistentStoreCoordinator: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.

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 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

• – setMetadata:

Declared In

NSPersistentStore.h

isReadOnly

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.

Declared In

NSPersistentStore.h

metadata

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.

Declared In

NSPersistentStore.h

options

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.h

persistentStoreCoordinator

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.

Declared In

NSPersistentStore.h

setIdentifier:

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

• – identifier
• – metadata

Declared In

NSPersistentStore.h

setMetadata:

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.

Declared In

NSPersistentStore.h

setReadOnly:

Sets whether the receiver is read-only.

- (void)setReadOnly:(BOOL)flag

Parameters

flag

YES if the receiver is read-only, otherwise NO.

Availability

• Available in Mac OS X v10.5 and later.

Declared In

NSPersistentStore.h

setURL:

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

• – URL

Declared In

NSPersistentStore.h

type

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.

Declared In

NSPersistentStore.h

URL

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

• – setURL:

Declared In

NSPersistentStore.h

willRemoveFromPersistentStoreCoordinator:

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.

Declared In

NSPersistentStore.h

---