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 (*hash< auto > options)
| Creates the object from constructor options.
| constructor (AbstractTable table)
| Creates the object.
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.
const | DbUpsertMap = ...
| Maps SqlUtil Upsert Result Codes to DB Provider Upsert Result Codes.
const | MapperKeyInfo = ...
| Mapper runtime key info.
const | ProviderInfo = ...
| Provider info.
const | SearchOptions = ...
| Search options.
const | UpsertOptions = ...
| Upsert options.

## 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

  rec | a hash representing a single input record
  create_options | the create options 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_cond | a hash for identifying the record(s) to be deleted
  search_options | the delete options 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

## 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_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; 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
| ) |  |

protected

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

Parameters

  search_options | the search options 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_options | the search options after processing by validateSearchOptions()

Exceptions

  MULTIPLE-RECORDS-ERROR | multiple 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

  set | the hash of field data to set
  where_cond | a hash for identifying the record(s) to be updated
  search_options | the update options 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

  set | the hash of field data to set
  where_cond | a hash for identifying the record to be update
  search_options | the update options 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 create options 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