Client Library API Reference

Table of Contents

• Introduction to the Qorus Client Library
• Using the Qorus Client from Python
• Using the Qorus Client from Java
• Initializing the Qorus Client Library
• Using Datasources
• Using SQL Tables
• Using Data Providers
• Communicating with Qorus Servers
  • Communicating with Qorus Servers with the REST API
  • Calling Service Methods from Qore
  • UNIX Socket Support in URLs
• Using User Connections in the Qorus Client Library

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 to acquire Datasources based on named datasource in the system database as well as other connections and integration objects.

For the Python-based remote client, allowing users to work with remote Qorus instances over HTTP and WebSocket connections, which can be installed on any platform supporting a recent version of Python 3; see https://github.com/qoretechnologies/qorus-remote.

The Python client can be installed from pip with:

pip install qorus-remote 

Note that this documentation documents the Qorus client library delivered with the Qorus server. The Qorus client library is written in Qore and requires read access to the server configuration files (System Options File, as well as to the network encryption key file and the sensitive data key file, etc).

All Qorus client scripts depend on the client library, such as the following:

• ocmd: Command-Line Interface to the Qorus RPC API
• ostatus: Show System, Workflow, and Service Status
• ojview: Show Job Information
• oprop: System Property Tool
• ostart: Start Workflow Execution Instances
• ostop: Stop Workflow Instances
• oview: Show Workflow Instance, Order Status and Overviews
• qevent: Command-Line Event Monitor
• qrest: Command-Line Interface to the Qorus System REST API
• schema-tool: Schema Manipulation Helper Tool
• user-tool: Offline Role-Based Access Control Tool
• swagger2service: Generate Qorus REST Server Service from a Swagger Schema

See also

• Qorus Client Domain Options for options affecting the Qorus client
• OMQ::QorusClient (static methods related to Qorus client functionality)
• OMQ::QorusClientAPI (the class defining the omqclient object)

Using the Qorus Client from Python

Python integration with Qore is implemented using the qoreloader module, which is the Python module provided in Qore's python module, providing tight integration with both languages, including bi-directional dynamic and transparent imports of code and data between Python and Qore as well as Python and Java with the assistance of the jni module.

The Python qoreloader module is located in $OMQ_DIR/python; this directory must appear in the PYTHONPATH environment variable to be imported by Python.

Python examples in this guide assume that the qoreloader module is available from the PYTHONPATH environment variable.

PYTHONPATH Unix / Linux Example

export PYTHONPATH=$OMQ_DIR/python/qoreloader.so

The qoreloader module will initialize the Qore library when imported and will generate Python classes dynamically from Qore and Java classes with supported import statements; additionally, the qoreloader module will convert data automatically to and from Qore and Java at runtime when Python code calls Qore or Java code and vice-versa.

Python Example:

import qoreloader
import qore.QorusClientBase
from qore.__root__.OMQ.UserApi import UserApi
 
# NOTE: this make a REST call to retrieve the session ID; Qorus must be running
print('Qorus session ID: {}'.format(UserApi.getSessionId()))

See also

• Configure Environment Variables for more information on environment variables used by Qorus
• Importing Qore APIs into Python
• Importing Java APIs Indirectly into Python Through Qore

Using the Qorus Client from Java

Java integration with Qore is implemented through the qore-jni.jar JAR file, which provides a Java compiler based on the standard javax.tools package in the java.compiler module, as well as a a class loader, both supporting dynamic bytecode generation of wrapper classes for Qore and Python declarations and symbols on demand during complation and at runtime.

The qore-jni.jar JAR file will automatically initialize Qore's jni module as well as Qore's python module as needed to introspect Qore and Python definitions, generate Java bytecode dynamically, and import the generated bytecode directly into the requesting Java program.

This allows Java programs to use the full Qorus API set as well as dynamically import Python APIs and modules into Java and use them as if they were Java APIs.

Qorus provides qjavac as a front end to the Qore Java compiler for convenience; qjavac takes the same arguments as the standard javac compiler.

To compile Java code using dynamic imports, make sure and include $OMQ_DIR/jar/qore-jni.jar in the classpath.

Java Compilation Example

