jens@0: /*
jens@0:  *  Ottoman.h
jens@0:  *  Ottoman
jens@0:  *
jens@0:  *  Created by Jens Alfke on 8/31/09.
jens@0:  *  Copyright 2009 Jens Alfke. All rights reserved.
jens@0:  *  BSD-Licensed: See the file "LICENSE.txt" for details.
jens@0:  */
jens@0: 
jens@0: #ifndef _MOOSEYARD_OTTOMAN_
jens@0: #define _MOOSEYARD_OTTOMAN_
jens@0: 
jens@0: namespace Mooseyard {
jens@0:     
jens@0:     class ChunkIterator;
jens@0:     class Dictionary;
jens@0:     class File;
jens@0:     class VersionDictionary;
jens@0:     class OverlayDictionary;
jens@0:     
jens@0:     
jens@0:     /** A version-controlled persistent dictionary. 
jens@0:         Each version is stored as a VersionDictionary, unsaved changes as an OverlayDictionary. */
jens@0:     class Ottoman {
jens@0:     public:
jens@0:         /** Creates an "untitled" Ottoman with no file and no lastVersion.
jens@0:             After adding values to the currentVersion, use saveAs to save it. */
jens@0:         Ottoman ();
jens@0:         
jens@0:         /** Opens an existing Ottoman file. */
jens@0:         explicit Ottoman (const char *filename, bool writeable =true);
jens@0:         
jens@0:         /** Closes an Ottoman. */
jens@0:         virtual ~Ottoman();
jens@0:         
jens@0:         /** The current filename, or NULL if the receiver is still in the "untitled" state. */
jens@0:         virtual const char* filename() const                {return _filename;}
jens@0:         
jens@0:         /** The latest saved version of the dictionary. 
jens@0:             Earlier versions can be accessed through its previousVersion() accessor.
jens@0:             This will be NULL if the receiver is still in the "untitled" state. */
jens@0:         virtual VersionDictionary* lastVersion() const         {return _lastVersion;}
jens@0:         
jens@0:         /** A mutable overlay representing the current state of the dictionary.
jens@0:             Changes are made in memory until save() is called.
jens@0:             This will be NULL if the receiver was opened read-only (writeable=false). */
jens@0:         virtual OverlayDictionary* currentVersion() const   {return _current;}
jens@0:         
jens@0:         /** Has the on-disk file been updated with newer revisions than what I know about? */
jens@0:         virtual bool needsSync() const;
jens@0:         
jens@0:         /** Reads any newer versions from disk.
jens@0:             Returns true if new versions were read, false if there were none.
jens@0:             Afterwards, lastVersion() will return the latest version in the file. 
jens@0:             (The old lastVersion dictionary is still around, so you can save a pointer to it 
jens@0:             before the call and use it later to see what changed.)
jens@0:             Changes made to the currentVersion dictionary are not lost, but are now relative
jens@0:             to the new lastVersion. You may want to scan them and resolve conflicts. */
jens@0:         virtual bool sync();
jens@0:         
jens@0:         /** Saves the current version to the file, by appending.
jens@0:             Returns false if there is a version conflict; in that case you need to call sync(),
jens@0:             possibly resolve conflicts, and then call save() again. */
jens@0:         virtual bool save();
jens@0:         
jens@0:         /** Saves the current version to the file, by writing to a new temporary file and
jens@0:             then atomically replacing the original. 
jens@0:             Older versions, and older copies of the data, are not preserved, so this
jens@0:             will typically shrink the file quite a bit.
jens@0:             Returns false if there is a version conflict. */
jens@0:         virtual bool saveAndCompact();
jens@0:          
jens@0:         /** Saves the current version to a new file, leaving the new file open, 
jens@0:             so subsequent saves will be written to it. */
jens@0:         virtual void saveAs (const char *newFilename, bool overwriteAllowed =true);
jens@0:         
jens@0:         /** Scans the file for damage. Returns true if the file is OK, false if problems are found.
jens@0:             If the 'repair' flag is set, will truncate the file to the last valid version. */
jens@0:         bool scavenge (bool repair =false);
jens@0:         
jens@0:         ChunkIterator* chunkIterator() const;       // for testing purposes
jens@0: 
jens@0:     private:
jens@0:         Ottoman(const Ottoman&);            // forbid copying/assignment
jens@0:         Ottoman& operator=(const Ottoman&);
jens@0:         
jens@0:         void _open();
jens@0:         void _append (File *dstFile);
jens@0:         File* _writeTo (const char *dstFileName, bool overwriteAllowed);
jens@0:         
jens@0:         bool _writeable;
jens@0:         File *_file;
jens@0:         char *_filename;
jens@0:         VersionDictionary *_lastVersion;
jens@0:         OverlayDictionary *_current;
jens@0:     };
jens@0:     
jens@0: }
jens@0: #endif // _MOOSEYARD_OTTOMAN_