Qore DataProvider Module Reference  1.0.1
DataProvider::AbstractDataProvider Class Referenceabstract

The AbstractDataProvider class. More...

Public Member Methods

 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< stringgetChildProviderNames ()
 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, AbstractDataProviderTypegetErrorResponseTypes ()
 Returns a hash of error responses, if any. More...
 
hash< DataProviderInfogetInfo ()
 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, AbstractDataFieldgetOrNothingRecordType (*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, AbstractDataFieldgetRecordType (*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, AbstractDataFieldgetSoftRecordType (*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 Methods

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

Private Member Methods

*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< stringgetChildProviderNamesImpl ()
 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, AbstractDataProviderTypegetErrorResponseTypesImpl ()
 Returns a hash of error responses, if any. More...
 
*hash< string, AbstractDataFieldgetRecordTypeImpl (*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< DataProviderInfogetStaticInfoImpl ()
 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 Private Member Methods

static bool checkCallbacks ()
 Checks if callbacks have already been set or locked.
 

Static Private 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

Member Function Documentation

◆ checkCreate()

DataProvider::AbstractDataProvider::checkCreate ( )

Ensures that the data provider supports record creation.

Exceptions
INVALID-OPERATIONthe data provider does not support record creation

◆ checkDelete()

DataProvider::AbstractDataProvider::checkDelete ( )

Ensures that the data provider supports record deletion.

Exceptions
INVALID-OPERATIONthe data provider does not support record deletion

◆ checkRead()

DataProvider::AbstractDataProvider::checkRead ( )

Ensures that the data provider supports read operations.

Exceptions
INVALID-OPERATIONthe data provider does not support read operations

◆ checkRequest()

DataProvider::AbstractDataProvider::checkRequest ( )

Ensures that the data provider supports the request API.

Exceptions
INVALID-OPERATIONthe data provider does not support the request API

◆ checkUpdate()

DataProvider::AbstractDataProvider::checkUpdate ( )

Ensures that the data provider supports record upserts.

Exceptions
INVALID-OPERATIONthe data provider does not support record updating

◆ checkUpsert()

DataProvider::AbstractDataProvider::checkUpsert ( )

Ensures that the data provider supports record upserts.

Exceptions
INVALID-OPERATIONthe 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
reca hash representing a single input record
create_optionsthe create options; will be processed by validateCreateOptions()
Returns
the data written to the data provider
Exceptions
INVALID-OPERATIONthe data provider does not support record creation

◆ createRecordImpl()

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

Creates the given record to the data provider.

Parameters
reca hash representing a single input record
create_optionsthe create options after processing by validateCreateOptions()
Returns
the data written to the data provider

◆ deleteRecords()

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

Deletes zero or more records.

Parameters
where_conda hash for identifying the record(s) to be deleted
search_optionsthe search options; will be processed by validateSearchOptions()
Returns
the number of records deleted
Exceptions
INVALID-OPERATIONthe data provider does not support record deletion

◆ deleteRecordsImpl()

int DataProvider::AbstractDataProvider::deleteRecordsImpl ( *hash< auto >  where_cond,
*hash< auto >  search_options 
)
private

Deletes zero or more records.

Parameters
where_conda hash for identifying the record(s) to be deleted
search_optionsthe 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
reqthe request to serialize and make according to the request type
request_optionsthe request options; will be processed by validateRequestOptions()
Returns
the response to the request
Exceptions
INVALID-OPERATIONthe data provider does not support the request API
INVALID-REQUESTthe request argument provided do not match the expected request type

◆ doRequestImpl()

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

Makes a request and returns the response.

Parameters
reqthe request to serialize and make according to the request type
request_optionsthe 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-OPERATIONthe 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_sizethe number of records in a read block; must be a positive number
search_optionsthe search options; will be processed by validateSearchOptions()
Returns
a bulk record interface object that will return the records in bulk format
Exceptions
INVALID-BLOCK-SIZEthe block size must be a positive number
INVALID-OPERATIONthe 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-OPERATIONthe 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-PROVIDERunknown 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-PROVIDERunknown child provider
See also
getChildProvider()

◆ getChildProviderImpl()

*AbstractDataProvider DataProvider::AbstractDataProvider::getChildProviderImpl ( string  name)
private

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

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
patha 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-PROVIDERunknown 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_codethe 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-OPERATIONthe data provider does not support the request API
UNKNOWN-ERROR-RESPONSEthe error response given is not known

◆ getErrorResponseTypeImpl()

AbstractDataProviderType DataProvider::AbstractDataProvider::getErrorResponseTypeImpl ( string  error_code)
private

Returns the type for the given error code.

Parameters
error_codethe 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-RESPONSEthe 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-OPERATIONthe data provider does not support the request API

◆ getErrorResponseTypesImpl()

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

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_optionsthe search options; will be processed by validateSearchOptions()
Exceptions
INVALID-OPERATIONthe 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_optionsto 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)
private

Returns the description of the record type, if any.

Parameters
search_optionsto 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-OPERATIONthe data provider does not support the request API

◆ getRequestTypeImpl()

*AbstractDataProviderType DataProvider::AbstractDataProvider::getRequestTypeImpl ( )
private

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-OPERATIONthe data provider does not support the request API

◆ getResponseTypeImpl()

*AbstractDataProviderType DataProvider::AbstractDataProvider::getResponseTypeImpl ( )
private

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

processes search or set values to convert types if necessary

Parameters
hthe hash of field values to process
search_optionsthe 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
reqthe request to serialize and make according to the request type
where_condthe search criteria; will be processed by processFieldValues()
search_optionsthe search options after processing by validateSearchOptions()

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

Exceptions
INVALID-OPERATIONthe 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 
)
private

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

Parameters
reqthe request to serialize and make according to the request type
where_condthe search criteria; after processing by processFieldValues()
search_optionsthe 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_condthe search criteria; will be processed by processFieldValues()
search_optionsthe search options; will be processed by validateSearchOptions()
Exceptions
INVALID-OPERATIONthe data provider does not support reading

◆ searchFirstRecordImpl()

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

Returns the first record matching the search options.

Parameters
where_condthe search criteria
search_optionsthe 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_condthe search criteria; will be processed by processFieldValues()
search_optionsthe search options; will be processed by validateSearchOptions()
Exceptions
INVALID-OPERATIONthe 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_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; will be processed by validateSearchOptions()
Returns
a bulk record interface object that will return the records in bulk format
Exceptions
INVALID-BLOCK-SIZEthe block size must be a positive number
INVALID-OPERATIONthe data provider does not support reading

◆ searchRecordsBulkImpl()

AbstractDataProviderBulkRecordInterface DataProvider::AbstractDataProvider::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_sizethe number of records in a read block; must be a positive number
where_condthe search criteria; after processing by processFieldValues()
search_optionsthe search options after processing by validateSearchOptions()
Exceptions
INVALID-BLOCK-SIZEthe block size must be a positive number
INVALID-OPERATIONthe data provider does not support reading

◆ searchRecordsImpl()

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

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

Parameters
where_condthe search criteria
search_optionsthe 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_condthe search criteria; will be processed by processFieldValues()
search_optionsthe search options; will be processed by validateSearchOptions()
Exceptions
INVALID-OPERATIONthe data provider does not support reading
MULTIPLE-RECORDS-ERRORmultiple records found

◆ searchSingleRecordImpl()

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

Returns a single record matching the search options.

Parameters
where_condthe search criteria
search_optionsthe search options after processing by validateSearchOptions()
Exceptions
MULTIPLE-RECORDS-ERRORmultiple 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_resolutionsignature bool sub (string value) { ... }; this callback will be used to check if a URI path needs dynamic resolution
resolve_valuesignature 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 ( )
private

Throws an INVALID-OPERATION exception.

Exceptions
INVALID-OPERATIONthis 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
setthe hash of field data to set
where_conda hash for identifying the record(s) to be updated
search_optionsthe search options; will be processed by validateSearchOptions()
Returns
the number of records updated
Exceptions
INVALID-OPERATIONthe data provider does not support record updating

◆ updateRecordsImpl()

int DataProvider::AbstractDataProvider::updateRecordsImpl ( hash< auto >  set,
hash< auto >  where_cond,
*hash< auto >  search_options 
)
private

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 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
setthe hash of field data to set; will be processed by processFieldValues()
where_condthe search criteria; will be processed by processFieldValues()
search_optionsthe search options; will be processed by validateSearchOptions()
Returns
True if the record was updated, False if not (no record found)
Exceptions
INVALID-OPERATIONthe data provider does not support record updating

◆ updateSingleRecordImpl()

bool DataProvider::AbstractDataProvider::updateSingleRecordImpl ( hash< auto >  set,
hash< auto >  where_cond,
*hash< auto >  search_options 
)
private

Updates a single record matching the search options.

Parameters
setthe hash of field data to set
where_condthe search criteria
search_optionsthe 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
reca hash representing a single input record
upsert_optionsthe upsert options; will be processed by validateUpsertOptions()
Returns
see DB Provider Upsert Result Codes for possible values
Exceptions
INVALID-OPERATIONthe data provider does not support upsert operations

◆ upsertRecordImpl()

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

Upserts the given record to the data provider.

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

validates create options

Exceptions
CREATE-OPTION-ERRORinvalid or unsupported create option

◆ validateRequestOptions()

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

validates request options

Exceptions
REQUEST-OPTION-ERRORinvalid or unsupported request option

◆ validateSearchOptions()

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

validates search options

Exceptions
SEARCH-OPTION-ERRORinvalid or unsupported search option

◆ validateUpsertOptions()

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

validates upsert options

Exceptions
UPSERT-OPTION-ERRORinvalid or unsupported upsert option