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  "select_block" : sprintf("the row block size used when bulk DML / batch inserts are used; default: %y", OptionDefaults.select_block),
902  );
903 
905  const OptionDefaults = (
906  "select_block": 1000,
907  );
908 
909 public:
910 
911  private :
912  // internal SQLStatement
913  SQLStatement m_stmt;
914  // a select_block size. Taken from options
915  int select_block;
916 
917 public:
918 
920 
928  constructor(hash mapv, *hash opts);
929 
930 
932 
934  hash optionKeys();
935 
936 
938  commit();
939 
940 
942  rollback();
943 
944 
947 
949  abstract private initOptions(reference opts);
950 
952  abstract private initStatement();
953 
955 
961 
962 
964 
973  *hash getData();
974 
975 
977 
985  *list getDataRows();
986 
987 
988  }; // AbstractSqlStatementOutboundMapper
989 
992 
993 public:
994  private :
995  // the target table object
996  SqlUtil::AbstractTable m_table;
997  // SqlUtil select hash
998  *hash m_sh;
999 
1000 public:
1001 
1003 
1013  constructor(SqlUtil::Table source, *hash sh, hash mapv, *hash opts)
1014  ;
1015 
1016 
1018 
1028  constructor(SqlUtil::AbstractTable source, *hash sh, hash mapv, *hash opts)
1029  ;
1030 
1031 
1033 
1035  string getTableName();
1036 
1037 
1039 
1042 
1043 
1046 
1047 
1049  static *hash getStaticInputRecord(AbstractTable table, *hash select_hash, *reference sql);
1050 
1052  initStatement();
1053 
1054 
1056  private initOptions(reference opts);
1057 
1058  }; // SqlStatementOutboundMapper
1059 
1062 
1063 public:
1064  private :
1065  AbstractDatasource m_ds;
1066  string m_sql;
1067  *list m_sqlargs;
1068 
1069 public:
1070 
1072 
1102  constructor(AbstractDatasource ds, string sql, *softlist sqlargs, hash mapv, *hash opts)
1103  ;
1104 
1105 
1108 
1109 
1111  static *hash getStaticInputRecord(AbstractDatasource ds, string sql, *softlist args);
1112 
1114  private initStatement();
1115 
1116 
1118  private initOptions(reference opts);
1119 
1120  }; // RawSqlStatementOutboundMapper
1121 };
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 AbstractDatasource resource
Qore::AbstractIterator i
int commitLimit()
returns the commit_limit value set in the constructor()
nothing commit()
commits the transaction
static *hash getStaticInputRecord(AbstractDatasource ds, string sql, *softlist args)
returns a description of the input record based on Qore::SQL::SQLStatement::describe() ...
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
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:991
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:1061
nothing rollback()
discards any queued data and rolls back the transaction
Mapper::MapperIterator iterator()
Get MapperIterator for easy line-by-line processing.
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:905
*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 AbstractDatasource 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
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 ...