Introduction

XEP is a lightweight Java API that provides high-performance Java persistence technology for simple to medium complexity object hierarchies. XEP projects the data in Java objects as persistent events (database objects that store a persistent copy of the data fields), accessing the Caché database over a TCP/IP link. XEP is optimized for transaction processing applications that require extremely high speed data persistence and retrieval.

Installation and Configuration

This section provides specifies requirements and provides instructions for installing Caché and configuring your environment to use XEP.

Installation

When installing Caché, select the Development environment:
- In Windows, select the Setup Type: Development option during installation.
- In UNIX® and related operating systems, select the 1) Development - Install Cache server and all language bindings option during installation (see “Run the Installation Script” in the UNIX® and Linux section of the Installation Guide).
If Caché has been installed with security level 2, open the Management Portal and go to System Administration > Security > Services, select %Service_CallIn, and make sure the Service Enabled box is checked.
If you installed Caché with security level 1 (minimal) it should already be checked.

Requirements

A Java JDK supported by this release of Caché (see “Supported Java Technologies” in the online InterSystems Supported PlatformsOpens in a new tab document for this release). If you are running 64-bit Caché, 64-bit Java is also required.
The Caché User namespace must exist and must be writable.

Required Environment Variables

In order to run XEP applications, the following environment variables must be properly set on all platforms:

Your Path must include dynamic library load path <install-dir>/bin:
- In Windows, add it to your PATH environment variable.
- In UNIX® and related operating systems, add it to your LD_LIBRARY_PATH environment variable.
- In Mac OS X, add it to your DYLD_LIBRARY_PATH environment variable.
If your Path variable includes more than one <install-dir>/bin path (for example, if you have installed more than one instance of Caché) only the first one will be used, and any others will be ignored.

Required Files

All XEP 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

The default stack size of the Java Virtual Machine on Windows is too small for running XEP applications (running them with the default stack size causes Java to report EXCEPTION_STACK_OVERFLOW). To optimize performance, heap size should also be increased. To temporarily modify the stack size and heap size when running an XEP application, add the following command line arguments:
```
   -Xss1024k
   -Xms2500m -Xmx2500m
```

Configuration for UNIX® and Related Operating Systems

Make sure that you have permissions on the Cache binaries (add the user to the cacheusr group).
Set the environment variable LD_PRELOAD to the path of libjsig.so (a library which enables Java to resolve signal handling anomalies) within your Java installation. For example (depending on which shell you are using) :
```
   setenv LD_PRELOAD /my_jdk_path/jre/lib/amd64/libjsig.so 
```
or
```
   set LD_PRELOAD=/my_jdk_path/jre/lib/amd64/libjsig.so 
```
The path of libjsig.so under the root of a Java installation may vary from platform to platform, or from one Java release to another. You can locate it on your system with the following command:
```
   find $JAVA_HOME -name libjsig.so -print 
```
where JAVA_HOME is set to the root directory of your Java installation.

Note:

The LD_PRELOAD variable setting is important if your XEP application also uses other third party components that set up signal handlers. It enables Java to chain signal handlers set by Caché with its own signal handlers, so that they do not interfere with each other. Failure to set this variable may result in a system crash.

XEP Sample Applications

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:

RunAll.java — is a program that runs all of the other sample programs in sequence.
Coverage.java — tests basic functionality such as connecting, importing a schema, storing, querying, updating and deleting XEP events. It also exercises most of the supported data types.
SingleString.java — is the most basic XEP test program. It connects to the database, imports a simple class containing only one string field, then stores and loads a number of events corresponding to that class.
FlightLog.java — is an example that demonstrates the XEP full inheritance model. It tracks airline flight information such as times, locations, personnel, and passengers.
Benchmark.java — is a performance test for the XEP API.
IdKeys.java — extends the Benchmark test by adding the composite IdKey feature.
Threads.java — is a multithreaded XEP test program. It extends the Java Thread class, and uses the Basic.java test suite to test XEP using multiple threads.

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.