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:

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
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
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
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
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
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
void	discard () throws Throwable
	discards any buffered batched data; this method should be called after using the batch APIs (queueData()) and an error occurs
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

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

Deprecated:

Use dynamic imports instead: import qoremod.TableMapper.InboundTableMapper;

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

• queueData()
• flush()

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

• queueData()
• discard()

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

rec	the 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-INPUT	a field marked mandatory is missing
STRING-TOO-LONG	a field value exceeds the maximum value and the 'trunc' key is not set
INVALID-NUMBER	the 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 ) 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

rec	the 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

• flush()
• discard()

Exceptions

MAPPER-BATCH-ERROR	this exception is thrown if this method is called when the "unstable_input" option was given in the constructor
MISSING-INPUT	a field marked mandatory is missing
STRING-TOO-LONG	a field value exceeds the maximum value and the 'trunc' key is not set
INVALID-NUMBER	the 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, 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

rec	the input record or record set in case a Map<String, Object> of lists is passed
crec	an 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

• flush()
• discard()

Exceptions

MAPPER-BATCH-ERROR	this exception is thrown if this method is called when the "unstable_input" option was given in the constructor
MISSING-INPUT	a field marked mandatory is missing
STRING-TOO-LONG	a field value exceeds the maximum value and the 'trunc' key is not set
INVALID-NUMBER	the 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 ) 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

l	a 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

• flush()
• discard()

Exceptions

MAPPER-BATCH-ERROR	this exception is thrown if this method is called when the "unstable_input" option was given in the constructor
MISSING-INPUT	a field marked mandatory is missing
STRING-TOO-LONG	a field value exceeds the maximum value and the 'trunc' key is not set
INVALID-NUMBER	the 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, 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

l	a list of hashes representing the input records
crec	an 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

• flush()
• discard()

Exceptions

MAPPER-BATCH-ERROR	this exception is thrown if this method is called when the "unstable_input" option was given in the constructor
MISSING-INPUT	a field marked mandatory is missing
STRING-TOO-LONG	a field value exceeds the maximum value and the 'trunc' key is not set
INVALID-NUMBER	the field is marked as numeric but the input value contains non-numeric data

---

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

• /tmp/module-jni/src/java/org/qore/lang/tablemapper/InboundTableMapper.java