docs.intersystems.com
Home  /  First Look: JDBC and InterSystems IRIS


Articles
First Look: JDBC and InterSystems IRIS
InterSystems: The power behind what matters   
Search:  


If you want to use Java with InterSystems IRIS™, this document provides an introduction to how to use JDBC.
JDBC: How to Use It with InterSystems IRIS
InterSystems provides a fully compliant (JDBC 4.2), pure Java, type 4 JDBC driver, which is a single standalone JAR file with no dependencies.
If you are already familiar with JDBC, and have a JDK 1.7 or 1.8 installed, all you need to do is to add intersystems-jdbc-3.0.0.jar to your CLASSPATH. The driver name is com.intersystems.jdbc.IRISDriver, and it’s typically installed under
<install-dir>\dev\java\lib\JDK1x
where JDK1x is either JDK17 or JDK18 (which are the two currently JDK supported versions).
The URL (connection string) is:
jdbc:IRIS://ipAddress:superserverPort/namespace
Plus, if you are connecting to a local Windows machine (either using a hostname of localhost or an IP address of 127.0.0.1), then the connection automatically uses a special, high-performance local connection, called a shared memory connection. For more information about shared memory connections, see JDBC: What’s Unique about Shared Memory Connections.
The point of this document is to give you a taste of using JDBC with InterSystems IRIS without bogging you down in details, so we’ve kept this exploration simple. When you bring InterSystems IRIS to your production systems, though, there are many things you will need to do differently, such as in regard to (but not limited) to security. So be sure not to confuse this exploration of InterSystems IRIS with the real thing! The sources provided at the end of this document will give you a good idea of what’s involved in using JDBC with InterSystems IRIS in production.
JDBC: Why Is It Important?
If you don’t know all the fine points of JDBC: simply put, it is the industry standard for platform-agnostic database connectivity. Specifically, JDBC is a database technology from Oracle that provides access to data sources. It is used to establish database connectivity and provides a standard, reliable way for Java programmers to connect to many types of data sources or perform operations on them with SQL.
Connecting to InterSystems IRIS via JDBC is simple, especially if you’ve used JDBC before. Establishing a JDBC connection to InterSystems IRIS from a Java application allows you to run SQL commands against InterSystems IRIS databases from your Java application.
And the InterSystems IRIS implementation of JDBC has been tuned to provide the fastest, most efficient access to your data.
JDBC: Part of InterSystems IRIS Java Connectivity Options
The InterSystems IRIS JDBC driver is the core InterSystems IRIS Java component, and supports traditional relational (SQL) access. For tighter integration, InterSystems IRIS also provides a separate feature — the InterSystems IRIS XEP component.
Taken all together, InterSystems IRIS provides a unique set of capabilities to use the same physical connection and transaction context to manipulate data using relational and object-oriented paradigms. For more complex applications, InterSystems fully supports Hibernate. Enabling all these forms of connectivity — InterSystems IRIS XEP, Hibernate, and also the InterSystems IRIS Spark Connector — is the InterSystems IRIS JDBC driver.
JDBC: What’s Unique about Shared Memory Connections
As with other database platforms, a JDBC connection to a remote InterSystems IRIS instance is over TCP/IP. To maximize performance, InterSystems IRIS also offers a Java shared memory connection. Shared memory connections are available to Java applications running on the same Windows machine as an InterSystems IRIS instance.
A shared memory connection is a temporary device, backed either by a file or virtual memory, that is shared by a JDBC client and an instance of InterSystems IRIS running on the same physical machine. Further, these connections do not require potentially expensive calls into the kernel network stack. By using a channel directly from the JDBC client to InterSystems IRIS, they provide the ultimate in low latency and high throughput for JDBC operations.
If shared memory connections are available, InterSystems IRIS uses them by default — and you can easily disable them. For now, shared memory connections are available for JDBC only on Microsoft Windows. In future releases of InterSystems IRIS, you will be able to use shared memory connections on other platforms, including Linux.
JDBC: Exploring It
We’ve developed a demo that shows you how to work with JDBC and InterSystems IRIS — and how straightforward that is.
Please note that this code does not demonstrate the improved performance power of the InterSystems Java shared memory connection, because it does not deal with the large volumes of data that the shared memory connection can handle so efficiently.
For instructions on how to install and license a development instance of InterSystems IRIS, see Quick Start: InterSystems IRIS Installation.
Here is the sample code:
import java.sql.*;

public class JDBCSample {
    public static void main(String[] str) throws Exception {
        String url = "jdbc:IRIS://127.0.0.1:1972/USER";

        Class.forName("com.intersystems.jdbc.IRISDriver");
        Connection connection = DriverManager.getConnection(url,"_SYSTEM","SYS");
        // Replace _SYSTEM and SYS with a username and password on your system

        String createTable = "CREATE TABLE People(ID int, FirstName varchar(255), LastName varchar(255))";
        String insert1 = "INSERT INTO People VALUES (1, 'John', 'Smith')";
        String insert2 = "INSERT INTO People VALUES (2, 'Jane', 'Doe')";
        String query = "SELECT * FROM People";

        Statement statement = connection.createStatement();
        statement.executeUpdate(createTable);
        statement.executeUpdate(insert1);
        statement.executeUpdate(insert2);
        ResultSet resultSet = statement.executeQuery(query);
        System.out.println("Printing out contents of SELECT query: ");
        while (resultSet.next()) {
            System.out.println(resultSet.getString(1) + ", " + resultSet.getString(2) + ", " + resultSet.getString(3));
        }
        resultSet.close();
        statement.close();
        connection.close();
    }
}
If the connection and queries have completed successfully, you should see a console window containing the results of the SELECT query.
A Note on the Sample
The connection string syntax is:
jdbc:IRIS://ipAddress:superserverPort/namespace
where:
JDBC: For More Information
For more information on JDBC, SQL and InterSystems IRIS, and other Java interoperability technologies, see: