KDb

KDbTableSchema.h
1/* This file is part of the KDE project
2 Copyright (C) 2003 Joseph Wenninger <jowenn@kde.org>
3 Copyright (C) 2003-2016 Jarosław Staniek <staniek@kde.org>
4
5 This library is free software; you can redistribute it and/or
6 modify it under the terms of the GNU Library General Public
7 License as published by the Free Software Foundation; either
8 version 2 of the License, or (at your option) any later version.
9
10 This library is distributed in the hope that it will be useful,
11 but WITHOUT ANY WARRANTY; without even the implied warranty of
12 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
13 Library General Public License for more details.
14
15 You should have received a copy of the GNU Library General Public License
16 along with this library; see the file COPYING.LIB. If not, write to
17 the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
18 * Boston, MA 02110-1301, USA.
19*/
20
21#ifndef KDB_TABLESCHEMA_H
22#define KDB_TABLESCHEMA_H
23
24#include <QString>
25#include <QVector>
26
27#include "KDbFieldList.h"
28#include "KDbIndexSchema.h"
29
30class KDbConnection;
32class KDbFieldPrivate;
33
34/*! Provides information about native database table
35 that can be stored using KDb database engine.
36*/
37class KDB_EXPORT KDbTableSchema : public KDbFieldList, public KDbObject
38{
39public:
40 explicit KDbTableSchema(const QString& name);
41 explicit KDbTableSchema(const KDbObject& object);
43
44 /*! Copy constructor.
45 If @a copyId is true, it's copied as well, otherwise the table id becomes -1,
46 what is usable when we want to store the copy as an independent table. */
47 explicit KDbTableSchema(const KDbTableSchema& ts, bool copyId);
48
49 /*! Copy constructor like @ref KDbTableSchema(const KDbTableSchema&, bool).
50 @a id is set as the table identifier. This is rarely usable, e.g.
51 in project and data migration routines when we need to need deal with unique identifiers;
52 @see KexiMigrate::performImport(). */
53 KDbTableSchema(const KDbTableSchema& ts, int id);
54
55 ~KDbTableSchema() override;
56
57 /*! Inserts @a field into a specified position (@a index).
58 'order' property of @a field is set automatically.
59 @c false is returned if @a field is @c nullptr or @a index is invalid. */
60 bool insertField(int index, KDbField *field) override;
61
62 /*! Reimplemented for internal reasons. */
63 bool removeField(KDbField *field) override;
64
65 /*! @return list of fields that are primary key of this table.
66 This method never returns @c nullptr value,
67 if there is no primary key, empty KDbIndexSchema object is returned.
68 KDbIndexSchema object is owned by the table schema. */
69 KDbIndexSchema* primaryKey();
70
71 //! @overload KDbIndexSchema* primaryKey()
72 const KDbIndexSchema* primaryKey() const;
73
74 /*! Sets table's primary key index to @a pkey.
75 Pass pkey as @c nullptr to unassign existing primary key. In this case "primary"
76 property of previous primary key KDbIndexSchema object that will be cleared,
77 making it an ordinary index.
78
79 If this table already has primary key assigned, it is unassigned using setPrimaryKey(nullptr).
80
81 Before assigning as primary key, you should add the index to indices list
82 with addIndex() (this is not done automatically!).
83 */
84 void setPrimaryKey(KDbIndexSchema *pkey);
85
86 const QList<KDbIndexSchema*>::ConstIterator indicesIterator() const;
87
88 const QList<KDbIndexSchema*>* indices() const;
89
90 //! Adds index @a index to this table schema
91 //! Ownership of the index is transferred to the table schema.
92 //! @return true on success
93 //! @since 3.1
94 bool addIndex(KDbIndexSchema *index);
95
96 //! Removes index @a index from this table schema
97 //! Ownership of the index is transferred to the table schema.
98 //! @return true on success
99 //! @since 3.1
100 bool removeIndex(KDbIndexSchema *index);
101
102 /*! Creates a copy of index @a index with references moved to fields of this table.
103 The new index is added to this table schema.
104 Table fields are taken by name from this table. This way it's possible to copy index
105 owned by other table and add it to another table, e.g. a copied one.
106
107 To copy an index from another table, call:
108 @code
109 KDbIndexSchema *originalIndex = anotherTable->indices()->at(...);
110 KDbIndexSchema *newIndex = table->copyIndex(*originalIndex);
111 // newIndex is now created and is added to the table 'table'
112 @endcode
113
114 To copy an index within the same table, call:
115 @code
116 KDbIndexSchema *originalIndex = table->indices()->at(...);
117 KDbIndexSchema *newIndex = table->copyIndex(*originalIndex);
118 // newIndex is now created and is added to the table
119 @endcode
120 @since 3.1
121 @todo All relationships should be also copied
122 */
123 KDbIndexSchema* copyIndexFrom(const KDbIndexSchema& index);
124
125 /*! Removes all fields from the list, clears name and all other properties.
126 @see KDbFieldList::clear() */
127 void clear() override;
128
129 /*! Sends information about fields of this table schema to debug output @a dbg. */
130 QDebug debugFields(QDebug dbg) const;
131
132 /*! @return true if this is internal KDb's table.
133 Internal tables are hidden in applications (if desired) but are available
134 for schema export/import functionality.
135
136 Any internal KDb system table's schema (kexi__*) has
137 cleared its KDbObject part, e.g. id=-1 for such table,
138 and no description, caption and so on. This is because
139 it represents a native database table rather that extended Kexi table.
140
141 KDbTableSchema object has this property set to false, KDbInternalTableSchema has it
142 set to true. */
143 bool isInternal() const;
144
145 /*! @return query schema object that is defined by "select * from <this_table_name>"
146 This query schema object is owned by the table schema object.
147 It is convenient way to get such a query when it is not available otherwise.
148 Always returns non-0. */
149 KDbQuerySchema* query();
150
151 /*! @return any field not being a part of primary key of this table.
152 If there is no such field, returns @c nullptr. */
153 KDbField* anyNonPKField();
154
155 /*! Sets lookup field schema @a lookupFieldSchema for @a fieldName.
156 Passing @c nullptr @a lookupFieldSchema will remove the previously set lookup field.
157 @return true if @a lookupFieldSchema has been added,
158 or false if there is no such field @a fieldName. */
159 bool setLookupFieldSchema(const QString& fieldName, KDbLookupFieldSchema *lookupFieldSchema);
160
161 /*! @return lookup field schema for @a field.
162 0 is returned if there is no such field in the table or this field has no lookup schema.
163 Note that even id non-zero is returned here, you may want to check whether lookup field's
164 recordSource().name() is empty (if so, the field should behave as there was no lookup field
165 defined at all). */
166 KDbLookupFieldSchema *lookupFieldSchema(const KDbField& field);
167
168 //! @overload
169 const KDbLookupFieldSchema *lookupFieldSchema(const KDbField& field) const;
170
171 /*! @overload KDbLookupFieldSchema *KDbTableSchema::lookupFieldSchema( KDbField& field ) const */
172 KDbLookupFieldSchema *lookupFieldSchema(const QString& fieldName);
173
174 /*! @return list of lookup field schemas for this table.
175 The order is the same as the order of fields within the table. */
176 QVector<KDbLookupFieldSchema*> lookupFields() const;
177
178protected:
179 /*! Automatically retrieves table schema via connection. */
180 explicit KDbTableSchema(KDbConnection *conn, const QString & name = QString());
181
182 /*! @return connection object if table was created/retrieved using a connection,
183 otherwise @c nullptr. */
184 KDbConnection* connection() const;
185
186 /*! For KDbConnection. */
187 void setConnection(KDbConnection* conn);
188
189private:
190 //! Used by some ctors.
191 void init(KDbConnection* conn);
192
193 //! Used by some ctors.
194 void init(const KDbTableSchema& ts, bool copyId);
195
196 class Private;
197 Private * const d;
198
199 friend class KDbConnection;
200 friend class KDbNativeStatementBuilder;
201 friend class KDbFieldPrivate;
202 Q_DISABLE_COPY(KDbTableSchema)
203};
204
205/*! Internal table with a name @a name. Rarely used.
206 Use KDbConnection::createTable() to create a table using this schema.
207 The table will not be visible as user table.
208 For example, 'kexi__blobs' table is created this way by Kexi application. */
209class KDB_EXPORT KDbInternalTableSchema : public KDbTableSchema
210{
211public:
212 explicit KDbInternalTableSchema(const QString& name);
213 explicit KDbInternalTableSchema(const KDbTableSchema& ts);
215 ~KDbInternalTableSchema() override;
216
217private:
218 class Private;
219 Private * const d;
220};
221
222//! Sends information about table schema @a table to debug output @a dbg.
223KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbTableSchema& table);
224
225//! Sends information about internal table schema @a table to debug output @a dbg.
226KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbInternalTableSchema& table);
227
228#endif
Provides database connection, allowing queries and data modification.
virtual bool removeField(KDbField *field)
virtual void clear()
virtual bool insertField(int index, KDbField *field)
Meta-data for a field.
Definition KDbField.h:72
Provides information about database index that can be created for a database table.
Provides information about lookup field's setup.
A builder for generating various types of native SQL statements.
KDbQuerySchema provides information about database query.
This file is part of the KDE documentation.
Documentation copyright © 1996-2024 The KDE developers.
Generated on Fri Dec 6 2024 12:12:34 by doxygen 1.12.0 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.