Database.hh

Go to the documentation of this file.

//
// Database.hh
//
// Copyright (c) 2019 Couchbase, Inc All rights reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//
 
#pragma once
#include "cbl++/Base.hh"
#include "cbl/CBLCollection.h"
#include "cbl/CBLDatabase.h"
#include "cbl/CBLDocument.h"
#include "cbl/CBLQuery.h"
#include "cbl/CBLLog.h"
#include "cbl/CBLScope.h"
#include "fleece/Fleece.hh"
#include "fleece/Mutable.hh"
#include <exception>
#include <functional>
#include <mutex>
#include <optional>
#include <string>
#include <string_view>
#include <vector>
 
 
CBL_ASSUME_NONNULL_BEGIN
 
namespace cbl {
    class Blob;
    class Collection;
    class Document;
    class MutableDocument;
    class Query;

    using ConflictHandler = std::function<bool(MutableDocument documentBeingSaved,
                                               Document conflictingDocument)>;
 
    
#ifdef COUCHBASE_ENTERPRISE
    class Extension {
    public:
        static void enableVectorSearch(std::string_view path) {
            CBLError error {};
            internal::check(CBL_EnableVectorSearch(slice(path), &error), error);
        }
    };

    using EncryptionAlgorithm = CBLEncryptionAlgorithm;
    using EncryptionKeySize   = CBLEncryptionKeySize;

    class EncryptionKey : public CBLEncryptionKey {
    public:
        EncryptionKey()
        : CBLEncryptionKey()
        {}

        EncryptionKey(const CBLEncryptionKey& k)
        : CBLEncryptionKey(k)
        {}

        EncryptionKey(std::string_view password, bool old = false) {
            if ( old ) CBLEncryptionKey_FromPasswordOld(this, slice(password));
            else CBLEncryptionKey_FromPassword(this, slice(password));
        }

        EncryptionKey& operator=(const CBLEncryptionKey& k) {
            CBLEncryptionKey::operator=(k);
            return *this;
        }
    };
 
#endif

    class DatabaseConfiguration {
    public:
        std::string      directory;      
    #ifdef COUCHBASE_ENTERPRISE
        EncryptionKey encryptionKey;     
    #endif
        bool fullSync{false};

        DatabaseConfiguration(const CBLDatabaseConfiguration& cblConfig) {
            directory = ((slice)cblConfig.directory).asString();
#ifdef COUCHBASE_ENTERPRISE
            encryptionKey = cblConfig.encryptionKey;
#endif
            fullSync = cblConfig.fullSync;
        }

        DatabaseConfiguration() = default;

        static DatabaseConfiguration defaultConfiguration() {
            return CBLDatabaseConfiguration_Default();
        }
    };

    class Database : private RefCounted {
    public:
        // Static database-file operations:

        static bool exists(std::string_view name, std::optional<std::string_view> inDirectory=std::nullopt) {
            slice inDir;
            if ( inDirectory ) inDir = slice(*inDirectory);
            return CBL_DatabaseExists(slice(name), inDir);
        }

        static void copyDatabase(std::string_view fromPath,
                                 std::string_view toName)
        {
            CBLError error;
            internal::check( CBL_CopyDatabase(slice(fromPath), slice(toName),
                                              nullptr, &error), error );
        }

        static void copyDatabase(std::string_view fromPath,
                                 std::string_view toName,
                                 const DatabaseConfiguration& config)
        {
            CBLError error;
            CBLDatabaseConfiguration cblConfig{
                (slice)config.directory,
#ifdef COUCHBASE_ENTERPRISE
                config.encryptionKey,
#endif
                config.fullSync
            };
            internal::check( CBL_CopyDatabase(slice(fromPath), slice(toName),
                                              &cblConfig, &error), error );
        }

        static void deleteDatabase(std::string_view name, std::optional<std::string_view> inDirectory =std::nullopt) {
            CBLError error;
            slice inDir;
            if ( inDirectory ) inDir = slice(*inDirectory);
            if (!CBL_DeleteDatabase(slice(name), inDir, &error) && error.code != 0)
                internal::check(false, error);
        }
 
        // Lifecycle:

        Database(std::string_view name) {
            open(name, nullptr);
        }

        Database(std::string_view name,
                 const DatabaseConfiguration& config)
        {
            CBLDatabaseConfiguration cblConfig{
                (slice)config.directory,
#ifdef COUCHBASE_ENTERPRISE
                config.encryptionKey,
#endif
                config.fullSync
            };
            open(name, &cblConfig);
        }

        void close() {
            CBLError error;
            internal::check(CBLDatabase_Close(ref(), &error), error);
        }

        void deleteDatabase() {
            CBLError error;
            internal::check(CBLDatabase_Delete(ref(), &error), error);
        }
        
        void performMaintenance(CBLMaintenanceType type) {
            CBLError error;
            internal::check(CBLDatabase_PerformMaintenance(ref(), type, &error), error);
        }
 
#ifdef COUCHBASE_ENTERPRISE
        void changeEncryptionKey(const EncryptionKey* _cbl_nullable newKey) {
            CBLError error{};
            internal::check(CBLDatabase_ChangeEncryptionKey(ref(), newKey, &error), error);
        }
#endif
 
        // Accessors:
        
        std::string name() const                        {return internal::asString(CBLDatabase_Name(ref()));}
        
        std::string path() const                        {return internal::asString(CBLDatabase_Path(ref()));}
        
        DatabaseConfiguration config() const            {return CBLDatabase_Config(ref());}

        inline Blob getBlob(fleece::Dict properties) const;

        inline void saveBlob(const Blob& blob);
 
