bdb_blob.hpp
上传用户:yhdzpy8989
上传日期:2007-06-13
资源大小:13604k
文件大小:9k
源码类别:

生物技术

开发平台:

C/C++

  1. /*
  2.  * ===========================================================================
  3.  * PRODUCTION $Log: bdb_blob.hpp,v $
  4.  * PRODUCTION Revision 1000.1  2004/04/12 17:13:11  gouriano
  5.  * PRODUCTION PRODUCTION: UPGRADED [CATCHUP_003] Dev-tree R1.14
  6.  * PRODUCTION
  7.  * ===========================================================================
  8.  */
  9. #ifndef BDB___BLOB_HPP__
  10. #define BDB___BLOB_HPP__
  11. /* $Id: bdb_blob.hpp,v 1000.1 2004/04/12 17:13:11 gouriano Exp $
  12.  * ===========================================================================
  13.  *
  14.  *                            PUBLIC DOMAIN NOTICE
  15.  *               National Center for Biotechnology Information
  16.  *
  17.  *  This software/database is a "United States Government Work" under the
  18.  *  terms of the United States Copyright Act.  It was written as part of
  19.  *  the author's official duties as a United States Government employee and
  20.  *  thus cannot be copyrighted.  This software/database is freely available
  21.  *  to the public for use. The National Library of Medicine and the U.S.
  22.  *  Government have not placed any restriction on its use or reproduction.
  23.  *
  24.  *  Although all reasonable efforts have been taken to ensure the accuracy
  25.  *  and reliability of the software and data, the NLM and the U.S.
  26.  *  Government do not and cannot warrant the performance or results that
  27.  *  may be obtained by using this software or data. The NLM and the U.S.
  28.  *  Government disclaim all warranties, express or implied, including
  29.  *  warranties of performance, merchantability or fitness for any particular
  30.  *  purpose.
  31.  *
  32.  *  Please cite the author in any work or product based on this material.
  33.  *
  34.  * ===========================================================================
  35.  *
  36.  * Author:  Anatoliy Kuznetsov
  37.  *   
  38.  * File Description: BDB library BLOB support.
  39.  *
  40.  */
  41. /// @file bdb_blob.hpp
  42. /// BDB library BLOB support.
  43. #include <bdb/bdb_file.hpp>
  44. BEGIN_NCBI_SCOPE
  45. /** @addtogroup BDB_BLOB
  46.  *
  47.  * @{
  48.  */
  49. class CBDB_BLobStream;
  50. /// Berkeley DB BLOB File class. 
  51. ///
  52. /// The basic BLOB file. Key part of the file consists of one or more 
  53. /// fields. Data part is one binary object(BLOB).
  54. class NCBI_BDB_EXPORT CBDB_BLobFile : public CBDB_File
  55. {
  56. public:
  57.     CBDB_BLobFile();
  58.     /// Insert BLOB into the database
  59.     ///
  60.     /// Before calling this function you should assign the key fields.
  61.     /// @param data BLOB data
  62.     /// @param size data size in bytes
  63.     EBDB_ErrCode Insert(const void* data, size_t size);
  64.     /// Fetche the record corresponding to the current key value.
  65.     ///
  66.     /// Key fields should be assigned before calling this function.
  67.     /// This call actually translates into a BerkeleyDB call, so the target page
  68.     /// will be read from the disk into the BerkeleyDB internal cache.
  69.     /// You can call LobSize to get BLOB data size, allocate the target 
  70.     /// buffer and then call GetData (two phase BLOB fetch). 
  71.     /// If you know the data size upfront parameterized Fetch is a 
  72.     /// better alternative.
  73.     EBDB_ErrCode Fetch();
  74.     /// Retrieve BLOB data
  75.     ///
  76.     /// Fetch LOB record directly into the provided '*buf'.
  77.     /// If size of the LOB is greater than 'buf_size', then
  78.     /// if reallocation is allowed -- '*buf' will be reallocated
  79.     /// to fit the BLOB size; otherwise it throws an exception.
  80.     /// @param buf pointer on buffer pointer
  81.     /// @param buf_size buffer size
  82.     /// @param allow_realloc when "eReallocAllowed" Berkeley DB reallocates
  83.     /// the buffer to allow successful fetch
  84.     EBDB_ErrCode Fetch(void**       buf, 
  85.                        size_t       buf_size, 
  86.                        EReallocMode allow_realloc);
  87.     /// Get LOB size. Becomes available right after successfull Fetch.
  88.     size_t LobSize() const;
  89.     /// Copy LOB data into the 'buf'.
  90.     /// Throw an exception if buffer size 'size' is less than LOB size.
  91.     ///
  92.     /// @param buf destination data buffer
  93.     /// @param size data buffer size
  94.     /// @sa LobSize
  95.     EBDB_ErrCode GetData(void* buf, size_t size);
  96.     /// Creates stream like object to retrieve or write BLOB by chunks.
  97.     /// Caller is responsible for deletion.
  98.     CBDB_BLobStream* CreateStream();
  99. };
  100. /// Berkeley DB BLOB File stream. 
  101. ///
  102. /// Class wraps partial data read/write functionality of Berkeley DB.
  103. /// Both Read and Write functions of the class directly call 
  104. /// corresponding Berkeley DB methods without any buffering. For performance
  105. /// reasons it's advised to read or write data in chunks of substantial size.
  106. class NCBI_BDB_EXPORT CBDB_BLobStream
  107. {
  108. protected:
  109.     CBDB_BLobStream(DB* db, DBT* dbt_key, size_t blob_size, DB_TXN* txn);
  110. public:
  111.     ~CBDB_BLobStream();
  112.     /// Set current transaction for BLOB stream
  113.     void SetTransaction(CBDB_Transaction* trans);
  114.     /// Read data from BLOB
  115.     void Read(void *buf, size_t buf_size, size_t *bytes_read);
  116.     /// Write data into BLOB
  117.     void Write(const void* buf, size_t buf_size);
  118.     /// Return how much bytes we can read from the blob
  119.     size_t PendingCount() const { return m_BlobSize > 0 ? (m_BlobSize - m_Pos) : 0; }
  120. private:
  121.     CBDB_BLobStream(const CBDB_BLobStream&);
  122.     CBDB_BLobStream& operator=(const CBDB_BLobStream&);
  123. private:
  124.     DB*        m_DB;
  125.     DBT*       m_DBT_Key;
  126.     DBT*       m_DBT_Data;
  127.     DB_TXN*    m_Txn;
  128.     unsigned   m_Pos;
  129.     size_t     m_BlobSize;
  130. private:
  131.     friend class CBDB_BLobFile;
  132. };
  133. /// Berkeley DB Large Object File class. 
  134. /// Implements simple BLOB storage based on single unsigned integer key
  135. class NCBI_BDB_EXPORT CBDB_LobFile : public CBDB_RawFile
  136. {
  137. public:
  138.     CBDB_LobFile();
  139.     /// Insert BLOB data into the database
  140.     ///
  141.     /// @param lob_id insertion key
  142.     /// @param data buffer pointer
  143.     /// @param size data size in bytes
  144.     EBDB_ErrCode Insert(unsigned int lob_id, const void* data, size_t size);
  145.     /// Fetch LOB record. On success, LOB size becomes available
  146.     /// (see LobSize()), and the value can be obtained using GetData().
  147.     ///
  148.     /// <pre>
  149.     /// Typical usage for this function is:
  150.     /// 1. Call Fetch()
  151.     /// 2. Allocate LobSize() chunk of memory
  152.     /// 3. Use GetData() to retrive lob value
  153.     /// </pre>
  154.     EBDB_ErrCode Fetch(unsigned int lob_id);
  155.     /// Fetch LOB record directly into the provided '*buf'.
  156.     /// If size of the LOB is greater than 'buf_size', then
  157.     /// if reallocation is allowed -- '*buf' will be reallocated
  158.     /// to fit the LOB size; otherwise, a exception will be thrown.
  159.     EBDB_ErrCode Fetch(unsigned int lob_id, 
  160.                        void**       buf, 
  161.                        size_t       buf_size, 
  162.                        EReallocMode allow_realloc);
  163.     /// Get LOB size. Becomes available right after successfull Fetch.
  164.     size_t LobSize() const;
  165.     /// Copy LOB data into the 'buf'.
  166.     /// Throw an exception if buffer size 'size' is less than LOB size. 
  167.     EBDB_ErrCode GetData(void* buf, size_t size);
  168.     /// Comparison function for unsigned int key
  169.     virtual void SetCmp(DB*);
  170. private:
  171.     unsigned int  m_LobKey;  
  172. };
  173. /* @} */
  174. /////////////////////////////////////////////////////////////////////////////
  175. //  IMPLEMENTATION of INLINE functions
  176. /////////////////////////////////////////////////////////////////////////////
  177. /////////////////////////////////////////////////////////////////////////////
  178. //  CBDB_LobFile::
  179. //
  180. inline EBDB_ErrCode CBDB_LobFile::Fetch(unsigned int lob_id)
  181. {
  182.     return Fetch(lob_id, 0, 0, eReallocForbidden);
  183. }
  184. END_NCBI_SCOPE
  185. /*
  186.  * ===========================================================================
  187.  * $Log: bdb_blob.hpp,v $
  188.  * Revision 1000.1  2004/04/12 17:13:11  gouriano
  189.  * PRODUCTION: UPGRADED [CATCHUP_003] Dev-tree R1.14
  190.  *
  191.  * Revision 1.14  2003/12/29 17:06:04  kuznets
  192.  * +CBDB_BlobStream::SetTransaction()
  193.  *
  194.  * Revision 1.13  2003/12/29 16:51:21  kuznets
  195.  * Added transaction support for BLOB stream
  196.  *
  197.  * Revision 1.12  2003/10/24 13:39:59  kuznets
  198.  * + PendingCount for BlobStream
  199.  *
  200.  * Revision 1.11  2003/09/29 16:43:40  kuznets
  201.  * Returned back CBDB_LobFile::SetCmp function
  202.  * (was removed before out of good intentions)
  203.  *
  204.  * Revision 1.10  2003/09/26 20:54:37  kuznets
  205.  * Documentaion change
  206.  *
  207.  * Revision 1.9  2003/09/26 18:48:05  kuznets
  208.  * Doxigenification of comments
  209.  *
  210.  * Revision 1.8  2003/09/17 18:17:15  kuznets
  211.  * +CBDB_BLobStream class
  212.  *
  213.  * Revision 1.7  2003/07/02 17:53:59  kuznets
  214.  * Eliminated direct dependency from <db.h>
  215.  *
  216.  * Revision 1.6  2003/06/27 18:57:16  dicuccio
  217.  * Uninlined strerror() adaptor.  Changed to use #include<> instead of #include ""
  218.  *
  219.  * Revision 1.5  2003/06/10 20:07:27  kuznets
  220.  * Fixed header files not to repeat information from the README file
  221.  *
  222.  * Revision 1.4  2003/06/03 18:50:09  kuznets
  223.  * Added dll export/import specifications
  224.  *
  225.  * Revision 1.3  2003/05/05 20:14:41  kuznets
  226.  * Added CBDB_BLobFile, CBDB_File changed to support more flexible data record
  227.  * management.
  228.  *
  229.  * Revision 1.2  2003/04/29 16:48:31  kuznets
  230.  * Fixed minor warnings in Sun Workshop compiler
  231.  *
  232.  * Revision 1.1  2003/04/24 16:31:16  kuznets
  233.  * Initial revision
  234.  *
  235.  * ===========================================================================
  236.  */
  237. #endif