File indexing completed on 2024-10-27 10:38:06
0001 /* This file is part of the KDE project 0002 Copyright (C) 2003 Joseph Wenninger <jowenn@kde.org> 0003 Copyright (C) 2003-2016 Jarosław Staniek <staniek@kde.org> 0004 0005 This library is free software; you can redistribute it and/or 0006 modify it under the terms of the GNU Library General Public 0007 License as published by the Free Software Foundation; either 0008 version 2 of the License, or (at your option) any later version. 0009 0010 This library is distributed in the hope that it will be useful, 0011 but WITHOUT ANY WARRANTY; without even the implied warranty of 0012 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 0013 Library General Public License for more details. 0014 0015 You should have received a copy of the GNU Library General Public License 0016 along with this library; see the file COPYING.LIB. If not, write to 0017 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, 0018 * Boston, MA 02110-1301, USA. 0019 */ 0020 0021 #ifndef KDB_TABLESCHEMA_H 0022 #define KDB_TABLESCHEMA_H 0023 0024 #include <QString> 0025 #include <QVector> 0026 0027 #include "KDbFieldList.h" 0028 #include "KDbIndexSchema.h" 0029 0030 class KDbConnection; 0031 class KDbLookupFieldSchema; 0032 class KDbFieldPrivate; 0033 0034 /*! Provides information about native database table 0035 that can be stored using KDb database engine. 0036 */ 0037 class KDB_EXPORT KDbTableSchema : public KDbFieldList, public KDbObject 0038 { 0039 public: 0040 explicit KDbTableSchema(const QString& name); 0041 explicit KDbTableSchema(const KDbObject& object); 0042 KDbTableSchema(); 0043 0044 /*! Copy constructor. 0045 If @a copyId is true, it's copied as well, otherwise the table id becomes -1, 0046 what is usable when we want to store the copy as an independent table. */ 0047 explicit KDbTableSchema(const KDbTableSchema& ts, bool copyId); 0048 0049 /*! Copy constructor like @ref KDbTableSchema(const KDbTableSchema&, bool). 0050 @a id is set as the table identifier. This is rarely usable, e.g. 0051 in project and data migration routines when we need to need deal with unique identifiers; 0052 @see KexiMigrate::performImport(). */ 0053 KDbTableSchema(const KDbTableSchema& ts, int id); 0054 0055 ~KDbTableSchema() override; 0056 0057 /*! Inserts @a field into a specified position (@a index). 0058 'order' property of @a field is set automatically. 0059 @c false is returned if @a field is @c nullptr or @a index is invalid. */ 0060 bool insertField(int index, KDbField *field) override; 0061 0062 /*! Reimplemented for internal reasons. */ 0063 bool removeField(KDbField *field) override; 0064 0065 /*! @return list of fields that are primary key of this table. 0066 This method never returns @c nullptr value, 0067 if there is no primary key, empty KDbIndexSchema object is returned. 0068 KDbIndexSchema object is owned by the table schema. */ 0069 KDbIndexSchema* primaryKey(); 0070 0071 //! @overload KDbIndexSchema* primaryKey() 0072 const KDbIndexSchema* primaryKey() const; 0073 0074 /*! Sets table's primary key index to @a pkey. 0075 Pass pkey as @c nullptr to unassign existing primary key. In this case "primary" 0076 property of previous primary key KDbIndexSchema object that will be cleared, 0077 making it an ordinary index. 0078 0079 If this table already has primary key assigned, it is unassigned using setPrimaryKey(nullptr). 0080 0081 Before assigning as primary key, you should add the index to indices list 0082 with addIndex() (this is not done automatically!). 0083 */ 0084 void setPrimaryKey(KDbIndexSchema *pkey); 0085 0086 const QList<KDbIndexSchema*>::ConstIterator indicesIterator() const; 0087 0088 const QList<KDbIndexSchema*>* indices() const; 0089 0090 //! Adds index @a index to this table schema 0091 //! Ownership of the index is transferred to the table schema. 0092 //! @return true on success 0093 //! @since 3.1 0094 bool addIndex(KDbIndexSchema *index); 0095 0096 //! Removes index @a index from this table schema 0097 //! Ownership of the index is transferred to the table schema. 0098 //! @return true on success 0099 //! @since 3.1 0100 bool removeIndex(KDbIndexSchema *index); 0101 0102 /*! Creates a copy of index @a index with references moved to fields of this table. 0103 The new index is added to this table schema. 0104 Table fields are taken by name from this table. This way it's possible to copy index 0105 owned by other table and add it to another table, e.g. a copied one. 0106 0107 To copy an index from another table, call: 0108 @code 0109 KDbIndexSchema *originalIndex = anotherTable->indices()->at(...); 0110 KDbIndexSchema *newIndex = table->copyIndex(*originalIndex); 0111 // newIndex is now created and is added to the table 'table' 0112 @endcode 0113 0114 To copy an index within the same table, call: 0115 @code 0116 KDbIndexSchema *originalIndex = table->indices()->at(...); 0117 KDbIndexSchema *newIndex = table->copyIndex(*originalIndex); 0118 // newIndex is now created and is added to the table 0119 @endcode 0120 @since 3.1 0121 @todo All relationships should be also copied 0122 */ 0123 KDbIndexSchema* copyIndexFrom(const KDbIndexSchema& index); 0124 0125 /*! Removes all fields from the list, clears name and all other properties. 0126 @see KDbFieldList::clear() */ 0127 void clear() override; 0128 0129 /*! Sends information about fields of this table schema to debug output @a dbg. */ 0130 QDebug debugFields(QDebug dbg) const; 0131 0132 /*! @return true if this is internal KDb's table. 0133 Internal tables are hidden in applications (if desired) but are available 0134 for schema export/import functionality. 0135 0136 Any internal KDb system table's schema (kexi__*) has 0137 cleared its KDbObject part, e.g. id=-1 for such table, 0138 and no description, caption and so on. This is because 0139 it represents a native database table rather that extended Kexi table. 0140 0141 KDbTableSchema object has this property set to false, KDbInternalTableSchema has it 0142 set to true. */ 0143 bool isInternal() const; 0144 0145 /*! @return query schema object that is defined by "select * from <this_table_name>" 0146 This query schema object is owned by the table schema object. 0147 It is convenient way to get such a query when it is not available otherwise. 0148 Always returns non-0. */ 0149 KDbQuerySchema* query(); 0150 0151 /*! @return any field not being a part of primary key of this table. 0152 If there is no such field, returns @c nullptr. */ 0153 KDbField* anyNonPKField(); 0154 0155 /*! Sets lookup field schema @a lookupFieldSchema for @a fieldName. 0156 Passing @c nullptr @a lookupFieldSchema will remove the previously set lookup field. 0157 @return true if @a lookupFieldSchema has been added, 0158 or false if there is no such field @a fieldName. */ 0159 bool setLookupFieldSchema(const QString& fieldName, KDbLookupFieldSchema *lookupFieldSchema); 0160 0161 /*! @return lookup field schema for @a field. 0162 0 is returned if there is no such field in the table or this field has no lookup schema. 0163 Note that even id non-zero is returned here, you may want to check whether lookup field's 0164 recordSource().name() is empty (if so, the field should behave as there was no lookup field 0165 defined at all). */ 0166 KDbLookupFieldSchema *lookupFieldSchema(const KDbField& field); 0167 0168 //! @overload 0169 const KDbLookupFieldSchema *lookupFieldSchema(const KDbField& field) const; 0170 0171 /*! @overload KDbLookupFieldSchema *KDbTableSchema::lookupFieldSchema( KDbField& field ) const */ 0172 KDbLookupFieldSchema *lookupFieldSchema(const QString& fieldName); 0173 0174 /*! @return list of lookup field schemas for this table. 0175 The order is the same as the order of fields within the table. */ 0176 QVector<KDbLookupFieldSchema*> lookupFields() const; 0177 0178 protected: 0179 /*! Automatically retrieves table schema via connection. */ 0180 explicit KDbTableSchema(KDbConnection *conn, const QString & name = QString()); 0181 0182 /*! @return connection object if table was created/retrieved using a connection, 0183 otherwise @c nullptr. */ 0184 KDbConnection* connection() const; 0185 0186 /*! For KDbConnection. */ 0187 void setConnection(KDbConnection* conn); 0188 0189 private: 0190 //! Used by some ctors. 0191 void init(KDbConnection* conn); 0192 0193 //! Used by some ctors. 0194 void init(const KDbTableSchema& ts, bool copyId); 0195 0196 class Private; 0197 Private * const d; 0198 0199 friend class KDbConnection; 0200 friend class KDbNativeStatementBuilder; 0201 friend class KDbFieldPrivate; 0202 Q_DISABLE_COPY(KDbTableSchema) 0203 }; 0204 0205 /*! Internal table with a name @a name. Rarely used. 0206 Use KDbConnection::createTable() to create a table using this schema. 0207 The table will not be visible as user table. 0208 For example, 'kexi__blobs' table is created this way by Kexi application. */ 0209 class KDB_EXPORT KDbInternalTableSchema : public KDbTableSchema 0210 { 0211 public: 0212 explicit KDbInternalTableSchema(const QString& name); 0213 explicit KDbInternalTableSchema(const KDbTableSchema& ts); 0214 KDbInternalTableSchema(const KDbInternalTableSchema& ts); 0215 ~KDbInternalTableSchema() override; 0216 0217 private: 0218 class Private; 0219 Private * const d; 0220 }; 0221 0222 //! Sends information about table schema @a table to debug output @a dbg. 0223 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbTableSchema& table); 0224 0225 //! Sends information about internal table schema @a table to debug output @a dbg. 0226 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbInternalTableSchema& table); 0227 0228 #endif