Qore TableMapper Module Reference  1.2
TableMapper.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
3 
4 /* TableMapper.qm Copyright 2014 - 2017 Qore Technologies, s.r.o.
5 
6  Permission is hereby granted, free of charge, to any person obtaining a
7  copy of this software and associated documentation files (the "Software"),
8  to deal in the Software without restriction, including without limitation
9  the rights to use, copy, modify, merge, publish, distribute, sublicense,
10  and/or sell copies of the Software, and to permit persons to whom the
11  Software is furnished to do so, subject to the following conditions:
12 
13  The above copyright notice and this permission notice shall be included in
14  all copies or substantial portions of the Software.
15 
16  THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
17  IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
18  FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
19  AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
20  LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
21  FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
22  DEALINGS IN THE SOFTWARE.
23 */
24 
25 // this module requires Qore 0.8.13 or better
26 
27 // require type definitions everywhere
28 
29 // enable all warnings
30 
31 // don't use "$" signs for variables and class members, assume local variable scope
32 
33 // requires the Mapper module
34 // requires the SqlUtil module
35 
36 
256 namespace TableMapper {
260 
261 public:
262  public :
264  const OptionKeys = Mapper::OptionKeys + (
265  "unstable_input": sprintf("if this is set to True then a slower insert/upsert method will be used that verifies each input row; if False an optimized insert/upsert method is used (additionally bulk inserts/upserts are possible) but all input hashes must have the same keys in the same order; default: %y", OptionDefaults.unstable_input),
266  "insert_block": sprintf("the row block size used when bulk DML / batch inserts/upserts are used; default: %y", OptionDefaults.insert_block),
267  "rowcode": "a closure or call reference taking a single hash argument representing the row values inserted/upserted plus any output values generated in inserts (such as sequence values, for example)",
268  "upsert": "if True then data will be upserted instead of inserted",
269  "upsert_strategy": "the upsert strategy code to use; implies 'upsert'",
270  );
271 
273  const OptionDefaults = (
274  "unstable_input": False,
275  "insert_block": 1000,
276  );
277 
278 public:
279 
280  private :
283 
286 
289 
292 
295 
298 
301 
304 
307  *int hbuf_size; // size of the batch in hbuf (like if returned from
308  // getRecListSize())
309  // FIXME would be nice to have hbuf with hbuf_size
310  // in a class, but there are performance considerations.
311  // --PQ 23-Mar-2017
312 
314  *code rowcode;
315 
317  bool upsert = False;
318 
321 
323  *code upsert_code;
324 
325 public:
326 
328 
361  constructor(SqlUtil::Table target, hash mapv, *hash opts);
362 
363 
365 
398  constructor(SqlUtil::AbstractTable target, hash mapv, *hash opts);
399 
400 
402 
404  destructor();
405 
406 
408  static hash getOutputRecord(*string mname, AbstractTable table, *hash output);
409 
411 
412 private:
413  init(hash mapv, *hash opts);
414 public:
415 
416 
418 
419 private:
420  mapFieldType(string key, hash m, reference<int> v, hash rec);
421 public:
422 
423 
425 
429 private:
430  checkMapField(string k, reference<hash> fh);
431 public:
432 
433 
435 
437  hash validTypes();
438 
439 
441 
443  hash validKeys();
444 
445 
447 
449  hash optionKeys();
450 
451 
453 
463  hash insertRow(hash rec);
464 
465 
467 
479  setRowCode(*code rowc);
480 
481 
483 
547  *hash queueData(hash rec, *hash crec);
548 
549 
551 
588 
589 
591 
626  *hash queueData(list l, *hash crec);
627 
628 
630 
643 private:
644  *hash queueDataIntern(hash rec);
645 public:
646 
647 
656 private:
657  *int getRecListSize(hash rec);
658 public:
659 
660 
666 private:
668 public:
669 
670 
675 private:
676  bool isMapperConstant();
677 public:
678 
679 
685  static nothing addBatchToBatch(reference<hash> hb, hash batch);
686 
688 
690  deprecated static nothing addBatchToBatch(reference<hash> hb, reference x1, hash batch, *reference x2);
691 
693 
716  *hash flush();
717 
718 
720 
741  discard();
742 
743 
753  // return nothing if nothing needs to be flushed
754 
755 private:
756  *hash flushIntern(bool force_flush);
757 public:
758 
759 
761  *list getReturning();
762 
763 
765  logOutput(hash h);
766 
767 
769 
775 
776 
778  deprecated hash insertRowNoCommit(hash rec);
779 
781  nothing commit();
782 
783 
785  nothing rollback();
786 
787 
789  string getTableName();
790 
791 
794 
795 
798 
799 
801 
802 private:
803  error(string fmt);
804 public:
805 
806 
808 
809 private:
810  error2(string ex, string fmt);
811 public:
812 
813  };
814 
817 
818 public:
820 
839  constructor(SqlUtil::Table target, hash mapv = {}, *hash opts) ;
840 
841 
843 
863  constructor(SqlUtil::AbstractTable target, hash mapv = {}, *hash opts) ;
864 
865 
867 
868 private:
869  init(hash mapv, *hash opts);
870 public:
871 
872 
874  static hash getStaticInputRecord(SqlUtil::AbstractTable table);
875  };
876 
879 
880 public:
881  public :
882 
883 public:
884 
885  private :
888 
891 
893  int cnt = 0;
894 
897 
898 public:
899 
901 
908 
909 
911 
939  constructor(Qore::AbstractIterator i, SqlUtil::Table target, hash mapv, *hash opts, int commit_limit = 0) ;
940 
941 
943 
971  constructor(Qore::AbstractIterator i, SqlUtil::AbstractTable target, hash mapv, *hash opts, int commit_limit = 0) ;
972 
973 
975 
999 
1000 
1002  hash getValue();
1003 
1004 
1006 
1010  bool next();
1011 
1012 
1014  int commitLimit();
1015 
1016 
1018  nothing commit();
1019 
1020 
1022  nothing rollback();
1023 
1024 
1026  string getTableName();
1027 
1028 
1030 
1032  int getCount();
1033 
1034 
1036 
1038  resetCount();
1039 
1040 
1043 
1044 
1046 
1057  setRuntime(string key, auto value);
1058 
1059 
1061 
1071  setRuntime(hash runtime);
1072 
1073 
1075 
1085  replaceRuntime(*hash runtime);
1086 
1087 
1089 
1100  auto getRuntime(string key);
1101 
1102  };
1103 
1105 
1110 
1111 public:
1112  public :
1113 
1114 public:
1115 
1116  private :
1119 
1120 public:
1121 
1123 
1126  ;
1127 
1128 
1130 
1138  ;
1139 
1140 
1142 
1149  constructor(SqlUtil::Table table, hash sh, hash mapv, *hash opts)
1150  ;
1151 
1152 
1154 
1159  ;
1160 
1161 
1162 
1163 private:
1164  setup(hash mapv, *hash opts);
1165 public:
1166 
1167 
1169  hash getValue();
1170 
1171 
1173 
1175  int getCount();
1176 
1177 
1179 
1181  resetCount();
1182 
1183 
1185  bool hasBulk();
1186 
1187 
1189 
1193  list mapBulk(int size);
1194 
1195 
1197 
1208  setRuntime(string key, auto value);
1209 
1210 
1212 
1222  setRuntime(hash runtime);
1223 
1224 
1226 
1236  replaceRuntime(*hash runtime);
1237 
1238 
1240 
1251  auto getRuntime(string key);
1252 
1253  }; // class SqlStatementMapperIterator
1254 
1257 
1258 public:
1259  public :
1261  const OptionKeys = Mapper::OptionKeys + (
1262  "table": "(required) the AbstractTable object for the source of the data",
1263  "sh": "(optional) an SqlUtil select hash",
1264  "select_block" : sprintf("the row block size used when bulk DML / batch inserts are used; default: %y", OptionDefaults.select_block),
1265  );
1266 
1268  const OptionDefaults = (
1269  "select_block": 1000,
1270  );
1271 
1272 public:
1273 
1274  private :
1275  // internal SQLStatement
1276  SQLStatement m_stmt;
1277  // a select_block size. Taken from options
1278  int select_block;
1279  // original option hash
1280  *hash m_orig_opts;
1281 
1282 public:
1283 
1285 
1295  constructor(hash mapv, *hash opts);
1296 
1297 
1299 
1301  hash optionKeys();
1302 
1303 
1305  commit();
1306 
1307 
1309  rollback();
1310 
1311 
1314 
1316 
1317 private:
1318  abstract initOptions(reference<hash> opts);
1319 public:
1320 
1322 
1323 private:
1324  abstract initStatement();
1325 public:
1326 
1328 
1330  Qore::SQL::SQLStatement getRowIterator();
1331 
1332 
1334 
1340 
1341 
1343 
1352  *hash getData();
1353 
1354 
1356 
1364  *list getDataRows();
1365 
1366 
1367  }; // AbstractSqlStatementOutboundMapper
1368 
1371 
1372 public:
1373  private :
1374  // the target table object
1375  SqlUtil::AbstractTable m_table;
1376  // SqlUtil select hash
1377  *hash m_sh;
1378 
1379 public:
1380 
1382 
1392  constructor(SqlUtil::Table source, *hash sh, hash mapv, *hash opts)
1393  ;
1394 
1395 
1397 
1407  constructor(SqlUtil::AbstractTable source, *hash sh, hash mapv, *hash opts)
1408  ;
1409 
1410 
1412 
1414  string getTableName();
1415 
1416 
1418 
1421 
1422 
1425 
1426 
1428  static *hash getStaticInputRecord(AbstractTable table, *hash select_hash, *reference<string> sql);
1429 
1431  initStatement();
1432 
1433 
1435 
1436 private:
1437  initOptions(reference<hash> opts);
1438 public:
1439 
1440  }; // SqlStatementOutboundMapper
1441 
1444 
1445 public:
1446  private :
1447  AbstractDatasource m_ds;
1448  string m_sql;
1449  *list m_sqlargs;
1450 
1451 public:
1452 
1454 
1484  constructor(Qore::SQL::AbstractDatasource ds, string sql, *softlist sqlargs, hash mapv, *hash opts)
1485  ;
1486 
1487 
1490 
1491 
1493  static *hash getStaticInputRecord(Qore::SQL::AbstractDatasource ds, string sql, *softlist args);
1494 
1496 
1497 private:
1498  initStatement();
1499 public:
1500 
1501 
1503 
1504 private:
1505  initOptions(reference<hash> opts);
1506 public:
1507 
1508  }; // RawSqlStatementOutboundMapper
1509 };
auto getRuntime(string key)
string sprintf(string fmt,...)
string getTableName()
returns the table name
*hash getOutputRecord()
*hash queueData(hash rec, *hash crec)
inserts/upserts a row (or a set of rows, in case a hash of lists is passed) into the block buffer bas...
provides a hash iterator based on a InboundTableMapper object and an iterator input source; for each ...
Definition: TableMapper.qm.dox.h:878
Qore::SQL::SQLStatement stmt
statement for inserts/upserts
Definition: TableMapper.qm.dox.h:300
int commit_limit
row commit limit (<= 0 for no commits)
Definition: TableMapper.qm.dox.h:890
*list getReturning()
returns a list argument for the SqlUtil "returning" option, if applicable
Mapper::Mapper m_mapper
data mapper
Definition: TableMapper.qm.dox.h:1118
*int upsert_strategy
upsert strategy option
Definition: TableMapper.qm.dox.h:320
provides an outbound data mapper to a Table with SqlUtil select hash as a asource ...
Definition: TableMapper.qm.dox.h:1370
destructor()
throws an exception if there is data pending in the block cache
hash hbuf
buffer for bulk DML
Definition: TableMapper.qm.dox.h:306
hash validKeys()
returns a list of valid field keys for this class (can be overridden in subclasses) ...
hash optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses) ...
static nothing addBatchToBatch(reference< hash > hb, hash batch)
checkMapField(string k, reference< hash > fh)
perform per-field pre-processing on the passed map in the constructor
provides an outbound data mapper to a raw SQL statement
Definition: TableMapper.qm.dox.h:1443
nothing rollback()
discards any queued data and rolls back the transaction
hash validTypes()
returns a list of valid field types for this class (can be overridden in subclasses) ...
hash val
a copy of the last hash value mapped
Definition: TableMapper.qm.dox.h:896
mapFieldType(string key, hash m, reference< int > v, hash rec)
performs type handling
*hash flush()
flushes any remaining batched data to the database; this method should always be called before commit...
const OptionDefaults
default option values
Definition: TableMapper.qm.dox.h:273
*hash flushIntern(bool force_flush)
const False
list list(...)
bool has_returning
if the AbstractTable object supports the "returning" clause
Definition: TableMapper.qm.dox.h:288
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
const OptionKeys
option keys for this object
Definition: TableMapper.qm.dox.h:264
deprecated hash insertRowNoCommit(hash rec)
Plain alias to insertRow(). Obsolete. Do not use.
setup(hash mapv, *hash opts)
SqlUtil::AbstractTable getTable()
returns the underlying SqlUtil::AbstractTable object
*hash queueDataIntern(hash rec)
inserts a row into the block buffer based on a mapped input record; does not commit the transaction ...
bool upsert
upsert flag
Definition: TableMapper.qm.dox.h:317
init(hash mapv, *hash opts)
common constructor initialization
*code upsert_code
closure used for upserting
Definition: TableMapper.qm.dox.h:323
nothing commit()
flushes any queued data and commits the transaction
SqlUtil::AbstractDatabase db
the target Database object in case sequence value need to be acquired
Definition: TableMapper.qm.dox.h:285
bool unstable_input
"unstable input" option for non-optimized inserts/upserts (~33% performance reduction in insert/upser...
Definition: TableMapper.qm.dox.h:297
maps from source to target tables with exactly the same structure
Definition: TableMapper.qm.dox.h:816
setRuntime(string key, auto value)
error(string fmt)
prepends the datasource description to the error string and calls Mapper::error() ...
the TableMapper namespace contains all the definitions in the TableMapper module
Definition: TableMapper.qm.dox.h:257
provides an abstract base for all SQL based outbound mappers
Definition: TableMapper.qm.dox.h:1256
error2(string ex, string fmt)
prepends the datasource description to the error description and calls Mapper::error2() ...
list ret_args
"returning" arguments for sequences
Definition: TableMapper.qm.dox.h:291
provides a hash iterator based on a mapper object and an SQLStatement or SqlUtil select hash ...
Definition: TableMapper.qm.dox.h:1109
provides an inbound data mapper to a Table target
Definition: TableMapper.qm.dox.h:259
discard()
discards any buffered batched data; this method should be called after using the batch APIs (queueDat...
replaceRuntime(*hash runtime)
hash insertRow(hash rec)
inserts or upserts a row into the target table based on a mapped input record; does not commit the tr...
TableMapper::InboundTableMapper mapc
data mapper
Definition: TableMapper.qm.dox.h:887
hash hash(object obj)
list out_args
extra arguments for sequence output binds
Definition: TableMapper.qm.dox.h:294
int insert_block
bulk DML block size (also valid for upserts despite the name)
Definition: TableMapper.qm.dox.h:303
SqlUtil::AbstractTable table
the target table object
Definition: TableMapper.qm.dox.h:282
TableMapper::InboundTableMapperIterator iterator(Qore::AbstractIterator i)
returns an iterator for the current object
logOutput(hash h)
ignore logging from Mapper since we may have to log sequence values; output logged manually in insert...
*code rowcode
per-row Closures or Call References for batch inserts/upserts
Definition: TableMapper.qm.dox.h:314
setRowCode(*code rowc)
sets a closure or call reference that will be called when data has been sent to the database and all ...