bdb_file.hpp

ncbi源码

/*
 * ===========================================================================
 * PRODUCTION $Log: bdb_file.hpp,v $
 * PRODUCTION Revision 1000.2  2004/06/01 18:37:00  gouriano
 * PRODUCTION PRODUCTION: UPGRADED [GCC34_MSVC7] Dev-tree R1.30
 * PRODUCTION
 * ===========================================================================
 */

#ifndef BDB_FILE_HPP__
#define BDB_FILE_HPP__

/* $Id: bdb_file.hpp,v 1000.2 2004/06/01 18:37:00 gouriano Exp $
 * ===========================================================================
 *
 *                            PUBLIC DOMAIN NOTICE
 *               National Center for Biotechnology Information
 *
 *  This software/database is a "United States Government Work" under the
 *  terms of the United States Copyright Act.  It was written as part of
 *  the author's official duties as a United States Government employee and
 *  thus cannot be copyrighted.  This software/database is freely available
 *  to the public for use. The National Library of Medicine and the U.S.
 *  Government have not placed any restriction on its use or reproduction.
 *
 *  Although all reasonable efforts have been taken to ensure the accuracy
 *  and reliability of the software and data, the NLM and the U.S.
 *  Government do not and cannot warrant the performance or results that
 *  may be obtained by using this software or data. The NLM and the U.S.
 *  Government disclaim all warranties, express or implied, including
 *  warranties of performance, merchantability or fitness for any particular
 *  purpose.
 *
 *  Please cite the author in any work or product based on this material.
 *
 * ===========================================================================
 *
 * Author:  Anatoliy Kuznetsov
 *   
 * File Description: Berkeley DB File classes.
 *
 */

/// @file bdb_file.hpp
/// BDB File management.

#include <bdb/bdb_types.hpp>


BEGIN_NCBI_SCOPE

/** @addtogroup BDB_Files
 *
 * @{
 */


/// BDB Return codes
///


enum EBDB_ErrCode {
    eBDB_Ok,
    eBDB_NotFound,
    eBDB_KeyDup
};


class CBDB_Env;
class CBDB_Transaction;


/// Raw file class wraps up basic Berkeley DB operations. 
///

class NCBI_BDB_EXPORT CBDB_RawFile
{
public:
    static const char kDefaultDatabase[];  // = "_table"

    enum EOpenMode {
        eReadWrite,
        eReadOnly,
        eCreate,         //!< implies 'eReadWrite' too
        eReadWriteCreate //!< read-write, create if it doesn't exist
    };

    enum EReallocMode {
        eReallocAllowed,
        eReallocForbidden
    };

    enum EDuplicateKeys {
        eDuplicatesDisable,
        eDuplicatesEnable
    };

    enum EIgnoreError {
        eIgnoreError,
        eThrowOnError
    };

public:
    CBDB_RawFile(EDuplicateKeys dup_keys=eDuplicatesDisable);
    virtual ~CBDB_RawFile();

    /// Associate file with environment. Should be called before 
    /// file opening.
    void SetEnv(CBDB_Env& env);

    /// Get pointer on file environment
    /// Return NULL if no environment has been set
    CBDB_Env* GetEnv() { return m_Env; }

    /// Open file with specified access mode
    void Open(const char* filename, EOpenMode open_mode);
    /// Open file with specified filename and database name.
    /// (Berkeley DB supports having several database tables in one file.) 
    void Open(const char* filename, const char* database,
              EOpenMode open_mode);
    /// Attach class to external BerkeleyDB file instance.
    /// Note: Should be already open.
    void Attach(CBDB_RawFile& bdb_file);
    /// Close file
    void Close();
    /// Reopen database file. (Should be already open).
    void Reopen(EOpenMode open_mode);

    /// Remove the database specified by the filename and database arguments
    void Remove(const char* filename, const char* database = 0);
    /// Empty the database. Return number of records removed.
    unsigned int Truncate();

    // Set Berkeley DB page size value. By default OS default is used.
    void SetPageSize(unsigned int page_size);

    /// Set Berkeley DB memory cache size for the file (default is 256K).
    void SetCacheSize(unsigned int cache_size);

    const string& FileName() const;
    const string& Database() const;

    /// Set comparison function. Default implementation installs bdb_types based
    /// function. Can be overloaded for some specific cases.
    virtual void SetCmp(DB*) = 0;

    /// Return TRUE if the file is open
    bool IsOpen() const;

    // Return TRUE if the file is attached to some other BDB file
    bool IsAttached() const;

    /// Return TRUE if the if the underlying database files were created 
    /// on an architecture of the different byte order 
    bool IsByteSwapped() const { return m_ByteSwapped; }

