DataProvider::AbstractDataProvider Class Referenceabstract

The AbstractDataProvider class. More...

Inheritance diagram for DataProvider::AbstractDataProvider:
[legend]

## Public Member Functions

| 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...
| 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< 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...
*hash< string, hash< DataProviderOptionInfo > > | getCreateOptions ()
| Returns options that can be used for creating records. More...
AbstractDataProviderType | getErrorResponseType (string error_code)
| Returns the type for the given error code. More...
*hash< string, AbstractDataProviderType > | getErrorResponseTypes ()
| Returns a hash of error responses, if any. More...
*hash< 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< 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...
abstract string | getName ()
| Returns the data provider name.
*hash< string, AbstractDataField > | getOrNothingRecordType (*hash< auto > search_options)
| Returns the description of the record type with "or nothing" types, if any.
AbstractDataProviderRecordIterator | getRecordIterator (*hash< auto > search_options)
| Returns an iterator iterating all records. More...
*hash< string, AbstractDataField > | getRecordType (*hash< auto > search_options)
| Returns the description of the record type, if any. More...
*hash< string, hash< DataProviderOptionInfo > > | getRequestOptions ()
| Returns options that can be used for requests. More...
*AbstractDataProviderType | getRequestType ()
| Returns the description of a successful request message, if any. More...
*AbstractDataProviderType | getResponseType ()
| Returns the description of a response message, if this object represents a response message. More...
*hash< string, hash< DataProviderOptionInfo > > | getSearchOptions ()
| Returns options that can be used for searching. More...
*hash< string, AbstractDataField > | getSoftRecordType (*hash< auto > search_options)
| Returns the description of the record type with soft types, if any.
*hash< string, hash< DataProviderOptionInfo > > | getUpsertOptions ()
| Returns options that can be used for upserting records. More...
bool | hasRecord ()
| Returns True if the data provider has a record type. More...
bool | recordRequiresSearchOptions ()
| Returns True if the data provider requires search options to retrieve the record type.
AbstractDataProviderRecordIterator | requestSearchRecords (auto req, *hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options according to an API request. More...
bool | requiresTransactionManagement ()
| Returns True if the data provider supports transaction management. More...
| rollback ()
| Rolls back data written to the data provider. More...
*hash< auto > | searchFirstRecord (hash< auto > where_cond, *hash< auto > search_options)
| Returns the first record matching the search options. More...
AbstractDataProviderRecordIterator | searchRecords (*hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options. More...
AbstractDataProviderBulkRecordInterface | searchRecordsBulk (int block_size=1000, *hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options. More...
*hash< auto > | searchSingleRecord (hash< auto > where_cond, *hash< auto > search_options)
| Returns a single record matching the search options. More...
| 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 | 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 Functions

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

## Protected Member Functions

| 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< string > | getChildProviderNamesImpl ()
| Returns a list of child data provider names, if any. More...
AbstractDataProviderType | getErrorResponseTypeImpl (string error_code)
| Returns the type for the given error code. More...
*hash< string, AbstractDataProviderType > | getErrorResponseTypesImpl ()
| Returns a hash of error responses, if any. More...
*hash< string, AbstractDataField > | getRecordTypeImpl (*hash< auto > search_options)
| Returns the description of the record type, if any. More...
*AbstractDataProviderType | getRequestTypeImpl ()
| Returns the description of a successful request message, if any. More...
*AbstractDataProviderType | getResponseTypeImpl ()
| Returns the description of a response message, if this object represents a response message. More...
abstract hash< DataProviderInfo > | getStaticInfoImpl ()
| Returns data provider static info.
| processConstructorOptions (*hash< string, hash< DataProviderOptionInfo >> option_desc, *hash< auto > options)
| processes options passed to the constructor
*hash< auto > | processFieldValues (*hash< auto > h, *hash< auto > search_options)
| processes search or set values to convert types if necessary More...
AbstractDataProviderRecordIterator | requestSearchRecordsImpl (auto req, *hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options according to an API request. More...
*hash< auto > | searchFirstRecordImpl (hash< auto > where_cond, *hash< auto > search_options)
| Returns the first record matching the search options. More...
AbstractDataProviderBulkRecordInterface | searchRecordsBulkImpl (int block_size=1000, *hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options. More...
AbstractDataProviderRecordIterator | searchRecordsImpl (*hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options. More...
*hash< auto > | searchSingleRecordImpl (hash< auto > where_cond, *hash< auto > search_options)
| Returns a single record matching the search options. More...
| throwUnimplementedException ()
| Throws an `INVALID-OPERATION` exception. More...
| 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 Protected Member Functions

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

## Protected Attributes

Logger | logger
| Logger for logging.

## Static Protected Attributes

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

## Detailed Description

The AbstractDataProvider class.

## Member Function Documentation

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

## addFieldImpl()

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

protected

Creates a new field.

Parameters

  field | the field to add
  field_add_options | the 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
  :
  - commit()
  - rollback()

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

## checkRead()

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

Ensures that the data provider supports read operations.

Exceptions

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

## checkRequest()

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

Ensures that the data provider supports the request API.

Exceptions

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

## checkUpdate()

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

Ensures that the data provider supports record upserts.

Exceptions

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

## 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
  :
  - beginTransaction()
  - rollback()

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

## createChildProviderImpl()

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

protected

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
  child_create_options | the 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

  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

## createRecordImpl()

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

protected

Creates the given record to the data provider.

Parameters

  rec | a hash representing a single input record
  create_options | the create options after processing by validateCreateOptions()

Returns
  the data written to the data provider

Exceptions

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

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

## deleteChildProviderImpl()

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

protected

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

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

Exceptions

  INVALID-OPERATION | thrown if the data provider does not support this API
  DELETE-FIELD-ERROR | error adding the field

Since
  DataProvider 2.0

## deleteFieldImpl()

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

protected

Deletes an existing field.

Parameters

  name | the name of the field to delete
  field_delete_options | the 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_cond | a hash for identifying the record(s) to be deleted
  search_options | the search options; will be processed by validateSearchOptions()

Returns
  the number of records deleted

Exceptions

  INVALID-OPERATION | the data provider does not support record deletion
  DELETE-RECORDS-ERROR | error deleting records

## deleteRecordsImpl()

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

protected

Deletes zero or more records.

Parameters

  where_cond | a hash for identifying the record(s) to be deleted
  search_options | the delete options after processing by validateSearchOptions()

Returns
  the number of records deleted

## doRequest()

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

Makes a request and returns the response.

Parameters

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

Returns
  the response to the request

Exceptions

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

## doRequestImpl()

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

protected

Makes a request and returns the response.

Parameters

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

Returns
  the response to the request

## getBulkInserter()

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

Returns a bulk insert operation object for the data provider.

Returns
  a bulk insert operation object for the data provider

Exceptions

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

## getBulkRecordInterface()

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

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

Parameters

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

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

Exceptions

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

## getBulkUpserter()

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

Returns a bulk upsert operation object for the data provider.

Returns
  a bulk upsert operation object for the data provider

Exceptions

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

## 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-PROVIDER | unknown child provider

See also
  getChildProviderEx()

## getChildProviderEx()

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

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

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

Exceptions

  INVALID-CHILD-PROVIDER | unknown child provider

See also
  getChildProvider()

## getChildProviderImpl()

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

protected

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

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

## getChildProviderNames()

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

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

Returns
  a list of child data provider names, if any

## getChildProviderNamesImpl()

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

protected

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

Returns
  a list of child data provider names, if any

This base class method returns NOTHING

## getChildProviderPath()

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

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

throws an exception 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

## getCreateOptions()

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

Returns options that can be used for creating records.

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

## getErrorResponseType()

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

Returns the type for the given error code.

Parameters

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

Returns
  the type for the given error code

Exceptions

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

## getErrorResponseTypeImpl()

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

protected

Returns the type for the given error code.

Parameters

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

Returns
  the type for the given error code

Exceptions

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

## getErrorResponseTypes()

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

Returns a hash of error responses, if any.

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

Exceptions

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

## getErrorResponseTypesImpl()

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

protected

Returns a hash of error responses, if any.

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

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

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

## getRecordIterator()

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

Returns an iterator iterating all records.

Parameters

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

Exceptions

  INVALID-OPERATION | the data provider does not support reading

## getRecordType()

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

Returns the description of the record type, if any.

Parameters

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

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

## getRecordTypeImpl()

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

protected

Returns the description of the record type, if any.

Parameters

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

## getRequestOptions()

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

Returns options that can be used for requests.

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

## getRequestType()

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

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

Returns
  the request type for this provider

Exceptions

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

## getRequestTypeImpl()

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

protected

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

Returns
  the request type for this provider

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

## getResponseType()

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

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

Returns
  the response type for this response message

Exceptions

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

## getResponseTypeImpl()

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

protected

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

Returns
  the response type for this response message

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

## getSearchOptions()

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

Returns options that can be used for searching.

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

## getUpsertOptions()

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

Returns options that can be used for upserting records.

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

## hasRecord()

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

Returns True if the data provider has a record type.

Returns
  True if the data provider has a record type

## processFieldValues()

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

protected

processes search or set values to convert types if necessary

Parameters

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

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

## requestSearchRecords()

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

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

Parameters

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

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

Exceptions

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

## requestSearchRecordsImpl()

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

protected

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

Parameters

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

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

See also
  searchRecordsImpl()

## requiresTransactionManagement()

bool DataProvider::AbstractDataProvider::requiresTransactionManagement | ( |  | ) |

Returns True if the data provider supports transaction management.

Returns
  True if the data provider supports transaction management, in which case commit() or rollback() must be called to flush or discard data written to the data provider

## rollback()

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

Rolls back data written to the data provider.

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

See also
  :
  - beginTransaction()
  - commit()

## searchFirstRecord()

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

Returns the first record matching the search options.

Parameters

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

Exceptions

  INVALID-OPERATION | the data provider does not support reading

## searchFirstRecordImpl()

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

protected

Returns the first record matching the search options.

Parameters

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

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

## searchRecords()

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

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

Parameters

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

Exceptions

  INVALID-OPERATION | the data provider does not support reading

## searchRecordsBulk()

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

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

Parameters

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

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

Exceptions

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

## searchRecordsBulkImpl()

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

protected

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

Parameters

  block_size | the number of records in a read block; must be a positive number
  where_cond | the search criteria; after processing by processFieldValues()
  search_options | the search options after processing by validateSearchOptions()

Exceptions

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

## searchRecordsImpl()

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

protected

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

Parameters

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

See also
  requestSearchRecordsImpl()

## searchSingleRecord()

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

Returns a single record matching the search options.

Parameters

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

Exceptions

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

## searchSingleRecordImpl()

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

protected

Returns a single record matching the search options.

Parameters

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

Exceptions

  MULTIPLE-RECORDS-ERROR | multiple records found

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

## setDynamicValueCallbacks() [1/2]

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

static

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

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

Note
  after this call, callbacks cannot be changed

## setDynamicValueCallbacks() [2/2]

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

static

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

Parameters

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

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

Note
  after this call, callbacks cannot be changed

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

## supportsUpdateField()

bool DataProvider::AbstractDataProvider::supportsUpdateField | ( |  | ) |

Returns True if the data provider supports updating existing fields.

Since
  DataProvider 2.0

## throwUnimplementedException()

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

protected

Throws an `INVALID-OPERATION` exception.

Exceptions

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

  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

## updateFieldImpl()

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

protected

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

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

  set | the hash of field data to set
  where_cond | a hash for identifying the record(s) to be updated
  search_options | the search options; will be processed by validateSearchOptions()

Returns
  the number of records updated

Exceptions

  INVALID-OPERATION | the data provider does not support record updating
  UPDATE-RECORDS-ERROR | error updating records

## updateRecordsImpl()

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

protected

Updates zero or more records matching the search options.

Parameters

  set | the hash of field data to set
  where_cond | a hash for identifying the record(s) to be updated
  search_options | the update options after processing by validateSearchOptions()

Returns
  the number of records updated

## updateSingleRecord()

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

Updates a single record matching the search options.

Parameters

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

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

Exceptions

  INVALID-OPERATION | the data provider does not support record updating
  UPDATE-RECORDS-ERROR | error updating records

## updateSingleRecordImpl()

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

protected

Updates a single record matching the search options.

Parameters

  set | the hash of field data to set
  where_cond | the search criteria
  search_options | the search options after processing by validateSearchOptions()

## upsertRecord()

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

Upserts the given record in the data provider.

Parameters

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

Returns
  see DB Provider Upsert Result Codes for possible values

Exceptions

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

## upsertRecordImpl()

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

protected

Upserts the given record to the data provider.

Parameters

  rec | a hash representing a single input record
  upsert_options | the create options after processing by validateUpsertOptions()

Returns
  see DB Provider Upsert Result Codes for possible values

## validateChildCreateOptions()

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

protected

validates child create options

Exceptions

  CHILD-CREATE-OPTION-ERROR | invalid or unsupported child create option

Since
  DataProvider 2.0

## validateChildDeleteOptions()

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

protected

validates child delete options

Exceptions

  CHILD-DELETE-OPTION-ERROR | invalid or unsupported child delete option

Since
  DataProvider 2.0

## validateCreateOptions()

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

protected

validates create options

Exceptions

  CREATE-OPTION-ERROR | invalid or unsupported create option

## validateFieldAddOptions()

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

protected

validates field add options

Exceptions

  FIELD-ADD-OPTION-ERROR | invalid or unsupported field add option

Since
  DataProvider 2.0

## validateFieldDeleteOptions()

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

protected

validates field delete options

Exceptions

  FIELD-DELETE-OPTION-ERROR | invalid or unsupported field delete option

Since
  DataProvider 2.0

## validateFieldUpdateOptions()

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

protected

validates field update options

Exceptions

  FIELD-UPDATE-OPTION-ERROR | invalid or unsupported field update option

Since
  DataProvider 2.0

## validateRequestOptions()

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

protected

validates request options

Exceptions

  REQUEST-OPTION-ERROR | invalid or unsupported request option

## validateSearchOptions()

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

protected

validates search options

Exceptions

  SEARCH-OPTION-ERROR | invalid or unsupported search option

## validateUpsertOptions()

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

protected

validates upsert options

Exceptions

  UPSERT-OPTION-ERROR | invalid or unsupported upsert option