Qorus Integration Engine® Enterprise Edition 7.0.0_prod
Loading...
Searching...
No Matches
OMQ::MapperApi::MapperApi Class Reference

Mapper API class. More...

Static Public Member Methods

static *hash< auto > getUserContextInfo ()
 returns a hash for the current user context
 
static auto getGlobalConfigItemValue (string item, *hash< auto > local_context, bool expand_complex_values=True)
 returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item
 
static auto getGlobalConfigItemValueWithDefault (string item, auto default_value, *hash< auto > local_context, bool expand_complex_values=True)
 returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item
 
static hash< auto > getSystemInfo ()
 returns a hash of system info
 
static auto getValueMap (string mapname, string key)
 Gets a lookup value from the value map by a key; the value map must be registered to the current interface.
 
static auto expandTemplatedValue (auto value, *hash< auto > local_context, bool expand_complex_values=True)
 expands all variables in a templated string
 
static hash< auto > propGet ()
 returns a hash of all system properties in all domains
 
static *hash< auto > propGet (string domain)
 returns a hash of all key-value pairs in the given domain or NOTHING if the system property domain does not exist
 
static auto propGet (string domain, string key)
 returns the value of the given system property key in the given domain or NOTHING if the system property does not exist
 
static SqlUtil::AbstractTable getSqlTable (string datasource, string table_name, bool register_dependency=True)
 get a cached table object (suitable for DML) if present, otherwise it creates one from scratch
 
static SqlUtil::AbstractTable getSqlTable (AbstractDatasource datasource, string table_name, bool register_dependency=True)
 get a cached table object (suitable for DML) if present, otherwise it creates one from scratch
 
