Connecting Java to InterSystems IRIS using JDBC

In the previous article, we talked about ODBC and connecting from C#. And now, let's look at JDBC and Java. The InterSystems JDBC driver is the recommended, high-performance way to integrate your Java applications.

Here is a step-by-step guide to getting your Java application connected to an IRIS instance using the JDBC driver.

Step 1: Obtain and Include the InterSystems IRIS JDBC Driver

Unlike ODBC drivers, which are often installed system-wide, JDBC drivers are typically distributed as JAR files that must be included in your Java project's classpath.

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. Conversely, you can download the jar file from Driver packages page.

Include the jar file in Project:

• Maven/Gradle: If you use a build tool, the simplest method is to add the InterSystems JDBC driver as a dependency in your pom.xml or build.gradle file. This automatically downloads and manages the JAR.
• Manual: For simple projects, you must place the JAR file in a project directory (e.g., /lib) and explicitly add it to your classpath when compiling and running.

Step 2: Define the JDBC Connection

The JDBC connection URL specifies exactly where and how the Java application connects to the database. It is formatted as jdbc:<subprotocol>://<host>:<port>/<namespace>.

The format for InterSystems IRIS is:

String url = "jdbc:IRIS://127.0.0.1:1972/USER";
String user = "_System";
String password = "SYS";

Note:

• The Driver Prefix is jdbc:IRIS.
• 127.0.0.1 is the server address (change this for remote connections).
• 1972 is the IRIS SuperServer port (the standard is usually 1972 or 51773).
• USER is the target Namespace in InterSystems IRIS where your code and data reside.
• The default user is _System with the password SYS. Always change these defaults in a production environment.

Step 3: Implement the Connection in Java

We will use the standard java.sql package to establish the connection and execute a query.

Here is a minimal Java example that connects to IRIS, executes a simple query against a default table, and displays the result using try-with-resources for reliable connection management.

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());
        }
    }
}

❗ As with all database connections, always use prepared statements (similar to parameterized queries) in production code to prevent SQL injection vulnerabilities.