qjavac -cp ${OMQ_DIR}/jar/qore-jni.jar MyClass.java

To run Java code that uses dynamic imports, you need to use the same classpath as above, plus Qore's org.qore.jni.QoreURLClassLoader as the system class loader.

Java Execution Example

java -cp ${OMQ_DIR}/jar/qore-jni.jar:. -Djava.system.class.loader=org.qore.jni.QoreURLClassLoader MyClass

See also

• Importing Qore and Python APIs Dynamically in Java
• Writing Tests in Java for Qorus Interfaces
• Using the jni Module From Java

Initializing the Qorus Client Library

Use the QorusClientBase module to ensure that a minimum set of Qorus client APIs are available to your script or program.

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

Python Example:

# the "qoreloader" module is provided by Qorus and provides the bridge between Python <-> Qore and, with Qore's "jni"
# module, between Python <-> Java
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_module
import qoreloader
 
# the "qoreloader" module provides the magic package "qore" which allows us to import Qore APIs and use them as if
# they were Python APIs
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_import_qore
from qore.QorusClientBase import QorusClient
 
# initialize the Qorus client
QorusClient.initFast()

Java Example:

// the magic "qoremod" package will load a Qore module and handles the dynamic bycode generation of wrapper classes
// in Java to enable Qore code to be used as if it were Java code
import qoremod.QorusClientBase.*;
 
class MyClass {
    // static initialization
    static {
        try {
            // we initialize the Qorus client in the class's static initialization block
            QorusClient.initFast();
        } catch (Throwable e) {
            throw new RuntimeException(e);
        }
    }
 
    public static void main(String[] args) throws Throwable {
        // ... code here
    }
}

Qore Example

# Qorus client base module
%requires QorusClientBase
 
# use new style, assume local variables and do not require $ symbols on vars and members, etc
%new-style
# requires all variables to be declared before use (recommended)
%require-our
# requires types to be declared
%require-types
# enable all warnings
%enable-all-warnings
 
%exec-class client
 
class client {
    constructor() {
        QorusClient::initFast();
    }
}

Using Datasources

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

%requires oracle

Use the UserApi::getDatasourceDedicated() method (or UserApi::getDatasourcePool()) to acquire Datasource and DatasourcePool objects.

Python Example:

# the "qoreloader" module is provided by Qorus and provides the bridge between Python <-> Qore and, with Qore's "jni"
# module, between Python <-> Java
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_module
import qoreloader
 
# the "qoreloader" module provides the magic package "qore" which allows us to import Qore APIs and use them as if
# they were Python APIs
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_import_qore
from qore.QorusClientBase import QorusClient
 
# import Qorus's "UserApi" class
from qore.__root__.OMQ.UserApi import UserApi
 
# import Qore's Datasource and DatasourcePool classes
from qore.__root__.Qore.SQL import Datasource, DatasourcePool
 
# initialize the Qorus client
QorusClient.initFast()
 
ds: Datasource = UserApi.getDatasourceDedicated('omquser')
dsp: DatasourcePool = UserApi.getDatasourcePool('omquser')

Java Example:

// the magic "qoremod" package will load a Qore module and handles the dynamic bycode generation of wrapper classes
// in Java to enable Qore code to be used as if it were Java code
import qoremod.QorusClientBase.*;
 
// import Qorus's "UserApi" class
import qoremod.QorusClientBase.OMQ.UserApi.UserApi;
 
// import Qore's Datasource and DatasourcePool classes
import qore.Qore.SQL.Datasource;
import qore.Qore.SQL.DatasourcePool;
 
class MyClass {
    // static initialization
    static {
        try {
            // we initialize the Qorus client in the class's static initialization block
            QorusClient.initFast();
        } catch (Throwable e) {
            throw new RuntimeException(e);
        }
    }
 
    public static void main(String[] args) throws Throwable {
        // get a Datasource object for the "omquser" datasource
        Datasource ds = UserApi.getDatasourceDedicated("omquser");
        // get a DatasourcePool object for the "omquser" datasource
        DatasourcePool dsp = UserApi.getDatasourcePool("omquser");
    }
}

Qore Example

# Qorus client base module
%requires QorusClientBase
 
