Qorus Integration Engine®  3.1.1.p9
Client Library API Reference

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 Qorus 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 QorusClientCore 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 Qorus 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:

Datasource ds = omqclient.getDatasource("app2")
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 or DataStream 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();
hash info = qrest.get("system");
printf("Qorus %s %s sessiond %s\n", info."omq-version", info."instance-key", info."session-id");
}
}

To get a REST or DataStream connection to a remote server, the function in the following example can be used.

OMQ::Client::QorusSystemRestHelper rest = get_remote_rest_connection("nodea");

Communicating with Qorus Servers with the RPC 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
# do not use "$" for vars and members, etc
%new-style
# requires types to be declared
%require-types
# use strict argument handling
%strict-args
%exec-class client
class client {
constructor() {
QorusClient::init();
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):

*hash rh = omqservice.system.info.searchReleases(("name": "qorus-user-rel1"));

The above example will return a hash of information about the "qorus-user-rel1" release, if it exists (see info.searchReleases() )

To get an RPC connection to a remote server, the function in the following example can be used.

OMQ::Client::QorusSystemAPIHelper rpc = get_remote_rpc_connection("nodea");

Note that the Qorus 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.

Using User Connections in the Qorus Client Library

User connections are user-defined connections to external sytems or facilities that are delivered as a part of Qorus releases.

Qorus client programs can use the get_user_connection() function to access connections defined in the Qorus system schema.

For example, the following code will retrieve user connection object named "my_connection":

%new-style
%require-types
%strict-args
object o = get_user_connection("my_connection");

The following code will list all user connections:

%new-style
%require-types
%strict-args
QorusClient::init();
OMQ::Client::UserConnection uc(omqclient.getDatasource("omq"));
map printf("%s: %s: %s\n", $1.name, $1.url, $1.desc), uc.getInfo().iterator();
qorus-small.png
Qorus Integration Engine®