ChangeSet.h

Go to the documentation of this file.

/*--------------------------------------------------------------------------------------+
|
|   Supplied under applicable software license agreement.
|
|   Copyright (c) 2018 Bentley Systems, Incorporated. All rights reserved.
|
+---------------------------------------------------------------------------------------*/
#pragma once

#include "BeSQLite.h"

BESQLITE_TYPEDEFS(IByteArray);
BESQLITE_TYPEDEFS(ChangeGroup);
BESQLITE_TYPEDEFS(IChangeSet);
BESQLITE_TYPEDEFS(ChangeSet);
BESQLITE_TYPEDEFS(ChangeStream);
BESQLITE_TYPEDEFS(SchemaChangeSet);

BEGIN_BENTLEY_SQLITE_NAMESPACE

//=======================================================================================
// @bsiclass                                                     Bentley Systems
//=======================================================================================
struct IByteArray
{
protected:
    virtual int _GetSize() const = 0;
    virtual void const* _GetData() const = 0;
public:
    int GetSize() const { return _GetSize(); }

    void const* GetData() const { return _GetData(); }
};

//=======================================================================================
// @bsiclass                                                     Bentley Systems
//=======================================================================================
struct SchemaChangeSet : IByteArray
{
private:
    Utf8String m_ddl;

    int _GetSize() const override { return IsEmpty() ? 0 : (int) m_ddl.SizeInBytes(); }
    void const* _GetData() const override { return m_ddl.c_str(); }

public:
    SchemaChangeSet(Utf8CP ddl = nullptr) { m_ddl.AssignOrClear(ddl); }

    BE_SQLITE_EXPORT void AddDDL(Utf8CP ddl);

    bool IsEmpty() const { return m_ddl.empty(); }

    void Clear() { m_ddl.clear(); }

    Utf8StringCR ToString() const { return m_ddl; }

    BE_SQLITE_EXPORT void Dump(Utf8CP label) const;
};

//=======================================================================================
// @bsiclass                                                     Bentley Systems
//=======================================================================================
struct ChangeTracker : RefCountedBase
{
friend struct Db;
friend struct DbFile;

private:
    SchemaChangeSet m_schemaChanges;
    DbResult RecordSchemaChange(Utf8CP ddl);

protected:
    bool            m_isTracking;
    Db*             m_db;
    SqlSessionP     m_session;
    Utf8String      m_name;
    
    enum class OnCommitStatus {Continue=0, Abort, Completed};
    enum class TrackChangesForTable : bool {No=0, Yes=1};

    BE_SQLITE_EXPORT DbResult CreateSession();
    virtual OnCommitStatus _OnCommit(bool isCommit, Utf8CP operation) = 0;
    void SetDb(Db* db) {m_db = db;}
    Db* GetDb() {return m_db;}
    Utf8CP GetName() const {return m_name.c_str();}

    SchemaChangeSetCR GetSchemaChanges() const { return m_schemaChanges; }

public:
    ChangeTracker(Utf8CP name=NULL) : m_name(name) {m_session=0; m_db=0; m_isTracking=false;}
    virtual ~ChangeTracker() {EndTracking();}
    virtual TrackChangesForTable _FilterTable(Utf8CP tableName) {return TrackChangesForTable::Yes;}
    SqlSessionP GetSqlSession() {return m_session;}

    BE_SQLITE_EXPORT DbResult DifferenceToDb(Utf8StringP errMsg, BeFileNameCR baseFile);

    BE_SQLITE_EXPORT void EndTracking();

    BE_SQLITE_EXPORT bool EnableTracking(bool val);

    enum class Mode
    {
        Direct = 0, 
        Indirect = 1, 
    };

    BE_SQLITE_EXPORT Mode GetMode() const;

    BE_SQLITE_EXPORT void SetMode(Mode mode);

    BE_SQLITE_EXPORT bool HasChanges() const;

    BE_SQLITE_EXPORT bool HasDataChanges() const;

    bool HasSchemaChanges() const { return !m_schemaChanges.IsEmpty(); } 

    void Restart() {EndTracking(); EnableTracking(true);}
    bool IsTracking() const {return m_isTracking;}
};

//=======================================================================================
// @bsiclass                                                     Bentley Systems
//=======================================================================================
struct Changes
{
private:
    ChangeStream* m_changeStream = nullptr;
    int    m_size = 0;
    void*  m_data = nullptr;
    mutable SqlChangesetIterP m_iter = 0;

