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 <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_INDEXSCHEMA_H
0021 #define KDB_INDEXSCHEMA_H
0022 
0023 #include <QSet>
0024 
0025 #include "KDbObject.h"
0026 #include "KDbFieldList.h"
0027 
0028 class KDbConnection;
0029 class KDbTableSchema;
0030 class KDbQuerySchema;
0031 class KDbRelationship;
0032 
0033 /*! @short Provides information about database index that can be created for a database table.
0034 
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();
0048 
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;
0054 
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);
0061 
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();
0066 
0067     /*! @return table that index is defined for, const version. */
0068     const KDbTableSchema* table() const;
0069 
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;
0076 
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;
0081 
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.
0088 
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);
0094 
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.
0099 
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);
0104 
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.
0110 
0111       Any newly created KDbIndexSchema object
0112       has this flag set to false.
0113 
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;
0121 
0122     /*! @return true if this index is primary key of its table.
0123       This can be one or multifield. */
0124     bool isPrimaryKey() const;
0125 
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);
0130 
0131     /*! @return true if this is unique index.
0132      This can be one or multifield. */
0133     bool isUnique() const;
0134 
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);
0140 
0141     /*! @return true if the index defines a foreign key,
0142      Created implicity for KDbRelationship object.*/
0143     bool isForeignKey() const;
0144 
0145 protected:
0146     //! Used by KDbTableSchema::copyIndex(const KDbIndexSchema&)
0147     KDbIndexSchema(const KDbIndexSchema& index, KDbTableSchema* parentTable);
0148 
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);
0153 
0154     /*! Sets auto-generated flag. This method should be called only
0155      from KDbTableSchema code
0156     @see isAutoGenerated(). */
0157     void setAutoGenerated(bool set);
0158 
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);
0165 
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);
0169 
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 };
0179 
0180 //! Sends information about index schema @a index to debug output @a dbg.
0181 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbIndexSchema& index);
0182 
0183 #endif