# use new style, assume local variables and do not require $ symbols on vars and members, etc
%new-style
# requires all variables to be declared before use (recommended)
%require-our
# requires types to be declared
%require-types
# enable all warnings
%enable-all-warnings
 
# initialize the client library
QorusClient::initFast();
 
# get a Datasource object for the "omquser" datasource
Datasource ds = UserApi::getDatasourceDedicated("omquser");
# get a DatasourcePool object for the "omquser" datasource
DatasourcePool dsp = UserApi::getDatasourcePool("omquser");

Using SQL Tables

Use the UserApi::getSqlTable() method to acquire AbstractTable objects.

Python Example:

# the "qoreloader" module is provided by Qorus and provides the bridge between Python <-> Qore and, with Qore's "jni"
# module, between Python <-> Java
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_module
import qoreloader
 
# the "qoreloader" module provides the magic package "qore" which allows us to import Qore APIs and use them as if
# they were Python APIs
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_import_qore
from qore.QorusClientBase import QorusClient
 
# import Qorus's "UserApi" class
from qore.__root__.OMQ.UserApi import UserApi
 
# import Qore's SqlUtil module's AbstractTable class
from qore.SqlUtil.SqlUtil import AbstractTable
 
# initialize the Qorus client
QorusClient.initFast()
 
# get the "gl_import" table in Qorus's "erp1" datasource
gl_import: AbstractTable = UserApi.getSqlTable('erp1', 'gl_import')

Java Example:

// the magic "qoremod" package will load a Qore module and handles the dynamic bycode generation of wrapper classes
// in Java to enable Qore code to be used as if it were Java code
import qoremod.QorusClientBase.*;
 
// import Qorus's "UserApi" class
import qoremod.QorusClientBase.OMQ.UserApi.UserApi;
 
// import Qore's SqlUtil module's AbstractTable class
import qoremod.SqlUtil.SqlUtil.AbstractTable;
 
class MyClass {
    // static initialization
    static {
        try {
            // we initialize the Qorus client in the class's static initialization block
            QorusClient.initFast();
        } catch (Throwable e) {
            throw new RuntimeException(e);
        }
    }
 
    public static void main(String[] args) throws Throwable {
        // get the "gl_import" table in Qorus's "erp1" datasource
        AbstractTable erp1 = UserApi.getSqlTable("erp1", "gl_import");
    }
}

Qore Example

# Qorus client base module
%requires QorusClientBase
 
# use new style, assume local variables and do not require $ symbols on vars and members, etc
%new-style
# requires all variables to be declared before use (recommended)
%require-our
# requires types to be declared
%require-types
# enable all warnings
%enable-all-warnings
 
# initialize the client library
QorusClient::initFast();
 
# get the "gl_import" table in Qorus's "erp1" datasource
SqlUtil::AbstractTable gl_import = UserApi::getSqlTable("erp1", "gl_import");

Using Data Providers

Use the UserApi::getDataProvider() method to acquire AbstractDataProvider objects.

Python Example:

# the "qoreloader" module is provided by Qorus and provides the bridge between Python <-> Qore and, with Qore's "jni"
# module, between Python <-> Java
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_module
import qoreloader
 
# the "qoreloader" module provides the magic package "qore" which allows us to import Qore APIs and use them as if
# they were Python APIs
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_import_qore
from qore.QorusClientBase import QorusClient
 
# import Qorus's "UserApi" class
from qore.__root__.OMQ.UserApi import UserApi
 
# import Qore's DataProvider module's AbstractDataProvider class
from qore.DataProvider.DataProvider import AbstractDataProvider
 
# get the "gl_import" table in Qorus's "erp1" datasource
provider: AbstractDataProvider = UserApi.getDataProvider("connection/rest-billing-1/rest-billing-demo/accounts/POST")

Java Example:

// the magic "qoremod" package will load a Qore module and handles the dynamic bycode generation of wrapper classes
// in Java to enable Qore code to be used as if it were Java code
import qoremod.QorusClientBase.*;
 
// import Qorus's "UserApi" class
import qoremod.QorusClientBase.OMQ.UserApi.UserApi;
 
