| Qore DataProvider Module Reference 1.2.1

Public Member Functions | Static Public Member Functions | Protected Member Functions | Static Protected Member Functions | Static Protected Attributes | List of all members
DataProvider::AbstractDataProvider Class Referenceabstract

The AbstractDataProvider class. More...

Inheritance diagram for DataProvider::AbstractDataProvider:
[legend]

## Public Member Functions
| checkCreate ()
| Ensures that the data provider supports record creation. More...
| checkDelete ()
| Ensures that the data provider supports record deletion. More...
| checkRead ()
| Ensures that the data provider supports read operations. More...
| checkRequest ()
| Ensures that the data provider supports the request API. More...
| checkUpdate ()
| Ensures that the data provider supports record upserts. More...
| checkUpsert ()
| Ensures that the data provider supports record upserts. More...
| commit ()
| Commits data written to the data provider. More...
*hash< auto > | createRecord (hash< auto > rec, *hash< auto > create_options)
| Creates the given record in the data provider. More...
int | deleteRecords (*hash< auto > where_cond, *hash< auto > search_options)
| Deletes zero or more records. More...
auto | doRequest (auto req, *hash< auto > request_options)
| Makes a request and returns the response. More...
AbstractDataProviderBulkOperation | getBulkInserter ()
| Returns a bulk insert operation object for the data provider. More...
AbstractDataProviderBulkRecordInterface | getBulkRecordInterface (int block_size=1000, *hash< auto > search_options)
| Returns an iterator iterating all records with the bulk read API. More...
AbstractDataProviderBulkOperation | getBulkUpserter ()
| Returns a bulk upsert operation object for the data provider. More...
*AbstractDataProvider | getChildProvider (string name)
| Returns the given child provider or NOTHING if the given child is unknown. More...
AbstractDataProvider | getChildProviderEx (string name)
| Returns the given child provider or throws an exception if the given child is unknown. More...
*list< string > | getChildProviderNames ()
| Returns a list of child data provider names, if any. More...
AbstractDataProvider | getChildProviderPath (string path)
| Returns the given child provider from a `"/"` separated path string; throws an exception if any element in the path is unknown. More...
*hash< string, hash< DataProviderOptionInfo > > | getCreateOptions ()
| Returns options that can be used for creating records. More...
AbstractDataProviderType | getErrorResponseType (string error_code)
| Returns the type for the given error code. More...
*hash< string, AbstractDataProviderType > | getErrorResponseTypes ()
| Returns a hash of error responses, if any. More...
hash< DataProviderInfo > | getInfo ()
| Returns data provider info.
hash< auto > | getInfoAsData ()
| Returns static provider information as data; no objects are returned. More...
*hash< string, hash< MapperRuntimeKeyInfo > > | getMapperRuntimeKeys ()
| Returns custom data mapper runtime keys. More...
abstract string | getName ()
| Returns the data provider name.
*hash< string, AbstractDataField > | getOrNothingRecordType (*hash< auto > search_options)
| Returns the description of the record type with "or nothing" types, if any.
AbstractDataProviderRecordIterator | getRecordIterator (*hash< auto > search_options)
| Returns an iterator iterating all records. More...
*hash< string, AbstractDataField > | getRecordType (*hash< auto > search_options)
| Returns the description of the record type, if any. More...
*hash< string, hash< DataProviderOptionInfo > > | getRequestOptions ()
| Returns options that can be used for requests. More...
*AbstractDataProviderType | getRequestType ()
| Returns the description of a successful request message, if any. More...
*AbstractDataProviderType | getResponseType ()
| Returns the description of a response message, if this object represents a response message. More...
*hash< string, hash< DataProviderOptionInfo > > | getSearchOptions ()
| Returns options that can be used for searching. More...
*hash< string, AbstractDataField > | getSoftRecordType (*hash< auto > search_options)
| Returns the description of the record type with soft types, if any.
*hash< string, hash< DataProviderOptionInfo > > | getUpsertOptions ()
| Returns options that can be used for upserting records. More...
bool | hasRecord ()
| Returns True if the data provider has a record type. More...
bool | recordRequiresSearchOptions ()
| Returns True if the data provider requires search options to retrieve the record type.
AbstractDataProviderRecordIterator | requestSearchRecords (auto req, *hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options according to an API request. More...
bool | requiresTransactionManagement ()
| Returns True if the data provider supports transaction management. More...
| rollback ()
| Rolls back data written to the data provider. More...
*hash< auto > | searchFirstRecord (hash< auto > where_cond, *hash< auto > search_options)
| Returns the first record matching the search options. More...
AbstractDataProviderRecordIterator | searchRecords (*hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options. More...
AbstractDataProviderBulkRecordInterface | searchRecordsBulk (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...
*hash< auto > | searchSingleRecord (hash< auto > where_cond, *hash< auto > search_options)
| Returns a single record matching the search options. More...
bool | supportsBulkCreate ()
| Returns True if the data provider supports bulk creation output.
bool | supportsBulkRead ()
| Returns True if the data provider supports native bulk reading.
bool | supportsBulkUpsert ()
| Returns True if the data provider supports bulk upserts.
bool | supportsCreate ()
| Returns True if the data provider supports the record creation API.
bool | supportsDelete ()
| Returns True if the data provider supports the record deletion API.
bool | supportsNativeSearch ()
| Returns True if the data provider supports the record search API natively.
bool | supportsRead ()
| Returns True if the data provider supports reading.
bool | supportsRequest ()
| Returns True if the data provider supports requests.
bool | supportsUpdate ()
| Returns True if the data provider supports the record update API.
bool | supportsUpsert ()
| Returns True if the data provider supports the record upsert API.
int | updateRecords (hash< auto > set, *hash< auto > where_cond, *hash< auto > search_options)
| Updates zero or more records matching the search options. More...
bool | updateSingleRecord (hash< auto > set, hash< auto > where_cond, *hash< auto > search_options)
| Updates a single record matching the search options. More...
string | upsertRecord (hash< auto > rec, *hash< auto > upsert_options)
| Upserts the given record in the data provider. More...

## Static Public Member Functions
static bool | setDynamicValueCallbacks ()
| Ensures that no callbacks can be set for dynamic URI resolution. More...
static bool | setDynamicValueCallbacks (code value_needs_resolution, code resolve_value)
| Set callbacks for dynamic URI resolution to allow for variable URI path elements to be resolved at runtime. More...

## Protected Member Functions
*hash< auto > | checkOptions (string err, *hash< string, hash< DataProviderOptionInfo >> option_desc, *hash< auto > options)
| verifies options according to the option
*hash< auto > | createRecordImpl (hash< auto > rec, *hash< auto > create_options)
| Creates the given record to the data provider. More...
int | deleteRecordsImpl (*hash< auto > where_cond, *hash< auto > search_options)
| Deletes zero or more records. More...
auto | doRequestImpl (auto req, *hash< auto > request_options)
| Makes a request and returns the response. More...
| error (string err, string fmt)
| thrown an exception
*AbstractDataProvider | getChildProviderImpl (string name)
| Returns the given child provider or NOTHING if the given child is unknown. More...
*list< string > | getChildProviderNamesImpl ()
| Returns a list of child data provider names, if any. More...
AbstractDataProviderType | getErrorResponseTypeImpl (string error_code)
| Returns the type for the given error code. More...
*hash< string, AbstractDataProviderType > | getErrorResponseTypesImpl ()
| Returns a hash of error responses, if any. More...
*hash< string, AbstractDataField > | getRecordTypeImpl (*hash< auto > search_options)
| Returns the description of the record type, if any. More...
*AbstractDataProviderType | getRequestTypeImpl ()
| Returns the description of a successful request message, if any. More...
*AbstractDataProviderType | getResponseTypeImpl ()
| Returns the description of a response message, if this object represents a response message. More...
abstract hash< DataProviderInfo > | getStaticInfoImpl ()
| Returns data provider static info.
| processConstructorOptions (*hash< string, hash< DataProviderOptionInfo >> option_desc, *hash< auto > options)
| processes options passed to the constructor
*hash< auto > | processFieldValues (*hash< auto > h, *hash< auto > search_options)
| processes search or set values to convert types if necessary More...
AbstractDataProviderRecordIterator | requestSearchRecordsImpl (auto req, *hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options according to an API request. More...
*hash< auto > | searchFirstRecordImpl (hash< auto > where_cond, *hash< auto > search_options)
| Returns the first record matching the search options. More...
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...
AbstractDataProviderRecordIterator | 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...
| throwUnimplementedException ()
| Throws an `INVALID-OPERATION` exception. 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...
string | upsertRecordImpl (hash< auto > rec, *hash< auto > upsert_options)
| Upserts the given record to the data provider. More...
*hash< auto > | validateCreateOptions (*hash< auto > create_options)
| validates create options More...
*hash< auto > | validateRequestOptions (*hash< auto > request_options)
| validates request options More...
*hash< auto > | validateSearchOptions (*hash< auto > search_options)
| validates search options More...
*hash< auto > | validateUpsertOptions (*hash< auto > upsert_options)
| validates upsert options More...

## Static Protected Member Functions
static bool | checkCallbacks ()
| Checks if callbacks have already been set or locked.

## Static Protected Attributes
static bool | callbacks_locked = False
| flag if callbacks are locked
static code | cb_resolve_value
| static callback for dynamic value resolution
static code | cb_value_needs_resolution
| static callback the returns a bool if the value needs dynamic resolution

## Detailed Description

The AbstractDataProvider class.

## Member Function Documentation

## ◆ checkCreate()

DataProvider::AbstractDataProvider::checkCreate | ( |  | ) |

Ensures that the data provider supports record creation.

Exceptions

  INVALID-OPERATION | the data provider does not support record creation

## ◆ checkDelete()

DataProvider::AbstractDataProvider::checkDelete | ( |  | ) |

Ensures that the data provider supports record deletion.

Exceptions

  INVALID-OPERATION | the data provider does not support record deletion

## ◆ checkRead()

DataProvider::AbstractDataProvider::checkRead | ( |  | ) |

Ensures that the data provider supports read operations.

Exceptions

  INVALID-OPERATION | the data provider does not support read operations

## ◆ checkRequest()

DataProvider::AbstractDataProvider::checkRequest | ( |  | ) |

Ensures that the data provider supports the request API.

Exceptions

  INVALID-OPERATION | the data provider does not support the request API

## ◆ checkUpdate()

DataProvider::AbstractDataProvider::checkUpdate | ( |  | ) |

Ensures that the data provider supports record upserts.

Exceptions

  INVALID-OPERATION | the data provider does not support record updating

## ◆ checkUpsert()

DataProvider::AbstractDataProvider::checkUpsert | ( |  | ) |

Ensures that the data provider supports record upserts.

Exceptions

  INVALID-OPERATION | the data provider does not support upsert operations

## ◆ commit()

DataProvider::AbstractDataProvider::commit | ( |  | ) |

Commits data written to the data provider.

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

## ◆ createRecord()

*hash<auto> DataProvider::AbstractDataProvider::createRecord | ( | hash< auto > | rec,
|  | *hash< auto > | create_options
| ) |  |

Creates the given record in the data provider.

Parameters

  rec | a hash representing a single input record
  create_options | the create options; will be processed by validateCreateOptions()

Returns
  the data written to the data provider

Exceptions

  INVALID-OPERATION | the data provider does not support record creation
  DUPLICATE-RECORD | this exception should be thrown if the provider fails due to an attempt to create a duplicate record

## ◆ createRecordImpl()

*hash<auto> DataProvider::AbstractDataProvider::createRecordImpl | ( | hash< auto > | rec,
|  | *hash< auto > | create_options
| ) |  |
| protected

Creates 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

Exceptions

  DUPLICATE-RECORD | this exception should be thrown if the provider fails due to an attempt to create a duplicate record

## ◆ deleteRecords()

int DataProvider::AbstractDataProvider::deleteRecords | ( | *hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

Deletes zero or more records.

Parameters

  where_cond | a hash for identifying the record(s) to be deleted
  search_options | the search options; will be processed by validateSearchOptions()

Returns
  the number of records deleted

Exceptions

  INVALID-OPERATION | the data provider does not support record deletion

## ◆ deleteRecordsImpl()

int DataProvider::AbstractDataProvider::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

## ◆ doRequest()

auto DataProvider::AbstractDataProvider::doRequest | ( | auto | req,
|  | *hash< auto > | request_options
| ) |  |

Makes a request and returns the response.

Parameters

  req | the request to serialize and make according to the request type
  request_options | the request options; will be processed by validateRequestOptions()

Returns
  the response to the request

Exceptions

  INVALID-OPERATION | the data provider does not support the request API
  INVALID-REQUEST | the request argument provided do not match the expected request type

## ◆ doRequestImpl()

auto DataProvider::AbstractDataProvider::doRequestImpl | ( | auto | req,
|  | *hash< auto > | request_options
| ) |  |
| protected

Makes a request and returns the response.

Parameters

  req | the request to serialize and make according to the request type
  request_options | the request options; will be processed by validateRequestOptions()

Returns
  the response to the request

## ◆ getBulkInserter()

AbstractDataProviderBulkOperation DataProvider::AbstractDataProvider::getBulkInserter | ( |  | ) |

Returns a bulk insert operation object for the data provider.

Returns
  a bulk insert operation object for the data provider

Exceptions

  INVALID-OPERATION | the data provider does not support create operations

## ◆ getBulkRecordInterface()

AbstractDataProviderBulkRecordInterface DataProvider::AbstractDataProvider::getBulkRecordInterface | ( | int | block_size = `1000`,
|  | *hash< auto > | search_options
| ) |  |

Returns an iterator iterating all records with the bulk read API.

Parameters

  block_size | the number of records in a read block; must be a positive number
  search_options | the search options; will be processed by validateSearchOptions()

Returns
  a bulk record interface object that will return the records in bulk format

Exceptions

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

## ◆ getBulkUpserter()

AbstractDataProviderBulkOperation DataProvider::AbstractDataProvider::getBulkUpserter | ( |  | ) |

Returns a bulk upsert operation object for the data provider.

Returns
  a bulk upsert operation object for the data provider

Exceptions

  INVALID-OPERATION | the data provider does not support upsert operations

## ◆ getChildProvider()

*AbstractDataProvider DataProvider::AbstractDataProvider::getChildProvider | ( | string | name | ) |

Returns the given child provider or NOTHING if the given child is unknown.

Returns
  the given child provider or NOTHING if the given child is unknown

Exceptions

  INVALID-CHILD-PROVIDER | unknown child provider

See also
  getChildProviderEx()

## ◆ getChildProviderEx()

AbstractDataProvider DataProvider::AbstractDataProvider::getChildProviderEx | ( | string | name | ) |

Returns the given child provider or throws an exception if the given child is unknown.

Returns
  the given child provider or throws an exception if the given child is unknown

Exceptions

  INVALID-CHILD-PROVIDER | unknown child provider

See also
  getChildProvider()

## ◆ getChildProviderImpl()

*AbstractDataProvider DataProvider::AbstractDataProvider::getChildProviderImpl | ( | string | name | ) |
| protected

Returns the given child provider or NOTHING if the given child is unknown.

Returns
  the given child provider or NOTHING if the given child is unknown

## ◆ getChildProviderNames()

*list<string> DataProvider::AbstractDataProvider::getChildProviderNames | ( |  | ) |

Returns a list of child data provider names, if any.

Returns
  a list of child data provider names, if any

## ◆ getChildProviderNamesImpl()

*list<string> DataProvider::AbstractDataProvider::getChildProviderNamesImpl | ( |  | ) |
| protected

Returns a list of child data provider names, if any.

Returns
  a list of child data provider names, if any

This base class method returns NOTHING

## ◆ getChildProviderPath()

AbstractDataProvider DataProvider::AbstractDataProvider::getChildProviderPath | ( | string | path | ) |

Returns the given child provider from a `"/"` separated path string; throws an exception if any element in the path is unknown.

Parameters

  path | a string giving a path to the target provider where child elements are separated by `"/"` characters

Returns
  the target child provider; throws an exception if any element in the path is unknown

Exceptions

  INVALID-CHILD-PROVIDER | unknown child provider

## ◆ getCreateOptions()

*hash<string, hash<DataProviderOptionInfo> > DataProvider::AbstractDataProvider::getCreateOptions | ( |  | ) |

Returns options that can be used for creating records.

Returns
  a hash of options that can be used for creating records; keys are option names, values describe the option; if NOTHING is returned, then the provider does not support any creation options

## ◆ getErrorResponseType()

AbstractDataProviderType DataProvider::AbstractDataProvider::getErrorResponseType | ( | string | error_code | ) |

Returns the type for the given error code.

Parameters

  error_code | the error code for the response; must be a known error code, or an `UNKNOWN-ERROR-RESPONSE` exception is thrown

Returns
  the type for the given error code

Exceptions

  INVALID-OPERATION | the data provider does not support the request API
  UNKNOWN-ERROR-RESPONSE | the error response given is not known

## ◆ getErrorResponseTypeImpl()

AbstractDataProviderType DataProvider::AbstractDataProvider::getErrorResponseTypeImpl | ( | string | error_code | ) |
| protected

Returns the type for the given error code.

Parameters

  error_code | the error code for the response; must be a known error code, or an `UNKNOWN-ERROR-RESPONSE` exception is thrown

Returns
  the type for the given error code

Exceptions

  UNKNOWN-ERROR-RESPONSE | the error response given is not known

## ◆ getErrorResponseTypes()

*hash<string, AbstractDataProviderType> DataProvider::AbstractDataProvider::getErrorResponseTypes | ( |  | ) |

Returns a hash of error responses, if any.

Returns
  a hash of error responses, if any, keyed by response code or string

Exceptions

  INVALID-OPERATION | the data provider does not support the request API

## ◆ getErrorResponseTypesImpl()

*hash<string, AbstractDataProviderType> DataProvider::AbstractDataProvider::getErrorResponseTypesImpl | ( |  | ) |
| protected

Returns a hash of error responses, if any.

Returns
  a hash of error responses, if any, keyed by response code or string

Note
  only called if the provider supports the request / response API

## ◆ getInfoAsData()

hash<auto> DataProvider::AbstractDataProvider::getInfoAsData | ( |  | ) |

Returns static provider information as data; no objects are returned.

Note
  the `name` and `children` attributes are not returned as they are dynamic attributes

## ◆ getMapperRuntimeKeys()

*hash<string, hash<MapperRuntimeKeyInfo> > DataProvider::AbstractDataProvider::getMapperRuntimeKeys | ( |  | ) |

Returns custom data mapper runtime keys.

Returns
  custom data mapper runtime keys

This base method returns NOTHING; reimplment in child classes to return a value

## ◆ getRecordIterator()

AbstractDataProviderRecordIterator DataProvider::AbstractDataProvider::getRecordIterator | ( | *hash< auto > | search_options | ) |

Returns an iterator iterating all records.

Parameters

  search_options | the search options; will be processed by validateSearchOptions()

Exceptions

  INVALID-OPERATION | the data provider does not support reading

## ◆ getRecordType()

*hash<string, AbstractDataField> DataProvider::AbstractDataProvider::getRecordType | ( | *hash< auto > | search_options | ) |

Returns the description of the record type, if any.

Parameters

  search_options | to be included and processed by validateSearchOptions() if recordRequiresSearchOptions() is True for this provider, otherwise any value provided in this argument is ignored

Returns
  the record type or NOTHING if the datas provider does not support a record type

## ◆ getRecordTypeImpl()

*hash<string, AbstractDataField> DataProvider::AbstractDataProvider::getRecordTypeImpl | ( | *hash< auto > | search_options | ) |
| protected

Returns the description of the record type, if any.

Parameters

  search_options | to be included and processed by validateSearchOptions() if recordRequiresSearchOptions() is True for this provider, otherwise any value provided in this argument is ignored

## ◆ getRequestOptions()

*hash<string, hash<DataProviderOptionInfo> > DataProvider::AbstractDataProvider::getRequestOptions | ( |  | ) |

Returns options that can be used for requests.

Returns
  a hash of options that can be used for requests; keys are request option names, values describe the request option; if NOTHING is returned, then the provider does not support any request options

## ◆ getRequestType()

*AbstractDataProviderType DataProvider::AbstractDataProvider::getRequestType | ( |  | ) |

Returns the description of a successful request message, if any.

Returns
  the request type for this provider

Exceptions

  INVALID-OPERATION | the data provider does not support the request API

## ◆ getRequestTypeImpl()

*AbstractDataProviderType DataProvider::AbstractDataProvider::getRequestTypeImpl | ( |  | ) |
| protected

Returns the description of a successful request message, if any.

Returns
  the request type for this provider

Note
  only called if the provider supports the request / response API

## ◆ getResponseType()

*AbstractDataProviderType DataProvider::AbstractDataProvider::getResponseType | ( |  | ) |

Returns the description of a response message, if this object represents a response message.

Returns
  the response type for this response message

Exceptions

  INVALID-OPERATION | the data provider does not support the request API

## ◆ getResponseTypeImpl()

*AbstractDataProviderType DataProvider::AbstractDataProvider::getResponseTypeImpl | ( |  | ) |
| protected

Returns the description of a response message, if this object represents a response message.

Returns
  the response type for this response message

Note
  only called if the provider supports the request / response API

## ◆ getSearchOptions()

*hash<string, hash<DataProviderOptionInfo> > DataProvider::AbstractDataProvider::getSearchOptions | ( |  | ) |

Returns options that can be used for searching.

Returns
  a hash of options that can be used for searching; keys are search option names, values describe the search option; if NOTHING is returned, then the provider does not support any search options

## ◆ getUpsertOptions()

*hash<string, hash<DataProviderOptionInfo> > DataProvider::AbstractDataProvider::getUpsertOptions | ( |  | ) |

Returns options that can be used for upserting records.

Returns
  a hash of options that can be used for upserting records; keys are option names, values describe the option; if NOTHING is returned, then the provider does not support any upsert options

## ◆ hasRecord()

bool DataProvider::AbstractDataProvider::hasRecord | ( |  | ) |

Returns True if the data provider has a record type.

Returns
  True if the data provider has a record type

## ◆ processFieldValues()

*hash<auto> DataProvider::AbstractDataProvider::processFieldValues | ( | *hash< auto > | h,
|  | *hash< auto > | search_options
| ) |  |
| protected

processes search or set values to convert types if necessary

Parameters

  h | the hash of field values to process
  search_options | the search options after processing by validateSearchOptions()

Returns
  processed field values, all non-hash values of h are processed with the field's type to ensure that the values are valid for the comparison or set operation; hash values are assumed to be provider- specific comparison or set operations and should be processed by the provider-specific method

## ◆ requestSearchRecords()

AbstractDataProviderRecordIterator DataProvider::AbstractDataProvider::requestSearchRecords | ( | auto | req,
|  | *hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

Returns an iterator for zero or more records matching the search options according to an API request.

Parameters

  req | the request to serialize and make according to the request type
  where_cond | the search criteria; will be processed by processFieldValues()
  search_options | the search options after processing by validateSearchOptions()

This will execute the request and perform a default search on any record(s) returned

Exceptions

  INVALID-OPERATION | the data provider does not support reading records or the request / response API

## ◆ requestSearchRecordsImpl()

AbstractDataProviderRecordIterator DataProvider::AbstractDataProvider::requestSearchRecordsImpl | ( | auto | req,
|  | *hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |
| protected

Returns an iterator for zero or more records matching the search options according to an API request.

Parameters

  req | the request to serialize and make according to the request type
  where_cond | the search criteria; after processing by processFieldValues()
  search_options | the search options after processing by validateSearchOptions()

This will execute the request and perform a default search on any record(s) returned

See also
  searchRecordsImpl()

## ◆ requiresTransactionManagement()

bool DataProvider::AbstractDataProvider::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()

DataProvider::AbstractDataProvider::rollback | ( |  | ) |

Rolls back data written to the data provider.

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

## ◆ searchFirstRecord()

*hash<auto> DataProvider::AbstractDataProvider::searchFirstRecord | ( | hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

Returns the first record matching the search options.

Parameters

  where_cond | the search criteria; will be processed by processFieldValues()
  search_options | the search options; will be processed by validateSearchOptions()

Exceptions

  INVALID-OPERATION | the data provider does not support reading

## ◆ searchFirstRecordImpl()

*hash<auto> DataProvider::AbstractDataProvider::searchFirstRecordImpl | ( | hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |
| protected

Returns the first record matching the search options.

Parameters

  where_cond | the search criteria
  search_options | the search options after processing by validateSearchOptions()

Note
  This default method returns immediately as soon as the first matching record is found

## ◆ searchRecords()

AbstractDataProviderRecordIterator DataProvider::AbstractDataProvider::searchRecords | ( | *hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

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; will be processed by validateSearchOptions()

Exceptions

  INVALID-OPERATION | the data provider does not support reading

## ◆ searchRecordsBulk()

AbstractDataProviderBulkRecordInterface DataProvider::AbstractDataProvider::searchRecordsBulk | ( | int | block_size = `1000`,
|  | *hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

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()

Returns
  a bulk record interface object that will return the records in bulk format

Exceptions

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

## ◆ searchRecordsBulkImpl()

AbstractDataProviderBulkRecordInterface DataProvider::AbstractDataProvider::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; after processing by processFieldValues()
  search_options | the search options after processing by validateSearchOptions()

Exceptions

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

## ◆ searchRecordsImpl()

AbstractDataProviderRecordIterator DataProvider::AbstractDataProvider::searchRecordsImpl | ( | *hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |
| protected

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

Parameters

  where_cond | the search criteria
  search_options | the search options after processing by validateSearchOptions()

See also
  requestSearchRecordsImpl()

## ◆ searchSingleRecord()

*hash<auto> DataProvider::AbstractDataProvider::searchSingleRecord | ( | hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

Returns a single record matching the search options.

Parameters

  where_cond | the search criteria; will be processed by processFieldValues()
  search_options | the search options; will be processed by validateSearchOptions()

Exceptions

  INVALID-OPERATION | the data provider does not support reading
  MULTIPLE-RECORDS-ERROR | multiple records found

## ◆ searchSingleRecordImpl()

*hash<auto> DataProvider::AbstractDataProvider::searchSingleRecordImpl | ( | hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |
| protected

Returns a single record matching the search options.

Parameters

  where_cond | the search criteria
  search_options | the search options after processing by validateSearchOptions()

Exceptions

  MULTIPLE-RECORDS-ERROR | multiple records found

Note
  This default methods searches the entire data set for a matching record

## ◆ setDynamicValueCallbacks() [1/2]

static bool DataProvider::AbstractDataProvider::setDynamicValueCallbacks | ( |  | ) |
| static

Ensures that no callbacks can be set for dynamic URI resolution.

Returns
  False if this call was ignored because callbacks are locked, True if the call was successful

Note
  after this call, callbacks cannot be changed

## ◆ setDynamicValueCallbacks() [2/2]

static bool DataProvider::AbstractDataProvider::setDynamicValueCallbacks | ( | code | value_needs_resolution,
|  | code | resolve_value
| ) |  |
| static

Set callbacks for dynamic URI resolution to allow for variable URI path elements to be resolved at runtime.

Parameters

  value_needs_resolution | signature `bool sub (string value) { ... }`; this callback will be used to check if a URI path needs dynamic resolution
  resolve_value | signature `auto sub (auto value) { ... }`; if `value_needs_resolution` returns True on a URI path, then this callback will be called at runtime for each request to resolve the URI path to the final path

Returns
  False if this call was ignored because callbacks are locked, True if the call was successful

Note
  after this call, callbacks cannot be changed

## ◆ throwUnimplementedException()

DataProvider::AbstractDataProvider::throwUnimplementedException | ( |  | ) |
| protected

Throws an `INVALID-OPERATION` exception.

Exceptions

  INVALID-OPERATION | this exception is thrown unconditionally by this method

## ◆ updateRecords()

int DataProvider::AbstractDataProvider::updateRecords | ( | hash< auto > | set,
|  | *hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

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; will be processed by validateSearchOptions()

Returns
  the number of records updated

Exceptions

  INVALID-OPERATION | the data provider does not support record updating

## ◆ updateRecordsImpl()

int DataProvider::AbstractDataProvider::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

## ◆ updateSingleRecord()

bool DataProvider::AbstractDataProvider::updateSingleRecord | ( | hash< auto > | set,
|  | hash< auto > | where_cond,
|  | *hash< auto > | search_options
| ) |  |

Updates a single record matching the search options.

Parameters

  set | the hash of field data to set; will be processed by processFieldValues()
  where_cond | the search criteria; will be processed by processFieldValues()
  search_options | the search options; will be processed by validateSearchOptions()

Returns
  True if the record was updated, False if not (no record found)

Exceptions

  INVALID-OPERATION | the data provider does not support record updating

## ◆ updateSingleRecordImpl()

bool DataProvider::AbstractDataProvider::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 | the search criteria
  search_options | the search options after processing by validateSearchOptions()

## ◆ upsertRecord()

string DataProvider::AbstractDataProvider::upsertRecord | ( | hash< auto > | rec,
|  | *hash< auto > | upsert_options
| ) |  |

Upserts the given record in the data provider.

Parameters

  rec | a hash representing a single input record
  upsert_options | the upsert options; will be processed by validateUpsertOptions()

Returns
  see DB Provider Upsert Result Codes for possible values

Exceptions

  INVALID-OPERATION | the data provider does not support upsert operations

## ◆ upsertRecordImpl()

string DataProvider::AbstractDataProvider::upsertRecordImpl | ( | hash< auto > | rec,
|  | *hash< auto > | upsert_options
| ) |  |
| protected

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

## ◆ validateCreateOptions()

*hash<auto> DataProvider::AbstractDataProvider::validateCreateOptions | ( | *hash< auto > | create_options | ) |
| protected

validates create options

Exceptions

  CREATE-OPTION-ERROR | invalid or unsupported create option

## ◆ validateRequestOptions()

*hash<auto> DataProvider::AbstractDataProvider::validateRequestOptions | ( | *hash< auto > | request_options | ) |
| protected

validates request options

Exceptions

  REQUEST-OPTION-ERROR | invalid or unsupported request option

## ◆ validateSearchOptions()

*hash<auto> DataProvider::AbstractDataProvider::validateSearchOptions | ( | *hash< auto > | search_options | ) |
| protected

validates search options

Exceptions

  SEARCH-OPTION-ERROR | invalid or unsupported search option

## ◆ validateUpsertOptions()

*hash<auto> DataProvider::AbstractDataProvider::validateUpsertOptions | ( | *hash< auto > | upsert_options | ) |
| protected

validates upsert options

Exceptions

  UPSERT-OPTION-ERROR | invalid or unsupported upsert option