#include <AbstractDataProvider.qc.dox.h>

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

	checkMessages ()
	Ensures that the data provider supports sending messages. More...

	checkObservable ()
	Ensures that the data provider supports observer pattern / event API. 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 (LoggerInterface 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< 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. More...

*list< hash< DataProviderSummaryInfo > >	getChildProviderSummaryInfo ()
	Return data provider summary info. More...

*string	getDesc ()
	Returns the data provider description.

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< DataProviderMessageInfo >	getEventInfo (string event_id)
	Returns the description of an observable event, if any. More...

hash< string, hash< DataProviderMessageInfo > >	getEventTypes ()
	Returns a hash of all supported event types. More...

hash< DataProviderInfo >	getInfo ()
	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...

hash< DataProviderMessageInfo >	getMessageInfo (string message_id)
	Returns the description of an outbound message, if any. More...

hash< string, hash< DataProviderMessageInfo > >	getMessageTypes ()
	Returns a hash of all supported outbound messages. 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...

hash< DataProviderSummaryInfo >	getSummaryInfo ()
	Return data provider summary info.

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

	sendMessage (string message_id, auto msg, *hash< auto > send_message_options)
	Sends a message from message-capable data providers. More...

	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	DataProviderSummaryInfoKeys = map $1.getName()
	A list of members names of the DataProviderSummaryInfoKeys hashdecl.

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< DataProviderExpression >	getEqualityComparisonExpression (int role, hash< DataProviderInfo > info, string key, auto value)
	Returns an equality comparison expression. More...

hash< DataProviderExpression >	getSimpleArgumentIntern (int role, hash< DataProviderInfo > info, hash< DataProviderExpressionInfo > expinfo, string key, auto value)
	Returns an argument for an expression. More...

Static Private Member Methods
static hash< DataProviderExpressionInfo >	getExpression (int role, string exp, *hash< string, hash< DataProviderExpressionInfo > > expmap)
	Returns an expression definition for an expression code or throws an exception. More...

Private Attributes
const	GenericRecordSearchOptions
	Generic record search options; see details below. More...

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

The AbstractDataProvider class.

Member Function Documentation

◆ addField()

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

Creates a new field.

Parameters

field	the field to add
field_add_options	the options for adding the new field

Exceptions

INVALID-OPERATION	thrown if the data provider does not support this API
ADD-FIELD-ERROR	error 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 require transaction management

See also

:

Since: DataProvider 1.2.2

◆ checkAddField()

DataProvider::AbstractDataProvider::checkAddField ( )

Ensures that the data provider supports adding fields.

Exceptions

INVALID-OPERATION the 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-OPERATION the data provider does not support record creation

◆ checkCreateChild()

DataProvider::AbstractDataProvider::checkCreateChild ( )

Ensures that the data provider supports creating children.

Exceptions

INVALID-OPERATION the 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-OPERATION the data provider does not support record deletion

◆ checkDeleteChild()

DataProvider::AbstractDataProvider::checkDeleteChild ( )

Ensures that the data provider supports deleting children.

Exceptions

INVALID-OPERATION the 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-OPERATION the data provider does not support the delete field API

Since: DataProvider 2.0

◆ checkMessages()

DataProvider::AbstractDataProvider::checkMessages ( )

Ensures that the data provider supports sending messages.

Exceptions

INVALID-OPERATION the data provider does not support sending messages

Since: DataProvider 2.5

◆ checkObservable()

DataProvider::AbstractDataProvider::checkObservable ( )

Ensures that the data provider supports observer pattern / event API.

Exceptions

INVALID-OPERATION the data provider does not support the observer pattern / event API

Since: DataProvider 2.5

◆ 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

◆ checkSchema()

DataProvider::AbstractDataProvider::checkSchema ( )

Ensures that the data provider supports a schema.

Exceptions

INVALID-OPERATION the 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-OPERATION the 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-OPERATION the data provider does not support record updating

◆ checkUpdateField()

DataProvider::AbstractDataProvider::checkUpdateField ( )

Ensures that the data provider supports updating fields.

Exceptions

INVALID-OPERATION the 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-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

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

name	the name of the new child data provider
fields	the fields for the new child data provider; must have at least one field
child_create_options	the options for creating the new child data provider

Returns: the new child data provider

Exceptions

INVALID-OPERATION	thrown if the data provider does not support this API
CREATE-CHILD-PROVIDER-ERROR	error 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

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
CREATE-RECORD-ERROR	the data provider raised an exception in the record creation operation
DUPLICATE-RECORD	this 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

name	the name of the new child data provider
child_delete_options	the options for deleting a child data provider

Exceptions

INVALID-OPERATION	thrown if the data provider does not support this API
DELETE-CHILD-PROVIDER-ERROR	error creating the child provider

Since: DataProvider 2.0

◆ deleteField()

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

Deletes an existing field.

Parameters

name	the name of the field to delete
field_delete_options	the options for deleting the new field; processed by validateFieldDeleteOptions()

Exceptions

INVALID-OPERATION	thrown if the data provider does not support this API
DELETE-FIELD-ERROR	error 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_cond	a hash for identifying the record(s) to be deleted; will be processed by processFieldValues()
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
DELETE-RECORDS-ERROR	error deleting records

◆ deleteRecords() [2/2]

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

Deletes zero or more records.

Parameters

where_cond	a hash for identifying the record(s) to be deleted; will be processed by processSearchParameters()
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
DELETE-RECORDS-ERROR	error 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

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

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

◆ 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

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

◆ getChildProviderSummaryInfo()

*list< hash< DataProviderSummaryInfo > > DataProvider::AbstractDataProvider::getChildProviderSummaryInfo ( )

Return data provider summary info.

Note: This creates an AbstractDataProvider object for each child; for cases when this is expensive, this method must be overridden / reimplemented in the child class for performance reasons

◆ 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_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

◆ 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

◆ getEventInfo()

hash< DataProviderMessageInfo > DataProvider::AbstractDataProvider::getEventInfo ( string event_id )

Returns the description of an observable event, if any.

Parameters

event_id the event ID of the event

Returns: the observable event type for this provider

Exceptions

INVALID-OPERATION	the data provider does not support the observer pattern / event API
INVALID-EVENT	the event_id is not valid

Since: DataProvider 2.5

◆ getEventTypes()

hash< string, hash< DataProviderMessageInfo > > DataProvider::AbstractDataProvider::getEventTypes ( )

Returns a hash of all supported event types.

Returns: a hash of all supported event types

Exceptions

INVALID-OPERATION the data provider does not support the observer pattern / event API

Since: DataProvider 2.5

◆ getExpression()

static hash< DataProviderExpressionInfo > DataProvider::AbstractDataProvider::getExpression	(	int	role,
		string	exp,
		*hash< string, hash< DataProviderExpressionInfo > >	expmap
	)

staticprivate

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_info if 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

◆ getMessageInfo()

hash< DataProviderMessageInfo > DataProvider::AbstractDataProvider::getMessageInfo ( string message_id )

Returns the description of an outbound message, if any.

Parameters

message_id the ID of the message

Returns: the message type for this provider

Exceptions

INVALID-OPERATION	the data provider does not support sending messages
INVALID-MESSAGE	the message_id is not valid

Since: DataProvider 2.5

◆ getMessageTypes()

hash< string, hash< DataProviderMessageInfo > > DataProvider::AbstractDataProvider::getMessageTypes ( )

Returns a hash of all supported outbound messages.

Returns: a hash of all supported outbound messages

Exceptions

INVALID-OPERATION the data provider does not support sending messages

Since: DataProvider 2.5

◆ 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

◆ 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

◆ 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

◆ getSchemaObject()

object DataProvider::AbstractDataProvider::getSchemaObject ( )

Returns the schema supporting this data provider.

Returns: the schema supporting this data provider

Exceptions

INVALID-OPERATION thrown 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_cond	the 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_options	the 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

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

◆ 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

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

Since: DataProvider 2.3

◆ requiresTransactionManagement()

bool DataProvider::AbstractDataProvider::requiresTransactionManagement ( )

Returns True if the data provider requires transaction management.

Returns: True if the data provider requires 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_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

◆ 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_cond	the search criteria; will be processed by processSearchParameters()
search_options	the search options; will be processed by validateSearchOptions()

Exceptions

INVALID-OPERATION the 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_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

◆ 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_cond	the search criteria; will be processed by processSearchParameters()
search_options	the search options; will be processed by validateSearchOptions()

Exceptions

INVALID-OPERATION the 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_size	the number of records in a read block; must be a positive number
where_cond	the search criteria; will be processed by processSearchParameters()
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

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

◆ 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_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

◆ 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_cond	the search criteria; will be processed by processSearchParameters()
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

Since: DataProvider 2.3

◆ sendMessage()

DataProvider::AbstractDataProvider::sendMessage	(	string	message_id,
		auto	msg,
		*hash< auto >	send_message_options
	)

Sends a message from message-capable data providers.

Parameters

message_id	the message ID to send; must correspond to a valid message ID
msg	the message to send
send_message_options	the options for sending the message; processed by validateSendMessageOptions()

Exceptions

INVALID-OPERATION	thrown if the data provider does not support this API
INVALID-MESSAGE	the message_id is not valid
SEND-MESSAGE-ERROR	error sending the message

Since: DataProvider 2.5

◆ 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

name	the name of the current field to update
field	the new definition of the field
field_update_options	the options for adding the new field

Exceptions

INVALID-OPERATION	thrown if the data provider does not support this API
UPDATE-FIELD-ERROR	error 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

set	the hash of field data to set
where_cond	a hash for identifying the record(s) to be updated; will be processed by processFieldValues()
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
UPDATE-RECORDS-ERROR	error 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

set	the hash of field data to set
where_cond	a hash for identifying the record(s) to be updated; will be processed by processSearchParameters()
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
UPDATE-RECORDS-ERROR	error 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

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
UPDATE-RECORDS-ERROR	error 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

set	the hash of field data to set; will be processed by processFieldValues()
where_cond	the search criteria; will be processed by processSearchParameters()
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
UPDATE-RECORDS-ERROR	error 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

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

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

Initial value:

= {
            "columns": <DataProviderOptionInfo>{
                "type": AbstractDataProviderTypeMap."any",
                "desc": "allows a subset of fields to be output in searches",
            },
            "limit": <DataProviderOptionInfo>{
                "type": AbstractDataProviderType::get(IntType),
                "desc": "the maximum number of records to return",
            },
            "offset": <DataProviderOptionInfo>{
                "type": AbstractDataProviderType::get(IntType),
                "desc": "the offset number in records to return",
            },
        }

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

Public Member Methods

Static Public Member Methods

Public Attributes

Private Member Methods

Static Private Member Methods

Private Attributes

Static Private Attributes

Detailed Description

Member Function Documentation

◆ addField()

◆ beginTransaction()

◆ checkAddField()

◆ checkCreate()

◆ checkCreateChild()

◆ checkDelete()

◆ checkDeleteChild()

◆ checkDeleteField()

◆ checkMessages()

◆ checkObservable()

◆ checkRead()

◆ checkRequest()

◆ checkSchema()

◆ checkSearchExpressions()

◆ checkUpdate()

◆ checkUpdateField()

◆ checkUpsert()

◆ commit()

◆ createChildProvider()

◆ createRecord()

◆ deleteChildProvider()

◆ deleteField()

◆ deleteRecords() [1/2]

◆ deleteRecords() [2/2]

◆ doRequest()

◆ evalGenericExpressionValue()

◆ getBulkInserter()

◆ getBulkRecordInterface()

◆ getBulkUpserter()

◆ getChildProvider()

◆ getChildProviderEx()

◆ getChildProviderNames()

◆ getChildProviderPath()

◆ getChildProviderSummaryInfo()

◆ getEqualityComparisonExpression()

◆ getErrorResponseType()

◆ getErrorResponseTypes()

◆ getEventInfo()

◆ getEventTypes()

◆ getExpression()

◆ getInfoAsData()

◆ getMapperRuntimeKeys()

◆ getMessageInfo()

◆ getMessageTypes()

◆ getRecordIterator()

◆ getRequestType()

◆ getResponseType()

◆ getSchemaObject()

◆ getSearchExpression()

◆ getSimpleArgumentIntern()

◆ requestSearchRecords() [1/2]

◆ requestSearchRecords() [2/2]

◆ requiresTransactionManagement()

◆ rollback()

◆ searchFirstRecord() [1/2]

◆ searchFirstRecord() [2/2]

◆ searchRecords() [1/2]

◆ searchRecords() [2/2]

◆ searchRecordsBulk() [1/2]

◆ searchRecordsBulk() [2/2]

◆ searchSingleRecord() [1/2]

◆ searchSingleRecord() [2/2]

◆ sendMessage()

◆ setDynamicValueCallbacks()

◆ updateField()

◆ updateRecords() [1/2]

◆ updateRecords() [2/2]

◆ updateSingleRecord() [1/2]

◆ updateSingleRecord() [2/2]

◆ upsertRecord()

Member Data Documentation