Introduction to the Qorus Client Library

The Qorus Client Library is designed to facilitate communication with Qorus servers and the manipulation of Qorus data without the use of the server. In addition, services are provided to parse the options and dbparams file, and to acquire Datasources based on named datasource in the dbparams file.

See also: Qorus Common API for a definition of API definitions common to all Qorus user code (workflows and services) as well as the client library.

To use the core client library (without HttpServer code and HTTP handlers), you script can require the QorusClientCore module as follows:

%requires QorusClientCore

This will ensure all client definitions are available to your script. The QorusClientCode module requires/loads the following additional modules:

To use the full Qorus client library (including HttpServer code and HTTP handlers), your script can include the backwards-compatible client library include file qorus-client.ql as follows:

%include qorus-client.ql

In this case, the following modules are loaded directly and are available in scripts without additional explicit module loading:

Note: The backwards-compatible Qorus client library include file is safe to use in scripts with parse options such as %require-types, %require-our, %new-style, etc.

Initializing the Client Library

The first step in using the client library is to initialize it with a call to OMQ::QorusClient::init() (or OMQ::QorusClient::init2()):

# Qorus client module
%requires QorusClientCore
 
# requires all variables to be declared before use (recommended)
%require-our
# requires types to be declared
%require-types
%exec-class client
class client {
    constructor() {
        QorusClient::init();
    }
}

Using Datasources

Database driver modules will be loaded on-demand when Datasource or DatasourcePool objects are acquired; if you want to use constants, functions, or other classes provided by the database modules, then load them explicitly with a %requires directive, as follows:

%requires oracle

Use the $omqclient object to acquire Datasource and DatasourcePool objects (after the client library is initialized) as follows:

my Datasource $ds = $omqclient.getDatasource("app2")

my DatasourcePool $dsp = $omqclient.getDatasourcePool("app2")

Communicating with Qorus Servers

Communicating with Qorus Servers with the REST API

Communication with the Qorus server using the REST API is performed through the global variable $qrest (see OMQ::QorusSystemRestHelperBase for the API reference for this object).

This object can then be used to make REST calls to the Qorus server's REST API as in the following example:

# Qorus client module
%requires QorusClientCore
# requires all variables to be declared before use (recommended)
%require-our
# requires types to be declared
%require-types
%exec-class client
class client {
    constructor() {
        QorusClient::init();
        my hash $info = $qrest.get("system");
        printf("Qorus %s %s sessiond %s\n", $info."omq-version", $info."instance-key", $info."session-id");
    }
}

Communicating with Qorus Servers with the REST API

RPC communication with the Qorus server is performed through the global variable $omqapi (see OMQ::QorusSystemAPIHelperBase for the method reference for the $omqapi object).

The use of the OMQ::QorusSystemAPIHelperBase::memberGate() and OMQ::QorusSystemAPIHelperBase::methodGate() methods makes it very easy to call server methods form the client; these methods automatically and transparently redirect unknown method and member access to the local class as server calls to the server and return the server's response.

Consider the following example:

# Qorus client module
%requires QorusClientCore
 
# requires all variables to be declared before use (recommended)
%require-our
# requires types to be declared
%require-types
%exec-class client
class client {
    constructor() {
        QorusClient::init();
        my hash $info = $omqapi."get-status";
        printf("Qorus %s %s sessiond %s\n", $info."omq-version", $info."instance-key", $info."session-id");
    }
}

This is all it takes to make an API call once the client library has been initialized with OMQ::QorusClient::init();

Use the $omqservice variable to easily call service methods. Internally, this object uses $omqapi to perform the communication with the server.

For example (assuming the client library has been initialized as in the previous examples):

my hash $opt = $omqservice.system.prop.get("omq");

The above example will return the contents of the "omq" system property domain as a hash (it's safe to declare $opt as a hash because the "omq" domain will always exist, therefore this command will always return a value).

Note that the Qorus server client programs are delivered in source form and can be used as examples of how to communicate with the server; see the source for:

The above programs show how to use the client API with command-line processing, error handling, etc.

UNIX Socket Support in URLs

URLs with UNIX sockets are generally supported in Qore with the following syntax:

scheme://socket=<url_encoded_path>/path

<url_encoded_path> is a path with URL-encoding as performed by encode_url(); for example, given the following URL:

"http://socket=%2ftmp%socket-dir%2fsocket-file-1/url/path"

This URL allows a filesystem path to be used in the host portion of the URL and for the URL to include a URL path as well.

Qorus Integration Engine