Qore jni Module  1.0.1
org.qore.lang.tablemapper.InboundTableMapper Class Reference

Java wrapper for the TableMapper::InboundTableMapper class in Qore. More...

Inheritance diagram for org.qore.lang.tablemapper.InboundTableMapper:
org.qore.lang.mapper.Mapper org.qore.jni.QoreObjectWrapper org.qore.lang.tablemapper.InboundIdentityTableMapper

Public Member Methods

 InboundTableMapper (QoreObject obj)
 creates the object as a wrapper for the Qore object
 
HashMap< String, Object > insertRow (Map< String, Object > rec) throws Throwable
 inserts or upserts a row into the target table based on a mapped input record; does not commit the transaction More...
 
HashMap< String, Object > queueData (Map< String, Object > rec, Map< String, Object > crec) throws Throwable
 inserts/upserts a row (or a set of rows, in case a Map<String, Object> 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...
 
HashMap< String, Object > queueData (Map< String, Object > rec) throws Throwable
 inserts/upserts a row (or a set of rows, in case a Map<String, Object> 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...
 
HashMap< String, Object > queueData (Map< String, Object >[] l, Map< String, Object > crec) throws Throwable
 inserts/upserts a set of rows (list of hashes representing input records) 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...
 
HashMap< String, Object > queueData (Map< String, Object >[] l) throws Throwable
 inserts/upserts a set of rows (list of hashes representing input records) 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...
 
HashMap< String, Object > flush () throws Throwable
 flushes any remaining batched data to the database; this method should always be called before committing the transaction or destroying the object More...
 
void discard () throws Throwable
 discards any buffered batched data; this method should be called after using the batch APIs (queueData()) and an error occurs More...
 
HashMap< String, Object > [] getReturning () throws Throwable
 returns a list argument for the SqlUtil "returning" option, if applicable
 
void commit () throws Throwable
 flushes any queued data and commits the transaction
 
void rollback () throws Throwable
 discards any queued data and rolls back the transaction
 
String getTableName () throws Throwable
 returns the table name
 
AbstractTable getTable () throws Throwable
 returns the underlying org.qore.lang.sqlutil.AbstractTable object
 
AbstractDatasource getDatasource () throws Throwable
 returns the org.qore.lang.AbstractDatasource object associated with this object
 
- Public Member Methods inherited from org.qore.lang.mapper.Mapper
 Mapper (QoreObject obj)
 creates the object as a wrapper for the Qore object
 
Object getRuntime (String key) throws Throwable
 get current runtime option value for a key More...
 
String getFieldName (String fname) throws Throwable
 returns a descriptive name of the given field if possible, otherwise returns the field name itself
 
HashMap< String, Object > validKeys () throws Throwable
 returns a list of valid field keys for this class (can be overridden in subclasses) More...
 
HashMap< String, Object > validTypes () throws Throwable
 returns a list of valid field types for this class (can be overridden in subclasses) More...
 
HashMap< String, Object > optionKeys () throws Throwable
 returns a list of valid constructor options for this class (can be overridden in subclasses) More...
 
HashMap< String, Object > getInputRecord () throws Throwable
 returns the value of the "input" option More...
 
HashMap< String, Object > getOutputRecord () throws Throwable
 returns the value of the "output" option More...
 
HashMap< String, Object > [] mapAll (Map< String, Object >[] recs) throws Throwable
 maps all input records and returns the mapped data as a list of output records More...
 
HashMap< String, Object > [] mapAll (Map< String, Object > recs) throws Throwable
 maps all input records and returns the mapped data as a list of output records More...
 
HashMap< String, Object > mapData (Map< String, Object > rec) throws Throwable
 processes the input record and returns a Map<String, Object> of the mapped values where the keys in the Map<String, Object> returned are the target field names; the order of the fields in the Map<String, Object> returned is the same order as the keys in the map hash. More...
 
- Public Member Methods inherited from org.qore.jni.QoreObjectWrapper
 QoreObjectWrapper (QoreObject obj)
 creates the wrapper object with the Qore object
 
void release ()
 releases the Qore object; do not call any further methods on the object after this call
 
QoreObject getQoreObject ()
 returns the Qore object
 
String className ()
 returns the class name for the Qore object
 
boolean instanceOf (String class_name)
 returns true if the object is an instance of the given class
 

Additional Inherited Members

- Private Attributes inherited from org.qore.jni.QoreObjectWrapper
QoreObject obj
 the wrapper Qore object
 

Detailed Description

Java wrapper for the TableMapper::InboundTableMapper class in Qore.

Note
Loads and initializes the Qore library and the jni module in static initialization if necessary

Member Function Documentation

◆ discard()

void org.qore.lang.tablemapper.InboundTableMapper.discard ( ) throws Throwable
inline

discards any buffered batched data; this method should be called after using the batch APIs (queueData()) and an error occurs

Example:
{
AbstractTable table = UserApi.get_sql_table("some_table");
try {
table_mapper = UserApi.get_mapper("my_mapper");
try {
table_mapper.queueData(l);
table_mapper.flush();
} catch (Throwable e) {
table_mapper.discard();
} finally {
table_mapper.release();
}
} finally {
table.release();
}
}
Note
  • flush() or discard() needs to be executed for each mapper used in the block when using multiple mappers whereas the DB transaction needs to be committed or rolled back once per datasource
  • also clears any row closure or call_reference set for batch operations
  • if an error occurs flushing data, the count is reset by calling Mapper::resetCount()
See also

◆ flush()

HashMap<String, Object> org.qore.lang.tablemapper.InboundTableMapper.flush ( ) throws Throwable
inline

flushes any remaining batched data to the database; this method should always be called before committing the transaction or destroying the object

Example:
{
AbstractTable table = UserApi.get_sql_table("some_table");
try {
table_mapper = UserApi.get_mapper("my_mapper");
try {
table_mapper.queueData(l);
table_mapper.flush();
} catch (Throwable e) {
table_mapper.discard();
} finally {
table_mapper.release();
}
} finally {
table.release();
}
}
Returns
if batch data was inserted then a hash (columns) of lists (row data) of all data inserted and potentially returned (in case of sequences) from the database server is returned; if constant mappings are used with batch data, then they are returned as single values assigned to the hash keys; returns null if no data was inserted
Note
  • flush() or discard() needs to be executed for each mapper used in the block when using multiple mappers whereas the DB transaction needs to be committed or rolled back once per datasource
  • also clears any row closure or call_reference set for batch operations
  • if an error occurs flushing data, the count is reset by calling Mapper::resetCount()
See also

◆ insertRow()

HashMap<String, Object> org.qore.lang.tablemapper.InboundTableMapper.insertRow ( Map< String, Object >  rec) throws Throwable
inline

inserts or upserts a row into the target table based on a mapped input record; does not commit the transaction

Parameters
recthe input record
Returns
a hash of the row values inserted/upserted (row name: value); note that any sequence values inserted are also returned here
Note
on mappers with "insert_block > 1" (i.e. also the underlying DB must allow for bulk operations), it is not allowed to use both single-record insertions (like insertRow()) and bulk operations (queueData()) in one transaction. Mixing insertRow() with queueData() leads to mismatch of Oracle DB types raising corresponding exceptions depending on particular record types (e.g. "ORA-01722: invalid number").
Exceptions
MISSING-INPUTa field marked mandatory is missing
STRING-TOO-LONGa field value exceeds the maximum value and the 'trunc' key is not set
INVALID-NUMBERthe field is marked as numeric but the input value contains non-numeric data

◆ queueData() [1/4]

HashMap<String, Object> org.qore.lang.tablemapper.InboundTableMapper.queueData ( Map< String, Object >  rec,
Map< String, Object >  crec 
) throws Throwable
inline

inserts/upserts a row (or a set of rows, in case a Map<String, Object> 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

Example:
{
AbstractTable table = UserApi.get_sql_table("some_table");
try {
InboundTableMapper table_mapper = UserApi.get_mapper("my_mapper");
try {
table_mapper.queueData(recs, crec);
table_mapper.flush();
} catch (Throwable e) {
table_mapper.discard();
} finally {
table_mapper.release();
}
} finally {
table.release();
}
}

Data is only inserted/upserted if the block buffer size reaches the limit defined by the "insert_block" option, in which case this method returns all the data inserted/upserted. In case the mapped data is only inserted into the cache, no value is returned.

Parameters
recthe input record or record set in case a Map<String, Object> of lists is passed
crecan optional simple Map<String, Object> (may be null) of data to be added to each input row before mapping
Returns
if batch data was inserted then a Map<String, Object> (columns) of lists (row data) of all data inserted and potentially returned (in case of sequences) from the database server is returned; if constant mappings are used with batch data, then they are returned as single values assigned to the Map<String, Object> keys; always returns a batch (Map<String, Object> of lists); in case no insert was made, null is returned
Note
  • make sure to call flush() before committing the transaction or discard() before rolling back the transaction or destroying the object when using this method
  • flush() or discard() needs to be executed for each mapper used in the block when using multiple mappers whereas the DB transaction needs to be committed or rolled back once per datasource
  • this method and batched inserts/upserts in general cannot be used when the "unstable_input" option is given in the constructor
  • if the "insert_block" option is set to 1, then this method simply calls insertRow(); however please note that in this case the return value is a Map<String, Object> of single value lists corresponding to a batch data insert
  • if an error occurs flushing data, the count is reset by calling Mapper::resetCount()
  • using a Map<String, Object> of lists in rec; note that this provides very high performance with SQL drivers that support Bulk DML
  • in case a Map<String, Object> of empty lists is passed, null is returned
  • 'crec' does not affect the number of output lines; in particular, if 'rec' is a batch with N rows of a column C and 'crec = ("C" : "mystring")' then the output will be as if there was 'N' rows with C = "mystring" on the input.
  • on mappers with "insert_block > 1" (i.e. also the underlying DB must allow for bulk operations), it is not allowed to use both single-record insertions (like insertRow()) and bulk operations (queueData()) in one transaction. Mixing insertRow() with queueData() leads to mismatch of Oracle DB types raising corresponding exceptions depending on particular record types (e.g. "ORA-01722: invalid number").
See also
Exceptions
MAPPER-BATCH-ERRORthis exception is thrown if this method is called when the "unstable_input" option was given in the constructor
MISSING-INPUTa field marked mandatory is missing
STRING-TOO-LONGa field value exceeds the maximum value and the 'trunc' key is not set
INVALID-NUMBERthe field is marked as numeric but the input value contains non-numeric data

◆ queueData() [2/4]

HashMap<String, Object> org.qore.lang.tablemapper.InboundTableMapper.queueData ( Map< String, Object >  rec) throws Throwable
inline

inserts/upserts a row (or a set of rows, in case a Map<String, Object> 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

Example:
{
AbstractTable table = UserApi.get_sql_table("some_table");
try {
table_mapper = UserApi.get_mapper("my_mapper");
try {
table_mapper.queueData(recs);
table_mapper.flush();
} catch (Throwable e) {
table_mapper.discard();
} finally {
table_mapper.release();
}
} finally {
table.release();
}
}

Data is only inserted/upserted if the block buffer size reaches the limit defined by the "insert_block" option, in which case this method returns all the data inserted/upserted. In case the mapped data is only inserted into the cache, no value is returned.

Parameters
recthe input record or record set in case a Map<String, Object> of lists is passed
Returns
if batch data was inserted then a Map<String, Object> (columns) of lists (row data) of all data inserted and potentially returned (in case of sequences) from the database server is returned; if constant mappings are used with batch data, then they are returned as single values assigned to the Map<String, Object> keys; always returns a batch (Map<String, Object> of lists); in case no insert was made, null is returned
Note
  • make sure to call flush() before committing the transaction or discard() before rolling back the transaction or destroying the object when using this method
  • flush() or discard() needs to be executed for each mapper used in the block when using multiple mappers whereas the DB transaction needs to be committed or rolled back once per datasource
  • this method and batched inserts/upserts in general cannot be used when the "unstable_input" option is given in the constructor
  • if the "insert_block" option is set to 1, then this method simply calls insertRow(); however please note that in this case the return value is a Map<String, Object> of single value lists corresponding to a batch data insert
  • if an error occurs flushing data, the count is reset by calling Mapper::resetCount()
  • using a Map<String, Object> of lists in rec; note that this provides very high performance with SQL drivers that support Bulk DML
  • in case a Map<String, Object> of empty lists is passed, null is returned
  • 'crec' does not affect the number of output lines; in particular, if 'rec' is a batch with N rows of a column C and 'crec = ("C" : "mystring")' then the output will be as if there was 'N' rows with C = "mystring" on the input.
  • on mappers with "insert_block > 1" (i.e. also the underlying DB must allow for bulk operations), it is not allowed to use both single-record insertions (like insertRow()) and bulk operations (queueData()) in one transaction. Mixing insertRow() with queueData() leads to mismatch of Oracle DB types raising corresponding exceptions depending on particular record types (e.g. "ORA-01722: invalid number").
See also
Exceptions
MAPPER-BATCH-ERRORthis exception is thrown if this method is called when the "unstable_input" option was given in the constructor
MISSING-INPUTa field marked mandatory is missing
STRING-TOO-LONGa field value exceeds the maximum value and the 'trunc' key is not set
INVALID-NUMBERthe field is marked as numeric but the input value contains non-numeric data

◆ queueData() [3/4]

HashMap<String, Object> org.qore.lang.tablemapper.InboundTableMapper.queueData ( Map< String, Object > []  l,
Map< String, Object >  crec 
) throws Throwable
inline

inserts/upserts a set of rows (list of hashes representing input records) 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

Example:
{
AbstractTable table = UserApi.get_sql_table("some_table");
try {
table_mapper = UserApi.get_mapper("my_mapper");
try {
table_mapper.queueData(l, crec);
table_mapper.flush();
} catch (Throwable e) {
table_mapper.discard();
} finally {
table_mapper.release();
}
} finally {
table.release();
}
}

Data is only inserted/upserted if the block buffer size reaches the limit defined by the "insert_block" option, in which case this method returns all the data inserted/upserted. In case the mapped data is only inserted into the cache, no value is returned.

Parameters
la list of hashes representing the input records
crecan optional simple Map<String, Object> of data to be added to each row
Returns
if batch data was inserted/upserted then a Map<String, Object> (columns) of lists (row data) of all data inserted/upserted and potentially returned (in case of sequences) from the database server is returned
Note
  • make sure to call flush() before committing the transaction or discard() before rolling back the transaction or destroying the object when using this method
  • flush() or discard() needs to be executed for each mapper used in the block when using multiple mappers whereas the DB transaction needs to be committed or rolled back once per datasource
  • this method and batched inserts/upserts in general cannot be used when the "unstable_input" option is given in the constructor
  • if the "insert_block" option is set to 1, then this method simply calls insertRow()
  • if an error occurs flushing data, the count is reset by calling Mapper::resetCount()
See also
Exceptions
MAPPER-BATCH-ERRORthis exception is thrown if this method is called when the "unstable_input" option was given in the constructor
MISSING-INPUTa field marked mandatory is missing
STRING-TOO-LONGa field value exceeds the maximum value and the 'trunc' key is not set
INVALID-NUMBERthe field is marked as numeric but the input value contains non-numeric data

◆ queueData() [4/4]

HashMap<String, Object> org.qore.lang.tablemapper.InboundTableMapper.queueData ( Map< String, Object > []  l) throws Throwable
inline

inserts/upserts a set of rows (list of hashes representing input records) 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

Example:
{
AbstractTable table = UserApi.get_sql_table("some_table");
try {
table_mapper = UserApi.get_mapper("my_mapper");
try {
table_mapper.queueData(l);
table_mapper.flush();
} catch (Throwable e) {
table_mapper.discard();
} finally {
table_mapper.release();
}
} finally {
table.release();
}
}

Data is only inserted/upserted if the block buffer size reaches the limit defined by the "insert_block" option, in which case this method returns all the data inserted/upserted. In case the mapped data is only inserted into the cache, no value is returned.

Parameters
la list of hashes representing the input records
Returns
if batch data was inserted/upserted then a Map<String, Object> (columns) of lists (row data) of all data inserted/upserted and potentially returned (in case of sequences) from the database server is returned; returns null if no data was inserted
Note
  • make sure to call flush() before committing the transaction or discard() before rolling back the transaction or destroying the object when using this method
  • flush() or discard() needs to be executed for each mapper used in the block when using multiple mappers whereas the DB transaction needs to be committed or rolled back once per datasource
  • this method and batched inserts/upserts in general cannot be used when the "unstable_input" option is given in the constructor
  • if the "insert_block" option is set to 1, then this method simply calls insertRow()
  • if an error occurs flushing data, the count is reset by calling Mapper::resetCount()
See also
Exceptions
MAPPER-BATCH-ERRORthis exception is thrown if this method is called when the "unstable_input" option was given in the constructor
MISSING-INPUTa field marked mandatory is missing
STRING-TOO-LONGa field value exceeds the maximum value and the 'trunc' key is not set
INVALID-NUMBERthe field is marked as numeric but the input value contains non-numeric data

The documentation for this class was generated from the following file: