(octave.info)Making Java Classes Available

---

Next: How to use Java from within Octave Up: Java Interface

---

Enter node , (file) or (file)node

A.4.1 Making Java Classes Available
-----------------------------------

Java finds classes by searching a CLASSPATH which 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, and then the DYNAMIC
CLASSPATH.  Classes appearing in the STATIC CLASSPATH, 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 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 ‘javaclasspath.txt’ in the m-file
     directory where Octave Java functions live.  This is where the
     function ‘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 JAR archives 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");