// import Qore's DataProvider module's AbstractDataProvider class
import qoremod.DataProvider.DataProvider.AbstractDataProvider;
 
class MyClass {
    public static void main(String[] args) throws Throwable {
        // get a REST POST Data Provider
        AbstractDataProvider provider =
            UserApi.getDataProvider("connection/rest-billing-1/rest-billing-demo/accounts/POST");
    }
}

Qore Example

# Qorus client base module
%requires QorusClientBase
 
# use new style, assume local variables and do not require $ symbols on vars and members, etc
%new-style
# requires all variables to be declared before use (recommended)
%require-our
# requires types to be declared
%require-types
# enable all warnings
%enable-all-warnings
 
# get a REST POST Data Provider
DataProvider::AbstractDataProvider provider =
    UserApi::getDataProvider("connection/rest-billing-1/rest-billing-demo/accounts/POST");

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), available in Qore. In Python and Java, this object should be declared and initialized explicitly as in the following examples.

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

Python Example:

# the "qoreloader" module is provided by Qorus and provides the bridge between Python <-> Qore and, with Qore's "jni"
# module, between Python <-> Java
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_module
import qoreloader
 
# the "qoreloader" module provides the magic package "qore" which allows us to import Qore APIs and use them as if
# they were Python APIs
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_import_qore
from qore.QorusClientBase import QorusClient
 
# import Qorus's "QorusSystemRestHelper" class
from qore.__root__.OMQ.Client import QorusSystemRestHelper
 
# initialize the Qorus client
QorusClient.initFast()
 
# create REST help object
qrest: QorusSystemRestHelper = QorusSystemRestHelper()
 
