DataProvider::DataProvider Class Reference

Data provider class. More...

#include <DataProvider.qc.dox.h>

Static Public Member Methods
static	addOptions (int options)
	Adds the given global data provider options.
static	checkOptions (int options)
	Checks for valid global data provider options.
static	checkStaticInit ()
	Checks for static initialization.
static	deferStaticInitialization ()
	Defers static initialization until restoreStaticInitialization() is called.
static bool	deregisterShutdownHandler (string key)
	Deregisters a shutdown handler.
static bool	getAutoConfig ()
	Returns the auto config flag.
static *AbstractDataProviderFactory	getFactory (string name)
	Returns the given data provider factory or NOTHING if not present.
static AbstractDataProviderFactory	getFactoryEx (string name)
	Returns the given data provider factory or throws an exception if not present.
static AbstractDataProvider	getFactoryObject (string path, *hash< auto > options)
	Returns a data provider object from the given factory, created with the given constructor options.
static AbstractDataProvider	getFactoryObjectFromExample (string path, data example, *hash< auto > options)
	Returns a data provider object from the given factory, created with the given options and example data.
static AbstractDataProvider	getFactoryObjectFromExample (string path, InputStream example, *hash< auto > options)
	Returns a data provider object from the given factory, created with the given options and example data.
static AbstractDataProvider	getFactoryObjectFromString (string name)
	Returns a data provider object from the given factory string.
static AbstractDataProvider	getFactoryObjectFromStringUseEnv (string name)
	Returns a data provider object from the given factory string using environment variables to find the factory.
static AbstractDataProvider	getFactoryObjectWithTemplate (string path, *hash< auto > template_options, *hash< auto > options)
	Returns a data provider object from the given factory, created with the given constructor options.
static *LoggerInterface	getGlobalLogger ()
	Returns the global data provider logger.
static hash< auto >	getInfoAsData (hash< auto > info0, *bool with_type_info)
	Converts an info hash with objects to a hash with string descriptions instead of the objects.
static int	getOptions ()
	Returns global data provider options.
static list< string >	getPathList (reference< string > path)
	Returns a list of strings in a path separated by "/" characters, normalizes the argument.
static list< string >	getPathList (string path)
	Returns a list of strings in a path separated by "/" characters.
static *AbstractDataProviderType	getType (string path)
	Returns the given data provider type or NOTHING if not present.
static DataProviderTypeCache	getTypeCache ()
	Returns the data provider cache.
static AbstractDataProviderType	getTypeEx (string path)
	Returns the given data provider type or throws an exception if not present.
static DataProviderTypeEntry	getTypeRoot ()
	Returns the root type entry.
static *list< string >	listFactories ()
	Returns a list of registered data provider factories.
static *list< string >	listTypes ()
	Returns a list of registered data provider type paths.
static	loadProvidersFromEnvironment (*LoggerInterface logger)
	Loads data providers from the environment.
static	loadTypesFromEnvironment (*LoggerInterface logger)
	Loads data types from the environment.
static	lockAllTypes ()
	Locks all types.
static	registerFactory (AbstractDataProviderFactory factory)
	Register a new data provider factory.
static	registerKnownFactories ()
	Registers all known data provider factories.
static	registerKnownTypes ()
	Registers all known data provider types.
static	registerShutdownHandler (string key, code handler)
	Registers a handler to run when shutting down data provider services.
static	registerStaticInitializer (code init)
	Registers a static initializer.
static	registerType (string path, AbstractDataProviderType type)
	Register a new data provider type.
static	removeOptions (int options)
	Removes the given global data provider options.
static	restoreStaticInitialization ()
	Restores static initialization deferred by deferStaticInitialization()
static	setAutoConfig ()
	Sets the flag that allows for automatic configuration from environment variables.
static	setGlobalLogger (*LoggerInterface logger)
	Sets or clears the global logger.
static	setOptions (int options)
	Replaces data provider global options with the value provided.
static	shutdown ()
	Shuts down background services related to data providers.
