1.1 --- /dev/null	Thu Jan 01 00:00:00 1970 +0000
     1.2 +++ b/include/Ottoman.h	Sun Sep 20 15:14:12 2009 -0700
     1.3 @@ -0,0 +1,99 @@
     1.4 +/*
     1.5 + *  Ottoman.h
     1.6 + *  Ottoman
     1.7 + *
     1.8 + *  Created by Jens Alfke on 8/31/09.
     1.9 + *  Copyright 2009 Jens Alfke. All rights reserved.
    1.10 + *  BSD-Licensed: See the file "LICENSE.txt" for details.
    1.11 + */
    1.12 +
    1.13 +#ifndef _MOOSEYARD_OTTOMAN_
    1.14 +#define _MOOSEYARD_OTTOMAN_
    1.15 +
    1.16 +namespace Mooseyard {
    1.17 +    
    1.18 +    class ChunkIterator;
    1.19 +    class Dictionary;
    1.20 +    class File;
    1.21 +    class VersionDictionary;
    1.22 +    class OverlayDictionary;
    1.23 +    
    1.24 +    
    1.25 +    /** A version-controlled persistent dictionary. 
    1.26 +        Each version is stored as a VersionDictionary, unsaved changes as an OverlayDictionary. */
    1.27 +    class Ottoman {
    1.28 +    public:
    1.29 +        /** Creates an "untitled" Ottoman with no file and no lastVersion.
    1.30 +            After adding values to the currentVersion, use saveAs to save it. */
    1.31 +        Ottoman ();
    1.32 +        
    1.33 +        /** Opens an existing Ottoman file. */
    1.34 +        explicit Ottoman (const char *filename, bool writeable =true);
    1.35 +        
    1.36 +        /** Closes an Ottoman. */
    1.37 +        virtual ~Ottoman();
    1.38 +        
    1.39 +        /** The current filename, or NULL if the receiver is still in the "untitled" state. */
    1.40 +        virtual const char* filename() const                {return _filename;}
    1.41 +        
    1.42 +        /** The latest saved version of the dictionary. 
    1.43 +            Earlier versions can be accessed through its previousVersion() accessor.
    1.44 +            This will be NULL if the receiver is still in the "untitled" state. */
    1.45 +        virtual VersionDictionary* lastVersion() const         {return _lastVersion;}
    1.46 +        
    1.47 +        /** A mutable overlay representing the current state of the dictionary.
    1.48 +            Changes are made in memory until save() is called.
    1.49 +            This will be NULL if the receiver was opened read-only (writeable=false). */
    1.50 +        virtual OverlayDictionary* currentVersion() const   {return _current;}
    1.51 +        
    1.52 +        /** Has the on-disk file been updated with newer revisions than what I know about? */
    1.53 +        virtual bool needsSync() const;
    1.54 +        
    1.55 +        /** Reads any newer versions from disk.
    1.56 +            Returns true if new versions were read, false if there were none.
    1.57 +            Afterwards, lastVersion() will return the latest version in the file. 
    1.58 +            (The old lastVersion dictionary is still around, so you can save a pointer to it 
    1.59 +            before the call and use it later to see what changed.)
    1.60 +            Changes made to the currentVersion dictionary are not lost, but are now relative
    1.61 +            to the new lastVersion. You may want to scan them and resolve conflicts. */
    1.62 +        virtual bool sync();
    1.63 +        
    1.64 +        /** Saves the current version to the file, by appending.
    1.65 +            Returns false if there is a version conflict; in that case you need to call sync(),
    1.66 +            possibly resolve conflicts, and then call save() again. */
    1.67 +        virtual bool save();
    1.68 +        
    1.69 +        /** Saves the current version to the file, by writing to a new temporary file and
    1.70 +            then atomically replacing the original. 
    1.71 +            Older versions, and older copies of the data, are not preserved, so this
    1.72 +            will typically shrink the file quite a bit.
    1.73 +            Returns false if there is a version conflict. */
    1.74 +        virtual bool saveAndCompact();
    1.75 +         
    1.76 +        /** Saves the current version to a new file, leaving the new file open, 
    1.77 +            so subsequent saves will be written to it. */
    1.78 +        virtual void saveAs (const char *newFilename, bool overwriteAllowed =true);
    1.79 +        
    1.80 +        /** Scans the file for damage. Returns true if the file is OK, false if problems are found.
    1.81 +            If the 'repair' flag is set, will truncate the file to the last valid version. */
    1.82 +        bool scavenge (bool repair =false);
    1.83 +        
    1.84 +        ChunkIterator* chunkIterator() const;       // for testing purposes
    1.85 +
    1.86 +    private:
    1.87 +        Ottoman(const Ottoman&);            // forbid copying/assignment
    1.88 +        Ottoman& operator=(const Ottoman&);
    1.89 +        
    1.90 +        void _open();
    1.91 +        void _append (File *dstFile);
    1.92 +        File* _writeTo (const char *dstFileName, bool overwriteAllowed);
    1.93 +        
    1.94 +        bool _writeable;
    1.95 +        File *_file;
    1.96 +        char *_filename;
    1.97 +        VersionDictionary *_lastVersion;
    1.98 +        OverlayDictionary *_current;
    1.99 +    };
   1.100 +    
   1.101 +}
   1.102 +#endif // _MOOSEYARD_OTTOMAN_