OMQ::Client::QorusSystemRestHelper Class Reference

class to call the system REST API from the client library More...

Inheritance diagram for OMQ::Client::QorusSystemRestHelper:

Collaboration diagram for OMQ::Client::QorusSystemRestHelper:

Public Member Methods
	constructor (*hash< auto > opts, *softbool do_not_connect)
	Creates the object with the given options. More...
	constructor (string name, *softbool do_not_connect)
	creates the object from the given remote connection name More...
	constructor (string user, string pwd)
	creates the object pointing to the first local listener for the current instance using the given user and password for connecting More...
	setBasePath (string p)
	sets the base path for REST requests
auto	restDo (string m, string path, auto args, *hash< auto > hdr, *hash< auto > opt, *reference< hash< auto > > info)
	makes the REST response and returns the deserialized body More...
auto	get (*hash< auto > opt, string path, auto args, *hash< auto > hdr, *reference< hash< auto > > info)
	issues an HTTP GET REST request against the server and returns the deserialized response More...
auto	put (*hash< auto > opt, string path, auto args, *hash< auto > hdr, *reference< hash< auto > > info)
	issues an HTTP PUT REST request against the server and returns the deserialized response More...
auto	post (*hash< auto > opt, string path, auto args, *hash< auto > hdr, *reference< hash< auto > > info)
	issues an HTTP POST REST request against the server and returns the deserialized response More...
auto	del (*hash< auto > opt, string path, auto args, *hash< auto > hdr, *reference< hash< auto > > info)
	issues an HTTP DELETE REST request against the server and returns the deserialized response More...
string	getRestErrorMessage (hash< auto > ex, *hash< auto > info, *reference< bool > down)
	returns a user-friendly error message when errors occur with REST messaging More...
bool	outputRestErrorMessage (hash< auto > ex, *hash< auto > info)
	outputs a user-friendly error string when errors occur with REST messaging More...
Public Member Methods inherited from OMQ::QorusSystemRestHelperBase
	constructor (*hash< auto > opts, *softbool do_not_connect)
	Creates the object with the given options. More...
	setSchema ()
	Sets the REST validator to the latest version of the schema for the Qorus API. More...
	setPublicSchema ()
	Sets the REST validator to the latest version of the public schema for the Qorus API. More...
abstract private	autoSetUrl (*hash< auto > opts)
	sets the URL automatically; must be reimplemented in subclasses
	setURL (string url)
	sets the URL for the object
hash< auto >	restDoWithInfo (string m, string path, auto args, *hash< auto > hdr, *hash< auto > opt)
	executes the remote REST call and returns the response More...
abstract auto	restDo (string m, string path, auto args, *hash< auto > hdr, *hash< auto > opt, *reference< hash< auto > > info)
	executes the remote REST call and returns the response More...
abstract private nothing	warning (string fmt,...)
	issue a warning on the console (for the client) or in the current log file (for the server) More...
auto	get (string path, auto args, *hash< auto > hdr, *reference< hash< auto > > info)
	executes a GET call on the remote REST service and returns the response More...
hash< auto >	getWithInfo (string path, auto args, *hash< auto > hdr)
	executes a GET call on the remote REST service and returns the response More...
auto	put (string path, auto args, *hash< auto > hdr, *reference< hash< auto > > info)
	executes a PUT call on the remote REST service and returns the response More...
hash< auto >	putWithInfo (string path, auto args, *hash< auto > hdr)
	executes a PUT call on the remote REST service and returns the response More...
auto	post (string path, auto args, *hash< auto > hdr, *reference< hash< auto > > info)
	executes a POST call on the remote REST service and returns the response More...
hash< auto >	postWithInfo (string path, auto args, *hash< auto > hdr)
	executes a POST call on the remote REST service and returns the response More...
auto	del (string path, auto args, *hash< auto > hdr, *reference< hash< auto > > info)
	executes a DELETE call on the remote REST service and returns the response More...
hash< auto >	delWithInfo (string path, auto args, *hash< auto > hdr)
	executes a DELETE call on the remote REST service and returns the response More...
hash< auto >	doRequest (string m, string path, auto body, *reference< hash< auto > > info, softbool decode_errors=True, *hash< auto > hdr)
	sends an HTTP request to the REST server and returns the response More...

Private Member Methods
	autoSetUrl (*hash< auto > opts)
	sets the URL automatically More...
	setInternalUrl (string url)
	Sets internal authentication info.
	warning (string fmt,...)
	prints a warning on the console
string	getBody (hash< auto > info)
	get the literal HTTP body from the info hash
	showRestRequest (hash< auto > info, auto args, *hash< auto > opt)
	outpus the REST request
	showRestResponse (hash< auto > info, auto rv, *hash< auto > opt)
	outpus the REST response