static logFatal (softstring msg,...)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 
static logError (softstring msg,...)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 
static logWarn (softstring msg,...)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 
static logInfo (softstring msg,...)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 
static logDebug (softstring msg,...)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 
static logTrace (softstring msg,...)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 
static logArgsFatal (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 
static logWithLevel (int level, string msg,...)
 Writes to the current interface log file with the given log level.
 
static logWithLevelArgs (int level, string msg, *softlist< auto > args)
 Writes to the current interface log file with the given log level.
 
static logArgsError (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 
static logArgsWarn (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 
static logArgsInfo (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 
static logArgsDebug (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 
static logArgsTrace (softstring msg, *softlist< auto > args)
 Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.
 

Detailed Description

Mapper API class.

Since
Qorus 4.1

Member Function Documentation

◆ expandTemplatedValue()

static auto OMQ::MapperApi::MapperApi::expandTemplatedValue ( auto  value,
*hash< auto >  local_context,
bool  expand_complex_values = True 
)
static

expands all variables in a templated string

Parameters
valuetemplated string to be expanded; see Config Item / Building Block Template Substitution Strings for more information on this parameter
local_contextlocal context supplied by the caller (plus user context info is added - see MapperApi::getUserContextInfo() method)
expand_complex_valuesif True then lists and hashes will have their string values expanded recursively
Returns
the value of the string as substituted with all variables expanded recursively until there are no more expansions to perform (or the derived value is not a string)
Exceptions
LIST-VALUE-ERRORcannot parse list value expression
REST-EXPRESSION-ERRORcannot parse REST expression and argument
UNSUPPORTED-CONTEXT-ERRORif an unknown context variable is specified to be expanded
FORMAT-ERRORif the templated string doesn't have correct format (e.g. unescaped dollar sign that does not represent a variable)
SENSITIVE-DATA-FORMAT-ERRORif the "$sensitive:<skey>.<svalue>.field-ref..." value or "$sensitive-alias:<alias>.field-ref..." template string does not have the required format
Since
  • Qorus 4.1.1 added the expand_complex_values argument
See also
Config Item / Building Block Template Substitution Strings

◆ getGlobalConfigItemValue()

static auto OMQ::MapperApi::MapperApi::getGlobalConfigItemValue ( string  item,
*hash< auto >  local_context,
bool  expand_complex_values = True 
)
static

returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item

Parameters
itemthe name of the configuration item to retrieve the value
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see MapperApi::getUserContextInfo() method)
expand_complex_valuesif True then lists and hashes will have their string values expanded recursively
Returns
the value of the given configuration item on global level
Exceptions
CONFIG-ITEM-ERRORthrown if the configuration item is not valid
Note
the value is always substituted with UserApi::expandTemplatedValue(); make sure and escape any "$" characters with a backslash ("\") to avoid template substitution
Since
  • Qorus 4.1.1 added the expand_complex_values argument
See also
getGlobalConfigItemValueWithDefault()

◆ getGlobalConfigItemValueWithDefault()

static auto OMQ::MapperApi::MapperApi::getGlobalConfigItemValueWithDefault ( string  item,
auto  default_value,
*hash< auto >  local_context,
bool  expand_complex_values = True 
)
static

returns the value of the given configuration item on global level; throws an exception if there is no value on global level for the configuration item

Parameters
itemthe name of the configuration item to retrieve the value
default_valuethe value to be returned if the value is not set
local_contextthe caller can supply its "local" context for template variables (plus user context info is added - see MapperApi::getUserContextInfo() method)
expand_complex_valuesif True then lists and hashes will have their string values expanded recursively
Returns
the value of the given global configuration item or default_value, if no value is set at the global level for the given configuration item
Note
Since
  • Qorus 4.1.1 added the expand_complex_values argument
See also
getGlobalConfigItemValue()

◆ getSqlTable() [1/2]

static SqlUtil::AbstractTable OMQ::MapperApi::MapperApi::getSqlTable ( AbstractDatasource  datasource,
string  table_name,
bool  register_dependency = True 
)
static

get a cached table object (suitable for DML) if present, otherwise it creates one from scratch

Parameters
datasourcea DatasourcePool object for a Qorus datasource; note that if the Qore::SQL::DatasourcePool object cannot be matched back to a known Qorus datasource, an INVALID-DATASOURCE exception will be thrown
table_namethe name of the table to be acquired; the handling of this parameter is identical to that in SqlUtil::Table::constructor(); names are converted to lower-case before performing the lookup and storage in the cache to ensure that the cache is based on case-insensitive lookups
register_dependencyif True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again
Returns
an SqlUtil::AbstractTable object corresponding to the parameters
Exceptions
INVALID-DATASOURCEthis exception is thrown if the datasource argument cannot be matched to a known Qorus datasource
Note
  • INVALID-DATASOURCE exceptions can be thrown with a valid Qorus datasource if the given datasource has been reset since it was acquired
  • other exceptions can be thrown when acquiring the table, for example if the given table is not accessible or if there are technical errors communicating with the database server, etc
  • you need to call clear_sql_table_cache() any time the table structure has changed
Example:
SqlUtil::AbstractTable t = MapperApi::getSqlTable(datasource_pool, "my_table");
See also
Since
Qorus 7.0

◆ getSqlTable() [2/2]

static SqlUtil::AbstractTable OMQ::MapperApi::MapperApi::getSqlTable ( string  datasource,
string  table_name,
bool  register_dependency = True 
)
static

get a cached table object (suitable for DML) if present, otherwise it creates one from scratch

Example:
SqlUtil::AbstractTable t = MapperApi::getSqlTable("my_datasource", "my_table");
Parameters
datasourcea Qorus datasource name
table_namethe name of the table to be acquired; the handling of this parameter is identical to that in SqlUtil::Table::constructor(); names are converted to lower-case before performing the lookup and storage in the cache to ensure that the cache is based on case-insensitive lookups
register_dependencyif True (the default) then if the connection is monitored as down, the calling interface will be temporarily disabled until the connection is up again
Returns
an SqlUtil::AbstractTable object corresponding to the parameters
Exceptions
INVALID-DATASOURCEthis exception is thrown if the datasource argument cannot be matched to a known datasource
Note
  • other exceptions can be thrown when acquiring the table, for example if the given table is not accessible or if there are technical errors communicating with the database server, etc
  • you need to call clear_sql_table_cache() any time the table structure has changed
See also
Since
Qorus 7.0

◆ getSystemInfo()

static hash< auto > OMQ::MapperApi::MapperApi::getSystemInfo ( )
static

returns a hash of system info

Returns
a hash of system info with the following keys:
  • instance-key: value of the system option by the same name
  • session-id: the session ID for the current Qorus application session
  • omq-version: the version string for the Qorus server
  • omq-version-code: a numeric code of the Qorus server version, where
    major = (x / 10000),
    minor = (x / 100) % 100, = x % 100
    this value is suitable for comparisons (ex: for Qorus 2.6.0, omq-version-code = 20600)
  • qore-version: the version string for the qore build used
  • datamodel-version: the datamodel version required by this version of Qorus
  • omq-schema: the datasource string for the system schema (without the password)
  • omquser-schema: the datasource string for the user schema (without the password)
  • starttime: the date and time when the instance was started
  • hostname: the hostname of the machine where the Qorus server is running
  • pid: the PID of the Qorus server process
  • threads: number of threads currently active
  • schema-properties: a hash of schema properties with the following keys:
  • omq-schema-version
  • omq-schema-compatibility
  • omq-load-schema-compatibility
  • logfile: the path for the system log file

◆ getUserContextInfo()

static *hash< auto > OMQ::MapperApi::MapperApi::getUserContextInfo ( )
static

returns a hash for the current user context

Example:
*hash<auto> h = MapperApi::getUserContextInfo();
Returns
a hash describing the current user context or NOTHING if called outside a workflow, service, or job; hash keys are as follows:
  • when called in a service:
    • "type": "service"
    • "servicetype": the type of service ("user" or "system")
    • "name": the name of the service
    • "version": the version of the service
    • "id": the service id
    • "context_user": the current username context, if any
  • when called in a job:
    • "type": "job"
    • "name": the name of the job
    • "version": the version of the job
    • "id": the job id
    • "job_instanceid": the job_instanceid of the current job instance
    • "context_user": the current username context, if any
  • when called in a workflow:
    • "type": "workflow"
    • "name": the name of the workflow
    • "version": the version of the workflow
    • "id": the workflow id
    • "workflow_instanceid": the workflow_instanceid of the current workflow instance (if available)
    • "stepname": the name of the current step (if available)
    • "stepversion": the version of the current step (if available)
    • "stepid": the id of the current step (if available)
    • "ind": the name of the current step index (if available)
    • "execid": the execution ID of the current workflow execution instance (if available)
    • "context_user": the current username context, if any

◆ getValueMap()

static auto OMQ::MapperApi::MapperApi::getValueMap ( string  mapname,
string  key 
)
static

Gets a lookup value from the value map by a key; the value map must be registered to the current interface.

Parameters
mapnamename of the value map
keya key name
Returns
the value assigned to the key
Exceptions
VALUE-MAP-ERRORthe given value map is unknown or not registered to the current interface

◆ logArgsDebug()

static OMQ::MapperApi::MapperApi::logArgsDebug ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logDebug()
Since
Qorus 7.0

◆ logArgsError()

static OMQ::MapperApi::MapperApi::logArgsError ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logError()
Since
Qorus 7.0

◆ logArgsFatal()

static OMQ::MapperApi::MapperApi::logArgsFatal ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logFatal()
Since
Qorus 7.0

◆ logArgsInfo()

static OMQ::MapperApi::MapperApi::logArgsInfo ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logInfo()
Since
Qorus 7.0

◆ logArgsTrace()

static OMQ::MapperApi::MapperApi::logArgsTrace ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logTrace()
Since
Qorus 7.0

◆ logArgsWarn()

static OMQ::MapperApi::MapperApi::logArgsWarn ( softstring  msg,
*softlist< auto >  args 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
argsthe arguments for the format string msg
See also
UserApi::logWarn()
Since
Qorus 7.0

◆ logDebug()

static OMQ::MapperApi::MapperApi::logDebug ( softstring  msg,
  ... 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logArgsDebug()
Since
Qorus 7.0

◆ logError()

static OMQ::MapperApi::MapperApi::logError ( softstring  msg,
  ... 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logArgsError()
Since
Qorus 7.0

◆ logFatal()

static OMQ::MapperApi::MapperApi::logFatal ( softstring  msg,
  ... 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logArgsFatal()
Since
Qorus 7.0

◆ logInfo()

static OMQ::MapperApi::MapperApi::logInfo ( softstring  msg,
  ... 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logArgsWarn()
Since
Qorus 7.0

◆ logTrace()

static OMQ::MapperApi::MapperApi::logTrace ( softstring  msg,
  ... 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logTrace()
Since
Qorus 7.0

◆ logWarn()

static OMQ::MapperApi::MapperApi::logWarn ( softstring  msg,
  ... 
)
static

Writes the information passed to the workflow, service, job, or system log file depending on the calling context if the interface logger level is equal or lower.

Parameters
msgthe format string for a vsprintf() call with the remaining arguments
See also
UserApi::logArgsWarn()
Since
Qorus 7.0

◆ logWithLevel()

static OMQ::MapperApi::MapperApi::logWithLevel ( int  level,
string  msg,
  ... 
)
static

Writes to the current interface log file with the given log level.

Parameters
levellog levels as defined by Logger::LoggerLevel
msgthe format string for the log message, arguments follow
Since
Qorus 7.0

◆ logWithLevelArgs()

static OMQ::MapperApi::MapperApi::logWithLevelArgs ( int  level,
string  msg,
*softlist< auto >  args 
)
static

Writes to the current interface log file with the given log level.

Parameters
levellog levels as defined by Logger::LoggerLevel
msgthe format string for the log message
argsoptional argument to format specifiers in msg
Since
Qorus 7.0

◆ propGet() [1/3]

static hash< auto > OMQ::MapperApi::MapperApi::propGet ( )
static

returns a hash of all system properties in all domains

Example:
hash<auto> h = MapperApi::propGet();
Returns
a hash of all system properties in all domains; the top-level keys are domain keys which have as values hashes with all key-value pairs set in the domain

◆ propGet() [2/3]

static *hash< auto > OMQ::MapperApi::MapperApi::propGet ( string  domain)
static

returns a hash of all key-value pairs in the given domain or NOTHING if the system property domain does not exist

Example:
*hash<auto> h = MapperApi::propGet(domain);
Returns
a hash of all key-value pairs in the given domain or NOTHING if the system property domain does not exist

◆ propGet() [3/3]

static auto OMQ::MapperApi::MapperApi::propGet ( string  domain,
string  key 
)
static

returns the value of the given system property key in the given domain or NOTHING if the system property does not exist

Example:
auto val = MapperApi::propGet(domain, key);
Returns
the value of the given system property key in the given domain

The documentation for this class was generated from the following file: