Re: Functions in Java interface

[Philip Nienhuis]

Rik-4 wrote
> 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

...plus the dialog functions inputdlg, errordlg, warndlg, listdlg, helpdlg
and (msgbox?). As Matlab's GUI was (is?) based on Java it was a logical move
to also implement these in Java for Octave as long as Octave didn't have
them. 
There was a thread on how to deal with them + dlgtest a while back.


> 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.

Originally only java_new & java_invoke (the latter had its first two
arguments reversed compared to javaMethod) existed in the Java package.
Later on Martin Hepperle created ML-compatible javaObject and javaMethod as
aliases for java_new and java_invoke, resp.

I have quite a bit of calls to java_new() and java_invoke() in the io
package. I wouldn't be surprised if there's a fair amount of user code out
there relying on these functions as well. Just think of the java package
creator Michael Goffioul - I'd expect him to be in that very situation.

If java_new and java_invoke aren't in the way, I'd vote for keeping them at
least until -say- Octave 4.0 (i.e., the second next stable version) and
deprecate them from there.


> 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?

See java_new and java_invoke. Please deprecate a little later on.


> 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.

javamem and the aforementioned debug / convert-matrix functions may serve a
need for debugging Java problems.
Remember, TMW ships a Java JRE with Matlab, thus avoiding a lot of Java
installation problems that may bite Octave users in the back - sneaky and
hard. For example, just look at the JAVA_HOME threads.


> 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?

Michael Goffioul is probably the one who has the best info here.


> 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?

It is used in the Java-based dialog box functions (inputdlg.m etc). 
ML allows cellstr array as input for argument MESSAGE but the Java package
can't handle those. Hitherto a kludge along the lines of cell2mlstr was
required, to convert a cellstr array to char string with "\n"s so that those
dialog boxes can show multiline text.

Is there a better trick, other than repeating cell2mlstr's code in each
dialog function?


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

Good to read that there's a critical eye looking at the Java contents. 
I'm all in favor of cleaning up, but from the perspective of backward
compatibility I'd vouch for keeping the "Octave-specific" ones around a bit
longer until existing code relying on them has been deprecated or adapted.

I quite don't mind that Octave has a richer function set than ML, au
contraire; Octave's aim of ML compatibility is only one-way (ML code should
be able to run in Octave), isn't it?  Only if polluting the namespace is a
real problem for specific functions I'd agree to simplify things.

For example, I have a new io package version (1.2.0) about ready, it is
relying on several functions referred to above. I'll release it asap, it's
too much work now to change the various function calls and test the lot.
A next version was already planned to have as much "ML-compatible" Java
calls as possible. (Hmm a nice occasion to bump the major version nr of the
io pkg)

In this regard I'd like to mention that the Octave-Forge Java package in
several occasions allows much more than Matlab. 
For example, I've tried to port a few of the io spreadsheet functions to
Matlab for use at work but especially the UNO versions (i.e., invoking
LibreOffice behind the scenes) just can't be implemented. It's hard to tell
exactly why, but explicit (i.e., javaObject()) vs. overloaded functions was
one point where all tricks failed.
IOW please let's be careful when removing or transforming functionality
that's implemented in the Java package and currently is in core Octave.

Another issue you touched only in passing above is "auto-boxing", i.e.
automatically transforming Java variable types to Octave variable types (or
if you like: class) and back. java.lang.Double <-> double is just one
example; a more exhaustive list is in the Java package section on the wiki:
  http://wiki.octave.org/Java_package
under "Testing the java package installation".
AFAIK ML doesn't do this auto-boxing - should Octave keep doing it? (I think
yes but that's just me.)
(IIRC things like zero vs. one based array indexing pop up here)

Philip




--
View this message in context: 
http://octave.1599824.n4.nabble.com/Functions-in-Java-interface-tp4647660p4647666.html
Sent from the Octave - Maintainers mailing list archive at Nabble.com.