Qore DbDataProvider Module Reference  1.0
DbDataProvider::DbTableDataProvider Class Reference

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

Inherits AbstractDataProvider.

Public Member Functions

 commit ()
 Commits data written to the data provider. More...
 
 constructor (AbstractTable table)
 Creates the object.
 
 constructor (*hash< auto > options)
 Creates the object from constructor options.
 
int doSequenceCurrvalKey (string sequence_name)
 Processes the sequence_currval runtime key in mappers.
 
int doSequenceKey (string sequence_name)
 Processes the sequence runtime key in mappers.
 
AbstractDataProviderBulkOperation getBulkInserter ()
 Returns a bulk insert operation object for the data provider. More...
 
AbstractDataProviderBulkOperation getBulkUpserter ()
 Returns a bulk upsert operation object for the data provider. More...
 
*AbstractDataProvider getChildProviders ()
 Returns child providers; return NOTHING if there are no child providers.
 
*hash< string, hash< MapperRuntimeKeyInfo > > getMapperRuntimeKeys ()
 Returns custom data mapper runtime keys. More...
 
string getName ()
 Returns the data provider name.
 
bool requiresTransactionManagement ()
 Returns True if the data provider supports transaction management. More...
 
 rollback ()
 Rolls back data written to the data provider. More...
 
string upsertRecordImpl (hash< auto > rec, *hash< auto > upsert_options)
 Upserts the given record to the data provider. More...
 

Public Attributes

const ConstructorOptions = ...
 Constructor options.
 
const CreateOptions = ...
 Create options; see details below. More...
 
const DbUpsertMap = ...
 Maps SqlUtil Upsert Result Codes to DB Provider Upsert Result Codes.
 
const MapperKeyInfo = ...
 Mapper runtime key info; see details below. More...
 
const ProviderInfo = ...
 Provider info.
 
const SearchOptions = ...
 Search options; see details below. More...
 
const UpsertOptions = ...
 Upsert options; see details below. More...
 

Protected Member Functions

*hash< auto > createRecordImpl (hash< auto > rec, *hash< auto > create_options)
 Writes the given record to the data provider. More...
 
Mutex db_lock ()
 lock for "db"
 
int deleteRecordsImpl (*hash< auto > where_cond, *hash< auto > search_options)
 Deletes zero or more records. More...
 
*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. More...
 
DbTableRecordIterator searchRecordsImpl (*hash< auto > where_cond, *hash< auto > search_options)
 Returns an iterator for zero or more records matching the search options. More...
 
*hash< auto > searchSingleRecordImpl (hash< auto > where_cond, *hash< auto > search_options)
 Returns a single record matching the search options. More...
 
int updateRecordsImpl (hash< auto > set, *hash< auto > where_cond, *hash< auto > search_options)
 Updates zero or more records matching the search options. More...
 
bool updateSingleRecordImpl (hash< auto > set, hash< auto > where_cond, *hash< auto > search_options)
 Updates a single record matching the search options. More...
 

Protected Attributes

AbstractDatabase db
 the database object, if required
 
AbstractTable table
 the table
 

Detailed Description

Defines a data provider based on a single SQL table.

Member Function Documentation

◆ commit()

DbDataProvider::DbTableDataProvider::commit ( )

Commits data written to the data provider.

Has no effect if the data provider does not support transaction management

◆ createRecordImpl()

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

Writes the given record to the data provider.

Parameters
reca hash representing a single input record
create_optionsthe 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

◆ deleteRecordsImpl()

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

Deletes zero or more records.

Parameters
where_conda hash for identifying the record(s) to be deleted
search_optionsthe search options (see SearchOptions) after processing by validateSearchOptions()
Returns
the number of records deleted
Exceptions
INVALID-OPERATIONthe 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

◆ requiresTransactionManagement()

bool DbDataProvider::DbTableDataProvider::requiresTransactionManagement ( )

Returns True if the data provider supports transaction management.

Returns
True if the data provider supports transaction management, in which case commit() or rollback() must be called to flush or discard data written to the data provider

◆ rollback()

DbDataProvider::DbTableDataProvider::rollback ( )

Rolls back data written to the data provider.

Has no effect if the data provider does not support transaction management

◆ searchRecordsBulkImpl()

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

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

Parameters
block_sizethe number of records in a read block; must be a positive number
where_condthe search criteria; will be processed by processFieldValues()
search_optionsthe search options (see SearchOptions); will be processed by validateSearchOptions()
Exceptions
INVALID-BLOCK-SIZEthe block size must be a positive number
INVALID-OPERATIONthe data provider does not support reading

◆ searchRecordsImpl()

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

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

Parameters
search_optionsthe 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 
)
protected

Returns a single record matching the search options.

Parameters
search_optionsthe search options (see SearchOptions) after processing by validateSearchOptions()
Exceptions
MULTIPLE-RECORDS-ERRORmultiple records found

◆ updateRecordsImpl()

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

Updates zero or more records matching the search options.

Parameters
setthe hash of field data to set
where_conda hash for identifying the record(s) to be updated
search_optionsthe 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 
)
protected

Updates a single record matching the search options.

Parameters
setthe hash of field data to set
where_conda hash for identifying the record to be update
search_optionsthe search options (see SearchOptions) after processing by validateSearchOptions()
Exceptions
UPDATE-SINGLE-RECORD-ERRORif 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
reca hash representing a single input record
upsert_optionsthe 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:

◆ 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