Qore TableMapper Module Reference  1.1
 All Classes Namespaces Functions Variables Groups Pages
TableMapper::InboundIdentityTableMapper Class Reference

maps from source to target tables with exactly the same structure More...

Inheritance diagram for TableMapper::InboundIdentityTableMapper:

Public Member Functions

 constructor (SqlUtil::Table target, hash mapv={}, *hash opts)
 builds the object based on an optional hash providing field mappings, data constraints, and optionally custom mapping logic More...
 
 constructor (SqlUtil::AbstractTable target, hash mapv={}, *hash opts)
 builds the object based on an optional hash providing field mappings, data constraints, and optionally custom mapping logic More...
 
private init (hash mapv, *hash opts)
 common constructor initialization
 
- Public Member Functions inherited from TableMapper::InboundTableMapper
private checkMapField (string k, reference fh)
 perform per-field pre-processing on the passed map in the constructor More...
 
nothing commit ()
 flushes any queued data and commits the transaction
 
 constructor (SqlUtil::Table target, hash mapv, *hash opts)
 builds the object based on a hash providing field mappings, data constraints, and optionally custom mapping logic More...
 
 constructor (SqlUtil::AbstractTable target, hash mapv, *hash opts)
 builds the object based on a hash providing field mappings, data constraints, and optionally custom mapping logic More...
 
 destructor ()
 throws an exception if there is data pending in the block cache More...
 
 discard ()
 discards any buffered batched data; this method should be called after using the batch APIs (queueData()) and an error occurs More...
 
private error (string fmt)
 prepends the datasource description to the error string and calls Mapper::error()
 
private error2 (string ex, string fmt)
 prepends the datasource description to the error description and calls Mapper::error2()
 
*hash flush ()
 flushes any remaining batched data to the database; this method should always be called before committing the transaction or destroying the object More...
 
private hash flushIntern ()
 flushes queued data to the database
 
Qore::SQL::AbstractDatasource getDatasource ()
 returns the AbstractDatasource object associated with this object
 
*list getReturning ()
 returns a list argument for the SqlUtil "returning" option, if applicable
 
SqlUtil::AbstractTable getTable ()
 returns the underlying SqlUtil::AbstractTable object
 
string getTableName ()
 returns the table name
 
private init (hash mapv, *hash opts)
 common constructor initialization
 
hash insertRow (hash rec)
 inserts a row into the target table based on a mapped input record; does not commit the transaction More...
 
deprecated hash insertRowNoCommit (hash rec)
 Plain alias to insertRow(). Obsolete. Do not use.
 
 logOutput (hash h)
 ignore logging from Mapper since we may have to log sequence values; output logged manually in insertRow()
 
private mapFieldType (string key, hash m, reference v, hash rec)
 performs type handling
 
hash optionKeys ()
 returns a list of valid constructor options for this class (can be overridden in subclasses) More...
 
*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 mapped input record; the block buffer is flushed to the DB if the buffer size reaches the limit defined by the "insert_block" option; does not commit the transaction More...
 
*hash queueData (AbstractIterator iter, *hash crec)
 inserts a set of rows (list of hashes) into the block buffer based on a mapped input record; the block buffer is flushed to the DB if the buffer size reaches the limit defined by the "insert_block" option; does not commit the transaction More...
 
private *hash queueDataIntern (hash rec)
 inserts a row into the block buffer based on a mapped input record; does not commit the transaction More...
 
nothing rollback ()
 discards any queued data and rolls back the transaction
 
 setRowCode (*code rowc)
 sets a closure or call reference that will be called when data has been sent to the database and all output data is available; must accept a hash argument that represents the data written to the database including any output arguments. This code will be reset, once the transaction is commited. More...
 
hash validKeys ()
 returns a list of valid field keys for this class (can be overridden in subclasses) More...
 
hash validTypes ()
 returns a list of valid field types for this class (can be overridden in subclasses) More...
 

Static Public Member Functions

