TableMapper.qm.dox.h
// -*- mode: c++; indent-tabs-mode: nil -*-
/* TableMapper.qm Copyright 2014 - 2016 Qore Technologies, sro
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in
all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
*/
// this module requires Qore 0.8.12 or better
// require type definitions everywhere
// enable all warnings
// don't use "$" signs for variables and class members, assume local variable scope
// requires the Mapper module
// requires the SqlUtil module
namespace TableMapper {
class InboundTableMapper : public Mapper::Mapper {
public:
public :
const OptionKeys = Mapper::OptionKeys + (
"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),
"insert_block": sprintf("the row block size used when bulk DML / batch inserts are used; default: %y", OptionDefaults.insert_block),
"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)",
);
const OptionDefaults = (
"unstable_input": False,
"insert_block": 1000,
);
public:
private :
SqlUtil::AbstractTable table;
SqlUtil::AbstractDatabase db;
bool has_returning;
list ret_args = ();
list out_args = ();
bool unstable_input = False;
SQLStatement stmt;
int insert_block;
hash hbuf;
*code rowcode;
public:
constructor(SqlUtil::Table target, hash mapv, *hash opts);
constructor(SqlUtil::AbstractTable target, hash mapv, *hash opts);
destructor();
static hash getOutputRecord(*string mname, AbstractTable table, *hash output);
private init(hash mapv, *hash opts);
private mapFieldType(string key, hash m, reference v, hash rec);
private checkMapField(string k, reference fh);
hash validTypes();
hash validKeys();
hash optionKeys();
hash insertRow(hash rec);
setRowCode(*code rowc);
*hash queueData(hash rec, *hash crec);
*hash queueData(AbstractIterator iter, *hash crec);
private *hash queueDataIntern(hash rec);
*hash flush();
discard();
private hash flushIntern();
*list getReturning();
logOutput(hash h);
deprecated hash insertRowNoCommit(hash rec);
nothing commit();
nothing rollback();
string getTableName();
SqlUtil::AbstractTable getTable();
Qore::SQL::AbstractDatasource getDatasource();
private error(string fmt);
private error2(string ex, string fmt);
};
class InboundIdentityTableMapper : public TableMapper::InboundTableMapper {
public:
constructor(SqlUtil::Table target, hash mapv = {}, *hash opts) ;
constructor(SqlUtil::AbstractTable target, hash mapv = {}, *hash opts) ;
private init(hash mapv, *hash opts);
static hash getStaticInputRecord(SqlUtil::AbstractTable table);
};
class InboundTableMapperIterator : public Mapper::AbstractMapperIterator {
public:
public :
public:
private :
TableMapper::InboundTableMapper mapc;
int commit_limit;
int cnt = 0;
hash val;
public:
constructor(Qore::AbstractIterator i, SqlUtil::Table target, hash mapv, *hash opts, int commit_limit = 0) ;
constructor(Qore::AbstractIterator i, SqlUtil::AbstractTable target, hash mapv, *hash opts, int commit_limit = 0) ;
constructor(Qore::AbstractIterator i, TableMapper::InboundTableMapper mapv, int commit_limit = 0) ;
hash getValue();
bool next();
int commitLimit();
nothing commit();
nothing rollback();
string getTableName();
int getCount();
resetCount();
Qore::SQL::AbstractDatasource getDatasource();
};
class SqlStatementMapperIterator : public Mapper::AbstractMapperIterator {
public:
public :
public:
private :
Mapper::Mapper m_mapper;
public:
constructor(SqlUtil::AbstractTable table, hash sh, hash mapv, *hash opts)
;
constructor(SqlUtil::Table table, hash sh, hash mapv, *hash opts)
;
constructor(Qore::SQL::SQLStatement stmt, hash mapv, *hash opts)
;
private setup(hash mapv, *hash opts);
hash getValue();
int getCount();
resetCount();
bool hasBulk();
list mapBulk(int size);
}; // class SqlStatementMapperIterator
class AbstractSqlStatementOutboundMapper : public Mapper::Mapper {
public:
public :
const OptionKeys = Mapper::OptionKeys + (
"select_block" : sprintf("the row block size used when bulk DML / batch inserts are used; default: %y", OptionDefaults.select_block),
);
const OptionDefaults = (
"select_block": 1000,
);
public:
private :
// internal SQLStatement
SQLStatement m_stmt;
// a select_block size. Taken from options
int select_block;
public:
constructor(hash mapv, *hash opts);
hash optionKeys();
commit();
rollback();
abstract Qore::SQL::AbstractDatasource getDatasource();
abstract private initOptions(reference opts);
abstract private initStatement();
Mapper::MapperIterator iterator();
*hash getData();
*list getDataRows();
}; // AbstractSqlStatementOutboundMapper
class SqlStatementOutboundMapper : public AbstractSqlStatementOutboundMapper {
public:
private :
// the target table object
SqlUtil::AbstractTable m_table;
// SqlUtil select hash
*hash m_sh;
public:
constructor(SqlUtil::Table source, *hash sh, hash mapv, *hash opts)
;
constructor(SqlUtil::AbstractTable source, *hash sh, hash mapv, *hash opts)
;
string getTableName();
SqlUtil::AbstractTable getTable();
Qore::SQL::AbstractDatasource getDatasource();
static *hash getStaticInputRecord(AbstractTable table, *hash select_hash, *reference sql);
initStatement();
private initOptions(reference opts);
}; // SqlStatementOutboundMapper
class RawSqlStatementOutboundMapper : public AbstractSqlStatementOutboundMapper {
public:
private :
AbstractDatasource m_ds;
string m_sql;
*list m_sqlargs;
public:
constructor(AbstractDatasource ds, string sql, *softlist sqlargs, hash mapv, *hash opts)
;
Qore::SQL::AbstractDatasource getDatasource();
static *hash getStaticInputRecord(AbstractDatasource ds, string sql, *softlist args);
private initStatement();
private initOptions(reference opts);
}; // RawSqlStatementOutboundMapper
};
TableMapper::AbstractSqlStatementOutboundMapper::getDatasource
abstract Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
TableMapper::InboundTableMapperIterator::getTableName
string getTableName()
returns the table name
TableMapper::AbstractSqlStatementOutboundMapper::commit
commit()
commits the transaction and frees the AbstractDatasource resource
Mapper::AbstractMapperIterator::i
Qore::AbstractIterator i
TableMapper::InboundTableMapperIterator::commitLimit
int commitLimit()
returns the commit_limit value set in the constructor()
TableMapper::InboundTableMapperIterator::commit
nothing commit()
commits the transaction
TableMapper::RawSqlStatementOutboundMapper::getStaticInputRecord
static *hash getStaticInputRecord(AbstractDatasource ds, string sql, *softlist args)
returns a description of the input record based on Qore::SQL::SQLStatement::describe() ...
sprintf
string sprintf(string fmt,...)
TableMapper::InboundTableMapper::getTableName
string getTableName()
returns the table name
TableMapper::SqlStatementMapperIterator::getValue
hash getValue()
returns the current row transformed with the mapper
Mapper::Mapper::getOutputRecord
*hash getOutputRecord()
SqlUtil::AbstractTable
TableMapper::InboundTableMapper::init
private init(hash mapv, *hash opts)
common constructor initialization
TableMapper::InboundTableMapper::queueData
*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 ...
TableMapper::InboundTableMapperIterator
provides a hash iterator based on a InboundTableMapper object and an iterator input source; for each ...
Definition: TableMapper.qm.dox.h:653
TableMapper::InboundTableMapperIterator::commit_limit
int commit_limit
row commit limit (<= 0 for no commits)
Definition: TableMapper.qm.dox.h:665
TableMapper::InboundIdentityTableMapper::init
private init(hash mapv, *hash opts)
common constructor initialization
TableMapper::InboundTableMapper::flushIntern
private hash flushIntern()
flushes queued data to the database
TableMapper::InboundTableMapper::getReturning
*list getReturning()
returns a list argument for the SqlUtil "returning" option, if applicable
TableMapper::InboundTableMapper::error2
private error2(string ex, string fmt)
prepends the datasource description to the error description and calls Mapper::error2() ...
TableMapper::SqlStatementMapperIterator::m_mapper
Mapper::Mapper m_mapper
data mapper
Definition: TableMapper.qm.dox.h:825
TableMapper::RawSqlStatementOutboundMapper::getDatasource
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
TableMapper::SqlStatementOutboundMapper::getStaticInputRecord
static *hash getStaticInputRecord(AbstractTable table, *hash select_hash, *reference sql)
returns a description of the input record based on Qore::SQL::SQLStatement::describe() ...
TableMapper::InboundTableMapperIterator::getDatasource
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
TableMapper::SqlStatementOutboundMapper
provides an outbound data mapper to a Table with SqlUtil select hash as a asource ...
Definition: TableMapper.qm.dox.h:991
TableMapper::InboundTableMapper::destructor
destructor()
throws an exception if there is data pending in the block cache
TableMapper::InboundTableMapper::hbuf
hash hbuf
buffer for bulk inserts
Definition: TableMapper.qm.dox.h:257
TableMapper::SqlStatementOutboundMapper::getTable
SqlUtil::AbstractTable getTable()
returns the underlying SqlUtil::AbstractTable object
TableMapper::InboundTableMapper::validKeys
hash validKeys()
returns a list of valid field keys for this class (can be overridden in subclasses) ...
TableMapper::InboundTableMapperIterator::next
bool next()
Moves the current position of the input iterator to the next element; returns False if there are no m...
TableMapper::InboundTableMapper::optionKeys
hash optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses) ...
TableMapper::SqlStatementOutboundMapper::initStatement
initStatement()
initializes the internal statement object
TableMapper::InboundIdentityTableMapper::getStaticInputRecord
static hash getStaticInputRecord(SqlUtil::AbstractTable table)
returns a description of the input record based on the AbstractTable source
Mapper::MapperIterator
TableMapper::RawSqlStatementOutboundMapper
provides an outbound data mapper to a raw SQL statement
Definition: TableMapper.qm.dox.h:1061
TableMapper::InboundTableMapper::rollback
nothing rollback()
discards any queued data and rolls back the transaction
TableMapper::AbstractSqlStatementOutboundMapper::iterator
Mapper::MapperIterator iterator()
Get MapperIterator for easy line-by-line processing.
TableMapper::SqlStatementMapperIterator::resetCount
resetCount()
resets the internal record count
TableMapper::SqlStatementOutboundMapper::getDatasource
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
TableMapper::InboundTableMapper::validTypes
hash validTypes()
returns a list of valid field types for this class (can be overridden in subclasses) ...
TableMapper::InboundTableMapperIterator::val
hash val
a copy of the last hash value mapped
Definition: TableMapper.qm.dox.h:671
TableMapper::AbstractSqlStatementOutboundMapper::OptionDefaults
const OptionDefaults
default option values
Definition: TableMapper.qm.dox.h:905
TableMapper::InboundTableMapper::flush
*hash flush()
flushes any remaining batched data to the database; this method should always be called before commit...
TableMapper::InboundTableMapper::OptionDefaults
const OptionDefaults
default option values
Definition: TableMapper.qm.dox.h:224
False
const False
TableMapper::AbstractSqlStatementOutboundMapper::initStatement
abstract private initStatement()
re-implement to initialize Qore::SQL::SQLStatement on demand
TableMapper::SqlStatementMapperIterator::hasBulk
bool hasBulk()
returns True because this class supports bulk mode
Qore::SQL::AbstractDatasource
TableMapper::InboundTableMapper::queueDataIntern
private *hash queueDataIntern(hash rec)
inserts a row into the block buffer based on a mapped input record; does not commit the transaction ...
Mapper::Mapper
list
list list(...)
TableMapper::InboundTableMapper::has_returning
bool has_returning
if the AbstractTable object supports the "returning" clause
Definition: TableMapper.qm.dox.h:239
TableMapper::InboundTableMapper::getDatasource
Qore::SQL::AbstractDatasource getDatasource()
returns the AbstractDatasource object associated with this object
TableMapper::InboundTableMapper::OptionKeys
const OptionKeys
option keys for this object
Definition: TableMapper.qm.dox.h:217
Qore::SQL::SQLStatement
TableMapper::InboundTableMapperIterator::constructor
constructor(Qore::AbstractIterator i, SqlUtil::Table target, hash mapv, *hash opts, int commit_limit=0)
creates the iterator from the arguments passed
TableMapper::InboundTableMapperIterator::resetCount
resetCount()
resets the internal record count
TableMapper::InboundTableMapper::checkMapField
private checkMapField(string k, reference fh)
perform per-field pre-processing on the passed map in the constructor
TableMapper::InboundTableMapper::insertRowNoCommit
deprecated hash insertRowNoCommit(hash rec)
Plain alias to insertRow(). Obsolete. Do not use.
TableMapper::SqlStatementOutboundMapper::initOptions
private initOptions(reference opts)
initializes options
TableMapper::InboundTableMapper::getTable
SqlUtil::AbstractTable getTable()
returns the underlying SqlUtil::AbstractTable object
Mapper::AbstractMapperIterator
TableMapper::InboundTableMapperIterator::rollback
nothing rollback()
rolls back the transaction
TableMapper::InboundTableMapperIterator::getCount
int getCount()
returns the internal record count
TableMapper::InboundTableMapper::error
private error(string fmt)
prepends the datasource description to the error string and calls Mapper::error() ...
TableMapper::SqlStatementMapperIterator::getCount
int getCount()
returns the internal record count
TableMapper::InboundTableMapper::commit
nothing commit()
flushes any queued data and commits the transaction
TableMapper::InboundTableMapperIterator::cnt
int cnt
row count for commit
Definition: TableMapper.qm.dox.h:668
TableMapper::AbstractSqlStatementOutboundMapper::OptionKeys
const OptionKeys
option keys for this object
Definition: TableMapper.qm.dox.h:900
TableMapper::RawSqlStatementOutboundMapper::initStatement
private initStatement()
initializes the internal statement object
TableMapper::InboundTableMapper::db
SqlUtil::AbstractDatabase db
the target Database object in case sequence value need to be acquired
Definition: TableMapper.qm.dox.h:236
TableMapper::InboundTableMapper::unstable_input
bool unstable_input
"unstable input" option for non-optimized inserts (~33% performance reduction in insert speed) ...
Definition: TableMapper.qm.dox.h:248
TableMapper::InboundIdentityTableMapper
maps from source to target tables with exactly the same structure
Definition: TableMapper.qm.dox.h:594
Mapper::Mapper::output
*hash output
TableMapper::InboundTableMapperIterator::getValue
hash getValue()
returns the current row transformed with the mapper
TableMapper::RawSqlStatementOutboundMapper::initOptions
private initOptions(reference opts)
initializes options
TableMapper
the TableMapper namespace contains all the definitions in the TableMapper module
Definition: TableMapper.qm.dox.h:210
TableMapper::AbstractSqlStatementOutboundMapper
provides an abstract base for all SQL based outbound mappers
Definition: TableMapper.qm.dox.h:895
TableMapper::SqlStatementMapperIterator::constructor
constructor(SqlUtil::AbstractTable table, hash sh, hash mapv, *hash opts)
creates the iterator from the arguments passed
TableMapper::SqlStatementMapperIterator::mapBulk
list mapBulk(int size)
performs bulk mapping by selecting the requested number of rows in a single select ...
TableMapper::AbstractSqlStatementOutboundMapper::optionKeys
hash optionKeys()
returns a list of valid constructor options for this class (can be overridden in subclasses) ...
TableMapper::AbstractSqlStatementOutboundMapper::getDataRows
*list getDataRows()
Retrieve mapped data as a hash of lists.
Mapper::Mapper::constructor
private constructor()
TableMapper::AbstractSqlStatementOutboundMapper::getData
*hash getData()
Retrieve mapped data as a hash of lists.
SqlUtil::Table
TableMapper::InboundTableMapper::ret_args
list ret_args
"returning" arguments for sequences
Definition: TableMapper.qm.dox.h:242
TableMapper::AbstractSqlStatementOutboundMapper::rollback
rollback()
rolls the transaction back and frees the AbstractDatasource resource
TableMapper::SqlStatementMapperIterator
provides a hash iterator based on a mapper object and an SQLStatement or SqlUtil select hash ...
Definition: TableMapper.qm.dox.h:816
TableMapper::InboundTableMapper
provides an inbound data mapper to a Table target
Definition: TableMapper.qm.dox.h:212
TableMapper::InboundTableMapper::discard
discard()
discards any buffered batched data; this method should be called after using the batch APIs (queueDat...
TableMapper::InboundTableMapper::insertRow
hash insertRow(hash rec)
inserts a row into the target table based on a mapped input record; does not commit the transaction ...
TableMapper::SqlStatementOutboundMapper::getTableName
string getTableName()
returns the table name
TableMapper::InboundTableMapperIterator::mapc
TableMapper::InboundTableMapper mapc
data mapper
Definition: TableMapper.qm.dox.h:662
hash
hash hash(object obj)
TableMapper::InboundTableMapper::out_args
list out_args
extra arguments for sequence output binds
Definition: TableMapper.qm.dox.h:245
TableMapper::InboundTableMapper::insert_block
int insert_block
bulk insert block size
Definition: TableMapper.qm.dox.h:254
SqlUtil::AbstractDatabase
TableMapper::InboundTableMapper::stmt
SQLStatement stmt
statement for inserts
Definition: TableMapper.qm.dox.h:251
TableMapper::AbstractSqlStatementOutboundMapper::initOptions
abstract private initOptions(reference opts)
re-implement to initialize options
TableMapper::InboundTableMapper::table
SqlUtil::AbstractTable table
the target table object
Definition: TableMapper.qm.dox.h:233
Qore::AbstractIterator
TableMapper::InboundTableMapper::logOutput
logOutput(hash h)
ignore logging from Mapper since we may have to log sequence values; output logged manually in insert...
TableMapper::InboundTableMapper::mapFieldType
private mapFieldType(string key, hash m, reference v, hash rec)
performs type handling
TableMapper::InboundTableMapper::rowcode
*code rowcode
per-row Closures or Call References for batch inserts
Definition: TableMapper.qm.dox.h:260
TableMapper::InboundTableMapper::setRowCode
setRowCode(*code rowc)
sets a closure or call reference that will be called when data has been sent to the database and all ...