Additional Inherited Members
Static Public Member Methods inherited from OMQ::QorusSystemRestHelperBase
static hash< auto >	toConfig (hash< auto > info)
	returns a hash of configuration information for the object
Public Attributes inherited from OMQ::QorusSystemRestHelperBase
const	Defaults
	default values for connection options
hash	conn_opts
	connection params
*string	api_version
	api version
*string	name
	connection name if known

Detailed Description

class to call the system REST API from the client library

Member Function Documentation

autoSetUrl()

OMQ::Client::QorusSystemRestHelper::autoSetUrl ( *hash< auto >  opts )

privatevirtual

sets the URL automatically

This method acquires an authentication token automatically that provides internal system access to Qorus APIs and data if no other explicit authentication information is available

Implements OMQ::QorusSystemRestHelperBase.

constructor() [1/3]

OMQ::Client::QorusSystemRestHelper::constructor	(	*hash< auto >	opts,
		*softbool	do_not_connect
	)

Creates the object with the given options.

A connection is automatically made unless the do_not_connect argument is False

Parameters

opts	options as follows: api_version: the REST API version (defaults to the latest version) connect_timeout: the connect timeout value in milliseconds timeout: the socket I/O timeout value in milliseconds url: the target URL
do_not_connect	if True, then the object will be created in an unconnected state

Since

Qorus 3.1.1 added the api_version option

constructor() [2/3]

OMQ::Client::QorusSystemRestHelper::constructor	(	string	name,
		*softbool	do_not_connect
	)

creates the object from the given remote connection name

A connection is automatically made unless the do_not_connect argument is False

Parameters

name	the remote connection name to use for the connection
do_not_connect	if True, then the object will be created in an unconnected state

constructor() [3/3]

OMQ::Client::QorusSystemRestHelper::constructor	(	string	user,
		string	pwd
	)

creates the object pointing to the first local listener for the current instance using the given user and password for connecting

Parameters

user	the username for the connection
pwd	the password for the connection

Since

Qorus 5.0 added this to the client version of this class

del()

auto OMQ::Client::QorusSystemRestHelper::del	(	*hash< auto >	opt,
		string	path,
		auto	args,
		*hash< auto >	hdr,
		*reference< hash< auto > >	info
	)

issues an HTTP DELETE REST request against the server and returns the deserialized response

Parameters

opt	output options: lit: if True, outputs the literal response reformat: if True, outputs a reformatted response with verbose formatting (easier to read complex data structures)
path	the URI path for the request
args	any arguments to the REST request
hdr	a hash of optional HTTP header info to add to the request
info	an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys: headers: a hash of outgoing HTTP request headers request-uri: the request URI string sent (ex: "GET /services/async/38.0/job HTTP/1.1") body-content-type: the outgoing message body Mime Content-Type value response-headers: a hash of incoming HTTP headers in the response chunked: set to True if the response was received with chunked transfer encoding response-code: the HTTP response code response-body: the raw message body in the response (after any content decoding) response-serialization: the type of message serialization in the response; see RestClient::RestClient::DataSerializationOptions for possible values request-body: the raw message body in the request (before any content encoding) request-serialization: the type of message serialization in the request; see RestClient::RestClient::DataSerializationOptions for possible values

Returns

the deserialized response body

Since

Qorus 3.1.0.p11 added the info argument

get()

auto OMQ::Client::QorusSystemRestHelper::get	(	*hash< auto >	opt,
		string	path,
		auto	args,
		*hash< auto >	hdr,
		*reference< hash< auto > >	info
	)

issues an HTTP GET REST request against the server and returns the deserialized response

Parameters

opt	output options: lit: if True, outputs the literal response reformat: if True, outputs a reformatted response with verbose formatting (easier to read complex data structures)
path	the URI path for the request
args	any arguments to the REST request
hdr	a hash of optional HTTP header info to add to the request
info	an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys: headers: a hash of outgoing HTTP request headers request-uri: the request URI string sent (ex: "GET /services/async/38.0/job HTTP/1.1") body-content-type: the outgoing message body Mime Content-Type value response-headers: a hash of incoming HTTP headers in the response chunked: set to True if the response was received with chunked transfer encoding response-code: the HTTP response code response-body: the raw message body in the response (after any content decoding) response-serialization: the type of message serialization in the response; see RestClient::RestClient::DataSerializationOptions for possible values request-body: the raw message body in the request (before any content encoding) request-serialization: the type of message serialization in the request; see RestClient::RestClient::DataSerializationOptions for possible values

Returns

the deserialized response body

Since

Qorus 3.1.0.p11 added the info argument

getRestErrorMessage()

string OMQ::Client::QorusSystemRestHelper::getRestErrorMessage	(	hash< auto >	ex,
		*hash< auto >	info,
		*reference< bool >	down
	)

