5 // Created by Jens Alfke on 9/21/09.
6 // Copyright 2009 Jens Alfke. All rights reserved.
9 #import <Foundation/Foundation.h>
11 @class MYVersionDictionary, MYCurrentVersionDictionary;
14 /** A version-controlled persistent dictionary.
15 Each version is stored as a MYVersionDictionary,
16 unsaved changes as an MYCurrentVersionDictionary. */
17 @interface MYOttoman : NSObject
20 MYVersionDictionary *_lastVersion;
21 MYCurrentVersionDictionary *_currentVersion;
24 /** Creates an "untitled" Ottoman with no file and no lastVersion.
25 After adding values to the currentVersion, use saveAs to save it. */
28 /** Opens an existing Ottoman file. */
29 - (id) initWithURL: (NSURL*)fileURL writeable: (BOOL)writeable error: (NSError**)outError;
31 /** Closes an Ottoman. */
34 /** The current file, or nil if the receiver is still in the "untitled" state. */
35 @property (readonly) NSURL *URL;
37 /** The latest saved version of the dictionary.
38 Earlier versions can be accessed through its previousVersion property.
39 This will be nil if the receiver is still in the "untitled" state. */
40 @property (readonly) MYVersionDictionary* lastVersion;
42 /** A mutable overlay representing the current state of the dictionary.
43 Changes are made in memory until -save is called.
44 This will be nil if the receiver was opened read-only (writeable=NO). */
45 @property (readonly) MYCurrentVersionDictionary* currentVersion;
47 /** Has the on-disk file been updated with newer revisions than what I know about? */
48 @property (readonly) BOOL needsSync;
50 /** Reads any newer versions from disk.
51 Returns YES if new versions were read, NO if there were none or on error.
52 Afterwards, -lastVersion will return the latest version in the file.
53 (The old lastVersion dictionary is still around, so you can save a pointer to it
54 before the call and use it later to see what changed.)
55 Changes made to the -currentVersion dictionary are not lost, but are now relative
56 to the new lastVersion. You may want to scan them and resolve conflicts. */
57 - (BOOL) sync: (NSError**)outError;
59 /** Saves the current version to the file, by appending.
60 Returns NO if there is a version conflict; in that case you need to call -sync,
61 possibly resolve conflicts, and then call -save again. */
62 - (BOOL) save: (NSError**)outError;
64 /** Saves the current version to the file, by writing to a new temporary file and
65 then atomically replacing the original.
66 Older versions, and older copies of the data, are not preserved, so this
67 will typically shrink the file quite a bit.
68 Returns NO if there is a version conflict. */
69 - (BOOL) saveAndCompact: (NSError**)outError;
71 /** Saves the current version to a new file, leaving the new file open,
72 so subsequent saves will be written to it. */
73 - (BOOL) saveAs: (NSURL*)newFileURL
74 overwriteAllowed: (BOOL)overwriteAllowed
75 error: (NSError**)outError;
77 /** Scans the file for damage. Returns YES if the file is OK, NO if problems are found.
78 If the 'repair' flag is set, will truncate the file to the last valid version. */
79 - (BOOL) scavengeAndRepair: (BOOL)repair error: (NSError**)outError;