Qore DataProvider Module Reference  2.2
DataProvider::AbstractDataProvider Class Referenceabstract

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...
 
 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...
 
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...
 
*hash< string, hash< DataProviderOptionInfo > > getChildCreateOptions ()
 Returns options that can be used for creating child data providers. More...
 
*hash< string, hash< DataProviderOptionInfo > > getChildDeleteOptions ()
 Returns options that can be used for deleting child data providers. 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...
 
*hash< string, hash< DataProviderOptionInfo > > getCreateOptions ()
 Returns options that can be used for creating records. 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< string, hash< DataProviderOptionInfo > > getFieldAddOptions ()
 Returns options that can be used for adding new fields to the data provider. More...
 
*hash< string, hash< DataProviderOptionInfo > > getFieldDeleteOptions ()
 Returns options that can be used for deleting fields from the data provider. More...
 
*hash< string, hash< DataProviderOptionInfo > > getFieldUpdateOptions ()
 Returns options that can be used for updating fields of the data provider. 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...
 
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...
 
object getSchemaObject ()
 Returns the schema supporting this data provider. More...
 
*object getSchemaType ()
 Returns the schema type for this data provider or NOTHING if no schema type is supported. 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...
 
 setLogger (Logger logger)
 Sets or replaces the logger.
 
bool supportsAddField ()
 Returns True if the data provider supports creating adding new fields. 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 supportsCreateChild ()
 Returns True if the data provider supports creating new child data providers. More...
 
bool supportsDelete ()
 Returns True if the data provider supports the record deletion API.
 
bool supportsDeleteChild ()
 Returns True if the data provider supports creating deleting child data providers. More...
 
bool supportsDeleteField ()
 Returns True if the data provider supports deleting existing fields. More...
 
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 supportsSchema ()
 Returns True if the data provider supports a schema. More...
 
bool supportsUpdate ()
 Returns True if the data provider supports the record update API.
 
bool supportsUpdateField ()
 Returns True if the data provider supports updating existing fields. More...
 
bool supportsUpsert ()
 Returns True if the data provider supports the record upsert API.
 
 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...
 
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

 addFieldImpl (AbstractDataField field, *hash< auto > field_add_options)
 Creates a new field. More...
 
*hash< auto > checkOptions (string err, *hash< string, hash< DataProviderOptionInfo >> option_desc, *hash< auto > options)
 verifies options according to the option
 
