# HG changeset patch
# User Ernst Reissner <rei3ner@arcor.de>
# Date 1470926905 -7200
#      Thu Aug 11 16:48:25 2016 +0200
# Node ID 09f748fdfa731939ddc6c092de7af346db285465
# Parent  54d058fcdf9127176beb29a514859141c831838f
redesign and simplification; added docs.

diff -r 54d058fcdf91 -r 09f748fdfa73 scripts/java/org/octave/Octave.java
--- a/scripts/java/org/octave/Octave.java	Thu Aug 11 16:24:06 2016 +0200
+++ b/scripts/java/org/octave/Octave.java	Thu Aug 11 16:48:25 2016 +0200
@@ -22,89 +22,163 @@
 
 package org.octave;
 
-import java.util.*;
+import java.util.Deque;
+import java.util.LinkedList;
 
+//! Allows to evaluate command strings, 
+//! calling named Octave functions and 
+//! invoking functions represented by @ref OctaveReference s. 
+//! Methods related to OctaveReferences are not described here, 
+//! but in @ref OctaveReference. 
+//!
+//! Evaluating a command string is 
+//! by ::doEvalString(String), by ::evalAndWait(String) and 
+//! by ::evalLater(String). 
+//! Whereas the first evaluates now, 
+//! the other two methods do this only if no threaded invocation is required; 
+//! otherwise depending on whether evaluation is now, 
+//! **** intention: (mainly for callbacks) avoid blocking of the curren thread. 
 public class Octave
 {
-  private static Object notifyObject = null;
-  private static Object[] args = null;
-  private static LinkedList invokeList = new LinkedList ();
-  private static LinkedList waitList = new LinkedList ();
 
-  public native static boolean call (String name, Object[] argin, Object[] argout);
-  public native static void doInvoke (int ID, Object[] args);
+  // static
+  // {
+  //   //loadLib();
+  // }
+
+  //! This is either @c null or a @ref Runnable. 
+  //! It is initialized with @c null, 
+  //! set by ::runAndWait(Runnable) 
+  //! provided threaded invocation is needed. 
+  //! If non-@c null, ::checkPendingAction() 
+  //! invokes Runnable#run() and #notifyAll() on #notifyObject and 
+  //! resets it to @c null afterwards. 
+  //! If @c null, ::checkPendingAction() does nothing. 
+  private static Runnable notifyObject = null;
+
+  //! Initially, the #runQueue is empty. 
+  //! Method ::runLater(Runnable) adds a @ref Runnable 
+  //! provided threaded invocation is needed. 
+  //!
+  //! One may assume that #runQueue contains instances of Runnable only 
+  //! and in particular no @c null entries. 
+  //!
+  //! Method ::checkPendingAction() removes the initial entry from #runQueue 
+  //! and runs it until #runQueue is empty. 
+  private final static Deque runQueue = new LinkedList ();
+
+  //! Initially, the #waitList is empty. 
+  //! Method ::waitFor(Object) adds an object to #waitList. 
+  //!
+  //! One may assume that #waitList contains no @c null entries. 
+  //!
+  //! Method ::endWaitFor(Object) removes the first occurrence of some object 
+  //! if present. 
+  //! Method ::checkWaitState() invokes #notifyAll() on the first entry, 
+  //! if #waitList is not empty. 
+  private final static Deque waitList = new LinkedList ();
+
+
+  public static void loadLib() {
+     System.setProperty("java.library.path",
+                       "/home/ernst/Octave/octave/.build/libinterp/.libs/");
+     System.out.println("loadLib: "+System.getProperty("java.library.path"));
+     System.loadLibrary("octinterp");
+//    System.out.println("...loadLib");
+  }
+
+  public Octave() {
+    //loadLib();
+  }
+
+  //! Call an Octave function named @c name
+  //! with input arguments arising from @c argin
+  //! by conversion from java types to octave types 
+  //! assigning the result of the call to output @c argout
+  //! after the inverse conversion. 
+  //!
+  //! Note that the conversion of @c argin succeeds always, 
+  //! lastly wrapping the Java-objects in Octave's octave_java type, 
+  //! whereas the conversion to @c argout may fail. 
+  //!
+  //! This method is implemented by 
+  //! #Java_org_octave_Octave_call(JNIEnv*,jclass,jstring,jobjectArray,jobjectArray) 
+  //! defined in @file ov-java.cc. 
+  //!
+  //! @param name
+  //!    the name of the octave function to be called. 
+  //! @param argin
+  //!    up to a conversion from Java types to Octave types, 
+  //!    the input arguments for function @c name. 
+  //! @param argout
+  //!    up to a conversion from Octave types to Java types 
+  //!    the result of the call to the function @c name. 
+  //! @return
+  //!    whether conversion from output arguments of function @c name 
+  //!    to Java types succeeded. 
+  public native static boolean call (String name, 
+                                     Object[] argin, Object[] argout);
+
+
+  //! Evaluates the given command @c cmd. 
+  //!
+  //! This is implemented by 
+  //! #Java_org_octave_Octave_doEvalString(JNIEnv*,jclass,jstring) 
+  //! defined in @file ov-java.cc. 
+  //!
+  //! @param cmd
+  //!    the command to be evaluated by Octave. 
+  // invoked by ::evalLater(String) and by ::evalAndWait(String) only 
+  // but could be interesting in general for Octave integration in Java 
   public native static void doEvalString (String cmd);
-  public native static boolean needThreadedInvokation ();
 
+  //! Return whether threaded invocation is needed. 
+  //!
+  //! This is implemented by 
+  //! #Java_org_octave_Octave_needThreadedInvocation(JNIEnv*,jclass) 
+  //! defined in @file ov-java.cc. 
+  // invoked by ::runAndWait(Runnable), ::runLater(Runnable) 
+  // and ::endWaitFor(Object) only 
+  // but could be interesting in general for Octave integration in Java 
+  public native static boolean needThreadedInvocation ();
+
+  //! Runs and invokes notifyAll() on #notifyObject if not @c null 
+  //! and resets it to #c null. 
+  //! After that runs all runnables in #runQueue. 
+  // invoked externally by ::java_event_hook in @file ov-java.cc. 
+  // but also by ::waitFor(Object)
   public static void checkPendingAction ()
   {
     if (notifyObject != null)
       {
         synchronized (notifyObject)
           {
-            if (notifyObject instanceof OctaveReference)
-              doInvoke (((OctaveReference)notifyObject).getID (), args);
-            else if (notifyObject instanceof String)
-              doEvalString ((String)notifyObject);
+            notifyObject.run();
             notifyObject.notifyAll ();
           }
         notifyObject = null;
-        args = null;
       }
 
-    Object obj;
-    Object[] objArgs;
-
-    while (true)
+    Runnable runnable;
+ 
+    while (!runQueue.isEmpty ())
       {
-        obj = null;
-        objArgs = null;
-
-        synchronized (invokeList)
+        synchronized (runQueue)
           {
-            if (invokeList.size () > 0)
-              {
-                obj = invokeList.remove ();
-                if (obj instanceof OctaveReference)
-                  objArgs = (Object[])invokeList.remove ();
-              }
+            // remove from the head 
+            runnable = (Runnable)runQueue.remove ();
           }
 
-        if (obj != null)
-          {
-            if (obj instanceof Runnable)
-              ((Runnable)obj).run ();
-            else if (obj instanceof OctaveReference)
-              doInvoke (((OctaveReference)obj).getID (), objArgs);
-            else if (obj instanceof String)
-              doEvalString ((String)obj);
-          }
-        else
-          break;
+        runnable.run ();
       }
-    /*
-      synchronized (invokeList)
-      {
-      while (invokeList.size () > 0)
-      {
-      Object obj = invokeList.remove ();
-      if (obj instanceof Runnable)
-      ((Runnable)obj).run ();
-      if (obj instanceof OctaveReference)
-      {
-      Object[] objArgs = (Object[])invokeList.remove ();
-      doInvoke (((OctaveReference)obj).getID (), objArgs);
-      }
-      else if (obj instanceof String)
-      doEvalString ((String)obj);
-      }
-      }
-    */
   }
 
+  //! Invokes ::notifyAll() on the first entry of #waitList, 
+  //! provided this is not empty without altering #waitList. 
+  // invoked by runAndWait(Runnable) and runLater(Runnable) only 
   private static void checkWaitState ()
   {
-    if (waitList.size () > 0)
+    if (!waitList.isEmpty ())
       {
         Object wObj = waitList.getFirst ();
         synchronized (wObj)
@@ -114,107 +188,181 @@
       }
   }
 
-  public static void invokeAndWait (OctaveReference ref, Object[] invokeArgs)
+  // nowhere invoked. 
+  // but maybe interesting for Octave integration in Java 
+  public static void evalAndWait (final String cmd)
   {
-    if (needThreadedInvokation ())
+   runAndWait(new Runnable() {
+        public void run() {
+          doEvalString (cmd);
+        }
+      });
+  }
+
+  //! If threaded invocation is needed, 
+  //! #notifyObject is set to @c runable and Object::wait() is invoked; 
+  //! otherwise @c runnable is run immediately. 
+  //!
+  //! @param runnable
+  //!    a Runnable instance (not @c null). 
+  // seems as if this thread waits until another thread runs notifyObject 
+  // invoked in ::evalAndWait (String) 
+  // and in OctaveReference.invokeAndWait(Object[])
+  static void runAndWait (Runnable runnable)
+  {
+    // assert runnable != null;
+    if (needThreadedInvocation ())
       {
-        synchronized (ref)
+        synchronized (runnable)
           {
-            notifyObject = ref;
-            args = invokeArgs;
-            try { checkWaitState (); ref.wait (); }
-            catch (InterruptedException e) {}
+            notifyObject = runnable;
+            try
+              {
+                checkWaitState ();
+                runnable.wait ();
+              }
+            catch (InterruptedException e)
+              {
+                // Here, checkPendingAction() has been invoked 
+                // first running notifierObject and then waking up this thread. 
+              }
           }
       }
     else
-      doInvoke (ref.getID (), invokeArgs);
+      {
+        runnable.run();
+      }
   }
 
-  public static void evalAndWait (String cmd)
+  //! If threaded invocation is needed, @c runnable is added to #runQueue 
+  //! and run later by ::checkPendingAction(); 
+  //! otherwise it is run immediately. 
+  //!
+  //! @param runnable 
+  //!    the runnable to be run right now or added to #runQueue 
+  //!    for running later. 
+  //! @throws NullPointerException
+  //!    if @c wObj is @c null. 
+  // used by OctaveReference.invokeLater(Object[]) 
+  //  and by ::evalLater(String)
+  static void runLater (Runnable runnable)
   {
-    if (needThreadedInvokation ())
+    // assert runnable != null;
+    // throws NullPointerException for runnable == null
+    runnable.equals("");// NOPMD
+    if (needThreadedInvocation ())
       {
-        synchronized (cmd)
+        synchronized (runQueue)
           {
-            notifyObject = cmd;
-            args = null;
-            try { checkWaitState (); cmd.wait (); }
-            catch (InterruptedException e) {}
+            // add to the tail of runQueue
+            runQueue.add (runnable);
+            checkWaitState ();
           }
       }
     else
-      doEvalString (cmd);
+      {
+        runnable.run ();
+      }
   }
 
-  public static void invokeLater (Runnable r)
+  // nowhere invoked 
+  // but maybe interesting for Octave integration in Java 
+  public static void evalLater (final String cmd)
   {
-    if (needThreadedInvokation ())
-      synchronized (invokeList)
-        {
-          invokeList.add (r);
-          checkWaitState ();
+    // assert cmd != null;
+    runLater(new Runnable() {
+        public void run() {
+          doEvalString (cmd);
         }
-    else
-      r.run ();
+      });
   }
 
-  public static void invokeLater (OctaveReference ref, Object[] invokeArgs)
-  {
-    if (needThreadedInvokation ())
-      synchronized (invokeList)
-        {
-          invokeList.add (ref);
-          invokeList.add (invokeArgs);
-          checkWaitState ();
-        }
-    else
-      doInvoke (ref.getID (), invokeArgs);
-  }
-
-  public static void evalLater (String cmd)
-  {
-    if (needThreadedInvokation ())
-      synchronized (invokeList)
-        {
-          invokeList.add (cmd);
-          checkWaitState ();
-        }
-    else
-      doEvalString (cmd);
-  }
-
+  //! Add @c wObj to #waitList and while still the first element, 
+  //! @c wObj's thread waits until interrupted 
+  //! and then executes the pending actions invoking ::checkPendingAction(). 
+  //!
+  //! @param wObj
+  //!    the object the thread of which shall wait 
+  //!    before executing peding actions. 
+  //! @throws NullPointerException
+  //!    if @c wObj is @c null. 
+  // nowhere invoked. 
+  // can be assumed that @c wObj is not @c null, 
+  // because otherwise, a NullPointerException is thrown. 
   public static void waitFor (Object wObj)
   {
-    waitList.add (0, wObj);
+    // assert wObj != null;
+    waitList.addFirst (wObj);
+    // throws NullPointerException for wObj == null
     synchronized (wObj)
       {
-        while (waitList.size () > 0 && waitList.getFirst () == wObj)
+        while (!waitList.isEmpty () && waitList.getFirst () == wObj)
           {
-            try { wObj.wait (); }
-            catch (InterruptedException e) {}
+            try 
+              {
+                wObj.wait ();
+              }
+            catch (InterruptedException e) 
+              {
+              }
             checkPendingAction ();
           }
       }
   }
 
+  //! Without prior invocation of ::waitFor(Object) 
+  //! with the same object, this method has no effect. 
+  //! With prior invocation of ::waitFor(Object), 
+  //! the first occurrence of the object in #waitList is removed 
+  //! and if it is the first in the list, all other threads waiting 
+  //! are notified. 
+  //!
+  //! @param obj
+  //!    an object or @c null. 
+  //!    Without previous successful invocation of ::waitFor(Object), 
+  //!    with the same value and in particular for @c null, 
+  //!    this method has no effect) 
+
+  // nowhere invoked. 
+  // removes @c obj from #waitList if present. 
+  // FIXME: does this work or do we have to synchronize for waitList?? 
   public static void endWaitFor (Object obj)
   {
-    boolean isCurrentWaitObject = (waitList.size () > 0 && waitList.getFirst () == obj);
+    boolean isCurrentWaitObject = !waitList.isEmpty () 
+      && waitList.getFirst () == obj;
 
+    // removes first occurrence if present 
     waitList.remove (obj);
-    if (needThreadedInvokation () && isCurrentWaitObject)
-      synchronized (obj)
-        {
-          obj.notifyAll ();
-        }
+    if (needThreadedInvocation () && isCurrentWaitObject)
+      {
+        synchronized (obj)
+          {
+            obj.notifyAll ();
+          }
+      }
   }
 
-  public static Object do_test (String name, Object arg0) throws Exception
+  //! Invoke an Octave function named @c name with a single argument 
+  //! @c arg0 which is converted to an Octave value before invocation 
+  //! of function @c name and convert the result back to a Java object 
+  //! which is returned. 
+  //!
+  //! @param name
+  //!    the name of the octave function to be called. 
+  //!    It is assumed that it takes one input argument and one output argument 
+  //!    and that the types fit after conversion. 
+  //! @throws Exception
+  //!    if back-conversion of the return value fails. 
+  //! @see #call(String, Object[], Object[])
+  public static Object do_test (String name, Object arg0) 
+    throws Exception
   {
     Object[] argin = new Object[] { arg0 };
     Object[] argout = new Object[1];
     if (call (name, argin, argout))
-      return argout[0];
+      {
+        return argout[0];
+      }
     throw new Exception ("octave call failed");
   }
 }
diff -r 54d058fcdf91 -r 09f748fdfa73 scripts/java/org/octave/OctaveReference.java
--- a/scripts/java/org/octave/OctaveReference.java	Thu Aug 11 16:24:06 2016 +0200
+++ b/scripts/java/org/octave/OctaveReference.java	Thu Aug 11 16:48:25 2016 +0200
@@ -22,20 +22,54 @@
 
 package org.octave;
 
+//! Represents the @c octave_value 
+//! in the value set of the map #octave_ref_map defined in @file ov-java.cc
+//! associated with the key given by #ID. 
+//! This is exactly the key which is the argument of ::OctaveReference(int) 
+//! and the return value of ::getID(). 
+//! If methods ::doInvoke(Object[]), ::invokeAndWait(Object[]) 
+//! and ::invokeLater(Object[]) are invoked, 
+//! it is assumed, that this @c octave_value is invocable. 
 public class OctaveReference
 {
-  private int ID;
 
+  //! The key in #octave_ref_map defined in @file ov-java.cc 
+  //! the according value of which is the @c octave_value 
+  //! this java object refers to. 
+  private final int ID;
+
+  //! Creates a new reference to an @c octave_value. 
+  //! It is assumed that #octave_ref_map defined in @file ov-java.cc 
+  //! maps @c ID onto that @c octave_value. 
+  //!
+  //! invoked by ::unbox(JNIEnv*, octave_value&, jobject_ref&, jclass_ref&) 
+  //! defined in @file ov-java.cc in case the octave value 
+  //! cannot be converted into a java object in a natural way. 
+  //!
+  //! @param ID
+  //!    the key in #octave_ref_map mapped to the @c octave_value 
+  //!    this reference refers to. 
   public OctaveReference (int ID)
   {
     this.ID = ID;
   }
 
+  //! Erases the entry of #octave_ref_map defined in @file ov-java.cc 
+  //! with identifier @c ID. 
+  //!
+  //! This is implemented by 
+  //! #Java_org_octave_OctaveReference_doFinalize(JNIEnv*,jclass,jint) 
+  //! defined in @file ov-java.cc. 
+  //!
+  //! @param ID
+  //!    represents an identifier in #octave_ref_map 
+  //!    defined in @file ov-java.cc. 
   private native static void doFinalize (int ID);
 
   protected void finalize () throws Throwable
   {
     doFinalize (this.ID);
+    super.finalize ();
   }
 
   public String toString ()
@@ -43,22 +77,78 @@
     return ("<octave reference " + this.ID + ">");
   }
 
+  //! Return the identifier #ID of this reference. 
+  // invoked by #box(JNIEnv*, void*, void*) defined in @file ov-java.cc 
+  // and by doInvoke(Object[]) only. 
   public int getID ()
   {
     return this.ID;
   }
 
-  public Object invoke (Object[] args)
+  //! Invoke function with identifier @c ID with arguments given by @c args 
+  //! ignoring output if provided. 
+  //!
+  //! This is implemented by 
+  //! #Java_org_octave_OctaveReference_doInvoke(JNIEnv*,jclass,jint,jobjectArray) 
+  //! defined in @file ov-java.cc. 
+  //!
+  //! @param ID
+  //!    the identifyer of a function handle given by #octave_ref_map 
+  //!    defined in @file ov-java.cc. 
+  //! @param args
+  //!    the arguments to invoke octave function with identifyer @c ID with 
+  //!    after conversion from Java types to Octave types. 
+  // invoked by ::doInvoke(Object[]) only 
+  private native static void doInvoke (int ID, Object[] args);
+
+  //! Invoke now the @c octave_value associated with #ID 
+  //! via the map #octave_ref_map defined in @file ov-java.cc 
+  //! with arguments @c args. 
+  //!
+  //! It is assumed, 
+  //! that this @c octave_value is a function invokable with these arguments. 
+  //!
+  //! @param args
+  //!    the argument list to be converted into @c octave_value s 
+  //!    before serving as parameters for the function referenced by this. 
+  // invoked by ::getRunnable(Object[]) only 
+  // but maybe interesting for Octave integration in Java 
+  public void doInvoke (Object[] args)
   {
-    //System.out.println ("OctaveReference::invoke");
-    Octave.doInvoke (this.ID, args);
-    return null;
+    doInvoke(this.getID(), args);
   }
 
-  public synchronized Object invokeAndWait (Object[] args)
+  //! Return a runnable the run-method of which 
+  //! just invokes ::doInvoke(int, Object[]) 
+  //! with ID given by ::getID() and arguments @c args. 
+  //!
+  //! @param args
+  //!    the arguments for invocation. 
+  //! @return 
+  //!    a runnable the run-method of which 
+  //!    just invokes ::doInvoke(int, Object[]) 
+  //!    with ID given by ::getID() and arguments @c args. 
+  private Runnable getRunnable(final Object[] args)
   {
-    //System.out.println ("OctaveReference::invokeandWait");
-    Octave.invokeAndWait (this, args);
-    return null;
+    return new Runnable()
+      {
+        public void run()
+        {
+          doInvoke (args);
+        }
+    };
+  }
+
+  // nowhere invoked. 
+  public synchronized void invokeAndWait (Object[] args)
+  {
+    Octave.runAndWait (getRunnable(args));
+  }
+
+  // added: ER
+  // nowhere invoked. 
+  public synchronized void invokeLater (Object[] args)
+  {
+    Octave.runLater(getRunnable(args));
   }
 }
