Connecting to InterSystems IRIS from Java

Connecting to InterSystem IRIS Hierarchical Model from Java

This notebook provides a step-by-step guide for Java developers looking to connect to and interact with InterSystems IRIS Hierarchical model.

Step 1. Prerequisites

Before writing any code, ensure that all necessary components are installed.

Component	Status	Check
InterSystems IRIS	Running	Ensure the IRIS instance is started and accessible
JDBC Driver	Available	Verify that you have intersystems-jdbc.jar file
Java project	Ready	Your project should be set up in your preferred IDE and include intersystems-jdbc.jar in classpath

You can download the jar file from Driver packages page.
If InterSystems IRIS is installed on your local machine or another you have access to, you can find the file in install-dir/dev/java/lib/ or similar, where install-dir is the installation directory for the instance.

Step 2. Forming Connection String

The connection string requires three critical pieces of information: the Server location (Host and Port), the target Namespace, and Credentials (UID and PWD):

        String connStr = "jdbc:IRIS://127.0.0.1:1972/USER";
String user = "_SYSTEM";
String pwd = "SYS";
        
    

Step 3. Writing Java Code to Write a Global to InterSystems IRIS

In the dedicated class add imports:

import com.intersystems.jdbc.*;

Create and open the connection to the database using the connectionString from Step 2:

        IRISConnection conn = (IRISConnection)java.sql.DriverManager.getConnection(connStr,user,pwd);
        
    

Create an IRIS object that will allow to work with globals:

IRIS global = IRIS.createIRIS(conn);

Create a global ^Person with two nodes "Doe,John" and "Smith,Jane" and set their dates of birth as values:

        global.set(Date.valueOf("1991-05-26"), "Person", "Doe,John");
global.set(Date.valueOf("1991-05-26"), "Person", "Smith,Jane");

To update a value of any node, use the same method.

Close and release resources:

        global.close();
conn.close();

Step 4. Writing Java code to Read All Nodes of the Global from InterSystems IRIS DB

Create an iterator that will allow to get access to all nodes on the first level of the global ^Person:

IRISIterator iter = global.getIRISIterator("Person");

Iterate over the resultset and print subscript and value:

        while (iter.hasNext()) {
    iter.next();
    System.out.println(iter.getSubscriptValue() + " was born on " + global.getDate("Person", iter.getSubscriptValue())); 
}
        
    

Step 5. Writing Java Code to Read Exact Node from InterSystems IRIS DB

Get the value of the node:

        Date dob = global.getDate("Person", "Smith,Jane");
System.out.println(dob);

Step 6. Writing Java Code to Delete a Node(s) from the DB

Delete the node:

        global.kill("Person", "Doe,John");
global.kill("Person");

Resulting Class

Here's the whole class including exception handling:

        package com.example;

import java.sql.Date;
import java.sql.SQLException;
import com.intersystems.jdbc.*;

public class GlobalsExample {

    public static void main(String[] args) throws Exception {
        
    	//Open a connection to the server and create an IRIS object
        String connStr = "jdbc:IRIS://127.0.0.1:1972/USER";
        String user = "_SYSTEM";
        String pwd = "SYS";
        
        // Use standard JDBC Connection
        try (IRISConnection conn = (IRISConnection)java.sql.DriverManager.getConnection(connStr,user,pwd)){
        	IRIS global = IRIS.createIRIS(conn);   
        	
        	global.set(Date.valueOf("1991-05-26"), "Person", "Doe,John");
        	global.set(Date.valueOf("1991-05-26"), "Person", "Smith,Jane");
        	
        	// Read child nodes in collation order while iter.hasNext() is true
        	try {
        	    IRISIterator iter = global.getIRISIterator("Person");
        	    while (iter.hasNext()) {
        	      iter.next();
        	      System.out.println(iter.getSubscriptValue() + " was born on " + global.getDate("Person", iter.getSubscriptValue())); 
        	    }
        	} catch  (Exception e) {
        	    System.out.println( e.getMessage());
        	}
        	
        	Date dob = global.getDate("Person", "Smith,Jane");
        	System.out.println(dob);
        	
        	global.kill("Person", "Doe,John");
        	global.kill("Person");
        
        	global.close();
            conn.close();

        } catch (SQLException e) {
            System.err.println("\n--- Database Error ---");
            System.err.println("Error Message: " + e.getMessage());
        }
    }
}
        
    

Connecting to InterSystem IRIS Object Model from Java (using XEP API)

This notebook provides a step-by-step guide for Java developers looking to connect to and interact with Object model of InterSystems IRIS using the InterSystems XEP API.

Step 1. Prerequisites

Before writing any code, ensure that all necessary components are installed.