AbstractDataProvider createChildProviderImpl (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 > createRecordImpl (hash< auto > rec, *hash< auto > create_options)
 Creates the given record to the data provider. More...
 
 deleteChildProviderImpl (string name, *hash< auto > child_delete_options)
 Deletes a child data provider. More...
 
 deleteFieldImpl (string name, *hash< auto > field_delete_options)
 Deletes an existing field. 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...
 
object getSchemaObjectImpl ()
 Returns the schema object supporting this data provider. 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...
 
 updateFieldImpl (string name, AbstractDataField field, *hash< auto > field_update_options)
 Updates an existing field. 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 > validateChildCreateOptions (*hash< auto > child_create_options)
 validates child create options More...
 
*hash< auto > validateChildDeleteOptions (*hash< auto > child_delete_options)
 validates child delete options More...
 
*hash< auto > validateCreateOptions (*hash< auto > create_options)
 validates create options More...
 
*hash< auto > validateFieldAddOptions (*hash< auto > field_add_options)
 validates field add options More...
 
*hash< auto > validateFieldDeleteOptions (*hash< auto > field_delete_options)
 validates field delete options More...
 
*hash< auto > validateFieldUpdateOptions (*hash< auto > field_update_options)
 validates field update 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.
 

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

◆ addFieldImpl()

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

Creates a new field.

Parameters
fieldthe field to add
field_add_optionsthe options for adding the new 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

◆ 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

◆ createChildProviderImpl()

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

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
child_create_optionsthe options for creating the new child data provider
Returns
the new child data 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

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

◆ deleteChildProviderImpl()

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

Deletes a child data provider.

Parameters
namethe name of the new child data provider
child_delete_optionsthe options for deleting a child data 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

◆ deleteFieldImpl()

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

Deletes an existing field.

Parameters
namethe name of the field to delete
field_delete_optionsthe options for deleting the new field
Since
DataProvider 2.0

◆ 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
DELETE-RECORDS-ERRORerror deleting records

◆ 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

◆ getChildCreateOptions()

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

Returns options that can be used for creating child data providers.

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

◆ getChildDeleteOptions()

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

Returns options that can be used for deleting child data providers.

Returns
a hash of options that can be used for delete child data providers; keys are option names, values describe the option; if NOTHING is returned, then the provider does not support any child deletion options
Since
DataProvider 2.0

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

◆ 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

◆ getFieldAddOptions()

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

Returns options that can be used for adding new fields to the data provider.

Returns
a hash of options that can be used for adding new fields; keys are option names, values describe the option; if NOTHING is returned, then the provider does not support any add field options
Since
DataProvider 2.0

◆ getFieldDeleteOptions()

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

Returns options that can be used for deleting fields from the data provider.

Returns
a hash of options that can be used for deleting fields; keys are option names, values describe the option; if NOTHING is returned, then the provider does not support any delete field options
Since
DataProvider 2.0

◆ getFieldUpdateOptions()

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

Returns options that can be used for updating fields of the data provider.

Returns
a hash of options that can be used for updating fields; keys are option names, values describe the option; if NOTHING is returned, then the provider does not support any update field options
Since
DataProvider 2.0

◆ 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

◆ 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

◆ 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

◆ getSchemaObjectImpl()

object DataProvider::AbstractDataProvider::getSchemaObjectImpl ( )
private

Returns the schema object supporting this data provider.

Returns
the schema object supporting this data provider
Since
DataProvider 2.2

◆ getSchemaType()

*object DataProvider::AbstractDataProvider::getSchemaType ( )

Returns the schema type for this data provider or NOTHING if no schema type is supported.

Since
DataProvider 2.2

◆ 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

See also
:

◆ 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

◆ supportsAddField()

bool DataProvider::AbstractDataProvider::supportsAddField ( )

Returns True if the data provider supports creating adding new fields.

Since
DataProvider 2.0

◆ supportsCreateChild()

bool DataProvider::AbstractDataProvider::supportsCreateChild ( )

Returns True if the data provider supports creating new child data providers.

Since
DataProvider 2.0

◆ supportsDeleteChild()

bool DataProvider::AbstractDataProvider::supportsDeleteChild ( )

Returns True if the data provider supports creating deleting child data providers.

Since
DataProvider 2.0

◆ supportsDeleteField()

bool DataProvider::AbstractDataProvider::supportsDeleteField ( )

Returns True if the data provider supports deleting existing fields.

Since
DataProvider 2.0

◆ supportsSchema()

bool DataProvider::AbstractDataProvider::supportsSchema ( )

Returns True if the data provider supports a schema.

Since
DataProvider 2.2

◆ supportsUpdateField()

bool DataProvider::AbstractDataProvider::supportsUpdateField ( )

Returns True if the data provider supports updating existing fields.

Since
DataProvider 2.0

◆ throwUnimplementedException()

DataProvider::AbstractDataProvider::throwUnimplementedException ( )
private

Throws an INVALID-OPERATION exception.

Exceptions
INVALID-OPERATIONthis exception is thrown unconditionally by this method

◆ 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

◆ updateFieldImpl()

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

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
Since
DataProvider 2.0

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

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

◆ 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

◆ validateChildCreateOptions()

*hash<auto> DataProvider::AbstractDataProvider::validateChildCreateOptions ( *hash< auto >  child_create_options)
private

validates child create options

Exceptions
CHILD-CREATE-OPTION-ERRORinvalid or unsupported child create option
Since
DataProvider 2.0

◆ validateChildDeleteOptions()

*hash<auto> DataProvider::AbstractDataProvider::validateChildDeleteOptions ( *hash< auto >  child_delete_options)
private

validates child delete options

Exceptions
CHILD-DELETE-OPTION-ERRORinvalid or unsupported child delete option
Since
DataProvider 2.0

◆ validateCreateOptions()

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

validates create options

Exceptions
CREATE-OPTION-ERRORinvalid or unsupported create option

◆ validateFieldAddOptions()

*hash<auto> DataProvider::AbstractDataProvider::validateFieldAddOptions ( *hash< auto >  field_add_options)
private

validates field add options

Exceptions
FIELD-ADD-OPTION-ERRORinvalid or unsupported field add option
Since
DataProvider 2.0

◆ validateFieldDeleteOptions()

*hash<auto> DataProvider::AbstractDataProvider::validateFieldDeleteOptions ( *hash< auto >  field_delete_options)
private

validates field delete options

Exceptions
FIELD-DELETE-OPTION-ERRORinvalid or unsupported field delete option
Since
DataProvider 2.0

◆ validateFieldUpdateOptions()

*hash<auto> DataProvider::AbstractDataProvider::validateFieldUpdateOptions ( *hash< auto >  field_update_options)
private

validates field update options

Exceptions
FIELD-UPDATE-OPTION-ERRORinvalid or unsupported field update option
Since
DataProvider 2.0

◆ 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

Member Data Documentation

◆ 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