File indexing completed on 2022-11-23 11:08:52

0001 /* This file is part of the KDE project
0002    Copyright (C) 2003-2016 Jarosław Staniek <>
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.
0009    This library is distributed in the hope that it will be useful,
0010    but WITHOUT ANY WARRANTY; without even the implied warranty of
0012    Library General Public License for more details.
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 */
0020 #ifndef KDB_INDEXSCHEMA_H
0021 #define KDB_INDEXSCHEMA_H
0023 #include <QSet>
0025 #include "KDbObject.h"
0026 #include "KDbFieldList.h"
0028 class KDbConnection;
0029 class KDbTableSchema;
0030 class KDbQuerySchema;
0031 class KDbRelationship;
0033 /*! @short Provides information about database index that can be created for a database table.
0035   KDbIndexSchema object stores information about table fields that
0036   defines this index and additional properties like: whether index is unique
0037   or primary key (requires unique). Single-field index can be also auto generated.
0038 */
0039 class KDB_EXPORT KDbIndexSchema : public KDbFieldList, public KDbObject
0040 {
0041 public:
0042     /*! Constructs empty index schema object that not assigned to any @a table.
0043      KDbTableSchema::addIndex() should be called afterwards, before adding any fields
0044      or attaching relationships.
0045      Any fields added with addField() will not be owned by index but by their table.
0046      */
0047     KDbIndexSchema();
0049     /*! Deletes the index. Referenced KDbField objects are not deleted.
0050      All KDbRelationship objects listed by masterRelationships() are detached from
0051      detail-side indices and then deleted.
0052      KDbRelationship objects listed by detailsRelationships() are not deleted. */
0053     ~KDbIndexSchema() override;
0055     /*! Adds field at the end of field list.
0056      KDbField will not be owned by index. KDbField must belong to a table
0057      specified by a KDbTableSchema::addIndex() call, otherwise field couldn't be added.
0058      @note Do not forget to add the field to a table, because adding it only to
0059      the KDbIndexSchema is not enough. */
0060     virtual bool addField(KDbField *field);
0062     /*! @return table that index belongs to
0063      Index should be assigned to a table using KDbTableSchema::addIndex().
0064      If it is not, table() returns @c nullptr. */
0065     KDbTableSchema* table();
0067     /*! @return table that index is defined for, const version. */
0068     const KDbTableSchema* table() const;
0070     /*! @return list of relationships from the table (of this index),
0071      i.e. any such relationship in which this table is at 'master' side.
0072      See KDbRelationship class documentation for more information.
0073      All objects on this list will be automatically deleted when this KDbIndexSchema
0074      object is deleted. */
0075     QList<const KDbRelationship*> masterRelationships() const;
0077     /*! @return list of relationships to the table (of this index),
0078      i.e. any such relationship in which this table is at 'details' side.
0079      See KDbRelationship class documentation for more information. */
0080     QList<const KDbRelationship*> detailsRelationships() const;
0082     /*! Attaches relationship definition @a rel to this KDbIndexSchema object.
0083      If @a rel relationship has this KDbIndexSchema defined at the master-side,
0084      @a rel is added to the list of master relationships (available with masterRelationships()).
0085      If @a rel relationship has this KDbIndexSchema defined at the details-side,
0086      @a rel is added to the list of details relationships (available with detailsRelationships()).
0087      For the former case, attached @a rel object is now owned by this KDbIndexSchema object.
0089      Note: call detachRelationship() for KDbIndexSchema object that @a rel
0090      was previously attached to, if any.
0091      @note Before using attachRelationship() the index KDbField must already belong to a table
0092      specified by a KDbTableSchema::addIndex() call. */
0093     void attachRelationship(KDbRelationship *rel);
0095     /*! Detaches relationship definition @a rel for this KDbIndexSchema object
0096      from the list of master relationships (available with masterRelationships()),
0097      or from details relationships list, depending for which side of the relationship
0098      is this IndexSchem object assigned.
0100      Note: If @a rel was detached from masterRelationships() list,
0101      this object now has no parent, so it must be attached to other index or deleted.
0102     */
0103     void detachRelationship(KDbRelationship *rel);
0105     /*! @return true if index is auto-generated.
0106       Auto-generated index is one-field index
0107       that was automatically generated
0108       for CREATE TABLE statement when the field has
0109       UNIQUE or PRIMARY KEY constraint enabled.
0111       Any newly created KDbIndexSchema object
0112       has this flag set to false.
0114       This flag is handled internally by KDbTableSchema.
0115       It can be usable for GUI application if we do not
0116       want display implicity/auto generated indices
0117       on the indices list or we if want to show these
0118       indices to the user in a special way.
0119     */
0120     bool isAutoGenerated() const;
0122     /*! @return true if this index is primary key of its table.
0123       This can be one or multifield. */
0124     bool isPrimaryKey() const;
0126     /*! Sets PRIMARY KEY flag. @see isPrimary().
0127      Note: Setting PRIMARY KEY on (true),
0128      UNIQUE flag will be also implicity set. */
0129     void setPrimaryKey(bool set);
0131     /*! @return true if this is unique index.
0132      This can be one or multifield. */
0133     bool isUnique() const;
0135     /*! Sets UNIQUE flag. @see isUnique().
0136      Note: Setting UNIQUE off (false), PRIMARY KEY flag will
0137      be also implicity set off, because this UNIQUE
0138      is the requirement for PRIMARY KEYS. */
0139     void setUnique(bool set);
0141     /*! @return true if the index defines a foreign key,
0142      Created implicity for KDbRelationship object.*/
0143     bool isForeignKey() const;
0145 protected:
0146     //! Used by KDbTableSchema::copyIndex(const KDbIndexSchema&)
0147     KDbIndexSchema(const KDbIndexSchema& index, KDbTableSchema* parentTable);
0149     //! Assigns this index to @a table
0150     //! table() must be @c nullptr and @a table must be not be @a nullptr.
0151     //! @since 3.1
0152     void setTable(KDbTableSchema *table);
0154     /*! Sets auto-generated flag. This method should be called only
0155      from KDbTableSchema code
0156     @see isAutoGenerated(). */
0157     void setAutoGenerated(bool set);
0159     /*! If @a set is true, declares that the index defines a foreign key,
0160      created implicity for KDbRelationship object. Setting this to true, implies
0161      clearing 'primary key', 'unique' and 'auto generated' flags.
0162      If this index contains just single field, it's 'foreign field'
0163      flag will be set to true as well. */
0164     void setForeignKey(bool set);
0166     /*! Internal version of attachRelationship(). If @a ownedByMaster is true,
0167      attached @a rel object will be owned by this index. */
0168     void attachRelationship(KDbRelationship *rel, bool ownedByMaster);
0170     friend class KDbConnection;
0171     friend class KDbTableSchema;
0172     friend class KDbQuerySchema;
0173     friend class KDbRelationship;
0174 private:
0175     class Private;
0176     Private * const d;
0177     Q_DISABLE_COPY(KDbIndexSchema)
0178 };
0180 //! Sends information about index schema @a index to debug output @a dbg.
0181 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbIndexSchema& index);
0183 #endif