        // Collections:
        
        fleece::MutableArray getScopeNames() const {
            CBLError error {};
            FLMutableArray flNames = CBLDatabase_ScopeNames(ref(), &error);
            internal::check(error.code == 0, error);
            fleece::MutableArray names(flNames);
            FLMutableArray_Release(flNames);
            return names;
        }
        
        fleece::MutableArray getCollectionNames(std::string_view scopeName = (std::string_view)slice(kCBLDefaultScopeName)) const {
            CBLError error {};
            FLMutableArray flNames = CBLDatabase_CollectionNames(ref(), slice(scopeName), &error);
            internal::check(error.code == 0, error);
            fleece::MutableArray names(flNames);
            FLMutableArray_Release(flNames);
            return names;
        }
        
        inline Collection getCollection(std::string_view collectionName, std::optional<std::string_view> scopeName = std::nullopt) const;

        inline Collection createCollection(std::string_view collectionName, std::optional<std::string_view> scopeName =std::nullopt);
        
        void deleteCollection(std::string_view collectionName, std::optional<std::string_view> scopeName =std::nullopt) {
            CBLError error {};
            slice sname = scopeName.value_or(slice(kCBLDefaultScopeName));
            if ( scopeName ) sname = *scopeName;
            internal::check(CBLDatabase_DeleteCollection(ref(), slice(collectionName), sname, &error), error);
        }

        inline Collection getDefaultCollection() const;
        
        // Query:

        inline Query createQuery(QueryLanguage language, std::string_view queryString);
 
        // Notifications:
        
        using NotificationsReadyCallback = std::function<void(Database)>;

        void bufferNotifications(NotificationsReadyCallback callback) {
            _notificationReadyCallbackAccess->setCallback(callback);
            CBLDatabase_BufferNotifications(ref(), [](void *context, CBLDatabase *db) {
                ((NotificationsReadyCallbackAccess*)context)->call(Database(db));
            }, _notificationReadyCallbackAccess.get());
        }

        void sendNotifications() {
            CBLDatabase_SendNotifications(ref());
        }
        
        // Destructors:

        ~Database() {
            clear();
        }
        
    protected:
        friend class Collection;
        friend class Scope;
        
        CBL_REFCOUNTED_WITHOUT_COPY_MOVE_BOILERPLATE(Database, RefCounted, CBLDatabase)
 
    private:
        void open(std::string_view name, const CBLDatabaseConfiguration* _cbl_nullable config) {
            CBLError error {};
            _ref = (CBLRefCounted*)CBLDatabase_Open(slice(name), config, &error);
            internal::check(_ref != nullptr, error);
            
            _notificationReadyCallbackAccess = std::make_shared<NotificationsReadyCallbackAccess>();
        }
 
        class NotificationsReadyCallbackAccess {
        public:
            void setCallback(NotificationsReadyCallback callback) {
                std::lock_guard<std::mutex> lock(_mutex);
                _callback = callback;
            }
            
            void call(Database db) {
                NotificationsReadyCallback callback;
                {
                    std::lock_guard<std::mutex> lock(_mutex);
                    callback = _callback;
                }
                if (callback)
                    callback(db);
            }
        private:
            std::mutex _mutex;
            NotificationsReadyCallback _callback {nullptr};
        };
        
        std::shared_ptr<NotificationsReadyCallbackAccess> _notificationReadyCallbackAccess;
        
    public:
        Database(const Database &other) noexcept
        :RefCounted(other)
        ,_notificationReadyCallbackAccess(other._notificationReadyCallbackAccess)
        { }

        Database(Database &&other) noexcept
        :RefCounted((RefCounted&&)other)
        ,_notificationReadyCallbackAccess(std::move(other._notificationReadyCallbackAccess))
        { }

        Database& operator=(const Database &other) noexcept {
            RefCounted::operator=(other);
            _notificationReadyCallbackAccess = other._notificationReadyCallbackAccess;
            return *this;
        }

        Database& operator=(Database &&other) noexcept {
            RefCounted::operator=((RefCounted&&)other);
            _notificationReadyCallbackAccess = std::move(other._notificationReadyCallbackAccess);
            return *this;
        }
        
        void clear() {
            // Reset _notificationReadyCallbackAccess the releasing the _ref to
            // ensure that CBLDatabase is deleted before _notificationReadyCallbackAccess.
            RefCounted::clear();
            _notificationReadyCallbackAccess.reset();
        }
    };
 

    class Transaction {
    public:
        explicit Transaction(Database db)
        :Transaction(db.ref())
        { }

        explicit Transaction (CBLDatabase *db) {
            CBLError error{};
            internal::check(CBLDatabase_BeginTransaction(db, &error), error);
            _db = db;
        }

        void commit()   {end(true);}

        void abort()    {end(false);}

        ~Transaction()  {end(false);}
 
    private:
        void end(bool commit) {
            CBLDatabase *db = _db;
            if (db) {
                _db = nullptr;
                CBLError error;
                if (!CBLDatabase_EndTransaction(db, commit, &error)) {
                    // If an exception is thrown while a Batch is in scope, its destructor will
                    // call end(). If I'm in this situation I cannot throw another exception or
                    // the C++ runtime will abort the process. Detect this and just warn instead.
                    if (std::current_exception())
                        CBL_Log(kCBLLogDomainDatabase, kCBLLogWarning,
                                "Transaction::end failed, while handling an exception");
                    else
                        internal::check(false, error);
                }
            }
        }
 
        CBLDatabase* _cbl_nullable _db = nullptr;
    };
}
 
CBL_ASSUME_NONNULL_END