be_io_recordstore.h

/******************************************************************************
 * This software was developed at the National Institute of Standards and
 * Technology (NIST) by employees of the Federal Government in the course
 * of their official duties. Pursuant to title 17 Section 105 of the
 * United States Code, this software is not subject to copyright protection
 * and is in the public domain. NIST assumes no responsibility whatsoever for
 * its use by other parties, and makes no guarantees, expressed or implied,
 * about its quality, reliability, or any other characteristic.
 ******************************************************************************/
#ifndef __BE_IO_RECORDSTORE_H__
#define __BE_IO_RECORDSTORE_H__
 
#include <functional>
#include <memory>
#include <string>
#include <vector>
 
#include <be_framework_enumeration.h>
#include <be_io.h>
#include <be_memory_autoarray.h>
 
/*
 * This file contains the class declaration for the RecordStore, a virtual
 * class that represents a collection of named blobs of data.
 */
 
namespace BiometricEvaluation {
 
        namespace IO {
                class RecordStoreIterator;
 
                class RecordStore {
                public:
                        struct Record {
                                Record();
 
                                Record(
                                    const std::string &key,
                                    const Memory::uint8Array &data);
                                std::string key;
                                Memory::uint8Array data;
                        };
                        using Record = struct Record;
 
                        using iterator = IO::RecordStoreIterator;
 
                        enum class Kind
                        {
                                BerkeleyDB,
                                Archive,
                                File,
                                SQLite,
                                Compressed,
                                List,
 
                                Default = BerkeleyDB
                        };
                        
                        static const std::string INVALIDKEYCHARS;
 
                        virtual ~RecordStore();
                        
                        virtual std::string getDescription() const = 0;
 
                        virtual unsigned int getCount() const = 0;
 
                        virtual std::string getPathname() const = 0;
 
                        virtual void move(
                            const std::string &pathname) = 0;
 
                        virtual void changeDescription(
                            const std::string &description) = 0;
 
                        virtual uint64_t getSpaceUsed() const = 0;
 
                        virtual void sync() const = 0;
 
                        void
                        virtual insert(
                            const std::string &key,
                            const Memory::uint8Array &data);
 
                        virtual void
                        insert(
                            const std::string &key,
                            const void *const data,
                            const uint64_t size) = 0;
 
                        virtual void remove(
                            const std::string &key) = 0;
 
                        virtual Memory::uint8Array
                        read(
                            const std::string &key) const = 0;
 
                        virtual void replace(
                            const std::string &key,
                            const Memory::uint8Array &data);
 
                        virtual void replace(
                            const std::string &key,
                            const void *const data,
                            const uint64_t size);
 
                        virtual uint64_t length(
                            const std::string &key) const = 0;
 
                        virtual void flush(
                            const std::string &key) const = 0;
 
                        static const int BE_RECSTORE_SEQ_START = 1;
                        static const int BE_RECSTORE_SEQ_NEXT = 2;
 
                        virtual RecordStore::Record
                        sequence(
                            int cursor = BE_RECSTORE_SEQ_NEXT) = 0;
 
                        virtual std::string
                        sequenceKey(
                            int cursor = BE_RECSTORE_SEQ_NEXT) = 0;
 
                        virtual void setCursorAtKey(
                            const std::string &key) = 0;
 
                        virtual bool
                        containsKey(
                            const std::string &key)
                            const;
 
                        virtual iterator
                        begin()
                            noexcept;
 
                        virtual iterator
                        end()
                            noexcept;
 
                        static bool
                        isRecordStore(
                            const std::string &pathname);
 
                        static std::shared_ptr<RecordStore> openRecordStore(
                            const std::string &pathname,
                            IO::Mode mode = Mode::ReadOnly);
 
                        static std::shared_ptr<RecordStore> createRecordStore(
                            const std::string &pathname,
                            const std::string &description,
                            const IO::RecordStore::Kind &kind);
 
                        static void removeRecordStore(
                            const std::string &pathname);
 
                        static void mergeRecordStores(
                            const std::string &mergePathname,
                            const std::string &description,
                            const IO::RecordStore::Kind &kind,
                            const std::vector<std::string> &pathnames,
                            const std::function<bool()> &interrupt = 
                                []() {return (false);});
 
                        class Impl;
                protected:
                private:
                };
 
                class RecordStoreIterator
                {
                public:
                        /*
                         * Satisfy std::iterator_traits<> expectations.
                         */
 
                        using iterator_category = std::forward_iterator_tag;
                        using value_type = RecordStore::Record;
                        using difference_type = std::ptrdiff_t;
                        using pointer = value_type*;
                        using reference = value_type&;
 
                        RecordStoreIterator() = default;
 
                        RecordStoreIterator(
                            IO::RecordStore *recordStore,
                            bool atEnd);
 
                        RecordStoreIterator(
                            const RecordStoreIterator &rhs) = default;
                        RecordStoreIterator(
                            RecordStoreIterator &&rvalue) = default;
                        ~RecordStoreIterator() = default;
 
                        /* 
                         * Operators.
                         */
 
                        reference
                        operator*();
 
                        pointer
                        operator->();
 
                        RecordStoreIterator&
                        operator++();
 
                        RecordStoreIterator
                        operator++(
                            int);
 
                        RecordStoreIterator
                        operator+=(
                            difference_type rhs);
 
                        RecordStoreIterator
                        operator+(
                            difference_type rhs);
 
                        bool
                        operator==(
                            const RecordStoreIterator &rhs);
 
                        inline bool
                        operator!=(
                            const RecordStoreIterator &rhs)
                        {
                                return (!(*this == rhs));
                        }
 
                        /* Default copy assignment operator */
                        RecordStoreIterator&
                        operator=(
                            const RecordStoreIterator &rhs) = default;
 
                        RecordStoreIterator&
                        operator=(
                            RecordStoreIterator &&rhs) = default;
 
                private:
                        IO::RecordStore *_recordStore{nullptr};
                        bool _atEnd{true};
                        value_type _currentRecord{};
 
                        void
                        setBegin();
 
                        void
                        step(
                            difference_type steps = 1);
 
                        void
                        setEnd();
                };
        }
}
 
BE_FRAMEWORK_ENUMERATION_DECLARATIONS(
    BiometricEvaluation::IO::RecordStore::Kind,
    BE_IO_RecordStore_Kind_EnumToStringMap);
 
#endif  /* __BE_IO_RECORDSTORE_H__ */