# kyotocabinet::ProtoDB< STRMAP, DBTYPE > Class Template Reference

Prototype implementation of database with STL. More...

`#include <kcprotodb.h>`

List of all members.

## Classes

class | Cursor
| Cursor to indicate a record. More...
struct | TranLog
| Transaction log.

## Public Member Functions

| ProtoDB ()
| Default constructor.
virtual | ~ProtoDB ()
| Destructor.
bool | accept (const char *kbuf, size_t ksiz, Visitor *visitor, bool writable=true)
| Accept a visitor to a record.
bool | iterate (Visitor *visitor, bool writable=true)
| Iterate to accept a visitor for each record.
Error | error () const
| Get the last happened error.
void | set_error (Error::Code code, const char *message)
| Set the error information.
bool | open (const std::string &path, uint32_t mode=OWRITER|OCREATE)
| Open a database file.
bool | close ()
| Close the database file.
bool | synchronize (bool hard=false, FileProcessor *proc=NULL)
| Synchronize updated contents with the file and the device.
bool | begin_transaction (bool hard=false)
| Begin transaction.
bool | begin_transaction_try (bool hard=false)
| Try to begin transaction.
bool | end_transaction (bool commit=true)
| End transaction.
bool | clear ()
| Remove all records.
int64_t | count ()
| Get the number of records.
int64_t | size ()
| Get the size of the database file.
std::string | path ()
| Get the path of the database file.
bool | status (std::map< std::string, std::string > *strmap)
| Get the miscellaneous status information.
Cursor * | cursor ()
| Create a cursor object.
char * | opaque ()
| Get the opaque data.
bool | synchronize_opaque ()
| Synchronize the opaque data.

## Detailed Description

### template<class STRMAP, uint8_t DBTYPE>
class kyotocabinet::ProtoDB< STRMAP, DBTYPE >

Prototype implementation of database with STL.

Parameters:

  | STRMAP | a class compatible with the map class of STL.
  | DBTYPE | the database type number of the class.

Note:
  This class template is a template for concrete classes which wrap data structures compatible with std::map. Template instance classes can be inherited but overwriting methods is forbidden. The class ProtoHashDB is the instance using std::unordered_map. The class ProtoTreeDB is the instance using std::map. Before every database operation, it is necessary to call the BasicDB::open method in order to open a database file and connect the database object to it. To avoid data missing or corruption, it is important to close every database file by the BasicDB::close method when the database is no longer in use. It is forbidden for multible database objects in a process to open the same database at the same time.

## Constructor & Destructor Documentation

template<class STRMAP , uint8_t DBTYPE>

kyotocabinet::ProtoDB< STRMAP, DBTYPE >::ProtoDB | ( |  | ) | `[explicit]`

Default constructor.

template<class STRMAP , uint8_t DBTYPE>

virtual kyotocabinet::ProtoDB< STRMAP, DBTYPE >::~ProtoDB | ( |  | ) | `[virtual]`

Destructor.

Note:
  If the database is not closed, it is closed implicitly.

## Member Function Documentation

template<class STRMAP , uint8_t DBTYPE>

bool kyotocabinet::ProtoDB< STRMAP, DBTYPE >::accept | ( | const char * | kbuf,
|  | size_t | ksiz,
|  | Visitor * | visitor,
|  | bool | writable = `true` |
| ) |  |  | `[virtual]`

Accept a visitor to a record.

Parameters:

  | kbuf | the pointer to the key region.
  | ksiz | the size of the key region.
  | visitor | a visitor object.
  | writable | true for writable operation, or false for read-only operation.

Returns:
  true on success, or false on failure.

Note:
  the operation for each record is performed atomically and other threads accessing the same record are blocked.

Implements kyotocabinet::DB.

template<class STRMAP , uint8_t DBTYPE>

bool kyotocabinet::ProtoDB< STRMAP, DBTYPE >::iterate | ( | Visitor * | visitor,
|  | bool | writable = `true` |
| ) |  |  | `[virtual]`

Iterate to accept a visitor for each record.

Parameters:

  | visitor | a visitor object.
  | writable | true for writable operation, or false for read-only operation.

Returns:
  true on success, or false on failure.

Note:
  the whole iteration is performed atomically and other threads are blocked.

Implements kyotocabinet::DB.

template<class STRMAP , uint8_t DBTYPE>

Error kyotocabinet::ProtoDB< STRMAP, DBTYPE >::error | ( |  | ) | const`[virtual]`

Get the last happened error.

Returns:
  the last happened error.

Implements kyotocabinet::BasicDB.

template<class STRMAP , uint8_t DBTYPE>

void kyotocabinet::ProtoDB< STRMAP, DBTYPE >::set_error | ( | Error::Code | code,
|  | const char * | message |
| ) |  |  |

Set the error information.

Parameters:

  | code | an error code.
  | message | a supplement message.

template<class STRMAP , uint8_t DBTYPE>

bool kyotocabinet::ProtoDB< STRMAP, DBTYPE >::open | ( | const std::string & | path,
|  | uint32_t | mode = `OWRITER | OCREATE` |
| ) |  |  | `[virtual]`

Open a database file.

