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. More...
| beginTransaction ()
| Begins a transaction with a data provider. More...
| checkAddField ()
| Ensures that the data provider supports adding fields. More...
| checkCreate ()
| Ensures that the data provider supports record creation. More...
| checkCreateChild ()
| Ensures that the data provider supports creating children. More...
| checkDelete ()
| Ensures that the data provider supports record deletion. More...
| checkDeleteChild ()
| Ensures that the data provider supports deleting children. More...
| checkDeleteField ()
| Ensures that the data provider supports deleting fields. More...
| checkMessages ()
| Ensures that the data provider supports sending messages. More...
| checkObservable ()
| Ensures that the data provider supports observer pattern / event API. More...
| checkRead ()
| Ensures that the data provider supports read operations. More...
| checkRequest ()
| Ensures that the data provider supports the request API. More...
| checkSchema ()
| Ensures that the data provider supports a schema. More...
| checkSearchExpressions ()
| Ensures that the data provider supports advanced search expressions. More...
| checkUpdate ()
| Ensures that the data provider supports record upserts. More...
| checkUpdateField ()
| Ensures that the data provider supports updating fields. More...
| checkUpsert ()
| Ensures that the data provider supports record upserts. More...
| commit ()
| Commits data written to the data provider. More...
| constructor ()
| Creates the data provider.
| constructor (Logger logger)
| Creates the data provider with the given Logger.
AbstractDataProvider | createChildProvider (string name, hash< string, AbstractDataField > fields, *hash< auto > child_create_options)
| Creates a new child data provider and returns it after adding as a child. More...
*hash< auto > | createRecord (hash< auto > rec, *hash< auto > create_options)
| Creates the given record in the data provider. More...
| deleteChildProvider (string name, *hash< auto > child_delete_options)
| Deletes a child data provider. More...
| deleteField (string name, *hash< auto > field_delete_options)
| Deletes an existing field. More...
int | deleteRecords (*hash< auto > where_cond, *hash< auto > search_options)
| Deletes zero or more records. More...
int | deleteRecords (*hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Deletes zero or more records. More...
auto | doRequest (auto req, *hash< auto > request_options)
| Makes a request and returns the response. More...
AbstractDataProviderBulkOperation | getBulkInserter ()
| Returns a bulk insert operation object for the data provider. More...
AbstractDataProviderBulkRecordInterface | getBulkRecordInterface (int block_size=1000, *hash< auto > search_options)
| Returns an iterator iterating all records with the bulk read API. More...
AbstractDataProviderBulkOperation | getBulkUpserter ()
| Returns a bulk upsert operation object for the data provider. More...
*AbstractDataProvider | getChildProvider (string name)
| Returns the given child provider or NOTHING if the given child is unknown. More...
AbstractDataProvider | getChildProviderEx (string name)
| Returns the given child provider or throws an exception if the given child is unknown. More...
*list< string > | getChildProviderNames ()
| Returns a list of child data provider names, if any. More...
AbstractDataProvider | getChildProviderPath (string path)
| Returns the given child provider from a `"/"` separated path string. More...
*list< hash< DataProviderSummaryInfo > > | getChildProviderSummaryInfo ()
| Return data provider summary info. More...
*string | getDesc ()
| Returns the data provider description.
private hash< DataProviderExpression > | getEqualityComparisonExpression (int role, hash< DataProviderInfo > info, string key, auto value)
| Returns an equality comparison expression. 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< DataProviderMessageInfo > | getEventInfo (string event_id)
| Returns the description of an observable event, if any. More...
hash< string, hash< DataProviderMessageInfo > > | getEventTypes ()
| Returns a hash of all supported event types. More...
hash< DataProviderInfo > | getInfo ()
| Returns data provider info.
hash< auto > | getInfoAsData (*bool with_type_info)
| Returns static provider information as data; no objects are returned. More...
*hash< string, hash< MapperRuntimeKeyInfo > > | getMapperRuntimeKeys ()
| Returns custom data mapper runtime keys. More...
hash< DataProviderMessageInfo > | getMessageInfo (string message_id)
| Returns the description of an outbound message, if any. More...
hash< string, hash< DataProviderMessageInfo > > | getMessageTypes ()
| Returns a hash of all supported outbound messages. More...
AbstractDataProviderRecordIterator | getRecordIterator (*hash< auto > search_options)
| Returns an iterator iterating all records. More...
*AbstractDataProviderType | getRequestType ()
| Returns the description of a successful request message, if any. More...
*AbstractDataProviderType | getResponseType ()
| Returns the description of a response message, if this object represents a response message. More...
object | getSchemaObject ()
| Returns the schema supporting this data provider. More...
*hash< auto > | getSearchExpression (*hash< auto > where_cond, *hash< auto > search_options)
| Returns a search expression for a standard search hash. More...
private hash< DataProviderExpression > | getSimpleArgumentIntern (int role, hash< DataProviderInfo > info, hash< DataProviderExpressionInfo > expinfo, string key, auto value)
| Returns an argument for an expression. More...
hash< DataProviderSummaryInfo > | getSummaryInfo ()
| Return data provider summary info.
AbstractDataProviderRecordIterator | requestSearchRecords (auto req, *hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options according to an API request. More...
AbstractDataProviderRecordIterator | requestSearchRecords (auto req, *hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options according to an API request. More...
bool | requiresTransactionManagement ()
| Returns True if the data provider supports transaction management. More...
| rollback ()
| Rolls back data written to the data provider. More...
*hash< auto > | searchFirstRecord (hash< auto > where_cond, *hash< auto > search_options)
| Returns the first record matching the search options. More...
*hash< auto > | searchFirstRecord (hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Returns the first record matching the search options. More...
AbstractDataProviderRecordIterator | searchRecords (*hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options. More...
AbstractDataProviderRecordIterator | searchRecords (*hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options. More...
AbstractDataProviderBulkRecordInterface | searchRecordsBulk (int block_size=1000, *hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options. More...
AbstractDataProviderBulkRecordInterface | searchRecordsBulk (int block_size=1000, *hash< auto > where_cond, *hash< auto > search_options)
| Returns an iterator for zero or more records matching the search options. More...
*hash< auto > | searchSingleRecord (hash< auto > where_cond, *hash< auto > search_options)
| Returns a single record matching the search options. More...
*hash< auto > | searchSingleRecord (hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Returns a single record matching the search options. More...
| sendMessage (string message_id, auto msg, *hash< auto > send_message_options)
| Sends a message from message-capable data providers. More...
| setLogger (Logger logger)
| Sets or replaces the logger.
| updateField (string name, AbstractDataField field, *hash< auto > field_update_options)
| Updates an existing field. More...
int | updateRecords (hash< auto > set, *hash< auto > where_cond, *hash< auto > search_options)
| Updates zero or more records matching the search options. More...
int | updateRecords (hash< auto > set, *hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Updates zero or more records matching the search options. More...
bool | updateSingleRecord (hash< auto > set, hash< auto > where_cond, *hash< auto > search_options)
| Updates a single record matching the search options. More...
bool | updateSingleRecord (hash< auto > set, hash< DataProviderExpression > where_cond, *hash< auto > search_options)
| Updates a single record matching the search options. More...
string | upsertRecord (hash< auto > rec, *hash< auto > upsert_options)
| Upserts the given record in the data provider. More...

## Static Public Member Functions

static auto | evalGenericExpressionValue (hash< auto > rec, auto val)
| Evaluates the given expression with the generic internal implementation and returns the result. More...
static private hash< DataProviderExpressionInfo > | getExpression (int role, string exp, *hash< string, hash< DataProviderExpressionInfo > > expmap)
| Returns an expression definition for an expression code or throws an exception. More...
static bool | setDynamicValueCallbacks ()
| Ensures that no callbacks can be set for dynamic URI resolution. More...

## Public Attributes

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

## Protected Attributes

const | GenericRecordSearchOptions
| Generic record search options; see details below. More...
*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

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

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

inline

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

Parameters

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

Returns
  the new child data provider

Exceptions

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

Since
  DataProvider 2.0

## createRecord()

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

Creates the given record in the data provider.

Parameters

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

Returns
  the data written to the data provider

Exceptions

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

## deleteChildProvider()

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

Deletes a child data provider.

Parameters

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

Exceptions

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

Since
  DataProvider 2.0

## deleteField()

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

Deletes an existing field.

Parameters

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

Exceptions

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

Since
  DataProvider 2.0

## deleteRecords() [1/2]

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

Deletes zero or more records.

Parameters

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

Returns
  the number of records deleted

Exceptions

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

## deleteRecords() [2/2]

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

Deletes zero or more records.

Parameters

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

Returns
  the number of records deleted

Exceptions

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

Since
  DataProvider 2.3

## doRequest()

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

Makes a request and returns the response.

Parameters

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

Returns
  the response to the request

Exceptions

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

## evalGenericExpressionValue()

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

static

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

Since
  DataProvider 2.3

## getBulkInserter()

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

Returns a bulk insert operation object for the data provider.

Returns
  a bulk insert operation object for the data provider

Exceptions

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

## getBulkRecordInterface()

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

inline

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

Parameters

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

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

Exceptions

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

## getBulkUpserter()

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

Returns a bulk upsert operation object for the data provider.

Returns
  a bulk upsert operation object for the data provider

Exceptions

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

## getChildProvider()

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

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

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

Exceptions

  INVALID-CHILD-PROVIDER | unknown child provider

See also
  getChildProviderEx()

## getChildProviderEx()

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

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

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

Exceptions

  INVALID-CHILD-PROVIDER | unknown child provider

See also
  getChildProvider()

## getChildProviderNames()

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

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

Returns
  a list of child data provider names, if any

## getChildProviderPath()

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

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

throws an exception with unknown path elements

Parameters

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

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

Exceptions

  INVALID-CHILD-PROVIDER | unknown child provider

## getChildProviderSummaryInfo()

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

Return data provider summary info.

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

## getEqualityComparisonExpression()

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

inline

Returns an equality comparison expression.

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

Since
  DataProvider 2.3

## getErrorResponseType()

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

Returns the type for the given error code.

Parameters

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

Returns
  the type for the given error code

Exceptions

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

## getErrorResponseTypes()

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

Returns a hash of error responses, if any.

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

Exceptions

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

## getEventInfo()

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

Returns the description of an observable event, if any.

Parameters

  event_id | the event ID of the event

Returns
  the observable event type for this provider

Exceptions

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

Since
  DataProvider 2.5

## getEventTypes()

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

Returns a hash of all supported event types.

Returns
  a hash of all supported event types

Exceptions

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

Since
  DataProvider 2.5

## getExpression()

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

inline static

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

Since
  DataProvider 2.3

## getInfoAsData()

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

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

Parameters

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

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

## getMapperRuntimeKeys()

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

Returns custom data mapper runtime keys.

Returns
  custom data mapper runtime keys

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

## getMessageInfo()

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

Returns the description of an outbound message, if any.

Parameters

  message_id | the ID of the message

Returns
  the message type for this provider

Exceptions

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

Since
  DataProvider 2.5

## getMessageTypes()

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

Returns a hash of all supported outbound messages.

Returns
  a hash of all supported outbound messages

Exceptions

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

Since
  DataProvider 2.5

## getRecordIterator()

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

Returns an iterator iterating all records.

Parameters

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

Exceptions

  INVALID-OPERATION | the data provider does not support reading

## getRequestType()

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

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

Returns
  the request type for this provider

Exceptions

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

## getResponseType()

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

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

Returns
  the response type for this response message

Exceptions

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

## getSchemaObject()

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

Returns the schema supporting this data provider.

Returns
  the schema supporting this data provider

Exceptions

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

Since
  DataProvider 2.2

## getSearchExpression()

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

Returns a search expression for a standard search hash.

Parameters

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

Returns
  a search expression corresponding to where_cond

Since
  DataProvider 2.3

## getSimpleArgumentIntern()

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

inline

Returns an argument for an expression.

Since
  DataProvider 2.3

## requestSearchRecords() [1/2]

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

inline

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

inline

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

inline

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

inline

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

inline

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

Parameters

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

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

Exceptions

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

## searchSingleRecord() [1/2]

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

Returns a single record matching the search options.

Parameters

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

Exceptions

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

## searchSingleRecord() [2/2]

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

Returns a single record matching the search options.

Parameters

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

Exceptions

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

Since
  DataProvider 2.3

## sendMessage()

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

Sends a message from message-capable data providers.

Parameters

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

Exceptions

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

Since
  DataProvider 2.5

## setDynamicValueCallbacks()

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

static

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

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

Note
  after this call, callbacks cannot be changed

## updateField()

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

Updates an existing field.

Parameters

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

Exceptions

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

Since
  DataProvider 2.0

## updateRecords() [1/2]

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

Updates zero or more records matching the search options.

Parameters

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

Returns
  the number of records updated

Exceptions

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

## updateRecords() [2/2]

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

Updates zero or more records matching the search options.

Parameters

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

Returns
  the number of records updated

Exceptions

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

Since
  DataProvider 2.3

## updateSingleRecord() [1/2]

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

Updates a single record matching the search options.

Parameters

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

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

Exceptions

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

## updateSingleRecord() [2/2]

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

Updates a single record matching the search options.

Parameters

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

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

Exceptions

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

Since
  DataProvider 2.3

## upsertRecord()

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

Upserts the given record in the data provider.

Parameters

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

Returns
  see DB Provider Upsert Result Codes for possible values

Exceptions

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

## Member Data Documentation

## GenericExpressions

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

Generic search operator expressions.

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

Since
  DataProvider 2.3

## GenericRecordSearchOptions

const DataProvider::AbstractDataProvider::GenericRecordSearchOptions

protected

Initial value:
= {
"columns": <DataProviderOptionInfo>{
"type": AbstractDataProviderTypeMap."any",
"desc": "allows a subset of fields to be output in searches",
},
"limit": <DataProviderOptionInfo>{
"type": AbstractDataProviderType::get(IntType),
"desc": "the maximum number of records to return",
},
"offset": <DataProviderOptionInfo>{
"type": AbstractDataProviderType::get(IntType),
"desc": "the offset number in records to return",
},
}
DataProvider::AbstractDataProviderType::get
static AbstractDataProviderType get(Type type, *hash< auto > options, *hash< auto > tags)
Returns an appropriate object for the given type.
DataProvider::AbstractDataProviderTypeMap
const AbstractDataProviderTypeMap
Maps Qore type name constant values to AbstractDataProviderType values.
Definition: AbstractDataProviderType.qc.dox.h:121
DataProvider::DataProviderOptionInfo
Data provider option info.
Definition: AbstractDataProvider.qc.dox.h:58

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