# HG changeset patch
# User Ernst Reissner <rei3ner@arcor.de>
# Date 1470928501 -7200
#      Thu Aug 11 17:15:01 2016 +0200
# Node ID f02fba58b3394bb4e54453e72d442376ba47f139
# Parent  09f748fdfa731939ddc6c092de7af346db285465
belongs still to 22257:09f748fdfa73

diff -r 09f748fdfa73 -r f02fba58b339 libinterp/octave-value/ov-java.cc
--- a/libinterp/octave-value/ov-java.cc	Thu Aug 11 16:48:25 2016 +0200
+++ b/libinterp/octave-value/ov-java.cc	Thu Aug 11 17:15:01 2016 +0200
@@ -50,7 +50,7 @@
 #include "oct-env.h"
 #include "oct-shlib.h"
 #include "ov-java.h"
-#include "parse.h"
+#include "parse.h"// defines feval 
 #include "variables.h"
 
 #if defined (HAVE_JAVA)
@@ -113,7 +113,6 @@
   { }
 
 protected:
-
   T jobj;
   bool detached;
   JNIEnv *env;
@@ -155,16 +154,16 @@
                                jobjectArray);
 
   JNIEXPORT void JNICALL
+  Java_org_octave_Octave_doEvalString (JNIEnv *, jclass, jstring);
+
+  JNIEXPORT jboolean JNICALL
+  Java_org_octave_Octave_needThreadedInvocation (JNIEnv *, jclass);
+
+  JNIEXPORT void JNICALL
   Java_org_octave_OctaveReference_doFinalize (JNIEnv *, jclass, jint);
 
   JNIEXPORT void JNICALL