static *AbstractDataProvider	tryLoadProviderForConnectionFromEnv (string name, *string subtype, *LoggerInterface logger)
	Tries to load a data provider from the environment from the connection name.

Public Attributes
const	FactoryMap = ...
	Map of known data provider factory names to modules.
const	FactoryModuleList = keys (map {$1: True}, FactoryMap.iterator())
	List of data provider factory modules.
const	NoApp = "$NO_APP"
	An invalid app name.
const	TypeMap = ...
	Map of known type path prefixes to modules.

Static Private Member Methods
static bool	checkInjection (object obj, hash< string, string > module_map)
	Check if the object is from a module that has been subject to dependency injections.
static	checkRequest ()
	Sets the env_config_locked variable if not already set.
static synchronized	checkStaticInitIntern ()
	Checks for static initialization.
static *object	checkSymbol (hash< SymbolInfo > info, *LoggerInterface logger)
	Returns True if an object of the given type has been loaded.
static	deregisterFactory (string name)
	Deregisters a factory if an exception occurs during the other module's initialization.
static Gate	factory_cache_lock ()
	data provider factory cache lock
static hash< FactoryInfo >	getFactoryInfoFromString (string name)
	Returns a hash of factory information from a string.
static *object	loadFromEnvironment (string func, string type, *hash< SymbolInfo > info, *LoggerInterface logger)
	Loads modules from the QORE_DATA_PROVIDERS environment variable.
static *string	tryGetFactoryModuleName (string name)
	Tries to load a module corresponding to the given factory.
static *string	tryGetModuleName (string name, string func, string type)
	Tries to load a module corresponding to the given factory.
static *string	tryGetTypeModuleName (string name)
	Tries to load a module corresponding to the given factory.
static bool	tryLoad (string module_str, *bool init)
	Try to load the given module.
static *DataProviderTypeEntry	tryLoadTypeFromPath (list< string > type_path)
	Tries to load the given type.
static DataProviderTypeCache	type_cache ()
	data provider data type cache

Static Private Attributes
static bool	allow_env_config = False
	flag to allow automatic configuration from environment variables
static bool	env_config_locked = False
	flag that locks the allow_env_config var
static hash< string, AbstractDataProviderFactory >	factory_cache
	data provider factory cache
static hash< string, string >	factory_module_map
	data provider factory module map
static list< code >	ilist
	Static initializer list.
static list< *list< code > >	ilist_save
	Deferred static initializers.
static *LoggerInterface	logger
	Global logger.
static hash< string, bool >	mod_map
	set of module already loaded
static int	options = 0
	Global options.
static hash< string, code >	smap
	Shutdown handlers; key -> handler.
static hash< string, string >	type_module_map
	data provider type module map

Detailed Description

Data provider class.

Member Function Documentation

addOptions()

static DataProvider::DataProvider::addOptions ( int  options )

static

Adds the given global data provider options.

Parameters

options

a bitfield of global data provider options

Exceptions

INVALID-OPTIONS

Invalid options provided

Since

DataProvider 3.0

checkOptions()

static DataProvider::DataProvider::checkOptions ( int  options )

static

Checks for valid global data provider options.

Parameters

options

a bitfield of global data provider options

Since

DataProvider 3.0

checkStaticInit()

static DataProvider::DataProvider::checkStaticInit ( )

static

Checks for static initialization.

Since

DataProvider 3.0

deferStaticInitialization()

static DataProvider::DataProvider::deferStaticInitialization ( )

static

Defers static initialization until restoreStaticInitialization() is called.

Since

DataProvider 3.0

deregisterShutdownHandler()

static bool DataProvider::DataProvider::deregisterShutdownHandler ( string  key )

static

Deregisters a shutdown handler.

Parameters

key	the key used to register the shutdown handler

Returns

True if the handler was deregistered, False if not (no such key)

Since

DataProvider 3.0

getFactoryEx()