static hash getStaticInputRecord (SqlUtil::AbstractTable table)
 returns a description of the input record based on the AbstractTable source
 
- Static Public Member Functions inherited from TableMapper::InboundTableMapper
static hash getOutputRecord (*string mname, AbstractTable table, *hash output)
 returns a description of the output record based on the AbstractTable target
 

Additional Inherited Members

- Public Attributes inherited from TableMapper::InboundTableMapper
const OptionDefaults
 default option values
 
const OptionKeys
 option keys for this object
 

Detailed Description

maps from source to target tables with exactly the same structure

Member Function Documentation

TableMapper::InboundIdentityTableMapper::constructor ( SqlUtil::Table  target,
hash  mapv = {},
*hash  opts 
)

builds the object based on an optional hash providing field mappings, data constraints, and optionally custom mapping logic

The target table is also scanned using SqlUtil and column definitions are used to update the target record specification, also if there are any columns with NOT NULL constraints and no default value, mapping, or constant value, then a MAP-ERROR exception is thrown

Example:
1 const DbMapper = (
2  "id": ("sequence": "seq_inventory_example"),
3  );
4 
5 InboundIdentityTableMapper mapper(table, DbMapper);
Parameters
targetthe target table object
mapva optional hash providing overrides for the default 1:1 input to output field mappings; each hash key is the name in lower case of the output column in the target table; each value is either True (meaning no translations are done; the data is copied 1:1) or a hash describing the mapping; see Mapper Specification Format for detailed documentation for this option
optsan optional hash of options for the mapper; see Mapper Options for a description of valid mapper options plus the following options specific to this object:
  • "unstable_input": set this option to True (default False) if the input passed to the mapper is unstable, meaning that different hash keys or a different hash key order can be passed as input data in each call to insertRow(); if this option is set, then insert speed will be reduced by about 33%; when this option is not set, an optimized insert approach is used which allows for better performance
  • "insert_block": for DB drivers supporting bulk DML (for use with the queueData(), flush(), and discard() methods), the number of rows inserted at once (default: 1000, only used when "unstable_input" is False) and bulk inserts are supported in the table object; see InboundTableMapper Bulk Insert API for more information
Exceptions
MAP-ERRORthe map hash has a logical error (ex: "trunc" key given without "maxlen", invalid map key)
TableMapper::InboundIdentityTableMapper::constructor ( SqlUtil::AbstractTable  target,
hash  mapv = {},
*hash  opts 
)

builds the object based on an optional hash providing field mappings, data constraints, and optionally custom mapping logic

The target table is also scanned using SqlUtil and column definitions are used to update the target record specification, also if there are any columns with NOT NULL constraints and no default value, mapping, or constant value, then a MAP-ERROR exception is thrown

Example:
1 const DbMapper = (
2  "id": ("sequence": "seq_inventory_example"),
3  );
4 
5 InboundIdentityTableMapper mapper(table, DbMapper);
Parameters
targetthe target table object
mapva hash providing field mappings; each hash key is the name of the output field; each value is either True (meaning no translations are done; the data is copied 1:1) or a hash describing the mapping; see Mapper Specification Format for detailed documentation for this option
optsan optional hash of options for the mapper; see Mapper Options for a description of valid mapper options plus the following options specific to this object:
  • "unstable_input": set this option to True (default False) if the input passed to the mapper is unstable, meaning that different hash keys or a different hash key order can be passed as input data in each call to insertRow(); if this option is set, then insert speed will be reduced by about 33%; when this option is not set, an optimized insert approach is used which allows for better performance
  • "insert_block": for DB drivers supporting bulk DML (for use with the queueData(), flush(), and discard() methods), the number of rows inserted at once (default: 1000, only used when "unstable_input" is False) and bulk inserts are supported in the table object; see InboundTableMapper Bulk Insert API for more information
Exceptions
MAP-ERRORthe map hash has a logical error (ex: "trunc" key given without "maxlen", invalid map key)
TABLE-ERRORthe table includes a column using an unknown native data type