Parameters:

  | path | the path of a database file.

  mode

  the connection mode. BasicDB::OWRITER as a writer, BasicDB::OREADER as a reader. The following may be added to the writer mode by bitwise-or: BasicDB::OCREATE, which means it creates a new database if the file does not exist, BasicDB::OTRUNCATE, which means it creates a new database regardless if the file exists, BasicDB::OAUTOTRAN, which means each updating operation is performed in implicit transaction, BasicDB::OAUTOSYNC, which means each updating operation is followed by implicit synchronization with the file system. The following may be added to both of the reader mode and the writer mode by bitwise-or: BasicDB::ONOLOCK, which means it opens the database file without file locking, BasicDB::OTRYLOCK, which means locking is performed without blocking, BasicDB::ONOREPAIR, which means the database file is not repaired implicitly even if file destruction is detected.

Returns:
  true on success, or false on failure.

Note:
  Every opened database must be closed by the BasicDB::close method when it is no longer in use. It is not allowed for two or more database objects in the same process to keep their connections to the same database file at the same time.

Implements kyotocabinet::BasicDB.

template<class STRMAP , uint8_t DBTYPE>

bool kyotocabinet::ProtoDB< STRMAP, DBTYPE >::close | ( |  | ) | `[virtual]`

Close the database file.

Returns:
  true on success, or false on failure.

Implements kyotocabinet::BasicDB.

template<class STRMAP , uint8_t DBTYPE>

bool kyotocabinet::ProtoDB< STRMAP, DBTYPE >::synchronize | ( | bool | hard = `false`,
|  | FileProcessor * | proc = `NULL` |
| ) |  |  | `[virtual]`

Synchronize updated contents with the file and the device.

Parameters:

  | hard | true for physical synchronization with the device, or false for logical synchronization with the file system.
  | proc | a postprocessor object. If it is NULL, no postprocessing is performed.

Returns:
  true on success, or false on failure.

Implements kyotocabinet::BasicDB.

template<class STRMAP , uint8_t DBTYPE>

bool kyotocabinet::ProtoDB< STRMAP, DBTYPE >::begin_transaction | ( | bool | hard = `false` | ) | `[virtual]`

Begin transaction.

Parameters:

  | hard | true for physical synchronization with the device, or false for logical synchronization with the file system.

Returns:
  true on success, or false on failure.

Implements kyotocabinet::BasicDB.

template<class STRMAP , uint8_t DBTYPE>

bool kyotocabinet::ProtoDB< STRMAP, DBTYPE >::begin_transaction_try | ( | bool | hard = `false` | ) | `[virtual]`

Try to begin transaction.

Parameters:

  | hard | true for physical synchronization with the device, or false for logical synchronization with the file system.

Returns:
  true on success, or false on failure.

Implements kyotocabinet::BasicDB.

template<class STRMAP , uint8_t DBTYPE>

bool kyotocabinet::ProtoDB< STRMAP, DBTYPE >::end_transaction | ( | bool | commit = `true` | ) | `[virtual]`

End transaction.

Parameters:

  | commit | true to commit the transaction, or false to abort the transaction.

Returns:
  true on success, or false on failure.

Implements kyotocabinet::BasicDB.

template<class STRMAP , uint8_t DBTYPE>

bool kyotocabinet::ProtoDB< STRMAP, DBTYPE >::clear | ( |  | ) | `[virtual]`

Remove all records.

Returns:
  true on success, or false on failure.

Implements kyotocabinet::DB.

template<class STRMAP , uint8_t DBTYPE>

int64_t kyotocabinet::ProtoDB< STRMAP, DBTYPE >::count | ( |  | ) | `[virtual]`

Get the number of records.

Returns:
  the number of records, or -1 on failure.

Implements kyotocabinet::DB.

template<class STRMAP , uint8_t DBTYPE>

int64_t kyotocabinet::ProtoDB< STRMAP, DBTYPE >::size | ( |  | ) | `[virtual]`

Get the size of the database file.

Returns:
  the size of the database file in bytes, or -1 on failure.

Implements kyotocabinet::BasicDB.

template<class STRMAP , uint8_t DBTYPE>

std::string kyotocabinet::ProtoDB< STRMAP, DBTYPE >::path | ( |  | ) | `[virtual]`

Get the path of the database file.

Returns:
  the path of the database file, or an empty string on failure.

Implements kyotocabinet::BasicDB.

template<class STRMAP , uint8_t DBTYPE>

bool kyotocabinet::ProtoDB< STRMAP, DBTYPE >::status | ( | std::map< std::string, std::string > * | strmap | ) | `[virtual]`

Get the miscellaneous status information.

Parameters:

  | strmap | a string map to contain the result.

Returns:
  true on success, or false on failure.

Implements kyotocabinet::BasicDB.

template<class STRMAP , uint8_t DBTYPE>

Cursor* kyotocabinet::ProtoDB< STRMAP, DBTYPE >::cursor | ( |  | ) | `[virtual]`

Create a cursor object.

Returns:
  the return value is the created cursor object.

Note:
  Because the object of the return value is allocated by the constructor, it should be released with the delete operator when it is no longer in use.

Implements kyotocabinet::BasicDB.

template<class STRMAP , uint8_t DBTYPE>

char* kyotocabinet::ProtoDB< STRMAP, DBTYPE >::opaque | ( |  | ) |

Get the opaque data.

Returns:
  the pointer to the opaque data region, whose size is 16 bytes.

template<class STRMAP , uint8_t DBTYPE>

bool kyotocabinet::ProtoDB< STRMAP, DBTYPE >::synchronize_opaque | ( |  | ) |

Synchronize the opaque data.

Returns:
  true on success, or false on failure.