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 | |
31 | namespace Xapian { |
32 | |
33 | class Database; |
34 | class WritableDatabase; |
35 | |
36 | /// Database factory functions which determine the database type automatically. |
37 | namespace 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 | */ |
46 | XAPIAN_VISIBILITY_DEFAULT |
47 | Database 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 | */ |
65 | XAPIAN_VISIBILITY_DEFAULT |
66 | WritableDatabase 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. |
72 | namespace 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 | */ |
79 | XAPIAN_VISIBILITY_DEFAULT |
80 | WritableDatabase open(); |
81 | |
82 | } |
83 | #endif |
84 | |
85 | #ifdef XAPIAN_HAS_BRASS_BACKEND |
86 | /// Database factory functions for the brass backend. |
87 | namespace 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 | */ |
93 | XAPIAN_VISIBILITY_DEFAULT |
94 | Database 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 | */ |
114 | XAPIAN_VISIBILITY_DEFAULT |
115 | WritableDatabase |
116 | open(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. |
123 | namespace 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 | */ |
129 | XAPIAN_VISIBILITY_DEFAULT |
130 | Database 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 | */ |
150 | XAPIAN_VISIBILITY_DEFAULT |
151 | WritableDatabase |
152 | open(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. |
159 | namespace 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 | */ |
165 | XAPIAN_VISIBILITY_DEFAULT |
166 | Database 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 | */ |
186 | XAPIAN_VISIBILITY_DEFAULT |
187 | WritableDatabase |
188 | open(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. |
195 | namespace 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 | */ |
216 | XAPIAN_VISIBILITY_DEFAULT |
217 | Database 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 | */ |
237 | XAPIAN_VISIBILITY_DEFAULT |
238 | WritableDatabase 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 | */ |
254 | XAPIAN_VISIBILITY_DEFAULT |
255 | Database 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 | */ |
270 | XAPIAN_VISIBILITY_DEFAULT |
271 | WritableDatabase 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 | |