Qore DataProvider Module Reference  2.3
DataProvider::AbstractDataProvider Class Reference

The AbstractDataProvider class. More...

Inheritance diagram for DataProvider::AbstractDataProvider:

Public Member Methods

 addField (AbstractDataField field, *hash< auto > field_add_options)
 Creates a new field. More...
 
 beginTransaction ()
 Begins a transaction with a data provider. More...
 
 checkAddField ()
 Ensures that the data provider supports adding fields. More...
 
 checkCreate ()
 Ensures that the data provider supports record creation. More...
 
 checkCreateChild ()
 Ensures that the data provider supports creating children. More...
 
 checkDelete ()
 Ensures that the data provider supports record deletion. More...
 
 checkDeleteChild ()
 Ensures that the data provider supports deleting children. More...
 
 checkDeleteField ()
 Ensures that the data provider supports deleting fields. More...
 
 checkRead ()
 Ensures that the data provider supports read operations. More...
 
 checkRequest ()
 Ensures that the data provider supports the request API. More...
 
 checkSchema ()
 Ensures that the data provider supports a schema. More...
 
 checkSearchExpressions ()
 Ensures that the data provider supports advanced search expressions. More...
 
 checkUpdate ()
 Ensures that the data provider supports record upserts. More...
 
 checkUpdateField ()
 Ensures that the data provider supports updating fields. More...
 
 checkUpsert ()
 Ensures that the data provider supports record upserts. More...
 
 commit ()
 Commits data written to the data provider. More...
 
 constructor ()
 Creates the data provider.
 
 constructor (Logger logger)
 Creates the data provider with the given Logger.
 
AbstractDataProvider createChildProvider (string name, hash< string, AbstractDataField > fields, *hash< auto > child_create_options)
 Creates a new child data provider and returns it after adding as a child. More...
 
*hash< auto > createRecord (hash< auto > rec, *hash< auto > create_options)
 Creates the given record in the data provider. More...
 
 deleteChildProvider (string name, *hash< auto > child_delete_options)
 Deletes a child data provider. More...
 
 deleteField (string name, *hash< auto > field_delete_options)
 Deletes an existing field. More...
 
int deleteRecords (*hash< auto > where_cond, *hash< auto > search_options)
 Deletes zero or more records. More...
 