static AbstractDataProviderFactory DataProvider::DataProvider::getFactoryEx ( string  name )

static

Returns the given data provider factory or throws an exception if not present.

Parameters

name	the name of the data provider to retrieve

Returns

the given data provider; an exception is thrown if the data provide is unknown

Exceptions

PROVIDER-ERROR

the given provider is unknown

getFactoryObject()

static AbstractDataProvider DataProvider::DataProvider::getFactoryObject ( string  path, *hash< auto >  options  )

static

Returns a data provider object from the given factory, created with the given constructor options.

Parameters

path	the "/"-separated path to the target data provider; the first element is the factory name
options	factory creation options

Exceptions

PROVIDER-ERROR

the given provider factory or child provider is unknown

getFactoryObjectFromExample() [1/2]

static AbstractDataProvider DataProvider::DataProvider::getFactoryObjectFromExample ( string  path, data  example, *hash< auto >  options  )

static

Returns a data provider object from the given factory, created with the given options and example data.

Parameters

path	the "/"-separated path to the target data provider; the first element is the factory name
example	example data to process
options	factory creation options

Exceptions

PROVIDER-ERROR

the given provider factory or child provider is unknown

Since

DataProvider 2.7.1

getFactoryObjectFromExample() [2/2]

static AbstractDataProvider DataProvider::DataProvider::getFactoryObjectFromExample ( string  path, InputStream  example, *hash< auto >  options  )

static

Returns a data provider object from the given factory, created with the given options and example data.

Parameters

path	the "/"-separated path to the target data provider; the first element is the factory name
example	example data to process
options	factory creation options

Exceptions

PROVIDER-ERROR

the given provider factory or child provider is unknown

Since

DataProvider 2.7.1

getFactoryObjectFromString()

static AbstractDataProvider DataProvider::DataProvider::getFactoryObjectFromString ( string  name )

static

Returns a data provider object from the given factory string.

Factory options are given as string-formatted hash in curly brackets and child data providers are separated by forward slashes

Example:

DbDataProvider db = DataProvider::getFactoryObjectFromString("db{datasource=oracle:user/password@db}/my_table");

Exceptions

PROVIDER-ERROR

the given provider factory or child provider is unknown

getFactoryObjectFromStringUseEnv()

static AbstractDataProvider DataProvider::DataProvider::getFactoryObjectFromStringUseEnv ( string  name )

static

Returns a data provider object from the given factory string using environment variables to find the factory.

Factory options are given as string-formatted hash in curly brackets and child data providers are separated by forward slashes

Example:

DbDataProvider db = DataProvider::getFactoryObjectFromStringUseEnv("db{datasource=oracle:user/password@db}/my_table");

Exceptions

PROVIDER-ERROR

the given provider factory or child provider is unknown

getFactoryObjectWithTemplate()

static AbstractDataProvider DataProvider::DataProvider::getFactoryObjectWithTemplate ( string  path, *hash< auto >  template_options, *hash< auto >  options  )

static

Returns a data provider object from the given factory, created with the given constructor options.

Parameters

path	the "/"-separated path to the target data provider; the first element is the factory name
template_options	options with templated values; only the keys in this hash are relevant, as they indicate options that will be present at a later time when their values can be derived; the values provided in this call are assumed to be in an implementation-dependent templated format and should be ignored
options	factory creation options

Exceptions

PROVIDER-ERROR

the given provider factory or child provider is unknown

Since

DataProvider 2.7.1

getGlobalLogger()

static *LoggerInterface DataProvider::DataProvider::getGlobalLogger ( )

static

Returns the global data provider logger.

Returns

the global data provider logger

Since

DataProvider 3.0

getInfoAsData()

static hash< auto > DataProvider::DataProvider::getInfoAsData ( hash< auto >  info0, *bool  with_type_info  )

static

Converts an info hash with objects to a hash with string descriptions instead of the objects.

Parameters

info0	the raw info with objects describing the types
with_type_info	if True then more type information will be returned in the response

getOptions()

