text: /*-
   * See the file LICENSE for redistribution information.
   *
   * Copyright (c) 2009 Oracle.  All rights reserved.
   *
   */
  using System;
  using System.Collections.Generic;
  using System.Text;
  
  namespace BerkeleyDB {
      /// <summary>
      /// A class representing configuration parameters for
      /// <see cref="HashDatabase"/>
      /// </summary>
      public class HashDatabaseConfig : DatabaseConfig {
          /* Fields for db->set_flags() */
          /// <summary>
          /// Policy for duplicate data items in the database; that is, insertion
          /// when the key of the key/data pair being inserted already exists in
          /// the database will be successful.
          /// </summary>
          /// <remarks>
          /// <para>
          /// The ordering of duplicates in the database for
          /// <see cref="DuplicatesPolicy.UNSORTED"/> is determined by the order
          /// of insertion, unless the ordering is otherwise specified by use of a
          /// cursor operation or a duplicate sort function. The ordering of
          /// duplicates in the database for
          /// <see cref="DuplicatesPolicy.SORTED"/> is determined by the
          /// duplicate comparison function. If the application does not specify a
          /// comparison function using 
          /// <see cref="DuplicateCompare"/>, a default lexical
          /// comparison will be used.
          /// </para>
  		/// <para>
          /// <see cref="DuplicatesPolicy.SORTED"/> is preferred to 
          /// <see cref="DuplicatesPolicy.UNSORTED"/> for performance reasons.
          /// <see cref="DuplicatesPolicy.UNSORTED"/> should only be used by
          /// applications wanting to order duplicate data items manually.
          /// </para>
  		/// <para>
          /// If the database already exists, the value of Duplicates must be the
          /// same as the existing database or an error will be returned.
          /// </para>
  		/// </remarks>
          public DuplicatesPolicy Duplicates;
          internal new uint flags {
              get {
                  uint ret = base.flags;
                  ret |= (uint)Duplicates;
                  return ret;
              }
          }
  
          /// <summary>
          /// The policy for how to handle database creation.
          /// </summary>
          /// <remarks>
          /// If the database does not already exist and
          /// <see cref="CreatePolicy.NEVER"/> is set,
          /// <see cref="HashDatabase.Open"/> will fail.
          /// </remarks>
          public CreatePolicy Creation;
          internal new uint openFlags {
              get {
                  uint flags = base.openFlags;
                  flags |= (uint)Creation;
                  return flags;
              }
          }
  
          /// <summary>
          /// The Hash key comparison function.
          /// </summary>
          /// <remarks>
          /// <para>
          /// The comparison function is called whenever it is necessary to
          /// compare a key specified by the application with a key currently
          /// stored in the tree.
          /// </para>
          /// <para>
          /// If no comparison function is specified, the keys are compared
          /// lexically, with shorter keys collating before longer keys.
          /// </para>
          /// <para>
          /// If the database already exists, the comparison function must be the
          /// same as that historically used to create the database or corruption
          /// can occur. 
          /// </para>
          /// </remarks>
          public EntryComparisonDelegate HashComparison;
  
          internal bool fillFactorIsSet;
          private uint ffactor;
          /// <summary>
          /// The desired density within the hash table. If no value is specified,
          /// the fill factor will be selected dynamically as pages are filled. 
          /// </summary>
          /// <remarks>
          /// <para>
          /// The density is an approximation of the number of keys allowed to
          /// accumulate in any one bucket, determining when the hash table grows
          /// or shrinks. If you know the average sizes of the keys and data in
          /// your data set, setting the fill factor can enhance performance. A
          /// reasonable rule computing fill factor is to set it to the following:
          /// </para>
          /// <para>
          /// (pagesize - 32) / (average_key_size + average_data_size + 8)
          /// </para>
          /// <para>
          /// If the database already exists, this setting will be ignored.
          /// </para>
          /// </remarks>
          public uint FillFactor {
              get { return ffactor; }
              set {
                  fillFactorIsSet = true;
                  ffactor = value;
              }
          }
  
          /// <summary>
          /// A user-defined hash function; if no hash function is specified, a
          /// default hash function is used. 
          /// </summary>
          /// <remarks>
          /// <para>
          /// Because no hash function performs equally well on all possible data,
          /// the user may find that the built-in hash function performs poorly
          /// with a particular data set.
          /// </para>
          /// <para>
          /// If the database already exists, HashFunction must be the same as
          /// that historically used to create the database or corruption can
          /// occur.
          /// </para>
          /// </remarks>
          public HashFunctionDelegate HashFunction;
  
          /// <summary>
          /// The duplicate data item comparison function.
          /// </summary>
          /// <remarks>
          /// <para>
          /// The comparison function is called whenever it is necessary to
          /// compare a data item specified by the application with a data item
          /// currently stored in the database. Setting DuplicateCompare implies 
          /// setting <see cref="Duplicates"/> to
          /// <see cref="DuplicatesPolicy.SORTED"/>.
          /// </para>
  		/// <para>
          /// If no comparison function is specified, the data items are compared
          /// lexically, with shorter data items collating before longer data
          /// items.
          /// </para>
  		/// <para>
          /// If the database already exists when <see cref="HashDatabase.Open"/>
          /// is called, the delegate must be the same as that historically used
          /// to create the database or corruption can occur.
          /// </para>
          /// </remarks>
          public EntryComparisonDelegate DuplicateCompare;
  
          internal bool nelemIsSet;
          private uint nelems;
          /// <summary>
          /// An estimate of the final size of the hash table.
          /// </summary>
          /// <remarks>
          /// <para>
          /// In order for the estimate to be used when creating the database,
          /// <see cref="FillFactor"/> must also be set. If the estimate or fill
          /// factor are not set or are set too low, hash tables will still expand
          /// gracefully as keys are entered, although a slight performance
          /// degradation may be noticed.
          /// </para>
          /// <para>
          /// If the database already exists, this setting will be ignored.
          /// </para>
          /// </remarks>
          public uint TableSize {
              get { return nelems; }
              set {
                  nelemIsSet = true;
                  nelems = value;
              }
          }
  
          /// <summary>
          /// Instantiate a new HashDatabaseConfig object
          /// </summary>
          public HashDatabaseConfig() {
              Duplicates = DuplicatesPolicy.NONE;
              HashComparison = null;
              fillFactorIsSet = false;
              nelemIsSet = false;
              Creation = CreatePolicy.NEVER;
          }
      }
  }