src/DAL/SavableManager.h

   1 /***************************************************************************
   2  *   Copyright (C) 2008 by Sverre Rabbelier                                *
   3  *   sverre@rabbelier.nl                                                   *
   4  *                                                                         *
   5  *   This program is free software; you can redistribute it and/or modify  *
   6  *   it under the terms of the GNU General Public License as published by  *
   7  *   the Free Software Foundation; either version 3 of the License, or     *
   8  *   (at your option) any later version.                                   *
   9  *                                                                         *
  10  *   This program 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         *
  13  *   GNU General Public License for more details.                          *
  14  *                                                                         *
  15  *   You should have received a copy of the GNU General Public License     *
  16  *   along with this program; if not, write to the                         *
  17  *   Free Software Foundation, Inc.,                                       *
  18  *   59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.             *
  19  ***************************************************************************/
  20 #pragma once
  21
  22 /**
  23  * @file SavableManager.h
  24  * @brief Containers the SavableManager class.
  25  *
  26  * @see SavableManager.
  27  */
  28
  29 #include "Types.h"
  30
  31 /** The type used to cache SavableManagers by their keys in. */
  32 typedef std::map<Keys*, SavableManagerPtr> ByKeyCache;
  33 /** The type used to cache SavableManagers by their value in. */
  34 typedef std::map<FieldValue*, SavableManagerPtr> ByValueCache;
  35
  36 /**
  37  * This class represents one row in the database.
  38  *
  39  * It may be used to perform CRUD operations on the database.
  40  * (Create, Retreive, Update, Delete)
  41  */
  42 class SavableManager
  43 {
  44         public:
  45                 /**
  46                  * Select multiple entries from the database restricting on the specified values.
  47                  *
  48                  * This method wraps the creation of the SelectionMask and the call to the database.
  49                  * This is the preferred method of selection multiple rows from the database is through 'getmulti'.
  50                  *
  51                  * @param values The values to filter on.
  52                  * @return A SavableManagers bucket containing the retreived data.
  53                  * @see SelectionMask
  54                  */
  55                 static SavableManagersPtr getmulti(ValuesPtr values);
  56
  57                 /**
  58                  * Select multiple entries from the database restricting on the specified values.
  59                  *
  60                  * This method wraps the creation of the SelectionMask and the call to the database.
  61                  * This is the preferred method of selection multiple rows from the database is through 'getmulti'.
  62                  *
  63                  * @param values The values to filter on.
  64                  * @param joins The joins to extend the selection with.
  65                  * @return A SavableManagers bucket containing the retreived data.
  66                  * @see SelectionMask
  67                  */
  68                 static SavableManagersPtr getmulti(ValuesPtr values, const Joins& joins);
  69
  70                 /** Returns a new manager for the specified table, it is not yet stored in the database. */
  71                 static SavableManagerPtr getnew(TableImplPtr table);
  72
  73                 /** Returns a manager for the specified table using the specified key. */
  74                 static SavableManagerPtr bykey(KeyValuePtr key);
  75
  76                 /** Returns a manager using the specified keys, these are asserted to be all the keys for this table.*/
  77                 static SavableManagerPtr bykeys(KeysPtr keys);
  78
  79                 /** Returns a manager using the specified value, this value should uniquely identify an entry. */
  80                 static SavableManagerPtr byvalue(ValuePtr value);
  81
  82                 /** Wrapper that looks up a manager by the specified value and returns the keys. */
  83                 static KeysPtr lookupvalue(ValuePtr value);
  84
  85
  86                 /** Remove the row this manager represents from the databse. */
  87                 void erase();
  88
  89                 /** Save the row this manager represents to the database. */
  90                 void save();
  91
  92                 /** Discards any changes made to this manager. */
  93                 void discard();
  94
  95                 /** Wether the manager has been saved to the database or not. */
  96                 bool exists();
  97
  98
  99                 /** Binds the keys of this manager to the specified statement. */
 100                 void bindKeys(sqlite3* db, sqlite3_stmt* stmt, const int startpos = 1) const;
 101
 102                 /** Binds the fields of this manager to the specified statement. */
 103                 void bindFields(sqlite3* db, sqlite3_stmt* stmt, const int startpos = 1) const;
 104
 105                 /** First binds the keys and then the fields of this manager to the specified statement. */
 106                 void bindUpdate(sqlite3* db, sqlite3_stmt* stmt) const;
 107
 108                 /** Binds the lookup field of this manager to the specified statement. */
 109                 void bindLookup(sqlite3* db, sqlite3_stmt* stmt) const;
 110
 111
 112                 /**
 113                  * Parse an insertion from the database.
 114                  *
 115                  * Only valid on a table with a singular primary key.
 116                  * That is, sqlite3_last_insert_rowid must return the id of the inserted row.
 117                  */
 118                 void parseInsert(sqlite3* db);
 119
 120                 /** Read in this managers fields from a selection from the database. */
 121                 void parseSelect(sqlite3_stmt* stmt, const int startpos = 0);
 122
 123                 /** Read in the keys and the fields for this manager from a lookup from the database. */
 124                 void parseLookup(sqlite3_stmt* stmt);
 125
 126
 127                 /** Returns the table this manager belongs to. */
 128                 TableImplPtr getTable() const;
 129
 130                 /** Returns the keys of the row this manager represents. */
 131                 KeysPtr getkeys() const;
 132
 133                 /** Returns the value of the specified field of the row this manager represents . */
 134                 ValuePtr getfield(FieldImplPtr field) const;
 135
 136                 /** Returns the value of the specified key of the row this manager represents. */
 137                 KeyValuePtr getkey(KeyImplPtr keydef) const;
 138
 139
 140                 /** Returns an array of strings, one for each field in this row. */
 141                 Strings fieldList() const;
 142
 143                 /** Returns a string representation of the valueus of this manager compared to the database. */
 144                 std::string getDiff() const;
 145
 146                 /** Wether any changes been made to this manager that have not been saved to the databse yet. */
 147                 bool isDirty() const;
 148
 149
 150                 /** Sets this managers keys to the specified values. */
 151                 void setkeys(KeysPtr keys);
 152
 153                 /** Sets the specified field of this manager to the specified value. */
 154                 void setvalue(ValuePtr value);
 155
 156         private:
 157                 /** This is a managed class, use the factory methods insteaed of this constructor to create a new instance. */
 158                 SavableManager(TableImplPtr table);
 159
 160                 /** Destructor, a noop. */
 161                 ~SavableManager();
 162
 163
 164                 /** Unsets the dirty field and all the dirty fields of all keys and fields. */
 165                 void cleanup();
 166
 167
 168                 /** Cache the specified manager. */
 169                 static void doFullCache(SavableManagerPtr manager);
 170
 171                 static ByKeyCache ms_byKeyCache; /**< Lookup to retreive managers by the keys. */
 172                 static ByValueCache ms_byValueCache; /**< Lookup to retreive managers by value. */
 173
 174                 friend SmartPtrDelete(SavableManager);
 175                 friend class SelectionMask;
 176
 177                 TableImplPtr m_table; /**< The table this manager belongs to. */
 178                 ValuePtr m_lookupvalue; /**< The value the lookup will use. */
 179
 180                 KeysPtr m_keys; /**< The keys of this manager. */
 181                 FieldValueMap m_fields; /**< The valueu of this manager. */
 182
 183                 bool m_newentry; /**< Is this manager saved to the database yet. */
 184                 bool m_dirty; /**< Are changes made to this manager that have not been saved yet. */
 185 };