Defines a data provider based on a single SQL table. More...

#include <DbTableDataProvider.qc.dox.h>

Inheritance diagram for DbDataProvider::DbTableDataProvider:

Public Member Methods
	beginTransaction ()
	Begins a transaction in the datasource underlying the table.

	commit ()
	Commits data written to the data provider.

	constructor (*hash< auto > options)
	Creates the object from constructor options.

	constructor (AbstractTable table, *LoggerInterface logger)
	Creates the object.

AbstractDataProviderBulkOperation	getBulkInserter ()
	Returns a bulk insert operation object for the data provider.

AbstractDataProviderBulkOperation	getBulkUpserter ()
	Returns a bulk upsert operation object for the data provider.

*string	getDesc ()
	Returns the data provider description.

hash< DataProviderInfo >	getInfo ()
	Returns data provider info.

*hash< string, hash< MapperRuntimeKeyInfo > >	getMapperRuntimeKeys ()
	Returns custom data mapper runtime keys.

string	getName ()
	Returns the data provider name.

	rollback ()
	Rolls back data written to the data provider.

string	upsertRecordImpl (hash< auto > rec, *hash< auto > upsert_options)
	Upserts the given record to the data provider.

Public Member Methods inherited from DbDataProvider::DbDataProviderBase
	beginTransaction ()
	Begins a transaction in the datasource.

	commit ()
	Commits any transaction in progress in the datasource.

	constructor (*LoggerInterface logger)
	Creates the object with the given logger.

	constructor (AbstractDatabase db, *LoggerInterface logger)
	creates the object

	constructor (AbstractDatasource ds, hash< auto > opts, LoggerInterface logger)
	creates the object

	constructor (hash< auto > options, *LoggerInterface logger)
	Creates the object from constructor options.

int	doSequenceCurrvalKey (string sequence_name, hash< auto > ctx, *reference< bool > missing_input)
	Processes the `sequence_currval` runtime key in mappers as a mapper key handler.

int	doSequenceKey (string sequence_name, hash< auto > ctx, *reference< bool > missing_input)
	Processes the `sequence` runtime key in mappers as a mapper key handler.

*hash< string, hash< MapperRuntimeKeyInfo > >	getMapperRuntimeKeys ()
	Returns custom data mapper runtime keys.

hash< auto >	makeTableDesc (string name, hash< string, AbstractDataField > fields, *hash< auto > opts)
	Returns a table description hash from a field description.

bool	requiresTransactionManagement ()
	Returns True if the data provider supports transaction management.

	rollback ()
	Rolls back any transaction in progress in the datasource.

Public Attributes
const	ConstructorOptions = ...
	Constructor options.

const	CreateOptions = ...
	Create options; see details below.

const	DbUpsertMap = ...
	Maps SqlUtil Upsert Result Codes to DB Provider Upsert Result Codes.

const	MapperKeyInfo = ...
	Mapper runtime key info; see details below.

const	ProviderInfo = ...
	Provider info.

const	SearchOptions = ...
	Search options; see details below.

const	UpsertOptions = ...
	Upsert options; see details below.

Private Member Methods
	addFieldImpl (AbstractDataField field, *hash< auto > field_add_options)
	Creates a new field.

	alignTable (hash< auto > table_desc)
	Align table with the given description.

*hash< auto >	createRecordImpl (hash< auto > rec, *hash< auto > create_options)
	Writes the given record to the data provider.

Mutex	db_lock ()
	lock for "db"

	deleteFieldImpl (string name, *hash< auto > field_delete_options)
	Deletes an existing field.

int	deleteRecordsImpl (hash< auto > where_cond, hash< auto > search_options)
	Deletes zero or more records.

	execDdlSql (list< auto > sqll)
	Executes the given DDL SQL string list.

*hash< string, AbstractDataField >	getRecordTypeImpl (*hash< auto > search_options)
	Returns the description of the record type, if any.

hash< DataProviderInfo >	getStaticInfoImpl ()
	Returns data provider static info.

