class for REST HTTP connections; returns RestClient::RestClient objects More...

#include <RestClient.qm.dox.h>

Inheritance diagram for RestClient::RestConnection:

Public Member Methods
	constructor (string name, string description, string url, hash< auto > attributes={}, hash< auto > options={})
	creates the RestConnection connection object More...

DataProvider::AbstractDataProvider	getDataProvider ()
	returns a data provider object for this connection More...

*hash< auto >	getDefaultOptions ()
	returns default options

hash< auto >	getOptions ()
	gets options More...

object	getPollImpl ()
	Returns an unconnected object for a non-blocking poll operation. More...

string	getType ()
	returns `"rest"`

bool	hasDataProvider ()
	returns True, as this connection always returns a data provider with the getDataProvider() method More...

Qore::AbstractPollOperation	startPollConnect ()
	Called to start a non-blocking polling ping operation on the remote REST server. More...

Static Public Member Methods
static hash< auto >	processOptions (*hash< auto > opts)
	processes options for the constructor More...

Public Attributes
const	ConnectionScheme
	Connection entry info.

const	DefaultOptions = ...
	default options

const	OptionList = keys ConnectionScheme.options
	object connection option list

const	Options = map {$1: True}
	object connection options

hash< auto >	real_opts
	real options used when creating an object

Private Member Methods
hash< ConnectionSchemeInfo >	getConnectionSchemeInfoImpl ()
	Returns the ConnectionSchemeInfo hash for this object.

RestClient	getImpl (bool connect=True, *hash< auto > rtopts)
	returns a RestClient object More...

	pingImpl ()
	performs the internal ping More...

	setChildCapabilities ()
	Sets child data provider capabilities.

Detailed Description

class for REST HTTP connections; returns RestClient::RestClient objects

supports the following options:

"connect_timeout": connection timeout to use in milliseconds
"content_encoding": this sets the send encoding (if the "send_encoding" option is not set) and the requested response encoding; for possible values, see EncodingSupport
"data": see RestClient::RestClient::DataSerializationOptions for possible values when used with the null REST schema validator; the default is "auto"
"error_passthru": if True then HTTP status codes indicating errors will not cause a REST-RESPONSE-ERROR exception to be raised, rather such responses will be passed through to the caller like any other response
"headers": an optional hash of headers to send with every request, these can also be overridden in request method calls; also a string giving headers can be given in the format: header1=value, header2=value; the value will be parsed with parse_to_qore_value()
"http_version": HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects": maximum redirects to support
"proxy": proxy URL to use
"redirect_passthru": if True then redirect responses will be passed to the caller instead of processed
"send_encoding": a send data encoding option or the value "auto" which means to use automatic encoding; if not present defaults to no content-encoding on sent message bodies
"swagger": the path to a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); conflicts with validator
"swagger_base_path": in case a REST validator is used, the base path in the schema can be overridden with this option (applies to any REST validator; not just Swagger validators)
"timeout": transfer timeout to use in milliseconds
"validator": an AbstractRestSchemaValidator object to validate request and response messages; conflicts with swagger

Note

additionally supports the following runtime option in getImpl():

"validator": an AbstractRestSchemaValidator object for REST message validation (if present, overrides any REST schema validation option provided as a connection option)

See also: RestClient::constructor() for more information on the above options

Since: RestConnection 1.4

Member Function Documentation

◆ constructor()

RestClient::RestConnection::constructor	(	string	name,
		string	description,
		string	url,
		hash< auto >	attributes = `{}`,
		hash< auto >	options = `{}`
	)

creates the RestConnection connection object

Parameters

name	the name of the connection
description	connection description
url	connection URL (potentially with password info)
attributes	various attributes. See below
options	connection options

See AbstractConnection::constructor() for attributes and options reference.

Additional Attributes

error a custom error string

Exceptions

CONNECTION-OPTION-ERROR missing or invalid connection option

◆ getDataProvider()

DataProvider::AbstractDataProvider RestClient::RestConnection::getDataProvider ( )

returns a data provider object for this connection

Returns

a data provider object for this connection; the data provider is:

SwaggerDataProvider: if an appropriate schema is configured
RestClientDataProvider: if there is no schema configured

Exceptions

DATA-PROVIDER-ERROR this object does not support the data provider API

◆ getImpl()

RestClient RestClient::RestConnection::getImpl	(	bool	connect = `True`,
		*hash< auto >	rtopts
	)

privatevirtual

returns a RestClient object

Parameters

connect	if True, then the connection is returned already connected
rtopts	supports the following runtime option in getImpl(): `"validator"`: an AbstractRestSchemaValidator object for REST message validation (if present, overrides any REST schema validation option provided as a connection option)

Returns: a RestClient object

Implements ConnectionProvider::AbstractConnection.

◆ getOptions()

hash< auto > RestClient::RestConnection::getOptions ( )

gets options

Returns

returns a hash with the following supported options:

"connect_timeout": connection timeout to use in milliseconds
"content_encoding": this sets the send encoding (if the "send_encoding" option is not set) and the requested response encoding; for possible values, see EncodingSupport
"data": see RestClient::RestClient::DataSerializationOptions for possible values when used with the null REST schema validator; the default is "auto"
"error_passthru": if True then HTTP status codes indicating errors will not cause a REST-RESPONSE-ERROR exception to be raised, rather such responses will be passed through to the caller like any other response
"headers": an optional hash of headers to send with every request, these can also be overridden in request method calls; also a string giving headers can be given in the format: header1=value, header2=value; the value will be parsed with parse_to_qore_value()
"http_version": HTTP version to use ("1.0" or "1.1", defaults to "1.1")
"max_redirects": maximum redirects to support
"proxy": proxy URL to use
"redirect_passthru": if True then redirect responses will be passed to the caller instead of processed
"send_encoding": a send data encoding option or the value "auto" which means to use automatic encoding; if not present defaults to no content-encoding on sent message bodies
"swagger": the path to a Swagger 2.0 REST schema file for runtime API validation (see the Swagger module); conflicts with validator
"timeout": transfer timeout to use in milliseconds
"validator": an AbstractRestSchemaValidator object to validate request and response messages; conflicts with swagger

See also: RestClient::constructor() for more information on the above options

◆ getPollImpl()

object RestClient::RestConnection::getPollImpl ( )

Returns an unconnected object for a non-blocking poll operation.

Returns: an unconnected object for a non-blocking poll operation

Since: RestClient 1.9.1

◆ hasDataProvider()

bool RestClient::RestConnection::hasDataProvider ( )

returns True, as this connection always returns a data provider with the getDataProvider() method

Returns: True, as this connection always returns a data provider with the getDataProvider() method

See also: getDataProvider()

◆ pingImpl()

RestClient::RestConnection::pingImpl ( )

private

performs the internal ping

By default this creates a new connection only; override in child classes to implement additional ping logic

◆ processOptions()

static hash< auto > RestClient::RestConnection::processOptions ( *hash< auto > opts )

static

processes options for the constructor

In particular it parses any string as a value of the "headers" option to return a hash

◆ startPollConnect()

Qore::AbstractPollOperation RestClient::RestConnection::startPollConnect ( )

Called to start a non-blocking polling ping operation on the remote REST server.

Returns: a socket poll operation object that will allow the connection goal to be reached with polling

See also: supportsPollingApi()

Public Member Methods

Static Public Member Methods

Public Attributes

Private Member Methods