static int DataProvider::DataProvider::getOptions ( )

static

Returns global data provider options.

Returns

global data provider options

Since

DataProvider 3.0

getType()

static *AbstractDataProviderType DataProvider::DataProvider::getType ( string  path )

static

Returns the given data provider type or NOTHING if not present.

Parameters

path	a "/" separated path for the type; trailing path elements can be a path into fields

Returns

the given data provider type; NOTHING is returned if the type cannot be resolved

Note

types are stored based on the path provided which may differ from their type names (which may be generic and therefore not suitable for indexing)

getTypeEx()

static AbstractDataProviderType DataProvider::DataProvider::getTypeEx ( string  path )

static

Returns the given data provider type or throws an exception if not present.

Parameters

path	a "/" separated path for the type; trailing path elements can be a path into fields

Returns

the given data provider type; an exception is thrown if the data provide is unknown

Exceptions

PROVIDER-ERROR

the given data provider type path is unknown

Note

types are stored based on the path provided which may differ from their type names (which may be generic and therefore not suitable for indexing)

listTypes()

static *list< string > DataProvider::DataProvider::listTypes ( )

static

Returns a list of registered data provider type paths.

Note

types are stored based on the path provided which may differ from their type names (which may be generic and therefore not suitable for indexing)

registerFactory()

static DataProvider::DataProvider::registerFactory ( AbstractDataProviderFactory  factory )

static

Register a new data provider factory.

Parameters

factory

the new data provider factory

Exceptions

PROVIDER-ERROR

the given provider has already been registered

registerShutdownHandler()

static DataProvider::DataProvider::registerShutdownHandler ( string  key, code  handler  )

static

Registers a handler to run when shutting down data provider services.

Parameters

key	a unique key for the shutdown handler
handler	the shutdown handler

Since

DataProvider 3.0

registerStaticInitializer()

static DataProvider::DataProvider::registerStaticInitializer ( code  init )

static

Registers a static initializer.

Since

DataProvider 3.0

registerType()

static DataProvider::DataProvider::registerType ( string  path, AbstractDataProviderType  type  )

static

Register a new data provider type.

Parameters

path	a "/" separated path for the type; this is the lookup index
type	the new data provider type

Exceptions

PROVIDER-ERROR

the given provider has already been registered

Note

types are stored based on the path provided which may differ from their type names (which may be generic and therefore not suitable for indexing)

removeOptions()

static DataProvider::DataProvider::removeOptions ( int  options )

static

Removes the given global data provider options.

Parameters

options

a bitfield of global data provider options

Exceptions

INVALID-OPTIONS

Invalid options provided

Since

DataProvider 3.0

restoreStaticInitialization()

static DataProvider::DataProvider::restoreStaticInitialization ( )

static

Restores static initialization deferred by deferStaticInitialization()

Since

DataProvider 3.0

setAutoConfig()

static DataProvider::DataProvider::setAutoConfig ( )

static

Sets the flag that allows for automatic configuration from environment variables.

Must be called before any requests for types or factories are made, or an exception is raised

Exceptions

DATA-PROVIDER-ERROR

cannot call this method after requests for types or factories are made

setGlobalLogger()

static DataProvider::DataProvider::setGlobalLogger ( *LoggerInterface  logger )

static

Sets or clears the global logger.

Parameters

logger

the global data provider logger

Since

DataProvider 3.0

setOptions()

static DataProvider::DataProvider::setOptions ( int  options )

static

Replaces data provider global options with the value provided.

Parameters

options

a bitfield of global data provider options

Exceptions

INVALID-OPTIONS

Invalid options provided

Since

DataProvider 3.0

shutdown()

static DataProvider::DataProvider::shutdown ( )

static

Shuts down background services related to data providers.

Since

DataProvider 3.0

Member Data Documentation

allow_env_config

bool DataProvider::DataProvider::allow_env_config = False

staticprivate

flag to allow automatic configuration from environment variables

must be set before any requests for types or factories are made