returns a user-friendly error message when errors occur with REST messaging

Parameters

ex	an exception hash
info	an output hash from a REST call

Returns

a user-friendly error string corresponding to the REST error

Since

Qorus 3.1.0.p11

outputRestErrorMessage()

bool OMQ::Client::QorusSystemRestHelper::outputRestErrorMessage	(	hash< auto >	ex,
		*hash< auto >	info
	)

outputs a user-friendly error string when errors occur with REST messaging

Parameters

ex	an exception hash
info	an output hash from a REST call

Returns

True if the system is down, False if up

Since

• Qorus 3.1.0.p11
• Qorus 6.0 added a return value

post()

auto OMQ::Client::QorusSystemRestHelper::post	(	*hash< auto >	opt,
		string	path,
		auto	args,
		*hash< auto >	hdr,
		*reference< hash< auto > >	info
	)

issues an HTTP POST REST request against the server and returns the deserialized response

Parameters

opt	output options: lit: if True, outputs the literal response reformat: if True, outputs a reformatted response with verbose formatting (easier to read complex data structures)
path	the URI path for the request
args	any arguments to the REST request
hdr	a hash of optional HTTP header info to add to the request
info	an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys: headers: a hash of outgoing HTTP request headers request-uri: the request URI string sent (ex: "GET /services/async/38.0/job HTTP/1.1") body-content-type: the outgoing message body Mime Content-Type value response-headers: a hash of incoming HTTP headers in the response chunked: set to True if the response was received with chunked transfer encoding response-code: the HTTP response code response-body: the raw message body in the response (after any content decoding) response-serialization: the type of message serialization in the response; see RestClient::RestClient::DataSerializationOptions for possible values request-body: the raw message body in the request (before any content encoding) request-serialization: the type of message serialization in the request; see RestClient::RestClient::DataSerializationOptions for possible values

Returns

the deserialized response body

Since

Qorus 3.1.0.p11 added the info argument

put()

auto OMQ::Client::QorusSystemRestHelper::put	(	*hash< auto >	opt,
		string	path,
		auto	args,
		*hash< auto >	hdr,
		*reference< hash< auto > >	info
	)

issues an HTTP PUT REST request against the server and returns the deserialized response

Parameters

opt	output options: lit: if True, outputs the literal response reformat: if True, outputs a reformatted response with verbose formatting (easier to read complex data structures)
path	the URI path for the request
args	any arguments to the REST request
hdr	a hash of optional HTTP header info to add to the request
info	an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys: headers: a hash of outgoing HTTP request headers request-uri: the request URI string sent (ex: "GET /services/async/38.0/job HTTP/1.1") body-content-type: the outgoing message body Mime Content-Type value response-headers: a hash of incoming HTTP headers in the response chunked: set to True if the response was received with chunked transfer encoding response-code: the HTTP response code response-body: the raw message body in the response (after any content decoding) response-serialization: the type of message serialization in the response; see RestClient::RestClient::DataSerializationOptions for possible values request-body: the raw message body in the request (before any content encoding) request-serialization: the type of message serialization in the request; see RestClient::RestClient::DataSerializationOptions for possible values

Returns

the deserialized response body

Since

Qorus 3.1.0.p11 added the info argument

restDo()

auto OMQ::Client::QorusSystemRestHelper::restDo ( string  m, string  path, auto  args, *hash< auto >  hdr, *hash< auto >  opt, *reference< hash< auto > >  info  )

virtual

makes the REST response and returns the deserialized body

Parameters

m	the HTTP method for the request (ex: "GET")
path	the URI path for the request
args	any arguments to the REST request
hdr	a hash of optional HTTP header info to add to the request
opt	output options: lit: if True, outputs the literal response reformat: if True, outputs a reformatted response with verbose formatting (easier to read complex data structures)
info	an optional reference to a hash that will be used as an output variable giving a hash of request headers and other information about the HTTP request; if present the hash will contain the following keys: headers: a hash of outgoing HTTP request headers request-uri: the request URI string sent (ex: "GET /services/async/38.0/job HTTP/1.1") body-content-type: the outgoing message body Mime Content-Type value response-headers: a hash of incoming HTTP headers in the response chunked: set to True if the response was received with chunked transfer encoding response-code: the HTTP response code response-body: the raw message body in the response (after any content decoding) response-serialization: the type of message serialization in the response; see RestClient::RestClient::DataSerializationOptions for possible values request-body: the raw message body in the request (before any content encoding) request-serialization: the type of message serialization in the request; see RestClient::RestClient::DataSerializationOptions for possible values

Returns

the deserialized response body

Since

Qorus 3.1.0.p11 added the info argument

Implements OMQ::QorusSystemRestHelperBase.

---

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

• QorusClientBase.qm