Introduction

The Java version of the OpenEye Toolkits is a JNI (Java Native Interface) wrapper created using SWIG. It is important to note that this is not a new version of the toolkits written in Java nor is it a Java interpretation of the toolkit API, but a rather faithful reproduction of the toolkit API in Java. As such there are some features that might not be as Java-like as a toolkit written entirely in Java, but most of these are minor issues and consistency with all the supported languages makes translation from one to another relatively easy and greatly enhances our ability to support all three versions.

A few of these idiomatic differences include:

  • There are relatively few classes in OEChem and they have a rather shallow inheritance hierarchy.

  • Most OEChem algorithms are in C++ free functions. These are mapped to static methods in the class oechem.

  • Method names in most OEChem classes start with uppercase letters.

  • Java doesn’t support operator overloading, so C++ operators are mapped to methods. For example, operator bool() is mapped to a member function called IsValid(), operator() is mapped to call() and operator() const is mapped to constCall().

  • Java doesn’t support direct access to class attributes, so for some simple C++ classes and structs, direct access is mapped to a get/set pair of functions.

  • Calling close() is required for all objects that provide a close() method.

  • delete() should be explicitly called on all objects that come from the following toolkits:

    • Grid TK
    • Shape TK
    • Szybki TK
    • Zap TK

    The user should interact with these particular libraries from only a single Java thread. Failing to do so can lead to subtle race conditions.

  • There is a known bug concerning OpenEye constants that occurs when compiling against an older version of the OpenEye jar and running against a newer version of the OpenEye jar. Please make sure to run against java programs against the same version it was compiled with.

A Java version of the toolkits allows integration into Java desktop and server-side applications. However, the Java toolkits are not necessarily suited for applet programming since they require native code and platform- specific shared libraries. This can be achieved by building a multi-platform JAR as described in the final section, but this is considered for experts only.

Note

In general, due to the wrapping of native code, using explicit obj.delete() calls on class instances obtained from any toolkit is highly recommended as it minimizes issues with early or delayed deletion activity by the Java garbage collector on OpenEye class instances.

Prerequisites

In order to use the OpenEye Java toolkits, a compatible version the Java SDK must be installed. For the most part, this means installing a version of the Oracle/Sun SDK for your platform.

Windows

  • Oracle/Sun JDK 1.6 - x86 and x64
  • Oracle JDK 1.7 - x86 and x64
  • Oracle JDK 1.8 - x86 and x64

Linux

  • Oracle/Sun JDK 1.6 - x86 and x64
  • Oracle JDK 1.7 - x86 and x64
  • Oracle JDK 1.8 - x86 and x64
    • Ubuntu 14.04 LTS x64
    • Ubuntu 16.04 LTS x64
    • RHEL 6 x64
    • RHEL 7 x64

OS X

  • OS X 10.9
    • Java 6 x64
    • Java 7 x64
    • Java 8 x64
  • OS X 10.10
    • Java 6 x64
    • Java 7 x64
    • Java 8 x64
  • OS X 10.11
    • Java 6 x64
    • Java 7 x64
    • Java 8 x64
  • OS X 10.12
    • Java 6 x64
    • Java 7 x64
    • Java 8 x64

Licensing

A license file from OpenEye Scientific Software is required to run any OpenEye toolkit. A license file can be requested/obtained by contacting OpenEye at sales@eyesopen.com.

At startup, the toolkit looks for a valid license in the following default locations:

  • In a file specified by the environment variable OE_LICENSE.

  • In a file named oe_license.txt in the directory specified by the environment variable OE_DIR.

  • In a file named oe_license.txt in the user’s platform-specific local OpenEye application data directory. The location of this directory is detailed below:

    • Linux/UNIX:

      ~USERNAME/.OpenEye

    • Mac OS X:

      /Users/USERNAME/Library/OpenEye

    • Microsoft Windows Vista/7/8.1/10:

      C:\Users\USERNAME\AppData\Local\OpenEye

  • In a file named oe_license.txt in the current working directory

Download the OpenEye Java distribution

Picking a distribution is relatively easy. For each platform (Windows, Linux, and OS X) we only have 2 downloads, a 32-bit version (x86) and a 64-bit version (x64). Just make sure to get the one for your specific architecture.

Download from http://www.eyesopen.com/downloads.

Installation

Untar or unzip the distribution into a directory of your choice. This will create the following structure:

OpenEye-Java-2017.Feb.1-OSName-xArch/
    docs/
    lib/
       oejava-2017.Feb.1-OSName-xArch.jar
    verify/
       verify.py
    examples/
       build.xml
       openeye/
          examples/
          docexamples/

All the examples are found in the examples directory. Use ant to compile the examples jar then you can run an OEChem example using:

For Linux/OS X:

cd OpenEye-Java-2017.Feb.1-OSName-xArch/examples
ant
java -cp ../lib/oejava-2017.Feb.1-Linux-x64.jar:openeye.examples.jar openeye.examples.oechem.OEChemInfo

For Windows, note the use of semi-colon instead of a colon in the class path argument:

cd OpenEye-Java-2017.Feb.1-OSName-xArch/examples
ant
java -cp ../lib/oejava-2017.Feb.1-Windows-x64.jar;openeye.examples.jar openeye.examples.oechem.OEChemInfo

The verify.py script can also be run to ensure a properly working distribution in the current environment. This script requires python version 2.7 or 3.x. If there are problems with the distribution or environment the script will fail. To run verify.py:

cd OpenEye-Java-2017.Feb.1-OSName-xArch/verify
python verify.py

Note

If an error similar to java.lang.OutOfMemoryError: Java heap space occurs, one can increase the heap size of the JVM using the ‘JAVAFLAGS’ environment variable. The ‘-Xmx’ option controls the size of Java heap used. For example, in bash: export JAVAFLAGS=-Xmx4G. Then one can rerun verify.py.