xapian-core/include/xapian/dbfactory.h

   1 /** @file dbfactory.h
   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 /** Construct a Database object for read-only access to a remote database
 162  *  accessed via a TCP connection.
 163  *
 164  * Access to the remote database is via a TCP connection to the specified
 165  * host and port.
 166  *
 167  * @param host          hostname to connect to.
 168  * @param port          port number to connect to.
 169  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
 170  *                      for any individual operation on the remote database
 171  *                      then Xapian::NetworkTimeoutError is thrown.  A timeout
 172  *                      of 0 means don't timeout.  (Default is 10000ms, which
 173  *                      is 10 seconds).
 174  * @param connect_timeout       timeout to use when connecting to the server.
 175  *                              If this timeout is exceeded then
 176  *                              Xapian::NetworkTimeoutError is thrown.  A
 177  *                              timeout of 0 means don't timeout.  (Default is
 178  *                              10000ms, which is 10 seconds).
 179  */
 180 XAPIAN_VISIBILITY_DEFAULT
 181 Database open(const std::string &host, unsigned int port, useconds_t timeout = 10000, useconds_t connect_timeout = 10000);
 182
 183 /** Construct a WritableDatabase object for update access to a remote database
 184  *  accessed via a TCP connection.
 185  *
 186  * Access to the remote database is via a TCP connection to the specified
 187  * host and port.
 188  *
 189  * @param host          hostname to connect to.
 190  * @param port          port number to connect to.
 191  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
 192  *                      for any individual operation on the remote database
 193  *                      then Xapian::NetworkTimeoutError is thrown.  (Default
 194  *                      is 0, which means don't timeout).
 195  * @param connect_timeout       timeout to use when connecting to the server.
 196  *                              If this timeout is exceeded then
 197  *                              Xapian::NetworkTimeoutError is thrown.  A
 198  *                              timeout of 0 means don't timeout.  (Default is
 199  *                              10000ms, which is 10 seconds).
 200  */
 201 XAPIAN_VISIBILITY_DEFAULT
 202 WritableDatabase open_writable(const std::string &host, unsigned int port, useconds_t timeout = 0, useconds_t connect_timeout = 10000, int flags = 0);
 203
 204 /** Construct a Database object for read-only access to a remote database
 205  *  accessed via a program.
 206  *
 207  * Access to the remote database is done by running an external program and
 208  * communicating with it on stdin/stdout.
 209  *
 210  * @param program       the external program to run.
 211  * @param args          space-separated list of arguments to pass to program.
 212  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
 213  *                      for any individual operation on the remote database
 214  *                      then Xapian::NetworkTimeoutError is thrown.  A timeout
 215  *                      of 0 means don't timeout.  (Default is 10000ms, which
 216  *                      is 10 seconds).
 217  * @param flags         Xapian::DB_RETRY_LOCK or 0.
 218  */
 219 XAPIAN_VISIBILITY_DEFAULT
 220 Database open(const std::string &program, const std::string &args, useconds_t timeout = 10000);
 221
 222 /** Construct a WritableDatabase object for update access to a remote database
 223  *  accessed via a program.
 224  *
 225  * Access to the remote database is done by running an external program and
 226  * communicating with it on stdin/stdout.
 227  *
 228  * @param program       the external program to run.
 229  * @param args          space-separated list of arguments to pass to program.
 230  * @param timeout       timeout in milliseconds.  If this timeout is exceeded
 231  *                      for any individual operation on the remote database
 232  *                      then Xapian::NetworkTimeoutError is thrown.  (Default
 233  *                      is 0, which means don't timeout).
 234  * @param flags         Xapian::DB_RETRY_LOCK or 0.
 235  */
 236 XAPIAN_VISIBILITY_DEFAULT
 237 WritableDatabase open_writable(const std::string &program, const std::string &args, useconds_t timeout = 0, int flags = 0);
 238
 239 }
 240 #endif
 241
 242 }
 243
 244 #endif /* XAPIAN_INCLUDED_DBFACTORY_H */