docs.intersystems.com
Home  /  First Look: DBNative and InterSystems IRIS


Articles
First Look: DBNative and InterSystems IRIS
InterSystems: The power behind what matters   
Search:  


This First Look guide explains how to access InterSystems IRIS globals from a Java application using the InterSystems IRIS™ DBNative 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 DBNative without bogging you down in details, we’ve kept this exploration 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 DBNative to your production systems, there may be things you will need to do differently. Be sure not to confuse this exploration of DBNative 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 DBNative in production.
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, by entering the code below into the InterSystems IRIS Terminal, you can associate the value “Red” with the key “Color” using a global named ^Settings:
 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 DBNative Important?
DBNative 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 IRIS Terminal. This feature takes advantage of the JDBC connection to expose core ObjectScript functionality in Java applications. Importantly, since DBNative 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 DBNative.
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 DBNative
We have developed a brief demo that shows you how to work with DBNative in a Java application.
Before You Begin
To run the demo, you’ll need a machine with a running, licensed instance of InterSystems IRIS, version 1.7 or 1.8 of the JDK, and a Java IDE of your choice. You will also need to add isc-jdbc-3.0.0.jar to your CLASSPATH. You can find this file in the subdirectory <install-dir>\dev\java\lib\JDK18, where <install-dir> is the installation directory for your instance of InterSystems IRIS. If you are using version 1.7 of the JDK, you can locate this file in the subdirectory <install-dir>\dev\java\lib\JDK17.
For instructions on how to install and license a development instance of InterSystems IRIS, see Quick Start: InterSystems IRIS Installation.
Things to Note about the Sample
The connection string syntax is:
jdbc:Cache://host_IP:superserverPort/namespace, username, password
Note the following:
A shared memory connection will offer even better performance for DBNative. In order to use a shared memory connection, you will need a different connection string. For more information, see First Look: JDBC and InterSystems IRIS.
Using DBNative
At this point, you are ready to experiment with DBNative. Create a new Java project named “DBNative” using an IDE of your choice. Paste in the following code:
import java.sql.DriverManager;

import com.intersys.jdbc.CacheConnection;
import com.intersys.jdbc.DBNative;
import com.intersys.jdbc.SubscriptIterator;

public class dbnative {

    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
            CacheConnection conn = (CacheConnection) DriverManager.getConnection
                    ("jdbc:Cache://localhost:"+superserverPort+"/"+namespace,username,password);
            // create DBNative object
            DBNative dbNative = DBNative.createDBNative(conn);


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

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

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



            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
            dbNative.set(8888,"^testglobal","1");
            dbNative.set(9999,"^testglobal","2");

            // iterate over all nodes forwards
            SubscriptIterator subscriptIter = dbNative.getSubscriptIterator("^testglobal");
            System.out.println("walk forwards");
            while (subscriptIter.hasNext()) {
                String subscript = subscriptIter.next();
                System.out.println("subscript="+subscript+", value="+subscriptIter.getValue());
            }

            System.out.println();

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

            // calling a class method
            // ObjectScript equivalent: set returnValue = ##class(%Library.Utility).Date(5)
            String returnValue = dbNative.stringClassMethod("%Library.Utility","Date",5);
            System.out.println(returnValue);

            System.out.println();

            // close connection and DBNative object
            dbNative.close();
            conn.close();

        } catch (Exception ex) {
            System.out.println(ex.getMessage());
        }
    }

} // end class
Make sure to edit the superserverPort, username, namespace, and password variables to have accurate values.
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 DBNative.
If the example executes successfully, you should see printed 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 System Management Portal
Next, you will want to confirm your results in the System Management Portal. First, ensure that you are in the USER namespace. 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.
For More Information about DBNative
For more information on DBNative, globals, and InterSystems IRIS, see:
First Look: JDBC and InterSystems IRIS
Using Globals
Using the Java DBNative API with InterSystems IRIS