Component	Status	Check
InterSystems IRIS	Running	Ensure the IRIS instance is started and accessible
64-bit Java JDK	Running	Ensure you're using the correct Java version
XEP and JDBC jars	Available	All XEP applications require JAR files intersystems-jdbc.jar and intersystems-xep.jar
Java project	Ready	Your project should be set up in Visual Studio or your preferred IDE

You can download the XEP assembly from Driver packages page.
If InterSystems IRIS is installed on your local machine or another you have access to, you can find the file in install-dir/dev/java/lib/ or similar, where install-dir is the installation directory for the instance.

Step 2. Creating Proxy Class

To be able to work with persistent events, you need to create a class on the client side to generate objects for storage. To do this, create a new class with the following contents:

        package com.example;

import java.sql.Date;

public class Person {
	public String name;
	public Date dob;
	
	public Person() {}
    
    Person(String str, Date date) {
        name = str;
        dob = date;
    }
    
    public static Person[] generateSampleData(int objectCount) {
    	Person[] data = new Person[objectCount];
        for (int i=0;i<objectCount;i++) {
            data[i] = new Person("Doe,John"+i, Date.valueOf("1991-05-26"));
        }
        return data;
    }
}

        
    

Step 3. Writing Java Code to Store Data in the Database

In the dedicated class add imports of XEP API:

import com.intersystems.xep.*;

Create objects you wish to store in the database

        // Generate 12 SingleStringSample objects for use as test data
Person[] sampleArray = Person.generateSampleData(12);

Create an EventPersister and connect to the database

        EventPersister xepPersister = PersisterFactory.createPersister();
xepPersister.connect("127.0.0.1",1972,"User","_SYSTEM","SYS"); // connect to localhost

Import schema

        xepPersister.importSchema("xep.samples.SingleStringSample");   // import flat schema
        
    

Create an event and link it to the class

Event xepEvent = xepPersister.getEvent("xep.samples.Person");

Save 12 created objects of class xep.sample.Person to the database

xepEvent.Store(sampleArray);

Close and release all resources

        xepEvent.Close();
xepPersister.Close();

Step 4. Writing Java Code to Read Objects from the Database using SQL Query

In the same class write a query statement

String sqlQuery = "SELECT * FROM com_example.Person WHERE %ID BETWEEN ? AND ?";

create an EventQuery and execute it

        EventQuery xepQuery = xepEvent.createQuery(sqlQuery);
xepQuery.setParameter(1,3);    // assign value 3 to first SQL parameter
xepQuery.setParameter(2,12);   // assign value 12 to second SQL parameter
xepQuery.execute();            // get resultset for IDs between 3 and 12
        
    

Print the results

        EventQueryIterator xepIter = xepQuery.getIterator();
while (xepIter.hasNext()) {
	Person newSample = xepIter.next();
	System.out.println(newSample.name+" was born on "+newSample.dob);
}
        
    

Close the query

xepQuery.close();

Step 5. Writing Java Code to Read Object from the Database

In the same class using the same event get an object by its ID

        Person newSample = (Person)xepEvent.getObject(7);
System.out.println(newSample.name+" was born on "+newSample.dob);

Step 6. Writing Java Code to Change Object in the Database

In the same file using the same event either create a new object and substitute the existing object or take the already read object from step 4 and change its properties and then update the object in the database

        Person newP = new Person("Smith,Jane", Date.valueOf("1991-05-26"));
xepEvent.updateObject(4, newP);

Step 7. Writing Java Code to Delete an Object from the Database

In the same file using the same event use the known ID of an object to delete it from the database

xepEvent.deleteObject(3);

Resulting Class

Here's the whole class:

        package com.example;

import com.intersystems.xep.*;
import java.sql.Date;

public class XEPExample {
	 public static void main(String[] args) throws Exception {
		// Generate 12 Person objects for use as test data
		 Person[] sampleArray = Person.generateSampleData(12);
		 
		 // EventPersister
		 EventPersister xepPersister = PersisterFactory.createPersister();
		 xepPersister.connect("127.0.0.1",1972,"User","_SYSTEM","SYS"); // connect to localhost
		 xepPersister.deleteExtent("com.example.Person");   // remove old test data
		 xepPersister.importSchema("com.example.Person");   // import flat schema
		 
		 // Event
		 Event xepEvent = xepPersister.getEvent("com.example.Person");
		 xepEvent.store(sampleArray);
		 
		 xepEvent.deleteObject(3);
		 System.out.println("Object deleted");
		 
		 Person newP = new Person("Smith,Jane", Date.valueOf("1991-05-26"));
		 xepEvent.updateObject(4, newP);
		 
		 Person person = (Person)xepEvent.getObject(7);
		 if (person != null) {			 
			 person.name = "Doe,Jane";
			 xepEvent.updateObject(7, person);
			 }

		 // EventQuery
		 String sqlQuery = "SELECT * FROM com_example.Person WHERE %ID BETWEEN ? AND ?";
		 EventQuery xepQuery = xepEvent.createQuery(sqlQuery);
		 xepQuery.setParameter(1,3);    // assign value 3 to first SQL parameter
		 xepQuery.setParameter(2,12);   // assign value 12 to second SQL parameter
		 xepQuery.execute();            // get resultset for IDs between 3 and 12

		 // EventQueryIterator
		 EventQueryIterator xepIter = xepQuery.getIterator();
		 while (xepIter.hasNext()) {
		    Person newSample = xepIter.next();
		    System.out.println(newSample.name+" was born on "+newSample.dob);
		 }

		 xepQuery.close();
		 xepEvent.close();
		 xepPersister.close();
	 } // end main()
} // end class XepSimple
        
    

