Qore TableMapper Module Reference  1.1
TableMapper.qm.dox.h
1 // -*- mode: c++; indent-tabs-mode: nil -*-
3 
4 /* TableMapper.qm Copyright 2014 - 2016 Qore Technologies, sro
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.12 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 
209 namespace TableMapper {
213 
214 public:
215  public :
217  const OptionKeys = Mapper::OptionKeys + (
218  "unstable_input": sprintf("if this is set to True then a slower insert method will be used that verifies each input row; if False an optimized insert method is used (additionally bulk inserts are possible) but all input hashes must have the same keys in the same order; default: %y", OptionDefaults.unstable_input),
219  "insert_block": sprintf("the row block size used when bulk DML / batch inserts are used; default: %y", OptionDefaults.insert_block),
220  "rowcode": "a closure or call reference taking a single hash argument representing the row values inserted plus any output values generated in the insert (such as sequence values, for example)",
221  );
222 
224  const OptionDefaults = (
225  "unstable_input": False,
226  "insert_block": 1000,
227  );
228 
229 public:
230 
231  private :
234 
237 
240 
243 
246 
249 
251  SQLStatement stmt;
252 
255 
258 
260  *code rowcode;
261 
262 public:
263 
265 
295  constructor(SqlUtil::Table target, hash mapv, *hash opts);
296 
297 
299 
331  constructor(SqlUtil::AbstractTable target, hash mapv, *hash opts);
332 
333 
335 
337  destructor();
338 
339 
341  static hash getOutputRecord(*string mname, AbstractTable table, *hash output);
342 
344  private init(hash mapv, *hash opts);
345 
346 
348  private mapFieldType(string key, hash m, reference v, hash rec);
349 
350 
352 
355  private checkMapField(string k, reference fh);
356 
357 
359 
361  hash validTypes();
362 
363 
365 
367  hash validKeys();
368 
369 
371 
373  hash optionKeys();
374 
375 
377 
385  hash insertRow(hash rec);
386 
387 
389 
401  setRowCode(*code rowc);
402 
403 
405 
440  *hash queueData(hash rec, *hash crec);
441 
442 
444 
479  *hash queueData(AbstractIterator iter, *hash crec);
480 
481 
483 
494  private *hash queueDataIntern(hash rec);
495 
496 
498 
521  *hash flush();
522 
523 
525 
546  discard();
547 
548 
550  private hash flushIntern();
551 
552 
554  *list getReturning();
555 
556 
558  logOutput(hash h);
559 
560 
562  deprecated hash insertRowNoCommit(hash rec);
563 
565  nothing commit();
566 
567 
569  nothing rollback();
570 
571 
573  string getTableName();
574 
575 
578 
579 
582 
583 
585  private error(string fmt);
586 
587 
589  private error2(string ex, string fmt);
590 
591  };
592 
595 
596 public:
598 
617  constructor(SqlUtil::Table target, hash mapv = {}, *hash opts) ;
618 
619 
621 
641  constructor(SqlUtil::AbstractTable target, hash mapv = {}, *hash opts) ;
642 
643 
645  private init(hash mapv, *hash opts);
646 
647 
650  };
651 
654 
655 public:
656  public :
657 
658 public:
659 
660  private :
663 
666 
668  int cnt = 0;
669 
672 
673 public:
674 
676 
704  constructor(Qore::AbstractIterator i, SqlUtil::Table target, hash mapv, *hash opts, int commit_limit = 0) ;
705 
706 
708 
736  constructor(Qore::AbstractIterator i, SqlUtil::AbstractTable target, hash mapv, *hash opts, int commit_limit = 0) ;
737 
738 
740 
764 
765 
767  hash getValue();
768 
769 
771 
775  bool next();
776 
777 
779  int commitLimit();
780 
781 
783  nothing commit();
784 
785 
787  nothing rollback();
788 
789 
791  string getTableName();
792 
793 
795 
797  int getCount();
798 
799 
801 
803  resetCount();
804 
805 
808 
809  };
810 
812 
817 
818 public:
819  public :
820 
821 public:
822 
823  private :
826 
827 public:
828 
830 
837  constructor(SqlUtil::AbstractTable table, hash sh, hash mapv, *hash opts)
838  ;
839 
840 
842 
849  constructor(SqlUtil::Table table, hash sh, hash mapv, *hash opts)
850  ;
851 
852 
854 
858  constructor(Qore::SQL::SQLStatement stmt, hash mapv, *hash opts)
859  ;
860 
861 
862  private setup(hash mapv, *hash opts);
863 
864 
866  hash getValue();
867 
868 
870 
872  int getCount();
873 
874 
876 
878  resetCount();
879 
880 
882  bool hasBulk();
883 
884 
886 
890  list mapBulk(int size);
891 
892  }; // class SqlStatementMapperIterator
893 
896 
897 public:
898  public :
900  const OptionKeys = Mapper::OptionKeys + (
901  "table": "(required) the AbstractTable object for the source of the data",
902  "sh": "(optional) an SqlUtil select hash",
903  "select_block" : sprintf("the row block size used when bulk DML / batch inserts are used; default: %y", OptionDefaults.select_block),
904  );
905 
907  const OptionDefaults = (
908  "select_block": 1000,
909  );
910 
911 public:
912 
913  private :
914  // internal SQLStatement
915  SQLStatement m_stmt;
916  // a select_block size. Taken from options
917  int select_block;
918  // original option hash
919  *hash m_orig_opts;
920 
921 public:
922 
924 
934  constructor(hash mapv, *hash opts);
935 
936 
938 
940  hash optionKeys();
941 
942 
944  commit();
945 
946 
948  rollback();
949 
950 
953 
955  abstract private initOptions(reference opts);
956 
958  abstract private initStatement();
959 
961 
967 
968 
970 
979  *hash getData();
980 
981 
983 
991  *list getDataRows();
992 
993 
994  }; // AbstractSqlStatementOutboundMapper
995 
998 
999 public:
1000  private :
1001  // the target table object
1002  SqlUtil::AbstractTable m_table;
1003  // SqlUtil select hash
1004  *hash m_sh;
1005 
1006 public:
1007 
1009 
1019  constructor(SqlUtil::Table source, *hash sh, hash mapv, *hash opts)
1020  ;
1021 
1022 
1024 
1034  constructor(SqlUtil::AbstractTable source, *hash sh, hash mapv, *hash opts)
1035  ;
1036 
1037 
1039 
1041  string getTableName();
1042 
1043 
1045 
1048 
1049 
1052 
1053 
1055  static *hash getStaticInputRecord(AbstractTable table, *hash select_hash, *reference sql);
1056 
1058  initStatement();
1059 
1060 
1062  private initOptions(reference opts);
1063 
1064  }; // SqlStatementOutboundMapper
1065 
1068 
1069 public:
1070  private :
1071  AbstractDatasource m_ds;
1072  string m_sql;
1073  *list m_sqlargs;
1074 
1075 public:
1076 
1078 
1108  constructor(Qore::SQL::AbstractDatasource ds, string sql, *softlist sqlargs, hash mapv, *hash opts)
1109  ;
1110 
1111 
1114 
1115 
1117  static *hash getStaticInputRecord(Qore::SQL::AbstractDatasource ds, string sql, *softlist args);
1118 
1120  private initStatement();
1121 
1122 
1124  private initOptions(reference opts);
1125 
1126  }; // RawSqlStatementOutboundMapper
1127 };
abstract Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
string getTableName()
returns the table name
commit()
commits the transaction and frees the Qore::SQL::AbstractDatasource transaction thread resource ...
Qore::AbstractIterator i
int commitLimit()
returns the commit_limit value set in the constructor()
nothing commit()
commits the transaction
string sprintf(string fmt,...)
string getTableName()
returns the table name
hash getValue()
returns the current row transformed with the mapper
*hash getOutputRecord()
private init(hash mapv, *hash opts)
common constructor initialization
*hash queueData(hash rec, *hash crec)
inserts a row (or a set of rows, in case a hash of lists is passed) into the block buffer based on a ...
provides a hash iterator based on a InboundTableMapper object and an iterator input source; for each ...
Definition: TableMapper.qm.dox.h:653
int commit_limit
row commit limit (<= 0 for no commits)
Definition: TableMapper.qm.dox.h:665
private init(hash mapv, *hash opts)
common constructor initialization
private hash flushIntern()
flushes queued data to the database
*list getReturning()
returns a list argument for the SqlUtil "returning" option, if applicable
static *hash getStaticInputRecord(Qore::SQL::AbstractDatasource ds, string sql, *softlist args)
returns a description of the input record based on Qore::SQL::SQLStatement::describe() ...
private error2(string ex, string fmt)
prepends the datasource description to the error description and calls Mapper::error2() ...
Mapper::Mapper m_mapper
data mapper
Definition: TableMapper.qm.dox.h:825
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
static *hash getStaticInputRecord(AbstractTable table, *hash select_hash, *reference sql)
returns a description of the input record based on Qore::SQL::SQLStatement::describe() ...
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
provides an outbound data mapper to a Table with SqlUtil select hash as a asource ...
Definition: TableMapper.qm.dox.h:997
destructor()
throws an exception if there is data pending in the block cache
hash hbuf
buffer for bulk inserts
Definition: TableMapper.qm.dox.h:257
SqlUtil::AbstractTable getTable()
returns the underlying SqlUtil::AbstractTable object
hash validKeys()
returns a list of valid field keys for this class (can be overridden in subclasses) ...
bool next()
Moves the current position of the input iterator to the next element; returns False if there are no m...
hash optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses) ...
initStatement()
initializes the internal statement object
static hash getStaticInputRecord(SqlUtil::AbstractTable table)
returns a description of the input record based on the AbstractTable source
provides an outbound data mapper to a raw SQL statement
Definition: TableMapper.qm.dox.h:1067
nothing rollback()
discards any queued data and rolls back the transaction
resetCount()
resets the internal record count
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
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:671
const OptionDefaults
default option values
Definition: TableMapper.qm.dox.h:907
*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:224
const False
abstract private initStatement()
re-implement to initialize Qore::SQL::SQLStatement on demand
bool hasBulk()
returns True because this class supports bulk mode
private *hash queueDataIntern(hash rec)
inserts a row into the block buffer based on a mapped input record; does not commit the transaction ...
list list(...)
bool has_returning
if the AbstractTable object supports the "returning" clause
Definition: TableMapper.qm.dox.h:239
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
const OptionKeys
option keys for this object
Definition: TableMapper.qm.dox.h:217
constructor(Qore::AbstractIterator i, SqlUtil::Table target, hash mapv, *hash opts, int commit_limit=0)
creates the iterator from the arguments passed
resetCount()
resets the internal record count
private checkMapField(string k, reference fh)
perform per-field pre-processing on the passed map in the constructor
deprecated hash insertRowNoCommit(hash rec)
Plain alias to insertRow(). Obsolete. Do not use.
private initOptions(reference opts)
initializes options
SqlUtil::AbstractTable getTable()
returns the underlying SqlUtil::AbstractTable object
nothing rollback()
rolls back the transaction
int getCount()
returns the internal record count
private error(string fmt)
prepends the datasource description to the error string and calls Mapper::error() ...
int getCount()
returns the internal record count
nothing commit()
flushes any queued data and commits the transaction
int cnt
row count for commit
Definition: TableMapper.qm.dox.h:668
const OptionKeys
option keys for this object
Definition: TableMapper.qm.dox.h:900
private initStatement()
initializes the internal statement object
SqlUtil::AbstractDatabase db
the target Database object in case sequence value need to be acquired
Definition: TableMapper.qm.dox.h:236
bool unstable_input
"unstable input" option for non-optimized inserts (~33% performance reduction in insert speed) ...
Definition: TableMapper.qm.dox.h:248
maps from source to target tables with exactly the same structure
Definition: TableMapper.qm.dox.h:594
hash getValue()
returns the current row transformed with the mapper
private initOptions(reference opts)
initializes options
the TableMapper namespace contains all the definitions in the TableMapper module
Definition: TableMapper.qm.dox.h:210
provides an abstract base for all SQL based outbound mappers
Definition: TableMapper.qm.dox.h:895
constructor(SqlUtil::AbstractTable table, hash sh, hash mapv, *hash opts)
creates the iterator from the arguments passed
list mapBulk(int size)
performs bulk mapping by selecting the requested number of rows in a single select ...
hash optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses) ...
*list getDataRows()
Retrieve mapped data as a hash of lists.
private constructor()
*hash getData()
Retrieve mapped data as a hash of lists.
list ret_args
"returning" arguments for sequences
Definition: TableMapper.qm.dox.h:242
rollback()
rolls the transaction back and frees the Qore::SQL::AbstractDatasource transaction thread resource ...
provides a hash iterator based on a mapper object and an SQLStatement or SqlUtil select hash ...
Definition: TableMapper.qm.dox.h:816
provides an inbound data mapper to a Table target
Definition: TableMapper.qm.dox.h:212
SqlStatementMapperIterator iterator()
Returns an SqlStatementMapperIterator based on the current object.
discard()
discards any buffered batched data; this method should be called after using the batch APIs (queueDat...
hash insertRow(hash rec)
inserts a row into the target table based on a mapped input record; does not commit the transaction ...
string getTableName()
returns the table name
TableMapper::InboundTableMapper mapc
data mapper
Definition: TableMapper.qm.dox.h:662
hash hash(object obj)
list out_args
extra arguments for sequence output binds
Definition: TableMapper.qm.dox.h:245
int insert_block
bulk insert block size
Definition: TableMapper.qm.dox.h:254
SQLStatement stmt
statement for inserts
Definition: TableMapper.qm.dox.h:251
abstract private initOptions(reference opts)
re-implement to initialize options
SqlUtil::AbstractTable table
the target table object
Definition: TableMapper.qm.dox.h:233
logOutput(hash h)
ignore logging from Mapper since we may have to log sequence values; output logged manually in insert...
private mapFieldType(string key, hash m, reference v, hash rec)
performs type handling
*code rowcode
per-row Closures or Call References for batch inserts
Definition: TableMapper.qm.dox.h:260
setRowCode(*code rowc)
sets a closure or call reference that will be called when data has been sent to the database and all ...