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. All Native API classes are part of the InterSystems JDBC driver (com.intersystems.jdbc). They access the database through a standard JDBC connection, and can be used without any special setup or installation procedures. The Native API is a tool with many uses:
Call ObjectScript classmethods and functions — Access any available ObjectScript class or routine (including the huge collection in the Class Library) and call ObjectScript classmethods or functions from your Java application as easily as you can call native Java methods.
Directly control instances of an ObjectScript class — Create a Java proxy object to control an object on the server. The proxy can be used to call instance methods and get or set properties just as if you were using the server object directly.
Work with multidimensional global arrays — Gain direct access to the high performance native data structures. Global arrays can be created, read, changed, and deleted in Java applications just as they can in ObjectScript.
The following brief examples demonstrate how easy it is to add these abilities to your Java application.
Your Java application can call any ObjectScript method or function as easily as it calls native Java methods (see “Calling ObjectScript Methods and Functions”).
String currentNameSpace = iris.classMethodString("%SYSTEM.SYS","NameSpace");
This example calls one of the many methods available from the InterSystems Class Library, but you can just as easily access your own custom ObjectScript code. The following example uses a similar method to create a new instance of an ObjectScript class.
Your application can create an instance of an ObjectScript class, immediately generate a Java proxy object for it, and use the proxy to work with the ObjectScript instance (see “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.
The Native API provides all the methods needed to manipulate global arrays (see “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");