Skip to main content

First Look: InterSystems IRIS Native API for Java

This First Look explains how to access InterSystems IRIS® data platform globals from a Java application using the InterSystems IRIS Native functionality. In this exploration, you will first connect to InterSystems IRIS. You will then set and retrieve the value of a global node in InterSystems IRIS and iterate over the nodes of another global. You will also call an InterSystems IRIS class method. All of these activities will be performed from a Java application.

To give you a taste of the Native API without bogging you down in details, this exploration is intentionally simple. These activities are designed to only use the default settings and features, so that you can acquaint yourself with the fundamentals of the feature without having to deal with details that are off-topic or overly complicated. When you bring the Native API to your production systems, there may be things you will need to do differently. Be sure not to confuse this exploration of the Native API with the real thing! The sources provided at the end of this document will give you a good idea of what is involved in using the Native API in production.

To browse all of the First Looks, including those that can be performed on a free evaluation instance of InterSystems IRIS, see InterSystems First Looks.

Introduction to Globals

Globals provide an easy-to-use way to store data in persistent, multidimensional arrays. A global is a named multidimensional array that is stored within a physical InterSystems IRIS database. Within an application, the mappings of globals to physical databases is based on the current namespace — a namespace provides a logical, unified view of one or more physical databases. As an example, to associate the value “Red” with the key “Color” using a global named ^Settings, open the InterSystems Terminal, using the procedure described for your instance in InterSystems IRIS Basics: Connecting an IDE, and enter the following code:

 set ^Settings("Color")="Red"

You can take advantage of the multidimensional nature of globals to define a more complex structure:

 set ^Settings("Auto1","Properties","Color") = "Red"
 set ^Settings("Auto1","Properties","Model") = "SUV"
 set ^Settings("Auto2","Owner") = "Mo"
 set ^Settings("Auto2","Properties","Color") = "Green"

For more information on globals, see Using Globals.

Why is the Native API Important?

The Native API is a feature built on top of InterSystems IRIS JDBC functionality that allows you to execute a limited subset of core ObjectScript-like commands and access InterSystems IRIS data using globals, similar to the way you would in the InterSystems Terminal. This feature takes advantage of the JDBC connection to expose core ObjectScript functionality in Java applications. Importantly, since IRIS Native uses the same connection as JDBC, InterSystems IRIS data is exposed to your Java application as both relational tables through JDBC, and as globals through the Native API.

InterSystems IRIS provides a unique set of capabilities to use the same physical connection and transaction context to manipulate data using multiple paradigms: native, relational, and object-oriented.

Exploring the Native API

The following brief demo shows you how to work with the Native API in a Java application. (Want to see a quick demo of InterSystems IRIS Java development and interoperability features before getting started? Try the Java QuickStart!)

Before You Begin

To use the procedure, you will need a system to work on, with version 1.8 of the JDK and a Java IDE of your choice installed, and a running InterSystems IRIS instance to connect to. Your choices for InterSystems IRIS include several types of licensed and free evaluation instances; the instance need not be hosted by the system you are working on (although they must have network access to each other). For information on how to deploy each type of instance if you do not already have one to work with, see Deploying InterSystems IRIS in InterSystems IRIS Basics: Connecting an IDE. Connect your IDE to your InterSystems IRIS instance using the information in InterSystems IRIS Connection Information and Java IDEs in the same document.

You will also need to add the InterSystems IRIS JDBC driver, intersystems-jdbc-3.0.0.jar, to your local CLASSPATH. You can download this file from If you have installed InterSystems IRIS on your local machine or another you have access to, you can find the file in install-dir\dev\java\lib\JDK18, where install-dir is the InterSystems IRIS installation directory.

Connecting to InterSystems IRIS

The InterSystems IRIS connection string syntax is:


where the variables represent the connection settings described for your instance in InterSystems IRIS Basics: Connecting an IDE. (This is the same information you used to connect your IDE to the instance). Set namespace to the predefined namespace USER, as shown in the code that follows, or to another namespace you have created in your installed instance (as long as you update the code).

If you are connecting to an instance on the local Windows machine (using either the hostname localhost or the IP address, the connection automatically uses a special, high-performance local connection called a shared memory connection, which offers even better performance for the Native API. For more information, see First Look: JDBC and InterSystems IRIS.

Using the Native API

At this point, you are ready to experiment with the Native API. In your connected IDE (see Before You Begin), create a new Java project named IRISNative and paste in the following code. Make sure to edit the superserverPort, username, namespace, and password variables to reflect the correct values for your instance.

import java.sql.DriverManager;

import com.intersystems.jdbc.IRISConnection;
import com.intersystems.jdbc.IRIS;
import com.intersystems.jdbc.IRISIterator;

public class IRISNative {

    protected static int superserverPort = 00000; // YOUR PORT HERE
    protected static String namespace = "USER";
    protected static String username = "_SYSTEM";
    protected static String password = "SYS";

    public static void main(String[] args) {
        try {
            // open connection to InterSystems IRIS instance using connection string
            IRISConnection conn = (IRISConnection) DriverManager.getConnection
            // create Native API object
            IRIS iris = IRIS.createIRIS(conn);

            System.out.println("[1. Setting and getting a global]");

            // setting and getting a global
            // ObjectScript equivalent: set ^testglobal("1") = 8888
            // ObjectScript equivalent: set globalValue = $get(^testglobal("1"))
            Integer globalValue = iris.getInteger("^testglobal","1");

            System.out.println("The value of ^testglobal(1) is " + globalValue);

            System.out.println("[2. Iterating over a global]");

            // modify global to iterate over
            // ObjectScript equivalent: set ^testglobal("1") = 8888
            // ObjectScript equivalent: set ^testglobal("2") = 9999

            // iterate over all nodes forwards
            IRISIterator subscriptIter = iris.getIRISIterator("^testglobal");
            System.out.println("walk forwards");
            while (subscriptIter.hasNext()) {
                String subscript =;
                System.out.println("subscript="+subscript+", value="+subscriptIter.getValue());


            System.out.println("[3. Calling a class method]");

            // calling a class method
            // ObjectScript equivalent: set returnValue = ##class(%Library.Utility).Date(5)
            String returnValue = iris.classMethodString("%Library.Utility","Date",5);


            // close connection and IRIS object

        } catch (Exception ex) {


The example code is split into three sections:

  1. The first section shows how you set the value of a global and later retrieve it. The commands executed in this section are equivalent to the ObjectScript commands SET and GET.

  2. The second section shows how to iterate through the subnodes of a global, similar to the $ORDER ObjectScript function.

  3. The third section shows how you call an ObjectScript class method from your Java application using the Native API.

If the example executes successfully, you should see output with the results of the sample code:

[1. Setting and getting a global]
The value of ^testglobal(1) is 8888

[2. Iterating over a global]
walk forwards
subscript=1, value=8888
subscript=2, value=9999

[3. Calling a class method]
Jan 30, 2018

Confirming the Changes in the Management Portal

Next, confirm your results in the Management Portal, using the following procedure.

  1. Open the Management Portal for your instance in your browser, using the URL described for your instance in InterSystems IRIS Basics: Connecting an IDE.

  2. If you are not in the namespace you specified in the code, switch to it.

  3. Navigate to the Globals page (System Explorer > Globals). You should see the testglobal global created in the example code. Click View to see its contents. You should see the two nodes of the global: ^testglobal(1) = 8888 and ^testglobal(2) = 9999.

Learn More About the Native API

For more information on the Native API, globals, and InterSystems IRIS, see:

First Look: JDBC and InterSystems IRIS

Using Globals

Using the Native API for Java