Previous section   Next section

Introduction to the Native API

The Native API for Java is a lightweight interface to powerful InterSystems IRIS® resources that were once available only through ObjectScript. With the Native API, your applications can take advantage of seamless InterSystems IRIS data platform integration:
The following brief examples demonstrate how easy it is to add all of these abilities to your Java application.
Implement transparent bidirectional communication between ObjectScript and Java
The Native API for Java is implemented as an extension to the InterSystems JDBC driver in class jdbc.IRIS. Connections are created just they would be for any other Java application (see Using Java with InterSystems Software). This example opens a connection and then creates an instance of the Native API:
//Open a connection to InterSystems IRIS
  String connStr = "jdbc:IRIS://127.0.0.1:51773/USER";
  IRISConnection conn = (IRISConnection) DriverManager.getConnection(connStr,user,pwd);

// Use the connection to create an instance of the Native API
  IRIS iris = IRIS.createIRIS(conn);
This connection can also be used by the InterSystems Object Gateway, allowing your Java and ObjectScript applications to share the same context and work with the same objects.
Create and use individual instances of an ObjectScript class
Your application can create an instance of an ObjectScript class, immediately generate an Object Gateway proxy for it, and use the proxy to work with the ObjectScript instance (see the chapter on “Using Java Reverse Proxy Objects”).
In this example, the first line calls the %New() method of ObjectScript class Demo.dataStore, creating an instance in InterSystems IRIS. In Java, the call returns a corresponding proxy object named dataStoreProxy, which is used to call instance methods and get or set properties of the ObjectScript instance:
// use a classmethod call to create an ObjectScript instance and generate a proxy object
  IRISObject dataStoreProxy = (IRISObject)iris.classMethodObject("Demo.dataStore","%New");

// use the proxy to call instance methods, get and set properties
  dataStoreProxy.invokeVoid("ititialize");
  dataStoreProxy.set("propertyOne","a string property");
  String testString = dataStoreProxy.get("propertyOne");
  dataStoreProxy.invoke("updateLog","PropertyOne value changed to "+testString);

// pass the proxy back to ObjectScript method ReadDataStore()
  iris.classMethodObject("Demo.useData","ReadDataStore",dataStoreProxy);
The last line of this example passes the dataStoreProxy proxy to an ObjectScript method named ReadDataStore(), which interprets it as a reference to the original ObjectScript instance. From there, the instance could be saved to the database, passed to another ObjectScript application, or even passed back to your Java application.
Call ObjectScript classmethods and user-defined functions
You can easily call an ObjectScript classmethod or function (see the chapter on “Calling ObjectScript Methods and Functions”).
  String currentNameSpace = iris.classMethodString("%SYSTEM.SYS","NameSpace");
This example just calls a classmethod to get some system information, but the real power of these calls is their ability to leverage user-written code. You can write custom ObjectScript classmethods or functions for any purpose, and your Java application can call them as easily as it calls native Java methods.
Work with multidimensional global arrays
The Native API provides all the methods needed to manipulate global arrays (see the chapter on “Working with Global Arrays”). You can easily access and manipulate globals, traverse multilevel global arrays, and inspect data structures just as you can in ObjectScript. The following example demonstrates how to create, read, change, and delete a simple global array.
// Create a global (ObjectScript equivalent: set ^myGlobal("subOne") = 10)
  iris.set(10, "myGlobal", "subOne"); 

// Change, read, and delete the global
  iris.increment(2, "myGlobal", "subOne")   // increment value to 12
  System.out.print("New number is " + iris.getInteger("myGlobal", "subOne"));
  iris.kill("myGlobal", "subOne");
Previous section   Next section