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 Native API, Object Gateway proxy objects, and ObjectScript applications can all share the same connection and work together in the same context.
The Native API allows you to create instances of ObjectScript classes on InterSystems IRIS and generate Object Gateway proxy objects for them at runtime. Your Java application can use proxies to work with ObjectScript objects as easily as if they were native Java objects.
You can write custom ObjectScript classmethods or functions for any purpose, and your application can use the Native API to call them just as easily as native Java methods.
The Native API provides direct access to the high performance native data structures (global arrays) that underpin the InterSystems IRIS multidimensional storage model. 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 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");