Using Java with Caché eXTreme
[Home] [Back] [Next]
InterSystems: The power behind what matters   
Class Reference   

Caché eXTreme is a set of technologies that enable Caché to be leveraged as a high performance persistence storage engine optimized for XTP (Extreme Transaction Processing) applications.

Caché eXTreme components include:
The eXTreme APIs are designed for integration with Java platforms such as the following:
Installation and Configuration
This section provides specifies requirements and provides instructions for installing Caché and configuring your environment to use the eXTreme APIs.
Required Environment Variables
In order to run eXTreme applications, the following environment variables must be properly set on all platforms:
Required Files
All eXTreme applications require JAR files cache-jdbc-2.0.0.jar, cache-db-2.0.0.jar, and cache-extreme-2.0.0.jar. 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.
Your CLASSPATH environment variable must include the full paths to these files. Alternately, they can be specified in the Java command line classpath argument.
Configuration for Windows
Configuration for UNIX® and Related Operating Systems
Configuration for Mac OS X
Required Settings when Using the Globals API
The OSX SIP (System Integrity Protection) feature disables the use of DYLD_LIBRARY_PATH, which is required by the Globals API to locate and load libraries containing JNI-based native code. The following procedure will allow your system to work around this problem:
  1. Soft-link the following libraries to /usr/local/lib (where $GLOBALS_HOME is the root of the Caché installation):
    ln -s $GLOBALS_HOME/bin/libisccache.dylib /usr/local/lib
    ln -s $GLOBALS_HOME/bin/liblcbjni.dylib /usr/local/lib
    ln -s $GLOBALS_HOME/bin/liblcbindnt.dylib /usr/local/lib
    ln -s $GLOBALS_HOME/bin/liblcbclientnt.dylib /usr/local/lib
    ln -s $GLOBALS_HOME/bin/libmdsjni.dylib /usr/local/lib
  2. Specify -Djava.library.path=/usr/local/lib when running an application that uses the Globals API. For example:
    java -Djava.library.path=/usr/local/lib Sample
eXTreme Sample Applications
Sample applications are available for all eXTreme APIs. Run the samples with command line argument -h for a list of available command line options. In the following sections, <install-dir> is the full path of your Caché installation directory (see Default Caché Installation Directory for the location of <install-dir> on your system).
XEP Samples
XEP sample files are in <install-dir>/dev/java/samples/extreme/xep/test/. For convenience, these files are also compiled into extremesamples.jar, located in <install-dir>/dev/java/samples. The following sample programs are available:
See the Caché JavaDoc (<install-dir>/dev/java/samples/doc/index.html) for detailed documentation of these programs. Supporting files located in <install-dir>/dev/java/samples/extreme/xep/samples/ provide test data for the sample programs.
Globals API Samples
The Globals API sample application (com.intersys.globals.samples.Sample) is compiled into cache-extreme-2.0.0.jar. To run the program, enter the following command:
   java -Xss1024k -cp %jarpath%/cache-extreme-2.0.0.jar com.intersys.globals.samples.Sample -pause
where %jarpath% is a variable containing the path to the appropriate version of cache-extreme-2.0.0.jar (see Required Files for details).
The jar file also contains a copy of the source file,, which can be extracted to the current directory by the following command:
jar -xf %jarpath%/cache-extreme-2.0.0.jar com/intersys/globals/samples/
Sample Data Classes
The examples in this book frequently use the CosTutorial.Person and Sample.Person extents in the Caché Samples namespace to demonstrate data storage and retrieval.
The contents of these extents can be viewed in the Management Portal by going to [System Explorer] > [Globals], selecting Namespace and Samples from the choices in the left column, and clicking the view link for the desired extent (the CosTutorial.Person extent is listed under PersonD, not CosTutorial.PersonD).
This very simple Caché class contains the following declarations:
The following commands can be copied and pasted into the Terminal to populate the extent or delete all objects in the extent:
//Switch to the Samples namespace:
zn "Samples"
// Delete all instances of CosTutorial.Person from the extent:
Do ##class(CosTutorial.Person).%KillExtent()
// Create seven new instances of CosTutorial.Person:
Do ##class(CosTutorial.Person).Populate(7)
For complete structural details, see the CosTutorial.Person entry in the Class Reference. For a ObjectScript example, see the ObjectScript Tutorial (starting with Caché Objects and SQL).
Some examples in this book use the Sample.Person extent as a data source. The following commands can be copied and pasted into the Terminal to populate the extent or delete all objects in the extent:
//Switch to the Samples namespace:
zn "Samples"
// Delete all instances of Sample.Person from the extent:
Do ##class(Sample.Person).%KillExtent()
// Create seven new instances of Sample.Person:
Do ##class(Sample.Person).Populate(7)
For structural details, see the Sample.Person entry in the Class Reference.
Returning a ResultSet from Sample.Person
The following example demonstrates a simple query that returns a ResultSet containing sample data.
// Get a resultset containing Name and DOB properties.
  java.sql.ResultSet myResults = null;
  try {
    String sql="Select Name, DOB from Sample.Person Order By Name";
    myResults = jdbcConnection.prepareStatement(sql).executeQuery();
  catch (java.sql.SQLException e) { System.out.println("Query failed: " + e.getMessage()); }
A ResultSet is generated by using a JDBC connection to query the Sample.Person extent (see Accessing JDBC Databases in Using Caché with JDBC for more examples). Each row in the myResults object contains "Name" and "DOB" properties, which could be used as input to populate another extent, such as CosTutorial.Person.