-  Java_org_octave_Octave_doInvoke (JNIEnv *, jclass, jint, jobjectArray);
-
-  JNIEXPORT void JNICALL
-  Java_org_octave_Octave_doEvalString (JNIEnv *, jclass, jstring);
-
-  JNIEXPORT jboolean JNICALL
-  Java_org_octave_Octave_needThreadedInvokation (JNIEnv *, jclass);
+  Java_org_octave_OctaveReference_doInvoke (JNIEnv *, jclass, jint, jobjectArray);
 }
 
 static JavaVM *jvm = 0;
@@ -880,6 +879,7 @@
   return jcls;
 }
 
+// bug #48750 
 static dim_vector
 compute_array_dimensions (JNIEnv *jni_env, jobject obj)
 {
@@ -1190,12 +1190,14 @@
   octave_value retval;
 
   jobject jobj = TO_JOBJECT (jobj_arg);
-  jclass jcls = TO_JCLASS (jcls_arg);
+  jclass  jcls = TO_JCLASS  (jcls_arg);
 
   jclass_ref cls (jni_env);
 
   if (! jobj)
-    retval = Matrix ();
+    {
+      retval = Matrix ();
+    }
 
   while (retval.is_undefined ())
     {
@@ -1215,7 +1217,7 @@
       if (jni_env->IsInstanceOf (jobj, cls))
         {
           jmethodID m = jni_env->GetMethodID (cls, "booleanValue", "()Z");
-          retval = (jni_env->CallBooleanMethod (jobj, m) ? true : false);
+          retval = jni_env->CallBooleanMethod (jobj, m) ? true : false;
           break;
         }
 
@@ -1479,6 +1481,7 @@
   return retval;
 }
 
+// conversion from octave to java 
 static bool
 unbox (JNIEnv *jni_env, const octave_value& val, jobject_ref& jobj,
        jclass_ref& jcls)
@@ -1603,6 +1606,9 @@
         UNBOX_PRIMITIVE_SCALAR (uint64_t, uint64_scalar, "java/lang/Long", "(J)V");
 
 #undef UNBOX_PRIMITIVE_SCALAR
+
+      // Here, jobj contains the result of conversion. 
+      // and jcls its class 
       }
   else if (val.is_empty ())
     {
@@ -1722,7 +1728,7 @@
   for (int i = 0; i < args.length (); i++)
     {
       jobject_ref jobj (jni_env);
-      jclass_ref jcls (jni_env);
+      jclass_ref  jcls (jni_env);
 
       found = unbox (jni_env, args(i), jobj, jcls);
       if (! found)
@@ -1758,6 +1764,8 @@
   return -1;
 }
 
+// wraps org.octave.Octave.checkPendingAction()
+// goes into ::initialize_java()
 static int
 java_event_hook (void)
 {
@@ -1765,8 +1773,9 @@
 
   if (current_env)
     {
-      jclass_ref cls (current_env, find_octave_class (current_env, 
-                                                      "org/octave/Octave"));
+      jclass_ref cls (current_env, 
+                      find_octave_class (current_env, 
+                                         "org/octave/Octave"));
       jmethodID mID = current_env->GetStaticMethodID 
         (cls, "checkPendingAction", "()V");
       current_env->CallStaticVoidMethod (cls, mID);
@@ -1809,18 +1818,25 @@
   std::string fname = jstring_to_string (env, funcName);
 
   int nargout = env->GetArrayLength (argout);
-  int nargin = env->GetArrayLength (argin);
+  int nargin  = env->GetArrayLength (argin);
 
   octave_value_list varargin, varargout;
 
   for (int i = 0; i < nargin; i++)
     varargin(i) = box (env, env->GetObjectArrayElement (argin, i), 0);
 
+  // this is the core of this method 
   varargout = feval (fname, varargin, nargout);
 
+  // note: typedef java_local_ref<jobjectArray> jobjectArray_ref 
   jobjectArray_ref out_objs (env, argout), out_clss (env);
   out_objs.detach ();
-  return unbox (env, varargout, out_objs, out_clss);
+
+  // unbox (JNIEnv *env, const octave_value_list , // input
+  //        jobjectArray_ref&, jobjectArray_ref)   // output 
+  bool res = unbox (env, varargout, out_objs, out_clss);
+
+  return res;
 }
 
 JNIEXPORT void JNICALL
@@ -1830,8 +1846,8 @@
 }
 
 JNIEXPORT void JNICALL
-Java_org_octave_Octave_doInvoke (JNIEnv *env, jclass, jint ID,
-                                 jobjectArray args)
+Java_org_octave_OctaveReference_doInvoke (JNIEnv *env, jclass, jint ID,
+                                          jobjectArray args)
 {
   std::map<int,octave_value>::iterator it = octave_ref_map.find (ID);
 
@@ -1882,7 +1898,7 @@
 }
 
 JNIEXPORT jboolean JNICALL
-Java_org_octave_Octave_needThreadedInvokation (JNIEnv *env, jclass)
+Java_org_octave_Octave_needThreadedInvocation (JNIEnv *env, jclass)
 {
   return (get_current_thread_ID (env) != octave_thread_ID);
 }
