#import <CDBStore.h>
Inherited by CDBStringKeyStore.
Compared to a property list, a CDBStore is more flexible: the values can be any objects that support the NSCoding protocol, and the dictionary can be changed in place and saved back to the file. CDBStore also scales better, since the keys and values aren't read into memory until accessed.
Compared to CoreData, CDBStore is much simpler to use, especially if you want to retrofit existing code that uses NSDictionaries or property lists. It's also faster at what it does, since it doesn't have the overhead of a SQL interpreter and object-relational mapping. However, it is of course much more limited in functionality, as the only sorts of "queries" it offers are simple key-identity lookups.
How it works:
Keys are translated into raw data blobs and looked up in a CDBReader. The data values are translated into NSObjects, using an NSKeyedUnarchiver if necessary, and stored in an in-memory cache dictionary for speedy subsequent lookups (with object-identity.)
A modified value is stored back into the cache, and the key is marked as being changed.
To save the store, a CDBWriter is created on a temporary file, and all of the key/value pairs are written to it. Unmodified, undeleted values are copied directly over as data from the old CDB file, while modified or inserted values are first archived into NSData and then written. After this completes successfully, the original file is atomically replaced with the new file. This guarantees that the file always exists and is valid; if anything goes wrong while saving, or the system crashes, the worst that happens is that the latest changes are lost.
Public Member Functions | |
| (id) | - initWithFile: |
| Creates a CDBStore that will read from the given file, which must be in CDB format. | |
| (BOOL) | - open: |
| Opens the CDB file for reading. | |
| (BOOL) | - close |
| Closes the CDBStore. | |
| (void) | - emptyCache |
| Empties the in-memory cache of already-read values. | |
| (id) | - objectForKey: |
| Just as in an NSDictionary, returns the object associated with the key, or else nil. | |
| (NSEnumerator *) | - keyEnumerator |
| Returns an enumerator that will return all the keys in the store, in arbitrary order. | |
| (NSEnumerator *) | - objectEnumerator |
| Returns an enumerator that will return all the objects (values) in the store, in arbitrary order. | |
| (NSDictionary *) | - allKeysAndValues |
| Reads all keys and values into memory and returns them in the form of a regular NSDictionary. | |
| (void) | - setObject:forKey: |
| Just as in an NSDictionary, associates an object with a key. | |
| (void) | - objectChangedForKey: |
| Notifies the store that the object associated with the key has changed its persistent representation, and should be saved. | |
| (void) | - objectChanged: |
| Notifies the store that the value object has changed its persistent representation, and should be saved. | |
| (BOOL) | - save: |
| Saves the store to its file, if any changes have been made. | |
| (void) | - saveSoon |
| As an alternative to enabling autosave, you can call this method to schedule a save "soon" (at the end of the current run-loop cycle. | |
For subclasses to override | |
| (CDBData) | - encodeKey: |
| Encodes a key as raw bytes for use as a CDB key. | |
| (id) | - decodeKey: |
| Decodes raw CDB key bytes back into a key object. | |
| (NSData *) | - encodeObject:tag: |
| Encodes a value as raw bytes for use as a CDB value. | |
| (id) | - decodeObject:tag: |
| Decodes a raw CDB value into an object: the inverse of -encodeObject:. | |
Properties | |
| readonly NSString * | file |
| The path of the CDBStore's file. | |
| readonly BOOL | isOpen |
| Is the CDBStore open? | |
| readonly BOOL | hasChanges |
| Does the store contain any unsaved changes? | |
| readonly NSSet * | changedKeys |
| The set of keys whose values have been added, changed or deleted since the last save. | |
| NSTimeInterval | autosaveInterval |
| The time interval after which the store will automatically save changes. | |
| - (id) initWithFile: | (NSString*) | path |
Creates a CDBStore that will read from the given file, which must be in CDB format.
The file will not be opened or read from until the -open method is called.
| - (BOOL) open: | (NSError**) | outError |
Opens the CDB file for reading.
If an error occurs, returns NO and sets *outError. It is not an error for the file to be missing: CDBStore treats this as an empty file, and will create the file the first time -save: is called. If the file is already open, this method does nothing and returns YES.
| - (BOOL) close |
Closes the CDBStore.
Any unsaved changes are saved to the file, and the file is closed. The object cache is emptied. Afterwards, the store's objects cannot be accessed unless the store is re-opened. The store is implicitly closed when dealloced or finalized, but it's better to close it manually when you're done with it, in case a dangling reference bug prevents the object from being cleaned up.
| - (void) emptyCache |
Empties the in-memory cache of already-read values.
Unsaved changes are kept in the cache, however.
| - (id) objectForKey: | (id) | key |
Just as in an NSDictionary, returns the object associated with the key, or else nil.
| key | The dictionary key. By default, only NSData objects are allowed. Additional types of keys can be supported by subclassing CDBStore and overriding the -encodeKey: and decodeKey: methods. |
| - (NSEnumerator *) keyEnumerator |
Returns an enumerator that will return all the keys in the store, in arbitrary order.
| - (NSEnumerator *) objectEnumerator |
Returns an enumerator that will return all the objects (values) in the store, in arbitrary order.
| - (NSDictionary *) allKeysAndValues |
Reads all keys and values into memory and returns them in the form of a regular NSDictionary.
Needless to say, this can be very expensive if the file is large!
| - (void) setObject: | (id) | object | ||
| forKey: | (id) | key | ||
Just as in an NSDictionary, associates an object with a key.
| object | The new value to associate with the key. A nil value is legal, and deletes any previous value associated with the key. | |
| key | The dictionary key. By default, only NSData objects are allowed. Additional types of keys can be supported by subclassing CDBStore and overriding the -encodeKey: and decodeKey: methods. |
| - (void) objectChangedForKey: | (id) | key |
Notifies the store that the object associated with the key has changed its persistent representation, and should be saved.
| - (void) objectChanged: | (id) | object |
Notifies the store that the value object has changed its persistent representation, and should be saved.
This is slower than -objectChangedForKey:, and should only be used in contexts where you don't know the key associated with the object.
| - (BOOL) save: | (NSError**) | outError |
Saves the store to its file, if any changes have been made.
If the file didn't originally exist, this will create it. The file is saved atomically, by creating a new copy and swapping it in. (This is safer, but slower, than a typical database's save-in-place.)
| - (void) saveSoon |
As an alternative to enabling autosave, you can call this method to schedule a save "soon" (at the end of the current run-loop cycle.
) Multiple consecutive calls to this method only result in one save.
| - (CDBData) encodeKey: | (id) | key |
Encodes a key as raw bytes for use as a CDB key.
By default this only supports NSData objects.
| key | The key passed to a public API call like -objectForKey:. |
| - (id) decodeKey: | (CDBData) | keyData |
Decodes raw CDB key bytes back into a key object.
By default this creates NSData objects.
| keyData | Points to the raw CDB key read from the file. |
| - (NSData *) encodeObject: | (id) | object | ||
| tag: | (UInt8*) | outTag | ||
Encodes a value as raw bytes for use as a CDB value.
By default this supports any NSCoding-compliant object, with optimizations for NSData and NSString.
| object | The object (value) to be encoded. | |
| outTag | On return, should be set to a byte value that distinguishes the type of encoding used. The values 0..31 are reserved; subclasses should use other values. |
| - (id) decodeObject: | (CDBData) | data | ||
| tag: | (UInt8) | tag | ||
Decodes a raw CDB value into an object: the inverse of -encodeObject:.
Overrides should inspect the tag; if it matches a custom tag that they encode, they should decode and return the object. Otherwise call the inherited method.
| data | Points to the raw data from the CDB file (which was originally created by a call to -encodeObject:tag:.) | |
| tag | The tag associated with the data in the file (originally returned from -encodeObject:tag:.) |
| - (readonly NSString*) file |
The path of the CDBStore's file.
| - (NSSet *) changedKeys |
The set of keys whose values have been added, changed or deleted since the last save.
| - (NSTimeInterval) autosaveInterval |
The time interval after which the store will automatically save changes.
The default value is zero, which denotes "never", disabling auto-save.
1.5.4