KDb

KDbRecordEditBuffer.h
1 /* This file is part of the KDE project
2  Copyright (C) 2003, 2011 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_RECORDEDITBUFFER_H
21 #define KDB_RECORDEDITBUFFER_H
22 
23 #include <QMap>
24 #include <QVariant>
25 
26 #include "kdb_export.h"
27 
28 class KDbQueryColumnInfo;
29 class KDbField;
30 
31 /*! @short provides data for single edited database record
32 
33  KDbRecordEditBuffer provides data for single edited record,
34  needed to perform update at the database backend.
35  Its advantage over pasing e.g. KDbFieldList object is that
36  EditBuffer contains only changed values.
37 
38  EditBuffer offers two modes: db-aware and not-db-aware.
39  Db-aware buffer addresses a field using references to KDbQueryColumnInfo object,
40  while not-db-aware buffer addresses a field using its name.
41 
42  Example usage of not-db-aware buffer:
43  <code>
44  KDbQuerySchema *query = .....
45  EditBuffer buf;
46  buf.insert("name", "Joe");
47  buf.insert("surname", "Black");
48  buf.at("name"); //returns "Joe"
49  buf.at("surname"); //returns "Black"
50  buf.at(query->field("surname")); //returns "Black" too
51  // Now you can use buf to add or edit records using
52  // KDbConnection::updateRecord(), KDbConnection::insertRecord()
53  </code>
54 
55  Example usage of db-aware buffer:
56  <code>
57  KDbQuerySchema *query = .....
58  KDbQueryColumnInfo *ci1 = ....... //e.g. can be obtained from QueryScehma::fieldsExpanded()
59  KDbQueryColumnInfo *ci2 = .......
60  EditBuffer buf;
61  buf.insert(*ci1, "Joe");
62  buf.insert(*ci2, "Black");
63  buf.at(*ci1); //returns "Joe"
64  buf.at(*ci2); //returns "Black"
65  // Now you can use buf to add or edit records using
66  // KDbConnection::updateRecord(), KDbConnection::insertRecord()
67  </code>
68 
69  You can use QMap::clear() to clear buffer contents,
70  QMap::isEmpty() to see if buffer is empty.
71  For more, see QMap documentation.
72 
73  Notes: added fields should come from the same (common) KDbQuerySchema object.
74  However, this isn't checked at QValue& EditBuffer::operator[]( const KDbField& f ) level.
75 */
76 class KDB_EXPORT KDbRecordEditBuffer
77 {
78 public:
81 
82  explicit KDbRecordEditBuffer(bool dbAwareBuffer);
83 
85 
86  bool isDBAware() const;
87 
88  void clear();
89 
90  bool isEmpty() const;
91 
92  //! Inserts value @a val for db-aware buffer's column @a ci
93  //! Does nothing if @a ci is @c nullptr.
94  void insert(KDbQueryColumnInfo* ci, const QVariant &val);
95 
96  //! Inserts value @a val for not-db-aware buffer's column @a fname
97  void insert(const QString &fname, const QVariant &val);
98 
99  //! Removes value from db-aware buffer's column @a ci
100  void removeAt(const KDbQueryColumnInfo& ci);
101 
102  //! Removes value from not-db-aware buffer's column @a fname
103  void removeAt(const KDbField& field);
104 
105  //! Removes value from not-db-aware buffer's column @a fname
106  void removeAt(const QString& fname);
107 
108  /*! Useful only for db-aware buffer. @return value for column @a ci
109  If there is no value assigned for the buffer, this method tries to remember and return
110  default value obtained from @a ci if @a useDefaultValueIfPossible is true.
111  Note that if the column is declared as unique (especially: primary key),
112  default value will not be used.
113  Returns @c nullptr if @a ci is @c nullptr. */
114  const QVariant* at(KDbQueryColumnInfo *ci, bool useDefaultValueIfPossible = true) const;
115 
116  //! Useful only for not-db-aware buffer. @return value for field @a field
117  //! Returns @c nullptr if there is no such field.
118  const QVariant* at(const KDbField &field) const;
119 
120  //! Useful only for not-db-aware buffer. @return value for field @a fname
121  //! Returns @c nullptr if there is no such field.
122  const QVariant* at(const QString& fname) const;
123 
124  //! Useful only for db-aware buffer: @return true if the value available as
125  //! at( ci ) is obtained from column's default value
126  bool hasDefaultValueAt(const KDbQueryColumnInfo &ci) const;
127 
128  KDbRecordEditBuffer::SimpleMap simpleBuffer() const;
129 
130  KDbRecordEditBuffer::DbHash dbBuffer() const;
131 
132 protected:
133  SimpleMap *m_simpleBuffer;
134  SimpleMap::ConstIterator *m_simpleBufferIt;
135  DbHash *m_dbBuffer;
136  DbHash::Iterator *m_dbBufferIt;
137  QMap<KDbQueryColumnInfo*, bool> *m_defaultValuesDbBuffer;
138  QMap<KDbQueryColumnInfo*, bool>::ConstIterator *m_defaultValuesDbBufferIt;
139 
140 private:
141  Q_DISABLE_COPY(KDbRecordEditBuffer)
142 };
143 
144 //! Sends information about object @a buffer to debug output @a dbg.
145 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbRecordEditBuffer& buffer);
146 
147 #endif
QDataStream & operator<<(QDataStream &out, const KDateTime &dateTime)
provides data for single edited database record
Meta-data for a field.
Definition: KDbField.h:71
Helper class that assigns additional information for the column in a query.
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.