    /// Return TRUE if file can contain duplicate keys
    bool DuplicatesAllowed() const { return m_DuplicateKeys == eDuplicatesEnable; }

    /// Return the key duplicate mode value
    EDuplicateKeys GetDupKeysMode() const { return m_DuplicateKeys; }

    /// Return file name
    const string& GetFileName() const { return m_FileName; }

    /// Return the file open mode
    EOpenMode GetOpenMode() const { return m_OpenMode; }

    /// Flush any cached information to disk
    void Sync();

    /// Compute database statistic, return number of records.
    /// (Can be time consuming)
    unsigned CountRecs();
    
    /// Set current transaction
    void SetTransaction(CBDB_Transaction* trans);

private:
    CBDB_RawFile(const CBDB_RawFile&);
    CBDB_RawFile& operator= (const CBDB_RawFile&);

protected:
    void x_Open(const char* filename, const char* database,
                EOpenMode open_mode);
    void x_Create(const char* filename, const char* database);

    void x_Close(EIgnoreError close_mode);

    // Create m_DB member, set page, cache parameters
    void x_CreateDB();

    void x_RemoveTransaction(CBDB_Transaction* trans);
    
    /// Get transaction handler.
    ///
    /// Function returns NULL if no transaction has been set.
    ///
    /// @sa SetTransaction
    DB_TXN* GetTxn();

    /// Create DB cursor
    DBC* CreateCursor(CBDB_Transaction* trans = 0) const;

protected:
    DB*               m_DB;
    DBT*              m_DBT_Key;
    DBT*              m_DBT_Data;
    CBDB_Env*         m_Env;
    CBDB_Transaction* m_Trans;

private:
    bool             m_DB_Attached;  //!< TRUE if m_DB doesn't belong here
    bool             m_ByteSwapped;  //!< TRUE if file created on a diff.arch.
    string           m_FileName;     //!< filename
    string           m_Database;     //!< db name in file (optional)
    unsigned         m_PageSize;
    unsigned         m_CacheSize;
    EDuplicateKeys   m_DuplicateKeys;
    EOpenMode        m_OpenMode;

    static const int kOpenFileMask;
    
    friend class CBDB_Transaction;
    friend class CBDB_FileCursor;
};




/// Berkeley DB file class. 
/// Implements primary key and fields functionality.
///

class NCBI_BDB_EXPORT CBDB_File : public CBDB_RawFile
{
public:
    CBDB_File(EDuplicateKeys dup_keys = eDuplicatesDisable);

    /// Open file with specified access mode
    void Open(const char* filename, EOpenMode open_mode);

    /// Open file with specified filename and database name.
    /// (Berkeley DB supports having several database tables in one file.) 
    void Open(const char* filename, const char* database,
              EOpenMode open_mode);
    /// Reopen the db file
    void Reopen(EOpenMode open_mode);

    /// Attach external Berkeley DB file.
    /// Note: Should be already open.
    void Attach(CBDB_File& db_file);

    /// Fetches the record corresponding to the current key value.
    EBDB_ErrCode Fetch() { return x_Fetch(0); }
    
    /// Fetche the record corresponding to the current key value.
    /// Acquire write lock instead of read lock when doing the retrieval.
    /// Meaningful only in the presence of transactions.
    EBDB_ErrCode FetchForUpdate();
    
    enum EAfterWrite {
        eKeepData,    //!< Keep the inserted data for a while
        eDiscardData  //!< Invalidate the inserted data immediately after write
    };

    /// Insert new record
    EBDB_ErrCode Insert(EAfterWrite write_flag = eDiscardData);

    /// Delete record corresponding to the current key value.
    EBDB_ErrCode Delete(EIgnoreError on_error=eThrowOnError);

    /// Update record corresponding to the current key value. If record does not exist
    /// it will be inserted.
    EBDB_ErrCode UpdateInsert(EAfterWrite write_flag = eDiscardData);
    
    
    void BindKey (const char* field_name, 
                  CBDB_Field* key_field,  
                  size_t buf_size = 0);

    void BindData(const char* field_name,
                  CBDB_Field* data_field, 
                  size_t buf_size = 0, 
                  ENullable is_null = eNullable);

    /// Get Buffer manager for key section of the file
    const CBDB_BufferManager* GetKeyBuffer() const { return m_KeyBuf.get(); }

    /// Get Buffer manager for data section of the file
    const CBDB_BufferManager* GetDataBuffer() const { return m_DataBuf.get(); }


    /// Sets maximum number of key fields participating in comparison
    /// Should be less than total number of key fields
    void SetFieldCompareLimit(unsigned int n_fields);

    /// Create new copy of m_DBT_Key.
    /// Caller is responsible for proper deletion. See also: DestroyDBT_Clone
    DBT* CloneDBT_Key();