1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
/* This file is part of the KDE project
Copyright (C) 2003-2004 Jaroslaw Staniek <js@iidea.pl>
This library is free software; you can redistribute it and/or
modify it under the terms of the GNU Library General Public
License as published by the Free Software Foundation; either
version 2 of the License, or (at your option) any later version.
This library is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
Library General Public License for more details.
You should have received a copy of the GNU Library General Public License
along with this library; see the file COPYING.LIB. If not, write to
the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
* Boston, MA 02110-1301, USA.
*/
#ifndef KEXIDB_RELATIONSHIP_H
#define KEXIDB_RELATIONSHIP_H
#include <kexidb/field.h>
namespace KexiDB {
/*! KexiDB::Relationship provides information about one-to-many relationship between two tables.
Relationship is defined by a pair of (potentially multi-field) indices:
- "one" or "master" side: unique key
- "many" or "details" side: referenced foreign key
<pre>
[unique key, master] ----< [foreign key, details]
</pre>
In this documentation, we will call table that owns fields of "one" side as
"master side of the relationship", and the table that owns foreign key fields of
as "details side of the relationship".
Use masterTable(), and detailsTable() to get one-side table and many-side table, respectively.
Note: some engines (e.g. MySQL with InnoDB) requires that indices at both sides
have to be explicitly created.
\todo (js) It is planned that this will be handled by KexiDB internally and transparently.
Each (of the two) key can be defined (just like index) as list of fields owned by one table.
Indeed, relationship info can retrieved from Relationship object in two ways:
-# pair of indices; use masterIndex(), detailsIndex() for that
-# ordered list of field pairs (<master-side-field, details-side-field>); use fieldPairs() for that
No assigned objects (like fields, indices) are owned by Relationship object. The exception is that
list of field-pairs is internally created (on demand) and owned.
Relationship object is owned by IndexSchema object (the one that is defined at master-side of the
relationship).
Note also that IndexSchema objects are owned by appropriate tables, so thus
there is implicit ownership between TableSchema and Relationship.
If Relationship object is not attached to IndexSchema object,
you should care about destroying it by hand.
Example:
<pre>
----------
---r1--<| |
| Table A [uk]----r3---<
---r2--<| |
----------
</pre>
Table A has two relationships (r1, r2) at details side and one (r3) at master side.
[uk] stands for unique key.
*/
class IndexSchema;
class TableSchema;
class QuerySchema;
class KEXI_DB_EXPORT Relationship
{
public:
typedef QPtrList<Relationship> List;
typedef QPtrListIterator<Relationship> ListIterator;
/*! Creates uninitialized Relationship object.
setIndices() will be required to call.
*/
Relationship();
/*! Creates Relationship object and initialises it just by
calling setIndices(). If setIndices() failed, object is still uninitialised.
*/
Relationship(IndexSchema* masterIndex, IndexSchema* detailsIndex);
virtual ~Relationship();
/*! \return index defining master side of this relationship
or null if there is no information defined. */
IndexSchema* masterIndex() const { return m_masterIndex; }
/*! \return index defining referenced side of this relationship.
or null if there is no information defined. */
IndexSchema* detailsIndex() const { return m_detailsIndex; }
/*! \return ordered list of field pairs -- alternative form
for representation of relationship or null if there is no information defined.
Each pair has a form of <master-side-field, details-side-field>. */
Field::PairList* fieldPairs() { return &m_pairs; }
bool isEmpty() const { return m_pairs.isEmpty(); }
/*! \return table assigned at "master / one" side of this relationship.
or null if there is no information defined. */
TableSchema* masterTable() const;
/*! \return table assigned at "details / many / foreign" side of this relationship.
or null if there is no information defined. */
TableSchema* detailsTable() const;
/*! Sets \a masterIndex and \a detailsIndex indices for this relationship.
This also sets information about tables for master- and details- sides.
Notes:
- both indices must contain the same number of fields
- both indices must not be owned by the same table, and table (owner) must be not null.
- corresponding field types must be the same
- corresponding field types' signedness must be the same
If above rules are not fulfilled, information about this relationship is cleared.
On success, this Relationship object is detached from previous IndexSchema objects that were
assigned before, and new are attached.
*/
void setIndices(IndexSchema* masterIndex, IndexSchema* detailsIndex);
protected:
Relationship( QuerySchema *query, Field *field1, Field *field2 );
void createIndices( QuerySchema *query, Field *field1, Field *field2 );
/*! Internal version of setIndices(). \a ownedByMaster parameter is passed
to IndexSchema::attachRelationship() */
void setIndices(IndexSchema* masterIndex, IndexSchema* detailsIndex, bool ownedByMaster);
IndexSchema *m_masterIndex;
IndexSchema *m_detailsIndex;
Field::PairList m_pairs;
bool m_masterIndexOwned : 1;
bool m_detailsIndexOwned : 1;
friend class Connection;
friend class TableSchema;
friend class QuerySchema;
friend class IndexSchema;
};
} //namespace KexiDB
#endif
|
