File indexing completed on 2024-03-24 16:11:15

0001 /* This file is part of the KDE project
0002    Copyright (C) 2003-2018 Jarosław Staniek <staniek@kde.org>
0003 
0004    This library is free software; you can redistribute it and/or
0005    modify it under the terms of the GNU Library General Public
0006    License as published by the Free Software Foundation; either
0007    version 2 of the License, or (at your option) any later version.
0008 
0009    This library is distributed in the hope that it will be useful,
0010    but WITHOUT ANY WARRANTY; without even the implied warranty of
0011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012    Library General Public License for more details.
0013 
0014    You should have received a copy of the GNU Library General Public License
0015    along with this library; see the file COPYING.LIB.  If not, write to
0016    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0017  * Boston, MA 02110-1301, USA.
0018 */
0019 
0020 #ifndef KDB_DRIVERBEHAVIOR_H
0021 #define KDB_DRIVERBEHAVIOR_H
0022 
0023 #include "KDbDriver.h"
0024 #include "KDbUtils.h"
0025 
0026 /**
0027  * @brief Detailed definition of driver's default behavior
0028  *
0029  * This class is mostly interesting for KDb driver developers.
0030  * Defaults can be changed by KDbDriver subclass in constructors.
0031  */
0032 class KDB_EXPORT KDbDriverBehavior
0033 {
0034 public:
0035     explicit KDbDriverBehavior(KDbDriver *driver);
0036 
0037     ~KDbDriverBehavior();
0038 
0039     /*! Features (like transactions, etc.) supported by this driver
0040      (sum of selected  Features enum items).
0041      This member should be filled in driver implementation's constructor
0042      (by default m_features==NoFeatures). */
0043     int features;
0044 
0045     //! real type names for this engine
0046     QVector<QString> typeNames;
0047 
0048     /*! Driver properties (indexed by name), useful for presenting properties to the user.
0049      Contains i18n-ed captions.
0050      In driver implementations available properties can be initialized, for example:
0051      @code
0052         beh->properties.insert("maximum_performance", 1000, SomeClass::tr("Maximum performance"));
0053      @endcode
0054      You do not need to set captions of properties predefined by the KDbDriver superclass,
0055      they will be reused. Predefined properties are set in KDbDriver. */
0056     KDbUtils::PropertySet properties;
0057 
0058     //! "UNSIGNED" by default
0059     QString UNSIGNED_TYPE_KEYWORD;
0060 
0061     //! "AUTO_INCREMENT" by default, used as add-in word to field definition
0062     //! May be also used as full definition if SPECIAL_AUTO_INCREMENT_DEF is true.
0063     QString AUTO_INCREMENT_FIELD_OPTION;
0064 
0065     //! "AUTO_INCREMENT PRIMARY KEY" by default, used as add-in word to field definition
0066     //! May be also used as full definition if SPECIAL_AUTO_INCREMENT_DEF is true.
0067     QString AUTO_INCREMENT_PK_FIELD_OPTION;
0068 
0069     //! "" by default, used as type string for autoinc. field definition
0070     //! pgsql defines it as "SERIAL", sqlite defines it as "INTEGER"
0071     QString AUTO_INCREMENT_TYPE;
0072 
0073     /*! True if autoincrement field has special definition
0074      e.g. like "INTEGER PRIMARY KEY" for SQLite.
0075      Special definition string should be stored in AUTO_INCREMENT_FIELD_OPTION.
0076      False by default. */
0077     bool SPECIAL_AUTO_INCREMENT_DEF;
0078 
0079     /*! True if autoincrement requires field to be declared as primary key.
0080      This is true for SQLite. False by default. */
0081     bool AUTO_INCREMENT_REQUIRES_PK;
0082 
0083     /*! Name of a field (or built-in function) with autoincremented unique value,
0084      typically returned by KDbSqlResult::lastInsertRecordId().
0085 
0086      Examples:
0087      - PostgreSQL and SQLite engines use 'OID' field
0088      - MySQL uses LAST_INSERT_ID() built-in function
0089     */
0090     QString ROW_ID_FIELD_NAME;
0091 
0092     /*! True if the value (fetched from field or function,
0093      defined by ROW_ID_FIELD_NAME member) is EXACTLY the value of autoincremented field,
0094      not an implicit (internal) row number. Default value is false.
0095 
0096      Examples:
0097      - PostgreSQL and SQLite engines have this flag set to false ('OID' field has
0098         it's own implicit value)
0099      - MySQL engine has this flag set to true (LAST_INSERT_ID() returns real value
0100      of last autoincremented field).
0101 
0102      Notes:
0103      If it's false, we have a convenient way for identifying row even when there's
0104      no primary key defined. So, as '_ROWID' column in MySQL is really
0105      just a synonym for the primary key, this engine needs to have primary keys always
0106      defined if we want to use interactive editing features like row updating and deleting.
0107     */
0108     bool ROW_ID_FIELD_RETURNS_LAST_AUTOINCREMENTED_VALUE;
0109 
0110     /*! Name of any (e.g. first found) database for this connection that
0111      typically always exists. This can be not set if we want to do some magic checking
0112      what database name is availabe by reimplementing
0113      KDbConnection::anyAvailableDatabaseName().
0114      Example: for PostgreSQL this is "template1".
0115 
0116      @see KDbConnection::SetAvailableDatabaseName()
0117     */
0118     QString ALWAYS_AVAILABLE_DATABASE_NAME;
0119 
0120     /*! Opening quotation mark used for escaping identifier (see KDbDriver::escapeIdentifier()).
0121      Default value is '"'. Change it for your driver.
0122     */
0123     char OPENING_QUOTATION_MARK_BEGIN_FOR_IDENTIFIER;
0124 
0125     /*! Opening quotation mark used for escaping identifier (see KDbDriver::escapeIdentifier()).
0126      Default value is '"'. Change it for your driver.
0127     */
0128     char CLOSING_QUOTATION_MARK_BEGIN_FOR_IDENTIFIER;
0129 
0130     /*! True if using database is required to perform real connection.
0131      This is true for may engines, e.g. for PostgreSQL, where connection
0132      strings should contain a database name.
0133      If the flag is false, then developer has to call KDbConnection::useDatabase()
0134      after creating the KDbConnection object.
0135      This flag can be also used for file-based db drivers, e.g. SQLite sets it to true.
0136      MySQL sets it to false.
0137      By default this flag is true.
0138     */
0139     bool USING_DATABASE_REQUIRED_TO_CONNECT;
0140 
0141     /*! True if connection should be established (KDbConnection::connect()) in order
0142      to check database existence (KDbConnection::databaseExists()).
0143      This is true for most engines, but not for SQLite (and probably most
0144      file-based databases) where existence of database is checked at filesystem level.
0145      By default this flag is true.
0146     */
0147     bool CONNECTION_REQUIRED_TO_CHECK_DB_EXISTENCE;
0148 
0149     /*! True if connection should be established (KDbConnection::connect()) in order
0150      to create new database (KDbConnection::createDatabase()).
0151      This is true for most engines, but not for SQLite (and probably most
0152      file-based databases) where opening physical connection for nonexisting
0153      file creates new file.
0154      By default this flag is true.
0155     */
0156     bool CONNECTION_REQUIRED_TO_CREATE_DB;
0157 
0158     /*! True if connection should be established (KDbConnection::connect()) in order
0159      to drop database (KDbConnection::dropDatabase()).
0160      This is true for most engines, but not for SQLite (and probably most
0161      file-based databases) where dropping database is performed at filesystem level.
0162      By default this flag is true.
0163     */
0164     bool CONNECTION_REQUIRED_TO_DROP_DB;
0165 
0166     /*! Because some engines need to have opened any database before
0167      executing administrative sql statements like "create database" or "drop database",
0168      using appropriate, existing temporary database for this connection.
0169      This is the case for PostgreSQL.
0170      For file-based db drivers this flag is ignored.
0171      By default this flag is false.
0172 
0173      Note: This method has nothing to do with creating or using temporary databases
0174      in such meaning that these database are not persistent.
0175 
0176      @see KDbConnection::useTemporaryDatabaseIfNeeded()
0177     */
0178     bool USE_TEMPORARY_DATABASE_FOR_CONNECTION_IF_NEEDED;
0179 
0180     /*! Set to @c true in a subclass if after successful drv_createDatabase() the database
0181      is in opened state (as after useDatabase()).
0182      @c false for most engines. */
0183     bool IS_DB_OPEN_AFTER_CREATE;
0184 
0185     /*! True if before we know whether the fetched result of executed query
0186      is empty or not, we need to fetch first record. Particularly, it's true for SQLite.
0187      The flag is used in KDbCursor::open(). By default this flag is false. */
0188     bool _1ST_ROW_READ_AHEAD_REQUIRED_TO_KNOW_IF_THE_RESULT_IS_EMPTY;
0189 
0190     /*! True if "SELECT 1 from (subquery)" is supported. False by default.
0191      Used in KDbConnection::resultExists() for optimization. It's set to true for SQLite driver. */
0192     bool SELECT_1_SUBQUERY_SUPPORTED;
0193 
0194     /*! Literal for boolean true. "1" by default
0195         which is typically expected by backends even while the standard says "TRUE":
0196         https://troels.arvin.dk/db/rdbms/#data_types-boolean
0197     */
0198     QString BOOLEAN_TRUE_LITERAL;
0199 
0200     /*! Literal for boolean false. "0" by default
0201         which is typically expected by backends even while the standard says "TRUE":
0202         https://troels.arvin.dk/db/rdbms/#data_types-boolean
0203     */
0204     QString BOOLEAN_FALSE_LITERAL;
0205 
0206     /*! Specifies maximum length for Text type. If 0, there is are limits and length argument is not needed,
0207      e.g. VARCHAR works for the driver this is the case for SQLite and PostgreSQL.
0208      If greater than 0, this value should be used to express maximum value, e.g. VARCHAR(...).
0209      This is the case for MySQL.
0210      The default is 0. */
0211     int TEXT_TYPE_MAX_LENGTH;
0212 
0213     /*! "LIKE" by default, used to construct native expressions "x LIKE y" and "x NOT LIKE y".
0214      LIKE is case-insensitive for MySQL, SQLite, and often on Sybase/MSSQL
0215      while for PostgreSQL it's case-sensitive. So for PostgreSQL LIKE_OPERATOR == "ILIKE". */
0216     QString LIKE_OPERATOR;
0217 
0218     /*! "RANDOM()" function name, used in Driver::randomFunctionToString() to construct native
0219      expressions. */
0220     QString RANDOM_FUNCTION;
0221 
0222     /**
0223      * SQL statement used to obtain list of physical table names.
0224      * Used by default implementation of KDbConnection::drv_getTableNames(). Empty by default.
0225      * If empty, default implementation of KDbConnection::drv_getTableNames() fails.
0226      *
0227      * @since 3.2
0228      */
0229     KDbEscapedString GET_TABLE_NAMES_SQL;
0230 
0231 private:
0232     void initInternalProperties();
0233     friend class KDbDriver;
0234 
0235     Q_DISABLE_COPY(KDbDriverBehavior)
0236     class Private;
0237     Private * const d;
0238 };
0239 
0240 #endif