AbstractDataProviderBulkRecordInterface	searchRecordsBulkImpl (int block_size=1000, hash< auto > where_cond, hash< auto > search_options)
	Returns an iterator for zero or more records matching the search options.

DbTableRecordIterator	searchRecordsImpl (hash< auto > where_cond, hash< auto > search_options)
	Returns an iterator for zero or more records matching the search options.

*hash< auto >	searchSingleRecordImpl (hash< auto > where_cond, hash< auto > search_options)
	Returns a single record matching the search options.

	updateFieldImpl (string name, AbstractDataField field, *hash< auto > field_update_options)
	Updates an existing field.

int	updateRecordsImpl (hash< auto > set, hash< auto > where_cond, hash< auto > search_options)
	Updates zero or more records matching the search options.

bool	updateSingleRecordImpl (hash< auto > set, hash< auto > where_cond, *hash< auto > search_options)
	Updates a single record matching the search options.

Private Attributes
AbstractTable	table
	the table

Private Attributes inherited from DbDataProvider::DbDataProviderBase
const	ConstructorOptions = ...
	Constructor options.

AbstractDatabase	db
	the database object, if required

const	MapperKeyInfo = ...
	Mapper runtime key info; see details below.

Additional Inherited Members
Static Public Member Methods inherited from DbDataProvider::DbDataProviderBase
static hash< GenericColumnInfo >	getColumnDesc (AbstractDatabase db, AbstractDataField field, *hash< auto > opts)
	Returns a column description hash for a field.

static AbstractDatasource	getDatasource (AbstractDatasource ds)
	Returns the given AbstractDatasource object.

static AbstractDatasource	getDatasource (string ds_string)
	Returns an AbstractDatasource object from the given string.

static AbstractTable	getTable (AbstractDatasource ds, string table_string)
	Returns an AbstractTable object from the given datasource and table arguments.

static AbstractTable	getTable (string ds_string, string table_string)
	Returns an AbstractTable object from the given datasource and table strings.

static	setDatasourceLookup (code datasource_lookup)
	Sets the datasource lookup.

static	setTableLookup (code table_lookup)
	Sets the table lookup.

Static Private Attributes inherited from DbDataProvider::DbDataProviderBase
static *code	datasource_lookup
	Lookup to get an abstract datasource from a name.

static *code	table_lookup
	Lookup to get an abstract table from a datasource and a name.

Detailed Description

Defines a data provider based on a single SQL table.

Member Function Documentation

◆ addFieldImpl()

DbDataProvider::DbTableDataProvider::addFieldImpl	(	AbstractDataField	field,
		*hash< auto >	field_add_options
	)

private

Creates a new field.

Parameters

field	the field to add
field_add_options	the options for adding the new field

Returns: the new child data provider

Since: DataProvider 2.0

◆ beginTransaction()

DbDataProvider::DbTableDataProvider::beginTransaction ( )

Begins a transaction in the datasource underlying the table.

See also

:

Since: DbDataProvider 1.0.1

◆ commit()

DbDataProvider::DbTableDataProvider::commit ( )

Commits data written to the data provider.

See also

:

◆ createRecordImpl()

*hash< auto > DbDataProvider::DbTableDataProvider::createRecordImpl	(	hash< auto >	rec,
		*hash< auto >	create_options
	)

private

Writes the given record to the data provider.

Parameters

rec	a hash representing a single input record
create_options	the create options (see CreateOptions) after processing by validateCreateOptions()

Returns: the data written to the data provider plus any output (returning) variables

Note: this API will commit the row to the database unless the datasource was already in a transaction before this call

◆ deleteFieldImpl()

DbDataProvider::DbTableDataProvider::deleteFieldImpl	(	string	name,
		*hash< auto >	field_delete_options
	)

private

Deletes an existing field.

Parameters

name	the name of the field to delete
field_delete_options	the options for deleting the new field

Since: DataProvider 2.0

◆ deleteRecordsImpl()

