NCBI C++ ToolKit
bdb_blob.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef BDB___BLOB_HPP__
2 #define BDB___BLOB_HPP__
3 
4 /* $Id: bdb_blob.hpp 42205 2009-06-15 15:40:12Z ivanovp $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Author: Anatoliy Kuznetsov
30  *
31  * File Description: BDB library BLOB support.
32  *
33  */
34 
35 /// @file bdb_blob.hpp
36 /// BDB library BLOB support.
37 
39 #include <db/bdb/bdb_file.hpp>
40 
41 
43 
44 /** @addtogroup BDB_BLOB
45  *
46  * @{
47  */
48 
49 
50 class CBDB_BLobStream;
52 
53 /// Berkeley DB BLOB File class.
54 ///
55 /// The basic BLOB file. Key part of the file consists of one or more
56 /// fields. Data part is one binary object(BLOB).
57 
59 {
60 public:
61 
62  CBDB_BLobFile(EDuplicateKeys dup_keys = eDuplicatesDisable,
63  EDBType db_type = eBtree);
64 
65 
66  /// Insert BLOB into the database
67  ///
68  /// Before calling this function you should assign the key fields.
69  /// @param data BLOB data
70  /// @param size data size in bytes
71  EBDB_ErrCode Insert(const void* data, size_t size);
72 
73  /// Insert BLOB
75 
76  unsigned Append(const void* data, size_t size);
77 
78  /// Insert or update BLOB
79  ///
80  /// Before calling this function you should assign the key fields.
81  /// @param data BLOB data
82  /// @param size data size in bytes
83  EBDB_ErrCode UpdateInsert(const void* data, size_t size);
84 
85  /// Insert or update BLOB
87 
88 
89  /// Fetch the record corresponding to the current key value.
90  ///
91  /// Key fields should be assigned before calling this function.
92  /// This call actually translates into a BerkeleyDB call, so the target page
93  /// will be read from the disk into the BerkeleyDB internal cache.
94  /// You can call LobSize to get BLOB data size, allocate the target
95  /// buffer and then call GetData (two phase BLOB fetch).
96  /// If you know the data size upfront parameterized Fetch is a
97  /// better alternative.
99 
100  /// Retrieve BLOB data
101  ///
102  /// Fetch LOB record directly into the provided '*buf'.
103  /// If size of the LOB is greater than 'buf_size', then
104  /// if reallocation is allowed -- '*buf' will be reallocated
105  /// to fit the BLOB size; otherwise it throws an exception.
106  /// @param buf pointer on buffer pointer
107  /// @param buf_size buffer size
108  /// @param allow_realloc when "eReallocAllowed" Berkeley DB reallocates
109  /// the buffer to allow successful fetch
110  EBDB_ErrCode Fetch(void** buf,
111  size_t buf_size,
112  EReallocMode allow_realloc);
113 
114  /// Get LOB size. Becomes available right after successfull Fetch.
115  size_t LobSize() const;
116 
117  /// Get LOB size. Becomes available right after successfull Fetch.
118  size_t BlobSize() const { return LobSize(); }
119 
120  /// Read BLOB into vector.
121  /// If BLOB does not fit, method resizes the vector to accomodate.
122  ///
123  EBDB_ErrCode ReadRealloc(TBuffer& buffer);
124 
125  /// Copy LOB data into the 'buf'.
126  /// Throw an exception if buffer size 'size' is less than LOB size.
127  ///
128  /// @param buf destination data buffer
129  /// @param size data buffer size
130  /// @sa LobSize
131  EBDB_ErrCode GetData(void* buf, size_t size);
132 
133  /// Creates stream like object to retrieve or write BLOB by chunks.
134  /// Caller is responsible for deletion.
135  CBDB_BLobStream* CreateStream();
136 
137  /// Creates stream like object to retrieve or write BLOB by chunks.
138  /// Caller is responsible for deletion.
139  CBDB_BlobReaderWriter* CreateReaderWriter();
140 
141  /// Creates stream like object to read BLOB by chunks.
142  /// Return NULL if not found
143  IReader* CreateReader();
144 
145 private:
146  /// forbidden
149 };
150 
151 /// Variant of BLOB storage for integer key database
152 ///
154 {
155 public:
156  CBDB_FieldUint4 id; ///< ID key
157  Uint4 GetUid() const;
158 public:
159  CBDB_IdBlobFile(EDuplicateKeys dup_keys = eDuplicatesDisable,
160  EDBType db_type = eBtree);
161 
162  /// Hash for this type returns id (key);
163  virtual void SetHash(DB*);
164 };
165 
166 /// Stream style BDB BLOB reader
167 ///
168 /// Class wraps partial data access functionality of Berkeley DB.
169 /// All I/O directly calls corresponding Berkeley DB methods
170 /// without any buffering. For better performance it's advised to read or
171 /// write data in chunks of substantial size.
172 ///
174 {
175 protected:
176  CBDB_BlobReaderWriter(DB* db, DBT* dbt_key, size_t blob_size, DB_TXN* txn);
177 public:
179 
180  /// Set current transaction
181  void SetTransaction(CBDB_Transaction* trans);
182 
183 
184  virtual ERW_Result Read(void* buf,
185  size_t count,
186  size_t* bytes_read);
187  virtual ERW_Result PendingCount(size_t* count);
188 
189  virtual ERW_Result Write(const void* buf,
190  size_t count,
191  size_t* bytes_written);
192 
193  virtual ERW_Result Flush(void);
194 
195 private:
198  friend class CBDB_BLobFile;
199 private:
204  unsigned m_Pos;
205  size_t m_BlobSize;
206 };
207 
208 
209 class CBDB_BlobWriter;
210 
211 /// Berkeley DB BLOB File stream.
212 ///
213 /// Class wraps partial data read/write functionality of Berkeley DB.
214 /// Both Read and Write functions of the class directly call
215 /// corresponding Berkeley DB methods without any buffering. For performance
216 /// reasons it's advised to read or write data in chunks of substantial size.
217 
219 {
220 protected:
221  CBDB_BLobStream(DB* db, DBT* dbt_key, size_t blob_size, DB_TXN* txn);
222 public:
223 
224  ~CBDB_BLobStream();
225 
226  /// Set current transaction for BLOB stream
227  void SetTransaction(CBDB_Transaction* trans);
228 
229  /// Read data from BLOB
230  void Read(void *buf, size_t buf_size, size_t *bytes_read);
231  /// Write data into BLOB
232  void Write(const void* buf, size_t buf_size);
233 
234  /// Return how much bytes we can read from the blob
235  size_t PendingCount() const { return m_BlobSize > 0 ? (m_BlobSize - m_Pos) : 0; }
236 
237 private:
240 private:
245  unsigned m_Pos;
246  size_t m_BlobSize;
247 private:
248  friend class CBDB_BLobFile;
249 };
250 
251 
252 
253 /// Berkeley DB Large Object File class.
254 /// Implements simple BLOB storage based on single unsigned integer key
255 
257 {
258 public:
259  CBDB_LobFile();
260 
261  /// Insert BLOB data into the database, does nothing if key exists
262  ///
263  /// @param lob_id insertion key
264  /// @param data buffer pointer
265  /// @param size data size in bytes
266  EBDB_ErrCode Insert(unsigned int lob_id, const void* data, size_t size);
267 
268  /// Insert or Update BLOB data into the database
269  ///
270  /// @param lob_id insertion key
271  /// @param data buffer pointer
272  /// @param size data size in bytes
273  EBDB_ErrCode InsertUpdate(unsigned int lob_id, const void* data, size_t size);
274 
275  /// Fetch LOB record. On success, LOB size becomes available
276  /// (see LobSize()), and the value can be obtained using GetData().
277  ///
278  /// <pre>
279  /// Typical usage for this function is:
280  /// 1. Call Fetch()
281  /// 2. Allocate LobSize() chunk of memory
282  /// 3. Use GetData() to retrive lob value
283  /// </pre>
284  EBDB_ErrCode Fetch(unsigned int lob_id);
285 
286  /// Fetch LOB record directly into the provided '*buf'.
287  /// If size of the LOB is greater than 'buf_size', then
288  /// if reallocation is allowed -- '*buf' will be reallocated
289  /// to fit the LOB size; otherwise, a exception will be thrown.
290  EBDB_ErrCode Fetch(unsigned int lob_id,
291  void** buf,
292  size_t buf_size,
293  EReallocMode allow_realloc);
294 
295  /// Get LOB size. Becomes available right after successfull Fetch.
296  size_t LobSize() const;
297 
298  /// Copy LOB data into the 'buf'.
299  /// Throw an exception if buffer size 'size' is less than LOB size.
300  EBDB_ErrCode GetData(void* buf, size_t size);
301 
302  unsigned int GetKey() const { return m_LobKey; }
303 
304  /// Comparison function for unsigned int key
305  virtual void SetCmp(DB*);
306 
307 private:
308  EBDB_ErrCode x_Put(unsigned int lob_id, const void* data, size_t size, bool can_update);
309 
310  unsigned int m_LobKey;
311 };
312 
313 
314 /* @} */
315 
316 
317 /////////////////////////////////////////////////////////////////////////////
318 // IMPLEMENTATION of INLINE functions
319 /////////////////////////////////////////////////////////////////////////////
320 
321 
322 
323 /////////////////////////////////////////////////////////////////////////////
324 // CBDB_LobFile::
325 //
326 
327 
328 inline EBDB_ErrCode CBDB_LobFile::Fetch(unsigned int lob_id)
329 {
330  return Fetch(lob_id, 0, 0, eReallocForbidden);
331 }
332 
333 /////////////////////////////////////////////////////////////////////////////
334 // CBDB_BLobFile::
335 //
336 
338 {
339  return Insert(&buf[0], buf.size());
340 }
341 
343 {
344  return UpdateInsert(&buf[0], buf.size());
345 }
346 
347 
349 
350 
351 
352 #endif
BDB File management.
struct __db DB
Definition: bdb_types.hpp:52
struct __db_txn DB_TXN
Definition: bdb_types.hpp:55
struct __db_dbt DBT
Definition: bdb_types.hpp:51
Berkeley DB BLOB File class.
Definition: bdb_blob.hpp:59
Berkeley DB BLOB File stream.
Definition: bdb_blob.hpp:219
Stream style BDB BLOB reader.
Definition: bdb_blob.hpp:174
Uint4 field type.
Definition: bdb_types.hpp:1267
Berkeley DB file class.
Definition: bdb_file.hpp:445
Variant of BLOB storage for integer key database.
Definition: bdb_blob.hpp:154
Berkeley DB Large Object File class.
Definition: bdb_blob.hpp:257
Raw file class wraps up basic Berkeley DB operations.
Definition: bdb_file.hpp:73
BDB transaction object.
Definition: bdb_trans.hpp:63
Reallocable memory buffer (no memory copy overhead) Mimics vector<>, without the overhead of explicit...
A very basic data-read/write interface.
A very basic data-read interface.
Abstract reader-writer interface classes.
char data[12]
Definition: iconv.c:80
CBDB_BlobReaderWriter(const CBDB_BlobReaderWriter &)
unsigned int GetKey() const
Definition: bdb_blob.hpp:302
EBDB_ErrCode Insert(const void *data, size_t size)
Insert BLOB into the database.
Definition: bdb_blob.cpp:135
unsigned int m_LobKey
Definition: bdb_blob.hpp:310
CBDB_BLobStream & operator=(const CBDB_BLobStream &)
DB_TXN * m_Txn
Definition: bdb_blob.hpp:244
unsigned m_Pos
Definition: bdb_blob.hpp:245
CBDB_BLobFile & operator=(const CBDB_BLobFile &)
EBDB_ErrCode Fetch(unsigned int lob_id)
Fetch LOB record.
Definition: bdb_blob.hpp:328
EBDB_ErrCode UpdateInsert(const void *data, size_t size)
Insert or update BLOB.
Definition: bdb_blob.cpp:155
size_t m_BlobSize
Definition: bdb_blob.hpp:246
CBDB_BlobReaderWriter & operator=(const CBDB_BlobReaderWriter &)
CBDB_BLobStream(const CBDB_BLobStream &)
CBDB_BLobFile(const CBDB_BLobFile &)
forbidden
CBDB_FieldUint4 id
ID key.
Definition: bdb_blob.hpp:156
size_t BlobSize() const
Get LOB size. Becomes available right after successfull Fetch.
Definition: bdb_blob.hpp:118
size_t PendingCount() const
Return how much bytes we can read from the blob.
Definition: bdb_blob.hpp:235
unsigned Append(EAfterWrite write_flag=eDiscardData)
Append record to the queue (works only for DB_QUEUE database type)
Definition: bdb_file.cpp:1479
EBDB_ErrCode Insert(EAfterWrite write_flag=eDiscardData)
Insert new record.
Definition: bdb_file.cpp:1466
EBDB_ErrCode UpdateInsert(EAfterWrite write_flag=eDiscardData)
Update record corresponding to the current key value.
Definition: bdb_file.cpp:1489
virtual void SetHash(DB *)
Set hash function.
Definition: bdb_file.cpp:973
EDBType
Berkeley DB database type.
Definition: bdb_file.hpp:86
virtual void SetTransaction(ITransaction *trans)
Establish transaction association.
Definition: bdb_file.cpp:602
EDuplicateKeys
Control key duplicates in Btree.
Definition: bdb_file.hpp:101
EReallocMode
BLOB read mode, controld data buffer reallocation when there is not enough space in buffer.
Definition: bdb_file.hpp:95
EBDB_ErrCode
BDB Return codes.
Definition: bdb_file.hpp:57
virtual void SetCmp(DB *)
Set comparison function.
Definition: bdb_file.cpp:1559
EBDB_ErrCode Fetch()
Fetches the record corresponding to the current key value.
Definition: bdb_file.hpp:471
@ eReallocForbidden
Definition: bdb_file.hpp:97
void Read(CObjectIStream &in, TObjectPtr object, const CTypeRef &type)
Definition: serial.cpp:60
void Write(CObjectOStream &out, TConstObjectPtr object, const CTypeRef &type)
Definition: serial.cpp:55
uint32_t Uint4
4-byte (32-bit) unsigned integer
Definition: ncbitype.h:103
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
ERW_Result
Result codes for I/O operations.
#define NCBI_BDB_EXPORT
Definition: ncbi_export.h:272
char * buf
const struct ncbi::grid::netcache::search::fields::SIZE size
static pcre_uint8 * buffer
Definition: pcretest.c:1051
Modified on Sun Apr 14 05:24:38 2024 by modify_doxy.py rev. 669887