A.4.2 How to use Java from within Octave

The function javaObject creates Java objects. In fact it invokes the public constructor of the class with the given name and with the given parameters.

The following example shows how to invoke the constructors BigDecimal(double) and BigDecimal(String) of the builtin Java class java.math.BigDecimal.

javaObject ("java.math.BigDecimal",  1.001 );
javaObject ("java.math.BigDecimal", "1.001");

Note that parameters of the Octave type double are implicitly converted into the Java type double and the Octave type (array of) char is converted into the java type String. A Java object created by javaObject is never automatically converted into an Octave type but remains a Java object. It can be assigned to an Octave variable.

a = 1.001;
b = javaObject ("java.math.BigDecimal", a);

Using isjava, it is possible to check whether a variable is a Java object and its class can be determined as well. In addition to the previous example:

isjava (a)
⇒ ans = 0
class (a)
⇒ ans = double
isjava (b)
⇒ ans = 1
class (b)
⇒ ans = java.math.BigDecimal

The example above can be carried out using only Java objects:

a = javaObject ("java.lang.Double", 1.001);
b = javaObject ("java.math.BigDecimal", a);

isjava (a)
⇒ ans = 1
class (a)
⇒ ans = java.lang.Double
isjava (b)
⇒ ans = 1
class (b)
⇒ ans = java.math.BigDecimal

One can see, that even a java.lang.Double is not converted to an Octave double, when created by javaObject. But ambiguities might arise, if the Java classes java.lang.Double or double are parameters of a method (or a constructor). In this case they can be converted into one another, depending on the context.

Via javaObject one may create all kinds of Java objects but arrays. The latter are created through javaArray.

It is possible to invoke public member methods on Java objects in Java syntax:

a.toString
⇒ ans = 1.001
b.toString
⇒ ans = 1.000999999999999889865...

The second result may be surprising, but simply comes from the fact, that 1.001 cannot exactly be represented as double, due to rounding. Note that unlike in Java, in Octave methods without arguments can be invoked with and without parentheses ().

Currently it is not possible to invoke static methods with a Java like syntax from within Octave. Instead, one has to use the function javaMethod as in the following example:

java.math.BigDecimal.valueOf(1.001);                    # does not work
javaMethod ("valueOf", "java.math.BigDecimal", 1.001);  # workaround

As mentioned before, method and constructor parameters are converted automatically between Octave and Java types, if appropriate. For functions this is also true with return values, whereas for constructors this is not.

It is also possible to access public fields of Java objects from within Octave using Java syntax, with the limitation of static fields:

java.math.BigDecimal.ONE;                  # does not work
java_get ("java.math.BigDecimal", "ONE");  # workaround

Accordingly, with java_set the value of a field can be set. Note that only public Java fields are accessible from within Octave.

The following example indicates that in Octave empty brackets [] represent Java’s null value and how Java exceptions are represented.

javaObject ("java.math.BigDecimal", []);
⇒ error: [java] java.lang.NullPointerException

It is not recommended to represent Java’s null value by empty brackets [], because null has no type whereas [] has type double.

In Octave it is possible to provide limited Java reflection by listing the public fields and methods of a Java object, both static or not.

fieldnames (<Java object>)
methods (<Java object>)

Finally, an examples is shown how to access the stack trace from within Octave, where the function debug_java is used to set and to get the current debug state. In debug mode, the Java error and the stack trace are displayed.

debug_java (true)  # use "false" to omit display of stack trace
debug_java ()
⇒ ans = 1
javaObject ("java.math.BigDecimal", "1") ...
  .divide (javaObject ("java.math.BigDecimal", "0"))