Connecting to InterSystem IRIS Relational Model from Java (via JDBC)

This notebook provides a step-by-step guide for Java developers looking to connect to and interact with InterSystems IRIS SQL using JDBC bridge.

Step 1. Prerequisites

Before writing any code, ensure that all necessary components are installed.

Component	Status	Check
InterSystems IRIS	Running	Ensure the IRIS instance is started and accessible
JDBC Driver	Available	Verify that you have intersystems-jdbc.jar file
Java project	Ready	Your project should be set up in your preferred IDE and include intersystems-jdbc.jar in classpath

You can download the jar file from Driver packages page.
If InterSystems IRIS is installed on your local machine or another you have access to, you can find the file in install-dir/dev/java/lib/ or similar, where install-dir is the installation directory for the instance.

Step 2. Writing Java Code to Get Data from InterSystems IRIS via JDBC

In the dedicated class add imports to work with JDBC:

        import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
        
    

Create and open the connection to the database:

        String url = "jdbc:IRIS://127.0.0.1:1972/USER";
String user = "_System";
String password = "SYS";
Connection conn = DriverManager.getConnection(url, user, password);
        
    

Prepare and execute a SQL statement using PreparedStatement class:

        PreparedStatement pstmt = conn.prepareStatement("SELECT ID, Name, DOB FROM Sample.Person WHERE ID < ?")
int maxId = 5;
pstmt.setInt(1, maxId);
ResultSet rs = pstmt.executeQuery()
        
    

Loop throught the result

        while (rs.next()) {
    // Access data by column name
    int id = rs.getInt("ID");
    String name = rs.getString("Name");
    // JDBC automatically handles the mapping of IRIS types to Java types (e.g., Date)
    String dob = rs.getDate("DOB").toString(); 
    System.out.println(String.format("ID: %d, Name: %s, DOB: %s", id, name, dob));
}
        
    

Resulting Class

Here's the whole class including exception handling:

        package com.example;

import java.sql.Connection;
import java.sql.DriverManager;
import java.sql.PreparedStatement;
import java.sql.ResultSet;
import java.sql.SQLException;
	
public class IrisJdbcConnector {

    public static void main(String[] args) {
        
        // 1. Define the connection details
        String url = "jdbc:IRIS://127.0.0.1:1972/USER";
        String user = "_System";
        String password = "SYS";
        
        int maxId = 5; // Parameter for the query

        // The try-with-resources block ensures all resources are closed automatically
        try (
            // 2. Establish the connection
            Connection conn = DriverManager.getConnection(url, user, password);
            
            // 3. Define the SQL Query using a placeholder (?)
            PreparedStatement pstmt = conn.prepareStatement("SELECT ID, Name, DOB FROM Sample.Person WHERE ID < ?")
        ) {
            System.out.println("Connection to InterSystems IRIS successful!");

            // 4. Bind the parameter value
            pstmt.setInt(1, maxId);

            // 5. Execute the query
            try (ResultSet rs = pstmt.executeQuery()) {
                
                System.out.println("--- Query Results ---");
                
                // 6. Iterate through the results
                while (rs.next()) {
                    // Access data by column name
                    int id = rs.getInt("ID");
                    String name = rs.getString("Name");
                    // JDBC automatically handles the mapping of IRIS types to Java types (e.g., Date)
                    String dob = rs.getDate("DOB").toString(); 
                    
                    System.out.println(String.format("ID: %d, Name: %s, DOB: %s", id, name, dob));
                }
            }
            
        } catch (SQLException e) {
            // 7. Handle JDBC-specific exceptions (e.g., connection failure, invalid SQL)
            System.err.println("\n--- Database Error ---");
            System.err.println("SQL State: " + e.getSQLState());
            System.err.println("Error Message: " + e.getMessage());
            System.err.println("Ensure the IRIS server is running and the JDBC driver JAR is in the classpath.");
        } catch (Exception e) {
            System.err.println("\n--- General Error ---");
            System.err.println(e.getMessage());
        }
    }
}
        
    