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 the language
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 TK** 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.

.. _java_prerequisites:

Prerequisites
=============

In order to use the OpenEye Java toolkits, a compatible version of the Java
SDK must be installed. For the most part, this means installing a version
of OpenJDK8, OpenJDK11, or OpenJDK21.  See https://openjdk.org/
for your platform.

Linux installation also requires the zlib and libcairo libraries be available. These
are usually available on Desktop Linux installations by default, but
may not be available on Linux server installations.

Platform Support
----------------

OpenEye's support of operating systems changes from the time to time, with older systems
retired and newer ones validated.
For the current set of :ref:`supported platforms, see the current release notes <supported-tk-platforms-fall-2025>`.

Additional software requirements are spelled out in the following sections.

Java Versions
-------------

* `OpenJDK8 <https://openjdk.java.net/projects/jdk8/>`_ 

* `OpenJDK11  <https://openjdk.java.net/projects/jdk/11/>`_ 

* `OpenJDK21  <https://openjdk.java.net/projects/jdk/21/>`_ 


.. _java_gpu_prerequisites:

GPU Prerequisites
=================

.. include:: ../../common/gpu_prereq.rst

Download the OpenEye Java distribution
======================================

Picking a distribution is relatively easy. For each platform (Windows, Linux,
and macOS), we only have 1 download, a 64-bit version (x64).

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-|pkgversion|-OSName-xArch/
       docs/
       lib/
          oejava-|pkgversion|-OSName-xArch.jar
       verify/
          verify.py
       examples/
          build.xml
          openeye/
             examples/
             docexamples/


.. warning::

   For Windows, the distribution should be unzipped to a directory with a short
   pathname, so the longest directory pathname in the tree can be specified in
   less than 260 characters. Otherwise, one may see errors when running the
   verify.py mentioned below due to the 260 character maximum path limit in Windows.

.. warning::

   For Windows, please note that spaces in the path names to the distribution, `ant` or `java` may cause errors with building and running examples. 
   Please install these items in a location that does not contain spaces in the path name.

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/macOS::

   cd OpenEye-Java-|pkgversion|-OSName-xArch/examples
   ant
   java -cp ../lib/oejava-|pkgversion|-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-|pkgversion|-OSName-xArch/examples
   ant
   java -cp ../lib/oejava-|pkgversion|-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.
If there are problems with the distribution or
environment the script will fail.  To run verify.py::

   cd OpenEye-Java-|pkgversion|-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, add ``export JAVAFLAGS=-Xmx4G`` in bash, and then
   rerun verify.py.
