A.4.3 Set up the JVM

In order to execute Java code Octave creates a Java Virtual Machine (JVM). By default the version of the JVM is used that was detected during configuration on Unix-like systems or that is pointed to from the registry keys at HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\JRE or HKEY_LOCAL_MACHINE\SOFTWARE\JavaSoft\Java Runtime Environment on Windows. The default path to the JVM can be overridden by setting the environment variable JAVA_HOME to the path where the JVM is installed. On Windows that might be, for example, C:\Program Files\Java\jre-10.0.2. Make sure that you select a directory that contains the JVM with a bit-ness that matches Octave’s.

The JVM is only loaded once per Octave session. Thus, to change the used version of the JVM, you might have to re-start Octave. To check which version of the JVM is currently being used, run version -java.

The JVM allocates a fixed amount of initial memory and may expand this pool up to a fixed maximum memory limit. The default values depend on the Java version (see javamem). The memory pool is shared by all Java objects running in the JVM. This strict memory limit is intended mainly to avoid runaway applications inside web browsers or in enterprise servers which can consume all memory and crash the system. When the maximum memory limit is hit, Java code will throw exceptions so that applications will fail or behave unexpectedly.

You can specify options for the creation of the JVM inside a file named java.opts. This is a text file where enter you enter lines containing -X and -D options that are then passed to the JVM during initialization.

The directory where the Java options file is located is specified by the environment variable OCTAVE_JAVA_DIR. If unset the directory where javaclasspath.m resides is used instead (typically OCTAVE_HOME/share/octave/OCTAVE_VERSION/m/java/). You can find this directory by executing

which javaclasspath

The -X options allow you to increase the maximum amount of memory available to the JVM. The following example allows up to 256 Megabytes to be used by adding the following line to the java.opts file:

-Xmx256m

The maximum possible amount of memory depends on your system. On a Windows system with 2 Gigabytes main memory you should be able to set this maximum to about 1 Gigabyte.

If your application requires a large amount of memory from the beginning, you can also specify the initial amount of memory allocated to the JVM. Adding the following line to the java.opts file starts the JVM with 64 Megabytes of initial memory:

-Xms64m

For more details on the available -X options of your Java Virtual Machine issue the command ‘java -X’ at the operating system command prompt and consult the Java documentation.

The -D options can be used to define system properties which can then be used by Java classes inside Octave. System properties can be retrieved by using the getProperty() methods of the java.lang.System class. The following example line defines the property MyProperty and assigns it the string 12.34.

-DMyProperty=12.34

The value of this property can then be retrieved as a string by a Java object or in Octave:

octave> javaMethod ("getProperty", "java.lang.System", "MyProperty");
ans = 12.34