xapian-core/include/xapian/dbfactory.h

   1 /** @file
   2  * @brief Factory functions for constructing Database and WritableDatabase objects
   3  */
   4 /* Copyright (C) 2005,2006,2007,2008,2009,2011,2013,2014,2016 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 #if !defined XAPIAN_IN_XAPIAN_H && !defined XAPIAN_LIB_BUILD
  26 # error Never use <xapian/dbfactory.h> directly; include <xapian.h> instead.
  27 #endif
  28
  29 #ifndef _MSC_VER
  30 # include <sys/types.h>
  31 #endif
  32
  33 #include <string>
  34
  35 #include <xapian/constants.h>
  36 #include <xapian/database.h>
  37 #include <xapian/deprecated.h>
  38 #include <xapian/types.h>
  39 #include <xapian/version.h>
  40 #include <xapian/visibility.h>
  41
  42 namespace Xapian {
  43
  44 #ifdef _MSC_VER
  45 typedef unsigned useconds_t;
  46 #endif
  47
  48 /// Database factory functions which determine the database type automatically.
  49 namespace Auto {
  50
  51 /** Construct a Database object for a stub database file.
  52  *
  53  * The stub database file contains serialised parameters for one
  54  * or more databases.
  55  *
  56  * @param file  pathname of the stub database file.
  57  */
  58 XAPIAN_DEPRECATED(Database open_stub(const std::string &file));
  59
  60 inline Database
  61 open_stub(const std::string &file)
  62 {
  63     return Database(file, DB_BACKEND_STUB);
  64 }
  65
  66 /** Construct a WritableDatabase object for a stub database file.
  67  *
  68  *  The stub database file must contain serialised parameters for exactly one
  69  *  database.
  70  *
  71  *  @param file         pathname of the stub database file.
  72  *  @param action       determines handling of existing/non-existing database:
  73  *  - Xapian::DB_CREATE                 fail if database already exist,
  74  *                                      otherwise create new database.
  75  *  - Xapian::DB_CREATE_OR_OPEN         open existing database, or create new
  76  *                                      database if none exists.
  77  *  - Xapian::DB_CREATE_OR_OVERWRITE    overwrite existing database, or create
  78  *                                      new database if none exists.
  79  *  - Xapian::DB_OPEN                   open existing database, failing if none
  80  *                                      exists.
  81  */
  82 XAPIAN_DEPRECATED(WritableDatabase open_stub(const std::string &file, int action));
  83
  84 inline WritableDatabase
  85 open_stub(const std::string &file, int action)
  86 {
  87     return WritableDatabase(file, action|DB_BACKEND_STUB);
  88 }
  89
  90 }
  91
  92 #ifdef XAPIAN_HAS_INMEMORY_BACKEND
  93 /// Database factory functions for the inmemory backend.
  94 namespace InMemory {
  95
  96 /** Construct a WritableDatabase object for a new, empty InMemory database.
  97  *
  98  *  Only a writable InMemory database can be created, since a read-only one
  99  *  would always remain empty.
 100  */
 101 XAPIAN_DEPRECATED(WritableDatabase open());
 102
 103 inline WritableDatabase
 104 open()
 105 {
 106     return WritableDatabase(std::string(), DB_BACKEND_INMEMORY);
 107 }
 108
 109 }
 110 #endif
 111
 112 #ifdef XAPIAN_HAS_CHERT_BACKEND
 113 /// Database factory functions for the chert backend.
 114 namespace Chert {
 115
 116 /** Construct a Database object for read-only access to a Chert database.
 117  *
 118  * @param dir  pathname of the directory containing the database.
 119  */
 120 XAPIAN_DEPRECATED(Database open(const std::string &dir));
 121
 122 inline Database
 123 open(const std::string &dir)
 124 {
 125     return Database(dir, DB_BACKEND_CHERT);
 126 }
 127
 128 /** Construct a Database object for update access to a Chert database.
 129  *
 130  * @param dir           pathname of the directory containing the database.
 131  * @param action        determines handling of existing/non-existing database:
 132  *  - Xapian::DB_CREATE                 fail if database already exist,
 133  *                                      otherwise create new database.
 134  *  - Xapian::DB_CREATE_OR_OPEN         open existing database, or create new
 135  *                                      database if none exists.
 136  *  - Xapian::DB_CREATE_OR_OVERWRITE    overwrite existing database, or create
 137  *                                      new database if none exists.
 138  *  - Xapian::DB_OPEN                   open existing database, failing if none
 139  *                                      exists.
 140  * @param block_size    the Btree blocksize to use (in bytes), which must be a
 141  *                      power of two between 2048 and 65536 (inclusive).  The
 142  *                      default (also used if an invalid value if passed) is
 143  *                      8192 bytes.  This parameter is ignored when opening an
 144  *                      existing database.
 145  */
 146 XAPIAN_DEPRECATED(WritableDatabase open(const std::string &dir, int action, int block_size = 0));
 147
 148 inline WritableDatabase
 149 open(const std::string &dir, int action, int block_size)
 150 {
 151     return WritableDatabase(dir, action|DB_BACKEND_CHERT, block_size);
 152 }
 153
 154 }
 155 #endif
 156
 157 #ifdef XAPIAN_HAS_REMOTE_BACKEND
 158 /// Database factory functions for the remote backend.
 159 namespace Remote {
 160
 161 #if defined __GNUC__ && defined __MINGW32__
 162 // Avoid deprecation warnings about useconds_t on mingw.
 163 # pragma GCC diagnostic push
 164 # pragma GCC diagnostic ignored "-Wdeprecated-declarations"
 165 #endif
 166
 167 /** Construct a Database object for read-only access to a remote database
 168  *  accessed via a TCP connection.
 169  *
 170  * Access to the remote database is via a TCP connection to the specified
 171  * host and port.
 172  *
 173  * @param host          hostname to connect to.
 174  * @param port          port number to connect to.
 175  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
 176  *                      for any individual operation on the remote database
 177  *                      then Xapian::NetworkTimeoutError is thrown.  A timeout
 178  *                      of 0 means don't timeout.  (Default is 10000ms, which
 179  *                      is 10 seconds).
 180  * @param connect_timeout       timeout to use when connecting to the server.
 181  *                              If this timeout is exceeded then
 182  *                              Xapian::NetworkTimeoutError is thrown.  A
 183  *                              timeout of 0 means don't timeout.  (Default is
 184  *                              10000ms, which is 10 seconds).
 185  */
 186 XAPIAN_VISIBILITY_DEFAULT
 187 Database open(const std::string &host, unsigned int port, useconds_t timeout = 10000, useconds_t connect_timeout = 10000);
 188
 189 /** Construct a WritableDatabase object for update access to a remote database
 190  *  accessed via a TCP connection.
 191  *
 192  * Access to the remote database is via a TCP connection to the specified
 193  * host and port.
 194  *
 195  * @param host          hostname to connect to.
 196  * @param port          port number to connect to.
 197  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
 198  *                      for any individual operation on the remote database
 199  *                      then Xapian::NetworkTimeoutError is thrown.  (Default
 200  *                      is 0, which means don't timeout).
 201  * @param connect_timeout       timeout to use when connecting to the server.
 202  *                              If this timeout is exceeded then
 203  *                              Xapian::NetworkTimeoutError is thrown.  A
 204  *                              timeout of 0 means don't timeout.  (Default is
 205  *                              10000ms, which is 10 seconds).
 206  * @param flags         Xapian::DB_RETRY_LOCK or 0.
 207  */
 208 XAPIAN_VISIBILITY_DEFAULT
 209 WritableDatabase open_writable(const std::string &host, unsigned int port, useconds_t timeout = 0, useconds_t connect_timeout = 10000, int flags = 0);
 210
 211 /** Construct a Database object for read-only access to a remote database
 212  *  accessed via a program.
 213  *
 214  * Access to the remote database is done by running an external program and
 215  * communicating with it on stdin/stdout.
 216  *
 217  * @param program       the external program to run.
 218  * @param args          space-separated list of arguments to pass to program.
 219  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
 220  *                      for any individual operation on the remote database
 221  *                      then Xapian::NetworkTimeoutError is thrown.  A timeout
 222  *                      of 0 means don't timeout.  (Default is 10000ms, which
 223  *                      is 10 seconds).
 224  */
 225 XAPIAN_VISIBILITY_DEFAULT
 226 Database open(const std::string &program, const std::string &args, useconds_t timeout = 10000);
 227
 228 /** Construct a WritableDatabase object for update access to a remote database
 229  *  accessed via a program.
 230  *
 231  * Access to the remote database is done by running an external program and
 232  * communicating with it on stdin/stdout.
 233  *
 234  * @param program       the external program to run.
 235  * @param args          space-separated list of arguments to pass to program.
 236  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
 237  *                      for any individual operation on the remote database
 238  *                      then Xapian::NetworkTimeoutError is thrown.  (Default
 239  *                      is 0, which means don't timeout).
 240  * @param flags         Xapian::DB_RETRY_LOCK or 0.
 241  */
 242 XAPIAN_VISIBILITY_DEFAULT
 243 WritableDatabase open_writable(const std::string &program, const std::string &args, useconds_t timeout = 0, int flags = 0);
 244
 245 #if defined __GNUC__ && defined __MINGW32__
 246 # pragma GCC diagnostic pop
 247 #endif
 248
 249 }
 250 #endif
 251
 252 }
 253
 254 #endif /* XAPIAN_INCLUDED_DBFACTORY_H */