docs.intersystems.com
Home  /  Application Development: Language Bindings and Gateways  /  Using the InterSystems Native API for Java  /  Introduction to the Native API


Using the InterSystems Native API for Java
Introduction to the Native API
[Back]  [Next] 
InterSystems: The power behind what matters   
Search:  


The Native API is a lightweight Java interface to the native multidimensional storage data structures that underlie the InterSystems IRIS™ object and SQL interfaces. The Native API allows you to implement your own data structures by providing direct access to global arrays, the tree-based sparse arrays that form the basis of the multidimensional storage model. The Native API is implemented in the com.intersystems.jdbc.IRIS class as an extension to the InterSystems JDBC driver (see InterSystems Java Connectivity Options in Using Java JDBC with InterSystems IRIS for details).
This chapter discusses the following topics:
Introduction to Global Arrays
An InterSystems IRIS™ global array, like all sparse arrays, is a tree structure rather than a sequentially numbered list. The basic concept behind sparse arrays can be illustrated by analogy to the Java package naming convention. Each class in a package is uniquely identified by a namespace made up of a series of identifiers. For example, consider a package containing only two classes, main.foo.SubFoo and main.bar.UnderBar. The five identifiers that make up these namespaces could be viewed as elements of a sparse array:
   main -->|--> foo --> SubFoo
           |--> bar --> UnderBar
Classes could be created that use the other possible namespaces (for example, main or main.bar), but no resources are wasted if those classes do not exist.
Like Java classes, the elements of a global array are uniquely identified by a namespace consisting of an arbitrary number of identifiers. All namespaces in the global array structure are referred to as nodes. A node must either contain data, have child nodes, or both. A node that has child nodes but does not contain data is called a valueless node.
The root identifier (like main in the Java package) is referred to as the global name. All other identifiers in the namespace are called subscripts. The complete namespace of the node (global name plus subscripts) is the node address.
In ObjectScript notation, a node address is symbolized by a circumflex (^) followed by the global name and a comma-delimited subscript list in parentheses. For example, given a global array using the same identifiers as the Java package example, the nodes in the array would be represented as follows:
   (valueless root node)   ^main
   (valueless node)           ^main("foo")
   (node with value)             ^main("foo","SubFoo") = <value>
   (valueless node)           ^main("bar")
   (node with value)             ^main("bar","UnderBar") = <value>
The root node of the array is simply ^main, with no subscript list. The two nodes containing data are ^main("foo","SubFoo") and ^main("bar","UnderBar"). Nodes ^main, ^main("foo") and ^main("bar") are all valueless.
All descendants of a given node are referred to as subnodes of that node. For example, ^main("foo","SubFoo") is a subnode of ^main("foo"), and all four subscripted nodes are subnodes of ^main.
The term node level refers to the number of subscripts in the subscript list. For example, ^main("bar","UnderBar") is a level 2 node. The address has a level 1 subscript ("bar"), and a level 2 subscript ("UnderBar").
For more detailed information on the structure of global arrays, see Logical Structure of Globals in Using Globals.
The NativeDemo Program
This section describes a Native API application that creates and accesses a global array. In NativeDemo, a new jdbc.IRISConnection object is created and connected to the USER namespace on the InterSystems IRIS server. The connection object is used to create an instance of the jdbc.IRIS class. The program adds a new global array with two nodes to the database, reads the new persistent values from the database, and then deletes them before closing the connection and terminating.
The NativeDemo Program
package nativedemo;
import com.intersystems.jdbc.*;
public class NativeDemo {
  public static void main(String[] args) throws Exception {
    String connStr = "jdbc:IRIS://127.0.0.1:51773/USER";
    String user = "_SYSTEM";
    String password = "SYS";
    try {
      System.out.println("\nCreating the database connection... ");
      IRISConnection conn = (IRISConnection) java.sql.DriverManager.getConnection(connStr,user,password);
      System.out.println("Creating the IRIS instance... ");
      IRIS dbnative = IRIS.createIRIS(conn);

      dbnative.set("Hello world","globalArray","sub1");
      System.out.println("Created subnode ^globalArray(\"sub1\") with value \""
                         + dbnative.getString("globalArray","sub1") + "\"");
      dbnative.set("value2","globalArray"); 
      System.out.println("Assigned value \"" + dbnative.getString("globalArray") + "\" to root node.");

      dbnative.kill(globalName);   // delete entire global array ^globalArray
      dbnative.close();
      conn.close();
    }
    catch (Exception e) {
      System.out.println(e.getMessage());
    }
  }// end main()
} // end class NativeDemo
NativeDemo prints the following lines:
Creating the database connection...
Creating the IRIS instance...
Created subnode ^globalArray("sub1") with value "Hello world"
Assigned value "value2" to root node.
In this example, JDBC and Native API methods perform the following actions:
All of these methods are discussed in detail later in this book. See the next chapter (Working with Global Arrays) for details about specifying the subscripts of a node reference, creating a node, and changing a node value.