    void Finalize() const;

public:
    BE_SQLITE_EXPORT explicit Changes(ChangeSet const& changeSet);

    explicit Changes(ChangeStream& changeStream) : m_changeStream(&changeStream) {}

    Changes(void* data, int size) : m_data(data), m_size(size) {}

    Changes(Changes const& other) : m_data(other.m_data), m_size(other.m_size), m_changeStream(other.m_changeStream), m_iter(0) {}

    BE_SQLITE_EXPORT ~Changes();

    struct Change : std::iterator<std::input_iterator_tag, Change const>
        {
        private:
            bool  m_isValid;
            SqlChangesetIterP m_iter;

        public:
            Change(SqlChangesetIterP iter, bool isValid) {m_iter=iter; m_isValid=isValid;}
            BE_SQLITE_EXPORT DbResult GetOperation(Utf8CP* tableName, int* nCols, DbOpcode* opcode, int* indirect) const;

            BE_SQLITE_EXPORT DbResult GetPrimaryKeyColumns(Byte** cols, int* nCols) const;

            BE_SQLITE_EXPORT DbValue GetOldValue(int colNum) const;

            BE_SQLITE_EXPORT DbValue GetNewValue(int colNum) const;

            enum class Stage : bool {Old=0, New=1};
            DbValue GetValue(int colNum, Stage stage) const {return (stage==Stage::Old) ? GetOldValue(colNum) : GetNewValue(colNum);}

            BE_SQLITE_EXPORT Change& operator++();

            bool IsValid() const {return m_isValid;}

            Change const& operator* () const {return *this;}
            bool operator!=(Change const& rhs) const {return (m_iter != rhs.m_iter) || (m_isValid != rhs.m_isValid);}
            bool operator==(Change const& rhs) const {return (m_iter == rhs.m_iter) && (m_isValid == rhs.m_isValid);}

            BE_SQLITE_EXPORT void Dump(Db const&, bool isPatchSet, bset<Utf8String>& tablesSeen, int detailLevel) const;

            void Dump(Db const& db, bool isPatchSet, int detailLevel) const {bset<Utf8String> tablesSeen; Dump(db, isPatchSet, tablesSeen, detailLevel);}

            BE_SQLITE_EXPORT void DumpColumns(int startCol, int endCol, Changes::Change::Stage stage, bvector<Utf8String> const& columns, int detailLevel) const;

            BE_SQLITE_EXPORT Utf8String FormatPrimarykeyColumns(bool isInsert, int detailLevel) const;

            BE_SQLITE_EXPORT void OnPropertyUpdateReversed(Db&) const; 
        };

    typedef Change const_iterator;

    BE_SQLITE_EXPORT Change begin() const;

    Change end() const {return Change(m_iter, false);}

};

//=======================================================================================
// @bsiclass                                                     Bentley Systems
//=======================================================================================
struct ChangeGroup : NonCopyableClass
{
    friend struct ChangeSet;
    friend struct ChangeStream;
private:
    void*  m_changegroup;
    
public:
    BE_SQLITE_EXPORT ChangeGroup();
    BE_SQLITE_EXPORT ~ChangeGroup();
    BE_SQLITE_EXPORT DbResult AddChanges(int size, void const* data);
};

//=======================================================================================
// @bsiclass                                                     Bentley Systems
//=======================================================================================
struct IChangeSet
{
public:
    enum class SetType : bool {Full=0, Patch=1};
    enum class ApplyChangesForTable : bool {No=0, Yes=1};
    enum class ConflictCause : int {Data=1, NotFound=2, Conflict=3, Constraint=4, ForeignKey=5};
    enum class ConflictResolution : int {Skip=0, Replace=1, Abort=2};
protected:
    virtual ~IChangeSet() { }

    virtual ApplyChangesForTable _FilterTable(Utf8CP tableName) {return ApplyChangesForTable::Yes;}
    virtual ConflictResolution _OnConflict(ConflictCause clause, Changes::Change iter) = 0;
    virtual DbResult _FromChangeTrack(ChangeTracker& tracker, SetType setType) = 0;
    virtual DbResult _FromChangeGroup(ChangeGroupCR changeGroup) = 0;
    virtual DbResult _ApplyChanges(DbR db) = 0;
    virtual Changes _GetChanges() = 0;
public:
    ApplyChangesForTable FilterTable(Utf8CP tableName) { return _FilterTable(tableName); }

    ConflictResolution OnConflict(ConflictCause cause, Changes::Change iter) { return _OnConflict(cause, iter); }

