37.3.2 How to make Java classes available to Octave?

Java finds classes by searching a classpath. This is a list of Java archive files and/or directories containing class files. In Octave the classpath is composed of two parts:

• the static classpath is initialized once at startup of the JVM, and
• the dynamic classpath which can be modified at runtime.

Octave searches the static classpath first, then the dynamic classpath. Classes appearing in the static as well as in the dynamic classpath will therefore be found in the static classpath and loaded from this location. Classes which will be used frequently or must be available to all users should be added to the static classpath. The static classpath is populated once from the contents of a plain text file named javaclasspath.txt (or classpath.txt historically) when the Java Virtual Machine starts. This file contains one line for each individual classpath to be added to the static classpath. These lines can identify single class files, directories containing class files, or Java archives with complete class file hierarchies. Comment lines starting with a ‘#’ or a ‘%’ character are ignored.

The search rules for the file javaclasspath.txt (or classpath.txt) are:

• First, Octave tries to locate it in the current directory (where Octave was started from). If such a file is found, it is read and defines the initial static classpath. Thus, it is possible to define a static classpath on a ’per Octave invocation’ basis.
• Next, Octave searches in the user’s home directory. If a file javaclasspath.txt exists here, its contents are appended to the static classpath (if any). Thus, it is possible to build an initial static classpath on a ’per user’ basis.
• Finally, Octave looks for a next occurrence of file javaclasspath.txt in the m-files directory where Octave Java functions live. This is where javaclasspath.m resides, usually something like OCTAVE_HOME/share/octave/OCTAVE_VERSION/m/java/. You can find this directory by executing the command

  which javaclasspath
  

  If this file exists here, its contents are also appended to the static classpath. Note that the archives and class directories defined in this last step will affect all users.

Classes which are used only by a specific script should be placed in the dynamic classpath. This portion of the classpath can be modified at runtime using the javaaddpath and javarmpath functions.

Example:

octave> base_path = "C:/Octave/java_files";

octave> % add two JARchives to the dynamic classpath
octave> javaaddpath ([base_path, "/someclasses.jar"]);
octave> javaaddpath ([base_path, "/moreclasses.jar"]);

octave> % check the dynamic classpath
octave> p = javaclasspath;
octave> disp (p{1});
C:/Octave/java_files/someclasses.jar
octave> disp (p{2});
C:/Octave/java_files/moreclasses.jar

octave> % remove the first element from the classpath
octave> javarmpath ([base_path, "/someclasses.jar"]);
octave> p = javaclasspath;
octave> disp (p{1});
C:/Octave/java_files/moreclasses.jar

octave> % provoke an error
octave> disp (p{2});
error: A(I): Index exceeds matrix dimension.

Another way to add files to the dynamic classpath exclusively for your user account is to use the file .octaverc which is stored in your home directory. All Octave commands in this file are executed each time you start a new instance of Octave. The following example adds the directory octave to Octave’s search path and the archive myclasses.jar in this directory to the Java search path.

% contents of .octaverc:
addpath ("~/octave");
javaaddpath ("~/octave/myclasses.jar");