/*-
* See the file LICENSE for redistribution information.
*
* Copyright (c) 2009 Oracle. All rights reserved.
*
*/
using System;
using System.Collections.Generic;
using System.Text;
using BerkeleyDB.Internal;
namespace BerkeleyDB {
/// <summary>
/// The base class from which all database classes inherit
/// </summary>
public class BaseDatabase : IDisposable {
internal DB db;
protected internal DatabaseEnvironment env;
protected internal bool isOpen;
private DBTCopyDelegate CopyDelegate;
private EntryComparisonDelegate dupCompareHandler;
private DatabaseFeedbackDelegate feedbackHandler;
private BDB_CompareDelegate doDupCompareRef;
private BDB_DbFeedbackDelegate doFeedbackRef;
#region Constructors
/// <summary>
/// Protected constructor
/// </summary>
/// <param name="envp">
/// The environment in which to create this database
/// </param>
/// <param name="flags">Flags to pass to the DB->create() method</param>
protected BaseDatabase(DatabaseEnvironment envp, uint flags) {
db = new DB(envp == null ? null : envp.dbenv, flags);
db.api_internal = this;
if (envp == null) {
env = new DatabaseEnvironment(db.env());
} else
env = envp;
}
/// <summary>
/// Create a new database object with the same underlying DB handle as
/// <paramref name="clone"/>. Used during Database.Open to get an
/// object of the correct DBTYPE.
/// </summary>
/// <param name="clone">Database to clone</param>
protected BaseDatabase(BaseDatabase clone) {
db = clone.db;
clone.db = null;
db.api_internal = this;
env = clone.env;
clone.env = null;
}
internal void Config(DatabaseConfig cfg) {
// The cache size cannot change.
if (cfg.CacheSize != null)
db.set_cachesize(cfg.CacheSize.Gigabytes,
cfg.CacheSize.Bytes, cfg.CacheSize.NCaches);
if (cfg.encryptionIsSet)
db.set_encrypt(
cfg.EncryptionPassword, (uint)cfg.EncryptAlgorithm);
if (cfg.ErrorPrefix != null)
ErrorPrefix = cfg.ErrorPrefix;
if (cfg.ErrorFeedback != null)
ErrorFeedback = cfg.ErrorFeedback;
if (cfg.Feedback != null)
Feedback = cfg.Feedback;
db.set_flags(cfg.flags);
if (cfg.ByteOrder != ByteOrder.MACHINE)
db.set_lorder(cfg.ByteOrder.lorder);
if (cfg.pagesizeIsSet)
db.set_pagesize(cfg.PageSize);
if (cfg.Priority != CachePriority.DEFAULT)
db.set_priority(cfg.Priority.priority);
}
/// <summary>
/// Protected factory method to create and open a new database object.
/// </summary>
/// <param name="Filename">The database's filename</param>
/// <param name="DatabaseName">The subdatabase's name</param>
/// <param name="cfg">The database's configuration</param>
/// <param name="txn">
/// The transaction in which to open the database
/// </param>
/// <returns>A new, open database object</returns>
protected static BaseDatabase Open(string Filename,
string DatabaseName, DatabaseConfig cfg, Transaction txn) {
BaseDatabase ret = new BaseDatabase(cfg.Env, 0);
ret.Config(cfg);
ret.db.open(Transaction.getDB_TXN(txn),
Filename, DatabaseName, DBTYPE.DB_UNKNOWN, cfg.openFlags, 0);
return ret;
}
#endregion Constructor
#region Callbacks
private static void doFeedback(IntPtr dbp, int opcode, int percent) {
DB db = new DB(dbp, false);
db.api_internal.Feedback((DatabaseFeedbackEvent)opcode, percent);
}
#endregion Callbacks
#region Properties
// Sorted alpha by property name
/// <summary>
/// If true, all database modification operations based on this object
/// will be transactionally protected.
/// </summary>
public bool AutoCommit {
get {
uint flags = 0;
db.get_open_flags(ref flags);
return (flags & DbConstants.DB_AUTO_COMMIT) != 0;
}
}
/// <summary>
/// The size of the shared memory buffer pool -- that is, the cache.
/// </summary>
public CacheInfo CacheSize {
get {
uint gb = 0;
uint b = 0;
int n = 0;
db.get_cachesize(ref gb, ref b, ref n);
return new CacheInfo(gb, b, n);
}
}
/// <summary>
/// The CreatePolicy with which this database was opened.
/// </summary>
public CreatePolicy Creation {
get {
uint flags = 0;
db.get_open_flags(ref flags);
if ((flags & DbConstants.DB_EXCL) != 0)
return CreatePolicy.ALWAYS;
else if ((flags & DbConstants.DB_CREATE) != 0)
return CreatePolicy.IF_NEEDED;
else
return CreatePolicy.NEVER;
}
}
/// <summary>
/// The name of this database, if it has one.
/// </summary>
public string DatabaseName {
get {
string ret = "";
string tmp = "";
db.get_dbname(ref tmp, ref ret);
return ret;
}
}
/// <summary>
/// If true, do checksum verification of pages read into the cache from
/// the backing filestore.
/// </summary>
/// <remarks>
/// Berkeley DB uses the SHA1 Secure Hash Algorithm if encryption is
/// configured and a general hash algorithm if it is not.
/// </remarks>
public bool DoChecksum {
get {
uint flags = 0;
db.get_flags(ref flags);
return (flags & DbConstants.DB_CHKSUM) != 0;
}
}
/// <summary>
/// The algorithm used by the Berkeley DB library to perform encryption
/// and decryption.
/// </summary>
public EncryptionAlgorithm EncryptAlgorithm {
get {
uint flags = 0;
db.get_encrypt_flags(ref flags);
return (EncryptionAlgorithm)Enum.ToObject(
typeof(EncryptionAlgorithm), flags);
}
}
/// <summary>
/// If true, encrypt all data stored in the database.
/// </summary>
public bool Encrypted {
get {
uint flags = 0;
db.get_flags(ref flags);
return (flags & DbConstants.DB_ENCRYPT) != 0;
}
}
/// <summary>
/// The database byte order.
/// </summary>
public ByteOrder Endianness {
get {
int lorder = 0;
db.get_lorder(ref lorder);
return ByteOrder.FromConst(lorder);
}
}
/// <summary>
/// The mechanism for reporting detailed error messages to the
/// application.
/// </summary>
/// <remarks>
/// <para>
/// When an error occurs in the Berkeley DB library, a
/// <see cref="DatabaseException"/>, or subclass of DatabaseException,
/// is thrown. In some cases, however, the exception may be insufficient
/// to completely describe the cause of the error, especially during
/// initial application debugging.
/// </para>
/// <para>
/// In some cases, when an error occurs, Berkeley DB will call the given
/// delegate with additional error information. It is up to the delegate
/// to display the error message in an appropriate manner.
/// </para>
/// <para>
/// Setting ErrorFeedback to NULL unconfigures the callback interface.
/// </para>
/// <para>
/// This error-logging enhancement does not slow performance or
/// significantly increase application size, and may be run during
/// normal operation as well as during application debugging.
/// </para>
/// <para>
/// For databases opened inside of a DatabaseEnvironment, setting
/// ErrorFeedback affects the entire environment and is equivalent to
/// setting DatabaseEnvironment.ErrorFeedback.
/// </para>
/// <para>
/// For databases not opened in an environment, setting ErrorFeedback
/// configures operations performed using the specified object, not all
/// operations performed on the underlying database.
/// </para>
/// </remarks>
public ErrorFeedbackDelegate ErrorFeedback {
get { return env.ErrorFeedback; }
set { env.ErrorFeedback = value; }
}
/// <summary>
/// The prefix string that appears before error messages issued by
/// Berkeley DB.
/// </summary>
/// <remarks>
/// <para>
/// For databases opened inside of a DatabaseEnvironment, setting
/// ErrorPrefix affects the entire environment and is equivalent to
/// setting <see cref="DatabaseEnvironment.ErrorPrefix"/>.
/// </para>
/// <para>
/// Setting ErrorPrefix configures operations performed using the
/// specified object, not all operations performed on the underlying
/// database.
/// </para>
/// </remarks>
public string ErrorPrefix {
get { return env.ErrorPrefix; }
set { env.ErrorPrefix = value; }
}
/// <summary>
/// Monitor progress within long running operations.
/// </summary>
/// <remarks>
/// <para>
/// Some operations performed by the Berkeley DB library can take
/// non-trivial amounts of time. The Feedback delegate can be used by
/// applications to monitor progress within these operations. When an
/// operation is likely to take a long time, Berkeley DB will call the
/// specified delegate with progress information.
/// </para>
/// <para>
/// It is up to the delegate to display this information in an
/// appropriate manner.
/// </para>
/// </remarks>
public DatabaseFeedbackDelegate Feedback {
get { return feedbackHandler; }
set {
if (value == null)
db.set_feedback(null);
else if (feedbackHandler == null) {
if (doFeedbackRef == null)
doFeedbackRef = new BDB_DbFeedbackDelegate(doFeedback);
db.set_feedback(doFeedbackRef);
}
feedbackHandler = value;
}
}
/// <summary>
/// The filename of this database, if it has one.
/// </summary>
public string FileName {
get {
string ret = "";
string tmp = "";
db.get_dbname(ref ret, ref tmp);
return ret;
}
}
/// <summary>
/// If true, the object is free-threaded; that is, concurrently usable
/// by multiple threads in the address space.
/// </summary>
public bool FreeThreaded {
get {
uint flags = 0;
db.get_open_flags(ref flags);
return (flags & DbConstants.DB_THREAD) != 0;
}
}
/// <summary>
/// If true, the object references a physical file supporting multiple
/// databases.
/// </summary>
/// <remarks>
/// If true, the object is a handle on a database whose key values are
/// the names of the databases stored in the physical file and whose
/// data values are opaque objects. No keys or data values may be
/// modified or stored using the database handle.
/// </remarks>
public bool HasMultiple { get { return (db.get_multiple() != 0); } }
/// <summary>
/// If true, the underlying database files were created on an
/// architecture of the same byte order as the current one. This
/// information may be used to determine whether application data needs
/// to be adjusted for this architecture or not.
/// </summary>
public bool InHostOrder {
get {
int isswapped = 0;
db.get_byteswapped(ref isswapped);
return (isswapped == 0);
}
}
/// <summary>
/// <para>
/// If true, this database is not mapped into process memory.
/// </para>
/// <para>
/// See <see cref="DatabaseEnvironment.MMapSize"/> for further
/// information.
/// </para>
/// </summary>
public bool NoMMap {
get {
uint flags = 0;
db.get_open_flags(ref flags);
return (flags & DbConstants.DB_NOMMAP) == 0;
}
}
/// <summary>
/// If true, Berkeley DB will not write log records for this database.
/// </summary>
public bool NonDurableTxns {
get {
uint flags = 0;
db.get_flags(ref flags);
return (flags & DbConstants.DB_TXN_NOT_DURABLE) != 0;
}
}
/// <summary>
/// The database's current page size.
/// </summary>
/// <remarks> If <see cref="DatabaseConfig.PageSize"/> was not set by
/// your application, then the default pagesize is selected based on the
/// underlying filesystem I/O block size.
/// </remarks>
public uint Pagesize {
get {
uint pgsz = 0;
db.get_pagesize(ref pgsz);
return pgsz;
}
}
/// <summary>
/// The cache priority for pages referenced by this object.
/// </summary>
public CachePriority Priority {
get {
uint pri = 0;
db.get_priority(ref pri);
return CachePriority.fromUInt(pri);
}
}
/// <summary>
/// If true, this database has been opened for reading only. Any attempt
/// to modify items in the database will fail, regardless of the actual
/// permissions of any underlying files.
/// </summary>
public bool ReadOnly {
get {
uint flags = 0;
db.get_open_flags(ref flags);
return (flags & DbConstants.DB_RDONLY) != 0;
}
}
/// <summary>
/// If true, this database supports transactional read operations with
/// degree 1 isolation. Read operations on the database may request the
/// return of modified but not yet committed data.
/// </summary>
public bool ReadUncommitted {
get {
uint flags = 0;
db.get_open_flags(ref flags);
return (flags & DbConstants.DB_READ_UNCOMMITTED) != 0;
}
}
/// <summary>
/// If true, this database has been opened in a transactional mode.
/// </summary>
public bool Transactional {
get { return (db.get_transactional() != 0); }
}
/// <summary>
/// If true, the underlying file was physically truncated upon open,
/// discarding all previous databases it might have held.
/// </summary>
public bool Truncated {
get {
uint flags = 0;
db.get_open_flags(ref flags);
return (flags & DbConstants.DB_TRUNCATE) != 0;
}
}
/// <summary>
/// The type of the underlying access method (and file format). This
/// value may be used to determine the type of the database after an
/// <see cref="Database.Open"/>.
/// </summary>
public DatabaseType Type {
get {
DBTYPE mytype = DBTYPE.DB_UNKNOWN;
db.get_type(ref mytype);
switch (mytype) {
case DBTYPE.DB_BTREE:
return DatabaseType.BTREE;
case DBTYPE.DB_HASH:
return DatabaseType.HASH;
case DBTYPE.DB_QUEUE:
return DatabaseType.QUEUE;
case DBTYPE.DB_RECNO:
return DatabaseType.RECNO;
default:
return DatabaseType.UNKNOWN;
}
}
}
/// <summary>
/// If true, the database was opened with support for multiversion
/// concurrency control.
/// </summary>
public bool UseMVCC {
get {
uint flags = 0;
db.get_open_flags(ref flags);
return (flags & DbConstants.DB_MULTIVERSION) != 0;
}
}
#endregion Properties
#region Methods
//Sorted alpha by method name
/// <summary>
/// Flush any cached database information to disk, close any open
/// <see cref="Cursor"/> objects, free any
/// allocated resources, and close any underlying files.
/// </summary>
/// <overloads>
/// <para>
/// Although closing a database will close any open cursors, it is
/// recommended that applications explicitly close all their Cursor
/// objects before closing the database. The reason why is that when the
/// cursor is explicitly closed, the memory allocated for it is
/// reclaimed; however, this will not happen if you close a database
/// while cursors are still opened.
/// </para>
/// <para>
/// The same rule, for the same reasons, hold true for
/// <see cref="Transaction"/> objects. Simply make sure you resolve
/// all your transaction objects before closing your database handle.
/// </para>
/// <para>
/// Because key/data pairs are cached in memory, applications should
/// make a point to always either close database handles or sync their
/// data to disk (using <see cref="Sync"/> before exiting, to
/// ensure that any data cached in main memory are reflected in the
/// underlying file system.
/// </para>
/// <para>
/// When called on a database that is the primary database for a
/// secondary index, the primary database should be closed only after
/// all secondary indices referencing it have been closed.
/// </para>
/// <para>
/// When multiple threads are using the object concurrently, only a
/// single thread may call the Close method.
/// </para>
/// <para>
/// The object may not be accessed again after Close is called,
/// regardless of its outcome.
/// </para>
/// </overloads>
public void Close() {
Close(true);
}
/// <summary>
/// Optionally flush any cached database information to disk, close any
/// open <see cref="BaseDatabase.Cursor"/> objects, free
/// any allocated resources, and close any underlying files.
/// </summary>
/// <param name="sync">
/// If false, do not flush cached information to disk.
/// </param>
/// <remarks>
/// <para>
/// The sync parameter is a dangerous option. It should be set to false
/// only if the application is doing logging (with transactions) so that
/// the database is recoverable after a system or application crash, or
/// if the database is always generated from scratch after any system or
/// application crash.
/// </para>
/// <para>
/// It is important to understand that flushing cached information to
/// disk only minimizes the window of opportunity for corrupted data.
/// Although unlikely, it is possible for database corruption to happen
/// if a system or application crash occurs while writing data to the
/// database. To ensure that database corruption never occurs,
/// applications must either use transactions and logging with automatic
/// recovery or edit a copy of the database, and once all applications
/// using the database have successfully called Close, atomically
/// replace the original database with the updated copy.
/// </para>
/// <para>
/// Note that this parameter only works when the database has been
/// opened using an environment.
/// </para>
/// </remarks>
public void Close(bool sync) {
db.close(sync ? 0 : DbConstants.DB_NOSYNC);
isOpen = false;
}
/// <summary>
/// Create a database cursor.
/// </summary>
/// <returns>A newly created cursor</returns>
public Cursor Cursor() { return Cursor(new CursorConfig(), null); }
/// <summary>
/// Create a database cursor with the given configuration.
/// </summary>
/// <param name="cfg">
/// The configuration properties for the cursor.
/// </param>
/// <returns>A newly created cursor</returns>
public Cursor Cursor(CursorConfig cfg) { return Cursor(cfg, null); }
/// <summary>
/// Create a transactionally protected database cursor.
/// </summary>
/// <param name="txn">
/// The transaction context in which the cursor may be used.
/// </param>
/// <returns>A newly created cursor</returns>
public Cursor Cursor(Transaction txn) {
return Cursor(new CursorConfig(), txn);
}
/// <summary>
/// Create a transactionally protected database cursor with the given
/// configuration.
/// </summary>
/// <param name="cfg">
/// The configuration properties for the cursor.
/// </param>
/// <param name="txn">
/// The transaction context in which the cursor may be used.
/// </param>
/// <returns>A newly created cursor</returns>
public Cursor Cursor(CursorConfig cfg, Transaction txn) {
return new Cursor(db.cursor(
Transaction.getDB_TXN(txn), cfg.flags), Type, Pagesize);
}
/// <summary>
/// Remove key/data pairs from the database. The key/data pair
/// associated with <paramref name="key"/> is discarded from the
/// database. In the presence of duplicate key values, all records
/// associated with the designated key will be discarded.
/// </summary>
/// <remarks>
/// <para>
/// When called on a secondary database, remove the key/data pair from
/// the primary database and all secondary indices.
/// </para>
/// <para>
/// If the operation occurs in a transactional database, the operation
/// will be implicitly transaction protected.
/// </para>
/// </remarks>
/// <param name="key">
/// Discard the key/data pair associated with <paramref name="key"/>.
/// </param>
/// <exception cref="NotFoundException">
/// A NotFoundException is thrown if <paramref name="key"/> is not in
/// the database.
/// </exception>
/// <exception cref="KeyEmptyException">
/// A KeyEmptyException is thrown if the database is a
/// <see cref="QueueDatabase"/> or <see cref="RecnoDatabase"/>
/// database and <paramref name="key"/> exists, but was never explicitly
/// created by the application or was later deleted.
/// </exception>
public void Delete(DatabaseEntry key) {
Delete(key, null);
}
/// <summary>
/// Remove key/data pairs from the database. The key/data pair
/// associated with <paramref name="key"/> is discarded from the
/// database. In the presence of duplicate key values, all records
/// associated with the designated key will be discarded.
/// </summary>
/// <remarks>
/// <para>
/// When called on a secondary database, remove the key/data pair from
/// the primary database and all secondary indices.
/// </para>
/// <para>
/// If <paramref name="txn"/> is null and the operation occurs in a
/// transactional database, the operation will be implicitly transaction
/// protected.
/// </para>
/// </remarks>
/// <param name="key">
/// Discard the key/data pair associated with <paramref name="key"/>.
/// </param>
/// <param name="txn">
/// If the operation is part of an application-specified transaction,
/// <paramref name="txn"/> is a Transaction object returned from
/// <see cref="DatabaseEnvironment.BeginTransaction"/>; if
/// the operation is part of a Berkeley DB Concurrent Data Store group,
/// <paramref name="txn"/> is a handle returned from
/// <see cref="DatabaseEnvironment.BeginCDSGroup"/>; otherwise null.
/// </param>
/// <exception cref="NotFoundException">
/// A NotFoundException is thrown if <paramref name="key"/> is not in
/// the database.
/// </exception>
/// <exception cref="KeyEmptyException">
/// A KeyEmptyException is thrown if the database is a
/// <see cref="QueueDatabase"/> or <see cref="RecnoDatabase"/>
/// database and <paramref name="key"/> exists, but was never explicitly
/// created by the application or was later deleted.
/// </exception>
public void Delete(DatabaseEntry key, Transaction txn) {
db.del(Transaction.getDB_TXN(txn), key, 0);
}
/// <summary>
/// Check whether <paramref name="key"/> appears in the database.
/// </summary>
/// <remarks>
/// If the operation occurs in a transactional database, the operation
/// will be implicitly transaction protected.
/// </remarks>
/// <param name="key">The key to search for.</param>
/// <exception cref="NotFoundException">
/// A NotFoundException is thrown if <paramref name="key"/> is not in
/// the database.
/// </exception>
/// <exception cref="KeyEmptyException">
/// A KeyEmptyException is thrown if the database is a
/// <see cref="QueueDatabase"/> or <see cref="RecnoDatabase"/>
/// database and <paramref name="key"/> exists, but was never explicitly
/// created by the application or was later deleted.
/// </exception>
/// <returns>
/// True if <paramref name="key"/> appears in the database, false
/// otherwise.
/// </returns>
public bool Exists(DatabaseEntry key) {
return Exists(key, null, null);
}
/// <summary>
/// Check whether <paramref name="key"/> appears in the database.
/// </summary>
/// <remarks>
/// If <paramref name="txn"/> is null and the operation occurs in a
/// transactional database, the operation will be implicitly transaction
/// protected.
/// </remarks>
/// <param name="key">The key to search for.</param>
/// <param name="txn">
/// If the operation is part of an application-specified transaction,
/// <paramref name="txn"/> is a Transaction object returned from
/// <see cref="DatabaseEnvironment.BeginTransaction"/>; if
/// the operation is part of a Berkeley DB Concurrent Data Store group,
/// <paramref name="txn"/> is a handle returned from
/// <see cref="DatabaseEnvironment.BeginCDSGroup"/>; otherwise null.
/// </param>
/// <exception cref="NotFoundException">
/// A NotFoundException is thrown if <paramref name="key"/> is not in
/// the database.
/// </exception>
/// <exception cref="KeyEmptyException">
/// A KeyEmptyException is thrown if the database is a
/// <see cref="QueueDatabase"/> or <see cref="RecnoDatabase"/>
/// database and <paramref name="key"/> exists, but was never explicitly
/// created by the application or was later deleted.
/// </exception>
/// <returns>
/// True if <paramref name="key"/> appears in the database, false
/// otherwise.
/// </returns>
public bool Exists(DatabaseEntry key, Transaction txn) {
return Exists(key, txn, null);
}
/// <summary>
/// Check whether <paramref name="key"/> appears in the database.
/// </summary>
/// <remarks>
/// If <paramref name="txn"/> is null and the operation occurs in a
/// transactional database, the operation will be implicitly transaction
/// protected.
/// </remarks>
/// <param name="key">The key to search for.</param>
/// <param name="txn">
/// If the operation is part of an application-specified transaction,
/// <paramref name="txn"/> is a Transaction object returned from
/// <see cref="DatabaseEnvironment.BeginTransaction"/>; if
/// the operation is part of a Berkeley DB Concurrent Data Store group,
/// <paramref name="txn"/> is a handle returned from
/// <see cref="DatabaseEnvironment.BeginCDSGroup"/>; otherwise null.
/// </param>
/// <param name="info">The locking behavior to use.</param>
/// <exception cref="NotFoundException">
/// A NotFoundException is thrown if <paramref name="key"/> is not in
/// the database.
/// </exception>
/// <exception cref="KeyEmptyException">
/// A KeyEmptyException is thrown if the database is a
/// <see cref="QueueDatabase"/> or <see cref="RecnoDatabase"/>
/// database and <paramref name="key"/> exists, but was never explicitly
/// created by the application or was later deleted.
/// </exception>
/// <returns>
/// True if <paramref name="key"/> appears in the database, false
/// otherwise.
/// </returns>
public bool Exists(
DatabaseEntry key, Transaction txn, LockingInfo info) {
/*
* If the library call does not throw an exception the key exists.
* If the exception is NotFound the key does not exist and we
* should return false. Any other exception should get passed
* along.
*/
try {
db.exists(Transaction.getDB_TXN(txn),
key, (info == null) ? 0 : info.flags);
return true;
} catch (NotFoundException) {
return false;
}
}
/// <summary>
/// Retrieve a key/data pair from the database. In the presence of
/// duplicate key values, Get will return the first data item for
/// <paramref name="key"/>.
/// </summary>
/// <remarks>
/// If the operation occurs in a transactional database, the operation
/// will be implicitly transaction protected.
/// </remarks>
/// <param name="key">The key to search for</param>
/// <exception cref="NotFoundException">
/// A NotFoundException is thrown if <paramref name="key"/> is not in
/// the database.
/// </exception>
/// <exception cref="KeyEmptyException">
/// A KeyEmptyException is thrown if the database is a
/// <see cref="QueueDatabase"/> or <see cref="RecnoDatabase"/>
/// database and <paramref name="key"/> exists, but was never explicitly
/// created by the application or was later deleted.
/// </exception>
/// <returns>
/// A <see cref="KeyValuePair{T,T}"/> whose Key
/// parameter is <paramref name="key"/> and whose Value parameter is the
/// retrieved data.
/// </returns>
public
KeyValuePair<DatabaseEntry, DatabaseEntry> Get(DatabaseEntry key) {
return Get(key, null, null);
}
/// <summary>
/// Retrieve a key/data pair from the database. In the presence of
/// duplicate key values, Get will return the first data item for
/// <paramref name="key"/>.
/// </summary>
/// <remarks>
/// If <paramref name="txn"/> is null and the operation occurs in a
/// transactional database, the operation will be implicitly transaction
/// protected.
/// </remarks>
/// <param name="key">The key to search for</param>
/// <param name="txn">
/// <paramref name="txn"/> is a Transaction object returned from
/// <see cref="DatabaseEnvironment.BeginTransaction"/>; if
/// the operation is part of a Berkeley DB Concurrent Data Store group,
/// <paramref name="txn"/> is a handle returned from
/// <see cref="DatabaseEnvironment.BeginCDSGroup"/>; otherwise null.
/// </param>
/// <exception cref="NotFoundException">
/// A NotFoundException is thrown if <paramref name="key"/> is not in
/// the database.
/// </exception>
/// <exception cref="KeyEmptyException">
/// A KeyEmptyException is thrown if the database is a
/// <see cref="QueueDatabase"/> or <see cref="RecnoDatabase"/>
/// database and <paramref name="key"/> exists, but was never explicitly
/// created by the application or was later deleted.
/// </exception>
/// <returns>
/// A <see cref="KeyValuePair{T,T}"/> whose Key
/// parameter is <paramref name="key"/> and whose Value parameter is the
/// retrieved data.
/// </returns>
public KeyValuePair<DatabaseEntry, DatabaseEntry> Get(
DatabaseEntry key, Transaction txn) {
return Get(key, txn, null);
}
/// <summary>
/// Retrieve a key/data pair from the database. In the presence of
/// duplicate key values, Get will return the first data item for
/// <paramref name="key"/>.
/// </summary>
/// <remarks>
/// If <paramref name="txn"/> is null and the operation occurs in a
/// transactional database, the operation will be implicitly transaction
/// protected.
/// </remarks>
/// <param name="key">The key to search for</param>
/// <param name="txn">
/// <paramref name="txn"/> is a Transaction object returned from
/// <see cref="DatabaseEnvironment.BeginTransaction"/>; if
/// the operation is part of a Berkeley DB Concurrent Data Store group,
/// <paramref name="txn"/> is a handle returned from
/// <see cref="DatabaseEnvironment.BeginCDSGroup"/>; otherwise null.
/// </param>
/// <param name="info">The locking behavior to use.</param>
/// <exception cref="NotFoundException">
/// A NotFoundException is thrown if <paramref name="key"/> is not in
/// the database.
/// </exception>
/// <exception cref="KeyEmptyException">
/// A KeyEmptyException is thrown if the database is a
/// <see cref="QueueDatabase"/> or <see cref="RecnoDatabase"/>
/// database and <paramref name="key"/> exists, but was never explicitly
/// created by the application or was later deleted.
/// </exception>
/// <returns>
/// A <see cref="KeyValuePair{T,T}"/> whose Key
/// parameter is <paramref name="key"/> and whose Value parameter is the
/// retrieved data.
/// </returns>
public KeyValuePair<DatabaseEntry, DatabaseEntry> Get(
DatabaseEntry key, Transaction txn, LockingInfo info) {
return Get(key, null, txn, info, 0);
}
/// <summary>
/// Protected method to retrieve data from the underlying DB handle.
/// </summary>
/// <param name="key">
/// The key to search for. If null a new DatabaseEntry is created.
/// </param>
/// <param name="data">
/// The data to search for. If null a new DatabaseEntry is created.
/// </param>
/// <param name="txn">The txn for this operation.</param>
/// <param name="info">Locking info for this operation.</param>
/// <param name="flags">
/// Flags value specifying which type of get to perform. Passed
/// directly to DB->get().
/// </param>
/// <returns>
/// A <see cref="KeyValuePair{T,T}"/> whose Key
/// parameter is <paramref name="key"/> and whose Value parameter is the
/// retrieved data.
/// </returns>
protected KeyValuePair<DatabaseEntry, DatabaseEntry> Get(
DatabaseEntry key,
DatabaseEntry data, Transaction txn, LockingInfo info, uint flags) {
if (key == null)
key = new DatabaseEntry();
if (data == null)
data = new DatabaseEntry();
flags |= info == null ? 0 : info.flags;
db.get(Transaction.getDB_TXN(txn), key, data, flags);
return new KeyValuePair<DatabaseEntry, DatabaseEntry>(key, data);
}
/// <summary>
/// Retrieve a key/data pair from the database which matches
/// <paramref name="key"/> and <paramref name="data"/>.
/// </summary>
/// <remarks>
/// If the operation occurs in a transactional database, the operation
/// will be implicitly transaction protected.
/// </remarks>
/// <param name="key">The key to search for</param>
/// <param name="data">The data to search for</param>
/// <exception cref="NotFoundException">
/// A NotFoundException is thrown if <paramref name="key"/> and
/// <paramref name="data"/> are not in the database.
/// </exception>
/// <exception cref="KeyEmptyException">
/// A KeyEmptyException is thrown if the database is a
/// <see cref="QueueDatabase"/> or <see cref="RecnoDatabase"/>
/// database and <paramref name="key"/> exists, but was never explicitly
/// created by the application or was later deleted.
/// </exception>
/// <returns>
/// A <see cref="KeyValuePair{T,T}"/> whose Key
/// parameter is <paramref name="key"/> and whose Value parameter is
/// <paramref name="data"/>.
/// </returns>
public KeyValuePair<DatabaseEntry, DatabaseEntry> GetBoth(
DatabaseEntry key, DatabaseEntry data) {
return GetBoth(key, data, null, null);
}
/// <summary>
/// Retrieve a key/data pair from the database which matches
/// <paramref name="key"/> and <paramref name="data"/>.
/// </summary>
/// <remarks>
/// If <paramref name="txn"/> is null and the operation occurs in a
/// transactional database, the operation will be implicitly transaction
/// protected.
/// </remarks>
/// <param name="key">The key to search for</param>
/// <param name="data">The data to search for</param>
/// <param name="txn">
/// <paramref name="txn"/> is a Transaction object returned from
/// <see cref="DatabaseEnvironment.BeginTransaction"/>; if
/// the operation is part of a Berkeley DB Concurrent Data Store group,
/// <paramref name="txn"/> is a handle returned from
/// <see cref="DatabaseEnvironment.BeginCDSGroup"/>; otherwise null.
/// </param>
/// <exception cref="NotFoundException">
/// A NotFoundException is thrown if <paramref name="key"/> and
/// <paramref name="data"/> are not in the database.
/// </exception>
/// <exception cref="KeyEmptyException">
/// A KeyEmptyException is thrown if the database is a
/// <see cref="QueueDatabase"/> or <see cref="RecnoDatabase"/>
/// database and <paramref name="key"/> exists, but was never explicitly
/// created by the application or was later deleted.
/// </exception>
/// <returns>
/// A <see cref="KeyValuePair{T,T}"/> whose Key
/// parameter is <paramref name="key"/> and whose Value parameter is
/// <paramref name="data"/>.
/// </returns>
public KeyValuePair<DatabaseEntry, DatabaseEntry> GetBoth(
DatabaseEntry key, DatabaseEntry data, Transaction txn) {
return GetBoth(key, data, txn, null);
}
/// <summary>
/// Retrieve a key/data pair from the database which matches
/// <paramref name="key"/> and <paramref name="data"/>.
/// </summary>
/// <remarks>
/// If <paramref name="txn"/> is null and the operation occurs in a
/// transactional database, the operation will be implicitly transaction
/// protected.
/// </remarks>
/// <param name="key">The key to search for</param>
/// <param name="data">The data to search for</param>
/// <param name="txn">
/// <paramref name="txn"/> is a Transaction object returned from
/// <see cref="DatabaseEnvironment.BeginTransaction"/>; if
/// the operation is part of a Berkeley DB Concurrent Data Store group,
/// <paramref name="txn"/> is a handle returned from
/// <see cref="DatabaseEnvironment.BeginCDSGroup"/>; otherwise null.
/// </param>
/// <param name="info">The locking behavior to use.</param>
/// <exception cref="NotFoundException">
/// A NotFoundException is thrown if <paramref name="key"/> and
/// <paramref name="data"/> are not in the database.
/// </exception>
/// <exception cref="KeyEmptyException">
/// A KeyEmptyException is thrown if the database is a
/// <see cref="QueueDatabase"/> or <see cref="RecnoDatabase"/>
/// database and <paramref name="key"/> exists, but was never explicitly
/// created by the application or was later deleted.
/// </exception>
/// <returns>
/// A <see cref="KeyValuePair{T,T}"/> whose Key
/// parameter is <paramref name="key"/> and whose Value parameter is
/// <paramref name="data"/>.
/// </returns>
public KeyValuePair<DatabaseEntry, DatabaseEntry> GetBoth(
DatabaseEntry key,
DatabaseEntry data, Transaction txn, LockingInfo info) {
return Get(key, data, txn, info, DbConstants.DB_GET_BOTH);
}
/// <summary>
/// Display the database statistical information which does not require
/// traversal of the database.
/// </summary>
/// <remarks>
/// Among other things, this method makes it possible for applications
/// to request key and record counts without incurring the performance
/// penalty of traversing the entire database.
/// </remarks>
/// <overloads>
/// The statistical information is described by the
/// <see cref="BTreeStats"/>, <see cref="HashStats"/>,
/// <see cref="QueueStats"/>, and <see cref="RecnoStats"/> classes.
/// </overloads>
public void PrintFastStats() {
PrintStats(false, true);
}
/// <summary>
/// Display the database statistical information which does not require
/// traversal of the database.
/// </summary>
/// <remarks>
/// Among other things, this method makes it possible for applications
/// to request key and record counts without incurring the performance
/// penalty of traversing the entire database.
/// </remarks>
/// <param name="PrintAll">
/// If true, display all available information.
/// </param>
public void PrintFastStats(bool PrintAll) {
PrintStats(PrintAll, true);
}
/// <summary>
/// Display the database statistical information.
/// </summary>
/// <overloads>
/// The statistical information is described by the
/// <see cref="BTreeStats"/>, <see cref="HashStats"/>,
/// <see cref="QueueStats"/>, and <see cref="RecnoStats"/> classes.
/// </overloads>
public void PrintStats() {
PrintStats(false, false);
}
/// <summary>
/// Display the database statistical information.
/// </summary>
/// <param name="PrintAll">
/// If true, display all available information.
/// </param>
public void PrintStats(bool PrintAll) {
PrintStats(PrintAll, false);
}
private void PrintStats(bool all, bool fast) {
uint flags = 0;
flags |= all ? DbConstants.DB_STAT_ALL : 0;
flags |= fast ? DbConstants.DB_FAST_STAT : 0;
db.stat_print(flags);
}
/// <summary>
/// Remove the underlying file represented by
/// <paramref name="Filename"/>, incidentally removing all of the
/// databases it contained.
/// </summary>
/// <param name="Filename">The file to remove</param>
public static void Remove(string Filename) {
Remove(Filename, null, null);
}
/// <summary>
/// Remove the underlying file represented by
/// <paramref name="Filename"/>, incidentally removing all of the
/// databases it contained.
/// </summary>
/// <param name="Filename">The file to remove</param>
/// <param name="DbEnv">
/// The DatabaseEnvironment the database belongs to
/// </param>
public static void Remove(string Filename, DatabaseEnvironment DbEnv) {
Remove(Filename, null, DbEnv);
}
/// <summary>
/// Remove the database specified by <paramref name="Filename"/> and
/// <paramref name="DatabaseName"/>.
/// </summary>
/// <param name="Filename">The file to remove</param>
/// <param name="DatabaseName">The database to remove</param>
public static void Remove(string Filename, string DatabaseName) {
Remove(Filename, DatabaseName, null);
}
/// <summary>
/// Remove the database specified by <paramref name="Filename"/> and
/// <paramref name="DatabaseName"/>.
/// </summary>
/// <overloads>
/// <para>
/// Applications should never remove databases with open DB handles, or
/// in the case of removing a file, when any database in the file has an
/// open handle. For example, some architectures do not permit the
/// removal of files with open system handles. On these architectures,
/// attempts to remove databases currently in use by any thread of
/// control in the system may fail.
/// </para>
/// <para>
/// Remove should not be called if the remove is intended to be
/// transactionally safe;
/// <see cref="DatabaseEnvironment.RemoveDB"/> should be
/// used instead.
/// </para>
/// </overloads>
/// <param name="Filename">The file to remove</param>
/// <param name="DatabaseName">The database to remove</param>
/// <param name="DbEnv">
/// The DatabaseEnvironment the database belongs to
/// </param>
public static void Remove(
string Filename, string DatabaseName, DatabaseEnvironment DbEnv) {
BaseDatabase db = new BaseDatabase(DbEnv, 0);
db.db.remove(Filename, DatabaseName, 0);
}
/// <summary>
/// Rename the underlying file represented by
/// <paramref name="Filename"/>, incidentally renaming all of the
/// databases it contained.
/// </summary>
/// <param name="Filename">The file to rename</param>
/// <param name="NewName">The new filename</param>
public static void Rename(string Filename, string NewName) {
Rename(Filename, null, NewName, null);
}
/// <summary>
/// Rename the underlying file represented by
/// <paramref name="Filename"/>, incidentally renaming all of the
/// databases it contained.
/// </summary>
/// <param name="Filename">The file to rename</param>
/// <param name="NewName">The new filename</param>
/// <param name="DbEnv">
/// The DatabaseEnvironment the database belongs to
/// </param>
public static void Rename(
string Filename, string NewName, DatabaseEnvironment DbEnv) {
Rename(Filename, null, NewName, DbEnv);
}
/// <summary>
/// Rename the database specified by <paramref name="Filename"/> and
/// <paramref name="DatabaseName"/>.
/// </summary>
/// <param name="Filename">The file to rename</param>
/// <param name="DatabaseName">The database to rename</param>
/// <param name="NewName">The new database name</param>
public static void Rename(
string Filename, string DatabaseName, string NewName) {
Rename(Filename, DatabaseName, NewName, null);
}
/// <summary>
/// Rename the database specified by <paramref name="Filename"/> and
/// <paramref name="DatabaseName"/>.
/// </summary>
/// <overloads>
/// <para>
/// Applications should not rename databases that are currently in use.
/// If an underlying file is being renamed and logging is currently
/// enabled in the database environment, no database in the file may be
/// open when Rename is called. In particular, some architectures do not
/// permit renaming files with open handles. On these architectures,
/// attempts to rename databases that are currently in use by any thread
/// of control in the system may fail.
/// </para>
/// <para>
/// Rename should not be called if the rename is intended to be
/// transactionally safe;
/// <see cref="DatabaseEnvironment.RenameDB"/> should be
/// used instead.
/// </para>
/// </overloads>
/// <param name="Filename">The file to rename</param>
/// <param name="DatabaseName">The database to rename</param>
/// <param name="NewName">The new database name</param>
/// <param name="DbEnv">
/// The DatabaseEnvironment the database belongs to
/// </param>
public static void Rename(string Filename,
string DatabaseName, string NewName, DatabaseEnvironment DbEnv) {
BaseDatabase db = new BaseDatabase(DbEnv, 0);
db.db.rename(Filename, DatabaseName, NewName, 0);
}
/// <summary>
/// Flush any cached information to disk.
/// </summary>
/// <remarks>
/// <para>
/// If the database is in memory only, Sync has no effect and will
/// always succeed.
/// </para>
/// <para>
/// It is important to understand that flushing cached information to
/// disk only minimizes the window of opportunity for corrupted data.
/// Although unlikely, it is possible for database corruption to happen
/// if a system or application crash occurs while writing data to the
/// database. To ensure that database corruption never occurs,
/// applications must either: use transactions and logging with
/// automatic recovery or edit a copy of the database, and once all
/// applications using the database have successfully called
/// <see cref="BaseDatabase.Close"/>, atomically replace
/// the original database with the updated copy.
/// </para>
/// </remarks>
public void Sync() {
db.sync(0);
}
/// <summary>
/// Empty the database, discarding all records it contains.
/// </summary>
/// <remarks>
/// If the operation occurs in a transactional database, the operation
/// will be implicitly transaction protected.
/// </remarks>
/// <overloads>
/// When called on a database configured with secondary indices,
/// Truncate will truncate the primary database and all secondary
/// indices. A count of the records discarded from the primary database
/// is returned.
/// </overloads>
/// <returns>
/// The number of records discarded from the database.
///</returns>
public uint Truncate() {
return Truncate(null);
}
/// <summary>
/// Empty the database, discarding all records it contains.
/// </summary>
/// <remarks>
/// If <paramref name="txn"/> is null and the operation occurs in a
/// transactional database, the operation will be implicitly transaction
/// protected.
/// </remarks>
/// <param name="txn">
/// <paramref name="txn"/> is a Transaction object returned from
/// <see cref="DatabaseEnvironment.BeginTransaction"/>; if
/// the operation is part of a Berkeley DB Concurrent Data Store group,
/// <paramref name="txn"/> is a handle returned from
/// <see cref="DatabaseEnvironment.BeginCDSGroup"/>; otherwise null.
/// </param>
/// <returns>
/// The number of records discarded from the database.
///</returns>
public uint Truncate(Transaction txn) {
uint countp = 0;
db.truncate(Transaction.getDB_TXN(txn), ref countp, 0);
return countp;
}
#endregion Methods
/// <summary>
/// Release the resources held by this object, and close the database if
/// it's still open.
/// </summary>
public void Dispose() {
if (isOpen)
this.Close();
if (db != null)
this.db.Dispose();
GC.SuppressFinalize(this);
}
}
}