1/** \file dbfactory.h
2 * \brief Factory functions for constructing Database and WritableDatabase objects
3 */
4/* Copyright (C) 2005,2006,2007,2008,2009 Olly Betts
5 *
6 * This program is free software; you can redistribute it and/or
7 * modify it under the terms of the GNU General Public License as
8 * published by the Free Software Foundation; either version 2 of the
9 * License, or (at your option) any later version.
10 *
11 * This program is distributed in the hope that it will be useful,
12 * but WITHOUT ANY WARRANTY; without even the implied warranty of
13 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
14 * GNU General Public License for more details.
15 *
16 * You should have received a copy of the GNU General Public License
17 * along with this program; if not, write to the Free Software
18 * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301
19 * USA
20 */
21
22#ifndef XAPIAN_INCLUDED_DBFACTORY_H
23#define XAPIAN_INCLUDED_DBFACTORY_H
24
25#include <string>
26
27#include <xapian/types.h>
28#include <xapian/version.h>
29#include <xapian/visibility.h>
30
31namespace Xapian {
32
33class Database;
34class WritableDatabase;
35
36/// Database factory functions which determine the database type automatically.
37namespace Auto {
38
39/** Construct a Database object for a stub database file.
40 *
41 * The stub database file contains serialised parameters for one
42 * or more databases.
43 *
44 * @param file pathname of the stub database file.
45 */
46XAPIAN_VISIBILITY_DEFAULT
47Database open_stub(const std::string &file);
48
49/** Construct a WritableDatabase object for a stub database file.
50 *
51 * The stub database file must contain serialised parameters for exactly one
52 * database.
53 *
54 * @param file pathname of the stub database file.
55 * @param action determines handling of existing/non-existing database:
56 * - Xapian::DB_CREATE fail if database already exist,
57 * otherwise create new database.
58 * - Xapian::DB_CREATE_OR_OPEN open existing database, or create new
59 * database if none exists.
60 * - Xapian::DB_CREATE_OR_OVERWRITE overwrite existing database, or create
61 * new database if none exists.
62 * - Xapian::DB_OPEN open existing database, failing if none
63 * exists.
64 */
65XAPIAN_VISIBILITY_DEFAULT
66WritableDatabase open_stub(const std::string &file, int action);
67
68}
69
70#ifdef XAPIAN_HAS_INMEMORY_BACKEND
71/// Database factory functions for the inmemory backend.
72namespace InMemory {
73
74/** Construct a WritableDatabase object for a new, empty InMemory database.
75 *
76 * Only a writable InMemory database can be created, since a read-only one
77 * would always remain empty.
78 */
79XAPIAN_VISIBILITY_DEFAULT
80WritableDatabase open();
81
82}
83#endif
84
85#ifdef XAPIAN_HAS_BRASS_BACKEND
86/// Database factory functions for the brass backend.
87namespace Brass {
88
89/** Construct a Database object for read-only access to a Brass database.
90 *
91 * @param dir pathname of the directory containing the database.
92 */
93XAPIAN_VISIBILITY_DEFAULT
94Database open(const std::string &dir);
95
96/** Construct a Database object for update access to a Brass database.
97 *
98 * @param dir pathname of the directory containing the database.
99 * @param action determines handling of existing/non-existing database:
100 * - Xapian::DB_CREATE fail if database already exist,
101 * otherwise create new database.
102 * - Xapian::DB_CREATE_OR_OPEN open existing database, or create new
103 * database if none exists.
104 * - Xapian::DB_CREATE_OR_OVERWRITE overwrite existing database, or create
105 * new database if none exists.
106 * - Xapian::DB_OPEN open existing database, failing if none
107 * exists.
108 * @param block_size the Btree blocksize to use (in bytes), which must be a
109 * power of two between 2048 and 65536 (inclusive). The
110 * default (also used if an invalid value if passed) is
111 * 8192 bytes. This parameter is ignored when opening an
112 * existing database.
113 */
114XAPIAN_VISIBILITY_DEFAULT
115WritableDatabase
116open(const std::string &dir, int action, int block_size = 8192);
117
118}
119#endif
120
121#ifdef XAPIAN_HAS_CHERT_BACKEND
122/// Database factory functions for the chert backend.
123namespace Chert {
124
125/** Construct a Database object for read-only access to a Chert database.
126 *
127 * @param dir pathname of the directory containing the database.
128 */
129XAPIAN_VISIBILITY_DEFAULT
130Database open(const std::string &dir);
131
132/** Construct a Database object for update access to a Chert database.
133 *
134 * @param dir pathname of the directory containing the database.
135 * @param action determines handling of existing/non-existing database:
136 * - Xapian::DB_CREATE fail if database already exist,
137 * otherwise create new database.
138 * - Xapian::DB_CREATE_OR_OPEN open existing database, or create new
139 * database if none exists.
140 * - Xapian::DB_CREATE_OR_OVERWRITE overwrite existing database, or create
141 * new database if none exists.
142 * - Xapian::DB_OPEN open existing database, failing if none
143 * exists.
144 * @param block_size the Btree blocksize to use (in bytes), which must be a
145 * power of two between 2048 and 65536 (inclusive). The
146 * default (also used if an invalid value if passed) is
147 * 8192 bytes. This parameter is ignored when opening an
148 * existing database.
149 */
150XAPIAN_VISIBILITY_DEFAULT
151WritableDatabase
152open(const std::string &dir, int action, int block_size = 8192);
153
154}
155#endif
156
157#ifdef XAPIAN_HAS_FLINT_BACKEND
158/// Database factory functions for the flint backend.
159namespace Flint {
160
161/** Construct a Database object for read-only access to a Flint database.
162 *
163 * @param dir pathname of the directory containing the database.
164 */
165XAPIAN_VISIBILITY_DEFAULT
166Database open(const std::string &dir);
167
168/** Construct a Database object for update access to a Flint database.
169 *
170 * @param dir pathname of the directory containing the database.
171 * @param action determines handling of existing/non-existing database:
172 * - Xapian::DB_CREATE fail if database already exist,
173 * otherwise create new database.
174 * - Xapian::DB_CREATE_OR_OPEN open existing database, or create new
175 * database if none exists.
176 * - Xapian::DB_CREATE_OR_OVERWRITE overwrite existing database, or create
177 * new database if none exists.
178 * - Xapian::DB_OPEN open existing database, failing if none
179 * exists.
180 * @param block_size the Btree blocksize to use (in bytes), which must be a
181 * power of two between 2048 and 65536 (inclusive). The
182 * default (also used if an invalid value if passed) is
183 * 8192 bytes. This parameter is ignored when opening an
184 * existing database.
185 */
186XAPIAN_VISIBILITY_DEFAULT
187WritableDatabase
188open(const std::string &dir, int action, int block_size = 8192);
189
190}
191#endif
192
193#ifdef XAPIAN_HAS_REMOTE_BACKEND
194/// Database factory functions for the remote backend.
195namespace Remote {
196
197/** Construct a Database object for read-only access to a remote database
198 * accessed via a TCP connection.
199 *
200 * Access to the remote database is via a TCP connection to the specified
201 * host and port.
202 *
203 * @param host hostname to connect to.
204 * @param port port number to connect to.
205 * @param timeout timeout in milliseconds. If this timeout is exceeded
206 * for any individual operation on the remote database
207 * then Xapian::NetworkTimeoutError is thrown. A timeout
208 * of 0 means don't timeout. (Default is 10000ms, which
209 * is 10 seconds).
210 * @param connect_timeout timeout to use when connecting to the server.
211 * If this timeout is exceeded then
212 * Xapian::NetworkTimeoutError is thrown. A
213 * timeout of 0 means don't timeout. (Default is
214 * 10000ms, which is 10 seconds).
215 */
216XAPIAN_VISIBILITY_DEFAULT
217Database open(const std::string &host, unsigned int port, Xapian::timeout timeout = 10000, Xapian::timeout connect_timeout = 10000);
218
219/** Construct a WritableDatabase object for update access to a remote database
220 * accessed via a TCP connection.
221 *
222 * Access to the remote database is via a TCP connection to the specified
223 * host and port.
224 *
225 * @param host hostname to connect to.
226 * @param port port number to connect to.
227 * @param timeout timeout in milliseconds. If this timeout is exceeded
228 * for any individual operation on the remote database
229 * then Xapian::NetworkTimeoutError is thrown. (Default
230 * is 0, which means don't timeout).
231 * @param connect_timeout timeout to use when connecting to the server.
232 * If this timeout is exceeded then
233 * Xapian::NetworkTimeoutError is thrown. A
234 * timeout of 0 means don't timeout. (Default is
235 * 10000ms, which is 10 seconds).
236 */
237XAPIAN_VISIBILITY_DEFAULT
238WritableDatabase open_writable(const std::string &host, unsigned int port, Xapian::timeout timeout = 0, Xapian::timeout connect_timeout = 10000);
239
240/** Construct a Database object for read-only access to a remote database
241 * accessed via a program.
242 *
243 * Access to the remote database is done by running an external program and
244 * communicating with it on stdin/stdout.
245 *
246 * @param program the external program to run.
247 * @param args space-separated list of arguments to pass to program.
248 * @param timeout timeout in milliseconds. If this timeout is exceeded
249 * for any individual operation on the remote database
250 * then Xapian::NetworkTimeoutError is thrown. A timeout
251 * of 0 means don't timeout. (Default is 10000ms, which
252 * is 10 seconds).
253 */
254XAPIAN_VISIBILITY_DEFAULT
255Database open(const std::string &program, const std::string &args, Xapian::timeout timeout = 10000);
256
257/** Construct a WritableDatabase object for update access to a remote database
258 * accessed via a program.
259 *
260 * Access to the remote database is done by running an external program and
261 * communicating with it on stdin/stdout.
262 *
263 * @param program the external program to run.
264 * @param args space-separated list of arguments to pass to program.
265 * @param timeout timeout in milliseconds. If this timeout is exceeded
266 * for any individual operation on the remote database
267 * then Xapian::NetworkTimeoutError is thrown. (Default
268 * is 0, which means don't timeout).
269 */
270XAPIAN_VISIBILITY_DEFAULT
271WritableDatabase open_writable(const std::string &program, const std::string &args, Xapian::timeout timeout = 0);
272
273}
274#endif
275
276}
277
278#endif /* XAPIAN_INCLUDED_DBFACTORY_H */
279