File indexing completed on 2024-12-01 04:19:15

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