    DbResult FromChangeTrack(ChangeTracker& tracker, SetType setType=SetType::Full) { return _FromChangeTrack(tracker, setType); }

    DbResult FromChangeGroup(ChangeGroupCR changeGroup) { return _FromChangeGroup(changeGroup); }

    DbResult ApplyChanges(DbR db) { return _ApplyChanges(db); }

    Changes GetChanges() { return _GetChanges(); }
};

//=======================================================================================
// @bsiclass                                                     Bentley Systems
//=======================================================================================
struct ChangeSet : NonCopyableClass, IChangeSet, IByteArray
{
private:
    int    m_size;
    void*  m_changeset;

    int _GetSize() const override { return m_size; }
    void const* _GetData() const override { return m_changeset; }

protected:
    BE_SQLITE_EXPORT virtual DbResult _FromChangeTrack(ChangeTracker& tracker, SetType setType) override;
    BE_SQLITE_EXPORT virtual DbResult _FromChangeGroup(ChangeGroupCR changeGroup) override;
    BE_SQLITE_EXPORT virtual DbResult _ApplyChanges(DbR db) override;
    virtual Changes _GetChanges() override { return Changes(*this); }
public:
    ChangeSet() {m_size=0; m_changeset=nullptr;}
    ~ChangeSet() {Free();}

    BE_SQLITE_EXPORT void Free();

    BE_SQLITE_EXPORT DbResult Invert();

    BE_SQLITE_EXPORT DbResult FromData(int size, void const* data, bool invert);

    BE_SQLITE_EXPORT DbResult ConcatenateWith(ChangeSet const& second);

    bool IsValid() {return 0 != m_changeset;}

    BE_SQLITE_EXPORT void Dump(Utf8CP label, Db const&, bool isPatchSet=false, int detailLevel=0) const;

    BE_SQLITE_EXPORT static Utf8String InterpretConflictCause(ChangeSet::ConflictCause);
};

//=======================================================================================
// @bsiclass                                                     Bentley Systems
//=======================================================================================
struct AbortOnConflictChangeSet : BeSQLite::ChangeSet
{
ConflictResolution _OnConflict(ConflictCause cause, BeSQLite::Changes::Change iter) override
    {
    BeAssert(false);
    return ChangeSet::ConflictResolution::Abort;
    }
};

//=======================================================================================
// @bsiclass                                                     Bentley Systems
//=======================================================================================
struct ChangeStream : NonCopyableClass, IChangeSet
{
friend struct Changes;
private:
    static int OutputCallback(void *pOut, const void *pData, int nData);
    static int InputCallback(void *pIn, void *pData, int *pnData);
    static int ConflictCallback(void *pCtx, int cause, SqlChangesetIterP iter);
    static int FilterTableCallback(void *pCtx, Utf8CP tableName);

    // Resets the change stream, and is internally called at the 
    // end of various change stream operations
    void Reset() { _Reset(); }
    static DbResult TransferBytesBetweenStreams(ChangeStream& inStream, ChangeStream& outStream);

protected:
    BE_SQLITE_EXPORT virtual DbResult _FromChangeTrack(ChangeTracker& tracker, SetType setType) override;
    BE_SQLITE_EXPORT virtual DbResult _FromChangeGroup(ChangeGroupCR changeGroup) override;
    BE_SQLITE_EXPORT virtual DbResult _ApplyChanges(DbR db) override;
    virtual Changes _GetChanges() override { return Changes(*this); }

    virtual DbResult _InputPage(void *pData, int *pnData) { return BE_SQLITE_OK; }

    virtual DbResult _OutputPage(const void *pData, int nData) { return BE_SQLITE_OK; }

    virtual void _Reset() {}

public:
    ChangeStream() {}

    BE_SQLITE_EXPORT DbResult ToChangeGroup(ChangeGroup& changeGroup);

    BE_SQLITE_EXPORT DbResult ToChangeSet(ChangeSet& changeSet, bool invert = false);

    BE_SQLITE_EXPORT DbResult FromChangeStream(ChangeStream& inStream, bool invert = false);

    BE_SQLITE_EXPORT DbResult ToChangeStream(ChangeStream& outStream, bool invert = false);

    BE_SQLITE_EXPORT DbResult FromConcatenatedChangeStreams(ChangeStream& inStream1, ChangeStream& inStream2);
    
    BE_SQLITE_EXPORT void Dump(Utf8CP label, DbCR db, bool isPatchSet = false, int detailLevel = 0);
};

END_BENTLEY_SQLITE_NAMESPACE