1/*-
2 * See the file LICENSE for redistribution information.
3 *
4 * Copyright (c) 2009 Oracle.  All rights reserved.
5 *
6 */
7using System;
8using System.Collections.Generic;
9using System.Text;
10
11namespace BerkeleyDB {
12    /// <summary>
13    /// A class representing configuration parameters for
14    /// <see cref="HashDatabase"/>
15    /// </summary>
16    public class HashDatabaseConfig : DatabaseConfig {
17        /* Fields for db->set_flags() */
18        /// <summary>
19        /// Policy for duplicate data items in the database; that is, insertion
20        /// when the key of the key/data pair being inserted already exists in
21        /// the database will be successful.
22        /// </summary>
23        /// <remarks>
24        /// <para>
25        /// The ordering of duplicates in the database for
26        /// <see cref="DuplicatesPolicy.UNSORTED"/> is determined by the order
27        /// of insertion, unless the ordering is otherwise specified by use of a
28        /// cursor operation or a duplicate sort function. The ordering of
29        /// duplicates in the database for
30        /// <see cref="DuplicatesPolicy.SORTED"/> is determined by the
31        /// duplicate comparison function. If the application does not specify a
32        /// comparison function using
33        /// <see cref="DuplicateCompare"/>, a default lexical
34        /// comparison will be used.
35        /// </para>
36		/// <para>
37        /// <see cref="DuplicatesPolicy.SORTED"/> is preferred to
38        /// <see cref="DuplicatesPolicy.UNSORTED"/> for performance reasons.
39        /// <see cref="DuplicatesPolicy.UNSORTED"/> should only be used by
40        /// applications wanting to order duplicate data items manually.
41        /// </para>
42		/// <para>
43        /// If the database already exists, the value of Duplicates must be the
44        /// same as the existing database or an error will be returned.
45        /// </para>
46		/// </remarks>
47        public DuplicatesPolicy Duplicates;
48        internal new uint flags {
49            get {
50                uint ret = base.flags;
51                ret |= (uint)Duplicates;
52                return ret;
53            }
54        }
55
56        /// <summary>
57        /// The policy for how to handle database creation.
58        /// </summary>
59        /// <remarks>
60        /// If the database does not already exist and
61        /// <see cref="CreatePolicy.NEVER"/> is set,
62        /// <see cref="HashDatabase.Open"/> will fail.
63        /// </remarks>
64        public CreatePolicy Creation;
65        internal new uint openFlags {
66            get {
67                uint flags = base.openFlags;
68                flags |= (uint)Creation;
69                return flags;
70            }
71        }
72
73        /// <summary>
74        /// The Hash key comparison function.
75        /// </summary>
76        /// <remarks>
77        /// <para>
78        /// The comparison function is called whenever it is necessary to
79        /// compare a key specified by the application with a key currently
80        /// stored in the tree.
81        /// </para>
82        /// <para>
83        /// If no comparison function is specified, the keys are compared
84        /// lexically, with shorter keys collating before longer keys.
85        /// </para>
86        /// <para>
87        /// If the database already exists, the comparison function must be the
88        /// same as that historically used to create the database or corruption
89        /// can occur.
90        /// </para>
91        /// </remarks>
92        public EntryComparisonDelegate HashComparison;
93
94        internal bool fillFactorIsSet;
95        private uint ffactor;
96        /// <summary>
97        /// The desired density within the hash table. If no value is specified,
98        /// the fill factor will be selected dynamically as pages are filled.
99        /// </summary>
100        /// <remarks>
101        /// <para>
102        /// The density is an approximation of the number of keys allowed to
103        /// accumulate in any one bucket, determining when the hash table grows
104        /// or shrinks. If you know the average sizes of the keys and data in
105        /// your data set, setting the fill factor can enhance performance. A
106        /// reasonable rule computing fill factor is to set it to the following:
107        /// </para>
108        /// <para>
109        /// (pagesize - 32) / (average_key_size + average_data_size + 8)
110        /// </para>
111        /// <para>
112        /// If the database already exists, this setting will be ignored.
113        /// </para>
114        /// </remarks>
115        public uint FillFactor {
116            get { return ffactor; }
117            set {
118                fillFactorIsSet = true;
119                ffactor = value;
120            }
121        }
122
123        /// <summary>
124        /// A user-defined hash function; if no hash function is specified, a
125        /// default hash function is used.
126        /// </summary>
127        /// <remarks>
128        /// <para>
129        /// Because no hash function performs equally well on all possible data,
130        /// the user may find that the built-in hash function performs poorly
131        /// with a particular data set.
132        /// </para>
133        /// <para>
134        /// If the database already exists, HashFunction must be the same as
135        /// that historically used to create the database or corruption can
136        /// occur.
137        /// </para>
138        /// </remarks>
139        public HashFunctionDelegate HashFunction;
140
141        /// <summary>
142        /// The duplicate data item comparison function.
143        /// </summary>
144        /// <remarks>
145        /// <para>
146        /// The comparison function is called whenever it is necessary to
147        /// compare a data item specified by the application with a data item
148        /// currently stored in the database. Setting DuplicateCompare implies
149        /// setting <see cref="Duplicates"/> to
150        /// <see cref="DuplicatesPolicy.SORTED"/>.
151        /// </para>
152		/// <para>
153        /// If no comparison function is specified, the data items are compared
154        /// lexically, with shorter data items collating before longer data
155        /// items.
156        /// </para>
157		/// <para>
158        /// If the database already exists when <see cref="HashDatabase.Open"/>
159        /// is called, the delegate must be the same as that historically used
160        /// to create the database or corruption can occur.
161        /// </para>
162        /// </remarks>
163        public EntryComparisonDelegate DuplicateCompare;
164
165        internal bool nelemIsSet;
166        private uint nelems;
167        /// <summary>
168        /// An estimate of the final size of the hash table.
169        /// </summary>
170        /// <remarks>
171        /// <para>
172        /// In order for the estimate to be used when creating the database,
173        /// <see cref="FillFactor"/> must also be set. If the estimate or fill
174        /// factor are not set or are set too low, hash tables will still expand
175        /// gracefully as keys are entered, although a slight performance
176        /// degradation may be noticed.
177        /// </para>
178        /// <para>
179        /// If the database already exists, this setting will be ignored.
180        /// </para>
181        /// </remarks>
182        public uint TableSize {
183            get { return nelems; }
184            set {
185                nelemIsSet = true;
186                nelems = value;
187            }
188        }
189
190        /// <summary>
191        /// Instantiate a new HashDatabaseConfig object
192        /// </summary>
193        public HashDatabaseConfig() {
194            Duplicates = DuplicatesPolicy.NONE;
195            HashComparison = null;
196            fillFactorIsSet = false;
197            nelemIsSet = false;
198            Creation = CreatePolicy.NEVER;
199        }
200    }
201}