int DbDataProvider::DbTableDataProvider::deleteRecordsImpl	(	*hash< auto >	where_cond,
		*hash< auto >	search_options
	)

private

Deletes zero or more records.

Parameters

where_cond	a hash for identifying the record(s) to be deleted
search_options	the search options (see SearchOptions) after processing by validateSearchOptions()

Returns: the number of records deleted

Exceptions

INVALID-OPERATION the data provider does not support record updating

Note: this API will commit the row to the database unless the datasource was already in a transaction before this call

◆ getBulkInserter()

AbstractDataProviderBulkOperation DbDataProvider::DbTableDataProvider::getBulkInserter ( )

Returns a bulk insert operation object for the data provider.

Returns: a bulk insert operation object for the data provider

◆ getBulkUpserter()

AbstractDataProviderBulkOperation DbDataProvider::DbTableDataProvider::getBulkUpserter ( )

Returns a bulk upsert operation object for the data provider.

Returns: a bulk upsert operation object for the data provider

◆ getMapperRuntimeKeys()

*hash< string, hash< MapperRuntimeKeyInfo > > DbDataProvider::DbTableDataProvider::getMapperRuntimeKeys ( )

Returns custom data mapper runtime keys.

Returns: custom data mapper runtime keys

◆ rollback()

DbDataProvider::DbTableDataProvider::rollback ( )

Rolls back data written to the data provider.

See also

:

◆ searchRecordsBulkImpl()

AbstractDataProviderBulkRecordInterface DbDataProvider::DbTableDataProvider::searchRecordsBulkImpl	(	int	block_size = `1000`,
		*hash< auto >	where_cond,
		*hash< auto >	search_options
	)

private

Returns an iterator for zero or more records matching the search options.

Parameters

block_size	the number of records in a read block; must be a positive number
where_cond	the search criteria; will be processed by processFieldValues()
search_options	the search options (see SearchOptions); will be processed by validateSearchOptions()

Exceptions

INVALID-BLOCK-SIZE	the block size must be a positive number
INVALID-OPERATION	the data provider does not support reading

◆ searchRecordsImpl()

DbTableRecordIterator DbDataProvider::DbTableDataProvider::searchRecordsImpl	(	*hash< auto >	where_cond,
		*hash< auto >	search_options
	)

private

Returns an iterator for zero or more records matching the search options.

Parameters

where_cond	the search criteria; will be processed by processFieldValues()
search_options	the search options (see SearchOptions) after processing by validateSearchOptions()

Note: this method acquires a transaction lock if one is not already acquired; the iterator returned performs a rollback in the destructor if a new transaction lock was acquired by this call and DbTableRecordIterator::keepTransactionLock() is not called

◆ searchSingleRecordImpl()

*hash< auto > DbDataProvider::DbTableDataProvider::searchSingleRecordImpl	(	*hash< auto >	where_cond,
		*hash< auto >	search_options
	)

private

Returns a single record matching the search options.

Parameters

where_cond	the search criteria; will be processed by processFieldValues()
search_options	the search options (see SearchOptions) after processing by validateSearchOptions()

Exceptions

MULTIPLE-RECORDS-ERROR multiple records found

◆ updateFieldImpl()

DbDataProvider::DbTableDataProvider::updateFieldImpl	(	string	name,
		AbstractDataField	field,
		*hash< auto >	field_update_options
	)

private

Updates an existing field.

Parameters

name	the name of the current field to update
field	the new definition of the field
field_update_options	the options for adding the new field

Since: DataProvider 2.0

◆ updateRecordsImpl()

int DbDataProvider::DbTableDataProvider::updateRecordsImpl	(	hash< auto >	set,
		*hash< auto >	where_cond,
		*hash< auto >	search_options
	)

private

Updates zero or more records matching the search options.

Parameters

set	the hash of field data to set
where_cond	a hash for identifying the record(s) to be updated
search_options	the search options (see SearchOptions) after processing by validateSearchOptions()

Returns: the number of records updated

