Loading...
Searching...
No Matches
DataProvider::AbstractDataProvider Class Reference

The AbstractDataProvider class. More...

`#include <AbstractDataProvider.qc.dox.h>`

Inheritance diagram for DataProvider::AbstractDataProvider:
[legend]

## Public Member Functions

| addField (AbstractDataField field, *hash< auto > field_add_options)
| Creates a new field.
| beginTransaction ()
| Begins a transaction with a data provider.
| checkAddField ()
| Ensures that the data provider supports adding fields.
| checkCreate ()
| Ensures that the data provider supports record creation.
| checkCreateChild ()
| Ensures that the data provider supports creating children.
| checkDelete ()
| Ensures that the data provider supports record deletion.
| checkDeleteChild ()
| Ensures that the data provider supports deleting children.
| checkDeleteField ()
| Ensures that the data provider supports deleting fields.
| checkMessages ()
| Ensures that the data provider supports sending messages.
| checkObservable ()
| Ensures that the data provider supports observer pattern / event API.
| checkRead ()
| Ensures that the data provider supports read operations.
| checkRequest ()
| Ensures that the data provider supports the request API.
| checkSchema ()
| Ensures that the data provider supports a schema.
| checkSearchExpressions ()
| Ensures that the data provider supports advanced search expressions.
| checkUpdate ()
| Ensures that the data provider supports record upserts.
| checkUpdateField ()
| Ensures that the data provider supports updating fields.
| checkUpsert ()
| Ensures that the data provider supports record upserts.
| commit ()
| Commits data written to the data provider.
| constructor ()
| Creates the data provider.
| constructor (LoggerInterface logger)
| Creates the data provider with the given Logger.
AbstractDataProvider | createChildProvider (string name, hash< string, AbstractDataField > fields, *hash< auto > child_create_options)
| Creates a new child data provider and returns it after adding as a child.
*hash< auto > | createRecord (hash< auto > rec, *hash< auto > create_options)
| Creates the given record in the data provider.
| deleteChildProvider (string name, *hash< auto > child_delete_options)
| Deletes a child data provider.
| deleteField (string name, *hash< auto > field_delete_options)
| Deletes an existing field.
int | deleteRecords (*hash< auto > where_cond, *hash< auto > search_options)
| Deletes zero or more records.
int | deleteRecords (*hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Deletes zero or more records.
auto | doRequest (auto req, *hash< auto > request_options)
| Makes a request and returns the response.
*hash< auto > | getAdditionalInfo ()
| Returns additional provider-specific information.
AbstractDataProviderBulkOperation | getBulkInserter ()
| Returns a bulk insert operation object for the data provider.
AbstractDataProviderBulkRecordInterface | getBulkRecordInterface (int block_size=1000, *hash< auto > search_options)
| Returns an iterator iterating all records with the bulk read API.
AbstractDataProviderBulkOperation | getBulkUpserter ()
| Returns a bulk upsert operation object for the data provider.
*AbstractDataProvider | getChildProvider (string name)
| Returns the given child provider or nothing if the given child is unknown.
AbstractDataProvider | getChildProviderEx (string name)
| Returns the given child provider or throws an exception if the given child is unknown.
*list< string > | getChildProviderNames ()
| Returns a list of child data provider names, if any.
AbstractDataProvider | getChildProviderPath (string path)
| Returns the given child provider from a `"/"` separated path string.
*list< hash< DataProviderSummaryInfo > > | getChildProviderSummaryInfo ()
| Return data provider summary info.
*hash< DataProviderConnectionInfo > | getConnectionInfo ()
| Returns connection info if the data provider supports connections, otherwise returns NOTHING.
*string | getDesc ()
| Returns the data provider description.
string | getDisplayName ()
| Returns the data provider display name.
*list< hash< AllowedValueInfo > > | getElementReferenceData (string type, *hash< auto > action_opts)
| Returns element reference data of the given kind if available.
*list< hash< AllowedValueInfo > > | getElementReferenceDataEx (string type, *hash< auto > action_opts)
| Returns element reference data of the given kind if available.
*list< hash< AllowedValueInfo > > | getElementReferenceDataSafe (string type, *hash< auto > action_opts)
| Returns element reference data of the given kind if available; logs but ignores exceptions retrieving the data.
*list< hash< AllowedValueInfo > > | getElementReferenceDataSafeEx (string type, *hash< auto > action_opts)
| Returns element reference data of the given kind if available.
AbstractDataProviderType | getErrorResponseType (string error_code)
| Returns the type for the given error code.
*hash< string, AbstractDataProviderType > | getErrorResponseTypes ()
| Returns a hash of error responses, if any.
hash< DataProviderMessageInfo > | getEventInfo (string event_id)
| Returns the description of an observable event, if any.
hash< DataProviderMessageInfo > | getEventInfoWithData (string event_id, auto req)
| Returns the description of an observable event, if any with option data, if any.
hash< string, hash< DataProviderMessageInfo > > | getEventTypes ()
| Returns a hash of all supported event types.
auto | getExampleErrorResponseData (string error_code)
| Returns example data for the error message with the given error code.
auto | getExampleEventData (string event_id)
| Returns example data for the given observable event.
hash< auto > | getExampleRecordData ()
| Returns example data for the record type.
auto | getExampleRequestData ()
| Returns example data for a request message.
auto | getExampleResponseData ()
| Returns example data for a successful request message.
hash< DataProviderInfo > | getInfo ()
| Returns data provider info.
hash< auto > | getInfoAsData (*bool with_type_info)
| Returns static provider information as data; no objects are returned.
*hash< string, hash< MapperRuntimeKeyInfo > > | getMapperRuntimeKeys ()
| Returns custom data mapper runtime keys.
hash< DataProviderMessageInfo > | getMessageInfo (string message_id)
| Returns the description of an outbound message, if any.
hash< string, hash< DataProviderMessageInfo > > | getMessageTypes ()
| Returns a hash of all supported outbound messages.
AbstractDataProviderRecordIterator | getRecordIterator (*hash< auto > search_options)
| Returns an iterator iterating all records.
*list< hash< AllowedValueInfo > > | getReferenceData (string type, *hash< auto > action_opts)
| Returns reference data of the given kind if available.
*list< hash< AllowedValueInfo > > | getReferenceDataEx (string type, *hash< auto > action_opts)
| Returns reference data of the given kind if available.
*list< hash< AllowedValueInfo > > | getReferenceDataSafe (string type, *hash< auto > action_opts)
| Returns reference data of the given kind if available; logs but ignores exceptions retrieving the data.
*list< hash< AllowedValueInfo > > | getReferenceDataSafeEx (string type, *hash< auto > action_opts)
| Returns reference data of the given kind if available.
auto | getReferenceDataValue (string type, *hash< auto > action_opts)
| Returns a reference data value of the given kind if available.
auto | getReferenceDataValueEx (string type, *hash< auto > action_opts)
| Returns a reference data value of the given kind if available.
auto | getReferenceDataValueSafe (string type, *hash< auto > action_opts)
| Returns a reference data value of the given kind if available; logs but ignores exceptions retrieving the data.
auto | getReferenceDataValueSafeEx (string type, *hash< auto > action_opts)
| Returns reference data of the given kind if available.
*AbstractDataProviderType | getRequestType ()
| Returns the description of a successful request message, if any.
*AbstractDataProviderType | getRequestTypeWithData (auto req)
| Returns the description of a successful request message with call data, if any.
*AbstractDataProviderType | getResponseType ()
| Returns the description of a response message, if this object represents a response message.
*AbstractDataProviderType | getResponseTypeWithData (auto req)
| Returns the description of a successful response message with call data, if any.
object | getSchemaObject ()
| Returns the schema supporting this data provider.
*hash< auto > | getSearchExpression (*hash< auto > where_cond, *hash< auto > search_options)
| Returns a search expression for a standard search hash.
*string | getShortDesc ()
| Returns the data provider short description.
hash< DataProviderSummaryInfo > | getSummaryInfo ()
| Return data provider summary info.
*hash< string, bool > | getSupportedElementReferenceData ()
| Returns information on supported element reference data.
*hash< string, bool > | getSupportedReferenceData ()
| Returns information on supported reference data.
*hash< string, bool > | getSupportedReferenceDataValues ()
| Returns information on supported reference data values.
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.
AbstractDataProviderRecordIterator | requestSearchRecords (auto req, *hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options according to an API request.
bool | requiresTransactionManagement ()
| Returns True if the data provider requires transaction management.
| rollback ()
| Rolls back data written to the data provider.
*hash< auto > | searchFirstRecord (hash< auto > where_cond, *hash< auto > search_options)
| Returns the first record matching the search options.
*hash< auto > | searchFirstRecord (hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Returns the first record matching the search options.
AbstractDataProviderRecordIterator | searchRecords (*hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options.
AbstractDataProviderRecordIterator | searchRecords (*hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options.
AbstractDataProviderBulkRecordInterface | searchRecordsBulk (int block_size=1000, *hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options.
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.
*hash< auto > | searchSingleRecord (hash< auto > where_cond, *hash< auto > search_options)
| Returns a single record matching the search options.
*hash< auto > | searchSingleRecord (hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Returns a single record matching the search options.
| sendMessage (string message_id, auto msg, *hash< auto > send_message_options)
| Sends a message from message-capable data providers.
*hash< string, hash< ActionOptionInfo > > | tryGetActionOptionsFromRequestTypeWithData (auto req)
| Returns action options corresponding to the request type with the given request data, if possible.
*hash< string, hash< ActionOptionInfo > > | tryGetActionOptionsWithData (hash< DataProviderActionInfo > action, auto req)
| Returns action options corresponding to the given option data.
| updateConnectionObjects (object conn, object connobj)
| Update any connection used by the data provider.
| updateField (string name, AbstractDataField field, *hash< auto > field_update_options)
| Updates an existing field.
int | updateRecords (hash< auto > set, *hash< auto > where_cond, *hash< auto > search_options)
| Updates zero or more records matching the search options.
int | updateRecords (hash< auto > set, *hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Updates zero or more records matching the search options.
bool | updateSingleRecord (hash< auto > set, hash< auto > where_cond, *hash< auto > search_options)
| Updates a single record matching the search options.
bool | updateSingleRecord (hash< auto > set, hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Updates a single record matching the search options.
string | upsertRecord (hash< auto > rec, *hash< auto > upsert_options)
| Upserts the given record in the data provider.

## Static Public Member Functions

static auto | evalGenericExpressionValue (hash< auto > rec, auto val)
| Evaluates the given expression with the generic internal implementation and returns the result.
static bool | setDynamicValueCallbacks ()
| Ensures that no callbacks can be set for dynamic URI resolution.

## Public Attributes

const | DataProviderSummaryInfoKeys = map $1.getName()
| A list of members names of the DataProviderSummaryInfoKeys hashdecl.
const | GenericExpressionImplementations = ...
| Generic expression implementations for data providers without native search functionality.
const | GenericExpressions = map {$1.key: $1.value.exp}
| Generic search operator expressions.
const | GenericRecordSearchOptions = ...
| Generic record search options; see details below.

## Protected Member Functions

hash< DataProviderExpression > | getEqualityComparisonExpression (int role, hash< DataProviderInfo > info, string key, auto value)
| Returns an equality comparison expression.
hash< DataProviderExpression > | getSimpleArgumentIntern (int role, hash< DataProviderInfo > info, hash< DataProviderExpressionInfo > expinfo, string key, auto value)
| Returns an argument for an expression.
*hash< string, hash< ActionOptionInfo > > | tryGetActionOptionsWithDataImpl (hash< DataProviderActionInfo > action, auto req)
| Returns action options corresponding to the given option data.

## Static Protected Member Functions

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

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

## beginTransaction()

DataProvider::AbstractDataProvider::beginTransaction | ( |  | ) |

Begins a transaction with a data provider.

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

See also
  :
  - 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

## checkMessages()

DataProvider::AbstractDataProvider::checkMessages | ( |  | ) |

Ensures that the data provider supports sending messages.

Exceptions

  INVALID-OPERATION | the data provider does not support sending messages

Since
  DataProvider 2.5

## checkObservable()

DataProvider::AbstractDataProvider::checkObservable | ( |  | ) |

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

Exceptions

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

Since
  DataProvider 2.5

## checkRead()

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

Ensures that the data provider supports read operations.

Exceptions

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

## checkRequest()

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

Ensures that the data provider supports the request API.

Exceptions

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

## checkSchema()

DataProvider::AbstractDataProvider::checkSchema | ( |  | ) |

Ensures that the data provider supports a schema.

Exceptions

  INVALID-OPERATION | the data provider does not support a schema

Since
  DataProvider 2.2

## checkSearchExpressions()

DataProvider::AbstractDataProvider::checkSearchExpressions | ( |  | ) |

Ensures that the data provider supports advanced search expressions.

Exceptions

  INVALID-OPERATION | the data provider does not support advanced search expressions

Since
  DataProvider 2.2

## checkUpdate()

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

Ensures that the data provider supports record upserts.

Exceptions

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

## checkUpdateField()

DataProvider::AbstractDataProvider::checkUpdateField | ( |  | ) |

Ensures that the data provider supports updating fields.

Exceptions

  INVALID-OPERATION | the data provider does not support the update field API

Since
  DataProvider 2.0

## checkUpsert()

DataProvider::AbstractDataProvider::checkUpsert | ( |  | ) |

Ensures that the data provider supports record upserts.

Exceptions

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

## commit()

DataProvider::AbstractDataProvider::commit | ( |  | ) |

Commits data written to the data provider.

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

See also
  :
  - 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

## createRecord()

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

Creates the given record in the data provider.

Parameters

  rec | a hash representing a single input record
  create_options | the create options; will be processed by validateCreateOptions()

Returns
  the data written to the data provider

Exceptions

  INVALID-OPERATION | the data provider does not support record creation
  CREATE-RECORD-ERROR | the data provider raised an exception in the record creation operation
  DUPLICATE-RECORD | this exception should be thrown if the provider fails due to an attempt to create a duplicate record

## deleteChildProvider()

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

Deletes a child data provider.

Parameters

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

Exceptions

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

Since
  DataProvider 2.0

## deleteField()

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

Deletes an existing field.

Parameters

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

Exceptions

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

Since
  DataProvider 2.0

## deleteRecords() [1/2]

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

Deletes zero or more records.

Parameters

  where_cond | a hash for identifying the record(s) to be deleted; will be processed by processFieldValues()
  search_options | the search options; will be processed by validateSearchOptions()

Returns
  the number of records deleted

Exceptions

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

## deleteRecords() [2/2]

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

Deletes zero or more records.

Parameters

  where_cond | a hash for identifying the record(s) to be deleted; will be processed by processSearchParameters()
  search_options | the search options; will be processed by validateSearchOptions()

Returns
  the number of records deleted

Exceptions

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

Since
  DataProvider 2.3

## doRequest()

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

Makes a request and returns the response.

Parameters

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

Returns
  the response to the request

Exceptions

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

## evalGenericExpressionValue()

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

static

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

Since
  DataProvider 2.3

## getAdditionalInfo()

*hash< auto > DataProvider::AbstractDataProvider::getAdditionalInfo | ( |  | ) |

Returns additional provider-specific information.

Since
  DataProvider 3.0

## getBulkInserter()

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

Returns a bulk insert operation object for the data provider.

Returns
  a bulk insert operation object for the data provider

Exceptions

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

## getBulkRecordInterface()

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

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

Parameters

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

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

Exceptions

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

## getBulkUpserter()

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

Returns a bulk upsert operation object for the data provider.

Returns
  a bulk upsert operation object for the data provider

Exceptions

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

## getChildProvider()

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

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

Parameters

  name | the name of the child

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.

Parameters

  name | the name of the child

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

Exceptions

  INVALID-CHILD-PROVIDER | unknown child provider

See also
  getChildProvider()

## getChildProviderNames()

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

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

Returns
  a list of child data provider names, if any

## getChildProviderPath()

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

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

throws an exception with unknown path elements

Parameters

  path | a string giving a path to the target provider where child elements are separated by `"/"` characters

Returns
  the target child provider; throws an exception if any element in the path is unknown

Exceptions

  INVALID-CHILD-PROVIDER | unknown child provider

## getChildProviderSummaryInfo()

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

Return data provider summary info.

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

## getConnectionInfo()

*hash< DataProviderConnectionInfo > DataProvider::AbstractDataProvider::getConnectionInfo | ( |  | ) |

Returns connection info if the data provider supports connections, otherwise returns NOTHING.

Returns
  connection info if the data provider supports connections, otherwise returns NOTHING

Since
  DataProvider 3.0

## getDisplayName()

string DataProvider::AbstractDataProvider::getDisplayName | ( |  | ) |

Returns the data provider display name.

Since
  DataProvider 3.0

## getElementReferenceData()

*list< hash< AllowedValueInfo > > DataProvider::AbstractDataProvider::getElementReferenceData | ( | string | type,
|  | *hash< auto > | action_opts )

Returns element reference data of the given kind if available.

Parameters

  type | the unique type name of the element reference data
  action_opts | an optional hash of action options when called when working with an app action

Returns
  a list of allowed values for this data

Exceptions

  ELEMENT-REFERENCE-DATA-ERROR | thrown if there is an error retrieving the element reference data

Since
  DataProvider 3.0

## getElementReferenceDataEx()

*list< hash< AllowedValueInfo > > DataProvider::AbstractDataProvider::getElementReferenceDataEx | ( | string | type,
|  | *hash< auto > | action_opts )

Returns element reference data of the given kind if available.

Parameters

  type | the unique type name of the element reference data
  action_opts | an optional hash of action options when called when working with an app action

Returns
  a list of allowed values for this data

Exceptions

  ELEMENT-REFERENCE-DATA-ERROR | thrown if there is an error retrieving the element reference data
  UNSUPPORTED-ELEMENT-REFERENCE-DATA | thrown if type is not supported as element reference data

Since
  DataProvider 3.0

## getElementReferenceDataSafe()

*list< hash< AllowedValueInfo > > DataProvider::AbstractDataProvider::getElementReferenceDataSafe | ( | string | type,
|  | *hash< auto > | action_opts )

Returns element reference data of the given kind if available; logs but ignores exceptions retrieving the data.

Parameters

  type | the unique type name of the element reference data
  action_opts | an optional hash of action options when called when working with an app action

Returns
  a list of allowed values for this data or nothing if an exception occured retrieving the element reference data

Since
  DataProvider 3.0

## getElementReferenceDataSafeEx()

*list< hash< AllowedValueInfo > > DataProvider::AbstractDataProvider::getElementReferenceDataSafeEx | ( | string | type,
|  | *hash< auto > | action_opts )

Returns element reference data of the given kind if available.

Parameters

  type | the unique type name of the element reference data
  action_opts | an optional hash of action options when called when working with an app action

Returns
  a list of allowed values for this data or nothing if an exception occured retrieving the element reference data

Logs but ignores exceptions retrieving the data; throws an exception if the data type is unsupported

Exceptions

  UNSUPPORTED-ELEMENT-REFERENCE-DATA | thrown if type is not supported as element reference data

Since
  DataProvider 3.0

## getEqualityComparisonExpression()

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

protected

Returns an equality comparison expression.

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

Since
  DataProvider 2.3

## getErrorResponseType()

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

Returns the type for the given error code.

Parameters

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

Returns
  the type for the given error code

Exceptions

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

## getErrorResponseTypes()

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

Returns a hash of error responses, if any.

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

Exceptions

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

## getEventInfo()

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

Returns the description of an observable event, if any.

Parameters

  event_id | the event ID of the event

Returns
  the observable event type for this provider

Exceptions

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

Since
  DataProvider 2.5

## getEventInfoWithData()

hash< DataProviderMessageInfo > DataProvider::AbstractDataProvider::getEventInfoWithData | ( | string | event_id,
|  | auto | req )

Returns the description of an observable event, if any with option data, if any.

Parameters

  event_id | the event ID of the event
  req | example option data that can be used to determine the final type

Returns
  the event type for this provider according to any call data passed

Exceptions

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

Note
  This API is meant to provide information about event data types that can depend on option data

Since
  DataProvider 3.0

## getEventTypes()

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

Returns a hash of all supported event types.

Returns
  a hash of all supported event types

Exceptions

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

Since
  DataProvider 2.5

## getExampleErrorResponseData()

auto DataProvider::AbstractDataProvider::getExampleErrorResponseData | ( | string | error_code | ) |

Returns example data for the error message with 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
  example data for the error message with 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

Since
  DataProvider 3.0

## getExampleEventData()

auto DataProvider::AbstractDataProvider::getExampleEventData | ( | string | event_id | ) |

Returns example data for the given observable event.

Parameters

  event_id | the event ID of the event

Returns
  example data for the given observable event

Exceptions

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

Since
  DataProvider 3.0

## getExampleRecordData()

hash< auto > DataProvider::AbstractDataProvider::getExampleRecordData | ( |  | ) |

Returns example data for the record type.

Returns
  example data for the record type

Since
  DataProvider 3.0

## getExampleRequestData()

auto DataProvider::AbstractDataProvider::getExampleRequestData | ( |  | ) |

Returns example data for a request message.

Returns
  example data for a request message

Exceptions

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

Since
  DataProvider 3.0

## getExampleResponseData()

auto DataProvider::AbstractDataProvider::getExampleResponseData | ( |  | ) |

Returns example data for a successful request message.

Returns
  example data for a successful request message

Exceptions

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

Since
  DataProvider 3.0

## getExpression()

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

staticprotected

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

Since
  DataProvider 2.3

## getInfoAsData()

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

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

Parameters

  with_type_info | if True then more type information will be returned in the response

Note
  the `name` and `children` attributes are not returned as they are dynamic attributes

## getMapperRuntimeKeys()

*hash< string, hash< MapperRuntimeKeyInfo > > DataProvider::AbstractDataProvider::getMapperRuntimeKeys | ( |  | ) |

Returns custom data mapper runtime keys.

Returns
  custom data mapper runtime keys

This base method returns nothing; reimplment in child classes to return a value

## getMessageInfo()

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

Returns the description of an outbound message, if any.

Parameters

  message_id | the ID of the message

Returns
  the message type for this provider

Exceptions

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

Since
  DataProvider 2.5

## getMessageTypes()

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

Returns a hash of all supported outbound messages.

Returns
  a hash of all supported outbound messages

Exceptions

  INVALID-OPERATION | the data provider does not support sending messages

Since
  DataProvider 2.5

## getRecordIterator()

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

Returns an iterator iterating all records.

Parameters

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

Exceptions

  INVALID-OPERATION | the data provider does not support reading

## getReferenceData()

*list< hash< AllowedValueInfo > > DataProvider::AbstractDataProvider::getReferenceData | ( | string | type,
|  | *hash< auto > | action_opts )

Returns reference data of the given kind if available.

Parameters

  type | the unique type name of the reference data
  action_opts | an optional hash of action options when called when working with an app action

Returns
  a list of allowed values for this data

Exceptions

  REFERENCE-DATA-ERROR | thrown if there is an error retrieving the reference data

Since
  DataProvider 3.0

## getReferenceDataEx()

*list< hash< AllowedValueInfo > > DataProvider::AbstractDataProvider::getReferenceDataEx | ( | string | type,
|  | *hash< auto > | action_opts )

Returns reference data of the given kind if available.

Parameters

  type | the unique type name of the reference data
  action_opts | an optional hash of action options when called when working with an app action

Returns
  a list of allowed values for this data

Exceptions

  REFERENCE-DATA-ERROR | thrown if there is an error retrieving the reference data
  UNSUPPORTED-REFERENCE-DATA | thrown if type is not supported as reference data

Since
  DataProvider 3.0

## getReferenceDataSafe()

*list< hash< AllowedValueInfo > > DataProvider::AbstractDataProvider::getReferenceDataSafe | ( | string | type,
|  | *hash< auto > | action_opts )

Returns reference data of the given kind if available; logs but ignores exceptions retrieving the data.

Parameters

  type | the unique type name of the reference data
  action_opts | an optional hash of action options when called when working with an app action

Returns
  a list of allowed values for this data or nothing if an exception occured retrieving the reference data

Since
  DataProvider 3.0

## getReferenceDataSafeEx()

*list< hash< AllowedValueInfo > > DataProvider::AbstractDataProvider::getReferenceDataSafeEx | ( | string | type,
|  | *hash< auto > | action_opts )

Returns reference data of the given kind if available.

Parameters

  type | the unique type name of the reference data
  action_opts | an optional hash of action options when called when working with an app action

Returns
  a list of allowed values for this data or nothing if an exception occured retrieving the reference data

Logs but ignores exceptions retrieving the data; throws an exception if the data type is unsupported

Exceptions

  UNSUPPORTED-REFERENCE-DATA | thrown if type is not supported as reference data

Since
  DataProvider 3.0

## getReferenceDataValue()

auto DataProvider::AbstractDataProvider::getReferenceDataValue | ( | string | type,
|  | *hash< auto > | action_opts )

Returns a reference data value of the given kind if available.

Parameters

  type | the unique type name of the reference data
  action_opts | an optional hash of action options when called when working with an app action

Returns
  the value of the reference data

Exceptions

  REFERENCE-DATA-ERROR | thrown if there is an error retrieving the reference data

Since
  DataProvider 3.0

## getReferenceDataValueEx()

auto DataProvider::AbstractDataProvider::getReferenceDataValueEx | ( | string | type,
|  | *hash< auto > | action_opts )

Returns a reference data value of the given kind if available.

Parameters

  type | the unique type name of the reference data
  action_opts | an optional hash of action options when called when working with an app action

Returns
  the value of the reference data

Exceptions

  REFERENCE-DATA-ERROR | thrown if there is an error retrieving the reference data
  UNSUPPORTED-REFERENCE-DATA | thrown if type is not supported as reference data

Since
  DataProvider 3.0

## getReferenceDataValueSafe()

auto DataProvider::AbstractDataProvider::getReferenceDataValueSafe | ( | string | type,
|  | *hash< auto > | action_opts )

Returns a reference data value of the given kind if available; logs but ignores exceptions retrieving the data.

Parameters

  type | the unique type name of the reference data value
  action_opts | an optional hash of action options when called when working with an app action

Returns
  the reference data value or nothing if an exception occured retrieving the reference data value

Since
  DataProvider 3.0

## getReferenceDataValueSafeEx()

auto DataProvider::AbstractDataProvider::getReferenceDataValueSafeEx | ( | string | type,
|  | *hash< auto > | action_opts )

Returns reference data of the given kind if available.

Parameters

  type | the unique type name of the reference data
  action_opts | an optional hash of action options when called when working with an app action

Returns
  a list of allowed values for this data or nothing if an exception occured retrieving the reference data

Logs but ignores exceptions retrieving the data; throws an exception if the data type is unsupported

Exceptions

  UNSUPPORTED-REFERENCE-DATA | thrown if type is not supported as reference data

Since
  DataProvider 3.0

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

## getRequestTypeWithData()

*AbstractDataProviderType DataProvider::AbstractDataProvider::getRequestTypeWithData | ( | auto | req | ) |

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

Parameters

  req | sample request data that can be used to determine the final type

Returns
  the request type for this provider according to any call data passed

Exceptions

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

Note
  This API is meant to provide information about request data types that can depend on the call data

Since
  DataProvider 3.0

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

## getResponseTypeWithData()

*AbstractDataProviderType DataProvider::AbstractDataProvider::getResponseTypeWithData | ( | auto | req | ) |

Returns the description of a successful response message with call data, if any.

Parameters

  req | sample request data that can be used to determine the final type

Returns
  the response type for this provider according to any call data passed

Exceptions

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

Note
  This API is meant to provide information about response data types that can depend on the call data

Since
  DataProvider 3.0

## getSchemaObject()

object DataProvider::AbstractDataProvider::getSchemaObject | ( |  | ) |

Returns the schema supporting this data provider.

Returns
  the schema supporting this data provider

Exceptions

  INVALID-OPERATION | thrown if the data provider does not support this API

Since
  DataProvider 2.2

## getSearchExpression()

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

Returns a search expression for a standard search hash.

Parameters

  where_cond | the search criteria; if the data provider supports advanced search, and the value is an expression, it will be processed by processSearchParameters(), otherwise by processFieldValues()
  search_options | the search options; will be processed by validateSearchOptions()

Returns
  a search expression corresponding to where_cond

Since
  DataProvider 2.3

## getShortDesc()

*string DataProvider::AbstractDataProvider::getShortDesc | ( |  | ) |

Returns the data provider short description.

Since
  DataProvider 3.0

## getSimpleArgumentIntern()

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

protected

Returns an argument for an expression.

Since
  DataProvider 2.3

## getSupportedElementReferenceData()

*hash< string, bool > DataProvider::AbstractDataProvider::getSupportedElementReferenceData | ( |  | ) |

Returns information on supported element reference data.

Returns
  a hash of supported element reference data; keys in the hash returned are supported in calls to getElementReferenceData()

Since
  DataProvider 3.0

## getSupportedReferenceData()

*hash< string, bool > DataProvider::AbstractDataProvider::getSupportedReferenceData | ( |  | ) |

Returns information on supported reference data.

Returns
  a hash of supported reference data; keys in the hash returned are supported in calls to getReferenceData()

Since
  DataProvider 3.0

## getSupportedReferenceDataValues()

*hash< string, bool > DataProvider::AbstractDataProvider::getSupportedReferenceDataValues | ( |  | ) |

Returns information on supported reference data values.

Returns
  a hash of supported reference data values; keys in the hash returned are supported in calls to getReferenceDataValue()

Since
  DataProvider 3.0

## requestSearchRecords() [1/2]

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

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

Parameters

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

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

Exceptions

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

## requestSearchRecords() [2/2]

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

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

Parameters

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

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

Exceptions

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

Since
  DataProvider 2.3

## requiresTransactionManagement()

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

Returns True if the data provider requires transaction management.

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

## rollback()

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

Rolls back data written to the data provider.

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

See also
  :
  - beginTransaction()
  - commit()

## searchFirstRecord() [1/2]

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

Returns the first record matching the search options.

Parameters

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

Exceptions

  INVALID-OPERATION | the data provider does not support reading

## searchFirstRecord() [2/2]

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

Returns the first record matching the search options.

Parameters

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

Exceptions

  INVALID-OPERATION | the data provider does not support reading

Since
  DataProvider 2.3

## searchRecords() [1/2]

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

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

Parameters

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

Exceptions

  INVALID-OPERATION | the data provider does not support reading

## searchRecords() [2/2]

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

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

Parameters

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

Exceptions

  INVALID-OPERATION | the data provider does not support reading

Since
  DataProvider 2.3

## searchRecordsBulk() [1/2]

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

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

Parameters

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

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

Exceptions

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

Since
  DataProvider 2.3

## searchRecordsBulk() [2/2]

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

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

Parameters

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

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

Exceptions

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

## searchSingleRecord() [1/2]

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

Returns a single record matching the search options.

Parameters

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

Exceptions

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

## searchSingleRecord() [2/2]

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

Returns a single record matching the search options.

Parameters

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

Exceptions

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

Since
  DataProvider 2.3

## sendMessage()

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

Sends a message from message-capable data providers.

Parameters

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

Exceptions

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

Since
  DataProvider 2.5

## setDynamicValueCallbacks()

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

static

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

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

Note
  after this call, callbacks cannot be changed

## tryGetActionOptionsFromRequestTypeWithData()

*hash< string, hash< ActionOptionInfo > > DataProvider::AbstractDataProvider::tryGetActionOptionsFromRequestTypeWithData | ( | auto | req | ) |

Returns action options corresponding to the request type with the given request data, if possible.

Parameters

  req | sample request data that can be used to determine the final type

Returns
  action options corresponding to the request type

Exceptions

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

Note
  This API is meant to provide information about request data types that can depend on the call data

Since
  DataProvider 3.0

## tryGetActionOptionsWithData()

*hash< string, hash< ActionOptionInfo > > DataProvider::AbstractDataProvider::tryGetActionOptionsWithData | ( | hash< DataProviderActionInfo > | action,
|  | auto | req )

Returns action options corresponding to the given option data.

Parameters

  req | sample option data that can be used to determine the final type

Returns
  action options according to the available option data

Note
  This API is meant to provide information about options that can depend on option data

Since
  DataProvider 3.1

## tryGetActionOptionsWithDataImpl()

*hash< string, hash< ActionOptionInfo > > DataProvider::AbstractDataProvider::tryGetActionOptionsWithDataImpl | ( | hash< DataProviderActionInfo > | action,
|  | auto | req )

protected

Returns action options corresponding to the given option data.

Parameters

  req | sample option data that can be used to determine the final type

Returns
  action options according to the available option data

Note
  This API is meant to provide information about options that can depend on option data

Since
  DataProvider 3.1

## updateConnectionObjects()

DataProvider::AbstractDataProvider::updateConnectionObjects | ( | object | conn,
|  | object | connobj )

Update any connection used by the data provider.

Parameters

  conn | the new AbstractConnection object
  connobj | the new connection object itself (ex: RestClient for a "rest" connection)

This is useful for event-driven providers that require a connection object to generate events.

Subclasses should implement appropriate logic

Since
  DataProvider 3.0

## updateField()

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

Updates an existing field.

Parameters

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

Exceptions

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

Since
  DataProvider 2.0

## updateRecords() [1/2]

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

Updates zero or more records matching the search options.

Parameters

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

Returns
  the number of records updated

Exceptions

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

## updateRecords() [2/2]

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

Updates zero or more records matching the search options.

Parameters

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

Returns
  the number of records updated

Exceptions

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

Since
  DataProvider 2.3

## updateSingleRecord() [1/2]

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

Updates a single record matching the search options.

Parameters

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

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

Exceptions

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

## updateSingleRecord() [2/2]

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

Updates a single record matching the search options.

Parameters

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

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

Exceptions

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

Since
  DataProvider 2.3

## upsertRecord()

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

Upserts the given record in the data provider.

Parameters

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

Returns
  see DB Provider Upsert Result Codes for possible values

Exceptions

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

## Member Data Documentation

## GenericExpressions

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

Generic search operator expressions.

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

Since
  DataProvider 2.3

## GenericRecordSearchOptions

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

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