Skip to main content
Previous sectionNext section

Configuration and Requirements

To use the InterSystems JDBC driver, you should be familiar with the Java programming language and have some understanding of how Java is configured on your operating system. If you are performing custom configuration of the InterSystems JDBC driver on UNIX®, you should also be familiar with compiling and linking code, writing shell scripts, and other such tasks.

The InterSystems Java Class Packages

The main InterSystems Java class packages are contained in the following files:

  • intersystems-jdbc-3.0.0.jar — the core JDBC jar file. All of the other files in this list are dependent on this file.

    In addition to the core JDBC API, this file also includes the classes that implement the Native API (see Using the Native API for Java).

  • intersystems-xep-3.0.0.jar — required for XEP Java persistence applications (see Persisting Java Objects with InterSystems XEP). Depends on the JDBC jar.

  • intersystems-gateway-3.0.0.jar — required for Java Object Gateway applications (see Using the Object Gateway for Java). Depends on the JDBC jar.

  • intersystems-uima-1.0.0.jar — required for UIMA support (see Using InterSystems UIMA). Depends on the JDBC jar.

  • intersystems-spark-1.0.0.jar — required for the InterSystems implementation of the Apache Spark Data Source API (see Using the InterSystems Spark Connector). Depends on the JDBC jar.

  • intersystems-utils-3.0.0.jar — required for the JDBC Simple Data Transfer utility (see article “Using the Simple Data Transfer Utility”). Depends on the JDBC jar, and requires the XEP jar if XEP transfer mode is used.

There are separate versions of these files for each supported version of Java, located in subdirectories of <install-dir>/dev/java/lib (for example, <install-dir>/dev/java/lib/JDK18 contains the files for Java 1.8).

You can determine the location of <install-dir> (the InterSystems IRIS root directory) for an instance of InterSystems IRIS by opening the InterSystems terminal in that instance and issuing the following ObjectScript command:

   write $system.Util.InstallDirectory()
Copy code to clipboard

Client-Server Configuration

The Java client and InterSystems IRIS server may reside on the same physical machine or they may be located on different machines. Only the InterSystems IRIS server machine requires a copy of InterSystems IRIS; client applications do not require a local copy.

Java Client Requirements

The InterSystems IRIS Java client requires a supported version of the Java JDK. Client applications do not require a local copy of InterSystems IRIS.

The online InterSystems IRIS Data Platform Supported Platforms document for this release specifies the current requirements for all Java-based client applications. See the section on “Supported Java Technologies” for supported Java releases.

The core component of the Java binding is a file named intersystems-jdbc-3.0.0.jar, which contains the Java classes that provide the connection and caching mechanisms for communication with the InterSystems IRIS server and JDBC connectivity. Client applications do not require a local copy of InterSystems IRIS, but the intersystems-jdbc-3.0.0.jar file must be on the class path of the application when compiling or using Java proxy classes. See “The InterSystems IRIS Java Class Packages” for more information on these files.

InterSystems IRIS Server Configuration

Every Java client that wishes to connect to an InterSystems IRIS server needs a URL that provides the server IP address, TCP port number, and InterSystems IRIS namespace, plus a username and password.

To run a Java or JDBC client application, make sure that your installation meets the following requirements:

  • The client must be able to access a machine that is currently running a compatible version of the InterSystems IRIS server (see the online InterSystems IRIS Data Platform Supported Platforms document for this release). The client and the server can be running on the same machine.

  • Your class path must include the version of intersystems-jdbc-3.0.0.jar that correspond to the client version of the Java JDK (see “The InterSystems IRIS Java Class Packages”).

  • To connect to the InterSystems IRIS server, the client application must have the following information:

    • The IP address of the machine on which the InterSystems IRIS Superserver is running. The Java sample programs use the address of the server on the local machine (localhost or 127.0.0.1). If you want a sample program to connect to a different system you will need to change its connection string and recompile it.

    • The TCP port number on which the InterSystems IRIS Superserver is listening. The Java sample programs use 1972 (the default). If you want a sample program to use a different port you will need to change its connection string and recompile it.

    • A valid SQL username and password. You can manage SQL usernames and passwords on the System Administration > Security > Users page of the Management Portal. The Java sample programs use the administrator username, "_SYSTEM" and the default password "SYS" or "sys". Typically, you will change the default password after installing the server. If you want a sample program to use a different username and password you will need to change it and recompile it.

    • The server namespace containing the classes and data that your client application will use.

    See “Establishing JDBC Connections” for detailed information on connecting to the InterSystems IRIS server.