Note: this API will commit the row to the database unless the datasource was already in a transaction before this call

◆ updateSingleRecordImpl()

bool DbDataProvider::DbTableDataProvider::updateSingleRecordImpl	(	hash< auto >	set,
		hash< auto >	where_cond,
		*hash< auto >	search_options
	)

private

Updates a single record matching the search options.

Parameters

set	the hash of field data to set
where_cond	a hash for identifying the record to be update
search_options	the search options (see SearchOptions) after processing by validateSearchOptions()

Exceptions

UPDATE-SINGLE-RECORD-ERROR if the update would update more than one record

Note: this API will commit the row to the database unless the datasource was already in a transaction before this call

◆ upsertRecordImpl()

string DbDataProvider::DbTableDataProvider::upsertRecordImpl	(	hash< auto >	rec,
		*hash< auto >	upsert_options
	)

Upserts the given record to the data provider.

Parameters

rec	a hash representing a single input record
upsert_options	the upsert options (see UpsertOptions) after processing by validateUpsertOptions()

Returns: see DB Provider Upsert Result Codes for possible values

Note: this API will commit the row to the database unless the datasource was already in a transaction before this call

Member Data Documentation

◆ CreateOptions

const DbDataProvider::DbTableDataProvider::CreateOptions = ...

Create options; see details below.

The DbTableDataProvider class supports the following create option:

returning: a list having elements of one of the two following types:
- string: column names to return the value inserted
- hash: a hash having the following keys:
  - "key": (required) the column name to return
  - "type": (optional) the data type for the output placeholder buffer (ex: Type::Number)

◆ MapperKeyInfo

const DbDataProvider::DbTableDataProvider::MapperKeyInfo = ...

Mapper runtime key info; see details below.

The DbTableDataProvider class supports the following create option:

sequence: names the DB sequence that will be used to populate the field
sequence_currval: names the DB sequence that will be used to populate the field; the current value of the sequence is used; will not increment the sequence

◆ SearchOptions

const DbDataProvider::DbTableDataProvider::SearchOptions = ...

Search options; see details below.

The DbTableDataProvider class supports the following search options:

columns: column argument for the select expression; see SqlUtil select option columns for more information on this argument
limit: the maximum number of records to return; see SqlUtil select option limit for more information on this argument
offset: the offset number in records to return; see SqlUtil select option offset for more information on this argument
groupby: group by argument for the select expression; see SqlUtil select option groupby for more information on this argument
having: having argument for the select expression; see SqlUtil select option having for more information on this argument
orderby: order by argument for the select expression; see SqlUtil select option orderby for more information on this argument
forupdate: uses FOR UPDATE with the query to lock records selected; see SqlUtil select option forupdate for more information on this argument

◆ UpsertOptions

const DbDataProvider::DbTableDataProvider::UpsertOptions = ...

Upsert options; see details below.

The DbTableDataProvider class supports the following upsert options:

upsert_strategy: an upsert strategu code; see: SqlUtil upsert strategy codes for more info
omit_update: allows for an asymmetrical upsert where a set of column values is inserted, but a smaller set is updated in case the unique key values are present in the target table; the value of this option should be set to the columns to omit in the update clause

Public Member Methods

Public Attributes

Private Member Methods

Private Attributes

Additional Inherited Members

Detailed Description

Member Function Documentation

◆ addFieldImpl()

◆ beginTransaction()

◆ commit()

◆ createRecordImpl()

◆ deleteFieldImpl()

◆ deleteRecordsImpl()

◆ getBulkInserter()

◆ getBulkUpserter()

◆ getMapperRuntimeKeys()

◆ rollback()

◆ searchRecordsBulkImpl()

◆ searchRecordsImpl()

◆ searchSingleRecordImpl()

◆ updateFieldImpl()

◆ updateRecordsImpl()

◆ updateSingleRecordImpl()

◆ upsertRecordImpl()

Member Data Documentation

◆ CreateOptions

◆ MapperKeyInfo

◆ SearchOptions

◆ UpsertOptions