# retrieve system information
info: dict = qrest.get("system")
print('Qorus {} {} sessiond {}.format(info['omq-version'], info['instance-key'], info['session-id']))

Java Example:

// the magic "qoremod" package will load a Qore module and handles the dynamic bycode generation of wrapper classes
// in Java to enable Qore code to be used as if it were Java code
import qoremod.QorusClientBase.*;
 
// import Qore's Hash class
import org.qore.jni.Hash;
 
// import Qorus's REST helper class
import qoremod.QorusClientBase.OMQ.Client.QorusSystemRestHelper;
 
class MyClass {
    // Qorus REST API interface object
    public static QorusSystemRestHelper qrest;
 
    // static initialization
    static {
        try {
            // we initialize the Qorus client in the class's static initialization block
            QorusClient.initFast();
 
            // create REST help object
            qrest = new QorusSystemRestHelper();
        } catch (Throwable e) {
            throw new RuntimeException(e);
        }
    }
 
    public static void main(String[] args) throws Throwable {
        Hash info = (Hash)qrest.get("system");
        System.out.printf("Qorus %s %s sessiond %s\n", info.getString("omq-version"), info.getString("instance-key"),
            info.getString("session-id"));
    }
}

Qore Example

# Qorus client base module
%requires QorusClientBase
 
# use new style, assume local variables and do not require $ symbols on vars and members, etc
%new-style
# requires all variables to be declared before use (recommended)
%require-our
# requires types to be declared
%require-types
# enable all warnings
%enable-all-warnings
 
%exec-class client
 
class client {
    constructor() {
        # initialize the client
        QorusClient::initFast();
 
        # retrieve system information
        hash<auto> 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 API in the following example can be used.

Python Example:

# the "qoreloader" module is provided by Qorus and provides the bridge between Python <-> Qore and, with Qore's "jni"
# module, between Python <-> Java
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_module
import qoreloader
 
# the "qoreloader" module provides the magic package "qore" which allows us to import Qore APIs and use them as if
# they were Python APIs
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_import_qore
from qore.QorusClientBase import QorusClient
 
# import Qorus's "QorusSystemRestHelper" class
from qore.__root__.OMQ.Client import QorusSystemRestHelper
 
# initialize the Qorus client
QorusClient.initFast()
 
# get a connection to remote Qorus server "nodea"
qrest: QorusSystemRestHelper = QorusSystemRestHelper('nodea')
 
# retrieve system information
info: dict = qrest.get("system")
print('Qorus {} {} sessiond {}.format(info['omq-version'], info['instance-key'], info['session-id']))

Java Example:

// the magic "qoremod" package will load a Qore module and handles the dynamic bycode generation of wrapper classes
// in Java to enable Qore code to be used as if it were Java code
import qoremod.QorusClientBase.*;
 
// import Qore's Hash class
import org.qore.jni.Hash;
 
// import Qorus's REST helper class
import qoremod.QorusClientBase.OMQ.Client.QorusSystemRestHelper;
 
class MyClass {
    // Qorus REST API interface object
    public static QorusSystemRestHelper qrest;
 
    // static initialization
    static {
        try {
            // we initialize the Qorus client in the class's static initialization block
            QorusClient.initFast();
 
            // get a connection to remote Qorus server "nodea"
            qrest = new QorusSystemRestHelper("nodea");
        } catch (Throwable e) {
            throw new RuntimeException(e);
        }
    }
 
    public static void main(String[] args) throws Throwable {
        Hash info = (Hash)qrest.get("system");
        System.out.printf("Qorus %s %s sessiond %s\n", info.getString("omq-version"), info.getString("instance-key"),
            info.getString("session-id"));
    }
}

Qore Example

# Qorus client base module
%requires QorusClientBase
 
# use new style, assume local variables and do not require $ symbols on vars and members, etc
%new-style
# requires all variables to be declared before use (recommended)
%require-our
# requires types to be declared
%require-types
# enable all warnings
%enable-all-warnings
 
# initialize the client
QorusClient::initFast();
 
# get a connection to remote Qorus server "nodea"
OMQ::Client::QorusSystemRestHelper rest = UserApi::getRemoteRestConnection("nodea");
printf("Qorus %s %s sessiond %s\n", info."omq-version", info."instance-key", info."session-id");

Calling Service Methods from Qore

From Qore, use the omqservice variable to easily call service methods. Internally, this object uses the global omqapi variable to perform the communication with the server.

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

*hash<auto> 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 also

Communicating with Qorus Servers with the REST API to get a REST connection to a remote server.

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:

• qrest: Command-Line Interface to the Qorus System REST API
• ocmd: Command-Line Interface to the Qorus RPC API
• ostatus: Show System, Workflow, and Service Status
• oview: Show Workflow Instance, Order Status and Overviews
• ojview: Show Job Information
• ostart: Start Workflow Execution Instances
• ostop: Stop Workflow Instances
• qevent: Command-Line Event Monitor
• qhaorder: Qorus Order Proxy Server (DEPRECATED)

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%2fqorus-sock-qorus-instance-1/api/latest/system/starttime"

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 UserApi::getUserConnection() method to access connections defined in the Qorus system schema (Note that this method works equally in server and client code).

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

Python Example:

# the "qoreloader" module is provided by Qorus and provides the bridge between Python <-> Qore and, with Qore's "jni"
# module, between Python <-> Java
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_module
import qoreloader
 
# the "qoreloader" module provides the magic package "qore" which allows us to import Qore APIs and use them as if
# they were Python APIs
# ref: https://qoretechnologies.com/manual/qorus/gitlab-docs/develop/python/python/html/index.html#python_qoreloader_import_qore
from qore.QorusClientBase import QorusClient
 
# import Qorus's "UserApi" class
from qore.__root__.OMQ.UserApi import UserApi
 
# get the object from the "my_connection" connection
obj = UserApi.getUserConnection("my_connection")

Java Example:

// the magic "qoremod" package will load a Qore module and handles the dynamic bycode generation of wrapper classes
// in Java to enable Qore code to be used as if it were Java code
import qoremod.QorusClientBase.*;
 
// import Qorus's UserApi class
import qoremod.QorusClientBase.OMQ.UserApi.UserApi;
 
class MyClass {
    public static void main(String[] args) throws Throwable {
        // get the object from the "my_connection" connection
        Object o = UserApi.getUserConnection("my_connection");
    }
}

Qore Example

%new-style
%require-types
%strict-args
 
%requires QorusClientBase
 
# get the object from the "my_connection" connection
object o = UserApi::getUserConnection("my_connection");

Note

The class of the object returned by the UserApi::getUserConnection() method depends on the connection type.