KDb

KDbRelationship.h
1 /* This file is part of the KDE project
2  Copyright (C) 2003-2017 JarosÅ‚aw Staniek <[email protected]>
3 
4  This library is free software; you can redistribute it and/or
5  modify it under the terms of the GNU Library General Public
6  License as published by the Free Software Foundation; either
7  version 2 of the License, or (at your option) any later version.
8 
9  This library is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY; without even the implied warranty of
11  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
12  Library General Public License for more details.
13 
14  You should have received a copy of the GNU Library General Public License
15  along with this library; see the file COPYING.LIB. If not, write to
16  the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
17  * Boston, MA 02110-1301, USA.
18  */
19 
20 #ifndef KDB_RELATIONSHIP_H
21 #define KDB_RELATIONSHIP_H
22 
23 #include "KDbField.h"
24 
25 /*! KDbRelationship provides information about one-to-many relationship between two tables.
26  Relationship is defined by a pair of (potentially multi-field) indices:
27  - "one" or "master" side: unique key
28  - "many" or "details" side: referenced foreign key
29  <pre>
30  [unique key, master] ----< [foreign key, details]
31  </pre>
32 
33  In this documentation, we will call table that owns fields of "one" side as
34  "master side of the relationship", and the table that owns foreign key fields of
35  as "details side of the relationship".
36  Use masterTable(), and detailsTable() to get one-side table and many-side table, respectively.
37 
38  Note: some engines (e.g. MySQL with InnoDB) requires that indices at both sides
39  have to be explicitly created.
40 
41  @todo (js) It is planned that this will be handled by KDb internally and transparently.
42 
43  Each (of the two) key can be defined (just like index) as list of fields owned by one table.
44  Indeed, relationship info can retrieved from KDbRelationship object in two ways:
45  -# pair of indices; use masterIndex(), detailsIndex() for that
46  -# ordered list of field pairs (<master-side-field, details-side-field>); use fieldPairs() for that
47 
48  No assigned objects (like fields, indices) are owned by KDbRelationship object. The exception is that
49  list of field-pairs is internally created (on demand) and owned.
50 
51  KDbRelationship object is owned by KDbIndexSchema object (the one that is defined at master-side of the
52  relationship).
53  Note also that KDbIndexSchema objects are owned by appropriate tables, so thus
54  there is implicit ownership between KDbTableSchema and KDbRelationship.
55 
56  If KDbRelationship object is not attached to KDbIndexSchema object,
57  you should care about destroying it by hand.
58 
59  Example:
60  <pre>
61  ----------
62  ---r1--<| |
63  | Table A [uk]----r3---<
64  ---r2--<| |
65  ----------
66  </pre>
67  Table A has two relationships (r1, r2) at details side and one (r3) at master side.
68  [uk] stands for unique key.
69 */
70 
71 class KDbIndexSchema;
72 class KDbTableSchema;
73 class KDbQuerySchema;
74 
75 class KDB_EXPORT KDbRelationship
76 {
77 public:
78  typedef QList<KDbRelationship*> List;
79  typedef QList<KDbRelationship*>::ConstIterator ListIterator;
80 
81  /**
82  * @brief Creates a new uninitialized KDbRelationship object
83  */
84  KDbRelationship();
85 
86  /**
87  * @brief Creates a new KDbRelationship object and initialises it using setIndices()
88  *
89  * If setIndices() failed, object is still uninitialised. Check this using isEmpty().
90  */
91  KDbRelationship(KDbIndexSchema* masterIndex, KDbIndexSchema* detailsIndex);
92 
93  virtual ~KDbRelationship();
94 
95  //! Assigns @a other to this object returns a reference to this object.
96  //! @since 3.1
97  KDbRelationship& operator=(KDbRelationship &other);
98 
99  //! @return true if this relationship is the same as @a other
100  //! Relationships are equal if they have the same details and master indices are equal
101  //! @since 3.1
102  bool operator==(const KDbRelationship& other) const;
103 
104  //! @return @c true if this object is not equal to @a other; otherwise returns @c false.
105  //! @since 3.1
106  inline bool operator!=(const KDbRelationship &other) const { return !operator==(other); }
107 
108  /*! @return index defining master side of this relationship
109  or @c nullptr if there is no information defined. */
110  KDbIndexSchema* masterIndex();
111 
112  //! @overload
113  const KDbIndexSchema* masterIndex() const;
114 
115  /*! @return index defining referenced side of this relationship.
116  or @c nullptr if there is no information defined. */
117  KDbIndexSchema* detailsIndex();
118 
119  //! @overload
120  const KDbIndexSchema* detailsIndex() const;
121 
122  /**
123  * Returns ordered list of field pairs, alternative representation of relationship
124  *
125  * @c nullptr is returned if there is no information defined.
126  * Each pair has a form of <master-side-field, details-side-field>.
127  */
128  KDbField::PairList* fieldPairs();
129 
130  //! @overload
131  const KDbField::PairList* fieldPairs() const;
132 
133  //! @return true if there are no master-details pairs in this relationship object
134  //! @see fieldPairs()
135  bool isEmpty() const;
136 
137  /*! @return table assigned at "master / one" side of this relationship.
138  or @c nullptr if there is no information defined. */
139  KDbTableSchema* masterTable();
140 
141  //! @overload
142  const KDbTableSchema* masterTable() const;
143 
144  /*! @return table assigned at "details / many / foreign" side of this relationship.
145  or @c nullptr if there is no information defined. */
146  KDbTableSchema* detailsTable();
147 
148  //! @overload
149  const KDbTableSchema* detailsTable() const;
150 
151  /*! Sets @a masterIndex and @a detailsIndex indices for this relationship.
152  This also sets information about tables for master- and details- sides.
153  Notes:
154  - both indices must contain the same number of fields
155  - both indices must not be owned by the same table, and table (owner) must be not null.
156  - corresponding field types must be the same
157  - corresponding field types' signedness must be the same
158  If above rules are not fulfilled, information about this relationship is cleared.
159  On success, this KDbRelationship object is detached from previous KDbIndexSchema objects that were
160  assigned before, and new are attached.
161  */
162  bool setIndices(KDbIndexSchema* masterIndex, KDbIndexSchema* detailsIndex);
163 
164 protected:
165  KDbRelationship(KDbQuerySchema *query, KDbField *field1, KDbField *field2);
166 
167  friend class KDbConnection;
168  friend class KDbTableSchema;
169  friend class KDbQuerySchema;
170  friend class KDbIndexSchema;
171 
172 private:
173  class Private;
174  Private * const d;
175 };
176 
177 #endif
bool operator==(const Qt3DRender::QGraphicsApiFilter &reference, const Qt3DRender::QGraphicsApiFilter &sample)
bool operator!=(const Qt3DRender::QGraphicsApiFilter &reference, const Qt3DRender::QGraphicsApiFilter &sample)
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
This file is part of the KDE documentation.
Documentation copyright © 1996-2022 The KDE developers.
Generated on Sat Jun 25 2022 06:21:33 by doxygen 1.8.17 written by Dimitri van Heesch, © 1997-2006

KDE's Doxygen guidelines are available online.