File indexing completed on 2024-11-10 10:15:31

0001 /* This file is part of the KDE project
0002    Copyright (C) 2003, 2011 Jarosław Staniek <staniek@kde.org>
0003 
0004    This library is free software; you can redistribute it and/or
0005    modify it under the terms of the GNU Library General Public
0006    License as published by the Free Software Foundation; either
0007    version 2 of the License, or (at your option) any later version.
0008 
0009    This library is distributed in the hope that it will be useful,
0010    but WITHOUT ANY WARRANTY; without even the implied warranty of
0011    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
0012    Library General Public License for more details.
0013 
0014    You should have received a copy of the GNU Library General Public License
0015    along with this library; see the file COPYING.LIB.  If not, write to
0016    the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
0017  * Boston, MA 02110-1301, USA.
0018 */
0019 
0020 #ifndef KDB_RECORDEDITBUFFER_H
0021 #define KDB_RECORDEDITBUFFER_H
0022 
0023 #include <QMap>
0024 #include <QVariant>
0025 
0026 #include "kdb_export.h"
0027 
0028 class KDbQueryColumnInfo;
0029 class KDbField;
0030 
0031 /*!  @short provides data for single edited database record
0032 
0033   KDbRecordEditBuffer provides data for single edited record,
0034   needed to perform update at the database backend.
0035   Its advantage over pasing e.g. KDbFieldList object is that
0036   EditBuffer contains only changed values.
0037 
0038   EditBuffer offers two modes: db-aware and not-db-aware.
0039   Db-aware buffer addresses a field using references to KDbQueryColumnInfo object,
0040   while not-db-aware buffer addresses a field using its name.
0041 
0042   Example usage of not-db-aware buffer:
0043   <code>
0044   KDbQuerySchema *query = .....
0045   EditBuffer buf;
0046   buf.insert("name", "Joe");
0047   buf.insert("surname", "Black");
0048   buf.at("name"); //returns "Joe"
0049   buf.at("surname"); //returns "Black"
0050   buf.at(query->field("surname")); //returns "Black" too
0051   // Now you can use buf to add or edit records using
0052   // KDbConnection::updateRecord(), KDbConnection::insertRecord()
0053   </code>
0054 
0055   Example usage of db-aware buffer:
0056   <code>
0057   KDbQuerySchema *query = .....
0058   KDbQueryColumnInfo *ci1 = ....... //e.g. can be obtained from QueryScehma::fieldsExpanded()
0059   KDbQueryColumnInfo *ci2 = .......
0060   EditBuffer buf;
0061   buf.insert(*ci1, "Joe");
0062   buf.insert(*ci2, "Black");
0063   buf.at(*ci1); //returns "Joe"
0064   buf.at(*ci2); //returns "Black"
0065   // Now you can use buf to add or edit records using
0066   // KDbConnection::updateRecord(), KDbConnection::insertRecord()
0067   </code>
0068 
0069   You can use QMap::clear() to clear buffer contents,
0070   QMap::isEmpty() to see if buffer is empty.
0071   For more, see QMap documentation.
0072 
0073   Notes: added fields should come from the same (common) KDbQuerySchema object.
0074   However, this isn't checked at QValue& EditBuffer::operator[]( const KDbField& f ) level.
0075 */
0076 class KDB_EXPORT KDbRecordEditBuffer
0077 {
0078 public:
0079     typedef QMap<QString, QVariant> SimpleMap;
0080     typedef QHash<KDbQueryColumnInfo*, QVariant> DbHash;
0081 
0082     explicit KDbRecordEditBuffer(bool dbAwareBuffer);
0083 
0084     ~KDbRecordEditBuffer();
0085 
0086     bool isDBAware() const;
0087 
0088     void clear();
0089 
0090     bool isEmpty() const;
0091 
0092     //! Inserts value @a val for db-aware buffer's column @a ci
0093     //! Does nothing if @a ci is @c nullptr.
0094     void insert(KDbQueryColumnInfo* ci, const QVariant &val);
0095 
0096     //! Inserts value @a val for not-db-aware buffer's column @a fname
0097     void insert(const QString &fname, const QVariant &val);
0098 
0099     //! Removes value from db-aware buffer's column @a ci
0100     void removeAt(const KDbQueryColumnInfo& ci);
0101 
0102     //! Removes value from not-db-aware buffer's column @a fname
0103     void removeAt(const KDbField& field);
0104 
0105     //! Removes value from not-db-aware buffer's column @a fname
0106     void removeAt(const QString& fname);
0107 
0108     /*! Useful only for db-aware buffer. @return value for column @a ci
0109      If there is no value assigned for the buffer, this method tries to remember and return
0110      default value obtained from @a ci if @a useDefaultValueIfPossible is true.
0111      Note that if the column is declared as unique (especially: primary key),
0112      default value will not be used.
0113      Returns @c nullptr if @a ci is @c nullptr. */
0114     const QVariant* at(KDbQueryColumnInfo *ci, bool useDefaultValueIfPossible = true) const;
0115 
0116     //! Useful only for not-db-aware buffer. @return value for field @a field
0117     //! Returns @c nullptr if there is no such field.
0118     const QVariant* at(const KDbField &field) const;
0119 
0120     //! Useful only for not-db-aware buffer. @return value for field @a fname
0121     //! Returns @c nullptr if there is no such field.
0122     const QVariant* at(const QString& fname) const;
0123 
0124     //! Useful only for db-aware buffer: @return true if the value available as
0125     //! at( ci ) is obtained from column's default value
0126     bool hasDefaultValueAt(const KDbQueryColumnInfo &ci) const;
0127 
0128     KDbRecordEditBuffer::SimpleMap simpleBuffer() const;
0129 
0130     KDbRecordEditBuffer::DbHash dbBuffer() const;
0131 
0132 protected:
0133     SimpleMap *m_simpleBuffer;
0134     SimpleMap::ConstIterator *m_simpleBufferIt;
0135     DbHash *m_dbBuffer;
0136     DbHash::Iterator *m_dbBufferIt;
0137     QMap<KDbQueryColumnInfo*, bool> *m_defaultValuesDbBuffer;
0138     QMap<KDbQueryColumnInfo*, bool>::ConstIterator *m_defaultValuesDbBufferIt;
0139 
0140 private:
0141     Q_DISABLE_COPY(KDbRecordEditBuffer)
0142 };
0143 
0144 //! Sends information about object @a buffer to debug output @a dbg.
0145 KDB_EXPORT QDebug operator<<(QDebug dbg, const KDbRecordEditBuffer& buffer);
0146 
0147 #endif