int deleteRecords (*hash< DataProviderExpression > 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. More...
 
*string getDesc ()
 Returns the data provider description.
 
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 (*bool with_type_info)
 Returns static provider information as data; no objects are returned. More...
 
*hash< string, hash< MapperRuntimeKeyInfo > > getMapperRuntimeKeys ()
 Returns custom data mapper runtime keys. More...
 
AbstractDataProviderRecordIterator getRecordIterator (*hash< auto > search_options)
 Returns an iterator iterating all records. 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...
 
object getSchemaObject ()
 Returns the schema supporting this data provider. More...
 
*hash< auto > getSearchExpression (*hash< auto > where_cond, *hash< auto > search_options)
 Returns a search expression for a standard search hash. More...
 
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...
 
AbstractDataProviderRecordIterator requestSearchRecords (auto req, *hash< DataProviderExpression > 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...
 
*hash< auto > searchFirstRecord (hash< DataProviderExpression > 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...
 
AbstractDataProviderRecordIterator searchRecords (*hash< DataProviderExpression > 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< DataProviderExpression > 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...
 
*hash< auto > searchSingleRecord (hash< DataProviderExpression > where_cond, *hash< auto > search_options)
 Returns a single record matching the search options. More...
 
 setLogger (Logger logger)
 Sets or replaces the logger.
 
 updateField (string name, AbstractDataField field, *hash< auto > field_update_options)
 Updates an existing field. More...
 
int updateRecords (hash< auto > set, *hash< auto > where_cond, *hash< auto > search_options)
 Updates zero or more records matching the search options. More...
 
int updateRecords (hash< auto > set, *hash< DataProviderExpression > 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...
 
bool updateSingleRecord (hash< auto > set, hash< DataProviderExpression > 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 auto evalGenericExpressionValue (hash< auto > rec, auto val)
 Evaluates the given expression with the generic internal implementation and returns the result. More...
 
static bool setDynamicValueCallbacks ()
 Ensures that no callbacks can be set for dynamic URI resolution. More...
 

Public Attributes

const GenericExpressionImplementations = ...
 Generic expression implementations for data providers without native search functionality.
 
const GenericExpressions = map {$1.key: $1.value.exp}
 Generic search operator expressions. More...
 

Private Member Methods

hash< DataProviderExpressiongetEqualityComparisonExpression (int role, hash< DataProviderInfo > info, string key, auto value)
 Returns an equality comparison expression. More...
 
hash< DataProviderExpressionInfogetExpression (int role, string exp, hash< DataProviderInfo > info=getInfo())
 Returns an expression definition for an expression code or throws an exception. More...
 
hash< DataProviderExpressiongetSimpleArgumentIntern (int role, hash< DataProviderInfo > info, hash< DataProviderExpressionInfo > expinfo, string key, auto value)
 Returns an argument for an expression. More...
 

Private Attributes

const GenericRecordSearchOptions = ...
 Generic record search options; see details below. More...
 
Logger logger
 Logger for logging.
 

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

◆ addField()

DataProvider::AbstractDataProvider::addField ( AbstractDataField  field,
*hash< auto >  field_add_options 
)

Creates a new field.

Parameters
fieldthe field to add
field_add_optionsthe options for adding the new field
Exceptions
INVALID-OPERATIONthrown if the data provider does not support this API
ADD-FIELD-ERRORerror adding the field
Since
DataProvider 2.0

◆ beginTransaction()

DataProvider::AbstractDataProvider::beginTransaction ( )

Begins a transaction with a data provider.

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

See also
:
Since
DataProvider 1.2.2

◆ checkAddField()

DataProvider::AbstractDataProvider::checkAddField ( )

Ensures that the data provider supports adding fields.

Exceptions
INVALID-OPERATIONthe data provider does not support the add field API
Since
DataProvider 2.0

◆ checkCreate()

DataProvider::AbstractDataProvider::checkCreate ( )

Ensures that the data provider supports record creation.

Exceptions
INVALID-OPERATIONthe data provider does not support record creation

◆ checkCreateChild()

DataProvider::AbstractDataProvider::checkCreateChild ( )

Ensures that the data provider supports creating children.

Exceptions
INVALID-OPERATIONthe data provider does not support the child creation API
Since
DataProvider 2.0

◆ checkDelete()

DataProvider::AbstractDataProvider::checkDelete ( )

Ensures that the data provider supports record deletion.

Exceptions
INVALID-OPERATIONthe data provider does not support record deletion

◆ checkDeleteChild()

DataProvider::AbstractDataProvider::checkDeleteChild ( )

Ensures that the data provider supports deleting children.

Exceptions
INVALID-OPERATIONthe data provider does not support the child deletion API
Since
DataProvider 2.0

◆ checkDeleteField()

DataProvider::AbstractDataProvider::checkDeleteField ( )

Ensures that the data provider supports deleting fields.

Exceptions
INVALID-OPERATIONthe data provider does not support the delete field API
Since
DataProvider 2.0

◆ 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

◆ checkSchema()

DataProvider::AbstractDataProvider::checkSchema ( )

Ensures that the data provider supports a schema.

Exceptions
INVALID-OPERATIONthe data provider does not support a schema
Since
DataProvider 2.2

◆ checkSearchExpressions()

DataProvider::AbstractDataProvider::checkSearchExpressions ( )

Ensures that the data provider supports advanced search expressions.

Exceptions
INVALID-OPERATIONthe data provider does not support advanced search expressions
Since
DataProvider 2.2

◆ checkUpdate()

DataProvider::AbstractDataProvider::checkUpdate ( )

Ensures that the data provider supports record upserts.

Exceptions
INVALID-OPERATIONthe data provider does not support record updating

◆ checkUpdateField()

DataProvider::AbstractDataProvider::checkUpdateField ( )

Ensures that the data provider supports updating fields.

Exceptions
INVALID-OPERATIONthe data provider does not support the update field API
Since
DataProvider 2.0

◆ 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

See also
:

◆ createChildProvider()

AbstractDataProvider DataProvider::AbstractDataProvider::createChildProvider ( string  name,
hash< string, AbstractDataField fields,
*hash< auto >  child_create_options 
)

Creates a new child data provider and returns it after adding as a child.

Parameters
namethe name of the new child data provider
fieldsthe fields for the new child data provider; must have at least one field
child_create_optionsthe options for creating the new child data provider
Returns
the new child data provider
Exceptions
INVALID-OPERATIONthrown if the data provider does not support this API
CREATE-CHILD-PROVIDER-ERRORerror creating the child provider
Since
DataProvider 2.0

◆ 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
CREATE-RECORD-ERRORthe data provider raised an exception in the record creation operation
DUPLICATE-RECORDthis exception should be thrown if the provider fails due to an attempt to create a duplicate record

◆ deleteChildProvider()

DataProvider::AbstractDataProvider::deleteChildProvider ( string  name,
*hash< auto >  child_delete_options 
)

Deletes a child data provider.

Parameters
namethe name of the new child data provider
child_delete_optionsthe options for deleting a child data provider
Exceptions
INVALID-OPERATIONthrown if the data provider does not support this API
DELETE-CHILD-PROVIDER-ERRORerror creating the child provider
Since
DataProvider 2.0

◆ deleteField()

DataProvider::AbstractDataProvider::deleteField ( string  name,
*hash< auto >  field_delete_options 
)

Deletes an existing field.

Parameters
namethe name of the field to delete
field_delete_optionsthe options for deleting the new field
Exceptions
INVALID-OPERATIONthrown if the data provider does not support this API
DELETE-FIELD-ERRORerror adding the field
Since
DataProvider 2.0

◆ deleteRecords() [1/2]

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; will be processed by processFieldValues()
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
DELETE-RECORDS-ERRORerror deleting records

◆ deleteRecords() [2/2]

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

Deletes zero or more records.

Parameters
where_conda hash for identifying the record(s) to be deleted; will be processed by processSearchParameters()
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
DELETE-RECORDS-ERRORerror deleting records
Since
DataProvider 2.3

◆ 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

◆ evalGenericExpressionValue()

static auto DataProvider::AbstractDataProvider::evalGenericExpressionValue ( hash< auto >  rec,
auto  val 
)
static

Evaluates the given expression with the generic internal implementation and returns the result.

Since
DataProvider 2.3

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

◆ 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

◆ getChildProviderPath()

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

Returns the given child provider from a "/" separated path string.

throws an exception with unknown path elements

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

◆ getEqualityComparisonExpression()

hash<DataProviderExpression> DataProvider::AbstractDataProvider::getEqualityComparisonExpression ( int  role,
hash< DataProviderInfo info,
string  key,
auto  value 
)
private

Returns an equality comparison expression.

Must be reimplemented by data provider implementations that support expressions and use a symbol different from '=' for the comparison operator

Since
DataProvider 2.3

◆ 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

◆ 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

◆ getExpression()

hash<DataProviderExpressionInfo> DataProvider::AbstractDataProvider::getExpression ( int  role,
string  exp,
hash< DataProviderInfo info = getInfo() 
)
private

Returns an expression definition for an expression code or throws an exception.

Since
DataProvider 2.3

◆ getInfoAsData()

hash<auto> DataProvider::AbstractDataProvider::getInfoAsData ( *bool  with_type_info)

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

Parameters
with_type_infoif True then more type information will be returned in the response
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

◆ 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

◆ 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

◆ getSchemaObject()

object DataProvider::AbstractDataProvider::getSchemaObject ( )

Returns the schema supporting this data provider.

Returns
the schema supporting this data provider
Exceptions
INVALID-OPERATIONthrown if the data provider does not support this API
Since
DataProvider 2.2

◆ getSearchExpression()

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

Returns a search expression for a standard search hash.

Parameters
where_condthe search criteria; if the data provider supports advanced search, and the value is an expression, it will be processed by processSearchParameters(), otherwise by processFieldValues()
search_optionsthe search options; will be processed by validateSearchOptions()
Returns
a search expression corresponding to where_cond
Since
DataProvider 2.3

◆ getSimpleArgumentIntern()

hash<DataProviderExpression> DataProvider::AbstractDataProvider::getSimpleArgumentIntern ( int  role,
hash< DataProviderInfo info,
hash< DataProviderExpressionInfo expinfo,
string  key,
auto  value 
)
private

Returns an argument for an expression.

Since
DataProvider 2.3

◆ requestSearchRecords() [1/2]

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

◆ requestSearchRecords() [2/2]

AbstractDataProviderRecordIterator DataProvider::AbstractDataProvider::requestSearchRecords ( auto  req,
*hash< DataProviderExpression 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
Since
DataProvider 2.3

◆ 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

See also
:

◆ searchFirstRecord() [1/2]

*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

◆ searchFirstRecord() [2/2]

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

Returns the first record matching the search options.

Parameters
where_condthe search criteria; will be processed by processSearchParameters()
search_optionsthe search options; will be processed by validateSearchOptions()
Exceptions
INVALID-OPERATIONthe data provider does not support reading
Since
DataProvider 2.3

◆ searchRecords() [1/2]

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

◆ searchRecords() [2/2]

AbstractDataProviderRecordIterator DataProvider::AbstractDataProvider::searchRecords ( *hash< DataProviderExpression 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 processSearchParameters()
search_optionsthe search options; will be processed by validateSearchOptions()
Exceptions
INVALID-OPERATIONthe data provider does not support reading
Since
DataProvider 2.3

◆ searchRecordsBulk() [1/2]

AbstractDataProviderBulkRecordInterface DataProvider::AbstractDataProvider::searchRecordsBulk ( int  block_size = 1000,
*hash< DataProviderExpression 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 processSearchParameters()
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
Since
DataProvider 2.3

◆ searchRecordsBulk() [2/2]

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

◆ searchSingleRecord() [1/2]

*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

◆ searchSingleRecord() [2/2]

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

Returns a single record matching the search options.

Parameters
where_condthe search criteria; will be processed by processSearchParameters()
search_optionsthe search options; will be processed by validateSearchOptions()
Exceptions
INVALID-OPERATIONthe data provider does not support reading
MULTIPLE-RECORDS-ERRORmultiple records found
Since
DataProvider 2.3

◆ setDynamicValueCallbacks()

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

◆ updateField()

DataProvider::AbstractDataProvider::updateField ( string  name,
AbstractDataField  field,
*hash< auto >  field_update_options 
)

Updates an existing field.

Parameters
namethe name of the current field to update
fieldthe new definition of the field
field_update_optionsthe options for adding the new field
Exceptions
INVALID-OPERATIONthrown if the data provider does not support this API
UPDATE-FIELD-ERRORerror adding the field
Since
DataProvider 2.0

◆ updateRecords() [1/2]

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; will be processed by processFieldValues()
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
UPDATE-RECORDS-ERRORerror updating records

◆ updateRecords() [2/2]

int DataProvider::AbstractDataProvider::updateRecords ( hash< auto >  set,
*hash< DataProviderExpression 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; will be processed by processSearchParameters()
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
UPDATE-RECORDS-ERRORerror updating records
Since
DataProvider 2.3

◆ updateSingleRecord() [1/2]

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
UPDATE-RECORDS-ERRORerror updating records

◆ updateSingleRecord() [2/2]

bool DataProvider::AbstractDataProvider::updateSingleRecord ( hash< auto >  set,
hash< DataProviderExpression 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 processSearchParameters()
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
UPDATE-RECORDS-ERRORerror updating records
Since
DataProvider 2.3

◆ 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

Member Data Documentation

◆ GenericExpressions

const DataProvider::AbstractDataProvider::GenericExpressions = map {$1.key: $1.value.exp}

Generic search operator expressions.

The following are generic search operator expressions implemented for all data providers that do not provide native search functionality

Since
DataProvider 2.3

◆ GenericRecordSearchOptions

const DataProvider::AbstractDataProvider::GenericRecordSearchOptions = ...
private

Generic record search options; see details below.

Each record-based data provider should support the following search options:

  • columns: a list of one or more field names; allows a subset of fields to be output in searches
  • limit: the maximum number of records to return
  • offset: the offset number in records to return