KDb

KDbTableSchema.h
1 /* This file is part of the KDE project
2  Copyright (C) 2003 Joseph Wenninger <[email protected]>
3  Copyright (C) 2003-2016 JarosÅ‚aw Staniek <[email protected]>
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 
30 class KDbConnection;
32 class KDbFieldPrivate;
33 
34 /*! Provides information about native database table
35  that can be stored using KDb database engine.
36 */
37 class KDB_EXPORT KDbTableSchema : public KDbFieldList, public KDbObject
38 {
39 public:
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 
178 protected:
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 
189 private:
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. */
209 class KDB_EXPORT KDbInternalTableSchema : public KDbTableSchema
210 {
211 public:
212  explicit KDbInternalTableSchema(const QString& name);
213  explicit KDbInternalTableSchema(const KDbTableSchema& ts);
215  ~KDbInternalTableSchema() override;
216 
217 private:
218  class Private;
219  Private * const d;
220 };
221 
222 //! Sends information about table schema @a table to debug output @a dbg.
223 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbTableSchema& table);
224 
225 //! Sends information about internal table schema @a table to debug output @a dbg.
226 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbInternalTableSchema& table);
227 
228 #endif
KCALENDARCORE_EXPORT QDataStream & operator<<(QDataStream &out, const KCalendarCore::Alarm::Ptr &)
Provides information about lookup field's setup.
A builder for generating various types of native SQL statements.
virtual bool insertField(int index, KDbField *field)
virtual bool removeField(KDbField *field)
Provides information about database index that can be created for a database table.
KDbQuerySchema provides information about database query.
Meta-data for a field.
Definition: KDbField.h:71
Provides database connection, allowing queries and data modification.
Definition: KDbConnection.h:51
virtual void clear()
This file is part of the KDE documentation.
Documentation copyright © 1996-2023 The KDE developers.
Generated on Fri Jun 9 2023 04:07:16 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.