Functions in Java interface

[Rik]

12/7/12

All,

We seem to have an embarassment of riches.  The new Java interface brings
with it many more functions than the existing Matlab interface.  I think it
is desirable to pare down the list of Octave functions for greater
compatibility and to avoid polluting the global namespace.

As an example, we are exposing a function java_init() which can lead to
segfaults when called repeatedly according to bug #37877.

The list of Matlab java functions is:

javaArray      Construct Java array
javaclasspath  Get and set Java class path
javaaddpath    Add entries to dynamic Java class path
javarmpath     Remove entries from dynamic Java class path
javaMethod     Invoke Java method
javaMethodEDT  Invoke Java method from Event Dispatch Thread (EDT)
javaObject     Invoke Java constructor
javaObjectEDT  Java object constructor on Event Dispatch Thread (EDT)
javachk        Generate error message based on Java feature support
isjava         Determine whether input is Java object
usejava        Determine whether Java feature is supported in MATLAB software

The list of Octave java functions is:

__java__
java
java2mat
javaArray
javaMethod
javaObject
java_convert_matrix
java_debug
java_exit
java_get
java_init
java_invoke
java_new
java_set
java_unsigned_conversion
javaaddpath
javaclasspath
javafields
javamem
javamethods
javarmpath
cell2mlstr
dlgtest

The functions which need a determination are

__java__
java
java2mat
java_convert_matrix
java_debug
java_exit
java_get
java_init
java_invoke
java_new
java_set
java_unsigned_conversion
javafields
javamem
javamethods
cell2mlstr
dlgtest

__java__ is an empty DLD_FCN; it would seem that this could be deleted
immediately.

java_init and java_exit call internal C++ initialization and termination
routines for the JVM.  However, calling any java routine will take care of
initialization for the user so I would vote to remove these explicit
functions from user space immediately.

java_new is a synonym for javaObject.  I like the simplicity (new reminds
me of C++ and the fact that we are calling a constructor), but do we really
need to extend the syntax here since the Matlab function already exists? 
It might be wise to deprecate this so that Octave java code doesn't diverge
so significantly that it becomes cumbersome to run our code on Matlab.

java_set and java_get can set/get data members in a class.  In both Octave
and Matlab the struct syntax is overloaded to perform this operation.

java_set (java_obj, "fieldname", value)
   is equivalent to
java_obj.fieldname = value.

Matlab manages without these so it seems like we could to.  Do people like
the extra setter/getter routines are should we start these on the road to
removal by deprecating them?

java_debug, java_convert_matrix, java_unsigned_conversion control certain
variables within __java__.cc but they are undocumented.  From looking at
the code,
java_debug does print out some extra information when enabled.
java_convert_matrix controls whether return results which are of a
complementary type to an existing Octave class (java.lang.Double -> double)
are automatically converted.
java_unsigned_conversion controls whether signed/unsigned results are
returned in the automatic conversion if that is enabled.

I would say that java_convert_matrix sounds too much like a function call
that would convert a java matrix to an Octave matrix and should probably be
renamed.  For all of them, I think it would be nice to find names that
indicate that these are variables rather than functions.  As an example, we
don't have a function jit_debug.  Instead we have enable_jit_debugging()
which handles setting the internal variable.

isjava is something simple and should be added to the core (rather than in
scripts/java which is conditionally built).  Something simple like

retval = (arg.class_name () == "octave_java");

javafields and javamethods, in Matlab, are handled by overloading
fieldnames() and methods().  I propose that we do the same and then
deprecate these two functions.  The beginning of methods() is

--- ov-class.cc:methods ---
if (arg.is_object ())
  class_name = arg.class_name ();
else if (arg.is_string ())
  class_name = arg.string_value ();
else
  error ("methods: expecting object or class name as argument");
---------------------------

Once isjava is written, it would be easy to add an arg.is_java call () to
this if/else tree and then pass the work to the existing C++
javamethods().  Similarly, the fieldnames() code starts out with

if (arg.is_map () || arg.is_object ())

which could be extended to check for a java object and then call javafields
code.

javamem doesn't seem to have an exact analog under Matlab.  inmem() is
related, but doesn't actually report how much memory is being used.  I
guess it can stay for now.

java2mat seems like it is in the conversion family of routines such as
mat2cell, etc.  However, it doesn't appear to work as I would expect when I
used javaArray and then java2mat.  It is also undocumented and doesn't
appear anywhere else in java.cc or in scripts/java according to grep.  Is
there someone who can say definitively whether this function can be deprecated?

cell2mlstr seems like a convenience function that should possibly be in
scripts/general along with cell2mat since it is not java specific. 
Phillip, can you comment on when this function is used and why it is valuable?

dlgtest is just a test function for the various dialog boxes and probably
doesn't need to be in the user namespace.

Cheers,
Rik